@ngocsangairvds/vsaf 3.2.14 → 3.2.16

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

@@ -1,4130 +0,0 @@
-"""Agentic investigation helpers extracted from CodeAnalysisAgent."""
-
-from __future__ import annotations
-
-import asyncio
-import os
-import re
-import time
-from pathlib import Path
-from typing import TYPE_CHECKING, Any
-from urllib.parse import urlparse
-
-from vds_agent_core.config import LLMProtocolType
-from vds_agent_core.skills.manager import SkillManager
-
-from vds_audit_orchestrator.agents.code_analysis_prompts import CODE_ANALYSIS_SYSTEM_PROMPT
-from vds_audit_orchestrator.agents.pydantic_base import AuditDeps, CodeFindings, _build_toolsets
-from vds_audit_orchestrator.agents.tool_efficiency_guard import CadencePolicy, ToolEfficiencyGuard
-from vds_audit_orchestrator.config import get_config
-from vds_audit_orchestrator.engine.requirement_analysis import (
-    CodeSearchStrategyHint,
-    RequirementAnalysisResult,
-    derive_code_search_strategy,
-)
-from vds_audit_orchestrator.evidence.code_pack import CodeEvidencePack, CodePackBuilder
-from vds_audit_orchestrator.skills.skill_routing import AuditSkillRouter
-
-if TYPE_CHECKING:
-    from vds_audit_orchestrator.evidence.corpus import EvidenceCorpus
-    from vds_audit_orchestrator.models.evidence import EvidenceBundle
-
-# =============================================================================
-# Agentic Code Analysis System Prompt (Phase 41)
-# =============================================================================
-
-AGENTIC_CODE_ANALYSIS_SYSTEM_PROMPT = """You are a senior code quality analyst with access to repository exploration tools.
-
-Operate in TOOL-FIRST mode:
-- Do not assume provided snippets are complete.
-- Explore the repository and evidence corpus to gather precise evidence.
-- Prefer targeted retrieval over broad reads.
-
-- **list_directory**: Browse repository structure to find relevant files.
-- **read_file**: Read specific files or line ranges for deeper analysis.
-- **grep_search**: Search for patterns, function names, or keywords across the repo.
-- **rg_search**: Explicit ripgrep alias for exact/regex search.
-- **ast_grep_search**: Structural AST search for syntax-aware matching.
-- **list_evidence_documents**: List available Confluence/docs evidence in the corpus.
-- **search_evidence**: Search docs evidence by keyword.
-- **read_evidence_document**: Read a specific evidence document.
-- **list_skills**: List available skills.
-- **load_skill**: Load one skill when it is directly relevant.
-- **read_skill_resource**: Read a specific skill resource when needed.
-- **run_skill_script**: Execute a skill script only when it materially improves evidence quality.
-
-## Evidence Scopes
-
-The `search_code` and `read_code_file` tools accept a `scope` parameter to target specific evidence domains:
-
-- **scope="code"** (default): Search/read source code files (*.py, *.java, *.kt, *.go, *.ts, etc.). Use for implementation logic, API routes, error handling, and business logic.
-- **scope="config"**: Search/read configuration files (*.yaml, *.yml, *.json, *.toml, *.ini, *.properties, *.env, *.cfg, *.conf). Use for environment configs, deployment settings, feature flags, and infrastructure parameters.
-- **scope="lib"**: Search/read shared library files across auxiliary repositories. Use for cross-cutting concerns, shared utilities, and common modules referenced by the main codebase.
-- **scope="all"**: Search across all evidence domains without filtering. Use sparingly when the target domain is unknown.
-
-When investigating configuration-related checklist items (e.g., environment separation, secret management, deployment configs), prefer `scope="config"`. When investigating shared libraries or cross-repo dependencies, use `scope="lib"`.
-
-## Investigation Strategy
-
-1. Start with lightweight repository orientation (one discovery call only: grep_search preferred, list_directory only when needed).
-2. Retrieve only files/docs relevant to the checklist row and findings hypothesis.
-3. Correlate code findings with documentation evidence when possible.
-4. Keep tool usage focused - avoid exhaustive repo scans and avoid repeating identical list_directory calls on the same path.
-   - Do not perform path-by-path directory descent (e.g., repo -> src -> main -> java -> ...).
-   - After at most two list_directory calls, pivot to grep_search/rg_search/search_code_vector/read_file.
-5. After gathering sufficient evidence, produce your final assessment.
-6. Quality-first behavior: use focused tool calls; stop broad searching once two consecutive searches add no new evidence.
-7. Call exactly one tool per turn; wait for its result before the next tool call.
-8. Do not return a final answer before at least one repository tool call is completed.
-
-## Evaluation Criteria
-
-Same criteria as standard code analysis:
-- Code Structure (25%): module organization, separation of concerns
-- Error Handling (25%): try/except patterns, error propagation
-- Naming Conventions (20%): PEP 8 compliance, clarity
-- Security Practices (15%): input validation, credential handling
-- Maintainability (15%): complexity, documentation, test coverage
-
-## Output Requirements
-
-Provide the same structured output as standard analysis:
-1. Overall score (0-10) based on weighted criteria
-2. Specific issues with file paths, severity, and recommendations
-3. Detected patterns (both positive practices and anti-patterns)
-4. Confidence level based on evidence quality
-5. Clear reasoning for your assessment
-
-Be specific and actionable. Only report real issues found in the evidence."""
-
-AGENTIC_CODE_ANALYSIS_SYSTEM_PROMPT_OLLAMA_COMPACT = """You are a code analyst in strict TOOL-FIRST mode.
-
-Rules:
-- Start with grep_search or rg_search, then read_file on a concrete hit.
-- grep_search/rg_search match FILE CONTENT (not filenames). Use code/security patterns (e.g. "class ", "@RestController", "password", "TODO") with include globs.
-- Never use overly broad regex patterns such as "^", "$", ".", ".*", "\\s*", or empty pattern values.
-- Prefer specific tokens/patterns and include globs that narrow file scope (e.g. "**/*.java", "**/*.yml").
-- Use ast_grep_search when structural matching is needed.
-- Use list_directory only if grep_search cannot locate relevant files.
-- Never do path-by-path directory descent; maximum two list_directory calls before pivoting.
-- Never call read_file on "." or any directory path; read only concrete files.
-- Call one tool per turn and avoid repeating the same low-signal pattern.
-- If vector retrieval is available, use search_evidence_vector (docs) or search_code_vector (code) for grounding.
-- search_code and read_code_file accept scope: "code" (default, source files), "config" (configuration files), "lib" (shared libraries), "all" (unfiltered).
-- Use scope="config" for environment/deployment/secret checks; scope="lib" for shared library checks.
-- Ground each issue in concrete evidence and return only real, verifiable findings.
-"""
-
-PATH_RESOLUTION_RECOVERABLE_ERRORS = (OSError, RuntimeError)
-
-
-def _render_phase115_strategy_guidance(strategy_hint: CodeSearchStrategyHint) -> str:
-    tool_text = ", ".join(strategy_hint.preferred_tools) or "search_code, read_code_file"
-    patterns_text = ", ".join(strategy_hint.file_pattern_hints) or "no specific file-pattern hints"
-    lines = ["\n## [Search strategy guidance] (Phase 115)"]
-    lines.append(f"- Strategy: {strategy_hint.strategy}")
-    lines.append(f"- Preferred tools: {tool_text}")
-    if strategy_hint.scope_hint:
-        lines.append(f"- Scope hint: {strategy_hint.scope_hint}")
-    if strategy_hint.query_variant:
-        lines.append(f"- Query variant: {strategy_hint.query_variant}")
-    if strategy_hint.requirement_type_tag:
-        lines.append(f"- Requirement type: {strategy_hint.requirement_type_tag}")
-    if strategy_hint.file_pattern_hints:
-        lines.append(f"- File pattern hints: {patterns_text}")
-
-    if strategy_hint.strategy == "targeted_file":
-        lines.append("- Guidance: search for specific artifacts first, then confirm with focused reads.")
-    elif strategy_hint.strategy == "structural_pattern":
-        lines.append(
-            "- Guidance: use structural/vector discovery first, then confirm architecture boundaries with concrete code reads."
-        )
-    elif strategy_hint.strategy == "multi_pass":
-        lines.append(
-            "- Guidance: run an initial domain-specific pass, then broaden scope only if the first pass is insufficient."
-        )
-    elif strategy_hint.strategy == "vector_semantic":
-        lines.append(
-            "- Guidance: use search_code_vector as the primary discovery tool when available, then pivot to concrete reads."
-        )
-    else:
-        lines.append("- Guidance: use semantic grep first, then read the most relevant concrete files.")
-
-    if strategy_hint.escalation_scope:
-        lines.append(f"- Escalation scope: {strategy_hint.escalation_scope}")
-    return "\n".join(lines) + "\n"
-
-
-AGENTIC_SETUP_RECOVERABLE_ERRORS = (
-    AttributeError,
-    ImportError,
-    OSError,
-    RuntimeError,
-    TypeError,
-    ValueError,
-)
-CODE_PACK_RECOVERABLE_ERRORS = (OSError, RuntimeError, TypeError, ValueError)
-STRUCTURED_OUTPUT_RECOVERABLE_ERRORS = (TypeError, ValueError)
-
-
-class AgenticInvestigator:
-    """Mixin containing the AGENTIC investigation flow for code analysis."""
-
-    _SKILL_TOOL_NAMES: frozenset[str] = frozenset(
-        {
-            "list_skills",
-            "load_skill",
-            "read_skill_resource",
-            "run_skill_script",
-        }
-    )
-
-    @staticmethod
-    def _get_runtime_config():
-        """Return runtime config for agentic setup."""
-        return get_config()
-
-    @staticmethod
-    def _build_runtime_toolsets(llm_config: Any):
-        """Build runtime toolsets from LLM config."""
-        return _build_toolsets(llm_config)
-
-    @staticmethod
-    def _runtime_protocol_type():
-        """Return protocol enum used by agentic runtime routing."""
-        return LLMProtocolType
-
-    @staticmethod
-    def _parse_env_bool(name: str) -> bool | None:
-        """Parse optional boolean env flag."""
-        raw = os.getenv(name)
-        if raw is None:
-            return None
-        value = raw.strip().lower()
-        if value in {"1", "true", "yes", "on"}:
-            return True
-        if value in {"0", "false", "no", "off"}:
-            return False
-        return None
-
-    def _runtime_protocol_value(self) -> str:
-        """Resolve protocol value used by the active runtime model endpoint."""
-        return str(self.settings.protocol.value)
-
-    def _uses_local_openai_protocol(self) -> bool:
-        """Return True when runtime uses OpenAI protocol against a local endpoint."""
-        if self._runtime_protocol_value() != "openai":
-            return False
-        endpoint_value = getattr(self.settings, "base_url", None)
-        endpoint = endpoint_value.strip() if isinstance(endpoint_value, str) else ""
-        if not endpoint:
-            endpoint = "http://127.0.0.1:11434"
-        if not endpoint:
-            return False
-        parsed = urlparse(endpoint)
-        host = (parsed.hostname or "").lower()
-        return host in {"localhost", "127.0.0.1", "0.0.0.0", "::1"}
-
-    def _is_agentic_skills_toolset_enabled(self, llm_config: Any) -> bool:
-        """Resolve effective skill-toolset flag for agentic code analysis."""
-        code_override = self._parse_env_bool("VDS_AUDIT_AGENTIC_CODE_ENABLE_SKILLS_TOOLSET")
-        if code_override is not None:
-            return code_override
-        generic_override = self._parse_env_bool("VDS_AUDIT_AGENTIC_ENABLE_SKILLS_TOOLSET")
-        if generic_override is not None:
-            return generic_override
-        return bool(getattr(llm_config, "skills_toolset_enabled", False))
-
-    @staticmethod
-    def _has_default_skills_toolset_available() -> bool:
-        try:
-            from vds_audit_orchestrator.agents.toolsets.skills_toolset import DEFAULT_AUDIT_SKILLS
-        except Exception:
-            return False
-        return bool(list(DEFAULT_AUDIT_SKILLS or []))
-
-    @classmethod
-    def _requires_requirement_driven_skill_toolset(cls, state_context: dict[str, Any] | None) -> bool:
-        interpretation = cls._extract_requirement_interpretation_from_state_context(state_context)
-        objectives = interpretation.get("skill_objectives") if isinstance(interpretation, dict) else []
-        normalized_objectives = {
-            str(item).strip() for item in (objectives if isinstance(objectives, list) else []) if str(item).strip()
-        }
-        return bool(
-            normalized_objectives
-            & {
-                "discover_app_config",
-                "resolve_environment_specific_config",
-                "analyze_datasource_isolation",
-                "compare_cross_service_config_separation",
-            }
-        )
-
-    def _resolve_agentic_runtime(self) -> dict[str, Any] | None:
-        """Resolve effective runtime settings for bounded AGENTIC execution.
-
-        Returns None when AGENTIC runtime cannot be initialized.
-        """
-        try:
-            config = self._get_runtime_config()
-        except AGENTIC_SETUP_RECOVERABLE_ERRORS as exc:
-            self.logger.warning(
-                "agentic_config_load_failed",
-                error=str(exc),
-                error_type=type(exc).__name__,
-                handler="_resolve_agentic_runtime",
-            )
-            return None
-
-        agentic_cfg = config.agentic
-        mode_value = getattr(self, "agentic_mode", None)
-        if mode_value is None:
-            mode_value = getattr(self, "_agentic_mode", "")
-        forced_agentic_mode = str(mode_value).strip().lower() == "on"
-        if not agentic_cfg.enabled:
-            if not forced_agentic_mode:
-                self.logger.info("agentic_disabled_in_config")
-                return None
-            self.logger.warning("agentic_force_enabled_by_mode_override")
-
-        safe_extensions = tuple(ext for ext in agentic_cfg.safe_extensions if isinstance(ext, str) and ext)
-        if not safe_extensions:
-            self.logger.warning("agentic_safe_extensions_empty")
-            return None
-
-        max_turns = int(agentic_cfg.max_turns)
-        max_tool_calls = int(agentic_cfg.max_tool_calls)
-        strict_cap_max_turns = int(getattr(agentic_cfg, "strict_cap_max_turns", 10))
-        strict_cap_max_tool_calls = int(getattr(agentic_cfg, "strict_cap_max_tool_calls", 24))
-        llm_skills_toolset_enabled = self._is_agentic_skills_toolset_enabled(config.llm)
-        raw_state_context = getattr(self, "_state_context", None)
-        state_context = dict(raw_state_context) if isinstance(raw_state_context, dict) else {}
-        if (
-            not llm_skills_toolset_enabled
-            and self._requires_requirement_driven_skill_toolset(state_context)
-            and self._has_default_skills_toolset_available()
-        ):
-            llm_skills_toolset_enabled = True
-            self.logger.info(
-                "agentic_skills_toolset_auto_enabled_for_requirement",
-                reason="requirement_driven_app_config_skill",
-            )
-        compact_max_turns_override: int | None = None
-        compact_max_tool_calls_override: int | None = None
-        compact_default_max_turns = 8
-        compact_default_max_tool_calls = 20
-        raw_compact_turns = str(os.getenv("VDS_AUDIT_AGENTIC_COMPACT_MAX_TURNS", "")).strip()
-        raw_compact_tools = str(os.getenv("VDS_AUDIT_AGENTIC_COMPACT_MAX_TOOL_CALLS", "")).strip()
-        raw_compact_default_turns = str(
-            os.getenv("VDS_AUDIT_AGENTIC_COMPACT_DEFAULT_MAX_TURNS", str(compact_default_max_turns))
-        ).strip()
-        raw_compact_default_tools = str(
-            os.getenv("VDS_AUDIT_AGENTIC_COMPACT_DEFAULT_MAX_TOOL_CALLS", str(compact_default_max_tool_calls))
-        ).strip()
-        if raw_compact_turns.isdigit():
-            parsed_turns = int(raw_compact_turns)
-            if parsed_turns > 0:
-                compact_max_turns_override = parsed_turns
-        if raw_compact_tools.isdigit():
-            parsed_tools = int(raw_compact_tools)
-            if parsed_tools > 0:
-                compact_max_tool_calls_override = parsed_tools
-        if raw_compact_default_turns.isdigit():
-            parsed_default_turns = int(raw_compact_default_turns)
-            if parsed_default_turns > 0:
-                compact_default_max_turns = parsed_default_turns
-        if raw_compact_default_tools.isdigit():
-            parsed_default_tools = int(raw_compact_default_tools)
-            if parsed_default_tools > 0:
-                compact_default_max_tool_calls = parsed_default_tools
-        if forced_agentic_mode and not agentic_cfg.enabled:
-            # Guardrail for forced explicit mode: avoid low default caps causing
-            # immediate request-limit exits before meaningful tool exploration.
-            max_turns = max(max_turns, 12)
-            max_tool_calls = max(max_tool_calls, 40)
-        # Strict fail-fast mode: preserve tool-first quality, but cap runaway loops.
-        # This keeps analysis focused and forces earlier synthesis/guard handling.
-        if bool(agentic_cfg.strict_no_fallback):
-            if self._uses_local_openai_protocol():
-                max_turns = min(max_turns, strict_cap_max_turns)
-                max_tool_calls = min(max_tool_calls, strict_cap_max_tool_calls)
-                if compact_max_turns_override is not None:
-                    max_turns = min(max_turns, compact_max_turns_override)
-                else:
-                    max_turns = min(max_turns, compact_default_max_turns)
-                if compact_max_tool_calls_override is not None:
-                    max_tool_calls = min(max_tool_calls, compact_max_tool_calls_override)
-                else:
-                    max_tool_calls = min(max_tool_calls, compact_default_max_tool_calls)
-            else:
-                max_turns = min(max_turns, 12)
-                max_tool_calls = min(max_tool_calls, 24)
-
-        return {
-            "enabled": True,
-            "max_turns": max_turns,
-            "max_tool_calls": max_tool_calls,
-            "tool_timeout_sec": int(agentic_cfg.tool_timeout_sec),
-            "safe_extensions": safe_extensions,
-            "max_read_bytes": int(agentic_cfg.max_read_bytes),
-            "max_read_lines": int(agentic_cfg.max_read_lines),
-            "strict_no_fallback": bool(agentic_cfg.strict_no_fallback),
-            "strict_cap_max_turns": strict_cap_max_turns,
-            "strict_cap_max_tool_calls": strict_cap_max_tool_calls,
-            "compact_max_turns_override": compact_max_turns_override,
-            "compact_max_tool_calls_override": compact_max_tool_calls_override,
-            "compact_default_max_turns": compact_default_max_turns,
-            "compact_default_max_tool_calls": compact_default_max_tool_calls,
-            "local_openai_synthesis_max_turns": int(getattr(agentic_cfg, "local_openai_synthesis_max_turns", 4)),
-            "local_openai_synthesis_max_tool_calls": int(
-                getattr(agentic_cfg, "local_openai_synthesis_max_tool_calls", 2)
-            ),
-            "local_openai_hard_synthesis_max_turns": int(
-                getattr(agentic_cfg, "local_openai_hard_synthesis_max_turns", 2)
-            ),
-            "local_openai_hard_synthesis_max_tool_calls": int(
-                getattr(agentic_cfg, "local_openai_hard_synthesis_max_tool_calls", 0)
-            ),
-            "synthesis_max_turns": int(getattr(agentic_cfg, "synthesis_max_turns", 4)),
-            "synthesis_max_tool_calls": int(getattr(agentic_cfg, "synthesis_max_tool_calls", 2)),
-            "hard_synthesis_max_turns": int(getattr(agentic_cfg, "hard_synthesis_max_turns", 2)),
-            "hard_synthesis_max_tool_calls": int(getattr(agentic_cfg, "hard_synthesis_max_tool_calls", 0)),
-            "skills_toolset_enabled": llm_skills_toolset_enabled,
-            "non_progress_policy": agentic_cfg.non_progress_policy.model_dump(),
-            "tool_allowlist": list(agentic_cfg.tool_allowlists.get("code", [])),
-        }
-
-    @staticmethod
-    def _extract_tool_usage(telemetry: dict[str, Any] | None) -> tuple[int, int]:
-        if not isinstance(telemetry, dict):
-            return (0, 0)
-        usage = telemetry.get("usage")
-        usage_tool_calls = int(usage.get("tool_calls", 0) or 0) if isinstance(usage, dict) else 0
-        event_tool_calls = int(telemetry.get("event_tool_calls_completed", telemetry.get("event_tool_calls", 0)) or 0)
-        event_skill_tool_calls = int(telemetry.get("event_skill_tool_calls", 0) or 0)
-        tool_calls = max(usage_tool_calls, event_tool_calls)
-        skill_calls = event_skill_tool_calls
-        return (tool_calls, skill_calls)
-
-    @staticmethod
-    def _extract_docs_tool_usage(telemetry: dict[str, Any] | None) -> int:
-        """Return count of evidence-doc tool calls observed in telemetry."""
-        if not isinstance(telemetry, dict):
-            return 0
-        by_name = telemetry.get("event_tool_count_by_name")
-        if not isinstance(by_name, dict):
-            return 0
-        return sum(
-            int(by_name.get(name, 0) or 0)
-            for name in ("list_evidence_documents", "search_evidence", "read_evidence_document")
-        )
-
-    @staticmethod
-    def _extract_docs_read_tool_usage(telemetry: dict[str, Any] | None) -> int:
-        """Return count of concrete evidence-doc reads (not just discovery/search)."""
-        if not isinstance(telemetry, dict):
-            return 0
-        by_name = telemetry.get("event_tool_count_by_name")
-        if not isinstance(by_name, dict):
-            return 0
-        return int(by_name.get("read_evidence_document", 0) or 0)
-
-    @staticmethod
-    def _extract_vector_docs_tool_usage(telemetry: dict[str, Any] | None) -> int:
-        """Return count of vector-evidence tool calls observed in telemetry."""
-        if not isinstance(telemetry, dict):
-            return 0
-        by_name = telemetry.get("event_tool_count_by_name")
-        if not isinstance(by_name, dict):
-            return 0
-        return int(by_name.get("search_evidence_vector", 0) or 0) + int(by_name.get("search_code_vector", 0) or 0)
-
-    @staticmethod
-    def _extract_code_read_tool_usage(telemetry: dict[str, Any] | None) -> int:
-        """Return count of concrete code-reading/navigation tool calls from telemetry."""
-        if not isinstance(telemetry, dict):
-            return 0
-        by_name = telemetry.get("event_tool_count_by_name")
-        if not isinstance(by_name, dict):
-            return 0
-        return sum(
-            int(by_name.get(name, 0) or 0)
-            for name in ("read_file", "get_definition", "find_references", "workspace_symbol")
-        )
-
-    @staticmethod
-    def _extract_skill_effective_usage(telemetry: dict[str, Any] | None) -> int:
-        """Return count of effective skill tool calls (execution-class) from telemetry."""
-        if not isinstance(telemetry, dict):
-            return 0
-        if "event_skill_execution_effective_tool_calls" in telemetry:
-            return int(telemetry.get("event_skill_execution_effective_tool_calls", 0) or 0)
-        if "event_skill_effective_tool_calls" in telemetry:
-            return int(telemetry.get("event_skill_effective_tool_calls", 0) or 0)
-        usage = telemetry.get("event_skill_tool_usage")
-        if isinstance(usage, list):
-            effective_execution = 0
-            for entry in usage:
-                if not isinstance(entry, dict):
-                    continue
-                tool_name = str(entry.get("tool") or "").strip()
-                if tool_name not in {"read_skill_resource", "run_skill_script"}:
-                    continue
-                if bool(entry.get("effective")):
-                    effective_execution += 1
-            if effective_execution > 0:
-                return effective_execution
-        by_name = telemetry.get("event_skill_tool_count_by_name")
-        if isinstance(by_name, dict):
-            return int(by_name.get("read_skill_resource", 0) or 0) + int(by_name.get("run_skill_script", 0) or 0)
-        if "event_skill_execution_tool_calls" in telemetry:
-            return int(telemetry.get("event_skill_execution_tool_calls", 0) or 0)
-        return 0
-
-    @staticmethod
-    def _merge_retry_telemetry(aggregate: dict[str, Any], attempt: dict[str, Any] | None) -> dict[str, Any]:
-        """Merge one attempt telemetry snapshot into aggregate counters."""
-        if not isinstance(attempt, dict):
-            return aggregate
-        observed_keys = {
-            "event_tool_calls",
-            "event_tool_calls_started",
-            "event_tool_calls_completed",
-            "event_tool_effective_calls",
-            "event_skill_tool_calls",
-            "event_skill_discovery_tool_calls",
-            "event_skill_bootstrap_tool_calls",
-            "event_skill_execution_tool_calls",
-            "event_skill_execution_effective_tool_calls",
-            "event_skill_effective_tool_calls",
-            "event_turn_effectiveness",
-            "event_tool_names",
-            "event_tool_signatures",
-            "event_tool_count_by_name",
-            "event_tool_effective_count_by_name",
-            "event_skill_tool_count_by_name",
-            "event_tool_latencies_ms",
-            "usage",
-            "skill_policy_diagnostics",
-        }
-        if not any(key in attempt for key in observed_keys):
-            return aggregate
-
-        numeric_keys = (
-            "event_tool_calls",
-            "event_tool_calls_started",
-            "event_tool_calls_completed",
-            "event_tool_effective_calls",
-            "event_skill_tool_calls",
-            "event_skill_discovery_tool_calls",
-            "event_skill_bootstrap_tool_calls",
-            "event_skill_execution_tool_calls",
-            "event_skill_execution_effective_tool_calls",
-            "event_skill_effective_tool_calls",
-        )
-        for key in numeric_keys:
-            if key not in attempt and key not in aggregate:
-                continue
-            aggregate[key] = int(aggregate.get(key, 0) or 0) + int(attempt.get(key, 0) or 0)
-
-        tool_names = aggregate.get("event_tool_names")
-        if not isinstance(tool_names, list):
-            tool_names = []
-        for name in attempt.get("event_tool_names", []):
-            if isinstance(name, str) and name and name not in tool_names:
-                tool_names.append(name)
-        aggregate["event_tool_names"] = tool_names
-
-        tool_signatures = aggregate.get("event_tool_signatures")
-        if not isinstance(tool_signatures, list):
-            tool_signatures = []
-        if isinstance(attempt.get("event_tool_signatures"), list):
-            tool_signatures.extend(str(sig) for sig in attempt["event_tool_signatures"])
-        aggregate["event_tool_signatures"] = tool_signatures
-
-        for map_key in (
-            "event_tool_count_by_name",
-            "event_tool_effective_count_by_name",
-            "event_skill_tool_count_by_name",
-        ):
-            merged = aggregate.get(map_key)
-            if not isinstance(merged, dict):
-                merged = {}
-            source = attempt.get(map_key)
-            if isinstance(source, dict):
-                for name, count in source.items():
-                    key = str(name)
-                    merged[key] = int(merged.get(key, 0) or 0) + int(count or 0)
-            aggregate[map_key] = merged
-
-        turn_effectiveness = aggregate.get("event_turn_effectiveness")
-        if not isinstance(turn_effectiveness, dict):
-            turn_effectiveness = {}
-        next_turn_index = max(
-            (int(str(turn_key)) for turn_key in turn_effectiveness if str(turn_key).strip().isdigit()),
-            default=0,
-        )
-        attempt_turn_effectiveness = attempt.get("event_turn_effectiveness")
-        if isinstance(attempt_turn_effectiveness, dict):
-            for _, payload in sorted(
-                (
-                    (int(str(turn_key)), value)
-                    for turn_key, value in attempt_turn_effectiveness.items()
-                    if str(turn_key).strip().isdigit() and isinstance(value, dict)
-                ),
-                key=lambda item: item[0],
-            ):
-                next_turn_index += 1
-                turn_effectiveness[str(next_turn_index)] = dict(payload)
-        if turn_effectiveness:
-            aggregate["event_turn_effectiveness"] = turn_effectiveness
-            aggregate["event_turn_index"] = next_turn_index
-
-        latencies = aggregate.get("event_tool_latencies_ms")
-        if not isinstance(latencies, list):
-            latencies = []
-        if isinstance(attempt.get("event_tool_latencies_ms"), list):
-            latencies.extend(
-                int(value) for value in attempt["event_tool_latencies_ms"] if isinstance(value, (int, float))
-            )
-        aggregate["event_tool_latencies_ms"] = latencies
-
-        usage = aggregate.get("usage")
-        if not isinstance(usage, dict):
-            usage = {}
-        attempt_usage = attempt.get("usage")
-        if isinstance(attempt_usage, dict):
-            usage["requests"] = int(usage.get("requests", 0) or 0) + int(attempt_usage.get("requests", 0) or 0)
-            usage["input_tokens"] = int(usage.get("input_tokens", 0) or 0) + int(
-                attempt_usage.get("input_tokens", 0) or 0
-            )
-            usage["output_tokens"] = int(usage.get("output_tokens", 0) or 0) + int(
-                attempt_usage.get("output_tokens", 0) or 0
-            )
-            usage["tool_calls"] = int(usage.get("tool_calls", 0) or 0) + int(attempt_usage.get("tool_calls", 0) or 0)
-        aggregate["usage"] = usage
-        skill_policy_diagnostics = attempt.get("skill_policy_diagnostics")
-        if isinstance(skill_policy_diagnostics, dict):
-            aggregate["skill_policy_diagnostics"] = dict(skill_policy_diagnostics)
-        aggregate["retry_attempts"] = int(aggregate.get("retry_attempts", 0) or 0) + 1
-        return aggregate
-
-    @staticmethod
-    def _parse_skill_name_from_error(error: str) -> str | None:
-        return SkillManager.parse_skill_name_from_error(error)
-
-    @staticmethod
-    def _drop_skill_from_toolsets(toolsets: list[Any], skill_name: str) -> tuple[list[Any], int]:
-        return SkillManager.drop_skill_from_toolsets(toolsets, skill_name)
-
-    def _prevalidate_skill_toolsets(self, toolsets: list[Any]) -> list[Any]:
-        import vds_audit_orchestrator.agents.toolsets.skills_toolset as _st
-
-        class _HashValidator:
-            def validate(self, item: Any, *, raise_on_mismatch: bool = False) -> bool:
-                return _st.validate_skill_content_hash(item, raise_on_mismatch=raise_on_mismatch)
-
-        return SkillManager.prevalidate_skill_toolsets(toolsets, logger=self.logger, hash_validator=_HashValidator())
-
-    @staticmethod
-    def _is_tool_efficiency_kpi_unsatisfied(
-        summary: dict[str, Any] | None,
-        cadence_policy: CadencePolicy | None = None,
-    ) -> bool:
-        return ToolEfficiencyGuard.is_tool_efficiency_kpi_unsatisfied(summary, cadence_policy=cadence_policy)
-
-    @staticmethod
-    def _build_tool_efficiency_corrective_prompt(
-        base_prompt: str,
-        cadence_policy: CadencePolicy | None = None,
-    ) -> str:
-        return ToolEfficiencyGuard.build_tool_efficiency_corrective_prompt(base_prompt, cadence_policy=cadence_policy)
-
-    @staticmethod
-    def _collect_available_skill_names(toolsets: list[Any]) -> list[str]:
-        return SkillManager.collect_available_skill_names(toolsets, require_skill_tool_bindings=True)
-
-    @staticmethod
-    def _build_preloaded_skill_context(
-        toolsets: list[Any],
-        available_skill_names: list[str],
-        *,
-        max_skills: int = 2,
-        max_chars_per_skill: int = 1400,
-        preferred_skill_names: list[str] | None = None,
-    ) -> tuple[str, list[str]]:
-        return SkillManager.build_preloaded_skill_context(
-            toolsets=toolsets,
-            available_skill_names=available_skill_names,
-            max_skills=max_skills,
-            max_chars_per_skill=max_chars_per_skill,
-            preferred_skill_names=preferred_skill_names,
-        )
-
-    @classmethod
-    def _recommend_skills_for_state_context(
-        cls,
-        *,
-        state_context: dict[str, Any] | None,
-        available_skill_names: list[str],
-        limit: int = 3,
-    ) -> list[str]:
-        state = dict(state_context or {}) if isinstance(state_context, dict) else {}
-        interpretation = cls._extract_requirement_interpretation_from_state_context(state)
-        requirement_text = str(
-            interpretation.get("intent") or state.get("requirement_text") or state.get("row_requirement_text") or ""
-        ).strip()
-        requirement_category = str(
-            interpretation.get("control_objective")
-            or state.get("requirement_category")
-            or state.get("row_requirement_category")
-            or ""
-        ).strip()
-        return AuditSkillRouter.recommend_skills_for_requirement(
-            requirement_text=requirement_text,
-            requirement_category=requirement_category,
-            requirement_interpretation=interpretation,
-            available_skill_names=available_skill_names,
-            limit=limit,
-        )
-
-    @staticmethod
-    def _focus_skills_in_toolsets(
-        toolsets: list[Any],
-        allowed_skill_names: list[str],
-    ) -> tuple[list[Any], int]:
-        return SkillManager.retain_skills_in_toolsets(toolsets=toolsets, allowed_skill_names=allowed_skill_names)
-
-    @staticmethod
-    def _normalize_string_list(value: Any) -> list[str]:
-        if not isinstance(value, list):
-            return []
-        return [str(item).strip() for item in value if str(item).strip()]
-
-    @staticmethod
-    def _remove_tool_names(toolsets: list[Any], blocked_names: set[str] | frozenset[str]) -> tuple[list[Any], int]:
-        """Remove tool bindings by exact name across all toolsets."""
-        blocked = {str(name).strip() for name in blocked_names if str(name).strip()}
-        if not blocked:
-            return list(toolsets), 0
-        filtered: list[Any] = []
-        removed = 0
-        for toolset in toolsets:
-            tools_map = getattr(toolset, "tools", None)
-            if isinstance(tools_map, dict):
-                for name in list(tools_map):
-                    if name in blocked:
-                        tools_map.pop(name, None)
-                        removed += 1
-                if not tools_map:
-                    continue
-            filtered.append(toolset)
-        return filtered, removed
-
-    @staticmethod
-    def _is_doc_like_ref(ref: str) -> bool:
-        normalized = str(ref or "").strip().lower()
-        if not normalized:
-            return False
-        if normalized.startswith("chunk:"):
-            return True
-        if "/docs/" in normalized or normalized.startswith("docs/"):
-            return True
-        if "openapi" in normalized or "swagger" in normalized or "readme" in normalized:
-            return True
-        return normalized.endswith((".md", ".mdx", ".adoc", ".rst", ".txt", ".pdf", ".yaml", ".yml"))
-
-    @staticmethod
-    def _is_code_like_ref(ref: str) -> bool:
-        normalized = str(ref or "").strip().lower()
-        if not normalized:
-            return False
-        return normalized.endswith(
-            (
-                ".py",
-                ".java",
-                ".kt",
-                ".kts",
-                ".js",
-                ".jsx",
-                ".ts",
-                ".tsx",
-                ".go",
-                ".rb",
-                ".php",
-                ".cs",
-                ".c",
-                ".h",
-                ".cpp",
-                ".cc",
-                ".rs",
-                ".swift",
-                ".scala",
-            )
-        )
-
-    @classmethod
-    def _extract_evidence_refs_from_state_context(cls, state_context: dict[str, Any] | None) -> list[str]:
-        if not isinstance(state_context, dict):
-            return []
-
-        refs: list[str] = []
-
-        def _append_from(value: Any) -> None:
-            if isinstance(value, list):
-                refs.extend(str(item).strip() for item in value if str(item).strip())
-            elif isinstance(value, str) and value.strip():
-                refs.append(value.strip())
-
-        _append_from(state_context.get("evidence_refs"))
-        for key in ("row_context", "context", "row", "tool_get_row_context_output", "retrieval_trace"):
-            container = state_context.get(key)
-            if isinstance(container, dict):
-                _append_from(container.get("evidence_refs"))
-
-        return list(dict.fromkeys(refs))
-
-    @classmethod
-    def _extract_evidence_context_text(cls, state_context: dict[str, Any] | None) -> str:
-        if not isinstance(state_context, dict):
-            return ""
-
-        for key in ("evidence_context",):
-            value = state_context.get(key)
-            if isinstance(value, str) and value.strip():
-                return value.strip()
-
-        for key in ("row_context", "context", "row", "tool_get_row_context_output", "retrieval_trace"):
-            container = state_context.get(key)
-            if isinstance(container, dict):
-                value = container.get("evidence_context")
-                if isinstance(value, str) and value.strip():
-                    return value.strip()
-
-        return ""
-
-    @classmethod
-    def _should_skip_advisory_skill_sequence(
-        cls,
-        *,
-        state_context: dict[str, Any] | None,
-        interpretation: dict[str, Any] | None,
-    ) -> bool:
-        """Return True when advisory skill usage should be suppressed for grounded rows."""
-        interp = dict(interpretation or {}) if isinstance(interpretation, dict) else {}
-        refs = cls._extract_evidence_refs_from_state_context(state_context)
-        evidence_context = cls._extract_evidence_context_text(state_context)
-        evidence_targets = {
-            str(item).strip().lower() for item in (interp.get("evidence_targets") or []) if str(item).strip()
-        }
-        objectives = {str(item).strip().lower() for item in (interp.get("skill_objectives") or []) if str(item).strip()}
-
-        has_doc_ref = any(cls._is_doc_like_ref(ref) for ref in refs)
-        has_code_ref = any(cls._is_code_like_ref(ref) for ref in refs)
-        has_context_signal = len(evidence_context) >= 200
-
-        # Docs-anchored rows with explicit documentation-analysis objectives are
-        # frequently over-triggering discovery-only skill loops. Keep skills
-        # advisory-only when baseline grounding is already present.
-        if "analyze_documentation_artifacts" in objectives and (
-            len(refs) >= 2 and (has_doc_ref or "docs" in evidence_targets) and (has_context_signal or len(refs) >= 3)
-        ):
-            return True
-
-        if len(refs) < 4:
-            return False
-        if not ("docs" in evidence_targets and "code" in evidence_targets):
-            return False
-        if not (has_doc_ref and has_code_ref):
-            return False
-        return len(evidence_context) >= 800 or len(refs) >= 5
-
-    @classmethod
-    def _extract_requirement_interpretation_from_state_context(
-        cls,
-        state_context: dict[str, Any] | None,
-    ) -> dict[str, Any]:
-        """Extract requirement interpretation artifact from state context variants."""
-        if not isinstance(state_context, dict):
-            return {}
-
-        def _extract_from_container(container: dict[str, Any] | None) -> dict[str, Any]:
-            if not isinstance(container, dict):
-                return {}
-            direct_interpretation = container.get("requirement_interpretation")
-            if isinstance(direct_interpretation, dict):
-                return dict(direct_interpretation)
-            nested_context = container.get("context")
-            if isinstance(nested_context, dict):
-                nested_interpretation = nested_context.get("requirement_interpretation")
-                if isinstance(nested_interpretation, dict):
-                    return dict(nested_interpretation)
-            return {}
-
-        direct = state_context.get("requirement_interpretation")
-        if isinstance(direct, dict):
-            return dict(direct)
-
-        for key in (
-            "row_context",
-            "context",
-            "row",
-            "tool_get_row_context_output",
-            "retrieval_trace",
-        ):
-            extracted = _extract_from_container(state_context.get(key))
-            if extracted:
-                return extracted
-
-        fallback_keys = {
-            "intent",
-            "control_objective",
-            "evidence_targets",
-            "code_targets",
-            "acceptance_signals",
-            "skill_objectives",
-        }
-        if any(key in state_context for key in fallback_keys):
-            return {key: state_context.get(key) for key in fallback_keys if key in state_context}
-        return {}
-
-    @classmethod
-    def _resolve_requirement_skill_activation_decision(
-        cls,
-        *,
-        state_context: dict[str, Any] | None,
-    ) -> dict[str, Any]:
-        """Resolve requirement-driven skill activation decision (FR-122)."""
-        state = dict(state_context) if isinstance(state_context, dict) else {}
-        interpretation = cls._extract_requirement_interpretation_from_state_context(state)
-
-        explicit_state_decision = state.get("skills_needed")
-        if isinstance(explicit_state_decision, bool):
-            explicit_state_reason = str(state.get("skills_needed_reason") or "").strip()
-            return {
-                "skills_needed": explicit_state_decision,
-                "reason": explicit_state_reason or "state_context_explicit_skills_needed",
-                "decision_source": "state_context",
-            }
-
-        explicit_interpretation_decision = interpretation.get("skills_needed")
-        if isinstance(explicit_interpretation_decision, bool):
-            explicit_interpretation_reason = str(interpretation.get("skills_needed_reason") or "").strip()
-            return {
-                "skills_needed": explicit_interpretation_decision,
-                "reason": explicit_interpretation_reason or "requirement_interpretation_explicit_skills_needed",
-                "decision_source": "requirement_interpretation",
-            }
-
-        intent = str(
-            interpretation.get("intent") or state.get("requirement_text") or state.get("row_requirement_text") or ""
-        ).strip()
-        control_objective = str(
-            interpretation.get("control_objective")
-            or state.get("requirement_category")
-            or state.get("row_requirement_category")
-            or ""
-        ).strip()
-        evidence_targets = [
-            target.lower() for target in cls._normalize_string_list(interpretation.get("evidence_targets"))
-        ]
-        code_targets = cls._normalize_string_list(interpretation.get("code_targets"))
-        acceptance_signals = cls._normalize_string_list(interpretation.get("acceptance_signals"))
-        skill_objectives = cls._normalize_string_list(interpretation.get("skill_objectives"))
-
-        if not interpretation and not intent and not control_objective:
-            return {
-                "skills_needed": False,
-                "reason": "requirement_interpretation_missing",
-                "decision_source": "fallback",
-            }
-
-        if skill_objectives:
-            return {
-                "skills_needed": True,
-                "reason": "requirement_interpretation_skill_objectives_present",
-                "decision_source": "requirement_interpretation",
-                "skill_objectives": skill_objectives[:4],
-            }
-
-        combined_text = " ".join(
-            part
-            for part in [
-                intent.lower(),
-                control_objective.lower(),
-                " ".join(signal.lower() for signal in acceptance_signals[:4]),
-            ]
-            if part
-        )
-        keyword_list = (
-            "workflow",
-            "orchestrator",
-            "runbook",
-            "playbook",
-            "cli",
-            "command",
-            "tooling",
-            "lsp",
-            "mypy",
-            "pyright",
-            "ruff",
-            "uv",
-            "typer",
-            "confluence",
-            "bitbucket",
-            "grafana",
-            "bpmn",
-            "spec",
-            "automation",
-            "script",
-            "sync",
-            "integration guide",
-            "documentation process",
-        )
-        keyword_hits = [keyword for keyword in keyword_list if keyword in combined_text]
-        docs_targeted = "docs" in evidence_targets
-        code_targeted = "code" in evidence_targets or bool(code_targets)
-        operational_skill_keywords = {
-            "script",
-            "automation",
-            "runbook",
-            "playbook",
-            "cli",
-            "command",
-            "tooling",
-            "confluence",
-            "grafana",
-            "bitbucket",
-            "integration guide",
-            "documentation process",
-        }
-
-        if keyword_hits and (docs_targeted or not code_targeted):
-            return {
-                "skills_needed": True,
-                "reason": f"requirement_interpretation_keyword:{keyword_hits[0]}",
-                "decision_source": "heuristic",
-                "keyword_hits": keyword_hits[:4],
-            }
-        if keyword_hits and any(keyword in operational_skill_keywords for keyword in keyword_hits):
-            return {
-                "skills_needed": True,
-                "reason": f"requirement_interpretation_operational_keyword:{keyword_hits[0]}",
-                "decision_source": "heuristic",
-                "keyword_hits": keyword_hits[:4],
-            }
-
-        return {
-            "skills_needed": False,
-            "reason": "requirement_interpretation_code_first_no_skill_signal",
-            "decision_source": "heuristic",
-            "keyword_hits": keyword_hits[:4],
-            "evidence_targets": evidence_targets[:4],
-            "code_target_count": len(code_targets),
-        }
-
-    @staticmethod
-    def _apply_tool_allowlist(toolsets: list[Any], allowlist: list[str]) -> list[Any]:
-        """Filter toolset-exposed tools to the configured allowlist."""
-        allowed = {name for name in allowlist if isinstance(name, str) and name.strip()}
-        if not allowed:
-            return list(toolsets)
-        filtered: list[Any] = []
-        for toolset in toolsets:
-            tools_map = getattr(toolset, "tools", None)
-            if isinstance(tools_map, dict):
-                for name in list(tools_map):
-                    if name not in allowed:
-                        tools_map.pop(name, None)
-                if not tools_map:
-                    continue
-            filtered.append(toolset)
-        return filtered
-
-    @staticmethod
-    def _is_repetitive_non_progress_tool_usage(
-        telemetry: dict[str, Any] | None,
-        cadence_policy: CadencePolicy | None = None,
-    ) -> bool:
-        return ToolEfficiencyGuard.is_repetitive_non_progress_tool_usage(telemetry, cadence_policy=cadence_policy)
-
-    @staticmethod
-    def _is_invalid_tool_usage_error(error: str) -> bool:
-        return ToolEfficiencyGuard.is_invalid_tool_usage_error(error)
-
-    @staticmethod
-    def _parse_tool_name_from_invalid_tool_error(error: str) -> str | None:
-        return ToolEfficiencyGuard.parse_tool_name_from_invalid_tool_error(error)
-
-    @staticmethod
-    def _build_tool_allowlist_guard_prompt(
-        base_prompt: str,
-        *,
-        allowed_tools: list[str],
-        attempted_tool: str | None,
-    ) -> str:
-        return ToolEfficiencyGuard.build_tool_allowlist_guard_prompt(
-            base_prompt,
-            allowed_tools=allowed_tools,
-            attempted_tool=attempted_tool,
-        )
-
-    @staticmethod
-    def _is_list_directory_churn(
-        telemetry: dict[str, Any] | None,
-        *,
-        min_calls: int = 4,
-        dominance_ratio: float = 0.6,
-    ) -> bool:
-        return ToolEfficiencyGuard.is_list_directory_churn(
-            telemetry,
-            min_calls=min_calls,
-            dominance_ratio=dominance_ratio,
-        )
-
-    @staticmethod
-    def _is_usage_limit_error(exc: Exception) -> bool:
-        """Return True when an exception indicates request/tool budget exhaustion."""
-        message = str(exc).lower()
-        cause = getattr(exc, "__cause__", None)
-        cause_message = str(cause).lower() if cause is not None else ""
-        combined = f"{message}\n{cause_message}"
-        return (
-            "request_limit" in combined
-            or "tool_calls_limit" in combined
-            or "usagelimitexceeded" in combined
-            or "usage limit exceeded" in combined
-        )
-
-    @staticmethod
-    def _is_output_validation_retry_error(exc: Exception) -> bool:
-        """Return True when provider exhausted output validation retries."""
-        message = str(exc).lower()
-        cause = getattr(exc, "__cause__", None)
-        cause_message = str(cause).lower() if cause is not None else ""
-        combined = f"{message}\n{cause_message}"
-        return "output validation" in combined and "exceeded maximum retries" in combined
-
-    @staticmethod
-    def _has_concrete_reasoning_evidence_refs(reasoning: str) -> bool:
-        """Return True when reasoning includes concrete path:line or quoted document evidence refs."""
-        text = str(reasoning or "").strip()
-        if not text:
-            return False
-
-        file_line_ref = re.search(r"(?<!\w)(?:[A-Za-z]:)?[A-Za-z0-9_./\\-]+\.[A-Za-z0-9_]{1,10}:\d+(?!\w)", text)
-        if file_line_ref is not None:
-            return True
-
-        document_title_ref = re.search(
-            r"\b(?:doc|document|confluence)\b[^\n]{0,80}[\"'`][^\"'`\n]{3,120}[\"'`]",
-            text,
-            flags=re.IGNORECASE,
-        )
-        return document_title_ref is not None
-
-    @staticmethod
-    def _build_issue_grounded_reasoning(output: CodeFindings | None) -> str:
-        """Synthesize a grounded reasoning fallback from structured issue outputs.
-
-        Some providers intermittently return empty `reasoning` while still returning
-        grounded `issues`. This fallback keeps strict quality gates meaningful without
-        adding tool/fallback retries.
-        """
-        if output is None:
-            return ""
-        issues = getattr(output, "issues", None)
-        if not isinstance(issues, list) or not issues:
-            return ""
-
-        evidence_bits: list[str] = []
-        for issue in issues[:3]:
-            file_path = str(getattr(issue, "file_path", "") or "").strip() or "unknown"
-            line_number = getattr(issue, "line_number", None)
-            severity = str(getattr(issue, "severity", "") or "medium").lower()
-            description = str(getattr(issue, "description", "") or "Issue detected").strip()
-            ref = f"{file_path}:{line_number}" if line_number else file_path
-            evidence_bits.append(f"{severity} issue at {ref}: {description}.")
-
-        score = float(getattr(output, "score", 0.0) or 0.0)
-        confidence = float(getattr(output, "confidence", 0.0) or 0.0)
-        files_analyzed = int(getattr(output, "files_analyzed", 0) or 0)
-        stack = [str(item).strip() for item in (getattr(output, "tech_stack", []) or []) if str(item).strip()]
-        stack_summary = ", ".join(stack[:4]) if stack else "undetermined stack"
-        return (
-            f"Code analysis found {len(issues)} issue(s) across approximately {max(files_analyzed, len(issues))} file(s) "
-            f"with score {score:.1f}/10 and confidence {confidence:.2f}. "
-            f"Primary evidence: {' '.join(evidence_bits)} "
-            f"Observed stack context: {stack_summary}. "
-            "Residual uncertainty: additional deep-path files may contain further edge cases not covered in this pass."
-        )
-
-    @staticmethod
-    def _has_grounded_issue_paths(output: CodeFindings | None, repo_path: Path) -> bool:
-        """Return True when findings reference at least one concrete file under repo_path.
-
-        This is a defensive quality gate for providers where tool-call telemetry
-        can be inconsistent in some runs. It does not replace tool usage checks;
-        it only allows an explicit, logged degraded pass when findings are still
-        grounded to real repository files.
-        """
-        if output is None:
-            return False
-        issues = getattr(output, "issues", None)
-        if not isinstance(issues, list) or not issues:
-            return False
-
-        repo_root = repo_path.resolve()
-        for issue in issues:
-            file_path = str(getattr(issue, "file_path", "") or "").strip()
-            if not file_path or file_path.lower() == "unknown":
-                continue
-
-            candidate = Path(file_path)
-            if not candidate.is_absolute():
-                candidate = repo_root / candidate
-
-            try:
-                resolved = candidate.resolve()
-            except PATH_RESOLUTION_RECOVERABLE_ERRORS:
-                continue
-
-            if resolved.is_file() and (resolved == repo_root or repo_root in resolved.parents):
-                return True
-        return False
-
-    @staticmethod
-    def _has_productive_agentic_output(
-        output: CodeFindings | None,
-        efficiency_summary: dict[str, Any] | None,
-    ) -> bool:
-        return ToolEfficiencyGuard.has_productive_agentic_output(output, efficiency_summary)
-
-    async def _run_agentic_analysis(
-        self,
-        evidence: EvidenceBundle,
-        profile: dict[str, Any] | None,
-        repo_path: Path,
-        *,
-        runtime: dict[str, Any] | None,
-    ) -> CodeFindings | None:
-        """Run agentic investigation with filesystem + LSP toolsets (Phase 41).
-
-        Attaches bounded, read-only toolsets to the PydanticAI agent and runs
-        a multi-turn investigation loop.
-
-        Args:
-            evidence: EvidenceBundle with git_evidence to analyze.
-            profile: Optional project profile for context.
-            repo_path: Absolute path to the repository.
-
-        Returns:
-            CodeFindings from agentic investigation, or None on failure.
-        """
-        from vds_audit_orchestrator.agents.toolsets.evidence_corpus import (
-            create_evidence_corpus_toolset,
-        )
-        from vds_audit_orchestrator.agents.toolsets.filesystem import create_filesystem_toolset
-        from vds_audit_orchestrator.agents.toolsets.lsp import create_lsp_toolset
-        from vds_audit_orchestrator.agents.toolsets.skills_toolset import get_default_skills_toolset
-        from vds_audit_orchestrator.agents.toolsets.vector_evidence import (
-            create_vector_evidence_toolset,
-            is_vector_evidence_ready,
-        )
-
-        if runtime is None:
-            self.logger.info("agentic_runtime_unavailable")
-            raise RuntimeError("agentic runtime unavailable")
-
-        tool_timeout_sec = int(runtime["tool_timeout_sec"])
-        safe_extensions = tuple(runtime["safe_extensions"])
-        max_read_bytes = int(runtime["max_read_bytes"])
-        max_read_lines = int(runtime.get("max_read_lines", 300))
-        strict_no_fallback = bool(runtime.get("strict_no_fallback", True))
-        non_progress_policy = runtime.get("non_progress_policy", {}) if isinstance(runtime, dict) else {}
-        row_context = runtime.get("row_context") if isinstance(runtime, dict) else None
-        cadence_policy = ToolEfficiencyGuard.create_policy_for_row(
-            row_context if isinstance(row_context, dict) else None,
-            overrides=non_progress_policy if isinstance(non_progress_policy, dict) and non_progress_policy else None,
-        )
-        tool_allowlist = list(runtime.get("tool_allowlist", [])) if isinstance(runtime, dict) else []
-        max_turns = int(runtime["max_turns"])
-        max_tool_calls = int(runtime["max_tool_calls"])
-        strict_cap_max_turns = int(runtime.get("strict_cap_max_turns", 10))
-        strict_cap_max_tool_calls = int(runtime.get("strict_cap_max_tool_calls", 24))
-        local_openai_synthesis_max_turns = int(
-            runtime.get("synthesis_max_turns", runtime.get("local_openai_synthesis_max_turns", 4))
-        )
-        local_openai_synthesis_max_tool_calls = int(
-            runtime.get("synthesis_max_tool_calls", runtime.get("local_openai_synthesis_max_tool_calls", 2))
-        )
-        local_openai_hard_synthesis_max_turns = int(
-            runtime.get("hard_synthesis_max_turns", runtime.get("local_openai_hard_synthesis_max_turns", 2))
-        )
-        local_openai_hard_synthesis_max_tool_calls = int(
-            runtime.get("hard_synthesis_max_tool_calls", runtime.get("local_openai_hard_synthesis_max_tool_calls", 0))
-        )
-        skills_toolset_enabled = bool(runtime.get("skills_toolset_enabled", True))
-        mode_value = getattr(self, "agentic_mode", None)
-        if mode_value is None:
-            mode_value = getattr(self, "_agentic_mode", "")
-        forced_agentic_mode = str(mode_value).strip().lower() == "on"
-
-        local_openai_protocol = self._uses_local_openai_protocol()
-        if (
-            strict_no_fallback
-            and local_openai_protocol
-            and (max_tool_calls > strict_cap_max_tool_calls or max_turns > strict_cap_max_turns)
-        ):
-            self.logger.info(
-                "agentic_budget_adjusted_for_local_openai_protocol",
-                original_max_turns=max_turns,
-                original_max_tool_calls=max_tool_calls,
-                adjusted_max_turns=strict_cap_max_turns,
-                adjusted_max_tool_calls=strict_cap_max_tool_calls,
-                forced_agentic_mode=forced_agentic_mode,
-            )
-            max_turns = min(max_turns, strict_cap_max_turns)
-            max_tool_calls = min(max_tool_calls, strict_cap_max_tool_calls)
-
-        # Build toolsets scoped to repo_path.
-        base_toolsets: list[Any] = []
-        try:
-            base_toolsets = self._build_runtime_toolsets(self._get_runtime_config().llm)
-        except AGENTIC_SETUP_RECOVERABLE_ERRORS as exc:
-            self.logger.warning(
-                "agentic_base_toolsets_failed",
-                error=str(exc),
-                error_type=type(exc).__name__,
-                handler="_run_agentic_analysis._build_runtime_toolsets",
-            )
-        skills_toolset_present = any(
-            isinstance(getattr(toolset, "_vds_skill_metadata", None), list)
-            and len(getattr(toolset, "_vds_skill_metadata", [])) > 0
-            for toolset in base_toolsets
-        )
-        if not skills_toolset_present and skills_toolset_enabled:
-            try:
-                default_skills_toolset = get_default_skills_toolset()
-                base_toolsets.append(default_skills_toolset)
-                self.logger.info("agentic_default_skills_toolset_attached")
-            except AGENTIC_SETUP_RECOVERABLE_ERRORS as exc:
-                self.logger.warning(
-                    "agentic_default_skills_toolset_unavailable",
-                    error=str(exc),
-                    error_type=type(exc).__name__,
-                    handler="_run_agentic_analysis.get_default_skills_toolset",
-                )
-        elif not skills_toolset_enabled:
-            self.logger.info("agentic_skills_toolset_disabled")
-
-        agentic_toolsets: list[Any] = []
-        try:
-            fs_toolset = create_filesystem_toolset(
-                repo_path,
-                safe_extensions=safe_extensions,
-                max_read_bytes=max_read_bytes,
-                max_read_lines=max_read_lines,
-                grep_timeout_sec=tool_timeout_sec,
-            )
-            agentic_toolsets.append(fs_toolset)
-        except AGENTIC_SETUP_RECOVERABLE_ERRORS as exc:
-            self.logger.warning(
-                "filesystem_toolset_creation_failed",
-                error=str(exc),
-                error_type=type(exc).__name__,
-                handler="_run_agentic_analysis.create_filesystem_toolset",
-                repo_path=str(repo_path),
-            )
-
-        try:
-            lsp_toolset = create_lsp_toolset(repo_path, timeout_sec=tool_timeout_sec)
-            agentic_toolsets.append(lsp_toolset)
-        except AGENTIC_SETUP_RECOVERABLE_ERRORS as exc:
-            self.logger.warning(
-                "lsp_toolset_creation_failed",
-                error=str(exc),
-                error_type=type(exc).__name__,
-                handler="_run_agentic_analysis.create_lsp_toolset",
-                repo_path=str(repo_path),
-            )
-
-        if not agentic_toolsets:
-            self.logger.warning("agentic_no_toolsets_available")
-            raise RuntimeError("agentic toolsets unavailable")
-
-        toolsets = list(base_toolsets)
-        toolsets.extend(agentic_toolsets)
-        toolsets = self._prevalidate_skill_toolsets(toolsets)
-        toolsets = self._apply_tool_allowlist(toolsets, tool_allowlist)
-
-        # Build dependencies.
-        deps = AuditDeps.from_evidence_bundle(
-            evidence=evidence,
-            profile=profile,
-            settings=self.settings,
-            evidence_corpus=self._evidence_corpus,
-        )
-
-        state_context = dict(self._state_context) if isinstance(self._state_context, dict) else {}
-
-        postgres_evidence_ready = bool(state_context.get("state_dsn")) and bool(
-            state_context.get("project_key") or state_context.get("project_storage_key")
-        )
-        deps.settings = {
-            **deps.settings,
-            "state_context": state_context,
-            "agentic": {
-                "max_turns": max_turns,
-                "max_tool_calls": max_tool_calls,
-                "tool_timeout_sec": tool_timeout_sec,
-                "safe_extensions": list(safe_extensions),
-                "max_read_bytes": max_read_bytes,
-                "max_read_lines": max_read_lines,
-                "grep_timeout_sec": tool_timeout_sec,
-                "lsp_timeout_sec": tool_timeout_sec,
-            },
-        }
-        if deps.evidence_corpus is not None:
-            try:
-                evidence_toolset = create_evidence_corpus_toolset()
-                toolsets.append(evidence_toolset)
-            except AGENTIC_SETUP_RECOVERABLE_ERRORS as exc:
-                self.logger.warning(
-                    "evidence_corpus_toolset_creation_failed",
-                    error=str(exc),
-                    error_type=type(exc).__name__,
-                    handler="_run_agentic_analysis.create_evidence_corpus_toolset",
-                )
-        available_skill_names = self._collect_available_skill_names(toolsets)
-        skills_available = len(available_skill_names) > 0
-        preloaded_skill_context, preloaded_skill_names = self._build_preloaded_skill_context(
-            toolsets=toolsets,
-            available_skill_names=available_skill_names,
-            max_skills=1 if local_openai_protocol else 2,
-            max_chars_per_skill=500 if local_openai_protocol else 1400,
-        )
-        if preloaded_skill_names:
-            self.logger.info(
-                "agentic_skill_bootstrap_preloaded",
-                preloaded_skill_count=len(preloaded_skill_names),
-                preloaded_skill_names=preloaded_skill_names,
-                preloaded_skill_chars=len(preloaded_skill_context),
-            )
-        self._log_trace_payload(
-            event_name="agentic_trace_runtime_context_assembly",
-            elapsed_sec=0.0,
-            payload={
-                "repo_path": str(repo_path),
-                "runtime": {
-                    "max_turns": max_turns,
-                    "max_tool_calls": max_tool_calls,
-                    "tool_timeout_sec": tool_timeout_sec,
-                    "safe_extension_count": len(safe_extensions),
-                    "max_read_bytes": max_read_bytes,
-                    "max_read_lines": max_read_lines,
-                },
-                "state_context_key_count": len(state_context),
-                "state_context_keys": sorted(str(key) for key in state_context)[:20],
-                "base_toolset_count": len(base_toolsets),
-                "agentic_toolset_count": len(agentic_toolsets),
-                "toolset_types": [type(toolset).__name__ for toolset in toolsets][:16],
-                "skills_available": skills_available,
-                "available_skill_names": available_skill_names[:8],
-                "preloaded_skill_names": preloaded_skill_names,
-                "docs_required": bool(deps.evidence_corpus and deps.evidence_corpus.documents),
-                "postgres_evidence_ready": postgres_evidence_ready,
-            },
-        )
-        docs_required = bool(deps.evidence_corpus and deps.evidence_corpus.documents)
-        vector_docs_required = False
-        try:
-            vector_docs_required = is_vector_evidence_ready(deps=deps)
-            if vector_docs_required:
-                vector_toolset = create_vector_evidence_toolset()
-                toolsets.append(vector_toolset)
-                self.logger.info("vector_evidence_toolset_attached")
-        except AGENTIC_SETUP_RECOVERABLE_ERRORS as exc:
-            self.logger.warning(
-                "vector_evidence_toolset_unavailable",
-                error=str(exc),
-                error_type=type(exc).__name__,
-                handler="_run_agentic_analysis.vector_evidence_setup",
-                repo_path=str(repo_path),
-            )
-            vector_docs_required = False
-        self.logger.info(
-            "agentic_vector_readiness_resolved",
-            vector_docs_required=vector_docs_required,
-            postgres_evidence_ready=postgres_evidence_ready,
-            docs_required=docs_required,
-            state_project_key=(
-                state_context.get("project_storage_key")
-                or state_context.get("project_key")
-                or state_context.get("project_id")
-            ),
-            state_repo_key=(state_context.get("repo_storage_key") or state_context.get("repo_key")),
-        )
-        strict_require_effective_skill_env = self._parse_env_bool("VDS_AUDIT_AGENTIC_STRICT_REQUIRE_EFFECTIVE_SKILL")
-        strict_require_effective_skill = (
-            True if strict_require_effective_skill_env is None else strict_require_effective_skill_env
-        )
-        strict_skip_post_guard_retries = bool(
-            strict_no_fallback and self._parse_env_bool("VDS_AUDIT_AGENTIC_STRICT_SKIP_POST_GUARD_RETRIES")
-        )
-        interpretation = self._extract_requirement_interpretation_from_state_context(state_context)
-        skill_activation_decision = self._resolve_requirement_skill_activation_decision(
-            state_context=state_context,
-        )
-        skills_needed = bool(skill_activation_decision.get("skills_needed"))
-        skills_needed_reason = str(skill_activation_decision.get("reason") or "unspecified")
-        recommended_skill_names: list[str] = []
-        if skills_needed and skills_available and skills_toolset_enabled:
-            recommended_skill_names = self._recommend_skills_for_state_context(
-                state_context=state_context,
-                available_skill_names=available_skill_names,
-                limit=3,
-            )
-            if recommended_skill_names:
-                toolsets, removed_skill_entries = self._focus_skills_in_toolsets(toolsets, recommended_skill_names)
-                if removed_skill_entries > 0:
-                    available_skill_names = self._collect_available_skill_names(toolsets)
-                    skills_available = len(available_skill_names) > 0
-                    preloaded_skill_context, preloaded_skill_names = self._build_preloaded_skill_context(
-                        toolsets=toolsets,
-                        available_skill_names=available_skill_names,
-                        max_skills=1 if local_openai_protocol else 2,
-                        max_chars_per_skill=500 if local_openai_protocol else 1400,
-                        preferred_skill_names=recommended_skill_names,
-                    )
-                    self.logger.info(
-                        "agentic_skill_allowlist_focused",
-                        recommended_skill_names=recommended_skill_names,
-                        removed_skill_entries=removed_skill_entries,
-                        available_skill_count=len(available_skill_names),
-                    )
-                    if preloaded_skill_names:
-                        self.logger.info(
-                            "agentic_skill_bootstrap_preloaded",
-                            preloaded_skill_count=len(preloaded_skill_names),
-                            preloaded_skill_names=preloaded_skill_names,
-                            preloaded_skill_chars=len(preloaded_skill_context),
-                            source="focused",
-                        )
-        advisory_skill_sequence_skipped = bool(
-            skills_needed
-            and skills_available
-            and skills_toolset_enabled
-            and (not strict_require_effective_skill)
-            and self._should_skip_advisory_skill_sequence(
-                state_context=state_context,
-                interpretation=interpretation,
-            )
-        )
-        if advisory_skill_sequence_skipped:
-            toolsets, removed_skill_tool_bindings = self._remove_tool_names(toolsets, self._SKILL_TOOL_NAMES)
-            skills_toolset_enabled = False
-            available_skill_names = self._collect_available_skill_names(toolsets)
-            skills_available = len(available_skill_names) > 0
-            preloaded_skill_context = ""
-            preloaded_skill_names = []
-            self.logger.info(
-                "agentic_advisory_skill_tools_suppressed",
-                removed_tool_bindings=removed_skill_tool_bindings,
-                skills_needed=skills_needed,
-                strict_require_effective_skill=strict_require_effective_skill,
-                skills_available_after_filter=skills_available,
-            )
-        self.logger.info(
-            "agentic_skill_activation_decision",
-            skills_needed=skills_needed,
-            skills_needed_reason=skills_needed_reason,
-            decision_source=str(skill_activation_decision.get("decision_source") or "unknown"),
-            skills_available=skills_available,
-            skills_toolset_enabled=skills_toolset_enabled,
-            strict_no_fallback=strict_no_fallback,
-            advisory_skill_sequence_skipped=advisory_skill_sequence_skipped,
-            recommended_skill_names=recommended_skill_names,
-            requirement_interpretation_present=bool(interpretation),
-        )
-        # Strict mode can optionally enforce an effective skill call, but this is now
-        # configurable so requirement-driven runs can avoid low-value skill churn.
-        skills_required = bool(
-            strict_no_fallback
-            and skills_available
-            and skills_toolset_enabled
-            and strict_require_effective_skill
-            and skills_needed
-        )
-
-        user_prompt = self._build_agentic_investigation_prompt(
-            evidence=evidence,
-            profile=profile,
-            repo_path=repo_path,
-            evidence_corpus=deps.evidence_corpus,
-            skills_available=skills_available,
-            available_skill_names=available_skill_names,
-            vector_docs_required=vector_docs_required,
-            preloaded_skill_context=preloaded_skill_context,
-            postgres_evidence_ready=postgres_evidence_ready,
-            compact_mode=local_openai_protocol,
-            strict_skill_required=skills_required,
-            skills_needed=skills_needed,
-            skills_needed_reason=skills_needed_reason,
-        )
-
-        self.logger.info(
-            "agentic_analysis_started",
-            repo_path=str(repo_path),
-            toolset_count=len(toolsets),
-            base_toolsets=len(base_toolsets),
-            agentic_toolsets=len(agentic_toolsets),
-            max_turns=max_turns,
-            max_tool_calls=max_tool_calls,
-            tool_timeout_sec=tool_timeout_sec,
-        )
-        system_prompt = (
-            AGENTIC_CODE_ANALYSIS_SYSTEM_PROMPT_OLLAMA_COMPACT
-            if local_openai_protocol
-            else AGENTIC_CODE_ANALYSIS_SYSTEM_PROMPT
-        )
-
-        start_time = time.monotonic()
-        if local_openai_protocol and strict_no_fallback:
-            retry_turn_cap = max(max_turns + 2, int(max_turns * 1.25))
-            retry_tool_call_cap = max(max_tool_calls + 6, int(max_tool_calls * 1.25))
-        else:
-            retry_turn_cap = max(max_turns + 6, int(max_turns * 1.5))
-            retry_tool_call_cap = max(max_tool_calls + 24, int(max_tool_calls * 1.5))
-        aggregate_retry_telemetry: dict[str, Any] = {}
-        corrective_budget_initial = max(
-            0,
-            int(
-                runtime.get(
-                    "corrective_budget_remaining",
-                    runtime.get("corrective_budget_initial", 5),
-                )
-            ),
-        )
-        corrective_budget_remaining = corrective_budget_initial
-        corrective_budget_events: list[dict[str, Any]] = []
-        corrective_budget_exhausted = corrective_budget_remaining <= 0
-        local_openai_hard_synthesis_used = False
-        strict_budget_hard_synthesis_used = False
-        hard_synthesis_quality_retry_used = False
-
-        def _sync_corrective_budget_telemetry(target: dict[str, Any]) -> None:
-            if not isinstance(target, dict):
-                return
-            target["corrective_budget_initial"] = corrective_budget_initial
-            target["corrective_budget_remaining"] = corrective_budget_remaining
-            target["corrective_budget_consumed"] = max(0, corrective_budget_initial - corrective_budget_remaining)
-            target["corrective_budget_exhausted"] = bool(corrective_budget_exhausted)
-            target["corrective_budget_events"] = [dict(entry) for entry in corrective_budget_events]
-
-        def _record_corrective_budget_event(
-            event_name: str,
-            *,
-            guard_class: str | None = None,
-            reason: str | None = None,
-        ) -> None:
-            entry: dict[str, Any] = {
-                "event": str(event_name),
-                "remaining": corrective_budget_remaining,
-                "consumed": max(0, corrective_budget_initial - corrective_budget_remaining),
-            }
-            if guard_class:
-                entry["guard_class"] = str(guard_class)
-            if reason:
-                entry["reason"] = str(reason)
-            corrective_budget_events.append(entry)
-            _sync_corrective_budget_telemetry(aggregate_retry_telemetry)
-
-        def _consume_corrective_budget(
-            *,
-            guard_class: str,
-            reason: str,
-        ) -> bool:
-            nonlocal corrective_budget_remaining
-            nonlocal corrective_budget_exhausted
-            if corrective_budget_remaining <= 0:
-                corrective_budget_exhausted = True
-                _record_corrective_budget_event(
-                    "exhausted",
-                    guard_class=guard_class,
-                    reason=reason,
-                )
-                self.logger.warning(
-                    "agentic_corrective_budget_exhausted",
-                    guard_class=guard_class,
-                    reason=reason,
-                    corrective_budget_initial=corrective_budget_initial,
-                    corrective_budget_remaining=corrective_budget_remaining,
-                    corrective_budget_consumed=max(0, corrective_budget_initial - corrective_budget_remaining),
-                )
-                return False
-            corrective_budget_remaining = max(0, corrective_budget_remaining - 1)
-            corrective_budget_exhausted = corrective_budget_remaining <= 0
-            _record_corrective_budget_event(
-                "consumed",
-                guard_class=guard_class,
-                reason=reason,
-            )
-            self.logger.info(
-                "agentic_corrective_budget_consumed",
-                guard_class=guard_class,
-                reason=reason,
-                corrective_budget_initial=corrective_budget_initial,
-                corrective_budget_remaining=corrective_budget_remaining,
-                corrective_budget_consumed=max(0, corrective_budget_initial - corrective_budget_remaining),
-                corrective_budget_exhausted=corrective_budget_exhausted,
-            )
-            if corrective_budget_exhausted:
-                _record_corrective_budget_event(
-                    "exhausted",
-                    guard_class=guard_class,
-                    reason=reason,
-                )
-                self.logger.warning(
-                    "agentic_corrective_budget_exhausted",
-                    guard_class=guard_class,
-                    reason=reason,
-                    corrective_budget_initial=corrective_budget_initial,
-                    corrective_budget_remaining=corrective_budget_remaining,
-                    corrective_budget_consumed=max(0, corrective_budget_initial - corrective_budget_remaining),
-                )
-            return True
-
-        def _build_corrective_budget_degraded_output(
-            *,
-            guard_class: str,
-            reason: str,
-            output_hint: CodeFindings | None,
-            telemetry_hint: dict[str, Any] | None,
-        ) -> CodeFindings:
-            tool_count_by_name = (
-                telemetry_hint.get("event_tool_count_by_name") if isinstance(telemetry_hint, dict) else {}
-            )
-            read_file_calls = (
-                int(tool_count_by_name.get("read_file", 0) or 0) if isinstance(tool_count_by_name, dict) else 0
-            )
-            base_reasoning = str(getattr(output_hint, "reasoning", "") or "").strip()
-            bounded_reasoning = base_reasoning[:320]
-            score_hint = float(getattr(output_hint, "score", 0.0) or 0.0) if output_hint is not None else 0.0
-            confidence_hint = float(getattr(output_hint, "confidence", 0.4) or 0.4) if output_hint is not None else 0.4
-            files_analyzed_hint = int(getattr(output_hint, "files_analyzed", 0) or 0) if output_hint is not None else 0
-            files_analyzed = max(files_analyzed_hint, read_file_calls, 0)
-            issues = list(getattr(output_hint, "issues", []) or [])[:10] if output_hint is not None else []
-            patterns = list(getattr(output_hint, "patterns", []) or [])[:10] if output_hint is not None else []
-            tech_stack = (
-                [str(item) for item in (getattr(output_hint, "tech_stack", []) or []) if str(item)][:10]
-                if output_hint is not None
-                else []
-            )
-            reasoning = (
-                "Degraded finalize: corrective budget exhausted; returning bounded grounded partial output. "
-                f"guard={guard_class}; reason={reason}."
-            )
-            if bounded_reasoning:
-                reasoning = f"{reasoning} Prior synthesis: {bounded_reasoning}"
-            return CodeFindings(
-                score=max(0.0, min(score_hint, 10.0)),
-                confidence=max(0.0, min(confidence_hint, 1.0)),
-                issues=issues,
-                patterns=patterns,
-                reasoning=reasoning,
-                files_analyzed=files_analyzed,
-                tech_stack=tech_stack,
-            )
-
-        def _degraded_finalize_for_corrective_budget(
-            *,
-            guard_class: str,
-            reason: str,
-            output_hint: CodeFindings | None,
-            telemetry_hint: dict[str, Any] | None,
-        ) -> CodeFindings:
-            _record_corrective_budget_event(
-                "degraded_finalize",
-                guard_class=guard_class,
-                reason=reason,
-            )
-            degraded_output = _build_corrective_budget_degraded_output(
-                guard_class=guard_class,
-                reason=reason,
-                output_hint=output_hint,
-                telemetry_hint=telemetry_hint,
-            )
-            self.logger.warning(
-                "agentic_corrective_budget_degraded_finalize",
-                guard_class=guard_class,
-                reason=reason,
-                corrective_budget_initial=corrective_budget_initial,
-                corrective_budget_remaining=corrective_budget_remaining,
-                corrective_budget_consumed=max(0, corrective_budget_initial - corrective_budget_remaining),
-                corrective_budget_exhausted=corrective_budget_exhausted,
-                observed_tool_names=(
-                    telemetry_hint.get("event_tool_names") if isinstance(telemetry_hint, dict) else None
-                ),
-            )
-            _sync_corrective_budget_telemetry(aggregate_retry_telemetry)
-            if isinstance(aggregate_retry_telemetry, dict):
-                self._last_agent_run_telemetry = dict(aggregate_retry_telemetry)
-            return degraded_output
-
-        _record_corrective_budget_event("initialized")
-        self.logger.info(
-            "agentic_corrective_budget_initialized",
-            corrective_budget_initial=corrective_budget_initial,
-            corrective_budget_remaining=corrective_budget_remaining,
-            corrective_budget_consumed=0,
-            corrective_budget_exhausted=corrective_budget_exhausted,
-        )
-
-        def _update_cadence_from_telemetry(
-            telemetry_snapshot: dict[str, Any] | None,
-            *,
-            row_index: int | None = None,
-        ) -> None:
-            """Update cadence_policy from aggregate telemetry tool counts (FR-120)."""
-            nonlocal cadence_policy
-            if not isinstance(telemetry_snapshot, dict):
-                return
-            tool_count_by_name = telemetry_snapshot.get("event_tool_count_by_name")
-            if not isinstance(tool_count_by_name, dict) or not tool_count_by_name:
-                return
-            for t_name, count in tool_count_by_name.items():
-                if not isinstance(t_name, str) or t_name == "final_result":
-                    continue
-                result_useful = int(count or 0) > 0
-                previous_ceiling = cadence_policy.tool_family_ceilings.get(t_name, cadence_policy.base_tool_budget)
-                cadence_policy = ToolEfficiencyGuard.update_tool_signal(cadence_policy, t_name, result_useful)
-                new_ceiling = cadence_policy.tool_family_ceilings.get(t_name, cadence_policy.base_tool_budget)
-                if new_ceiling != previous_ceiling:
-                    cadence_event = ToolEfficiencyGuard.build_cadence_telemetry(
-                        cadence_policy,
-                        t_name,
-                        previous_ceiling,
-                        "snr_adjustment",
-                        row_index=row_index,
-                    )
-                    cadence_event_name = str(cadence_event.get("event") or "cadence_ceiling_adjusted")
-                    cadence_event_payload = {k: v for k, v in cadence_event.items() if k != "event"}
-                    self.logger.info(
-                        cadence_event_name,
-                        **cadence_event_payload,
-                    )
-
-        async def _invoke_agentic(
-            user_prompt_payload: str,
-            turns: int,
-            tool_calls_limit: int,
-            *,
-            active_toolsets: list[Any],
-        ) -> CodeFindings:
-            nonlocal skills_available
-            nonlocal skills_required
-            nonlocal aggregate_retry_telemetry
-            nonlocal local_openai_hard_synthesis_used
-            nonlocal strict_budget_hard_synthesis_used
-            nonlocal cadence_policy
-
-            current_turns = turns
-            current_tool_calls = tool_calls_limit
-            current_toolsets = list(active_toolsets)
-            current_prompt = user_prompt_payload
-            used_invalid_tool_args_retry = False
-            used_invalid_tool_usage_retry = False
-            used_missing_skill_script_retry = False
-            used_missing_skill_resource_retry = False
-            used_missing_skill_name_retry = False
-            used_request_limit_synthesis_retry = False
-            used_stall_synthesis_retry = False
-            used_strict_budget_synthesis_retry = False
-            used_strict_budget_hard_synthesis_retry = False
-            used_non_progress_final_retry = False
-            used_list_directory_synthesis_retry = False
-            used_output_validation_synthesis_retry = False
-            budget_retry_attempts = 0
-            synthesis_tool_allowlist = [
-                "read_file",
-                "read_evidence_document",
-                "list_evidence_documents",
-                "search_evidence",
-                "search_evidence_vector",
-                "search_code_vector",
-            ]
-
-            def _to_synthesis_toolset(active_toolsets: list[Any]) -> list[Any]:
-                """Keep a tiny read-focused toolset to avoid zero-tool deadlocks."""
-                reduced = self._apply_tool_allowlist(list(active_toolsets), synthesis_tool_allowlist)
-                return reduced if reduced else []
-
-            def _synthesis_retry_caps(has_toolsets: bool) -> tuple[int, int]:
-                if local_openai_protocol and strict_no_fallback:
-                    turns_cap = max(1, local_openai_synthesis_max_turns)
-                    if has_toolsets:
-                        tools_cap = max(0, local_openai_synthesis_max_tool_calls)
-                    else:
-                        tools_cap = max(0, min(local_openai_synthesis_max_tool_calls, 1))
-                    return turns_cap, tools_cap
-                return 4, (8 if has_toolsets else 4)
-
-            # Local OpenAI-compatible runtimes can repeat low-signal tool loops.
-            # Keep retries bounded more aggressively to avoid long runaway cycles.
-            if strict_no_fallback:
-                max_budget_retry_attempts = 0
-            elif local_openai_protocol:
-                max_budget_retry_attempts = 1
-            else:
-                max_budget_retry_attempts = 2
-
-            while True:
-                try:
-                    output = await self._run_pydantic_agent(
-                        system_prompt=system_prompt,
-                        user_prompt=current_prompt,
-                        result_type=CodeFindings,
-                        complexity="standard",
-                        deps=deps,
-                        toolsets=current_toolsets,
-                        max_turns=current_turns,
-                        max_tool_calls=current_tool_calls,
-                        pre_retry_telemetry=aggregate_retry_telemetry
-                        if isinstance(aggregate_retry_telemetry, dict) and aggregate_retry_telemetry
-                        else None,
-                    )
-                    latest_telemetry = getattr(self, "_last_agent_run_telemetry", {})
-                    if isinstance(latest_telemetry, dict):
-                        aggregate_retry_telemetry = self._merge_retry_telemetry(
-                            aggregate_retry_telemetry,
-                            latest_telemetry,
-                        )
-                        _sync_corrective_budget_telemetry(aggregate_retry_telemetry)
-                        _update_cadence_from_telemetry(latest_telemetry)
-                    return output
-                except Exception as exc:
-                    latest_telemetry = getattr(self, "_last_agent_run_telemetry", {})
-                    if isinstance(latest_telemetry, dict):
-                        aggregate_retry_telemetry = self._merge_retry_telemetry(
-                            aggregate_retry_telemetry, latest_telemetry
-                        )
-                        _sync_corrective_budget_telemetry(aggregate_retry_telemetry)
-                        _update_cadence_from_telemetry(latest_telemetry)
-                    message = str(exc).lower()
-                    invalid_tool_args = "invalid tool call arguments" in message
-                    if invalid_tool_args and not used_invalid_tool_args_retry:
-                        # Retry once with stricter instructions but keep skill toolsets enabled.
-                        self.logger.warning(
-                            "agentic_invalid_tool_args_retry_with_skills",
-                            error=str(exc),
-                            toolsets=len(current_toolsets),
-                        )
-                        used_invalid_tool_args_retry = True
-                        current_prompt = (
-                            user_prompt_payload
-                            + "\n\nTOOL ARGUMENT GUARD:\n"
-                            + "- Call one tool per turn.\n"
-                            + "- Provide a valid JSON object for tool args.\n"
-                            + "- Keep skill tools enabled and use them when relevant."
-                        )
-                        continue
-
-                    invalid_tool_usage = self._is_invalid_tool_usage_error(message)
-                    if invalid_tool_usage and not used_invalid_tool_usage_retry:
-                        attempted_tool = self._parse_tool_name_from_invalid_tool_error(str(exc))
-                        self.logger.warning(
-                            "agentic_invalid_tool_usage_allowlist",
-                            error=str(exc),
-                            attempted_tool=attempted_tool,
-                            allowed_tools=tool_allowlist,
-                        )
-                        used_invalid_tool_usage_retry = True
-                        current_prompt = self._build_tool_allowlist_guard_prompt(
-                            user_prompt_payload,
-                            allowed_tools=tool_allowlist,
-                            attempted_tool=attempted_tool,
-                        )
-                        continue
-                    if invalid_tool_usage:
-                        attempted_tool = self._parse_tool_name_from_invalid_tool_error(str(exc))
-                        raise RuntimeError(
-                            "agentic tool policy violation: invalid tool usage "
-                            f"(attempted={attempted_tool or 'unknown'}, allowlist={tool_allowlist})"
-                        ) from exc
-
-                    missing_skill_script = "script '" in message and "not found in skill" in message
-                    if missing_skill_script and not used_missing_skill_script_retry:
-                        failing_skill = self._parse_skill_name_from_error(str(exc))
-                        updated_toolsets, removed_count = self._drop_skill_from_toolsets(
-                            current_toolsets,
-                            failing_skill or "",
-                        )
-                        self.logger.warning(
-                            "agentic_missing_skill_script_retry_degraded_skill",
-                            error=str(exc),
-                            failing_skill=failing_skill,
-                            removed_toolsets=removed_count,
-                        )
-                        used_missing_skill_script_retry = True
-                        current_toolsets = updated_toolsets
-                        if failing_skill:
-                            available_skill_names[:] = [name for name in available_skill_names if name != failing_skill]
-                            skills_available = len(available_skill_names) > 0
-                            if not skills_available:
-                                skills_required = False
-                        current_prompt = (
-                            user_prompt_payload
-                            + "\n\nSKILL SCRIPT GUARD:\n"
-                            + "- Do not call run_skill_script unless the selected skill explicitly lists scripts.\n"
-                            + "- Use load_skill and read_skill_resource for skills that have no scripts.\n"
-                            + "- Continue with filesystem/LSP tools for repository evidence."
-                        )
-                        continue
-
-                    missing_skill_resource = "resource '" in message and "not found in skill" in message
-                    if missing_skill_resource and not used_missing_skill_resource_retry:
-                        failing_skill = self._parse_skill_name_from_error(str(exc))
-                        updated_toolsets, removed_count = self._drop_skill_from_toolsets(
-                            current_toolsets,
-                            failing_skill or "",
-                        )
-                        self.logger.warning(
-                            "agentic_missing_skill_resource_retry_degraded_skill",
-                            error=str(exc),
-                            failing_skill=failing_skill,
-                            removed_toolsets=removed_count,
-                        )
-                        used_missing_skill_resource_retry = True
-                        current_toolsets = updated_toolsets
-                        if failing_skill:
-                            available_skill_names[:] = [name for name in available_skill_names if name != failing_skill]
-                        skills_available = len(available_skill_names) > 0
-                        if not available_skill_names:
-                            skills_required = False
-                        current_prompt = (
-                            user_prompt_payload
-                            + "\n\nSKILL RESOURCE GUARD:\n"
-                            + "- A referenced skill/resource is missing; skip that skill and continue.\n"
-                            + "- Use filesystem/LSP tools for repository evidence.\n"
-                            + "- Call load_skill first, then call read_skill_resource only for resource_name values listed in load_skill output."
-                        )
-                        continue
-
-                    missing_skill_name = "skill '" in message and "not found. available:" in message
-                    if missing_skill_name and not used_missing_skill_name_retry:
-                        failing_skill = self._parse_skill_name_from_error(str(exc))
-                        updated_toolsets, removed_count = self._drop_skill_from_toolsets(
-                            current_toolsets,
-                            failing_skill or "",
-                        )
-                        self.logger.warning(
-                            "agentic_missing_skill_name_retry_degraded_skill",
-                            error=str(exc),
-                            failing_skill=failing_skill,
-                            removed_toolsets=removed_count,
-                        )
-                        used_missing_skill_name_retry = True
-                        current_toolsets = updated_toolsets
-                        if failing_skill:
-                            available_skill_names[:] = [name for name in available_skill_names if name != failing_skill]
-                        skills_available = len(available_skill_names) > 0
-                        if not available_skill_names:
-                            skills_required = False
-                        current_prompt = (
-                            user_prompt_payload
-                            + "\n\nSKILL AVAILABILITY GUARD:\n"
-                            + f"- Available skills now: {', '.join(available_skill_names) if available_skill_names else 'none'}.\n"
-                            + "- Do not call load_skill for skills outside this list.\n"
-                            + "- Continue with filesystem/LSP tools if a skill is unavailable."
-                        )
-                        continue
-
-                    stall_after_tools = "stalled after tool activity" in message
-                    if stall_after_tools and not used_stall_synthesis_retry:
-                        self.logger.warning(
-                            "agentic_stall_synthesis_retry",
-                            error=str(exc),
-                            max_turns=current_turns,
-                            max_tool_calls=current_tool_calls,
-                            observed_tool_names=(
-                                aggregate_retry_telemetry.get("event_tool_names")
-                                if isinstance(aggregate_retry_telemetry, dict)
-                                else None
-                            ),
-                        )
-                        used_stall_synthesis_retry = True
-                        current_prompt = (
-                            user_prompt_payload
-                            + "\n\nSTALL RECOVERY - FINAL SYNTHESIS MODE:\n"
-                            + "- STOP calling tools.\n"
-                            + "- Use at most 1-2 focused read/list calls if essential, then finalize.\n"
-                            + "- Do not run broad grep/list loops.\n"
-                            + "- Return final CodeFindings JSON now."
-                        )
-                        current_toolsets = _to_synthesis_toolset(current_toolsets)
-                        synthesis_turns, synthesis_tools = _synthesis_retry_caps(bool(current_toolsets))
-                        current_tool_calls = synthesis_tools
-                        current_turns = min(current_turns, synthesis_turns)
-                        continue
-
-                    if self._is_output_validation_retry_error(exc) and not used_output_validation_synthesis_retry:
-                        self.logger.warning(
-                            "agentic_output_validation_hard_synthesis_retry",
-                            error=str(exc),
-                            max_turns=current_turns,
-                            max_tool_calls=current_tool_calls,
-                        )
-                        used_output_validation_synthesis_retry = True
-                        current_prompt = (
-                            user_prompt_payload
-                            + "\n\nOUTPUT VALIDATION RECOVERY - HARD SYNTHESIS MODE:\n"
-                            + "- DO NOT call tools.\n"
-                            + "- Return only final CodeFindings JSON matching the schema.\n"
-                            + "- Use evidence already collected in prior turns.\n"
-                        )
-                        current_toolsets = []
-                        # Keep a tiny allowance to avoid tool_calls_limit=0 deadlocks
-                        # when providers emit one residual internal tool/final_result call.
-                        current_tool_calls = max(1, local_openai_hard_synthesis_max_tool_calls)
-                        current_turns = min(current_turns, max(2, local_openai_hard_synthesis_max_turns))
-                        continue
-
-                    if not self._is_usage_limit_error(exc):
-                        raise
-
-                    telemetry_loop = (
-                        latest_telemetry
-                        if isinstance(latest_telemetry, dict) and latest_telemetry
-                        else (
-                            aggregate_retry_telemetry
-                            if isinstance(aggregate_retry_telemetry, dict) and aggregate_retry_telemetry
-                            else None
-                        )
-                    )
-                    if "tool_calls_limit" in message and self._is_list_directory_churn(telemetry_loop):
-                        tool_count_by_name = (
-                            telemetry_loop.get("event_tool_count_by_name") if isinstance(telemetry_loop, dict) else {}
-                        )
-                        list_directory_calls = (
-                            int(tool_count_by_name.get("list_directory", 0) or 0)
-                            if isinstance(tool_count_by_name, dict)
-                            else 0
-                        )
-                        self.logger.warning(
-                            "agentic_list_directory_loop_detected",
-                            error=str(exc),
-                            list_directory_calls=list_directory_calls,
-                            tool_calls=current_tool_calls,
-                        )
-                        if not used_list_directory_synthesis_retry:
-                            used_list_directory_synthesis_retry = True
-                            current_prompt = (
-                                user_prompt_payload
-                                + "\n\nLIST-DIRECTORY CHURN GUARD - FINAL SYNTHESIS MODE:\n"
-                                + "- STOP broad list_directory exploration.\n"
-                                + "- Use at most one targeted read_file/search call if essential.\n"
-                                + "- Prefer synthesizing from already collected evidence.\n"
-                                + "- Return final CodeFindings JSON now."
-                            )
-                            current_toolsets = _to_synthesis_toolset(current_toolsets)
-                            synthesis_turns, synthesis_tools = _synthesis_retry_caps(bool(current_toolsets))
-                            current_tool_calls = synthesis_tools
-                            current_turns = min(current_turns, synthesis_turns)
-                            continue
-                        raise RuntimeError(
-                            "agentic list_directory churn detected: aborting before tool_calls_limit repeats"
-                        ) from exc
-
-                    if self._is_repetitive_non_progress_tool_usage(
-                        aggregate_retry_telemetry if isinstance(aggregate_retry_telemetry, dict) else None,
-                        cadence_policy=cadence_policy,
-                    ):
-                        if not used_request_limit_synthesis_retry and budget_retry_attempts == 0:
-                            if not _consume_corrective_budget(
-                                guard_class="non_progress",
-                                reason="request_limit_synthesis_retry",
-                            ):
-                                return _degraded_finalize_for_corrective_budget(
-                                    guard_class="non_progress",
-                                    reason="request_limit_synthesis_retry_budget_exhausted",
-                                    output_hint=None,
-                                    telemetry_hint=(
-                                        aggregate_retry_telemetry
-                                        if isinstance(aggregate_retry_telemetry, dict)
-                                        else None
-                                    ),
-                                )
-                            self.logger.warning(
-                                "agentic_request_limit_synthesis_retry",
-                                error=str(exc),
-                                max_turns=current_turns,
-                                max_tool_calls=current_tool_calls,
-                                observed_tool_names=(
-                                    aggregate_retry_telemetry.get("event_tool_names")
-                                    if isinstance(aggregate_retry_telemetry, dict)
-                                    else None
-                                ),
-                            )
-                            used_request_limit_synthesis_retry = True
-                            current_prompt = (
-                                user_prompt_payload
-                                + "\n\nFINAL SYNTHESIS MODE:\n"
-                                + "- STOP calling tools.\n"
-                                + "- Use at most 1-2 focused read/list calls if essential, then finalize.\n"
-                                + "- Do not run broad grep/list loops.\n"
-                                + "- Return the final CodeFindings JSON now."
-                            )
-                            current_toolsets = _to_synthesis_toolset(current_toolsets)
-                            synthesis_turns, synthesis_tools = _synthesis_retry_caps(bool(current_toolsets))
-                            current_tool_calls = synthesis_tools
-                            current_turns = min(current_turns, synthesis_turns)
-                            continue
-                        self.logger.warning(
-                            "agentic_request_limit_non_progress_abort",
-                            error=str(exc),
-                            max_turns=current_turns,
-                            max_tool_calls=current_tool_calls,
-                            observed_tool_names=(
-                                aggregate_retry_telemetry.get("event_tool_names")
-                                if isinstance(aggregate_retry_telemetry, dict)
-                                else None
-                            ),
-                        )
-                        if not used_non_progress_final_retry:
-                            if not _consume_corrective_budget(
-                                guard_class="non_progress",
-                                reason="request_limit_non_progress_final_retry",
-                            ):
-                                return _degraded_finalize_for_corrective_budget(
-                                    guard_class="non_progress",
-                                    reason="request_limit_non_progress_final_retry_budget_exhausted",
-                                    output_hint=None,
-                                    telemetry_hint=(
-                                        aggregate_retry_telemetry
-                                        if isinstance(aggregate_retry_telemetry, dict)
-                                        else None
-                                    ),
-                                )
-                            used_non_progress_final_retry = True
-                            current_prompt = (
-                                user_prompt_payload
-                                + "\n\nNON-PROGRESS EXIT GUARD - FINAL ANSWER MODE:\n"
-                                + "- STOP calling tools immediately.\n"
-                                + "- Synthesize from already collected evidence only.\n"
-                                + "- Return final CodeFindings JSON now."
-                            )
-                            current_toolsets = _to_synthesis_toolset(current_toolsets)
-                            # Keep a tiny read-only budget to avoid tool_calls_limit=0 deadlocks
-                            # when providers emit one residual tool call before final synthesis.
-                            synthesis_turns, synthesis_tools = _synthesis_retry_caps(bool(current_toolsets))
-                            current_tool_calls = synthesis_tools
-                            current_turns = min(current_turns, synthesis_turns)
-                            continue
-                        if strict_skip_post_guard_retries:
-                            tool_count_by_name = (
-                                aggregate_retry_telemetry.get("event_tool_count_by_name")
-                                if isinstance(aggregate_retry_telemetry, dict)
-                                else {}
-                            )
-                            read_file_calls = (
-                                int(tool_count_by_name.get("read_file", 0) or 0)
-                                if isinstance(tool_count_by_name, dict)
-                                else 0
-                            )
-                            observed_tool_names = (
-                                aggregate_retry_telemetry.get("event_tool_names")
-                                if isinstance(aggregate_retry_telemetry, dict)
-                                else []
-                            )
-                            self.logger.warning(
-                                "agentic_request_limit_non_progress_degraded_skip_retry",
-                                error=str(exc),
-                                max_turns=current_turns,
-                                max_tool_calls=current_tool_calls,
-                                observed_tool_names=observed_tool_names,
-                                observed_read_file_calls=read_file_calls,
-                                strict_no_fallback=strict_no_fallback,
-                            )
-                            return CodeFindings(
-                                score=0.0,
-                                confidence=0.4,
-                                issues=[],
-                                patterns=[],
-                                reasoning=(
-                                    "Degraded finalize: strict non-progress/request-limit guard triggered; "
-                                    "returning bounded partial synthesis without additional retries."
-                                ),
-                                files_analyzed=max(0, read_file_calls),
-                                tech_stack=[],
-                            )
-                        if corrective_budget_remaining <= 0:
-                            return _degraded_finalize_for_corrective_budget(
-                                guard_class="non_progress",
-                                reason="request_limit_non_progress_abort_budget_exhausted",
-                                output_hint=None,
-                                telemetry_hint=(
-                                    aggregate_retry_telemetry if isinstance(aggregate_retry_telemetry, dict) else None
-                                ),
-                            )
-                        raise RuntimeError(
-                            "agentic non-progress detected before request-limit retry: repetitive tool usage"
-                        ) from exc
-
-                    if strict_no_fallback and local_openai_protocol and not used_strict_budget_synthesis_retry:
-                        self.logger.warning(
-                            "agentic_strict_budget_synthesis_retry",
-                            error=str(exc),
-                            max_turns=current_turns,
-                            max_tool_calls=current_tool_calls,
-                        )
-                        used_strict_budget_synthesis_retry = True
-                        current_prompt = (
-                            user_prompt_payload
-                            + "\n\nSTRICT BUDGET EXHAUSTED - FINAL SYNTHESIS MODE:\n"
-                            + "- STOP calling tools.\n"
-                            + "- Use at most 1-2 focused read/list calls if essential, then finalize.\n"
-                            + "- Do not run broad grep/list loops.\n"
-                            + "- Return final CodeFindings JSON now."
-                        )
-                        current_toolsets = _to_synthesis_toolset(current_toolsets)
-                        synthesis_turns, synthesis_tools = _synthesis_retry_caps(bool(current_toolsets))
-                        current_tool_calls = synthesis_tools
-                        current_turns = min(current_turns, synthesis_turns)
-                        continue
-
-                    if strict_no_fallback:
-                        if local_openai_protocol:
-                            # Local OpenAI providers can keep issuing repetitive tool calls even
-                            # after synthesis mode prompts. Avoid expanding budgets; force one
-                            # hard synthesis retry with tools disabled, then fail fast.
-                            if not used_non_progress_final_retry:
-                                used_non_progress_final_retry = True
-                                local_openai_hard_synthesis_used = True
-                                strict_budget_hard_synthesis_used = True
-                                self.logger.warning(
-                                    "agentic_local_openai_hard_synthesis_retry",
-                                    error=str(exc),
-                                    max_turns=current_turns,
-                                    max_tool_calls=current_tool_calls,
-                                )
-                                current_prompt = (
-                                    user_prompt_payload
-                                    + "\n\nLOCAL OPENAI HARD SYNTHESIS MODE:\n"
-                                    + "- DO NOT call any tools.\n"
-                                    + "- Synthesize strictly from prior tool outputs.\n"
-                                    + "- Return final CodeFindings JSON now.\n"
-                                )
-                                current_toolsets = []
-                                current_tool_calls = max(1, local_openai_hard_synthesis_max_tool_calls)
-                                current_turns = min(current_turns, max(1, local_openai_hard_synthesis_max_turns))
-                                continue
-                            self.logger.warning(
-                                "agentic_local_openai_budget_retry_disabled_fail_fast",
-                                error=str(exc),
-                                max_turns=current_turns,
-                                max_tool_calls=current_tool_calls,
-                            )
-                            raise
-                        # Non-local strict mode: avoid budget re-expansion after synthesis.
-                        # Force one hard synthesis retry with no tools, then fail fast.
-                        if not used_strict_budget_hard_synthesis_retry:
-                            used_strict_budget_hard_synthesis_retry = True
-                            strict_budget_hard_synthesis_used = True
-                            self.logger.warning(
-                                "agentic_strict_budget_hard_synthesis_retry",
-                                error=str(exc),
-                                max_turns=current_turns,
-                                max_tool_calls=current_tool_calls,
-                            )
-                            current_prompt = (
-                                user_prompt_payload
-                                + "\n\nSTRICT BUDGET EXHAUSTED - HARD SYNTHESIS MODE:\n"
-                                + "- DO NOT call tools.\n"
-                                + "- Synthesize strictly from prior tool outputs.\n"
-                                + "- Return final CodeFindings JSON now.\n"
-                            )
-                            current_toolsets = []
-                            # Keep a tiny allowance to avoid tool_calls_limit=0 deadlocks
-                            # when providers emit one residual internal tool/final_result call.
-                            current_tool_calls = max(1, local_openai_hard_synthesis_max_tool_calls)
-                            current_turns = min(current_turns, max(1, local_openai_hard_synthesis_max_turns))
-                            continue
-                        self.logger.warning(
-                            "agentic_budget_retry_disabled_fail_fast",
-                            error=str(exc),
-                            max_turns=current_turns,
-                            max_tool_calls=current_tool_calls,
-                        )
-                        raise
-
-                    if budget_retry_attempts >= max_budget_retry_attempts:
-                        self.logger.warning(
-                            "agentic_budget_retry_exhausted",
-                            error=str(exc),
-                            max_turns=current_turns,
-                            max_tool_calls=current_tool_calls,
-                            retry_attempts=budget_retry_attempts,
-                        )
-                        raise
-
-                    retry_turns = min(current_turns + 2, retry_turn_cap)
-                    retry_tool_calls = min(current_tool_calls + 6, retry_tool_call_cap)
-                    if retry_turns <= current_turns and retry_tool_calls <= current_tool_calls:
-                        raise
-                    self.logger.warning(
-                        "agentic_budget_retry",
-                        error=str(exc),
-                        original_max_turns=current_turns,
-                        original_max_tool_calls=current_tool_calls,
-                        retry_max_turns=retry_turns,
-                        retry_max_tool_calls=retry_tool_calls,
-                    )
-                    budget_retry_attempts += 1
-                    current_turns = retry_turns
-                    current_tool_calls = retry_tool_calls
-
-        output = await _invoke_agentic(
-            user_prompt,
-            max_turns,
-            max_tool_calls,
-            active_toolsets=toolsets,
-        )
-        if (not str(getattr(output, "reasoning", "") or "").strip()) and getattr(output, "issues", None):
-            synthesized_reasoning = self._build_issue_grounded_reasoning(output)
-            if synthesized_reasoning:
-                output.reasoning = synthesized_reasoning
-                self.logger.info(
-                    "agentic_reasoning_autofill_from_issues",
-                    issues_count=len(getattr(output, "issues", []) or []),
-                    reasoning_chars=len(synthesized_reasoning),
-                )
-        telemetry = (
-            aggregate_retry_telemetry
-            if isinstance(aggregate_retry_telemetry, dict) and aggregate_retry_telemetry
-            else getattr(self, "_last_agent_run_telemetry", {})
-        )
-        telemetry_available = isinstance(telemetry, dict) and (
-            "usage" in telemetry
-            or "event_tool_calls" in telemetry
-            or "event_tool_calls_started" in telemetry
-            or "event_tool_calls_completed" in telemetry
-        )
-        tool_calls_observed, skill_calls_observed = self._extract_tool_usage(telemetry if telemetry_available else None)
-        skill_effective_calls_observed = self._extract_skill_effective_usage(telemetry if telemetry_available else None)
-        docs_tool_calls_observed = self._extract_docs_tool_usage(telemetry if telemetry_available else None)
-        docs_read_calls_observed = self._extract_docs_read_tool_usage(telemetry if telemetry_available else None)
-        vector_docs_tool_calls_observed = self._extract_vector_docs_tool_usage(
-            telemetry if telemetry_available else None
-        )
-        code_read_calls_observed = self._extract_code_read_tool_usage(telemetry if telemetry_available else None)
-        quality_summary = self._build_response_quality_summary(output, telemetry if telemetry_available else None)
-        quality_flags = (
-            {str(flag) for flag in quality_summary.get("quality_flags", [])}
-            if isinstance(quality_summary, dict)
-            else set()
-        )
-        terminal_quality_flags = set(quality_flags)
-        reasoning_text = str(getattr(output, "reasoning", "") or "")
-        reasoning_has_evidence_refs = self._has_concrete_reasoning_evidence_refs(reasoning_text)
-        grounded_issue_paths = self._has_grounded_issue_paths(output, repo_path)
-        if (not reasoning_has_evidence_refs) and (not grounded_issue_paths):
-            terminal_quality_flags.add("reasoning_missing_evidence_refs")
-        terminal_quality_failure_reason = (
-            "reasoning_too_short"
-            if "reasoning_too_short" in terminal_quality_flags
-            else "reasoning_missing_evidence_refs"
-        )
-        if (
-            strict_no_fallback
-            and strict_budget_hard_synthesis_used
-            and bool({"reasoning_too_short", "reasoning_missing_evidence_refs"} & terminal_quality_flags)
-        ):
-            if strict_skip_post_guard_retries:
-                self.logger.warning(
-                    "agentic_strict_budget_hard_synthesis_quality_degraded_skip_retry",
-                    quality_flags=sorted(terminal_quality_flags),
-                    reasoning_chars=quality_summary.get("reasoning_chars"),
-                    observed_tool_counts=(
-                        telemetry.get("event_tool_count_by_name") if isinstance(telemetry, dict) else None
-                    ),
-                )
-            elif hard_synthesis_quality_retry_used:
-                self.logger.warning(
-                    "agentic_strict_budget_hard_synthesis_quality_unsatisfied",
-                    quality_flags=sorted(terminal_quality_flags),
-                    reasoning_chars=quality_summary.get("reasoning_chars"),
-                    observed_tool_counts=(
-                        telemetry.get("event_tool_count_by_name") if isinstance(telemetry, dict) else None
-                    ),
-                )
-                raise RuntimeError(
-                    f"agentic hard-synthesis quality guard unsatisfied: {terminal_quality_failure_reason} after terminal retry"
-                )
-            else:
-                hard_synthesis_quality_retry_used = True
-                self.logger.warning(
-                    "agentic_strict_budget_hard_synthesis_quality_retry",
-                    quality_flags=sorted(terminal_quality_flags),
-                    reasoning_chars=quality_summary.get("reasoning_chars"),
-                    observed_tool_counts=(
-                        telemetry.get("event_tool_count_by_name") if isinstance(telemetry, dict) else None
-                    ),
-                )
-                quality_guard_prompt = (
-                    user_prompt
-                    + "\n\nSTRICT HARD-SYNTHESIS QUALITY GUARD:\n"
-                    + "- DO NOT call tools.\n"
-                    + "- Return only final CodeFindings JSON.\n"
-                    + "- In reasoning, provide 4-6 sentences grounded in already collected evidence.\n"
-                    + "- Include at least two concrete evidence references (file path + line like src/app.py:123, or explicit document title in quotes).\n"
-                    + "- State key risk and one residual uncertainty explicitly.\n"
-                )
-                output = await _invoke_agentic(
-                    quality_guard_prompt,
-                    max(1, local_openai_hard_synthesis_max_turns),
-                    max(1, local_openai_hard_synthesis_max_tool_calls),
-                    active_toolsets=[],
-                )
-                if (not str(getattr(output, "reasoning", "") or "").strip()) and getattr(output, "issues", None):
-                    synthesized_reasoning = self._build_issue_grounded_reasoning(output)
-                    if synthesized_reasoning:
-                        output.reasoning = synthesized_reasoning
-                        self.logger.info(
-                            "agentic_reasoning_autofill_from_issues",
-                            issues_count=len(getattr(output, "issues", []) or []),
-                            reasoning_chars=len(synthesized_reasoning),
-                        )
-            telemetry = (
-                aggregate_retry_telemetry
-                if isinstance(aggregate_retry_telemetry, dict) and aggregate_retry_telemetry
-                else getattr(self, "_last_agent_run_telemetry", {})
-            )
-            telemetry_available = isinstance(telemetry, dict) and (
-                "usage" in telemetry
-                or "event_tool_calls" in telemetry
-                or "event_tool_calls_started" in telemetry
-                or "event_tool_calls_completed" in telemetry
-            )
-            tool_calls_observed, skill_calls_observed = self._extract_tool_usage(
-                telemetry if telemetry_available else None
-            )
-            skill_effective_calls_observed = self._extract_skill_effective_usage(
-                telemetry if telemetry_available else None
-            )
-            docs_tool_calls_observed = self._extract_docs_tool_usage(telemetry if telemetry_available else None)
-            docs_read_calls_observed = self._extract_docs_read_tool_usage(telemetry if telemetry_available else None)
-            vector_docs_tool_calls_observed = self._extract_vector_docs_tool_usage(
-                telemetry if telemetry_available else None
-            )
-            code_read_calls_observed = self._extract_code_read_tool_usage(telemetry if telemetry_available else None)
-            quality_summary = self._build_response_quality_summary(output, telemetry if telemetry_available else None)
-            quality_flags = (
-                {str(flag) for flag in quality_summary.get("quality_flags", [])}
-                if isinstance(quality_summary, dict)
-                else set()
-            )
-            terminal_quality_flags = set(quality_flags)
-            reasoning_text = str(getattr(output, "reasoning", "") or "")
-            reasoning_has_evidence_refs = self._has_concrete_reasoning_evidence_refs(reasoning_text)
-            grounded_issue_paths = self._has_grounded_issue_paths(output, repo_path)
-            if (not reasoning_has_evidence_refs) and (not grounded_issue_paths):
-                terminal_quality_flags.add("reasoning_missing_evidence_refs")
-            terminal_quality_failure_reason = (
-                "reasoning_too_short"
-                if "reasoning_too_short" in terminal_quality_flags
-                else "reasoning_missing_evidence_refs"
-            )
-            if bool({"reasoning_too_short", "reasoning_missing_evidence_refs"} & terminal_quality_flags):
-                self.logger.warning(
-                    "agentic_strict_budget_hard_synthesis_quality_unsatisfied",
-                    quality_flags=sorted(terminal_quality_flags),
-                    reasoning_chars=quality_summary.get("reasoning_chars"),
-                    observed_tool_counts=(
-                        telemetry.get("event_tool_count_by_name") if isinstance(telemetry, dict) else None
-                    ),
-                )
-                raise RuntimeError(
-                    f"agentic hard-synthesis quality guard unsatisfied: {terminal_quality_failure_reason} after terminal retry"
-                )
-
-        if telemetry_available and strict_no_fallback:
-            if self._is_repetitive_non_progress_tool_usage(telemetry, cadence_policy=cadence_policy):
-                strict_efficiency_summary = self._build_tool_efficiency_summary(
-                    telemetry if isinstance(telemetry, dict) else None
-                )
-                productive_output = self._has_productive_agentic_output(output, strict_efficiency_summary)
-                log_fn = self.logger.info if productive_output else self.logger.warning
-                log_event = (
-                    "agentic_non_progress_guard_degraded_productive"
-                    if productive_output
-                    else "agentic_non_progress_guard_unsatisfied"
-                )
-                log_fn(
-                    log_event,
-                    observed_tool_calls=tool_calls_observed,
-                    observed_skill_calls=skill_calls_observed,
-                    observed_skill_effective_calls=skill_effective_calls_observed,
-                    observed_tool_names=telemetry.get("event_tool_names"),
-                    productive_output=productive_output,
-                    strict_no_fallback=strict_no_fallback,
-                )
-                if strict_no_fallback and not productive_output:
-                    if strict_skip_post_guard_retries:
-                        self.logger.warning(
-                            "agentic_non_progress_guard_degraded_skip_retry",
-                            observed_tool_calls=tool_calls_observed,
-                            observed_skill_calls=skill_calls_observed,
-                            observed_tool_names=telemetry.get("event_tool_names"),
-                        )
-                    else:
-                        raise RuntimeError(
-                            "agentic non-progress guard unsatisfied: repetitive tool usage without progress"
-                        )
-
-            tool_count_by_name = telemetry.get("event_tool_count_by_name")
-            has_detailed_tool_telemetry = isinstance(tool_count_by_name, dict) and any(
-                str(name) != "final_result" and int(count or 0) > 0 for name, count in tool_count_by_name.items()
-            )
-            strict_code_read_required = has_detailed_tool_telemetry
-            if vector_docs_required and vector_docs_tool_calls_observed < 1:
-                self.logger.warning(
-                    "agentic_vector_docs_usage_guard_retry_strict",
-                    observed_tool_calls=tool_calls_observed,
-                    observed_vector_docs_tool_calls=vector_docs_tool_calls_observed,
-                    vector_docs_required=vector_docs_required,
-                )
-                if not _consume_corrective_budget(
-                    guard_class="vector",
-                    reason="strict_vector_docs_usage_guard_retry",
-                ):
-                    return _degraded_finalize_for_corrective_budget(
-                        guard_class="vector",
-                        reason="strict_vector_docs_usage_guard_retry_budget_exhausted",
-                        output_hint=output,
-                        telemetry_hint=telemetry if isinstance(telemetry, dict) else None,
-                    )
-                strict_vector_prompt = (
-                    user_prompt
-                    + "\n\nSTRICT MANDATORY VECTOR DOCS RETRIEVAL:\n"
-                    + "- Call search_evidence_vector (docs) or search_code_vector (code) with requirement-specific keywords.\n"
-                    + "- Use vector_retrieval_status only as readiness check, not as primary evidence.\n"
-                    + "- Read at least one concrete source after vector retrieval before finalizing."
-                )
-                output = await _invoke_agentic(
-                    strict_vector_prompt,
-                    min(max_turns + 2, retry_turn_cap),
-                    min(max_tool_calls + 8, retry_tool_call_cap),
-                    active_toolsets=toolsets,
-                )
-                telemetry = (
-                    aggregate_retry_telemetry
-                    if isinstance(aggregate_retry_telemetry, dict) and aggregate_retry_telemetry
-                    else getattr(self, "_last_agent_run_telemetry", {})
-                )
-                telemetry_available = isinstance(telemetry, dict) and (
-                    "usage" in telemetry
-                    or "event_tool_calls" in telemetry
-                    or "event_tool_calls_started" in telemetry
-                    or "event_tool_calls_completed" in telemetry
-                )
-                tool_calls_observed, skill_calls_observed = self._extract_tool_usage(
-                    telemetry if telemetry_available else None
-                )
-                skill_effective_calls_observed = self._extract_skill_effective_usage(
-                    telemetry if telemetry_available else None
-                )
-                docs_tool_calls_observed = self._extract_docs_tool_usage(telemetry if telemetry_available else None)
-                docs_read_calls_observed = self._extract_docs_read_tool_usage(
-                    telemetry if telemetry_available else None
-                )
-                vector_docs_tool_calls_observed = self._extract_vector_docs_tool_usage(
-                    telemetry if telemetry_available else None
-                )
-                code_read_calls_observed = self._extract_code_read_tool_usage(
-                    telemetry if telemetry_available else None
-                )
-            # Strict mode requires an explicit, effective skill tool call
-            # only for rows classified as skill-required.
-            skills_requirement_satisfied = (not skills_required) or (skill_effective_calls_observed >= 1)
-            if (
-                not skills_requirement_satisfied
-                and tool_calls_observed >= 1
-                and (not strict_code_read_required or code_read_calls_observed >= 1)
-                and (not docs_required or docs_read_calls_observed >= 1 or vector_docs_tool_calls_observed >= 1)
-                and (not vector_docs_required or vector_docs_tool_calls_observed >= 1)
-                and (vector_docs_tool_calls_observed < 1 or (docs_read_calls_observed + code_read_calls_observed) >= 1)
-            ):
-                self.logger.warning(
-                    "agentic_skill_usage_guard_retry_strict",
-                    observed_tool_calls=tool_calls_observed,
-                    observed_skill_calls=skill_calls_observed,
-                    observed_skill_effective_calls=skill_effective_calls_observed,
-                )
-                if not _consume_corrective_budget(
-                    guard_class="skill",
-                    reason="strict_skill_usage_guard_retry",
-                ):
-                    return _degraded_finalize_for_corrective_budget(
-                        guard_class="skill",
-                        reason="strict_skill_usage_guard_retry_budget_exhausted",
-                        output_hint=output,
-                        telemetry_hint=telemetry if isinstance(telemetry, dict) else None,
-                    )
-                strict_skill_prompt = (
-                    user_prompt
-                    + "\n\nSTRICT MANDATORY SKILL USAGE:\n"
-                    + '- Call load_skill(name="<listed-skill>") for one relevant available skill.\n'
-                    + '- Then call read_skill_resource(name="<listed-skill>", resource_path="<resource-from-load-skill>") once.\n'
-                    + "- Do not call list_skills in this retry; available skills are already listed.\n"
-                    + "- Use skill tools only in this retry to complete one effective skill sequence quickly.\n"
-                    + "- Keep filesystem evidence already collected; do not restart broad discovery.\n"
-                    + "- Return final output only after one effective skill tool call."
-                )
-                strict_skill_tool_allowlist = [
-                    "load_skill",
-                    "read_skill_resource",
-                    "run_skill_script",
-                ]
-                strict_skill_toolsets = self._apply_tool_allowlist(list(toolsets), strict_skill_tool_allowlist)
-                if not strict_skill_toolsets:
-                    self.logger.warning(
-                        "agentic_skill_usage_guard_retry_toolset_unavailable",
-                        allowlist=strict_skill_tool_allowlist,
-                    )
-                    strict_skill_toolsets = list(toolsets)
-                strict_skill_retry_turns = max(2, min(max_turns, 4))
-                strict_skill_retry_tool_calls = max(4, min(max_tool_calls, 8))
-                output = await _invoke_agentic(
-                    strict_skill_prompt,
-                    strict_skill_retry_turns,
-                    strict_skill_retry_tool_calls,
-                    active_toolsets=strict_skill_toolsets,
-                )
-                telemetry = (
-                    aggregate_retry_telemetry
-                    if isinstance(aggregate_retry_telemetry, dict) and aggregate_retry_telemetry
-                    else getattr(self, "_last_agent_run_telemetry", {})
-                )
-                telemetry_available = isinstance(telemetry, dict) and (
-                    "usage" in telemetry
-                    or "event_tool_calls" in telemetry
-                    or "event_tool_calls_started" in telemetry
-                    or "event_tool_calls_completed" in telemetry
-                )
-                tool_calls_observed, skill_calls_observed = self._extract_tool_usage(
-                    telemetry if telemetry_available else None
-                )
-                skill_effective_calls_observed = self._extract_skill_effective_usage(
-                    telemetry if telemetry_available else None
-                )
-                docs_tool_calls_observed = self._extract_docs_tool_usage(telemetry if telemetry_available else None)
-                docs_read_calls_observed = self._extract_docs_read_tool_usage(
-                    telemetry if telemetry_available else None
-                )
-                vector_docs_tool_calls_observed = self._extract_vector_docs_tool_usage(
-                    telemetry if telemetry_available else None
-                )
-                code_read_calls_observed = self._extract_code_read_tool_usage(
-                    telemetry if telemetry_available else None
-                )
-                skills_requirement_satisfied = (not skills_required) or (skill_effective_calls_observed >= 1)
-            if (
-                tool_calls_observed < 1
-                or (strict_code_read_required and code_read_calls_observed < 1)
-                or (not skills_requirement_satisfied)
-                or (docs_required and docs_read_calls_observed < 1 and vector_docs_tool_calls_observed < 1)
-                or (vector_docs_required and vector_docs_tool_calls_observed < 1)
-                or (vector_docs_tool_calls_observed >= 1 and (docs_read_calls_observed + code_read_calls_observed) < 1)
-            ):
-                if (
-                    strict_no_fallback
-                    and local_openai_protocol
-                    and local_openai_hard_synthesis_used
-                    and not has_detailed_tool_telemetry
-                ):
-                    self.logger.warning(
-                        "agentic_usage_guard_degraded_missing_detailed_telemetry",
-                        observed_tool_calls=tool_calls_observed,
-                        observed_skill_calls=skill_calls_observed,
-                        observed_skill_effective_calls=skill_effective_calls_observed,
-                        observed_tool_names=telemetry.get("event_tool_names"),
-                        strict_no_fallback=True,
-                    )
-                else:
-                    self.logger.warning(
-                        "agentic_usage_guard_unsatisfied",
-                        observed_tool_calls=tool_calls_observed,
-                        observed_skill_calls=skill_calls_observed,
-                        observed_skill_effective_calls=skill_effective_calls_observed,
-                        skills_available=skills_available,
-                        skills_required=skills_required,
-                        preloaded_skill_context_used=bool(preloaded_skill_names),
-                        preloaded_skill_names=preloaded_skill_names,
-                        strict_code_read_required=strict_code_read_required,
-                        observed_code_read_tool_calls=code_read_calls_observed,
-                        observed_docs_tool_calls=docs_tool_calls_observed,
-                        observed_docs_read_tool_calls=docs_read_calls_observed,
-                        docs_required=docs_required,
-                        observed_vector_docs_tool_calls=vector_docs_tool_calls_observed,
-                        vector_docs_required=vector_docs_required,
-                        strict_no_fallback=True,
-                    )
-                    if strict_skip_post_guard_retries:
-                        self.logger.warning(
-                            "agentic_usage_guard_degraded_skip_retry",
-                            strict_no_fallback=True,
-                            observed_tool_calls=tool_calls_observed,
-                            observed_skill_calls=skill_calls_observed,
-                            observed_code_read_tool_calls=code_read_calls_observed,
-                        )
-                    else:
-                        raise RuntimeError(
-                            "agentic usage guard unsatisfied: expected tool/docs/skill calls were not observed"
-                        )
-        elif telemetry_available:
-            non_progress_detected = self._is_repetitive_non_progress_tool_usage(
-                telemetry, cadence_policy=cadence_policy
-            )
-            tool_count_by_name = telemetry.get("event_tool_count_by_name") if isinstance(telemetry, dict) else None
-            has_detailed_tool_telemetry = isinstance(tool_count_by_name, dict) and any(
-                str(name) != "final_result" and int(count or 0) > 0 for name, count in tool_count_by_name.items()
-            )
-            require_code_read_in_relaxed_mode = (
-                has_detailed_tool_telemetry and not docs_required and not vector_docs_required
-            )
-            if tool_calls_observed < 1:
-                if non_progress_detected:
-                    self.logger.warning(
-                        "agentic_tool_usage_guard_retry_skipped_non_progress",
-                        observed_tool_calls=tool_calls_observed,
-                        observed_skill_calls=skill_calls_observed,
-                        observed_tool_names=telemetry.get("event_tool_names"),
-                    )
-                else:
-                    self.logger.warning(
-                        "agentic_tool_usage_guard_retry",
-                        observed_tool_calls=tool_calls_observed,
-                        observed_skill_calls=skill_calls_observed,
-                        skills_available=skills_available,
-                    )
-                    if not _consume_corrective_budget(
-                        guard_class="usage",
-                        reason="tool_usage_guard_retry",
-                    ):
-                        return _degraded_finalize_for_corrective_budget(
-                            guard_class="usage",
-                            reason="tool_usage_guard_retry_budget_exhausted",
-                            output_hint=output,
-                            telemetry_hint=telemetry if isinstance(telemetry, dict) else None,
-                        )
-                    guarded_prompt = (
-                        user_prompt
-                        + "\n\nMANDATORY TOOL USAGE:\n"
-                        + "- Before final output, perform one repository discovery call (grep_search preferred; list_directory only if needed).\n"
-                        + "- Then call read_file on at least one concrete file path returned by discovery.\n"
-                        + "- Do not repeat identical list_directory calls on the same path.\n"
-                        + "- Do not return a final answer without tool evidence."
-                    )
-                    output = await _invoke_agentic(
-                        guarded_prompt,
-                        min(max_turns + 2, retry_turn_cap),
-                        min(max_tool_calls + 8, retry_tool_call_cap),
-                        active_toolsets=toolsets,
-                    )
-                    telemetry = (
-                        aggregate_retry_telemetry
-                        if isinstance(aggregate_retry_telemetry, dict) and aggregate_retry_telemetry
-                        else getattr(self, "_last_agent_run_telemetry", {})
-                    )
-                    tool_calls_observed, skill_calls_observed = self._extract_tool_usage(telemetry)
-                    skill_effective_calls_observed = self._extract_skill_effective_usage(telemetry)
-                    docs_tool_calls_observed = self._extract_docs_tool_usage(telemetry)
-                    docs_read_calls_observed = self._extract_docs_read_tool_usage(telemetry)
-                    vector_docs_tool_calls_observed = self._extract_vector_docs_tool_usage(telemetry)
-                    code_read_calls_observed = self._extract_code_read_tool_usage(telemetry)
-                    non_progress_detected = self._is_repetitive_non_progress_tool_usage(
-                        telemetry, cadence_policy=cadence_policy
-                    )
-
-            if require_code_read_in_relaxed_mode and code_read_calls_observed < 1:
-                if non_progress_detected:
-                    self.logger.warning(
-                        "agentic_code_read_guard_retry_skipped_non_progress",
-                        observed_tool_calls=tool_calls_observed,
-                        observed_code_read_tool_calls=code_read_calls_observed,
-                        observed_tool_names=telemetry.get("event_tool_names"),
-                    )
-                else:
-                    self.logger.warning(
-                        "agentic_code_read_guard_retry",
-                        observed_tool_calls=tool_calls_observed,
-                        observed_code_read_tool_calls=code_read_calls_observed,
-                    )
-                    if not _consume_corrective_budget(
-                        guard_class="usage",
-                        reason="code_read_guard_retry",
-                    ):
-                        return _degraded_finalize_for_corrective_budget(
-                            guard_class="usage",
-                            reason="code_read_guard_retry_budget_exhausted",
-                            output_hint=output,
-                            telemetry_hint=telemetry if isinstance(telemetry, dict) else None,
-                        )
-                    code_read_guarded_prompt = (
-                        user_prompt
-                        + "\n\nMANDATORY CODE READ:\n"
-                        + "- Perform one focused discovery call (grep_search preferred).\n"
-                        + "- Immediately read_file (or get_definition/find_references) on a concrete file hit.\n"
-                        + "- Do not conclude without at least one concrete code read/navigation result."
-                    )
-                    output = await _invoke_agentic(
-                        code_read_guarded_prompt,
-                        min(max_turns + 2, retry_turn_cap),
-                        min(max_tool_calls + 8, retry_tool_call_cap),
-                        active_toolsets=toolsets,
-                    )
-                    telemetry = (
-                        aggregate_retry_telemetry
-                        if isinstance(aggregate_retry_telemetry, dict) and aggregate_retry_telemetry
-                        else getattr(self, "_last_agent_run_telemetry", {})
-                    )
-                    tool_calls_observed, skill_calls_observed = self._extract_tool_usage(telemetry)
-                    skill_effective_calls_observed = self._extract_skill_effective_usage(telemetry)
-                    docs_tool_calls_observed = self._extract_docs_tool_usage(telemetry)
-                    docs_read_calls_observed = self._extract_docs_read_tool_usage(telemetry)
-                    vector_docs_tool_calls_observed = self._extract_vector_docs_tool_usage(telemetry)
-                    code_read_calls_observed = self._extract_code_read_tool_usage(telemetry)
-                    non_progress_detected = self._is_repetitive_non_progress_tool_usage(
-                        telemetry, cadence_policy=cadence_policy
-                    )
-
-            if docs_required and docs_read_calls_observed < 1 and vector_docs_tool_calls_observed < 1:
-                if non_progress_detected:
-                    self.logger.warning(
-                        "agentic_docs_usage_guard_retry_skipped_non_progress",
-                        observed_tool_calls=tool_calls_observed,
-                        observed_docs_tool_calls=docs_tool_calls_observed,
-                        observed_tool_names=telemetry.get("event_tool_names"),
-                        docs_required=docs_required,
-                    )
-                else:
-                    self.logger.warning(
-                        "agentic_docs_usage_guard_retry",
-                        observed_tool_calls=tool_calls_observed,
-                        observed_docs_tool_calls=docs_tool_calls_observed,
-                        docs_required=docs_required,
-                    )
-                    if not _consume_corrective_budget(
-                        guard_class="docs",
-                        reason="docs_usage_guard_retry",
-                    ):
-                        return _degraded_finalize_for_corrective_budget(
-                            guard_class="docs",
-                            reason="docs_usage_guard_retry_budget_exhausted",
-                            output_hint=output,
-                            telemetry_hint=telemetry if isinstance(telemetry, dict) else None,
-                        )
-                    docs_guarded_prompt = (
-                        user_prompt
-                        + "\n\nMANDATORY DOCS RETRIEVAL:\n"
-                        + "- Call list_evidence_documents or search_evidence using architecture/security requirement keywords.\n"
-                        + "- Then call read_evidence_document on at least one relevant result.\n"
-                        + "- Correlate code findings with docs findings before final output."
-                    )
-                    output = await _invoke_agentic(
-                        docs_guarded_prompt,
-                        min(max_turns + 2, retry_turn_cap),
-                        min(max_tool_calls + 8, retry_tool_call_cap),
-                        active_toolsets=toolsets,
-                    )
-                    telemetry = (
-                        aggregate_retry_telemetry
-                        if isinstance(aggregate_retry_telemetry, dict) and aggregate_retry_telemetry
-                        else getattr(self, "_last_agent_run_telemetry", {})
-                    )
-                    tool_calls_observed, skill_calls_observed = self._extract_tool_usage(telemetry)
-                    skill_effective_calls_observed = self._extract_skill_effective_usage(telemetry)
-                    docs_tool_calls_observed = self._extract_docs_tool_usage(telemetry)
-                    docs_read_calls_observed = self._extract_docs_read_tool_usage(telemetry)
-                    vector_docs_tool_calls_observed = self._extract_vector_docs_tool_usage(telemetry)
-                    code_read_calls_observed = self._extract_code_read_tool_usage(telemetry)
-                    non_progress_detected = self._is_repetitive_non_progress_tool_usage(
-                        telemetry, cadence_policy=cadence_policy
-                    )
-
-            if vector_docs_required and vector_docs_tool_calls_observed < 1:
-                if non_progress_detected:
-                    self.logger.warning(
-                        "agentic_vector_docs_usage_guard_skipped_non_progress",
-                        observed_tool_calls=tool_calls_observed,
-                        observed_vector_docs_tool_calls=vector_docs_tool_calls_observed,
-                        observed_tool_names=telemetry.get("event_tool_names"),
-                        vector_docs_required=vector_docs_required,
-                    )
-                else:
-                    self.logger.warning(
-                        "agentic_vector_docs_usage_guard_retry",
-                        observed_tool_calls=tool_calls_observed,
-                        observed_vector_docs_tool_calls=vector_docs_tool_calls_observed,
-                        vector_docs_required=vector_docs_required,
-                    )
-                    if not _consume_corrective_budget(
-                        guard_class="vector",
-                        reason="vector_docs_usage_guard_retry",
-                    ):
-                        return _degraded_finalize_for_corrective_budget(
-                            guard_class="vector",
-                            reason="vector_docs_usage_guard_retry_budget_exhausted",
-                            output_hint=output,
-                            telemetry_hint=telemetry if isinstance(telemetry, dict) else None,
-                        )
-                    vector_guarded_prompt = (
-                        user_prompt
-                        + "\n\nMANDATORY VECTOR DOCS RETRIEVAL:\n"
-                        + "- Call search_evidence_vector (docs) or search_code_vector (code) with architecture/security requirement keywords.\n"
-                        + "- Use vector_retrieval_status only as readiness check, not as primary evidence.\n"
-                        + "- Correlate vector evidence chunks with repository findings before final output."
-                    )
-                    output = await _invoke_agentic(
-                        vector_guarded_prompt,
-                        min(max_turns + 2, retry_turn_cap),
-                        min(max_tool_calls + 8, retry_tool_call_cap),
-                        active_toolsets=toolsets,
-                    )
-                    telemetry = (
-                        aggregate_retry_telemetry
-                        if isinstance(aggregate_retry_telemetry, dict) and aggregate_retry_telemetry
-                        else getattr(self, "_last_agent_run_telemetry", {})
-                    )
-                    tool_calls_observed, skill_calls_observed = self._extract_tool_usage(telemetry)
-                    skill_effective_calls_observed = self._extract_skill_effective_usage(telemetry)
-                    docs_tool_calls_observed = self._extract_docs_tool_usage(telemetry)
-                    docs_read_calls_observed = self._extract_docs_read_tool_usage(telemetry)
-                    vector_docs_tool_calls_observed = self._extract_vector_docs_tool_usage(telemetry)
-                    code_read_calls_observed = self._extract_code_read_tool_usage(telemetry)
-                    non_progress_detected = self._is_repetitive_non_progress_tool_usage(
-                        telemetry, cadence_policy=cadence_policy
-                    )
-
-            if vector_docs_tool_calls_observed >= 1 and (docs_read_calls_observed + code_read_calls_observed) < 1:
-                if non_progress_detected:
-                    self.logger.warning(
-                        "agentic_vector_readback_guard_skipped_non_progress",
-                        observed_tool_calls=tool_calls_observed,
-                        observed_vector_docs_tool_calls=vector_docs_tool_calls_observed,
-                        observed_docs_read_tool_calls=docs_read_calls_observed,
-                        observed_code_read_tool_calls=code_read_calls_observed,
-                        observed_tool_names=telemetry.get("event_tool_names"),
-                    )
-                else:
-                    self.logger.warning(
-                        "agentic_vector_readback_guard_retry",
-                        observed_tool_calls=tool_calls_observed,
-                        observed_vector_docs_tool_calls=vector_docs_tool_calls_observed,
-                        observed_docs_read_tool_calls=docs_read_calls_observed,
-                        observed_code_read_tool_calls=code_read_calls_observed,
-                    )
-                    if not _consume_corrective_budget(
-                        guard_class="vector",
-                        reason="vector_readback_guard_retry",
-                    ):
-                        return _degraded_finalize_for_corrective_budget(
-                            guard_class="vector",
-                            reason="vector_readback_guard_retry_budget_exhausted",
-                            output_hint=output,
-                            telemetry_hint=telemetry if isinstance(telemetry, dict) else None,
-                        )
-                    vector_readback_prompt = (
-                        user_prompt
-                        + "\n\nMANDATORY VECTOR READ-BACK:\n"
-                        + "- After vector retrieval, read at least one concrete source before finalizing.\n"
-                        + "- Use read_evidence_document for docs vectors or read_file/get_definition/find_references for code vectors.\n"
-                        + "- Ground findings in the concrete read output, not vector summaries alone."
-                    )
-                    output = await _invoke_agentic(
-                        vector_readback_prompt,
-                        min(max_turns + 2, retry_turn_cap),
-                        min(max_tool_calls + 8, retry_tool_call_cap),
-                        active_toolsets=toolsets,
-                    )
-                    telemetry = (
-                        aggregate_retry_telemetry
-                        if isinstance(aggregate_retry_telemetry, dict) and aggregate_retry_telemetry
-                        else getattr(self, "_last_agent_run_telemetry", {})
-                    )
-                    tool_calls_observed, skill_calls_observed = self._extract_tool_usage(telemetry)
-                    skill_effective_calls_observed = self._extract_skill_effective_usage(telemetry)
-                    docs_tool_calls_observed = self._extract_docs_tool_usage(telemetry)
-                    docs_read_calls_observed = self._extract_docs_read_tool_usage(telemetry)
-                    vector_docs_tool_calls_observed = self._extract_vector_docs_tool_usage(telemetry)
-                    code_read_calls_observed = self._extract_code_read_tool_usage(telemetry)
-                    non_progress_detected = self._is_repetitive_non_progress_tool_usage(
-                        telemetry, cadence_policy=cadence_policy
-                    )
-
-            if skills_required and skill_effective_calls_observed < 1:
-                if non_progress_detected:
-                    self.logger.warning(
-                        "agentic_skill_usage_guard_retry_skipped_non_progress",
-                        observed_tool_calls=tool_calls_observed,
-                        observed_skill_calls=skill_calls_observed,
-                        observed_tool_names=telemetry.get("event_tool_names"),
-                    )
-                else:
-                    self.logger.warning(
-                        "agentic_skill_usage_guard_retry",
-                        observed_tool_calls=tool_calls_observed,
-                        observed_skill_calls=skill_calls_observed,
-                    )
-                    if not _consume_corrective_budget(
-                        guard_class="skill",
-                        reason="skill_usage_guard_retry",
-                    ):
-                        return _degraded_finalize_for_corrective_budget(
-                            guard_class="skill",
-                            reason="skill_usage_guard_retry_budget_exhausted",
-                            output_hint=output,
-                            telemetry_hint=telemetry if isinstance(telemetry, dict) else None,
-                        )
-                    skill_guarded_prompt = (
-                        user_prompt
-                        + "\n\nMANDATORY SKILL USAGE:\n"
-                        + "- Do not call list_skills unless the available skill list is missing.\n"
-                        + '- Call load_skill(name="<listed-skill>") once for one relevant skill.\n'
-                        + '- Then call read_skill_resource(name="<listed-skill>", resource_path="<resource-from-load-skill>") '
-                        + "or run_skill_script only when explicitly available.\n"
-                        + "- Do not return a final answer without at least one effective skill tool call."
-                    )
-                    output = await _invoke_agentic(
-                        skill_guarded_prompt,
-                        min(max_turns + 4, retry_turn_cap),
-                        min(max_tool_calls + 12, retry_tool_call_cap),
-                        active_toolsets=toolsets,
-                    )
-                    telemetry = (
-                        aggregate_retry_telemetry
-                        if isinstance(aggregate_retry_telemetry, dict) and aggregate_retry_telemetry
-                        else getattr(self, "_last_agent_run_telemetry", {})
-                    )
-                    tool_calls_observed, skill_calls_observed = self._extract_tool_usage(telemetry)
-                    skill_effective_calls_observed = self._extract_skill_effective_usage(telemetry)
-                    code_read_calls_observed = self._extract_code_read_tool_usage(telemetry)
-                    non_progress_detected = self._is_repetitive_non_progress_tool_usage(
-                        telemetry, cadence_policy=cadence_policy
-                    )
-
-            if non_progress_detected:
-                self.logger.warning(
-                    "agentic_non_progress_guard_retry",
-                    observed_tool_calls=tool_calls_observed,
-                    observed_skill_calls=skill_calls_observed,
-                    observed_tool_names=telemetry.get("event_tool_names"),
-                )
-                non_progress_guarded_prompt = (
-                    user_prompt
-                    + "\n\nNON-PROGRESS LOOP GUARD:\n"
-                    + "- Avoid repeating the same tool call pattern.\n"
-                    + "- Pivot to a different tool or file target when prior calls yield no new evidence.\n"
-                    + "- Do not call list_directory more than once per distinct path.\n"
-                    + "- Do not call search_evidence more than twice for the same requirement.\n"
-                    + "- Do not call list_skills unless you will immediately use a loaded skill in analysis.\n"
-                    + "- Produce findings only after acquiring fresh tool evidence."
-                )
-                if not _consume_corrective_budget(
-                    guard_class="non_progress",
-                    reason="non_progress_guard_retry",
-                ):
-                    return _degraded_finalize_for_corrective_budget(
-                        guard_class="non_progress",
-                        reason="non_progress_guard_retry_budget_exhausted",
-                        output_hint=output,
-                        telemetry_hint=telemetry if isinstance(telemetry, dict) else None,
-                    )
-                output = await _invoke_agentic(
-                    non_progress_guarded_prompt,
-                    min(max_turns, retry_turn_cap),
-                    min(max_tool_calls, 12),
-                    active_toolsets=toolsets,
-                )
-                telemetry = (
-                    aggregate_retry_telemetry
-                    if isinstance(aggregate_retry_telemetry, dict) and aggregate_retry_telemetry
-                    else getattr(self, "_last_agent_run_telemetry", {})
-                )
-                tool_calls_observed, skill_calls_observed = self._extract_tool_usage(telemetry)
-                skill_effective_calls_observed = self._extract_skill_effective_usage(telemetry)
-                docs_tool_calls_observed = self._extract_docs_tool_usage(telemetry)
-                docs_read_calls_observed = self._extract_docs_read_tool_usage(telemetry)
-                vector_docs_tool_calls_observed = self._extract_vector_docs_tool_usage(telemetry)
-                code_read_calls_observed = self._extract_code_read_tool_usage(telemetry)
-                non_progress_detected = self._is_repetitive_non_progress_tool_usage(
-                    telemetry, cadence_policy=cadence_policy
-                )
-
-            if non_progress_detected:
-                self.logger.warning(
-                    "agentic_non_progress_guard_unsatisfied",
-                    observed_tool_calls=tool_calls_observed,
-                    observed_skill_calls=skill_calls_observed,
-                    observed_skill_effective_calls=skill_effective_calls_observed,
-                    observed_tool_names=telemetry.get("event_tool_names"),
-                )
-                if corrective_budget_remaining <= 0:
-                    return _degraded_finalize_for_corrective_budget(
-                        guard_class="non_progress",
-                        reason="non_progress_guard_unsatisfied_budget_exhausted",
-                        output_hint=output,
-                        telemetry_hint=telemetry if isinstance(telemetry, dict) else None,
-                    )
-                raise RuntimeError("agentic non-progress guard unsatisfied: repetitive tool usage without progress")
-
-            # Strict mode requires an explicit, effective skill tool call
-            # only for rows classified as skill-required.
-            skills_requirement_satisfied = (not skills_required) or (skill_effective_calls_observed >= 1)
-            if (
-                tool_calls_observed < 1
-                or (require_code_read_in_relaxed_mode and code_read_calls_observed < 1)
-                or (not skills_requirement_satisfied)
-                or (docs_required and docs_read_calls_observed < 1 and vector_docs_tool_calls_observed < 1)
-                or (vector_docs_required and vector_docs_tool_calls_observed < 1)
-            ):
-                self.logger.warning(
-                    "agentic_usage_guard_unsatisfied",
-                    observed_tool_calls=tool_calls_observed,
-                    observed_skill_calls=skill_calls_observed,
-                    observed_skill_effective_calls=skill_effective_calls_observed,
-                    skills_available=skills_available,
-                    skills_required=skills_required,
-                    preloaded_skill_context_used=bool(preloaded_skill_names),
-                    preloaded_skill_names=preloaded_skill_names,
-                    observed_code_read_tool_calls=code_read_calls_observed,
-                    observed_docs_tool_calls=docs_tool_calls_observed,
-                    docs_required=docs_required,
-                    observed_vector_docs_tool_calls=vector_docs_tool_calls_observed,
-                    vector_docs_required=vector_docs_required,
-                )
-                # Relaxed mode is warning-only for usage guard misses; strict mode hard-fails above.
-
-        efficiency_summary = self._build_tool_efficiency_summary(telemetry if isinstance(telemetry, dict) else None)
-        if self._is_tool_efficiency_kpi_unsatisfied(efficiency_summary, cadence_policy=cadence_policy):
-            non_progress_detected = self._is_repetitive_non_progress_tool_usage(
-                telemetry, cadence_policy=cadence_policy
-            )
-            self.logger.warning(
-                "agentic_tool_efficiency_kpi_failed",
-                tool_efficiency=efficiency_summary,
-                strict_no_fallback=strict_no_fallback,
-                non_progress_detected=non_progress_detected,
-            )
-            if non_progress_detected:
-                self.logger.warning(
-                    "agentic_tool_efficiency_kpi_corrective_skipped_non_progress",
-                    tool_efficiency=efficiency_summary,
-                )
-            else:
-                corrected_prompt = self._build_tool_efficiency_corrective_prompt(
-                    user_prompt, cadence_policy=cadence_policy
-                )
-                output = await _invoke_agentic(
-                    corrected_prompt,
-                    min(max_turns + 3, retry_turn_cap),
-                    min(max_tool_calls + 12, retry_tool_call_cap),
-                    active_toolsets=toolsets,
-                )
-                telemetry = (
-                    aggregate_retry_telemetry
-                    if isinstance(aggregate_retry_telemetry, dict) and aggregate_retry_telemetry
-                    else getattr(self, "_last_agent_run_telemetry", {})
-                )
-                tool_calls_observed, skill_calls_observed = self._extract_tool_usage(telemetry)
-                skill_effective_calls_observed = self._extract_skill_effective_usage(telemetry)
-                docs_tool_calls_observed = self._extract_docs_tool_usage(telemetry)
-                docs_read_calls_observed = self._extract_docs_read_tool_usage(telemetry)
-                vector_docs_tool_calls_observed = self._extract_vector_docs_tool_usage(telemetry)
-                efficiency_summary = self._build_tool_efficiency_summary(
-                    telemetry if isinstance(telemetry, dict) else None
-                )
-                if self._is_tool_efficiency_kpi_unsatisfied(efficiency_summary, cadence_policy=cadence_policy):
-                    self.logger.warning(
-                        "agentic_tool_efficiency_kpi_unsatisfied",
-                        tool_efficiency=efficiency_summary,
-                        strict_no_fallback=strict_no_fallback,
-                    )
-                    if strict_no_fallback:
-                        if strict_skip_post_guard_retries:
-                            self.logger.warning(
-                                "agentic_tool_efficiency_kpi_degraded_skip_retry",
-                                tool_efficiency=efficiency_summary,
-                            )
-                        else:
-                            raise RuntimeError("agentic tool-efficiency KPI unsatisfied after corrective prompt")
-
-        elapsed = time.monotonic() - start_time
-        if isinstance(aggregate_retry_telemetry, dict):
-            _sync_corrective_budget_telemetry(aggregate_retry_telemetry)
-        if isinstance(telemetry, dict) and efficiency_summary:
-            telemetry["tool_efficiency"] = efficiency_summary
-        final_quality_summary = self._build_response_quality_summary(
-            output,
-            telemetry if isinstance(telemetry, dict) else None,
-        )
-        if isinstance(telemetry, dict):
-            telemetry["response_quality"] = final_quality_summary
-        self.logger.info(
-            "agentic_analysis_complete",
-            elapsed_sec=round(elapsed, 2),
-            score=getattr(output, "score", None),
-            confidence=getattr(output, "confidence", None),
-            observed_tool_calls=tool_calls_observed,
-            observed_code_read_tool_calls=code_read_calls_observed,
-            observed_skill_calls=skill_calls_observed,
-            observed_skill_effective_calls=skill_effective_calls_observed,
-            observed_docs_tool_calls=docs_tool_calls_observed,
-            observed_docs_read_tool_calls=docs_read_calls_observed,
-            observed_vector_docs_tool_calls=vector_docs_tool_calls_observed,
-            skills_available=skills_available,
-            available_skill_count=len(available_skill_names),
-            available_skill_names=available_skill_names[:8],
-            preloaded_skill_context_used=bool(preloaded_skill_names),
-            preloaded_skill_names=preloaded_skill_names,
-            skills_needed=skills_needed,
-            skills_needed_reason=skills_needed_reason,
-            skills_required=skills_required,
-            advisory_skill_sequence_skipped=advisory_skill_sequence_skipped,
-            docs_required=docs_required,
-            vector_docs_required=vector_docs_required,
-        )
-        if efficiency_summary:
-            self.logger.info(
-                "agentic_tool_efficiency",
-                **efficiency_summary,
-            )
-            skill_effective_rate = efficiency_summary.get("skill_effective_rate")
-            if isinstance(skill_effective_rate, float) and skill_effective_rate < 0.5:
-                self.logger.warning(
-                    "agentic_skill_efficiency_low",
-                    skill_effective_rate=skill_effective_rate,
-                    skill_calls_total=efficiency_summary.get("skill_calls_total"),
-                    skill_calls_effective=efficiency_summary.get("skill_calls_effective"),
-                    skill_discovery_ratio=efficiency_summary.get("skill_discovery_ratio"),
-                )
-            repetition_rate = efficiency_summary.get("tool_repetition_rate")
-            tool_calls_completed = int(efficiency_summary.get("tool_calls_completed", 0) or 0)
-            if isinstance(repetition_rate, float) and tool_calls_completed >= 6 and repetition_rate > 0.6:
-                self.logger.warning(
-                    "agentic_tool_efficiency_low",
-                    tool_repetition_rate=repetition_rate,
-                    tool_calls_completed=tool_calls_completed,
-                    tool_calls_unique=efficiency_summary.get("tool_calls_unique"),
-                )
-        if isinstance(telemetry, dict):
-            skill_calls = int(telemetry.get("event_skill_tool_calls", 0) or 0)
-            effective_skill_calls = int(
-                telemetry.get(
-                    "event_skill_execution_effective_tool_calls",
-                    telemetry.get("event_skill_effective_tool_calls", 0),
-                )
-                or 0
-            )
-            if skill_calls > 0 and effective_skill_calls == 0:
-                self.logger.warning(
-                    "ineffective_skill_use",
-                    observed_skill_calls=skill_calls,
-                    observed_skill_effective_calls=effective_skill_calls,
-                    observed_tool_names=telemetry.get("event_tool_names"),
-                )
-        if isinstance(telemetry, dict):
-            self._last_agent_run_telemetry = telemetry
-        return output
-
-    async def _run_pydantic_ai_analysis(
-        self,
-        evidence: EvidenceBundle,
-        profile: dict[str, Any] | None = None,
-    ) -> CodeFindings | None:
-        """Run PydanticAI-powered code quality analysis.
-
-        Uses the CodeFindings output model for typed, validated results
-        with automatic confidence-based retry logic.
-
-        Args:
-            evidence: EvidenceBundle with git_evidence to analyze.
-            profile: Optional project profile for context.
-
-        Returns:
-            CodeFindings instance with structured analysis results,
-            or None if analysis fails.
-        """
-        # Prepare code samples for analysis using CodePackBuilder (TSK-196)
-        repo_path = self._get_repo_path(evidence, profile)
-        code_samples = ""
-
-        if repo_path:
-            try:
-                runtime_config = None
-                runtime_config_getter = getattr(self, "_get_runtime_config", None)
-                if callable(runtime_config_getter):
-                    runtime_config = runtime_config_getter()
-
-                max_files = 20
-                max_total_chars: int | None = None
-                if runtime_config is not None and hasattr(runtime_config, "llm"):
-                    llm_cfg = runtime_config.llm
-                    max_files = int(getattr(llm_cfg, "code_review_max_files", max_files))
-                    max_total_chars = int(
-                        getattr(llm_cfg, "code_review_max_total_chars", self.MAX_TOTAL_CODE_CONTEXT_CHARS)
-                    )
-
-                builder = CodePackBuilder(repo_path)
-                pack = builder.build()
-                selected_files = self._select_files_for_llm(
-                    pack,
-                    max_files=max_files,
-                    max_total_chars=max_total_chars,
-                )
-                code_samples = self._format_code_pack(pack, files=selected_files)
-                self.logger.info("code_pack_used", files=pack.total_files_included, scanned=pack.total_files_scanned)
-                self.logger.info(
-                    "code_pack_selected_for_pydantic_analysis",
-                    selected=len(selected_files),
-                    source_files=sum(1 for file_ev in selected_files if self._is_source_code_file(file_ev.file_path)),
-                )
-            except CODE_PACK_RECOVERABLE_ERRORS as e:
-                self.logger.warning(
-                    "code_pack_build_failed",
-                    error=str(e),
-                    error_type=type(e).__name__,
-                    handler="_run_pydantic_code_analysis.code_pack_builder",
-                    repo_path=str(repo_path),
-                )
-                # Fallback will happen below if code_samples is empty
-
-        if not code_samples:
-            # Fallback to legacy preparation
-            max_files = 5
-            max_chars_per_file = 3000
-            runtime_config = None
-            runtime_config_getter = getattr(self, "_get_runtime_config", None)
-            if callable(runtime_config_getter):
-                runtime_config = runtime_config_getter()
-            if runtime_config is not None and hasattr(runtime_config, "llm"):
-                llm_cfg = runtime_config.llm
-                max_files = min(max(1, int(getattr(llm_cfg, "code_review_max_files", max_files))), 10)
-                total_chars = int(getattr(llm_cfg, "code_review_max_total_chars", self.MAX_TOTAL_CODE_CONTEXT_CHARS))
-                max_chars_per_file = max(1000, total_chars // max(1, max_files))
-            code_samples = self._prepare_code_samples(
-                evidence,
-                max_files=max_files,
-                max_chars_per_file=max_chars_per_file,
-            )
-
-        if not code_samples:
-            self.logger.info("no_code_samples_available")
-            return None
-
-        # Construct the analysis prompt
-        user_prompt = self._build_analysis_prompt(code_samples, evidence, profile)
-
-        if self.settings.protocol == LLMProtocolType.OPENAI and self._uses_local_openai_protocol():
-            return await self._run_ollama_code_analysis_direct(user_prompt=user_prompt)
-
-        # Build dependencies for PydanticAI agent
-        deps = AuditDeps.from_evidence_bundle(
-            evidence=evidence,
-            profile=profile,
-            settings=self.settings,
-            evidence_corpus=self._evidence_corpus,
-        )
-
-        # Run the PydanticAI agent
-        try:
-            output = await self._run_pydantic_agent(
-                system_prompt=CODE_ANALYSIS_SYSTEM_PROMPT,
-                user_prompt=user_prompt,
-                result_type=CodeFindings,
-                complexity="standard",
-                deps=deps,
-            )
-            return output
-        except Exception as e:
-            self.logger.warning(
-                "pydantic_ai_agent_failed",
-                error=str(e),
-                error_type=type(e).__name__,
-            )
-            raise
-
-    async def _run_ollama_code_analysis_direct(self, *, user_prompt: str) -> CodeFindings:
-        """Run CodeFindings generation via direct Ollama messages API.
-
-        OLLAMA's OpenAI-compat endpoint can reject certain assistant message shapes
-        emitted by structured-output runtimes. This path uses the native Ollama
-        messages wrapper and validates JSON into CodeFindings.
-        """
-        client = self.settings.get_client()
-        model_name = self.settings.select_model("standard") if hasattr(self.settings, "select_model") else None
-        selected_model = model_name or self.settings.model_standard
-        options: dict[str, Any] = {}
-        ollama_num_ctx = getattr(self.settings, "ollama_num_ctx", None)
-        if isinstance(ollama_num_ctx, int) and ollama_num_ctx > 0:
-            options["num_ctx"] = ollama_num_ctx
-
-        def _create_message():
-            return client.messages.create(
-                model=selected_model,
-                max_tokens=self.settings.max_tokens_per_request,
-                temperature=0.0,
-                system=CODE_ANALYSIS_SYSTEM_PROMPT,
-                messages=[{"role": "user", "content": user_prompt}],
-                format="json",
-                options=options,
-            )
-
-        message = await asyncio.to_thread(_create_message)
-        content_parts: list[str] = []
-        for block in getattr(message, "content", []) or []:
-            text = getattr(block, "text", None)
-            if text:
-                content_parts.append(text)
-        response_text = "\n".join(content_parts).strip()
-        payload = self._strip_json_fence(response_text)
-        try:
-            return CodeFindings.model_validate_json(payload)
-        except STRUCTURED_OUTPUT_RECOVERABLE_ERRORS as exc:
-            self.logger.debug(
-                "ollama_code_findings_json_parse_retry",
-                error_type=type(exc).__name__,
-            )
-            start = payload.find("{")
-            end = payload.rfind("}")
-            if 0 <= start < end:
-                return CodeFindings.model_validate_json(payload[start : end + 1])
-            raise
-
-    def _format_code_pack(self, pack: Any, files: list[Any] | None = None) -> str:
-        """Format CodeEvidencePack for prompt.
-
-        Args:
-            pack: CodeEvidencePack instance.
-
-        Returns:
-            Formatted string.
-        """
-        selected_files = files or pack.files
-        parts = [
-            f"Code Evidence Pack (Selected Files: {len(selected_files)} / {pack.total_files_included})",
-            "Selected file list:",
-        ]
-        parts.extend(f"- {file_ev.file_path}" for file_ev in selected_files)
-        parts.append("")
-
-        for file_ev in selected_files:
-            header = f"### File: {file_ev.file_path}"
-            if file_ev.priority <= 2:
-                header += " [HIGH PRIORITY]"
-            if file_ev.truncated:
-                header += " [TRUNCATED]"
-
-            parts.append(f"{header}\n```\n{file_ev.content}\n```\n")
-
-        return "\n".join(parts)
-
-    def _select_files_for_llm(
-        self,
-        code_pack: CodeEvidencePack,
-        max_files: int = 20,
-        max_infra_files: int = 6,
-        min_source_files: int = 12,
-        max_total_chars: int | None = None,
-    ) -> list[Any]:
-        """Select a source-first subset of files for LLM input quality.
-
-        Args:
-            code_pack: Code evidence pack to select from.
-            max_files: Maximum number of files to select.
-            max_infra_files: Maximum infrastructure files (priority <= 5).
-            min_source_files: Minimum source code files to include.
-            max_total_chars: Total content character budget. Defaults to
-                ``MAX_TOTAL_CODE_CONTEXT_CHARS`` when *None*.
-
-        Returns:
-            Selected file list, ordered by priority then path, within budget.
-        """
-        if not code_pack.files:
-            return []
-
-        effective_budget = max_total_chars if max_total_chars is not None else self.MAX_TOTAL_CODE_CONTEXT_CHARS
-        effective_max_infra_files = min(max_infra_files, max(1, max_files // 6))
-        per_file_budget_cap = max(1200, effective_budget // max(1, max_files))
-        infra_file_budget_cap = min(4000, per_file_budget_cap)
-        source_file_budget_cap = max(per_file_budget_cap, min(6000, per_file_budget_cap * 2))
-
-        sorted_files = sorted(code_pack.files, key=lambda file_ev: (file_ev.priority, file_ev.file_path))
-
-        security_path_tokens = (
-            "security",
-            "auth",
-            "token",
-            "credential",
-            "password",
-            "secret",
-            "sql",
-            "query",
-            "db",
-            "store",
-            "state",
-            "agent",
-            "workflow",
-            "llm",
-            "provider",
-        )
-
-        def _source_rank(file_ev: Any) -> tuple[int, int, int, str]:
-            normalized = str(getattr(file_ev, "file_path", "")).replace("\\", "/").lower()
-            security_relevant = 0 if any(token in normalized for token in security_path_tokens) else 1
-            tests_penalty = 1 if normalized.startswith("tests/") or "/tests/" in normalized else 0
-            content_len = len(getattr(file_ev, "content", "") or "")
-            oversized_penalty = 1 if content_len > source_file_budget_cap else 0
-            return (security_relevant, tests_penalty, oversized_penalty, normalized)
-
-        source_files = sorted(
-            [file_ev for file_ev in sorted_files if self._is_source_code_file(file_ev.file_path)],
-            key=_source_rank,
-        )
-        source_files_non_truncated = [
-            file_ev for file_ev in source_files if not bool(getattr(file_ev, "truncated", False))
-        ]
-        source_files_truncated = [file_ev for file_ev in source_files if bool(getattr(file_ev, "truncated", False))]
-        source_files = source_files_non_truncated
-        infra_files = [
-            file_ev
-            for file_ev in sorted_files
-            if (
-                file_ev.priority <= 5
-                and not self._is_source_code_file(file_ev.file_path)
-                and Path(str(file_ev.file_path)).name.lower() not in {"readme", "readme.md", "readme.rst", "readme.txt"}
-            )
-        ]
-        other_files = [
-            file_ev for file_ev in sorted_files if file_ev not in source_files and file_ev not in infra_files
-        ]
-
-        selected: list[Any] = []
-        total_chars = 0
-
-        def _clone_with_budget(file_ev: Any, budget: int) -> Any:
-            content = getattr(file_ev, "content", "") or ""
-            if len(content) <= budget:
-                return file_ev
-            truncated_content = content[: max(0, budget)]
-            if hasattr(file_ev, "model_copy"):
-                return file_ev.model_copy(update={"content": truncated_content, "truncated": True})
-            candidate = file_ev
-            candidate.content = truncated_content
-            candidate.truncated = True
-            return candidate
-
-        def _try_add(file_ev: Any, *, file_budget_cap: int | None = None) -> bool:
-            """Add file if within char budget. Returns True if added."""
-            nonlocal total_chars
-            content = getattr(file_ev, "content", "") or ""
-            content_len = len(content)
-            remaining = max(0, effective_budget - total_chars)
-            if remaining <= 0:
-                return False
-
-            candidate = file_ev
-            if file_budget_cap is not None and content_len > file_budget_cap:
-                # Prefer complete files; avoid adding partial excerpts unless this is
-                # the first/only candidate we can include.
-                if selected:
-                    return False
-                candidate = _clone_with_budget(file_ev, file_budget_cap)
-                content_len = len(getattr(candidate, "content", "") or "")
-                if content_len <= 0:
-                    return False
-
-            if content_len > remaining:
-                if selected:
-                    return False
-                # Hard-cap the very first file to keep prompt context within budget.
-                candidate = _clone_with_budget(candidate, remaining)
-                content_len = len(getattr(candidate, "content", "") or "")
-                if content_len <= 0:
-                    return False
-
-            selected.append(candidate)
-            total_chars += content_len
-            return True
-
-        # Keep core infra context but cap it to avoid drowning source implementation.
-        for f in infra_files[:effective_max_infra_files]:
-            if len(selected) >= max_files:
-                break
-            if not _try_add(f, file_budget_cap=infra_file_budget_cap):
-                continue
-
-        source_slots = max(0, max_files - len(selected))
-        target_source = min(
-            len(source_files_non_truncated),
-            source_slots,
-        )
-        for f in source_files_non_truncated[:target_source]:
-            if len(selected) >= max_files:
-                break
-            if not _try_add(f, file_budget_cap=source_file_budget_cap):
-                continue
-
-        selected_source_count = sum(1 for f in selected if self._is_source_code_file(getattr(f, "file_path", "")))
-        if selected_source_count < min_source_files:
-            needed_source = min_source_files - selected_source_count
-            for f in source_files_truncated:
-                if needed_source <= 0 or len(selected) >= max_files:
-                    break
-                if not _try_add(f, file_budget_cap=source_file_budget_cap):
-                    continue
-                needed_source -= 1
-
-        for file_ev in source_files_non_truncated[target_source:] + source_files_truncated + other_files:
-            if len(selected) >= max_files:
-                break
-            per_file_cap = (
-                source_file_budget_cap if self._is_source_code_file(file_ev.file_path) else infra_file_budget_cap
-            )
-            if not _try_add(file_ev, file_budget_cap=per_file_cap):
-                continue
-
-        # Guarantee at least one source file in selection when available; this avoids
-        # infra-only contexts on tight budgets (e.g., large README consuming all chars).
-        selected_has_source = any(self._is_source_code_file(f.file_path) for f in selected)
-        if source_files and not selected_has_source:
-            source_budget = max(1000, effective_budget // 2)
-            source_candidate = _clone_with_budget(source_files[0], source_budget)
-            source_len = len(getattr(source_candidate, "content", "") or "")
-            if source_len > 0:
-                while selected and (total_chars + source_len > effective_budget):
-                    removed = selected.pop()
-                    total_chars = max(0, total_chars - len(getattr(removed, "content", "") or ""))
-                if total_chars + source_len <= effective_budget:
-                    selected.append(source_candidate)
-                    total_chars += source_len
-
-        # Deduplicate while preserving order
-        deduped: list[Any] = []
-        seen: set[str] = set()
-        for file_ev in selected:
-            if file_ev.file_path in seen:
-                continue
-            seen.add(file_ev.file_path)
-            deduped.append(file_ev)
-
-        dropped = len(code_pack.files) - len(deduped)
-        if dropped > 0:
-            self.logger.info(
-                "llm_file_selection_budget_applied",
-                selected=len(deduped),
-                dropped=dropped,
-                total_chars=total_chars,
-                budget=effective_budget,
-                max_files=max_files,
-            )
-
-        return deduped[:max_files]
-
-    def _is_source_code_file(self, file_path: str) -> bool:
-        normalized = file_path.replace("\\", "/").lower()
-        if normalized.startswith("src/") or "/src/" in normalized:
-            return True
-        return normalized.endswith((".py", ".java", ".kt", ".kts", ".js", ".ts", ".tsx", ".go", ".rb", ".php"))
-
-    def _build_analysis_prompt(
-        self,
-        code_samples: str,
-        evidence: EvidenceBundle,
-        profile: dict[str, Any] | None = None,
-    ) -> str:
-        """Build the analysis prompt for the PydanticAI agent.
-
-        Args:
-            code_samples: Formatted code samples string.
-            evidence: EvidenceBundle for context.
-            profile: Optional project profile.
-
-        Returns:
-            Formatted user prompt string.
-        """
-        context_parts = []
-
-        if profile:
-            domain = profile.get("domain", "unknown")
-            criticality = profile.get("criticality", "unknown")
-            context_parts.append(f"Project Context: Domain={domain}, Criticality={criticality}")
-
-        if evidence.repository:
-            context_parts.append(f"Repository: {evidence.repository}")
-
-        file_count = len(evidence.git_evidence)
-        context_parts.append(f"Total files in evidence: {file_count}")
-
-        context = "\n".join(context_parts) if context_parts else "No additional context"
-        evidence_context = ""
-        if self._evidence_corpus:
-            evidence_context = "\n\n" + self._evidence_corpus.get_context_summary(max_chars=2500)
-
-        return f"""Analyze the following code files for quality, security, and maintainability issues.
-
-## Context
-{context}
-{evidence_context}
-
-## Code Files
-{code_samples}
-
-Provide a comprehensive analysis with:
-1. Overall quality score (0-10)
-2. Specific issues found (with file paths and recommendations)
-3. Detected patterns (positive practices and anti-patterns)
-4. Your confidence level in the analysis
-5. Clear reasoning for your assessment"""
-
-    def _build_agentic_investigation_prompt(
-        self,
-        *,
-        evidence: EvidenceBundle,
-        profile: dict[str, Any] | None,
-        repo_path: Path,
-        evidence_corpus: EvidenceCorpus | None,
-        skills_available: bool,
-        available_skill_names: list[str] | None = None,
-        vector_docs_required: bool = False,
-        preloaded_skill_context: str = "",
-        postgres_evidence_ready: bool = False,
-        compact_mode: bool = False,
-        strict_skill_required: bool = True,
-        skills_needed: bool = False,
-        skills_needed_reason: str = "",
-    ) -> str:
-        """Build a minimal, tool-first prompt for AGENTIC mode.
-
-        Intentionally avoids embedding large code snippets. The agent should
-        retrieve required code/docs via attached toolsets.
-        """
-        evidence_path_diagnostics = self._build_agentic_evidence_path_diagnostics(
-            evidence=evidence,
-            repo_path=repo_path,
-        )
-
-        context_lines: list[str] = [
-            f"Repository path: {repo_path}",
-            f"Repository name: {evidence.repository}",
-            f"Git evidence files available: {len(evidence.git_evidence)}",
-        ]
-
-        state_context = dict(self._state_context) if isinstance(self._state_context, dict) else {}
-        search_strategy_guidance = ""
-
-        if state_context:
-            raw_analysis = state_context.get("requirement_analysis_result")
-            if not raw_analysis:
-                raw_analysis = state_context.get("context", {}).get("requirement_analysis_result")
-            if raw_analysis:
-                analysis_res = RequirementAnalysisResult.from_mapping(raw_analysis)
-                if analysis_res:
-                    # Phase 123 (DD-123.9): Thread guidance text for shared-library promotion.
-                    _interp = state_context.get("context", {}).get("requirement_interpretation") or {}
-                    _guidance = str(_interp.get("detailed_guidance") or "") if isinstance(_interp, dict) else ""
-                    strategy_hint = derive_code_search_strategy(
-                        analysis_res,
-                        requirement_text=str(state_context.get("requirement_text") or ""),
-                        category=str(state_context.get("requirement_category") or ""),
-                        guidance_text=_guidance,
-                    )
-                    if strategy_hint is not None:
-                        search_strategy_guidance = _render_phase115_strategy_guidance(strategy_hint)
-
-        if state_context:
-            project_storage_key = str(state_context.get("project_storage_key") or "").strip()
-            repo_storage_key = str(state_context.get("repo_storage_key") or "").strip()
-            resolved_project = str(state_context.get("resolved_project") or "").strip()
-            if project_storage_key:
-                context_lines.append(f"State project key: {project_storage_key}")
-            if repo_storage_key:
-                context_lines.append(f"State repo key: {repo_storage_key}")
-            if resolved_project:
-                context_lines.append(f"Resolved project alias: {resolved_project}")
-
-        if profile:
-            domain = profile.get("domain", "unknown")
-            criticality = profile.get("criticality", "unknown")
-            context_lines.append(f"Project context: domain={domain}, criticality={criticality}")
-
-        sample_limit = 10 if compact_mode else 25
-        sample_paths = [str(item.source_id).strip() for item in evidence.git_evidence[:sample_limit] if item.source_id]
-        if sample_paths:
-            context_lines.append("Example candidate files from evidence seed:")
-            context_lines.extend(f"- {path}" for path in sample_paths)
-
-        docs_count = len(evidence_corpus.documents) if evidence_corpus is not None else 0
-        if docs_count > 0:
-            context_lines.append(f"Evidence corpus documents available: {docs_count}")
-            context_lines.append(
-                "Use list_evidence_documents/search_evidence/read_evidence_document for docs retrieval."
-            )
-            context_lines.append(
-                "Docs location guard: keep retrieval scoped to current project context; avoid cross-project docs unless explicitly required."
-            )
-            if postgres_evidence_ready:
-                context_lines.append(
-                    "State-backed evidence retrieval available (Postgres): prioritize targeted queries over broad scans."
-                )
-            if vector_docs_required:
-                context_lines.append(
-                    "Vector retrieval available: use search_evidence_vector for docs and search_code_vector for code grounding."
-                )
-        elif postgres_evidence_ready or vector_docs_required:
-            context_lines.append("Local evidence corpus is empty for this run.")
-            if postgres_evidence_ready:
-                context_lines.append(
-                    "State-backed evidence retrieval available (Postgres): use retrieval tools instead of broad repository scans."
-                )
-            if vector_docs_required:
-                context_lines.append(
-                    "Vector retrieval available: call search_evidence_vector (docs) or search_code_vector (code) for requirement-level grounding."
-                )
-        else:
-            context_lines.append("Evidence corpus unavailable for this run.")
-        if skills_available:
-            context_lines.append(
-                "Skill activation decision: "
-                f"skills_needed={'true' if skills_needed else 'false'}"
-                + (f" (reason={skills_needed_reason})" if str(skills_needed_reason).strip() else "")
-            )
-            context_lines.append(
-                "Skills toolset available: use skills only when directly useful; list_skills is discovery, not sufficient evidence by itself."
-            )
-            if preloaded_skill_context:
-                context_lines.append(
-                    "Preloaded skill guidance is already attached; avoid calling list_skills unless preloaded guidance is missing required details."
-                )
-            if available_skill_names:
-                context_lines.append("Available skills (policy-allowed):")
-                context_lines.extend(f"- {name}" for name in available_skill_names[:8])
-            if not skills_needed:
-                context_lines.append(
-                    "Skill policy: skills_needed=false for this run; keep skill usage optional and only call skill tools when they directly improve evidence quality."
-                )
-        else:
-            context_lines.append("Skills toolset unavailable for this run.")
-            if skills_needed:
-                context_lines.append(
-                    "Skill policy fallback: skills were requested but toolset is unavailable; continue without skill calls."
-                )
-
-        context = "\n".join(context_lines)
-        preloaded_skill_section = ""
-        if preloaded_skill_context:
-            preloaded_skill_section = (
-                "\n## Preloaded Skill Guidance\n"
-                "Use this as immediate run guidance without requiring initial skill discovery calls:\n"
-                f"{preloaded_skill_context}\n"
-            )
-        self._log_trace_payload(
-            event_name="agentic_trace_evidence_context_assembly",
-            elapsed_sec=0.0,
-            payload={
-                "repo_path": str(repo_path),
-                "repository": evidence.repository,
-                "evidence_path_diagnostics": evidence_path_diagnostics,
-                "context_line_count": len(context_lines),
-                "docs_available": docs_count > 0,
-                "docs_document_count": docs_count,
-                "skills_available": skills_available,
-                "available_skill_names": list(available_skill_names or [])[:8],
-                "vector_docs_required": vector_docs_required,
-                "preloaded_skill_context_chars": len(preloaded_skill_context),
-                "postgres_evidence_ready": postgres_evidence_ready,
-                "compact_mode": compact_mode,
-                "skills_needed": skills_needed,
-                "skills_needed_reason": str(skills_needed_reason or ""),
-                "strict_skill_required": strict_skill_required,
-            },
-        )
-        compact_skill_guidance = (
-            "9. Requirement-driven skill policy: skills_needed=false, so skill usage is optional and should be used only for clear evidence gains."
-            if not skills_needed
-            else (
-                "9. Requirement-driven skill policy: skills_needed=true, so prioritize one effective skill sequence "
-                "(load_skill -> read_skill_resource/run_skill_script) when it materially improves grounding."
-            )
-        )
-
-        interpretation = self._extract_requirement_interpretation_from_state_context(state_context)
-        evidence_targets = []
-        is_arch_requirement = False
-        if isinstance(interpretation, dict):
-            evidence_targets = [str(t).lower() for t in interpretation.get("evidence_targets", [])]
-            combined_arch = f"{interpretation.get('intent', '')} {interpretation.get('control_objective', '')}".lower()
-            is_arch_requirement = any(
-                marker in combined_arch
-                for marker in (
-                    "hexagonal",
-                    "clean architecture",
-                    "ports",
-                    "adapters",
-                    "domain logic",
-                    "domain",
-                    "kiến trúc",
-                    "phân lớp",
-                )
-            )
-
-        docs_guidance = ""
-        if is_arch_requirement:
-            docs_guidance = "\n10. Architecture Policy: This is a Clean Architecture requirement. Use `ast_grep_search` with pattern `import $A` to check cross-boundary imports (e.g. domain importing infrastructure or framework like @Entity/@Table). Do not guess dependencies without structural search."
-        elif "docs" in evidence_targets and "code" not in evidence_targets:
-            docs_guidance = "\n10. Docs-First Policy: This requirement relies exclusively on documentation (SLA, Support). ALWAYS call search_docs or search_evidence_vector BEFORE any code search. Source code rarely contains explicit SLA contracts."
-        elif "docs" in evidence_targets:
-            docs_guidance = "\n10. Hybrid Evidence Policy: This requirement needs both documentation and code. Start with search_docs or search_evidence_vector to understand the design, then use code tools to verify implementation."
-
-        if compact_mode:
-            return f"""Perform code quality and security analysis using TOOL-FIRST investigation.
-
-## Run Context
-{context}
-{preloaded_skill_section}
-
-## Required Approach
-1. Start with grep_search or rg_search, then read_file on a concrete hit.
-2. Use focused reads only; avoid directory-chaining loops.
-3. If state/vector retrieval is available, call search_evidence_vector or search_code_vector at least once before final answer.
-4. Correlate findings with concrete file paths and line ranges when possible.
-5. Call exactly one tool per turn and inspect result before the next call.
-6. If path errors repeat twice, pivot to grep_search/rg_search and continue.
-7. Avoid repeating the same tool pattern more than twice without new evidence.
-8. Do not execute exhaustive checklist probing; use at most 6 total tool calls unless critical evidence is still missing.
-{compact_skill_guidance}{docs_guidance}
-{search_strategy_guidance}
-
-## Output
-Provide:
-1. Overall score (0-10)
-2. Concrete issues (severity, file path, recommendation)
-3. Positive/negative patterns observed
-4. Confidence and concise reasoning
-"""
-        if skills_available and skills_needed:
-            skill_guidance = (
-                "10. Requirement-driven skills activation: skills_needed=true.\n"
-                "   - Prefer one effective sequence in the first 2 turns when it materially improves grounding:\n"
-                '   - load_skill(name="<available-skill-name>")\n'
-                '   - read_skill_resource(name="<available-skill-name>", resource_path="<resource-from-load-skill>") '
-                "or run_skill_script when explicitly available.\n"
-                "   - Skip list_skills when available skills are already listed in Run Context.\n"
-                "   - Do not call run_skill_script unless the loaded skill explicitly lists scripts in the load_skill result.\n"
-                f"   - {'This step is mandatory in this strict run.' if strict_skill_required else 'This step is optional in this run when strict skill enforcement is disabled.'}"
-            )
-        elif skills_available:
-            skill_guidance = (
-                "10. Requirement-driven skills activation: skills_needed=false.\n"
-                "   - Skill usage remains optional; avoid discovery-only churn.\n"
-                "   - Use skill tools only when they provide direct, row-specific evidence gains.\n"
-                "   - Keep analysis grounded with repository and evidence retrieval tools first."
-            )
-        else:
-            skill_guidance = "10. Skills toolset unavailable for this run; do not emit skill tool calls and continue with repository/docs tools."
-
-        docs_guidance_nc = ""
-        if is_arch_requirement:
-            docs_guidance_nc = "\n14. Architecture Policy: This is a Clean Architecture requirement. Use `ast_grep_search` with pattern `import $A` to check cross-boundary imports (e.g. domain importing infrastructure or framework like @Entity/@Table). Do not guess dependencies without structural search."
-        elif "docs" in evidence_targets and "code" not in evidence_targets:
-            docs_guidance_nc = "\n14. Docs-First Policy: This requirement relies exclusively on documentation (SLA, Support). ALWAYS call search_docs or search_evidence_vector BEFORE any code search. Source code rarely contains explicit SLA contracts."
-        elif "docs" in evidence_targets:
-            docs_guidance_nc = "\n14. Hybrid Evidence Policy: This requirement needs both documentation and code. Start with search_docs or search_evidence_vector to understand the design, then use code tools to verify implementation."
-
-        return f"""Perform code quality and security analysis using TOOL-FIRST investigation.
-
-## Run Context
-{context}
-{preloaded_skill_section}
-
-## Required Approach
-1. Use repository exploration tools to locate relevant implementation files.
-2. In the first two repository calls, follow cadence: discovery (grep_search/rg_search preferred) then read_file on a concrete hit.
-3. Read only focused files/sections needed to justify findings.
-4. If evidence corpus is available, call search_evidence and then read_evidence_document for at least one matched ref.
-5. If vector retrieval is available, call search_evidence_vector (docs) or search_code_vector (code) at least once before final answer.
-6. If state-backed retrieval is available, prioritize Postgres-backed evidence queries for requirement-level grounding.
-7. Correlate findings with concrete file paths and, where possible, line ranges.
-8. Before final answer, complete at least one repository tool call and at least one code-read/navigation call.
-9. Call exactly one tool per turn, then inspect the result before next call.
-   This step cadence is enforced by runtime caps (`agentic.max_turns`, `agentic.max_tool_calls`).
-{skill_guidance}
-11. Avoid repetitive loops: do not repeat the same tool pattern more than twice without new evidence.
-12. If search_evidence/search_evidence_vector/search_code_vector returns no useful hit twice, pivot to grep_search/rg_search/read_file or conclude evidence is insufficient.
-13. If a tool returns `[ERROR] Not a directory` or `[ERROR] Not a file` twice, stop path guessing.
-    Pivot immediately to grep_search/rg_search to discover exact paths, then read_file on discovered files.{docs_guidance_nc}
-{search_strategy_guidance}
-
-## Output
-Provide:
-1. Overall score (0-10)
-2. Concrete issues (severity, file path, recommendation)
-3. Positive/negative patterns observed
-4. Confidence and concise reasoning
-"""
-
-    def _build_agentic_evidence_path_diagnostics(
-        self,
-        *,
-        evidence: EvidenceBundle,
-        repo_path: Path,
-    ) -> dict[str, Any]:
-        """Summarize evidence path composition for trace-level diagnosability."""
-        repo_root = repo_path.resolve()
-        raw_paths = [str(item.source_id).strip() for item in evidence.git_evidence if item.source_id]
-        unique_paths = list(dict.fromkeys(path for path in raw_paths if path))
-
-        absolute_count = 0
-        relative_count = 0
-        inside_repo_count = 0
-        outside_repo_count = 0
-        resolve_error_count = 0
-        basename_counts: dict[str, int] = {}
-
-        for raw_path in unique_paths:
-            path = Path(raw_path)
-            if path.is_absolute():
-                absolute_count += 1
-                candidate = path
-            else:
-                relative_count += 1
-                candidate = repo_root / path
-
-            basename = path.name
-            basename_counts[basename] = basename_counts.get(basename, 0) + 1
-            try:
-                resolved = candidate.resolve()
-            except PATH_RESOLUTION_RECOVERABLE_ERRORS:
-                resolve_error_count += 1
-                continue
-
-            if resolved == repo_root or repo_root in resolved.parents:
-                inside_repo_count += 1
-            else:
-                outside_repo_count += 1
-
-        fragmented_basename_count = sum(1 for count in basename_counts.values() if count > 1)
-        return {
-            "total_evidence_files": len(evidence.git_evidence),
-            "with_source_id": len(raw_paths),
-            "missing_source_id": max(0, len(evidence.git_evidence) - len(raw_paths)),
-            "unique_source_paths": len(unique_paths),
-            "absolute_path_count": absolute_count,
-            "relative_path_count": relative_count,
-            "resolved_inside_repo_count": inside_repo_count,
-            "resolved_outside_repo_count": outside_repo_count,
-            "resolve_error_count": resolve_error_count,
-            "fragmented_basename_count": fragmented_basename_count,
-            "sample_paths": unique_paths[:12],
-        }