@ngocsangairvds/vsaf 3.2.13 → 3.2.15

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

@@ -1,1270 +0,0 @@
-"""Runtime helpers extracted from row_evaluator (FR-92)."""
-
-from __future__ import annotations
-
-import re
-from collections.abc import Mapping
-from typing import Any
-from urllib.parse import urlparse
-
-from vds_agent_core.agents.loop import AgentLoopAction, AgentLoopResult, LoopTerminationReason
-from vds_agent_core.llm.budget import BudgetExceededError, BudgetScope
-from vds_agent_core.skills.executor import SkillExecutor
-
-from vds_audit_orchestrator.agents.tool_registry import ToolName
-from vds_audit_orchestrator.engine.row_evaluator_types import build_requirement_interpretation
-from vds_audit_orchestrator.errors import AUDIT_ERROR_CODES
-from vds_audit_orchestrator.models.checklist import RowStatus, ScoreBreakdown
-
-
-def _safe_int(val: Any, default: int = 0) -> int:
-    try:
-        return int(val) if val is not None else default
-    except (ValueError, TypeError):
-        return default
-
-
-class RowEvaluatorRuntime:
-    """Shared runtime operations for RowEvaluator."""
-
-    @staticmethod
-    def _route_mode_from_route_id(route_id: str) -> str:
-        route_text = str(route_id or "").strip()
-        if route_text.startswith("docs_"):
-            return "docs_only"
-        if route_text.startswith("code_"):
-            return "code_only"
-        if route_text.startswith("hybrid_docs_first"):
-            return "hybrid_docs_first"
-        if route_text.startswith("hybrid_code_first"):
-            return "hybrid_code_first"
-        return ""
-
-    @staticmethod
-    def _is_actionable_skill_resource_path(resource_path: Any) -> bool:
-        normalized = str(resource_path or "").strip().replace("\\", "/").lower()
-        if not normalized:
-            return False
-        if normalized.endswith("/skill.md") or normalized == "skill.md":
-            return False
-        if normalized.endswith("quality.md") or normalized == "quality.md":
-            return False
-        if "row-analysis" in normalized:
-            return True
-        return bool(normalized.startswith("references/"))
-
-    @staticmethod
-    def _resolve_docs_precision_gap_reason(
-        *,
-        docs_intent_utilization: dict[str, Any],
-        normalized_docs_skip_reason: str,
-    ) -> str | bool:
-        docs_expected = bool(docs_intent_utilization.get("docs_path_expected"))
-        if not docs_expected:
-            return False
-        if normalized_docs_skip_reason:
-            return normalized_docs_skip_reason
-        docs_search_count = _safe_int(docs_intent_utilization.get("docs_search_step_count"), 0)
-        docs_read_count = _safe_int(docs_intent_utilization.get("docs_read_step_count"), 0)
-        docs_hit_count = _safe_int(docs_intent_utilization.get("docs_hit_count"), 0)
-        docs_effective = bool(docs_intent_utilization.get("docs_path_effective"))
-        if not docs_effective:
-            if docs_search_count <= 0:
-                return "docs_path_not_executed"
-            if docs_hit_count <= 0:
-                return "docs_search_no_hits"
-            if docs_read_count <= 0:
-                return "docs_search_hits_not_read"
-            return "docs_path_executed_without_effective_read"
-        if docs_hit_count <= 0:
-            return "docs_precision_low_no_hits"
-        return False
-
-    @staticmethod
-    def summarize_tool_first_efficiency(loop_result: AgentLoopResult) -> dict[str, Any]:
-        """Build compact efficiency metrics for bounded tool-first loop monitoring."""
-        trace_steps = list(loop_result.trace_steps or [])
-        route_id = ""
-        route_mode = ""
-        route_reason = ""
-        for step in trace_steps:
-            route_id = str(step.route_id or "").strip()
-            if route_id:
-                route_mode = RowEvaluatorRuntime._route_mode_from_route_id(route_id)
-                route_reason = str(step.route_reason or "").strip()
-                break
-        tools = [str(str(step.tool)) for step in trace_steps]
-        unique_tools = len(set(tools))
-        steps_executed = int(loop_result.steps_executed or 0)
-        evidence_refs_count = len(loop_result.evidence_refs or [])
-        trace_hydrated_ref_count = len(RowEvaluatorRuntime._extract_refs_from_trace_steps(trace_steps))
-        code_search_count = sum(1 for step in trace_steps if step.tool == ToolName.SEARCH_CODE)
-        docs_search_count = sum(1 for step in trace_steps if step.tool == ToolName.SEARCH_DOCS)
-        code_read_count = sum(1 for step in trace_steps if step.tool == ToolName.READ_CODE_FILE)
-        docs_read_count = sum(1 for step in trace_steps if step.tool == ToolName.READ_DOC_CHUNK)
-        record_evidence_refs_count = sum(1 for step in trace_steps if step.tool == ToolName.RECORD_EVIDENCE_REFS)
-        record_evidence_refs_required = (docs_read_count + code_read_count) > 0
-        record_evidence_refs_contract_met = (not record_evidence_refs_required) or record_evidence_refs_count > 0
-        record_evidence_refs_fallback_capture = False
-        record_evidence_refs_capture_failure_reason: str | bool = False
-        if record_evidence_refs_required and record_evidence_refs_count <= 0:
-            if trace_hydrated_ref_count > 0 and evidence_refs_count > 0:
-                record_evidence_refs_contract_met = True
-                record_evidence_refs_fallback_capture = True
-                record_evidence_refs_capture_failure_reason = "record_evidence_refs_hydrated_from_trace"
-            else:
-                record_evidence_refs_capture_failure_reason = "record_evidence_refs_not_called"
-        skill_call_count = sum(
-            1
-            for step in trace_steps
-            if step.tool
-            in {
-                ToolName.LIST_SKILLS,
-                ToolName.LOAD_SKILL,
-                ToolName.READ_SKILL_RESOURCE,
-                ToolName.RUN_SKILL_SCRIPT,
-            }
-        )
-        skill_discovery_call_count = sum(
-            1
-            for step in trace_steps
-            if step.tool
-            in {
-                ToolName.LIST_SKILLS,
-                ToolName.LOAD_SKILL,
-            }
-        )
-        skill_execution_call_count = sum(
-            1
-            for step in trace_steps
-            if step.tool
-            in {
-                ToolName.READ_SKILL_RESOURCE,
-                ToolName.RUN_SKILL_SCRIPT,
-            }
-        )
-        skill_effective_call_count = 0
-        skill_execution_effective_call_count = 0
-        for step in trace_steps:
-            tool_name = str(str(step.tool))
-            if not RowEvaluatorRuntime._is_skill_tool_name(tool_name):
-                continue
-            entry = {"tool": tool_name}
-            output_payload = step.output if isinstance(step.output, dict) else {}
-            entry.update(output_payload)
-            is_effective = RowEvaluatorRuntime._is_skill_usage_effective_entry(entry)
-            if is_effective:
-                skill_effective_call_count += 1
-                if tool_name in {ToolName.READ_SKILL_RESOURCE.value, ToolName.RUN_SKILL_SCRIPT.value}:
-                    skill_execution_effective_call_count += 1
-        raw_tool_error = loop_result.tool_error
-        normalized_tool_error = str(raw_tool_error).strip() if isinstance(raw_tool_error, str) else ""
-        docs_intent_utilization = (
-            dict(loop_result.docs_intent_utilization) if isinstance(loop_result.docs_intent_utilization, dict) else {}
-        )
-        raw_docs_skip_reason = docs_intent_utilization.get("docs_skip_reason")
-        if raw_docs_skip_reason in (None, False):
-            raw_docs_skip_reason = docs_intent_utilization.get("docs_path_skip_reason")
-        normalized_docs_skip_reason = str(raw_docs_skip_reason).strip() if isinstance(raw_docs_skip_reason, str) else ""
-        docs_precision_gap_reason = RowEvaluatorRuntime._resolve_docs_precision_gap_reason(
-            docs_intent_utilization=docs_intent_utilization,
-            normalized_docs_skip_reason=normalized_docs_skip_reason,
-        )
-        route_escalation_required = bool(docs_intent_utilization.get("route_escalation_required"))
-        route_escalation_applied = bool(docs_intent_utilization.get("route_escalation_applied"))
-        route_escalation_reason_raw = docs_intent_utilization.get("route_escalation_reason")
-        route_escalation_reason = (
-            str(route_escalation_reason_raw).strip() if isinstance(route_escalation_reason_raw, str) else ""
-        )
-        route_escalation_step_index_raw = docs_intent_utilization.get("route_escalation_step_index")
-        route_escalation_step_index = _safe_int(route_escalation_step_index_raw, 0)
-        raw_depth_stop_reason = loop_result.depth_stop_reason
-        normalized_depth_stop_reason = (
-            str(raw_depth_stop_reason).strip() if isinstance(raw_depth_stop_reason, str) else ""
-        )
-        max_depth_level = int(loop_result.max_depth_level or 0)
-        if max_depth_level <= 0 and trace_steps:
-            max_depth_level = max(_safe_int(step.depth_level, 1) for step in trace_steps)
-        depth_escalation_count = sum(1 for step in trace_steps if str(step.depth_increase_reason or "").strip())
-        repetition_rate = 0.0
-        if steps_executed > 0:
-            repetition_rate = max(0.0, (steps_executed - unique_tools) / steps_executed)
-        code_ranking_diagnostics = (
-            dict(loop_result.code_ranking_diagnostics) if isinstance(loop_result.code_ranking_diagnostics, dict) else {}
-        )
-        top_k_contract = (
-            dict(code_ranking_diagnostics.get("top_k_code_read_contract"))
-            if isinstance(code_ranking_diagnostics.get("top_k_code_read_contract"), dict)
-            else {}
-        )
-        top_k_applies = bool(top_k_contract.get("applies"))
-        top_k_target = _safe_int(top_k_contract.get("target_k"), 0)
-        top_k_read_count = _safe_int(top_k_contract.get("top_k_read_count"), 0)
-        top_k_read_met = bool(top_k_contract.get("top_k_read_met")) if top_k_applies else False
-        top_k_shortfall_reason_raw = top_k_contract.get("top_k_read_shortfall_reason")
-        top_k_shortfall_reason = (
-            str(top_k_shortfall_reason_raw).strip() if isinstance(top_k_shortfall_reason_raw, str) else ""
-        )
-        top_k_effective_raw = top_k_contract.get("top_k_effective")
-        top_k_effective_default = top_k_target if top_k_read_met else 0
-        top_k_effective = _safe_int(top_k_effective_raw, top_k_effective_default)
-        top_k_effective = max(0, min(top_k_target, top_k_effective))
-        top_k_fallback_applied_raw = top_k_contract.get("top_k_fallback_applied")
-        top_k_fallback_applied = bool(top_k_fallback_applied_raw)
-        top_k_bounded_soft_pass_raw = top_k_contract.get("top_k_bounded_soft_pass")
-        top_k_bounded_soft_pass = bool(top_k_bounded_soft_pass_raw)
-        db_family_coverage = (
-            dict(code_ranking_diagnostics.get("db_family_coverage"))
-            if isinstance(code_ranking_diagnostics.get("db_family_coverage"), dict)
-            else {}
-        )
-        term_origin_map = (
-            dict(code_ranking_diagnostics.get("term_origin_map"))
-            if isinstance(code_ranking_diagnostics.get("term_origin_map"), dict)
-            else {}
-        )
-        if not term_origin_map:
-            nested_term_origin_map = db_family_coverage.get("term_origin_map")
-            if isinstance(nested_term_origin_map, dict):
-                term_origin_map = dict(nested_term_origin_map)
-
-        db_requirement = bool(db_family_coverage.get("db_requirement"))
-        db_candidate_count = _safe_int(db_family_coverage.get("candidate_count"), 0)
-        db_pass_1_candidates = _safe_int(db_family_coverage.get("pass_1_candidates"), 0)
-        db_pass_2_candidates = _safe_int(db_family_coverage.get("pass_2_candidates"), 0)
-        db_config_database_hits = _safe_int(db_family_coverage.get("config_database_hits"), 0)
-        db_repository_hits = _safe_int(db_family_coverage.get("repository_hits"), 0)
-        db_service_impl_hits = _safe_int(db_family_coverage.get("service_impl_hits"), 0)
-        db_search_no_candidates_reason_raw = db_family_coverage.get("db_search_no_candidates_reason")
-        db_search_no_candidates_reason = (
-            str(db_search_no_candidates_reason_raw).strip()
-            if isinstance(db_search_no_candidates_reason_raw, str)
-            else ""
-        )
-        db_selected_read_shortfall_reason_raw = db_family_coverage.get("selected_read_shortfall_reason")
-        db_selected_read_shortfall_reason = (
-            str(db_selected_read_shortfall_reason_raw).strip()
-            if isinstance(db_selected_read_shortfall_reason_raw, str)
-            else ""
-        )
-        db_family_retrieval_insufficient = bool(db_family_coverage.get("db_family_retrieval_insufficient"))
-        db_selected_read_hits = 0
-        db_selected_read_config_hits = 0
-        db_selected_read_repository_hits = 0
-        for step in trace_steps:
-            if step.tool != ToolName.READ_CODE_FILE:
-                continue
-            output = step.output if isinstance(step.output, dict) else {}
-            code_path = str(output.get("path") or output.get("file_path") or "").strip().lower()
-            if not code_path:
-                continue
-            normalized_code_path = f"/{code_path}"
-            if (
-                "/config/database" in normalized_code_path
-                or "/repository/" in normalized_code_path
-                or "repository" in code_path
-            ):
-                db_selected_read_hits += 1
-            if "/config/database" in normalized_code_path:
-                db_selected_read_config_hits += 1
-            if "/repository/" in normalized_code_path or "repository" in code_path:
-                db_selected_read_repository_hits += 1
-        if db_config_database_hits <= 0 and db_selected_read_config_hits > 0:
-            db_config_database_hits = db_selected_read_config_hits
-        if db_repository_hits <= 0 and db_selected_read_repository_hits > 0:
-            db_repository_hits = db_selected_read_repository_hits
-        if not db_requirement and (
-            db_selected_read_hits > 0
-            or db_candidate_count > 0
-            or db_pass_1_candidates > 0
-            or db_pass_2_candidates > 0
-            or db_config_database_hits > 0
-            or db_repository_hits > 0
-            or db_service_impl_hits > 0
-        ):
-            db_requirement = True
-        if db_requirement and (db_config_database_hits + db_repository_hits + db_selected_read_hits) <= 0:
-            db_family_retrieval_insufficient = True
-        if docs_intent_utilization:
-            docs_intent_utilization["db_family_requirement"] = bool(db_requirement)
-        db_gap_reason_raw = db_family_coverage.get("coverage_gap_reason")
-        db_gap_reason = str(db_gap_reason_raw).strip() if isinstance(db_gap_reason_raw, str) else ""
-        if db_requirement and (db_config_database_hits > 0 or db_repository_hits > 0 or db_selected_read_hits > 0):
-            if db_gap_reason in {"db_search_no_candidates", "db_family_config_repository_missing"}:
-                db_gap_reason = "selected_read_recovered_db_family_coverage"
-            if db_search_no_candidates_reason and (db_config_database_hits > 0 or db_repository_hits > 0):
-                db_search_no_candidates_reason = ""
-        if top_k_applies and not top_k_read_met and not top_k_shortfall_reason:
-            if loop_result.termination_reason == LoopTerminationReason.BUDGET_EXHAUSTED:
-                top_k_shortfall_reason = "budget_exhausted"
-            elif loop_result.termination_reason == LoopTerminationReason.TIMEOUT:
-                top_k_shortfall_reason = "timeout"
-            elif loop_result.termination_reason == LoopTerminationReason.STAGNATION:
-                top_k_shortfall_reason = "stagnation_guardrail"
-        if top_k_applies and not top_k_read_met and top_k_shortfall_reason == "timeout_or_step_bound":
-            bounded_lower_k = max(0, min(top_k_target, top_k_read_count))
-            if top_k_effective <= 0:
-                top_k_effective = bounded_lower_k
-            if top_k_fallback_applied_raw is None:
-                top_k_fallback_applied = bool(bounded_lower_k > 0)
-            if top_k_bounded_soft_pass_raw is None:
-                top_k_bounded_soft_pass = bool(top_k_effective > 0)
-        else:
-            if not top_k_read_met:
-                top_k_effective = 0
-            top_k_fallback_applied = False
-            top_k_bounded_soft_pass = False
-        db_selected_read_coverage_met = bool(db_requirement and db_selected_read_hits > 0)
-        if db_requirement and not db_selected_read_coverage_met and not db_selected_read_shortfall_reason:
-            if db_search_no_candidates_reason:
-                db_selected_read_shortfall_reason = db_search_no_candidates_reason
-            elif db_candidate_count <= 0:
-                db_selected_read_shortfall_reason = "db_search_no_candidates"
-            elif (db_config_database_hits + db_repository_hits) <= 0:
-                db_selected_read_shortfall_reason = "db_family_selected_read_candidate_miss"
-            else:
-                db_selected_read_shortfall_reason = "db_family_selected_read_missing"
-        if db_family_coverage:
-            db_family_coverage = dict(db_family_coverage)
-            db_family_coverage["config_database_hits"] = db_config_database_hits
-            db_family_coverage["repository_hits"] = db_repository_hits
-            db_family_coverage["selected_read_hits"] = db_selected_read_hits
-            db_family_coverage["selected_read_coverage_met"] = bool(db_requirement and db_selected_read_hits > 0)
-            db_family_coverage["selected_read_shortfall_reason"] = db_selected_read_shortfall_reason or False
-            db_family_coverage["db_search_no_candidates_reason"] = db_search_no_candidates_reason
-            db_family_coverage["db_family_retrieval_insufficient"] = db_family_retrieval_insufficient
-            db_family_coverage["coverage_gap_reason"] = db_gap_reason or "none"
-        _eff = {
-            "termination_reason": loop_result.termination_reason.value,
-            "steps_executed": steps_executed,
-            "route_id": route_id or False,
-            "route_mode": route_mode or False,
-            "route_reason": route_reason or False,
-            "steps_unique_tools": unique_tools,
-            "step_repetition_rate": round(repetition_rate, 3),
-            "code_search_count": code_search_count,
-            "docs_search_count": docs_search_count,
-            "code_read_count": code_read_count,
-            "docs_read_count": docs_read_count,
-            "record_evidence_refs_count": record_evidence_refs_count,
-            "record_evidence_refs_required": record_evidence_refs_required,
-            "record_evidence_refs_contract_met": record_evidence_refs_contract_met,
-            "record_evidence_refs_fallback_capture": record_evidence_refs_fallback_capture,
-            "record_evidence_refs_capture_failure_reason": record_evidence_refs_capture_failure_reason,
-            "skill_call_count": skill_call_count,
-            "skill_discovery_call_count": skill_discovery_call_count,
-            "skill_execution_call_count": skill_execution_call_count,
-            "skill_effective_call_count": skill_effective_call_count,
-            "skill_execution_effective_call_count": skill_execution_effective_call_count,
-            "evidence_refs_count": evidence_refs_count,
-            "budget_remaining": int(loop_result.budget_remaining or 0),
-            "elapsed_seconds": round(float(loop_result.elapsed_seconds or 0.0), 3),
-            "tool_error": normalized_tool_error or False,
-            "docs_intent_utilization": docs_intent_utilization,
-            "docs_intent_required": bool(docs_intent_utilization.get("docs_path_expected")),
-            "docs_intent_utilized": bool(
-                docs_intent_utilization.get("docs_path_effective", docs_intent_utilization.get("docs_path_executed"))
-            ),
-            "docs_skip_reason": normalized_docs_skip_reason or False,
-            "docs_path_skip_reason": normalized_docs_skip_reason or False,
-            "docs_precision_gap_reason": docs_precision_gap_reason,
-            "route_escalation_required": route_escalation_required,
-            "route_escalation_applied": route_escalation_applied,
-            "route_escalation_reason": route_escalation_reason or False,
-            "route_escalation_step_index": route_escalation_step_index if route_escalation_step_index > 0 else False,
-            "max_depth_level": max_depth_level,
-            "depth_escalation_count": depth_escalation_count,
-            "depth_stop_reason": normalized_depth_stop_reason or False,
-            "top_k_code_read_contract_applies": top_k_applies,
-            "top_k_target": top_k_target,
-            "top_k_read_count": top_k_read_count,
-            "top_k_read_met": top_k_read_met if top_k_applies else False,
-            "top_k_read_shortfall_reason": top_k_shortfall_reason or False,
-            "top_k_effective": top_k_effective if top_k_applies else 0,
-            "top_k_fallback_applied": top_k_fallback_applied if top_k_applies else False,
-            "top_k_bounded_soft_pass": top_k_bounded_soft_pass if top_k_applies else False,
-            "db_family_coverage": db_family_coverage or False,
-            "db_family_requirement": db_requirement,
-            "db_family_candidate_count": db_candidate_count,
-            "db_family_pass_1_candidates": db_pass_1_candidates,
-            "db_family_pass_2_candidates": db_pass_2_candidates,
-            "db_family_config_database_hits": db_config_database_hits,
-            "db_family_repository_hits": db_repository_hits,
-            "db_family_service_impl_hits": db_service_impl_hits,
-            "db_family_selected_read_hits": db_selected_read_hits,
-            "db_family_selected_read_coverage_met": db_selected_read_coverage_met if db_requirement else False,
-            "db_family_selected_read_shortfall_reason": db_selected_read_shortfall_reason or False,
-            "db_search_no_candidates_reason": db_search_no_candidates_reason or False,
-            "db_family_retrieval_insufficient": db_family_retrieval_insufficient,
-            "db_family_coverage_gap_reason": db_gap_reason or False,
-            "term_origin_map": term_origin_map or False,
-        }
-        _p172_diags = loop_result.code_ranking_diagnostics or {}
-        for _k in (
-            "skill_first_loaded_at_step",
-            "search_pattern_diversity_count",
-            "breadth_enforcement_applied",
-            "control_objective_evidence_gate_applied",
-            "required_min_evidence_refs",
-            "required_min_search_patterns",
-            "diversity_gate_waived",
-            "skill_content_hash",
-        ):
-            if _k in _p172_diags:
-                _eff[_k] = _p172_diags[_k]
-        return _eff
-
-    @staticmethod
-    def _coverage_marker(value: Any) -> str:
-        try:
-            numeric = float(value)
-        except (TypeError, ValueError):
-            return "none"
-        bounded = max(0.0, min(1.0, numeric))
-        if bounded >= 0.75:
-            return "high"
-        if bounded >= 0.5:
-            return "medium"
-        if bounded > 0.0:
-            return "low"
-        return "none"
-
-    @staticmethod
-    def _tool_first_turn_family(tool_name: str) -> str:
-        normalized = str(tool_name or "").strip()
-        if normalized in {ToolName.SEARCH_DOCS.value, ToolName.READ_DOC_CHUNK.value}:
-            return "docs"
-        if normalized in {ToolName.SEARCH_CODE.value, ToolName.READ_CODE_FILE.value}:
-            return "code"
-        if normalized in {
-            ToolName.LIST_SKILLS.value,
-            ToolName.LOAD_SKILL.value,
-            ToolName.READ_SKILL_RESOURCE.value,
-            ToolName.RUN_SKILL_SCRIPT.value,
-        }:
-            return "skill"
-        if normalized == ToolName.GET_ROW_CONTEXT.value:
-            return "context"
-        if normalized == ToolName.RECORD_EVIDENCE_REFS.value:
-            return "evidence"
-        return "other"
-
-    @staticmethod
-    def _is_skill_tool_name(tool_name: str) -> bool:
-        normalized = str(tool_name or "").strip()
-        return normalized in {
-            ToolName.LIST_SKILLS.value,
-            ToolName.LOAD_SKILL.value,
-            ToolName.READ_SKILL_RESOURCE.value,
-            ToolName.RUN_SKILL_SCRIPT.value,
-        }
-
-    @staticmethod
-    def _is_skill_usage_informational_entry(entry: dict[str, Any]) -> bool:
-        tool_name = str(entry.get("tool") or "").strip()
-        if not RowEvaluatorRuntime._is_skill_tool_name(tool_name):
-            return bool(entry.get("success")) or bool(entry.get("effective"))
-        if tool_name == ToolName.READ_SKILL_RESOURCE.value:
-            content_length = int(entry.get("content_length", 0) or 0)
-            if content_length <= 0:
-                content_value = entry.get("content")
-                if isinstance(content_value, str):
-                    content_length = len(content_value)
-            if content_length > 0:
-                return True
-            return bool(entry.get("success"))
-        if tool_name == ToolName.LOAD_SKILL.value:
-            return bool(entry.get("success")) and (
-                bool(entry.get("resource_count")) or bool(entry.get("script_count")) or bool(entry.get("skill"))
-            )
-        if tool_name == ToolName.LIST_SKILLS.value:
-            return bool(entry.get("success")) and int(entry.get("results_count") or 0) > 0
-        if tool_name == ToolName.RUN_SKILL_SCRIPT.value:
-            return bool(entry.get("success")) or bool(entry.get("effective"))
-        return bool(entry.get("success")) or bool(entry.get("effective"))
-
-    @staticmethod
-    def _is_skill_usage_effective_entry(entry: dict[str, Any]) -> bool:
-        tool_name = str(entry.get("tool") or "").strip()
-        explicit_effective = bool(entry.get("effective"))
-        if not RowEvaluatorRuntime._is_skill_tool_name(tool_name):
-            return explicit_effective
-        if tool_name == ToolName.RUN_SKILL_SCRIPT.value:
-            if explicit_effective:
-                return True
-            stdout_value = entry.get("stdout")
-            has_stdout = isinstance(stdout_value, str) and bool(stdout_value.strip())
-            return bool(entry.get("success")) and has_stdout
-        if tool_name == ToolName.READ_SKILL_RESOURCE.value:
-            benefit_marked = (
-                bool(entry.get("benefit_signal")) or bool(entry.get("applied")) or bool(entry.get("evidence_refs"))
-            )
-            if explicit_effective and benefit_marked:
-                return True
-            content_length = int(entry.get("content_length", 0) or 0)
-            if content_length <= 0:
-                content_value = entry.get("content")
-                if isinstance(content_value, str):
-                    content_length = len(content_value)
-            resource_path = str(entry.get("resource") or entry.get("resource_path") or "").strip()
-            return (
-                bool(entry.get("success"))
-                and content_length > 0
-                and RowEvaluatorRuntime._is_actionable_skill_resource_path(resource_path)
-            )
-        # Discovery/bootstrap calls are never counted as direct requirement-analysis benefit.
-        return False
-
-    @staticmethod
-    def _is_turn_step_effective(step_payload: dict[str, Any]) -> bool:
-        tool_name = str(step_payload.get("tool") or "").strip()
-        output = step_payload.get("output")
-        if RowEvaluatorRuntime._is_skill_tool_name(tool_name):
-            if not isinstance(output, dict):
-                return False
-            if tool_name == ToolName.RUN_SKILL_SCRIPT.value:
-                stdout = output.get("stdout")
-                has_stdout = isinstance(stdout, str) and bool(stdout.strip())
-                return bool(output.get("success")) and has_stdout
-            if tool_name == ToolName.READ_SKILL_RESOURCE.value:
-                benefit_marked = (
-                    bool(output.get("benefit_signal"))
-                    or bool(output.get("applied"))
-                    or bool(output.get("evidence_refs"))
-                )
-                if benefit_marked:
-                    return True
-                content = output.get("content")
-                has_content = isinstance(content, str) and bool(content.strip())
-                resource_path = str(output.get("resource_path") or output.get("resource") or "").strip()
-                return (
-                    bool(output.get("success"))
-                    and has_content
-                    and RowEvaluatorRuntime._is_actionable_skill_resource_path(resource_path)
-                )
-            return False
-        if isinstance(output, dict):
-            hits = output.get("hits")
-            if isinstance(hits, list) and any(isinstance(item, dict) for item in hits):
-                return len(hits) > 0
-            refs = output.get("refs")
-            if isinstance(refs, list) and refs:
-                return True
-            accepted_count = output.get("accepted_count")
-            if isinstance(accepted_count, int) and accepted_count > 0:
-                return True
-            content = output.get("content")
-            if isinstance(content, str) and content.strip():
-                return True
-            ref = output.get("ref")
-            return bool(isinstance(ref, str) and ref.strip())
-        if isinstance(output, str):
-            return bool(output.strip())
-        if isinstance(output, list):
-            return bool(output)
-        return bool(output)
-
-    @classmethod
-    def infer_skill_usage_from_trace(
-        cls,
-        retrieval_trace: dict[str, Any] | None,
-    ) -> list[dict[str, Any]]:
-        """Derive skill usage records from tool-first trace when collector output is unavailable."""
-        if not isinstance(retrieval_trace, dict):
-            return []
-        loop_trace = retrieval_trace.get("tool_first_loop")
-        trace_steps = loop_trace.get("trace_steps") if isinstance(loop_trace, dict) else None
-        if not isinstance(trace_steps, list):
-            return []
-
-        usage: list[dict[str, Any]] = []
-        for step in trace_steps:
-            if not isinstance(step, dict):
-                continue
-            tool_name = str(step.get("tool") or "").strip()
-            if tool_name not in {
-                ToolName.LIST_SKILLS.value,
-                ToolName.LOAD_SKILL.value,
-                ToolName.READ_SKILL_RESOURCE.value,
-                ToolName.RUN_SKILL_SCRIPT.value,
-            }:
-                continue
-
-            output = step.get("output")
-            entry: dict[str, Any] = {
-                "tool": tool_name,
-                "effective": cls._is_turn_step_effective(step),
-            }
-            if isinstance(output, dict):
-                name = str(output.get("name") or output.get("resolved_name") or "").strip()
-                if name:
-                    entry["skill"] = name
-                resource_path = str(output.get("resource_path") or "").strip()
-                if resource_path:
-                    entry["resource"] = resource_path
-                if "success" in output:
-                    entry["success"] = bool(output.get("success"))
-                error = str(output.get("error") or "").strip()
-                if error:
-                    entry["error"] = error
-                content = output.get("content")
-                if isinstance(content, str):
-                    entry["content_length"] = len(content)
-            usage.append(entry)
-        return usage
-
-    @classmethod
-    def infer_skill_usage_from_prompt_telemetry(
-        cls,
-        retrieval_trace: dict[str, Any] | None,
-    ) -> list[dict[str, Any]]:
-        """Derive skill usage records from prompt tool telemetry when tool-first trace has none."""
-        if not isinstance(retrieval_trace, dict):
-            return []
-        telemetry = retrieval_trace.get("prompt_tool_telemetry")
-        if not isinstance(telemetry, dict):
-            return []
-
-        detailed_usage = telemetry.get("event_skill_tool_usage")
-        if isinstance(detailed_usage, list):
-            normalized_usage: list[dict[str, Any]] = []
-            for entry in detailed_usage:
-                if not isinstance(entry, dict):
-                    continue
-                tool_name = str(entry.get("tool") or "").strip()
-                if tool_name not in {
-                    ToolName.LIST_SKILLS.value,
-                    ToolName.LOAD_SKILL.value,
-                    ToolName.READ_SKILL_RESOURCE.value,
-                    ToolName.RUN_SKILL_SCRIPT.value,
-                }:
-                    continue
-                normalized_entry: dict[str, Any] = {
-                    "tool": tool_name,
-                    "success": bool(entry.get("success", True)),
-                    "effective": bool(entry.get("effective", False)),
-                }
-                for key in (
-                    "skill",
-                    "resource",
-                    "script",
-                    "error",
-                    "query",
-                    "source",
-                ):
-                    value = str(entry.get(key) or "").strip()
-                    if value:
-                        normalized_entry[key] = value
-                if isinstance(entry.get("results_count"), int):
-                    normalized_entry["results_count"] = int(entry.get("results_count") or 0)
-                if isinstance(entry.get("content_length"), int):
-                    normalized_entry["content_length"] = int(entry.get("content_length") or 0)
-                if "informational" in entry:
-                    normalized_entry["informational"] = bool(entry.get("informational"))
-                if "benefit_signal" in entry:
-                    normalized_entry["benefit_signal"] = bool(entry.get("benefit_signal"))
-                if "applied" in entry:
-                    normalized_entry["applied"] = bool(entry.get("applied"))
-                evidence_refs = entry.get("evidence_refs")
-                if isinstance(evidence_refs, list):
-                    refs = [str(item).strip() for item in evidence_refs if str(item).strip()]
-                    if refs:
-                        normalized_entry["evidence_refs"] = refs
-                normalized_usage.append(normalized_entry)
-            if normalized_usage:
-                return normalized_usage
-
-        skill_counts = telemetry.get("event_skill_tool_count_by_name")
-        if not isinstance(skill_counts, dict):
-            return []
-
-        usage: list[dict[str, Any]] = []
-        for tool_name in (
-            ToolName.LIST_SKILLS.value,
-            ToolName.LOAD_SKILL.value,
-            ToolName.READ_SKILL_RESOURCE.value,
-            ToolName.RUN_SKILL_SCRIPT.value,
-        ):
-            count = int(skill_counts.get(tool_name, 0) or 0)
-            if count <= 0:
-                continue
-            for _ in range(count):
-                entry: dict[str, Any] = {
-                    "tool": tool_name,
-                    "success": True,
-                    "effective": False,
-                    "source": "prompt_tool_telemetry_counts",
-                    "inferred": True,
-                }
-                if tool_name == ToolName.LIST_SKILLS.value:
-                    entry["results_count"] = 1
-                if tool_name == ToolName.READ_SKILL_RESOURCE.value:
-                    entry["informational"] = True
-                usage.append(entry)
-        return usage
-
-    @classmethod
-    def build_row_effectiveness_summary(
-        cls,
-        *,
-        retrieval_trace: dict[str, Any] | None,
-        skill_tool_usage: list[dict[str, Any]] | None,
-        coverage_metrics: dict[str, float] | None,
-    ) -> dict[str, Any]:
-        """Build additive row-level effectiveness telemetry for retrieval_trace."""
-        coverage_metrics = coverage_metrics or {}
-        skill_usage = [dict(entry) for entry in (skill_tool_usage or []) if isinstance(entry, dict)]
-        skill_calls_total = len(skill_usage)
-        skill_calls_success = sum(1 for entry in skill_usage if bool(entry.get("success")))
-        skill_calls_informational = sum(1 for entry in skill_usage if cls._is_skill_usage_informational_entry(entry))
-        skill_calls_effective = sum(1 for entry in skill_usage if cls._is_skill_usage_effective_entry(entry))
-        skill_execution_calls = sum(
-            1
-            for entry in skill_usage
-            if str(entry.get("tool") or "").strip()
-            in {
-                ToolName.READ_SKILL_RESOURCE.value,
-                ToolName.RUN_SKILL_SCRIPT.value,
-            }
-        )
-        skill_execution_effective_calls = sum(
-            1
-            for entry in skill_usage
-            if str(entry.get("tool") or "").strip()
-            in {
-                ToolName.READ_SKILL_RESOURCE.value,
-                ToolName.RUN_SKILL_SCRIPT.value,
-            }
-            and cls._is_skill_usage_effective_entry(entry)
-        )
-        skill_effective_rate = round(skill_calls_effective / skill_calls_total, 3) if skill_calls_total > 0 else 0.0
-        skill_execution_effective_rate = (
-            round(skill_execution_effective_calls / skill_execution_calls, 3) if skill_execution_calls > 0 else 0.0
-        )
-
-        coverage_contribution = {
-            "coverage_requirements": round(float(coverage_metrics.get("coverage_requirements", 0.0) or 0.0), 4),
-            "coverage_code": round(float(coverage_metrics.get("coverage_code", 0.0) or 0.0), 4),
-            "coverage_docs": round(float(coverage_metrics.get("coverage_docs", 0.0) or 0.0), 4),
-            "coverage_confidence": round(float(coverage_metrics.get("coverage_confidence", 0.0) or 0.0), 4),
-        }
-        coverage_markers = {metric: cls._coverage_marker(value) for metric, value in coverage_contribution.items()}
-
-        turn_entries: list[dict[str, Any]] = []
-        effective_turn_count = 0
-        contribution_turn_count = 0
-        loop_trace = retrieval_trace.get("tool_first_loop") if isinstance(retrieval_trace, dict) else None
-        trace_steps = loop_trace.get("trace_steps") if isinstance(loop_trace, dict) else None
-        if isinstance(trace_steps, list):
-            for offset, step in enumerate(trace_steps, start=1):
-                if not isinstance(step, dict):
-                    continue
-                raw_step_index = step.get("step")
-                turn_index = raw_step_index if isinstance(raw_step_index, int) and raw_step_index > 0 else offset
-                tool_name = str(step.get("tool") or "")
-                tool_family = cls._tool_first_turn_family(tool_name)
-                is_effective = cls._is_turn_step_effective(step)
-                contribution_markers = {"requirements": False, "docs": False, "code": False}
-                if is_effective:
-                    contribution_markers["requirements"] = True
-                    if tool_family == "docs":
-                        contribution_markers["docs"] = True
-                    elif tool_family == "code":
-                        contribution_markers["code"] = True
-                    elif tool_family == "evidence":
-                        contribution_markers["docs"] = coverage_contribution["coverage_docs"] > 0.0
-                        contribution_markers["code"] = coverage_contribution["coverage_code"] > 0.0
-                if (
-                    contribution_markers["requirements"]
-                    and contribution_markers["docs"]
-                    and contribution_markers["code"]
-                ):
-                    contribution_level = "high"
-                elif contribution_markers["requirements"] and (
-                    contribution_markers["docs"] or contribution_markers["code"]
-                ):
-                    contribution_level = "medium"
-                elif contribution_markers["requirements"]:
-                    contribution_level = "low"
-                else:
-                    contribution_level = "none"
-                if is_effective:
-                    effective_turn_count += 1
-                if contribution_level != "none":
-                    contribution_turn_count += 1
-                turn_entries.append(
-                    {
-                        "turn_index": turn_index,
-                        "tool": tool_name,
-                        "tool_family": tool_family,
-                        "effective": is_effective,
-                        "coverage_contribution_markers": contribution_markers,
-                        "requirement_coverage_contribution_level": contribution_level,
-                    }
-                )
-
-        summary: dict[str, Any] = {
-            "skill_effectiveness": {
-                "calls_total": skill_calls_total,
-                "calls_success": skill_calls_success,
-                "calls_informational": skill_calls_informational,
-                "calls_effective": skill_calls_effective,
-                "effective_rate": skill_effective_rate,
-                "execution_calls_total": skill_execution_calls,
-                "execution_calls_effective": skill_execution_effective_calls,
-                "execution_effective_rate": skill_execution_effective_rate,
-            },
-            "requirement_coverage_contribution": coverage_contribution,
-            "requirement_coverage_contribution_markers": coverage_markers,
-            "turn_effectiveness_summary": turn_entries,
-        }
-        if turn_entries:
-            turn_count = len(turn_entries)
-            summary["turn_effective_rate"] = round(effective_turn_count / turn_count, 3)
-            summary["turn_requirement_coverage_contribution_rate"] = round(contribution_turn_count / turn_count, 3)
-        return summary
-
-    @staticmethod
-    def enforce_tool_first_budget(
-        *,
-        config: Any,
-        enforcer: Any,
-        row_id: str,
-        check_id: str,
-        loop_result: AgentLoopResult,
-        logger: Any,
-    ) -> None:
-        """Apply strict/non-strict budget policy for tool-first loop termination."""
-        if enforcer is None:
-            return
-        if loop_result.termination_reason != LoopTerminationReason.BUDGET_EXHAUSTED:
-            return
-
-        budget_limit = max(0, int(config.tool_first_budget_units))
-        spent_units = max(0, budget_limit - int(loop_result.budget_remaining or 0)) + 1
-
-        enforcer.reset_usage(scope=BudgetScope.AUDIT, scope_id=row_id)
-        try:
-            usages = enforcer.record_cost(cost_dollars=float(spent_units), audit_id=row_id)
-        except BudgetExceededError as exc:
-            context = {
-                "kind": "strict_budget_exceeded",
-                "audit_error_key": "LLM_BUDGET_EXCEEDED",
-                "audit_error_code": AUDIT_ERROR_CODES["LLM_BUDGET_EXCEEDED"].code,
-                "row_id": row_id,
-                "check_id": check_id,
-                "termination_reason": loop_result.termination_reason.value,
-                "budget_limit_units": budget_limit,
-                "budget_spent_units": spent_units,
-                "budget_remaining_units": int(loop_result.budget_remaining or 0),
-                "steps_executed": int(loop_result.steps_executed or 0),
-            }
-            exc.error_context = context
-            raise
-
-        status = next((usage.status.value for usage in usages if usage.scope == BudgetScope.AUDIT), "exceeded")
-        logger.warning(
-            "row_tool_first_budget_exceeded_warning",
-            row_id=row_id,
-            check_id=check_id,
-            strict_budget=config.strict_budget,
-            status=status,
-            budget_limit_units=budget_limit,
-            budget_spent_units=spent_units,
-            budget_remaining_units=int(loop_result.budget_remaining or 0),
-            steps_executed=int(loop_result.steps_executed or 0),
-        )
-
-    @staticmethod
-    def _runtime_log_fields(runtime_context: Mapping[str, Any] | None) -> dict[str, Any]:
-        """Extract stable run identifiers for row-level telemetry events."""
-        if not isinstance(runtime_context, Mapping):
-            return {}
-
-        fields: dict[str, Any] = {}
-        for key in ("thread_id", "run_id", "audit_id", "project_key", "repo_key"):
-            value = runtime_context.get(key)
-            normalized = str(value or "").strip()
-            if normalized:
-                fields[key] = normalized
-        return fields
-
-    @staticmethod
-    def _normalize_ref_text(value: Any) -> str:
-        return str(value or "").strip()
-
-    @classmethod
-    def _extract_refs_from_trace_steps(cls, trace_steps: list[Any] | None) -> list[str]:
-        if not isinstance(trace_steps, list):
-            return []
-
-        refs: list[str] = []
-
-        def _append_ref(value: Any) -> None:
-            normalized = cls._normalize_ref_text(value)
-            if normalized:
-                refs.append(normalized)
-
-        def _append_ref_candidates(payload: Any) -> None:
-            if not isinstance(payload, dict):
-                return
-            for key in (
-                "read_ref",
-                "ref_value",
-                "ref",
-                "doc_id",
-                "source_path",
-                "source_url",
-                "file_path",
-                "path",
-            ):
-                _append_ref(payload.get(key))
-            chunk_id = cls._normalize_ref_text(payload.get("chunk_id"))
-            if chunk_id:
-                if chunk_id.startswith("chunk:"):
-                    refs.append(chunk_id)
-                else:
-                    refs.append(f"chunk:{chunk_id}")
-
-        for step in trace_steps:
-            tool_name = ""
-            output: Any = None
-            if hasattr(step, "tool") and hasattr(step, "output"):
-                tool_name = (
-                    str(getattr(getattr(step, "tool", None), "value", getattr(step, "tool", "")) or "").strip().lower()
-                )
-                output = getattr(step, "output", None)
-            elif isinstance(step, dict):
-                tool_name = str(step.get("tool") or "").strip().lower()
-                output = step.get("output")
-            else:
-                continue
-            if not isinstance(output, dict):
-                continue
-
-            if tool_name == ToolName.READ_DOC_CHUNK.value:
-                _append_ref(output.get("ref"))
-                chunk_id = cls._normalize_ref_text(output.get("chunk_id"))
-                if chunk_id:
-                    _append_ref(f"chunk:{chunk_id}" if not chunk_id.startswith("chunk:") else chunk_id)
-                _append_ref_candidates(output)
-            elif tool_name == ToolName.READ_CODE_FILE.value:
-                _append_ref(output.get("file_path"))
-                _append_ref(output.get("path"))
-                _append_ref_candidates(output)
-            elif tool_name == ToolName.RECORD_EVIDENCE_REFS.value:
-                refs_payload = output.get("refs")
-                if isinstance(refs_payload, list):
-                    for ref_payload in refs_payload:
-                        _append_ref_candidates(ref_payload)
-
-        return list(dict.fromkeys(refs))
-
-    @staticmethod
-    def run_tool_first_loop(
-        *,
-        loop: Any,
-        check: Any,
-        row_id: str,
-        evidence_refs: list[str],
-        requirement_interpretation: dict[str, Any] | None,
-        enforce_budget: Any,
-        summarize: Any,
-        logger: Any,
-        runtime_context: Mapping[str, Any] | None = None,
-    ) -> Any:
-        """Execute optional bounded tool-first loop before prompt backend."""
-        if loop is None:
-            return None
-
-        initial_context = {
-            "row_id": row_id,
-            "check_id": check.id,
-            "requirement_text": check.description or check.name or "",
-            "requirement_category": check.section_id,
-            "evidence_refs": list(evidence_refs),
-            "requirement_interpretation": dict(requirement_interpretation or {}),
-            "runtime_context": dict(runtime_context or {}),
-        }
-        result = loop.run(initial_context=initial_context)
-
-        # P172-G / TSK-172.12: evidence gate retry trigger.
-        # When the gate fires INSUFFICIENT_EVIDENCE on the first pass, re-run once with:
-        #   - evidence_gate_retry_count=1  → bypass key that lets _apply_evidence_gate skip on re-entry
-        #   - reset_stagnation_counter=True → clear stagnation hashes so the retry starts fresh
-        #   - +5 tool_calls_limit headroom  → gives the retry run extra budget above the gate
-        # Capped at 1 retry (TSK-172.13 bypass handles the loop side).
-        if (
-            result.termination_reason == LoopTerminationReason.INSUFFICIENT_EVIDENCE
-            and int(initial_context.get("evidence_gate_retry_count") or 0) == 0
-        ):
-            retry_context = dict(initial_context)
-            retry_context["evidence_gate_retry_count"] = 1
-            _loop_config = getattr(loop, "config", None)
-            _original_limit: int | None = None
-            if _loop_config is not None and hasattr(_loop_config, "tool_calls_limit"):
-                _original_limit = int(_loop_config.tool_calls_limit)
-                _loop_config.tool_calls_limit = _original_limit + 5
-            try:
-                result = loop.run(initial_context=retry_context, reset_stagnation_counter=True)
-            finally:
-                if _loop_config is not None and _original_limit is not None:
-                    _loop_config.tool_calls_limit = _original_limit
-
-        trace_refs = RowEvaluatorRuntime._extract_refs_from_trace_steps(list(result.trace_steps or []))
-        if trace_refs:
-            merged_refs = list(
-                dict.fromkeys(
-                    [str(ref).strip() for ref in list(result.evidence_refs or []) if str(ref).strip()] + trace_refs
-                )
-            )
-            if merged_refs != list(result.evidence_refs or []):
-                result = result.model_copy(update={"evidence_refs": merged_refs})
-                logger.info(
-                    "row_tool_first_evidence_refs_hydrated_from_trace",
-                    row_id=row_id,
-                    check_id=check.id,
-                    hydrated_ref_count=len(trace_refs),
-                    merged_ref_count=len(merged_refs),
-                )
-        enforce_budget(row_id=row_id, check_id=check.id, loop_result=result)
-        summary = summarize(result)
-        runtime_fields = RowEvaluatorRuntime._runtime_log_fields(runtime_context)
-        logger.info(
-            "row_tool_first_efficiency",
-            row_id=row_id,
-            check_id=check.id,
-            requirement_category=check.section_id,
-            skill_metrics_scope="tool_first_loop",
-            **runtime_fields,
-            **summary,
-        )
-        return result
-
-    @staticmethod
-    def reset_skill_usage(logger: Any) -> None:
-        """Reset per-row skill usage collector before evaluation starts."""
-        try:
-            SkillExecutor.reset_usage()
-        except Exception as exc:
-            logger.warning("row_evaluation_skill_usage_reset_failed", error=str(exc))
-
-    @staticmethod
-    def consume_skill_usage(logger: Any) -> list[dict[str, Any]]:
-        """Return per-row skill usage records for retrieval trace augmentation."""
-        try:
-            usage = SkillExecutor.consume_usage()
-        except Exception as exc:
-            logger.warning("row_evaluation_skill_usage_consume_failed", error=str(exc))
-            return []
-        return [dict(entry) for entry in usage if isinstance(entry, dict)]
-
-    @staticmethod
-    def is_doc_like_ref(ref: str) -> bool:
-        """Return True when evidence ref likely points to documentation material."""
-        value = str(ref or "").strip().lower()
-        if not value:
-            return False
-        if value.startswith("chunk:"):
-            return True
-        if "://" in value:
-            parsed = urlparse(value)
-            host = str(parsed.netloc or "").lower()
-            path = str(parsed.path or "").lower()
-            if "confluence" in host:
-                return True
-            if any(
-                marker in path
-                for marker in ("/wiki/", "/display/", "/docs/", "/documentation/", "/runbook/", "/guide/")
-            ):
-                return True
-            return bool(path.endswith((".md", ".markdown", ".rst", ".adoc", ".txt", ".pdf", ".html")))
-        if value.startswith("docs/") or "/docs/" in value:
-            return True
-        return bool(re.search(r"\.(md|markdown|rst|adoc|txt)$", value))
-
-    @classmethod
-    def normalize_docs_requirement_evidence(
-        cls,
-        *,
-        check: Any,
-        evidence_context: str | None,
-        evidence_refs: list[str] | None,
-        is_docs_focused_requirement: Any,
-    ) -> tuple[str | None, list[str]]:
-        """Prevent docs checks from being grounded solely by non-doc code refs."""
-        requirement_text = check.description or check.name or ""
-        requirement_category = check.section_id or ""
-        if not is_docs_focused_requirement(
-            requirement_text=requirement_text,
-            requirement_category=requirement_category,
-        ):
-            return evidence_context, list(evidence_refs or [])
-
-        refs = [str(ref).strip() for ref in (evidence_refs or []) if str(ref).strip()]
-        doc_refs = [ref for ref in refs if cls.is_doc_like_ref(ref)]
-        if doc_refs:
-            return evidence_context, list(dict.fromkeys(doc_refs))
-
-        return "", []
-
-    @classmethod
-    def normalize_docs_requirement_trace(
-        cls,
-        *,
-        check: Any,
-        retrieval_trace: dict[str, Any] | None,
-        normalized_evidence_refs: list[str] | None,
-        is_docs_focused_requirement: Any,
-    ) -> dict[str, Any] | None:
-        """Align docs-focused trace refs with normalized grounding refs."""
-        if retrieval_trace is None:
-            return None
-
-        requirement_text = check.description or check.name or ""
-        requirement_category = check.section_id or ""
-        if not is_docs_focused_requirement(
-            requirement_text=requirement_text,
-            requirement_category=requirement_category,
-        ):
-            return retrieval_trace
-
-        normalized_refs = [str(ref).strip() for ref in (normalized_evidence_refs or []) if str(ref).strip()]
-        trace = dict(retrieval_trace)
-        loop_trace = trace.get("tool_first_loop")
-        if not isinstance(loop_trace, dict):
-            return trace
-
-        loop_copy: dict[str, Any] = dict(loop_trace)
-        loop_copy["evidence_refs"] = normalized_refs
-
-        trace_steps = loop_copy.get("trace_steps")
-        if isinstance(trace_steps, list):
-            updated_steps: list[Any] = []
-            for step in trace_steps:
-                if not isinstance(step, dict):
-                    updated_steps.append(step)
-                    continue
-
-                step_copy = dict(step)
-                tool_value = str(step_copy.get("tool") or "")
-                if tool_value == ToolName.GET_ROW_CONTEXT.value:
-                    output = step_copy.get("output")
-                    if isinstance(output, dict):
-                        output_copy = dict(output)
-                        context = output_copy.get("context")
-                        if isinstance(context, dict):
-                            context_copy = dict(context)
-                            context_copy["seed_evidence_ref_count"] = len(normalized_refs)
-                            context_copy["evidence_refs"] = normalized_refs
-                            output_copy["context"] = context_copy
-                            step_copy["output"] = output_copy
-                updated_steps.append(step_copy)
-            loop_copy["trace_steps"] = updated_steps
-
-        trace["tool_first_loop"] = loop_copy
-        return trace
-
-    @staticmethod
-    def apply_docs_missing_evidence_guardrail(
-        *,
-        check: Any,
-        result: Any,
-        normalized_evidence_refs: list[str] | None,
-        is_docs_focused_requirement: Any,
-        score_to_1_5: Any,
-        merge_retrieval_trace: Any,
-    ) -> Any:
-        """For docs-focused checks, prevent PASS/PARTIAL when no doc refs remain."""
-        requirement_text = check.description or check.name or ""
-        requirement_category = check.section_id or ""
-        if not is_docs_focused_requirement(
-            requirement_text=requirement_text,
-            requirement_category=requirement_category,
-        ):
-            return result
-
-        refs = [str(ref).strip() for ref in (normalized_evidence_refs or []) if str(ref).strip()]
-        if refs:
-            return result
-
-        if result.status not in {RowStatus.PASS, RowStatus.PARTIAL}:
-            return result
-
-        guarded_score = min(float(result.score or 0.0), 39.0)
-        reason_text = str(result.reason or "").strip()
-        guardrail_note = (
-            "Không có minh chứng tài liệu hợp lệ cho tiêu chí tài liệu/integration guide; "
-            "trạng thái được hạ xuống FAIL theo guardrail."
-        )
-
-        result.status = RowStatus.FAIL
-        result.score = guarded_score
-        result.score_breakdown = ScoreBreakdown.compute(raw_score=guarded_score)
-        result.score_1_5 = score_to_1_5(guarded_score)
-        result.reason = f"{reason_text} {guardrail_note}".strip() if reason_text else guardrail_note
-        result.retrieval_trace = merge_retrieval_trace(
-            result.retrieval_trace,
-            {"docs_grounding_guardrail_applied": True},
-        )
-        return result
-
-    @staticmethod
-    def get_row_context_with_runtime(request: Any, runtime_context: dict[str, Any]) -> dict[str, Any]:
-        """Augment row context output with runtime identifiers for tool-first traces."""
-        row_id = str(getattr(request, "row_id", "") or "")
-        requirement_text = str(getattr(request, "requirement_text", "") or "")
-        requirement_category = getattr(request, "requirement_category", None)
-        detailed_guidance = getattr(request, "detailed_guidance", None)
-        evidence_refs = list(getattr(request, "evidence_refs", []) or [])
-        existing_interpretation = dict(getattr(request, "requirement_interpretation", {}) or {})
-        refreshed_interpretation = build_requirement_interpretation(
-            requirement_text=requirement_text,
-            requirement_category=requirement_category,
-            requirement_guidance=str(detailed_guidance or ""),
-            evidence_refs=evidence_refs,
-            check_config={
-                "detailed_guidance": str(detailed_guidance or ""),
-                "check_manual": "Manual" if bool(getattr(request, "check_manual", False)) else "",
-            },
-        )
-        if isinstance(existing_interpretation.get("instruction_plan"), dict):
-            refreshed_interpretation["instruction_plan"] = existing_interpretation["instruction_plan"]
-        if existing_interpretation.get("instruction_plan_id"):
-            refreshed_interpretation["instruction_plan_id"] = existing_interpretation["instruction_plan_id"]
-        return {
-            "row_id": row_id,
-            "context": {
-                "check_id": str(getattr(request, "check_id", "") or ""),
-                "requirement_text": requirement_text,
-                "requirement_category": requirement_category,
-                "requirement_interpretation": refreshed_interpretation,
-                "seed_evidence_ref_count": len(getattr(request, "evidence_refs", []) or []),
-                "runtime_context": {
-                    "state_dsn": runtime_context.get("state_dsn"),
-                    "project_key": runtime_context.get("project_key"),
-                    "repo_key": runtime_context.get("repo_key"),
-                    "repo_path": runtime_context.get("repo_path"),
-                    "thread_id": runtime_context.get("thread_id"),
-                    "run_id": runtime_context.get("run_id"),
-                    "audit_id": runtime_context.get("audit_id"),
-                    "skills_toolset_enabled": runtime_context.get("skills_toolset_enabled"),
-                    "available_skill_names": runtime_context.get("available_skill_names"),
-                    "project_evidence_context": runtime_context.get("project_evidence_context"),
-                    "dependency_graph_path": runtime_context.get("dependency_graph_path"),
-                    "project_artifact_readiness": runtime_context.get("project_artifact_readiness"),
-                    "project_artifact_provenance_summary": runtime_context.get("project_artifact_provenance_summary"),
-                    "knowledge_enabled": runtime_context.get("knowledge_enabled"),
-                    "knowledge_accumulation_enabled": runtime_context.get("knowledge_accumulation_enabled"),
-                    "knowledge_retrieval_enabled": runtime_context.get("knowledge_retrieval_enabled"),
-                    "knowledge_ttl_days": runtime_context.get("knowledge_ttl_days"),
-                    "knowledge_confidence_threshold": runtime_context.get("knowledge_confidence_threshold"),
-                },
-            },
-        }
-
-    @staticmethod
-    def tool_first_plan(step_number: int, context: dict[str, Any], trace_steps: list[Any]) -> AgentLoopAction | None:
-        from vds_audit_orchestrator.engine.tool_first_planner import ToolFirstPlanner
-
-        return ToolFirstPlanner.plan(step_number, context, trace_steps)