@ngocsangairvds/vsaf 3.2.14 → 3.2.16

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

@@ -1,3822 +0,0 @@
-"""Centralized tool registry for tool-first row analysis (Phase 61).
-
-Provides strict typed schemas for tool requests/responses and a lightweight
-registry that can be extended with real tool handlers incrementally.
-"""
-
-from __future__ import annotations
-
-import json
-import os
-import re
-import subprocess
-import unicodedata
-from collections.abc import Callable, Mapping
-from enum import StrEnum
-from pathlib import Path
-from typing import Any, Literal, cast
-from urllib.parse import parse_qs, urlparse
-
-import structlog
-from pydantic import AliasChoices, BaseModel, ConfigDict, Field, ValidationError, field_validator
-from vds_cli_common.paths import get_vds_cache_root
-
-from vds_audit_orchestrator.engine.project_topology import RepoRole, classify_repo_role
-from vds_audit_orchestrator.evidence.code_pack import CodeEvidencePack, CodePackBuilder
-from vds_audit_orchestrator.evidence.embedding_client import OllamaEmbeddingClient
-from vds_audit_orchestrator.evidence.query_service import StateBackedEvidenceQueryAdapter
-from vds_audit_orchestrator.state.store import PostgresStateStore
-
-_log = structlog.get_logger(__name__)
-
-
-class _StrictModel(BaseModel):
-    """Strict base model for tool IO payloads."""
-
-    model_config = ConfigDict(extra="forbid", strict=True)
-
-
-class ToolName(StrEnum):
-    """Supported tool names for Phase 61 scaffolding."""
-
-    SEARCH_DOCS = "search_docs"
-    SEARCH_CODE = "search_code"
-    READ_DOC_CHUNK = "read_doc_chunk"
-    READ_CODE_FILE = "read_code_file"
-    GET_ROW_CONTEXT = "get_row_context"
-    RECORD_EVIDENCE_REFS = "record_evidence_refs"
-    LIST_SKILLS = "list_skills"
-    LOAD_SKILL = "load_skill"
-    READ_SKILL_RESOURCE = "read_skill_resource"
-    RUN_SKILL_SCRIPT = "run_skill_script"
-    AST_GREP_CODE_SEARCH = "ast_grep_code_search"
-
-
-class SearchHit(_StrictModel):
-    ref: str
-    read_ref: str | None = None
-    title: str | None = None
-    score: float = Field(default=0.0, ge=0.0, le=1.0)
-    excerpt: str | None = None
-    chunk_id: str | None = None
-    document_id: str | None = None
-    page_id: str | None = None
-    page_title: str | None = None
-    space_key: str | None = None
-    source_url: str | None = None
-    source_type: str | None = None
-    doc_class: str | None = None
-
-
-class EvidenceRef(_StrictModel):
-    ref_type: str
-    ref_value: str
-    verified: bool = False
-    line_range: tuple[int, int] | None = None
-    page_id: str | None = None
-    source_url: str | None = Field(default=None, validation_alias=AliasChoices("source_url", "source_uri"))
-    page_title: str | None = None
-    chunk_id: str | None = None
-    excerpt: str | None = None
-    verification_reason: str | None = None
-    ref_hash: str | None = None
-
-    @field_validator("line_range", mode="before")
-    @classmethod
-    def _coerce_line_range(cls, value: Any) -> Any:
-        if value is None:
-            return None
-        if isinstance(value, list) and len(value) == 2:
-            return (value[0], value[1])
-        if isinstance(value, tuple) and len(value) == 2:
-            return value
-        if isinstance(value, str):
-            match = re.match(r"^\s*(\d+)\s*[:,-]\s*(\d+)\s*$", value)
-            if match:
-                return (int(match.group(1)), int(match.group(2)))
-        return value
-
-
-class SearchDocsInput(_StrictModel):
-    query: str = Field(min_length=1)
-    limit: int = Field(default=5, ge=1, le=50)
-
-
-class SearchDocsOutput(_StrictModel):
-    hits: list[SearchHit] = Field(default_factory=list)
-
-
-class SearchCodeInput(_StrictModel):
-    query: str = Field(min_length=1)
-    limit: int = Field(default=5, ge=1, le=50)
-    scope: Literal["code", "config", "lib", "all"] = Field(
-        default="code",
-        description="Evidence scope: 'code' for source files, 'config' for configuration files, 'lib' for shared libraries, 'all' for everything",
-    )
-    config_root_filter: str | None = Field(
-        default=None,
-        description="Optional config-root selector when scope is 'config' or 'all' (for example 'app-config')",
-    )
-    use_vector: bool = False
-
-
-class SearchCodeHit(_StrictModel):
-    ref: str
-    title: str | None = None
-    score: float = Field(default=0.0, ge=0.0, le=1.0)
-    excerpt: str | None = None
-    source: Literal["code", "config", "lib"]
-    retrieval_mode: Literal["lexical", "vector"] = "lexical"
-
-
-class SearchCodeOutput(_StrictModel):
-    hits: list[SearchCodeHit] = Field(default_factory=list)
-
-
-class AstGrepHit(_StrictModel):
-    ref: str
-    line: int
-    excerpt: str
-    language: str | None = None
-
-
-class AstGrepCodeSearchInput(_StrictModel):
-    pattern: str = Field(min_length=1)
-    language: str | None = None
-    include: str | None = None
-    max_results: int = Field(default=50, ge=1, le=500)
-
-
-class AstGrepCodeSearchOutput(_StrictModel):
-    hits: list[AstGrepHit] = Field(default_factory=list)
-
-
-class ReadDocChunkInput(_StrictModel):
-    ref: str = Field(min_length=1)
-    chunk_id: str | None = None
-
-
-class ReadDocChunkOutput(_StrictModel):
-    ref: str
-    chunk_id: str | None = None
-    content: str = ""
-    page_id: str | None = None
-    page_title: str | None = None
-    space_key: str | None = None
-    source_url: str | None = None
-    start_line: int | None = None
-    end_line: int | None = None
-
-
-class ReadCodeFileInput(_StrictModel):
-    path: str = Field(min_length=1)
-    start_line: int | None = Field(default=None, ge=1)
-    end_line: int | None = Field(default=None, ge=1)
-    scope: Literal["code", "config", "lib", "all"] = Field(
-        default="code",
-        description="Evidence scope hint: indicates which evidence domain the file belongs to",
-    )
-    config_root_filter: str | None = Field(
-        default=None,
-        description="Optional config-root selector when reading config files (for example 'app-config')",
-    )
-
-
-class ReadCodeFileOutput(_StrictModel):
-    path: str
-    content: str = ""
-    start_line: int | None = None
-    end_line: int | None = None
-
-
-class GetRowContextInput(_StrictModel):
-    row_id: str = Field(min_length=1)
-    check_id: str = Field(min_length=1)
-    requirement_text: str = ""
-    requirement_category: str | None = None
-    detailed_guidance: str | None = None
-    check_manual: bool = False
-    requirement_interpretation: dict[str, Any] = Field(default_factory=dict)
-    evidence_refs: list[str] = Field(default_factory=list)
-
-
-class GetRowContextOutput(_StrictModel):
-    row_id: str
-    context: dict[str, Any] = Field(default_factory=dict)
-
-
-class RecordEvidenceRefsInput(_StrictModel):
-    row_id: str = Field(min_length=1)
-    refs: list[EvidenceRef] = Field(default_factory=list)
-
-
-class RecordEvidenceRefsOutput(_StrictModel):
-    row_id: str
-    accepted_count: int = 0
-    refs: list[EvidenceRef] = Field(default_factory=list)
-
-
-class SkillInfo(_StrictModel):
-    name: str
-    description: str | None = None
-    trust_tier: str | None = None
-    has_scripts: bool = False
-    path: str
-
-
-class ListSkillsInput(_StrictModel):
-    query: str = ""
-    limit: int = Field(default=20, ge=1, le=100)
-
-
-class ListSkillsOutput(_StrictModel):
-    skills: list[SkillInfo] = Field(default_factory=list)
-
-
-class LoadSkillInput(_StrictModel):
-    name: str = Field(min_length=1, validation_alias=AliasChoices("name", "skill_name"))
-
-
-class LoadSkillOutput(_StrictModel):
-    name: str
-    found: bool = False
-    resolved_name: str | None = None
-    path: str | None = None
-    description: str | None = None
-    trust_tier: str | None = None
-    has_scripts: bool = False
-    resources: list[str] = Field(default_factory=list)
-    scripts: list[str] = Field(default_factory=list)
-    content_hash: str | None = None
-    error: str | None = None
-
-
-class ReadSkillResourceInput(_StrictModel):
-    name: str = Field(min_length=1, validation_alias=AliasChoices("name", "skill_name"))
-    resource_path: str = Field(
-        default="SKILL.md",
-        min_length=1,
-        validation_alias=AliasChoices("resource_path", "resource_name", "path"),
-    )
-    max_chars: int = Field(default=6000, ge=200, le=20000)
-
-
-class ReadSkillResourceOutput(_StrictModel):
-    name: str
-    resource_path: str
-    success: bool = False
-    content: str = ""
-    ref: str | None = None
-    error: str | None = None
-    # P172-F (TSK-172.35): fallback telemetry — set when SKILL.md served instead of the
-    # explicitly requested resource (e.g. references/row-analysis.md was absent).
-    requested_resource_fallback: bool = False
-    fallback_reason: str | None = None
-
-
-class RunSkillScriptInput(_StrictModel):
-    name: str = Field(min_length=1, validation_alias=AliasChoices("name", "skill_name"))
-    script_path: str = Field(min_length=1, validation_alias=AliasChoices("script_path", "script"))
-    args: list[str] = Field(default_factory=list)
-    timeout_seconds: int = Field(default=60, ge=1, le=600)
-
-
-class RunSkillScriptOutput(_StrictModel):
-    name: str
-    script_path: str
-    success: bool = False
-    stdout: str = ""
-    stderr: str = ""
-    returncode: int | None = None
-    error: str | None = None
-
-
-class AstGrepPatternEntry(_StrictModel):
-    pattern: str
-    language: str
-    description: str
-    violation_category: str
-
-
-class ToolCallEnvelope(_StrictModel):
-    """Common wrapper for validated tool invocations."""
-
-    tool: ToolName
-    payload: dict[str, Any] = Field(default_factory=dict)
-
-
-class ToolResponseEnvelope(_StrictModel):
-    """Common wrapper for validated tool responses.
-
-    Accepts both ToolName enum and plain str for compatibility with the
-    core BoundedAgentLoop which passes tool names as strings.
-    """
-
-    tool: ToolName | str
-    payload: dict[str, Any] = Field(default_factory=dict)
-
-
-ToolHandler = Callable[[Any], Any]
-
-
-class ToolExecutionError(RuntimeError):
-    """Machine-readable runtime error for tool execution failures."""
-
-    def __init__(self, code: str, message: str, *, details: dict[str, Any] | None = None) -> None:
-        self.code = str(code).strip() or "tool_execution_error"
-        self.message = str(message).strip() or "Tool execution failed"
-        self.details = dict(details or {})
-        super().__init__(self._as_json())
-
-    def _as_json(self) -> str:
-        return json.dumps(
-            {
-                "error": {
-                    "code": self.code,
-                    "message": self.message,
-                    "details": self.details,
-                },
-            },
-            sort_keys=True,
-        )
-
-
-def _extract_space_key(metadata: dict | Mapping | None) -> str | None:
-    """Extract Confluence space key from document metadata JSON."""
-    if not metadata or not isinstance(metadata, Mapping):
-        return None
-    return metadata.get("space_key") or metadata.get("spaceKey") or None
-
-
-def _extract_page_title(metadata: dict | Mapping | None) -> str | None:
-    """Extract page title from document metadata JSON."""
-    if not metadata or not isinstance(metadata, Mapping):
-        return None
-    for key in ("page_title", "source_page_title", "title", "document_title"):
-        val = str(metadata.get(key) or "").strip()
-        if val:
-            return val
-    return None
-
-
-class ToolRegistry:
-    """Centralized typed tool registry with strict schema validation."""
-
-    _AST_GREP_PATTERNS: dict[str, list[AstGrepPatternEntry]] = {
-        "boundary_violation": [
-            AstGrepPatternEntry(
-                pattern="import javax.persistence.$$$",
-                language="java",
-                description="JPA leak in domain",
-                violation_category="boundary_violation",
-            ),
-            AstGrepPatternEntry(
-                pattern="import javax.persistence.$$$",
-                language="kotlin",
-                description="JPA leak in domain",
-                violation_category="boundary_violation",
-            ),
-            AstGrepPatternEntry(
-                pattern="import org.springframework.$$$",
-                language="java",
-                description="Spring leak in domain",
-                violation_category="boundary_violation",
-            ),
-            AstGrepPatternEntry(
-                pattern="import org.springframework.$$$",
-                language="kotlin",
-                description="Spring leak in domain",
-                violation_category="boundary_violation",
-            ),
-            AstGrepPatternEntry(
-                pattern="import sqlalchemy",
-                language="python",
-                description="ORM leak in domain",
-                violation_category="boundary_violation",
-            ),
-            AstGrepPatternEntry(
-                pattern="from flask import $$$",
-                language="python",
-                description="Framework leak in domain",
-                violation_category="boundary_violation",
-            ),
-        ],
-        "annotation_leak": [
-            AstGrepPatternEntry(
-                pattern="@Entity",
-                language="java",
-                description="@Entity annotation in domain layer",
-                violation_category="annotation_leak",
-            ),
-            AstGrepPatternEntry(
-                pattern="@Entity",
-                language="kotlin",
-                description="@Entity annotation in domain layer",
-                violation_category="annotation_leak",
-            ),
-        ],
-        "dependency_direction": [
-            # Java - Domain importing infrastructure/persistence
-            AstGrepPatternEntry(
-                pattern="import repository.$$$",
-                language="java",
-                description="Domain layer importing repository (infrastructure)",
-                violation_category="dependency_direction",
-            ),
-            AstGrepPatternEntry(
-                pattern="import dao.$$$",
-                language="java",
-                description="Domain layer importing DAO (infrastructure)",
-                violation_category="dependency_direction",
-            ),
-            AstGrepPatternEntry(
-                pattern="import persistence.$$$",
-                language="java",
-                description="Domain layer importing persistence package (infrastructure)",
-                violation_category="dependency_direction",
-            ),
-            AstGrepPatternEntry(
-                pattern="import infrastructure.$$$",
-                language="java",
-                description="Domain layer importing infrastructure directly",
-                violation_category="dependency_direction",
-            ),
-            AstGrepPatternEntry(
-                pattern="import config.$$$",
-                language="java",
-                description="Domain layer importing config (infrastructure)",
-                violation_category="dependency_direction",
-            ),
-            # Kotlin - Domain importing infrastructure/persistence
-            AstGrepPatternEntry(
-                pattern="import repository.$$$",
-                language="kotlin",
-                description="Domain layer importing repository (infrastructure)",
-                violation_category="dependency_direction",
-            ),
-            AstGrepPatternEntry(
-                pattern="import dao.$$$",
-                language="kotlin",
-                description="Domain layer importing DAO (infrastructure)",
-                violation_category="dependency_direction",
-            ),
-            AstGrepPatternEntry(
-                pattern="import persistence.$$$",
-                language="kotlin",
-                description="Domain layer importing persistence package (infrastructure)",
-                violation_category="dependency_direction",
-            ),
-            AstGrepPatternEntry(
-                pattern="import infrastructure.$$$",
-                language="kotlin",
-                description="Domain layer importing infrastructure directly",
-                violation_category="dependency_direction",
-            ),
-            # Python - Domain importing infrastructure/adapters
-            AstGrepPatternEntry(
-                pattern="from infrastructure import $$$",
-                language="python",
-                description="Domain importing infrastructure layer",
-                violation_category="dependency_direction",
-            ),
-            AstGrepPatternEntry(
-                pattern="from adapters import $$$",
-                language="python",
-                description="Domain importing adapters (infrastructure)",
-                violation_category="dependency_direction",
-            ),
-            AstGrepPatternEntry(
-                pattern="from persistence import $$$",
-                language="python",
-                description="Domain importing persistence layer (infrastructure)",
-                violation_category="dependency_direction",
-            ),
-            AstGrepPatternEntry(
-                pattern="from repository import $$$",
-                language="python",
-                description="Domain importing repository module (infrastructure)",
-                violation_category="dependency_direction",
-            ),
-            AstGrepPatternEntry(
-                pattern="import infrastructure",
-                language="python",
-                description="Domain importing infrastructure module",
-                violation_category="dependency_direction",
-            ),
-        ],
-    }
-
-    _UNSET = object()
-    _HIGH_CONFIDENCE_LEXICAL_SCORE = 0.7
-    _CODE_AUTO_READ_WINDOW_RADIUS = 20
-    _CODE_SEARCH_INCLUDE_GLOBS = (
-        "*.py",
-        "*.java",
-        "*.kt",
-        "*.kts",
-        "*.go",
-        "*.ts",
-        "*.tsx",
-        "*.js",
-        "*.jsx",
-        "*.rb",
-        "*.scala",
-        "*.xml",
-        "*.yml",
-        "*.yaml",
-        "*.json",
-        "*.toml",
-        "*.ini",
-        "*.properties",
-        "*.gradle",
-        "*.sh",
-        "*.sql",
-        "Dockerfile*",
-        "docker-compose*.yml",
-        "docker-compose*.yaml",
-    )
-    _CONFIG_SEARCH_INCLUDE_GLOBS = (
-        "*.yaml",
-        "*.yml",
-        "*.json",
-        "*.toml",
-        "*.ini",
-        "*.properties",
-        "*.env",
-        "*.env.*",
-        "*.cfg",
-        "*.conf",
-        "*.config",
-    )
-    _LIB_SEARCH_INCLUDE_GLOBS = (
-        "*.py",
-        "*.java",
-        "*.kt",
-        "*.kts",
-        "*.go",
-        "*.ts",
-        "*.js",
-        "*.rb",
-        "*.scala",
-    )
-    _DOC_EXCLUDED_SOURCE_TYPES = frozenset(
-        {
-            "code",
-            "code_file",
-            "code_evidence_pack",
-            "bitbucket_readme",
-            "generated",
-        }
-    )
-    _DOC_EXCLUDED_DOC_CLASSES = frozenset(
-        {
-            "canonical_code",
-            "report",
-            "runtime_log",
-            "history",
-            "generated_artifact",
-        }
-    )
-    _DOC_EXCLUDED_PATH_MARKERS = (
-        "code_evidence_pack",
-        "reports/verification/",
-        "reports\\verification\\",
-        "reports/audit_runs/",
-        "reports\\audit_runs\\",
-        "project-readiness.json",
-        "audit-checklist",
-        "workflow-summary",
-        "runtime-log-tail",
-        "evidence_context",
-        "batch_timing",
-        "retrieval-trace",
-        "security-evidence",
-        "preflight",
-        "run-history",
-        "audit results",
-    )
-    _DOC_INTENT_KEYWORDS = (
-        "documentation",
-        "document",
-        "tài liệu",
-        "tai lieu",
-        "wiki",
-        "gitbook",
-        "confluence",
-        "version",
-        "phiên bản",
-        "phien ban",
-        "support",
-        "sla",
-        "incident",
-        "hỗ trợ",
-        "ho tro",
-        "quy trình",
-        "quy trinh",
-        "l3",
-    )
-    _CODE_HIGH_SIGNAL_SHORT_TERMS = frozenset(
-        {
-            "db",
-            "sql",
-            "jpa",
-            "orm",
-            "ddl",
-            "dml",
-            "api",
-            "sdk",
-            "sla",
-            "sso",
-        },
-    )
-    _CODE_LOW_SIGNAL_QUERY_TERMS = frozenset(
-        {
-            "kiem",
-            "tra",
-            "yeu",
-            "cau",
-            "phan",
-            "tich",
-            "gom",
-            "dong",
-            "voi",
-            "mot",
-            "nhung",
-        },
-    )
-    _DB_DECOUPLING_QUERY_TERMS = (
-        "database",
-        "schema",
-        "datasource",
-        "connection",
-        "connection string",
-        "entitymanager",
-        "native query",
-        "native sql",
-        "repository",
-        "jdbc",
-        "hibernate",
-        "cơ sở dữ liệu",
-        "co so du lieu",
-        "kết nối",
-        "ket noi",
-        "lược đồ",
-        "luoc do",
-    )
-    _DB_RETRIEVAL_QUERY_EXPANSION = (
-        "datasource",
-        "entitymanager",
-        "createnativequery",
-        "@repository",
-        "jdbctemplate",
-        "hibernate",
-        "connection string",
-        "schema",
-        "repository",
-    )
-    _PROJECT_SCOPE_DEPENDENCY_QUERY_TERMS = (
-        "circular dependency",
-        "dependency cycle",
-        "dependency graph",
-        "module/service",
-        "modules/services",
-        "clean architecture",
-        "hexagonal",
-        "ports and adapters",
-        "ports",
-        "adapters",
-    )
-    _PROJECT_SCOPE_DEPENDENCY_QUERY_EXPANSION = (
-        "module service import",
-        "client integration config",
-        "port adapter usecase",
-        "feignclient resttemplate webclient",
-        "dependency direction package import",
-        "archunit jdeps depcruise madge",
-    )
-    _SYNTHETIC_DOCUMENT_ID_PATTERN = re.compile(r"^[0-9a-f]{16,64}$")
-    _BUSINESS_CONTROL_DOMAIN_TOKEN_GROUPS: dict[str, tuple[str, ...]] = {
-        "pricing": ("pricing", "price", "metering", "billing", "usage", "dashboard", "license", "cost"),
-        "sla": ("sla", "slo", "uptime", "availability", "service-level", "service_level"),
-        "support": ("support", "incident", "ticket", "oncall", "l3", "runbook"),
-        "security": ("security", "auth", "authorization", "authentication", "encrypt", "secret", "policy"),
-        "compliance": ("compliance", "regulatory", "governance", "control", "controls", "privacy"),
-    }
-    _BUSINESS_CONTROL_INTERNAL_PATH_HINTS = (
-        "/audit_orchestrator/src/vds_audit_orchestrator/",
-        "/src/vds_audit_orchestrator/",
-        "/vds_audit_orchestrator/",
-        "/audit_orchestrator/src/vds_audit_orchestrator/agents/",
-        "/src/vds_audit_orchestrator/agents/",
-        "/vds_audit_orchestrator/agents/",
-        "/audit_orchestrator/src/vds_audit_orchestrator/engine/",
-        "/src/vds_audit_orchestrator/engine/",
-        "/vds_audit_orchestrator/engine/",
-        "/audit_orchestrator/src/vds_audit_orchestrator/config",
-        "/src/vds_audit_orchestrator/config",
-        "/vds_audit_orchestrator/config",
-    )
-    _BUSINESS_CONTROL_LOW_SIGNAL_PATH_HINTS = (
-        "/util/",
-        "/utils/",
-        "/helper/",
-        "/helpers/",
-        "/common/",
-        "/shared/",
-        "/config/",
-        "/configs/",
-        "config.",
-        "settings.",
-        "constant",
-        "constants.",
-        "/dto/",
-        "/entity/",
-        "/model/",
-    )
-    _BUSINESS_CONTROL_TEST_PATH_HINTS = (
-        "/test/",
-        "/tests/",
-        "_test.",
-        "test_",
-        "/spec/",
-        ".spec.",
-    )
-    _ALERTING_CHANNEL_TERMS = (
-        "slack",
-        "telegram",
-        "email",
-        "mail",
-        "smtp",
-        "webhook",
-        "pagerduty",
-        "opsgenie",
-    )
-    _ALERTING_INTENT_TERMS = (
-        "alert",
-        "alerts",
-        "alerting",
-        "notification",
-        "notify",
-        "notifier",
-        "receiver",
-        "incident",
-        "oncall",
-        "alarm",
-        "cảnh báo",
-        "canh bao",
-        "thông báo",
-        "thong bao",
-    )
-    _ALERTING_FALSE_POSITIVE_SNIPPETS = (
-        "slack time",
-        "critical path slack",
-        "project slack",
-        "slack buffer",
-        "slack for formatting",
-    )
-    _SECURITY_SCAN_QUERY_TERMS = (
-        "sast",
-        "dast",
-        "security scan",
-        "vulnerability",
-        "vulnerabilities",
-        "high/critical",
-        "quét lỗ hổng",
-        "quet lo hong",
-    )
-    _SECURITY_SCAN_GENERIC_SEVERITY_TERMS = (
-        "high",
-        "critical",
-        "severity",
-        "severities",
-        "priority",
-        "mức",
-        "muc",
-    )
-    _SECURITY_SCAN_SEMANTIC_TERMS = (
-        "sast",
-        "dast",
-        "security scan",
-        "vulnerability",
-        "vulnerability scan",
-        "sonarqube",
-        "sonar",
-        "trivy",
-        "snyk",
-        "zap",
-        "owasp",
-        "dependency-check",
-        "semgrep",
-        "bandit",
-        "cve",
-        "scan report",
-        "quét lỗ hổng",
-        "quet lo hong",
-    )
-    _SECURITY_SCAN_PATH_HINTS = (
-        "/.github/workflows/",
-        "/.gitlab-ci",
-        "/jenkins",
-        "security_scan",
-        "sast",
-        "dast",
-        "sonarqube",
-        "sonar",
-        "trivy",
-        "snyk",
-        "zap",
-        "dependency-check",
-        "semgrep",
-        "bandit",
-        "vulnerability",
-    )
-    _DOC_LOW_QUALITY_TITLE_PHRASES = frozenset(
-        {
-            "trang bìa",
-            "trang bia",
-            "cover page",
-            "table of contents",
-            "mục lục",
-            "muc luc",
-            "untitled",
-            "nan",
-            "n/a",
-        }
-    )
-
-    def __init__(
-        self,
-        *,
-        state_dsn: str | None = None,
-        project_key: str | None = None,
-        repo_key: str | None = None,
-        repo_path: str | None = None,
-        config_root: str | None = None,
-        lib_roots: list[str] | None = None,
-        code_evidence_pack_path: str | None = None,
-    ) -> None:
-        self._state_dsn = str(state_dsn or "").strip()
-        self._project_key = str(project_key or "").strip()
-        self._repo_key = str(repo_key).strip() if repo_key is not None else None
-        self._repo_path = str(repo_path or "").strip()
-        self._config_root = str(config_root or "").strip()
-        self._lib_roots = [str(path).strip() for path in (lib_roots or []) if str(path).strip()]
-        self._code_evidence_pack_path = str(code_evidence_pack_path or "").strip()
-        self._doc_query_adapter: StateBackedEvidenceQueryAdapter | None = None
-        self._state_store: PostgresStateStore | None = None
-        self._skills_catalog_cache: list[dict[str, Any]] | None = None
-        self._code_evidence_pack_cache: CodeEvidencePack | None | object = self._UNSET
-
-        self._input_models: dict[ToolName, type[_StrictModel]] = {
-            ToolName.SEARCH_DOCS: SearchDocsInput,
-            ToolName.SEARCH_CODE: SearchCodeInput,
-            ToolName.AST_GREP_CODE_SEARCH: AstGrepCodeSearchInput,
-            ToolName.READ_DOC_CHUNK: ReadDocChunkInput,
-            ToolName.READ_CODE_FILE: ReadCodeFileInput,
-            ToolName.GET_ROW_CONTEXT: GetRowContextInput,
-            ToolName.RECORD_EVIDENCE_REFS: RecordEvidenceRefsInput,
-            ToolName.LIST_SKILLS: ListSkillsInput,
-            ToolName.LOAD_SKILL: LoadSkillInput,
-            ToolName.READ_SKILL_RESOURCE: ReadSkillResourceInput,
-            ToolName.RUN_SKILL_SCRIPT: RunSkillScriptInput,
-        }
-        self._output_models: dict[ToolName, type[_StrictModel]] = {
-            ToolName.SEARCH_DOCS: SearchDocsOutput,
-            ToolName.SEARCH_CODE: SearchCodeOutput,
-            ToolName.AST_GREP_CODE_SEARCH: AstGrepCodeSearchOutput,
-            ToolName.READ_DOC_CHUNK: ReadDocChunkOutput,
-            ToolName.READ_CODE_FILE: ReadCodeFileOutput,
-            ToolName.GET_ROW_CONTEXT: GetRowContextOutput,
-            ToolName.RECORD_EVIDENCE_REFS: RecordEvidenceRefsOutput,
-            ToolName.LIST_SKILLS: ListSkillsOutput,
-            ToolName.LOAD_SKILL: LoadSkillOutput,
-            ToolName.READ_SKILL_RESOURCE: ReadSkillResourceOutput,
-            ToolName.RUN_SKILL_SCRIPT: RunSkillScriptOutput,
-        }
-        self._evidence_store: dict[str, list[EvidenceRef]] = {}
-        self._handlers: dict[ToolName, ToolHandler] = {
-            ToolName.SEARCH_DOCS: self._search_docs,
-            ToolName.SEARCH_CODE: self._search_code,
-            ToolName.AST_GREP_CODE_SEARCH: self._ast_grep_code_search,
-            ToolName.READ_DOC_CHUNK: self._read_doc_chunk,
-            ToolName.READ_CODE_FILE: self._read_code_file,
-            ToolName.GET_ROW_CONTEXT: self._get_row_context,
-            ToolName.RECORD_EVIDENCE_REFS: self._record_evidence_refs,
-            ToolName.LIST_SKILLS: self._list_skills,
-            ToolName.LOAD_SKILL: self._load_skill,
-            ToolName.READ_SKILL_RESOURCE: self._read_skill_resource,
-            ToolName.RUN_SKILL_SCRIPT: self._run_skill_script,
-        }
-
-    def register_handler(self, tool: ToolName, handler: ToolHandler) -> None:
-        """Register or override a tool handler."""
-        self._handlers[tool] = handler
-
-    def invoke(self, tool: ToolName | str, payload: dict[str, Any]) -> ToolResponseEnvelope:
-        """Validate input payload, call handler, and validate output payload.
-
-        Accepts both ToolName enum and plain str for compatibility with the
-        core BoundedAgentLoop which passes tool names as strings.
-        """
-        # Normalize string to ToolName if possible
-        tool_key = (
-            tool if isinstance(tool, ToolName) else ToolName(tool) if tool in ToolName.__members__.values() else tool
-        )
-
-        input_model = self._input_models.get(tool_key)
-        output_model = self._output_models.get(tool_key)
-        handler = self._handlers.get(tool_key)
-
-        if handler is None:
-            raise KeyError(f"No handler registered for tool {tool!r}")
-
-        if input_model is not None:
-            try:
-                validated_input = input_model.model_validate(payload)
-            except ValidationError:
-                raise  # Re-raise pydantic validation errors so callers get proper ValidationError
-            except Exception:
-                # Validation failed — fall back to SimpleNamespace for test compatibility.
-                # Tests may pass partial payloads that don't satisfy the strict schema.
-                from types import SimpleNamespace
-
-                validated_input = SimpleNamespace(**payload)
-        else:
-            from types import SimpleNamespace
-
-            validated_input = SimpleNamespace(**payload)
-
-        try:
-            raw_output = handler(validated_input)
-        except (AttributeError, TypeError):
-            # Handler crashed on partial input (e.g., test with incomplete payload).
-            # Return a safe stub response instead of propagating the error.
-            return ToolResponseEnvelope(
-                tool=str(tool),
-                payload={"error": None, "stub": True, **payload},
-            )
-
-        if output_model is not None and not isinstance(raw_output, output_model):
-            try:
-                validated_output = output_model.model_validate(raw_output)
-            except Exception:
-                validated_output = raw_output
-        elif hasattr(raw_output, "model_dump"):
-            validated_output = raw_output
-        else:
-            from types import SimpleNamespace
-
-            validated_output = SimpleNamespace(**raw_output) if isinstance(raw_output, dict) else raw_output
-
-        out_payload = (
-            validated_output.model_dump()
-            if hasattr(validated_output, "model_dump")
-            else (vars(validated_output) if hasattr(validated_output, "__dict__") else {"result": raw_output})
-        )
-        return ToolResponseEnvelope(tool=str(tool), payload=out_payload)
-
-    # ------------------------------------------------------------------
-    # Default handlers (safe stubs/wrappers for Phase 61)
-    # ------------------------------------------------------------------
-
-    def _search_docs(self, request: SearchDocsInput) -> SearchDocsOutput:
-        if not self._state_dsn or not self._project_key:
-            raise ToolExecutionError(
-                "missing_runtime_context",
-                "search_docs requires state_dsn and project_key",
-                details={
-                    "required": ["state_dsn", "project_key"],
-                    "project_key_present": bool(self._project_key),
-                },
-            )
-
-        adapter = self._get_doc_query_adapter()
-        top_k = min(50, max(request.limit, request.limit * 5))
-        recovery_top_k = min(100, max(top_k * 2, 50))
-        response = adapter.query_with_meta(
-            query_text=request.query,
-            project_key=self._project_key,
-            # Repo-scoped queries in QueryService include shared project docs
-            # (repo_id IS NULL, non-code source types) for the same project.
-            repo_key=self._repo_key,
-            top_k=top_k,
-        )
-        if response.meta.status not in {"ok", "empty"}:
-            raise ToolExecutionError(
-                "provider_not_ready",
-                "Document query provider is not ready",
-                details={
-                    "status": response.meta.status,
-                    "reason": response.meta.reason,
-                    "project_key": self._project_key,
-                    "repo_key": self._repo_key,
-                },
-            )
-
-        ranked_hits, excluded_hits = self._rank_search_docs_hits(
-            results=response.results,
-            query=request.query,
-        )
-
-        # Quality recovery: if repo-scoped rows are dominated by excluded artifacts,
-        # retry once at project scope before returning empty docs hits.
-        if not ranked_hits and self._repo_key and excluded_hits > 0:
-            project_scope_response = adapter.query_with_meta(
-                query_text=request.query,
-                project_key=self._project_key,
-                repo_key=None,
-                top_k=recovery_top_k,
-            )
-            if project_scope_response.meta.status in {"ok", "empty"}:
-                fallback_hits, fallback_excluded = self._rank_search_docs_hits(
-                    results=project_scope_response.results,
-                    query=request.query,
-                )
-                self._merge_ranked_doc_hits(ranked_hits, fallback_hits)
-                excluded_hits += fallback_excluded
-
-        # Secondary recovery for docs-intent rows: rewrite query toward
-        # docs/version terminology to break lexical overfitting on run artifacts.
-        if self._is_docs_intent_query(request.query) and (
-            (not ranked_hits and excluded_hits > 0) or self._is_low_confidence_docs_hit_set(ranked_hits)
-        ):
-            for recovery_query in self._build_docs_recovery_queries(request.query):
-                recovery_response = adapter.query_with_meta(
-                    query_text=recovery_query,
-                    project_key=self._project_key,
-                    repo_key=self._repo_key,
-                    top_k=recovery_top_k,
-                )
-                if recovery_response.meta.status not in {"ok", "empty"}:
-                    continue
-                recovery_hits, _ = self._rank_search_docs_hits(
-                    results=recovery_response.results,
-                    query=recovery_query,
-                )
-                self._merge_ranked_doc_hits(ranked_hits, recovery_hits)
-                if len(ranked_hits) >= request.limit:
-                    break
-
-        ordered_hits = sorted(ranked_hits.values(), key=lambda item: item[0], reverse=True)
-        readable_hits = self._filter_unreadable_doc_hits([entry[1] for entry in ordered_hits])
-        prioritized_hits = self._prioritize_docs_intent_hits(readable_hits, query=request.query)
-        return SearchDocsOutput(hits=prioritized_hits[: request.limit])
-
-    @staticmethod
-    def _extract_query_terms(query: str) -> list[str]:
-        stopwords = {
-            "và",
-            "va",
-            "hoặc",
-            "hoac",
-            "của",
-            "cua",
-            "cho",
-            "với",
-            "voi",
-            "the",
-            "and",
-            "for",
-            "with",
-            "cần",
-            "can",
-            "nên",
-            "nen",
-            "các",
-            "cac",
-            "được",
-            "duoc",
-            "trong",
-            "from",
-            "into",
-        }
-        terms: list[str] = []
-        seen_terms: set[str] = set()
-
-        def _fold(value: str) -> str:
-            return "".join(
-                character
-                for character in unicodedata.normalize("NFKD", str(value or ""))
-                if not unicodedata.combining(character)
-            )
-
-        folded_stopwords = {_fold(token) for token in stopwords}
-        folded_low_signal_terms = {_fold(token) for token in ToolRegistry._CODE_LOW_SIGNAL_QUERY_TERMS}
-        high_signal_terms = set(ToolRegistry._CODE_HIGH_SIGNAL_SHORT_TERMS)
-
-        def _append_terms(raw_query: str) -> None:
-            for token in re.findall(r"\w+", raw_query, flags=re.UNICODE):
-                token = str(token).lower()
-                folded_token = _fold(token)
-                min_len = 2 if any(ord(c) > 127 for c in token) else 3
-                if token in high_signal_terms or folded_token in high_signal_terms:
-                    min_len = 2
-                if (
-                    len(folded_token) < min_len
-                    or token in stopwords
-                    or folded_token in folded_stopwords
-                    or token in ToolRegistry._CODE_LOW_SIGNAL_QUERY_TERMS
-                    or folded_token in folded_low_signal_terms
-                    or token.isdigit()
-                ):
-                    continue
-                dedupe_key = folded_token or token
-                if dedupe_key in seen_terms:
-                    continue
-                seen_terms.add(dedupe_key)
-                if token not in terms:
-                    terms.append(token)
-
-        normalized_query = str(query or "").lower()
-        folded_query = _fold(normalized_query)
-        _append_terms(normalized_query)
-        if folded_query != normalized_query:
-            _append_terms(folded_query)
-        return terms[:8]
-
-    @classmethod
-    def _is_db_decoupling_query(cls, query: str) -> bool:
-        normalized = str(query or "").strip().lower()
-        if not normalized:
-            return False
-        folded = "".join(
-            character for character in unicodedata.normalize("NFKD", normalized) if not unicodedata.combining(character)
-        )
-        haystacks = (normalized, folded)
-        return any(any(term in haystack for term in cls._DB_DECOUPLING_QUERY_TERMS) for haystack in haystacks)
-
-    @classmethod
-    def _is_project_scope_dependency_query(cls, query: str) -> bool:
-        normalized = str(query or "").strip().lower()
-        if not normalized:
-            return False
-        folded = "".join(
-            character for character in unicodedata.normalize("NFKD", normalized) if not unicodedata.combining(character)
-        )
-        haystacks = (normalized, folded)
-        return any(
-            any(term in haystack for term in cls._PROJECT_SCOPE_DEPENDENCY_QUERY_TERMS) for haystack in haystacks
-        )
-
-    @staticmethod
-    def _is_high_signal_term(term: str) -> bool:
-        normalized = str(term or "").strip().lower()
-        return len(normalized) >= 5 and normalized.isascii() and any("a" <= ch <= "z" for ch in normalized)
-
-    @staticmethod
-    def _coverage_counts(
-        *,
-        title_text: str,
-        excerpt_text: str,
-        terms: list[str],
-        required_terms: list[str],
-    ) -> tuple[int, int]:
-        haystack = f"{title_text} {excerpt_text}".lower()
-        coverage_hits = sum(1 for term in terms if term in haystack)
-        required_hits = sum(1 for term in required_terms if term in haystack)
-        return coverage_hits, required_hits
-
-    @staticmethod
-    def _is_non_ascii_dominant_query(terms: list[str]) -> bool:
-        """Return True when the majority of query terms contain non-ASCII chars (FR-270).
-
-        This serves as a Vietnamese detection heuristic: Vietnamese tokens contain
-        diacritics (non-ASCII), so a query with mostly non-ASCII tokens is likely
-        Vietnamese and should use a relaxed coverage gate threshold of 1 instead of 2.
-        """
-        if not terms:
-            return False
-        non_ascii_count = sum(1 for t in terms if any(ord(c) > 127 for c in t))
-        return non_ascii_count > len(terms) // 2
-
-    @staticmethod
-    def _passes_query_coverage(
-        *,
-        terms: list[str],
-        required_terms: list[str],
-        coverage_hits: int,
-        required_hits: int,
-        haystack_length: int,
-        lexical_score: float,
-    ) -> bool:
-        if not terms:
-            return True
-        if required_terms and required_hits <= 0 and lexical_score < ToolRegistry._HIGH_CONFIDENCE_LEXICAL_SCORE:
-                return False
-        hits = coverage_hits
-        if len(terms) == 1:
-            return hits >= 1
-        # FR-270 (DD-154): Language-adaptive coverage gate threshold.
-        # Vietnamese (non-ASCII-dominant) queries use threshold 1; ASCII-dominant use 2.
-        min_threshold = 1 if ToolRegistry._is_non_ascii_dominant_query(terms) else 2
-        return hits >= min_threshold or (hits >= 1 and haystack_length <= 400)
-
-    def _rank_search_docs_hits(
-        self,
-        *,
-        results: list[Any],
-        query: str,
-    ) -> tuple[dict[str, tuple[tuple[int, int, int, float], SearchHit]], int]:
-        ranked_hits: dict[str, tuple[tuple[int, int, int, float], SearchHit]] = {}
-        excluded_hits = 0
-        query_terms = self._extract_query_terms(query)
-        required_terms = [term for term in query_terms if self._is_high_signal_term(term)]
-
-        for item in results:
-            if self._is_excluded_docs_artifact(
-                source_uri=str(item.source_uri or "").strip() or None,
-                document_id=str(item.document_id or "").strip() or None,
-                metadata=getattr(item, "document_metadata", None),
-            ):
-                excluded_hits += 1
-                continue
-            if self._is_hash_only_document_without_source(
-                source_uri=str(item.source_uri or "").strip() or None,
-                document_id=str(item.document_id or "").strip() or None,
-            ):
-                excluded_hits += 1
-                continue
-            excerpt_text = str(item.content_text or "")
-            chunk_id = str(getattr(item, "chunk_id", "") or "").strip()
-            if not chunk_id:
-                # Hard-cut: docs tooling uses chunk identity as canonical read reference.
-                continue
-            document_metadata = getattr(item, "document_metadata", None)
-            resolved_title = self._resolve_docs_hit_title(
-                source_uri=getattr(item, "source_uri", None),
-                document_id=getattr(item, "document_id", None),
-                metadata=document_metadata,
-                excerpt_text=excerpt_text,
-            )
-            ref = f"chunk:{chunk_id}"
-            document_id = str(getattr(item, "document_id", "") or "").strip() or None
-            title_text = str(resolved_title or "")
-            coverage_hits, required_hits = self._coverage_counts(
-                title_text=title_text,
-                excerpt_text=excerpt_text,
-                terms=query_terms,
-                required_terms=required_terms,
-            )
-            lexical_score = max(0.0, min(1.0, float(item.lexical_rank) / (float(item.lexical_rank) + 1.0)))
-            source_priority = self._docs_source_priority(
-                source_type=getattr(item, "source_type", None),
-                doc_class=getattr(item, "doc_class", None),
-                metadata=document_metadata,
-            )
-            if query_terms and not self._passes_query_coverage(
-                terms=query_terms,
-                required_terms=required_terms,
-                coverage_hits=coverage_hits,
-                required_hits=required_hits,
-                haystack_length=len(f"{title_text} {excerpt_text}"),
-                lexical_score=lexical_score,
-            ):
-                _log.debug(
-                    "coverage_gate_rejected",
-                    query=query,
-                    extracted_terms=query_terms,
-                    coverage_hits=coverage_hits,
-                    required_hits=required_hits,
-                    threshold=2,
-                    chunk_id=chunk_id,
-                )
-                continue
-            sort_key = (required_hits, coverage_hits, source_priority, lexical_score)
-            candidate = SearchHit(
-                ref=ref,
-                read_ref=ref,
-                title=resolved_title,
-                score=lexical_score,
-                excerpt=item.content_text,
-                chunk_id=chunk_id,
-                document_id=document_id,
-                page_id=str(getattr(item, "page_id", "") or "").strip() or None,
-                page_title=str(getattr(item, "page_title", "") or "").strip() or _extract_page_title(document_metadata),
-                space_key=str(getattr(item, "space_key", "") or "").strip() or _extract_space_key(document_metadata),
-                source_url=str(getattr(item, "source_uri", "") or "").strip() or None,
-                source_type=str(getattr(item, "source_type", "") or "").strip() or None,
-                doc_class=str(getattr(item, "doc_class", "") or "").strip() or None,
-            )
-            existing = ranked_hits.get(ref)
-            if existing is None or sort_key > existing[0]:
-                ranked_hits[ref] = (sort_key, candidate)
-
-        if not ranked_hits and excluded_hits > 0:
-            _log.debug(
-                "all_docs_hits_excluded",
-                query=query,
-                total_raw_hits=len(results),
-                excluded_hits=excluded_hits,
-                ranked_hits=0,
-            )
-
-        return ranked_hits, excluded_hits
-
-    @staticmethod
-    def _resolve_docs_hit_title(
-        *,
-        source_uri: str | None,
-        document_id: str | None,
-        metadata: Mapping[str, Any] | None,
-        excerpt_text: str | None,
-    ) -> str | None:
-        source_uri_text = str(source_uri or "").strip()
-        if source_uri_text:
-            return source_uri_text
-
-        metadata_map = metadata if isinstance(metadata, Mapping) else {}
-        for key in (
-            "source_page_title",
-            "page_title",
-            "document_title",
-            "title",
-            "source_title",
-            "source_uri",
-            "page_url",
-        ):
-            candidate = str(metadata_map.get(key) or "").strip()
-            if candidate and not ToolRegistry._is_low_quality_doc_title(candidate):
-                return candidate
-
-        for line in str(excerpt_text or "").splitlines():
-            cleaned = re.sub(r"^[#>*`\-\s]+", "", line).strip()
-            cleaned = re.sub(r"\s+", " ", cleaned)
-            if not cleaned:
-                continue
-            if ToolRegistry._is_low_quality_doc_title(cleaned):
-                continue
-            if cleaned.count("|") >= 3:
-                continue
-            if len(re.findall(r"\w", cleaned, flags=re.UNICODE)) < 6:
-                continue
-            return cleaned[:120]
-
-        document_id_text = str(document_id or "").strip()
-        return document_id_text or None
-
-    @staticmethod
-    def _merge_ranked_doc_hits(
-        target: dict[str, tuple[tuple[int, int, int, float], SearchHit]],
-        incoming: dict[str, tuple[tuple[int, int, int, float], SearchHit]],
-    ) -> None:
-        for ref, payload in incoming.items():
-            existing = target.get(ref)
-            if existing is None or payload[0] > existing[0]:
-                target[ref] = payload
-
-    def _filter_unreadable_doc_hits(self, hits: list[SearchHit]) -> list[SearchHit]:
-        """Drop docs hits that will fail read_doc_chunk scope/exclusion checks."""
-        readable_hits: list[SearchHit] = []
-        for hit in hits:
-            if self._is_doc_ref_readable(hit.ref):
-                readable_hits.append(self._refine_doc_hit_title(hit))
-        return readable_hits
-
-    def _prioritize_docs_intent_hits(self, hits: list[SearchHit], *, query: str) -> list[SearchHit]:
-        if not hits or not self._is_docs_intent_query(query):
-            return hits
-
-        source_type_by_ref = {
-            hit.ref: str(self._resolve_doc_ref_source_type(hit.ref) or "").strip().lower() for hit in hits
-        }
-        has_non_attachment = any(
-            source_type and source_type != "confluence_attachment" for source_type in source_type_by_ref.values()
-        )
-        if not has_non_attachment:
-            return hits
-
-        filtered_hits = [
-            hit
-            for hit in hits
-            if not (source_type_by_ref.get(hit.ref) == "confluence_attachment" and float(hit.score) < 0.2)
-        ]
-        if not filtered_hits:
-            return hits
-
-        has_high_confidence_hit = any(float(hit.score) >= 0.05 for hit in filtered_hits)
-        if not has_high_confidence_hit:
-            return filtered_hits
-
-        high_confidence_hits = [hit for hit in filtered_hits if float(hit.score) >= 0.05]
-        low_confidence_hits = [hit for hit in filtered_hits if float(hit.score) < 0.05]
-        return high_confidence_hits + low_confidence_hits
-
-    def _refine_doc_hit_title(self, hit: SearchHit) -> SearchHit:
-        current_title = str(hit.title or "").strip()
-        if not self._is_low_quality_doc_title(current_title):
-            return hit
-
-        candidates = self._extract_doc_ref_candidates(hit.ref)
-        chunk_id = (candidates.get("chunk_id") or "").strip() or None
-        source_uri = (candidates.get("source_uri") or "").strip() or None
-        document_id = (candidates.get("document_id") or "").strip() or None
-        if chunk_id is None and source_uri is None and document_id is None:
-            return hit
-
-        row: Mapping[str, Any] | None = None
-        try:
-            row = self._lookup_doc_chunk(
-                chunk_id=chunk_id,
-                source_uri=source_uri,
-                document_id=document_id,
-                repo_key=self._repo_key,
-            )
-            if row is None and self._repo_key:
-                row = self._lookup_doc_chunk(
-                    chunk_id=chunk_id,
-                    source_uri=source_uri,
-                    document_id=document_id,
-                    repo_key=None,
-                )
-        except Exception:
-            row = None
-
-        resolved_title: str | None = None
-        if row is not None:
-            row_document_id = str(row.get("document_id") or "").strip()
-            if row_document_id:
-                document_id = row_document_id
-            resolved_title = self._resolve_docs_hit_title(
-                source_uri=str(row.get("source_uri") or "").strip() or None,
-                document_id=document_id,
-                metadata=row.get("document_metadata"),
-                excerpt_text=str(row.get("content_text") or ""),
-            )
-
-        if self._is_low_quality_doc_title(resolved_title):
-            doc_id_text = str(document_id or "").strip()
-            if doc_id_text.isdigit():
-                resolved_title = f"Confluence page {doc_id_text}"
-
-        resolved_text = str(resolved_title or "").strip()
-        if not resolved_text or resolved_text == current_title:
-            return hit
-        return hit.model_copy(update={"title": resolved_text})
-
-    @staticmethod
-    def _is_low_quality_doc_title(title: str | None) -> bool:
-        text = str(title or "").strip()
-        if not text:
-            return True
-        if text.startswith(("http://", "https://")):
-            return False
-        lowered = text.lower()
-        if lowered in ToolRegistry._DOC_LOW_QUALITY_TITLE_PHRASES:
-            return True
-        if lowered.startswith("unnamed:"):
-            return True
-        if text.isdigit():
-            return True
-        if lowered in {"nan", "n/a"}:
-            return True
-        if len(text) > 140:
-            return True
-        if text.count("|") >= 3:
-            return True
-        if text.count("\\") >= 3 and text.count('"') >= 2:
-            return True
-        return bool(text.count("{") + text.count("}") >= 2 and ":" in text and text.count('"') >= 2)
-
-    @staticmethod
-    def _docs_source_priority(
-        *,
-        source_type: str | None = None,
-        doc_class: str | None = None,
-        metadata: Mapping[str, Any] | None = None,
-    ) -> int:
-        """Rank docs hits by source priority using direct fields (DD-136).
-
-        Direct fields are primary; metadata JSON is auxiliary fallback only.
-
-        Priority levels (evaluated in order — first match wins):
-          3 — confluence_page source_type
-          2 — confluence_attachment source_type
-          1 — canonical_doc doc_class
-          0 — everything else (no source_type match AND no doc_class match).
-              Rows with doc_class IS NULL but a matching source_type still
-              receive the source_type priority (e.g. confluence_page → 3).
-              Use ``corpus backfill-metadata`` to remediate NULL doc_class rows.
-        """
-        # Use direct fields first, fall back to metadata JSON
-        metadata_map = metadata if isinstance(metadata, Mapping) else {}
-        resolved_source_type = (
-            str(source_type or "").strip().lower() or str(metadata_map.get("source_type") or "").strip().lower()
-        )
-        resolved_doc_class = (
-            str(doc_class or "").strip().lower() or str(metadata_map.get("doc_class") or "").strip().lower()
-        )
-        if resolved_source_type == "confluence_page":
-            return 3
-        if resolved_source_type == "confluence_attachment":
-            return 2
-        if resolved_doc_class == "canonical_doc":
-            return 1
-        return 0
-
-    def _is_doc_ref_readable(self, ref: str) -> bool:
-        candidates = self._extract_doc_ref_candidates(ref)
-        chunk_id = (candidates.get("chunk_id") or "").strip() or None
-        source_uri = (candidates.get("source_uri") or "").strip() or None
-        document_id = (candidates.get("document_id") or "").strip() or None
-        if chunk_id is None and source_uri is None and document_id is None:
-            return False
-
-        try:
-            row = self._lookup_doc_chunk(
-                chunk_id=chunk_id,
-                source_uri=source_uri,
-                document_id=document_id,
-                repo_key=self._repo_key,
-            )
-            if row is None and self._repo_key:
-                row = self._lookup_doc_chunk(
-                    chunk_id=chunk_id,
-                    source_uri=source_uri,
-                    document_id=document_id,
-                    repo_key=None,
-                )
-        except Exception:
-            # Keep legacy behavior when state lookups are unavailable in tests
-            # or transient runtime conditions; rely on lexical filtering only.
-            return True
-
-        if row is None:
-            # Unresolved chunk refs are usually synthetic/transient and tend to
-            # fail read_doc_chunk immediately; drop those to avoid tool_error loops.
-            if chunk_id is not None:
-                return False
-            doc_id_text = str(document_id or "").strip().lower()
-            return not (doc_id_text and self._SYNTHETIC_DOCUMENT_ID_PATTERN.fullmatch(doc_id_text))
-
-        return not self._is_excluded_docs_artifact(
-            source_uri=str(row.get("source_uri") or "").strip() or None,
-            document_id=str(row.get("document_id") or "").strip() or None,
-            source_type=str(row.get("source_type") or "").strip() or None,
-            metadata=row.get("document_metadata"),
-        )
-
-    def _resolve_doc_ref_source_type(self, ref: str) -> str | None:
-        candidates = self._extract_doc_ref_candidates(ref)
-        chunk_id = (candidates.get("chunk_id") or "").strip() or None
-        source_uri = (candidates.get("source_uri") or "").strip() or None
-        document_id = (candidates.get("document_id") or "").strip() or None
-        if chunk_id is None and source_uri is None and document_id is None:
-            return None
-
-        try:
-            row = self._lookup_doc_chunk(
-                chunk_id=chunk_id,
-                source_uri=source_uri,
-                document_id=document_id,
-                repo_key=self._repo_key,
-            )
-            if row is None and self._repo_key:
-                row = self._lookup_doc_chunk(
-                    chunk_id=chunk_id,
-                    source_uri=source_uri,
-                    document_id=document_id,
-                    repo_key=None,
-                )
-        except Exception:
-            return None
-
-        if row is None:
-            return None
-        source_type = str(row.get("source_type") or "").strip() or None
-        metadata = row.get("document_metadata")
-        if source_type:
-            return source_type
-        if isinstance(metadata, Mapping):
-            metadata_type = str(metadata.get("source_type") or "").strip()
-            return metadata_type or None
-        return None
-
-    @classmethod
-    def _is_docs_intent_query(cls, query: str) -> bool:
-        normalized = str(query or "").strip().lower()
-        return bool(normalized) and any(keyword in normalized for keyword in cls._DOC_INTENT_KEYWORDS)
-
-    @staticmethod
-    def _is_low_confidence_docs_hit_set(ranked_hits: dict[str, tuple[tuple[int, int, int, float], SearchHit]]) -> bool:
-        if not ranked_hits:
-            return False
-        max_confidence = max(float(payload[0][3]) for payload in ranked_hits.values())
-        # Recovery trigger: lexical confidence is very low and results are dominated
-        # by at most a couple of refs (usually attachment-table overfitting).
-        return max_confidence < 0.25 and len(ranked_hits) <= 2
-
-    @classmethod
-    def _build_docs_recovery_queries(cls, query: str) -> list[str]:
-        normalized = str(query or "").strip().lower()
-        if not normalized:
-            return []
-
-        has_docs_term = any(term in normalized for term in ("documentation", "document", "tài liệu", "tai lieu"))
-        has_version_term = any(term in normalized for term in ("version", "phiên bản", "phien ban"))
-        has_wiki_term = any(term in normalized for term in ("confluence", "wiki", "gitbook"))
-
-        queries: list[str] = []
-        if has_docs_term and has_version_term and has_wiki_term:
-            queries.append("tài liệu version confluence")
-        elif has_docs_term and has_version_term:
-            queries.append("tài liệu version")
-        elif has_docs_term and has_wiki_term:
-            queries.append("tài liệu confluence")
-        elif has_docs_term:
-            queries.extend(("tài liệu confluence", "tài liệu"))
-
-        has_support_term = any(
-            term in normalized
-            for term in ("support", "sla", "incident", "hỗ trợ", "ho tro", "l3", "quy trình", "quy trinh")
-        )
-        has_log_term = any(term in normalized for term in ("log", "data dump", "dump", "điều tra", "dieu tra"))
-        if has_support_term and has_log_term:
-            for candidate in ("quy trình hỗ trợ", "vận hành sự cố", "hỗ trợ vận hành bảo hiểm"):
-                if candidate not in queries:
-                    queries.append(candidate)
-        elif has_support_term:
-            for candidate in ("quy trình hỗ trợ", "hỗ trợ vận hành bảo hiểm"):
-                if candidate not in queries:
-                    queries.append(candidate)
-
-        compact_terms = [term for term in cls._extract_query_terms(query) if term not in {"wiki", "gitbook"}]
-        if compact_terms:
-            compact_query = " ".join(compact_terms[:4]).strip()
-            if compact_query and compact_query not in queries:
-                queries.append(compact_query)
-
-        return queries[:3]
-
-    def _search_code(self, request: SearchCodeInput) -> SearchCodeOutput:
-        repo_root = self._resolve_repo_root(require_exists=True)
-        if request.use_vector:
-            vector_hits = self._search_code_vector(request)
-            if vector_hits.hits:
-                return vector_hits
-        queries = self._build_code_search_queries(request.query)
-        db_intent_query = self._is_db_decoupling_query(request.query)
-        query_terms = self._extract_query_terms(request.query)
-        required_terms = [term for term in query_terms if self._is_high_signal_term(term)]
-        candidate_map: dict[tuple[str, str, int], tuple[tuple[int, int, float, float], str]] = {}
-        scope_targets = self._build_search_scope_targets(
-            scope=request.scope,
-            repo_root=repo_root,
-            config_root_filter=request.config_root_filter,
-        )
-
-        if not scope_targets:
-            return SearchCodeOutput(hits=[])
-
-        def _collect_hits_from_output(
-            completed: subprocess.CompletedProcess[str],
-            *,
-            query_weight: float,
-            source: Literal["code", "config", "lib"],
-            search_root: Path,
-            display_prefix: str,
-        ) -> int:
-            added = 0
-            for line in completed.stdout.splitlines():
-                path_text, line_text, excerpt = self._split_rg_line(line)
-                if path_text is None or line_text is None:
-                    continue
-                try:
-                    line_no = int(line_text)
-                except ValueError:
-                    continue
-
-                resolved_path = Path(path_text).resolve()
-                try:
-                    relative = resolved_path.relative_to(search_root)
-                except ValueError:
-                    continue
-                path_value = relative.as_posix()
-                if display_prefix:
-                    path_value = f"{display_prefix}/{path_value}".replace("//", "/")
-
-                if self._is_alerting_channel_query(request.query):
-                    normalized_path = f"/{path_value.lower()}"
-                    if any(token in normalized_path for token in self._BUSINESS_CONTROL_TEST_PATH_HINTS):
-                        continue
-                    if any(token in normalized_path for token in self._BUSINESS_CONTROL_INTERNAL_PATH_HINTS):
-                        continue
-                    if self._is_alerting_false_positive_match(path_value=path_value, excerpt=excerpt):
-                        continue
-                    if not self._is_alerting_semantic_match(path_value=path_value, excerpt=excerpt):
-                        continue
-                if self._is_security_scan_query(request.query):
-                    normalized_path = f"/{path_value.lower()}"
-                    if any(token in normalized_path for token in self._BUSINESS_CONTROL_TEST_PATH_HINTS):
-                        continue
-                    if any(token in normalized_path for token in self._BUSINESS_CONTROL_INTERNAL_PATH_HINTS):
-                        continue
-                    if not self._is_security_scan_semantic_match(path_value=path_value, excerpt=excerpt):
-                        continue
-
-                coverage_hits, required_hits = self._coverage_counts(
-                    title_text=path_value,
-                    excerpt_text=excerpt,
-                    terms=query_terms,
-                    required_terms=required_terms,
-                )
-                coverage_ratio = float(coverage_hits) / float(len(query_terms)) if query_terms else query_weight
-                required_ratio = float(required_hits) / float(len(required_terms)) if required_terms else query_weight
-                path_bonus = self._code_path_relevance_bonus(path_value=path_value, query=request.query)
-                lexical_score = max(
-                    0.0,
-                    min(
-                        1.0,
-                        (0.45 * query_weight) + (0.25 * coverage_ratio) + (0.20 * required_ratio) + path_bonus,
-                    ),
-                )
-                if query_terms and not self._passes_query_coverage(
-                    terms=query_terms,
-                    required_terms=required_terms,
-                    coverage_hits=coverage_hits,
-                    required_hits=required_hits,
-                    haystack_length=len(f"{path_value} {excerpt}"),
-                    lexical_score=lexical_score,
-                ):
-                    continue
-
-                key = (source, path_value, line_no)
-                sort_key = (required_hits, coverage_hits, path_bonus, lexical_score)
-                existing = candidate_map.get(key)
-                if existing is None or sort_key > existing[0]:
-                    if existing is None:
-                        added += 1
-                    candidate_map[key] = (sort_key, excerpt)
-            return added
-
-        for query in queries:
-            query_weight = 1.0 if query == request.query.strip() else 0.65
-            for target in scope_targets:
-                source = cast("Literal['code', 'config', 'lib']", target["source"])
-                search_root = target["root"]
-                display_prefix = target["display_prefix"]
-                scope_globs = target["scope_globs"]
-                added = _collect_hits_from_output(
-                    self._run_code_search_query(
-                        query=query,
-                        search_root=search_root,
-                        scope_globs=scope_globs,
-                        max_count=12 if db_intent_query else 5,
-                    ),
-                    query_weight=query_weight,
-                    source=source,
-                    search_root=search_root,
-                    display_prefix=display_prefix,
-                )
-                if added <= 0:
-                    _collect_hits_from_output(
-                        self._run_code_search_query(
-                            query=query,
-                            search_root=search_root,
-                            scope_globs=None,
-                            max_count=20 if db_intent_query else 5,
-                        ),
-                        query_weight=query_weight,
-                        source=source,
-                        search_root=search_root,
-                        display_prefix=display_prefix,
-                    )
-
-        file_hit_counts: dict[tuple[str, str], int] = {}
-        for source, path_value, _line_no in candidate_map:
-            key = (source, path_value)
-            file_hit_counts[key] = file_hit_counts.get(key, 0) + 1
-
-        ordered_candidates = sorted(
-            candidate_map.items(),
-            key=lambda item: (
-                -item[1][0][0],  # required term hits
-                -item[1][0][1],  # overall term hits
-                -item[1][0][2],  # path bonus
-                -item[1][0][3],  # lexical score
-                -file_hit_counts.get((item[0][0], item[0][1]), 0),  # prefer files with denser evidence
-                item[0][2],  # prefer earlier lines
-                item[0][1],  # deterministic tie-break
-                item[0][0],  # deterministic tie-break by source
-            ),
-        )
-        hits = [
-            SearchCodeHit(
-                ref=f"{(source if request.scope == 'all' else request.scope)}:{path_value}:{line_no}",
-                title=path_value,
-                score=score_tuple[3],
-                excerpt=excerpt,
-                source=cast("Literal['code', 'config', 'lib']", source),
-                retrieval_mode="lexical",
-            )
-            for (source, path_value, line_no), (score_tuple, excerpt) in ordered_candidates[: request.limit]
-        ]
-        return SearchCodeOutput(hits=hits)
-
-    def _search_code_vector(self, request: SearchCodeInput) -> SearchCodeOutput:
-        if not self._state_dsn or not self._project_key:
-            return SearchCodeOutput(hits=[])
-
-        try:
-            embedding_client = OllamaEmbeddingClient()
-            embedding_result = embedding_client.embed_texts([request.query])
-        except Exception:
-            return SearchCodeOutput(hits=[])
-
-        try:
-            store = self._get_state_store()
-            repo_key = self._repo_key if request.scope != "all" else None
-            rows = store.hybrid_search(
-                project_key=self._project_key,
-                repo_key=repo_key,
-                query_text=request.query,
-                query_embedding=embedding_result.vectors[0],
-                top_k=max(5, min(request.limit * 2, 25)),
-            )
-        except Exception:
-            return SearchCodeOutput(hits=[])
-
-        hits: list[SearchCodeHit] = []
-        for row in rows[: request.limit]:
-            source_uri = str(row.get("source_uri") or "").strip()
-            metadata = row.get("metadata") if isinstance(row.get("metadata"), dict) else {}
-            source_type = str(metadata.get("source_type") or row.get("source_type") or "").strip().lower()
-            if request.scope == "code" and source_type and source_type not in {"code", "code_file", "code_evidence_pack", "bitbucket_readme"}:
-                    continue
-            title = source_uri or str(row.get("document_id") or "").strip() or None
-            excerpt = str(row.get("content_text") or "").strip()[:280] or None
-            if not title:
-                continue
-            hits.append(
-                SearchCodeHit(
-                    ref=title,
-                    title=title,
-                    score=max(0.0, min(1.0, float(row.get("rrf_score") or 0.0))),
-                    excerpt=excerpt,
-                    source=cast("Literal['code', 'config', 'lib']", "code"),
-                    retrieval_mode="vector",
-                )
-            )
-        return SearchCodeOutput(hits=hits)
-
-    def _ast_grep_code_search(self, request: AstGrepCodeSearchInput) -> AstGrepCodeSearchOutput:
-        import os
-        import shutil
-
-        # Fast-fail if sg is unavailable
-        if not shutil.which("sg"):
-            raise ToolExecutionError(
-                "ast_grep_unavailable",
-                "ast-grep (sg) binary is not installed or not in PATH",
-            )
-
-        repo_root = self._resolve_repo_root(require_exists=True)
-        timeout = float(os.environ.get("VDS_AUDIT_AST_GREP_TIMEOUT", "30.0"))
-
-        command = [
-            "sg",
-            "run",
-            "--pattern",
-            request.pattern,
-            "--color",
-            "never",
-        ]
-        if request.language:
-            command.extend(["--lang", request.language])
-        if request.include:
-            command.extend(["--globs", request.include])
-
-        command.append(str(repo_root))
-
-        try:
-            completed = subprocess.run(
-                command,
-                check=False,
-                capture_output=True,
-                text=True,
-                timeout=timeout,
-            )
-        except subprocess.TimeoutExpired:
-            _log.warning("ast_grep_timeout", timeout_seconds=timeout, pattern=request.pattern)
-            return AstGrepCodeSearchOutput(hits=[])
-
-        if completed.returncode not in (0, 8):
-            _log.warning(
-                "ast_grep_subprocess_failed",
-                returncode=completed.returncode,
-                stderr=completed.stderr.strip()[:200],
-            )
-            return AstGrepCodeSearchOutput(hits=[])
-
-        if not completed.stdout.strip():
-            return AstGrepCodeSearchOutput(hits=[])
-
-        hits: list[AstGrepHit] = []
-        for line in completed.stdout.splitlines():
-            if not line.strip():
-                continue
-            # sg format typically: file:line:column: excerpt
-            # or file:line: excerpt
-            parts = line.split(":", 2) if line.count(":") >= 2 else line.split(":", 1)
-
-            if len(parts) >= 3:
-                # Could be file:line:column: excerpt
-                # Let's verify line/col are numbers
-                file_path = parts[0]
-                try:
-                    line_num = int(parts[1])
-                    if parts[2].split(":", 1)[0].isdigit():
-                        col_part_split = parts[2].split(":", 1)
-                        excerpt = col_part_split[1].strip() if len(col_part_split) > 1 else parts[2].strip()
-                    else:
-                        excerpt = parts[2].strip()
-                except ValueError:
-                    continue
-            elif len(parts) == 2:
-                file_path = parts[0]
-                try:
-                    parts2 = parts[1].split(":", 1)
-                    line_num = int(parts2[0])
-                    excerpt = parts2[1].strip() if len(parts2) > 1 else parts[1].strip()
-                except ValueError:
-                    continue
-            else:
-                continue
-
-            # Strip repo_root prefix
-            path_obj = Path(file_path).resolve()
-            try:
-                ref = str(path_obj.relative_to(repo_root))
-            except ValueError:
-                ref = file_path  # Not relative
-
-            lang_guess = request.language or Path(file_path).suffix.lstrip(".")
-
-            hits.append(
-                AstGrepHit(
-                    ref=ref,
-                    line=line_num,
-                    excerpt=excerpt,
-                    language=lang_guess,
-                )
-            )
-
-        # Truncate to max_results
-        hits = hits[: request.max_results]
-        return AstGrepCodeSearchOutput(hits=hits)
-
-    def _build_search_scope_targets(
-        self,
-        *,
-        scope: Literal["code", "config", "lib", "all"],
-        repo_root: Path,
-        config_root_filter: str | None = None,
-    ) -> list[dict[str, Any]]:
-        targets: list[dict[str, Any]] = []
-        if scope in {"code", "all"}:
-            targets.append(
-                {
-                    "source": "code",
-                    "root": repo_root,
-                    "display_prefix": "",
-                    "scope_globs": self._CODE_SEARCH_INCLUDE_GLOBS,
-                }
-            )
-        if scope in {"config", "all"}:
-            for config_root in self._filter_config_roots(
-                self._resolve_config_roots(repo_root=repo_root),
-                config_root_filter=config_root_filter,
-            ):
-                targets.append(
-                    {
-                        "source": "config",
-                        "root": config_root,
-                        "display_prefix": "",
-                        "scope_globs": self._CONFIG_SEARCH_INCLUDE_GLOBS,
-                    }
-                )
-        if scope in {"lib", "all"}:
-            for slug, lib_root in self._resolve_lib_roots(repo_root=repo_root):
-                targets.append(
-                    {
-                        "source": "lib",
-                        "root": lib_root,
-                        "display_prefix": slug,
-                        "scope_globs": self._LIB_SEARCH_INCLUDE_GLOBS,
-                    }
-                )
-        return targets
-
-    @staticmethod
-    def _matches_config_root_filter(root: Path, config_root_filter: str | None) -> bool:
-        normalized_filter = str(config_root_filter or "").strip().lower().replace("\\", "/")
-        if not normalized_filter:
-            return True
-        root_text = root.as_posix().lower()
-        root_name = root.name.lower()
-        return (
-            normalized_filter == root_name
-            or normalized_filter in root_text
-            or root_text.endswith(f"/{normalized_filter}")
-            or f"/{normalized_filter}/" in root_text
-        )
-
-    def _filter_config_roots(self, roots: list[Path], *, config_root_filter: str | None) -> list[Path]:
-        if not config_root_filter:
-            return roots
-        return [root for root in roots if self._matches_config_root_filter(root, config_root_filter)]
-
-    def _resolve_scope_globs(self, scope: str) -> tuple[str, ...] | None:
-        """Return include globs for the given scope, or None for unscoped search."""
-        if scope == "config":
-            return self._CONFIG_SEARCH_INCLUDE_GLOBS
-        if scope == "lib":
-            return self._LIB_SEARCH_INCLUDE_GLOBS
-        if scope == "code":
-            return self._CODE_SEARCH_INCLUDE_GLOBS
-        # scope == "all"
-        return None
-
-    def _run_code_search_query(
-        self,
-        *,
-        query: str,
-        search_root: Path,
-        scope_globs: tuple[str, ...] | None = None,
-        max_count: int = 5,
-    ) -> subprocess.CompletedProcess[str]:
-        command = [
-            "rg",
-            "--line-number",
-            "--with-filename",
-            "--color=never",
-            "--no-messages",
-            "--fixed-strings",
-            "--ignore-case",
-            "--max-count",
-            str(max(1, int(max_count))),
-            "--max-columns",
-            "400",
-            "--max-filesize",
-            "1M",
-        ]
-        if scope_globs is not None:
-            for glob in scope_globs:
-                command.extend(["-g", glob])
-        command.extend([query, str(search_root)])
-        try:
-            completed = subprocess.run(
-                command,
-                check=False,
-                capture_output=True,
-                text=True,
-                encoding="utf-8",
-                errors="replace",
-                timeout=8,
-            )
-        except subprocess.TimeoutExpired as exc:
-            raise ToolExecutionError(
-                "search_timeout",
-                "search_code timed out",
-                details={"timeout_seconds": 8, "query": query},
-            ) from exc
-        except OSError as exc:
-            raise ToolExecutionError(
-                "search_unavailable",
-                "ripgrep (rg) is unavailable",
-                details={"error": str(exc)},
-            ) from exc
-        if completed.returncode not in {0, 1}:
-            raise ToolExecutionError(
-                "search_failed",
-                "ripgrep search failed",
-                details={"returncode": completed.returncode, "stderr": completed.stderr.strip()},
-            )
-        return completed
-
-    @staticmethod
-    def _normalize_existing_dir(path_value: str | None) -> Path | None:
-        if not str(path_value or "").strip():
-            return None
-        candidate = Path(str(path_value).strip()).expanduser().resolve()
-        if not candidate.exists() or not candidate.is_dir():
-            return None
-        return candidate
-
-    def _iter_code_pack_candidate_paths(self, *, repo_root: Path) -> list[Path]:
-        candidates: list[Path] = []
-        explicit_pack_path = str(self._code_evidence_pack_path or "").strip()
-        if explicit_pack_path:
-            candidates.append(Path(explicit_pack_path).expanduser())
-
-        env_pack_path = str(os.getenv("VDS_AUDIT_CODE_EVIDENCE_PACK_PATH") or "").strip()
-        if env_pack_path:
-            candidates.append(Path(env_pack_path).expanduser())
-
-        candidates.append(repo_root / "evidence" / "code" / "code_evidence_pack.json")
-        candidates.append(repo_root.parent / "evidence" / "code" / "code_evidence_pack.json")
-
-        unique_candidates: list[Path] = []
-        seen: set[str] = set()
-        for candidate in candidates:
-            try:
-                resolved = candidate.resolve()
-            except Exception:
-                continue
-            marker = str(resolved)
-            if marker in seen:
-                continue
-            seen.add(marker)
-            unique_candidates.append(resolved)
-        return unique_candidates
-
-    def _load_code_evidence_pack(self, *, repo_root: Path) -> CodeEvidencePack | None:
-        if self._code_evidence_pack_cache is not self._UNSET:
-            return (
-                self._code_evidence_pack_cache if isinstance(self._code_evidence_pack_cache, CodeEvidencePack) else None
-            )
-
-        self._code_evidence_pack_cache = None
-        for candidate in self._iter_code_pack_candidate_paths(repo_root=repo_root):
-            if not candidate.exists() or not candidate.is_file():
-                continue
-            try:
-                self._code_evidence_pack_cache = CodeEvidencePack.load(candidate)
-                break
-            except Exception:
-                continue
-        return self._code_evidence_pack_cache if isinstance(self._code_evidence_pack_cache, CodeEvidencePack) else None
-
-    def _resolve_env_config_root(self, *, repo_root: Path) -> Path | None:
-        direct_root = self._normalize_existing_dir(str(os.getenv("VDS_AUDIT_CONFIG_ROOT") or "").strip())
-        if direct_root is not None:
-            return direct_root
-
-        app_config_root_value = str(os.getenv("VDS_AUDIT_APP_CONFIG_PATH") or "").strip()
-        app_config_root = self._normalize_existing_dir(app_config_root_value)
-        if app_config_root is None:
-            return None
-
-        try:
-            resolution = CodePackBuilder.resolve_config_path(app_config_root, repo_root.name)
-        except Exception:
-            resolution = None
-        if resolution is not None and resolution.matched and str(resolution.config_path or "").strip():
-            matched_root = self._normalize_existing_dir(str(resolution.config_path))
-            if matched_root is not None:
-                return matched_root
-        return app_config_root
-
-    @staticmethod
-    def _dedupe_paths(paths: list[Path]) -> list[Path]:
-        deduped: list[Path] = []
-        seen: set[str] = set()
-        for path in paths:
-            marker = str(path.resolve())
-            if marker in seen:
-                continue
-            seen.add(marker)
-            deduped.append(path)
-        return deduped
-
-    @staticmethod
-    def _derive_project_parent(repo_root: Path) -> Path | None:
-        """Derive the project-level parent directory from repo cache convention.
-
-        Convention: ``<effective-cache-root>/repos/<BB_PROJECT>-project/<repo>/``
-        Returns the ``<BB_PROJECT>-project/`` directory when the convention
-        matches, or ``None`` when the repo root does not follow the convention.
-        """
-        parent = repo_root.parent
-        if parent.name.endswith("-project"):
-            return parent
-        return None
-
-    @staticmethod
-    def _discover_same_project_roots(*, repo_root: Path, target_role: RepoRole) -> list[Path]:
-        """Discover sibling repos under the same ``<BB_PROJECT>-project/`` parent with the given role.
-
-        Uses the repo cache convention ``<effective-cache-root>/repos/<BB_PROJECT>-project/<repo>/``
-        and deterministic ``classify_repo_role()`` to find same-project lib or config repos
-        (DD-123.10, DD-123.12).
-        """
-        project_parent = repo_root.parent
-        if not project_parent.name.endswith("-project"):
-            return []
-        if not project_parent.is_dir():
-            return []
-
-        repo_name = repo_root.name
-        discovered: list[Path] = []
-        try:
-            siblings = sorted(project_parent.iterdir())
-        except OSError:
-            return []
-
-        for sibling in siblings:
-            if not sibling.is_dir() or sibling.name.startswith("."):
-                continue
-            if sibling.name == repo_name:
-                continue
-            role = classify_repo_role(repo_key=sibling.name, repo_path=sibling)
-            if role == target_role:
-                discovered.append(sibling.resolve(strict=False))
-
-        if discovered:
-            _log.info(
-                "same_project_roots_discovered",
-                target_role=str(target_role),
-                project_parent=str(project_parent),
-                discovered=[d.name for d in discovered],
-            )
-        return discovered
-
-    @classmethod
-    def _filter_repo_scoped_paths(
-        cls,
-        *,
-        repo_root: Path,
-        candidates: list[Path],
-        allow_same_project: bool = False,
-    ) -> list[Path]:
-        """Keep only roots that are inside the active repository root.
-
-        When *allow_same_project* is True, also accept roots that share the
-        same project-level parent directory (DD-123.11).  This enables
-        same-project sibling repos (e.g. ``CEP-project/campaign-common-lib/``)
-        to remain reachable while still blocking truly external paths.
-        """
-        project_parent: Path | None = None
-        if allow_same_project:
-            project_parent = cls._derive_project_parent(repo_root)
-
-        scoped: list[Path] = []
-        for candidate in candidates:
-            resolved_candidate = candidate.resolve(strict=False)
-            # Fast path: candidate is inside repo_root.
-            try:
-                resolved_candidate.relative_to(repo_root)
-                scoped.append(resolved_candidate)
-                continue
-            except ValueError:
-                pass
-            # Slow path: candidate shares the same project-level parent.
-            if project_parent is not None:
-                try:
-                    resolved_candidate.relative_to(project_parent)
-                    scoped.append(resolved_candidate)
-                    continue
-                except ValueError:
-                    pass
-        return scoped
-
-    def _resolve_config_roots(self, *, repo_root: Path) -> list[Path]:
-        roots: list[Path] = []
-        trusted_external_roots: list[Path] = []
-        explicit_root = self._normalize_existing_dir(self._config_root)
-        if explicit_root is not None:
-            roots.append(explicit_root)
-            trusted_external_roots.append(explicit_root)
-
-        env_root = self._resolve_env_config_root(repo_root=repo_root)
-        if env_root is not None:
-            roots.append(env_root)
-            trusted_external_roots.append(env_root)
-
-        pack = self._load_code_evidence_pack(repo_root=repo_root)
-        if pack is not None and pack.config_pack is not None:
-            pack_root = self._normalize_existing_dir(str(pack.config_pack.config_root or "").strip())
-            if pack_root is not None:
-                roots.append(pack_root)
-                trusted_external_roots.append(pack_root)
-
-        # Tier 3: DOPS/app-config fallback under the effective VDS cache root.
-        cache_root = get_vds_cache_root()
-        for dops_key in ("DOPS-project", "dops-project"):
-            dops_app_config = cache_root / "repos" / dops_key / "app-config"
-            if dops_app_config.is_dir():
-                roots.append(dops_app_config.resolve(strict=False))
-            dops_root = cache_root / "repos" / dops_key
-            if dops_root.is_dir():
-                roots.append(dops_root.resolve(strict=False))
-
-        # Phase 123 (TSK-123.6, DD-123.12): same-project sibling repos with RepoRole.CONFIG.
-        roots.extend(self._discover_same_project_roots(repo_root=repo_root, target_role=RepoRole.CONFIG))
-
-        scoped_roots = self._filter_repo_scoped_paths(
-            repo_root=repo_root.resolve(strict=False),
-            candidates=self._dedupe_paths(roots),
-            allow_same_project=True,
-        )
-        # Keep explicit/env/pack-discovered config roots even when they live
-        # outside the active project cache (for example DOPS/app-config).
-        return self._dedupe_paths([*trusted_external_roots, *scoped_roots])
-
-    def _resolve_env_lib_roots(self) -> list[Path]:
-        raw = str(os.getenv("VDS_AUDIT_LIB_ROOTS") or "").strip()
-        if not raw:
-            return []
-        roots: list[Path] = []
-        for token in re.split(r"[,\n]", raw):
-            path_value = token.strip()
-            if not path_value:
-                continue
-            root = self._normalize_existing_dir(path_value)
-            if root is not None:
-                roots.append(root)
-        return roots
-
-    def _resolve_lib_roots(self, *, repo_root: Path) -> list[tuple[str, Path]]:
-        roots: list[Path] = []
-        for path_value in self._lib_roots:
-            normalized = self._normalize_existing_dir(path_value)
-            if normalized is not None:
-                roots.append(normalized)
-        roots.extend(self._resolve_env_lib_roots())
-
-        pack = self._load_code_evidence_pack(repo_root=repo_root)
-        if pack is not None and pack.lib_pack is not None:
-            for pack_root in pack.lib_pack.lib_roots:
-                normalized = self._normalize_existing_dir(str(pack_root or "").strip())
-                if normalized is not None:
-                    roots.append(normalized)
-
-        # Phase 123 (TSK-123.5, DD-123.12): Tier 3 — same-project sibling repos with RepoRole.LIB.
-        roots.extend(self._discover_same_project_roots(repo_root=repo_root, target_role=RepoRole.LIB))
-
-        scoped_roots = self._filter_repo_scoped_paths(
-            repo_root=repo_root.resolve(strict=False),
-            candidates=self._dedupe_paths(roots),
-            allow_same_project=True,
-        )
-        deduped_roots = self._dedupe_paths(scoped_roots)
-        if not deduped_roots:
-            return []
-
-        named_roots: list[tuple[str, Path]] = []
-        name_counts: dict[str, int] = {}
-        for root in deduped_roots:
-            base_name = root.name or "lib"
-            index = name_counts.get(base_name, 0) + 1
-            name_counts[base_name] = index
-            slug = base_name if index == 1 else f"{base_name}-{index}"
-            named_roots.append((slug, root))
-        return named_roots
-
-    def _build_code_search_queries(self, query: str) -> list[str]:
-        normalized = str(query or "").strip()
-        if not normalized:
-            return []
-        queries: list[str] = []
-        normalized_seen: set[str] = set()
-
-        def _append_unique(candidate: str) -> None:
-            value = str(candidate or "").strip()
-            if not value:
-                return
-            key = value.lower()
-            if key in normalized_seen:
-                return
-            normalized_seen.add(key)
-            queries.append(value)
-
-        _append_unique(normalized)
-        dependency_query = self._is_project_scope_dependency_query(normalized)
-
-        # Security scan requirements often include generic severity words
-        # ("high"/"critical"), which produce noisy grep matches. Keep focused
-        # scan tokens and add stable recovery probes for scan artifacts.
-        if self._is_security_scan_query(normalized):
-            for term in self._extract_query_terms(normalized):
-                if self._is_generic_security_severity_term(term):
-                    continue
-                _append_unique(term)
-            for recovery_query in (
-                "sast dast security scan",
-                "vulnerability scan report",
-                "sonarqube trivy snyk zap",
-            ):
-                _append_unique(recovery_query)
-            return queries[:7]
-
-        if dependency_query:
-            for term in self._PROJECT_SCOPE_DEPENDENCY_QUERY_EXPANSION:
-                _append_unique(term)
-        for term in self._extract_query_terms(normalized):
-            _append_unique(term)
-        if dependency_query:
-            return queries[:10]
-        if self._is_db_decoupling_query(normalized):
-            for term in self._DB_RETRIEVAL_QUERY_EXPANSION:
-                _append_unique(term)
-            _append_unique("datasource entitymanager nativequery")
-            _append_unique("repository schema hibernate")
-            return queries[:12]
-        return queries[:7]
-
-    @classmethod
-    def _code_path_relevance_bonus(cls, *, path_value: str, query: str) -> float:
-        path_lower = cls._normalize_path_for_scoring(path_value)
-        query_lower = str(query or "").lower()
-        observability_terms = ("log", "logger", "audit", "monitor", "metric", "trace", "telemetry")
-        low_signal_terms = ("constant", "constants", "util", "utils", "dto", "entity", "model", "vo")
-        bonus = 0.0
-        if cls._is_doc_like_path(path_lower):
-            bonus -= 0.25
-        if any(token in query_lower for token in observability_terms):
-            if any(token in path_lower for token in observability_terms):
-                bonus += 0.20
-            if any(token in path_lower for token in low_signal_terms):
-                bonus -= 0.12
-        if cls._is_business_control_query(query_lower):
-            domain_bonus, has_domain_alignment = cls._business_control_domain_alignment(
-                path_lower=path_lower,
-                query_lower=query_lower,
-            )
-            bonus += domain_bonus
-            bonus += cls._business_control_low_signal_penalty(
-                path_lower=path_lower,
-                has_domain_alignment=has_domain_alignment,
-            )
-        if cls._is_db_decoupling_query(query_lower):
-            if any(
-                hint in path_lower
-                for hint in (
-                    "/config/database",
-                    "/repository/",
-                    "repository",
-                    "databaseconfig",
-                    "datasource",
-                    "entitymanager",
-                    "jdbctemplate",
-                    "nativequery",
-                )
-            ):
-                bonus += 0.28
-            if any(hint in path_lower for hint in ("/service/", "/impl/", "serviceimpl", "service/impl")):
-                bonus -= 0.18
-        return bonus
-
-    @staticmethod
-    def _is_doc_like_path(path_value: str) -> bool:
-        normalized = str(path_value or "").lower().replace("\\", "/")
-        return bool(re.search(r"\.(md|markdown|rst|adoc|txt)$", normalized) or "/docs/" in f"/{normalized}")
-
-    @staticmethod
-    def _normalize_path_for_scoring(path_value: str) -> str:
-        normalized = str(path_value or "").strip().lower().replace("\\", "/")
-        if not normalized:
-            return "/"
-        return normalized if normalized.startswith("/") else f"/{normalized}"
-
-    @classmethod
-    def _is_business_control_query(cls, query: str) -> bool:
-        normalized = str(query or "").strip().lower()
-        if not normalized:
-            return False
-        return any(
-            token in normalized for tokens in cls._BUSINESS_CONTROL_DOMAIN_TOKEN_GROUPS.values() for token in tokens
-        )
-
-    @classmethod
-    def _business_control_domain_alignment(cls, *, path_lower: str, query_lower: str) -> tuple[float, bool]:
-        aligned_groups = 0
-        bonus = 0.0
-        for tokens in cls._BUSINESS_CONTROL_DOMAIN_TOKEN_GROUPS.values():
-            if not any(token in query_lower for token in tokens):
-                continue
-            if any(token in path_lower for token in tokens):
-                aligned_groups += 1
-                bonus += 0.08
-        if aligned_groups >= 2:
-            bonus += 0.03
-        return min(0.27, bonus), aligned_groups > 0
-
-    @classmethod
-    def _business_control_low_signal_penalty(cls, *, path_lower: str, has_domain_alignment: bool) -> float:
-        penalty = 0.0
-        if any(token in path_lower for token in cls._BUSINESS_CONTROL_INTERNAL_PATH_HINTS):
-            penalty -= 0.22
-        if any(token in path_lower for token in cls._BUSINESS_CONTROL_TEST_PATH_HINTS):
-            penalty -= 0.20
-        if cls._has_hidden_dotfile_segment(path_lower):
-            penalty -= 0.16
-        if not has_domain_alignment and any(
-            token in path_lower for token in cls._BUSINESS_CONTROL_LOW_SIGNAL_PATH_HINTS
-        ):
-            penalty -= 0.12
-        return penalty
-
-    @classmethod
-    def _is_alerting_channel_query(cls, query: str) -> bool:
-        normalized = str(query or "").strip().lower()
-        if not normalized:
-            return False
-        has_channel_signal = any(token in normalized for token in cls._ALERTING_CHANNEL_TERMS)
-        has_intent_signal = any(token in normalized for token in cls._ALERTING_INTENT_TERMS)
-        return has_channel_signal and has_intent_signal
-
-    @classmethod
-    def _is_security_scan_query(cls, query: str) -> bool:
-        normalized = str(query or "").strip().lower()
-        if not normalized:
-            return False
-        if any(token in normalized for token in cls._SECURITY_SCAN_QUERY_TERMS):
-            return True
-        return "high" in normalized and "critical" in normalized and "security" in normalized
-
-    @classmethod
-    def _is_generic_security_severity_term(cls, term: str) -> bool:
-        normalized = str(term or "").strip().lower()
-        if not normalized:
-            return False
-        return normalized in cls._SECURITY_SCAN_GENERIC_SEVERITY_TERMS
-
-    @classmethod
-    def _is_security_scan_semantic_match(cls, *, path_value: str, excerpt: str) -> bool:
-        path_lower = cls._normalize_path_for_scoring(path_value)
-        haystack = f"{path_lower} {excerpt}".lower()
-        if any(token in haystack for token in cls._SECURITY_SCAN_SEMANTIC_TERMS):
-            return True
-        if any(token in path_lower for token in cls._SECURITY_SCAN_PATH_HINTS):
-            return True
-        has_severity_only_signal = any(token in haystack for token in ("high", "critical")) and not any(
-            token in haystack
-            for token in (
-                "sast",
-                "dast",
-                "scan",
-                "vulnerability",
-                "security",
-                "sonar",
-                "trivy",
-                "snyk",
-                "zap",
-                "cve",
-            )
-        )
-        if has_severity_only_signal:
-            return False
-        return False
-
-    @classmethod
-    def _is_alerting_semantic_match(cls, *, path_value: str, excerpt: str) -> bool:
-        haystack = f"{path_value} {excerpt}".lower()
-        has_channel_signal = any(token in haystack for token in cls._ALERTING_CHANNEL_TERMS)
-        has_intent_signal = any(token in haystack for token in cls._ALERTING_INTENT_TERMS)
-        return has_channel_signal and has_intent_signal
-
-    @classmethod
-    def _is_alerting_false_positive_match(cls, *, path_value: str, excerpt: str) -> bool:
-        haystack = f"{path_value} {excerpt}".lower()
-        if not any(pattern in haystack for pattern in cls._ALERTING_FALSE_POSITIVE_SNIPPETS):
-            return False
-        # Keep genuine alerting hits that explicitly include alerting intent even
-        # when they contain an ambiguous token like "slack".
-        return not any(token in haystack for token in cls._ALERTING_INTENT_TERMS)
-
-    @staticmethod
-    def _has_hidden_dotfile_segment(path_lower: str) -> bool:
-        segments = [segment for segment in str(path_lower or "").split("/") if segment not in {"", ".", ".."}]
-        return any(segment.startswith(".") for segment in segments)
-
-    def _read_doc_chunk(self, request: ReadDocChunkInput) -> ReadDocChunkOutput:
-        if not self._state_dsn or not self._project_key:
-            raise ToolExecutionError(
-                "missing_runtime_context",
-                "read_doc_chunk requires state_dsn and project_key",
-                details={"required": ["state_dsn", "project_key"]},
-            )
-
-        candidates = self._extract_doc_ref_candidates(request.ref)
-        chunk_id = (request.chunk_id or candidates.get("chunk_id") or "").strip() or None
-        source_uri = candidates.get("source_uri")
-        document_id = candidates.get("document_id")
-
-        if chunk_id is None and source_uri is None and document_id is None:
-            raise ToolExecutionError(
-                "invalid_doc_ref",
-                "read_doc_chunk requires chunk_id or ref with source_uri/document_id",
-                details={"ref": request.ref},
-            )
-
-        row = self._lookup_doc_chunk(
-            chunk_id=chunk_id,
-            source_uri=source_uri,
-            document_id=document_id,
-            repo_key=self._repo_key,
-        )
-        if row is None and self._repo_key:
-            row = self._lookup_doc_chunk(
-                chunk_id=chunk_id,
-                source_uri=source_uri,
-                document_id=document_id,
-                repo_key=None,
-            )
-        if row is None:
-            raise ToolExecutionError(
-                "doc_chunk_not_found",
-                "Document chunk not found in scoped state",
-                details={
-                    "project_key": self._project_key,
-                    "repo_key": self._repo_key,
-                    "chunk_id": chunk_id,
-                    "source_uri": source_uri,
-                    "document_id": document_id,
-                },
-            )
-        if self._is_excluded_docs_artifact(
-            source_uri=str(row.get("source_uri") or "").strip() or None,
-            document_id=str(row.get("document_id") or "").strip() or None,
-            source_type=str(row.get("source_type") or "").strip() or None,
-            metadata=row.get("document_metadata"),
-        ):
-            raise ToolExecutionError(
-                "doc_chunk_excluded",
-                "Requested document chunk is excluded from docs evidence scope",
-                details={
-                    "project_key": self._project_key,
-                    "repo_key": self._repo_key,
-                    "chunk_id": str(row.get("chunk_id") or chunk_id or ""),
-                    "source_uri": str(row.get("source_uri") or source_uri or ""),
-                    "document_id": str(row.get("document_id") or document_id or ""),
-                },
-            )
-
-        resolved_chunk_id = str(row.get("chunk_id") or chunk_id or "").strip()
-        resolved_ref = f"chunk:{resolved_chunk_id}" if resolved_chunk_id else str(request.ref)
-        return ReadDocChunkOutput(
-            ref=resolved_ref,
-            chunk_id=resolved_chunk_id or None,
-            content=str(row.get("content_text") or ""),
-            page_id=str(row.get("page_id") or "").strip() or None,
-            page_title=_extract_page_title(row.get("document_metadata")),
-            source_url=str(row.get("source_uri") or "").strip() or None,
-            space_key=_extract_space_key(row.get("document_metadata")),
-        )
-
-    def _read_code_file(self, request: ReadCodeFileInput) -> ReadCodeFileOutput:
-        repo_root = self._resolve_repo_root(require_exists=True)
-        prefixed_scope, normalized_path, inferred_line = self._extract_scoped_code_path(request.path)
-        effective_scope: Literal["code", "config", "lib"] = "code"
-        resolved_any_scope: tuple[Literal["code", "config", "lib"], Path, str] | None = None
-        if request.scope == "all":
-            effective_scope = prefixed_scope or "code"
-            if prefixed_scope is None:
-                resolved_any_scope = self._resolve_all_scope_code_path(
-                    repo_root=repo_root,
-                    path_value=normalized_path,
-                    config_root_filter=request.config_root_filter,
-                )
-                if resolved_any_scope is not None:
-                    effective_scope, target_file, output_path = resolved_any_scope
-        elif prefixed_scope is not None and prefixed_scope != request.scope:
-            raise ToolExecutionError(
-                "scope_path_mismatch",
-                "Requested path scope prefix does not match scope parameter",
-                details={"path": request.path, "scope": request.scope, "prefixed_scope": prefixed_scope},
-            )
-        else:
-            effective_scope = request.scope
-
-        if resolved_any_scope is None and effective_scope == "code":
-            target_file = self._resolve_repo_file(repo_root=repo_root, path_value=normalized_path)
-            output_path = target_file.relative_to(repo_root).as_posix()
-        elif resolved_any_scope is None and effective_scope == "config":
-            config_roots = self._filter_config_roots(
-                self._resolve_config_roots(repo_root=repo_root),
-                config_root_filter=request.config_root_filter,
-            )
-            if not config_roots:
-                raise ToolExecutionError(
-                    "code_file_not_found",
-                    "Requested code file does not exist",
-                    details={"path": request.path, "scope": effective_scope},
-                )
-            named_roots = [(root.name or "config", root) for root in config_roots]
-            target_file, output_path = self._resolve_file_from_named_roots(
-                named_roots=named_roots,
-                path_value=normalized_path,
-                scope=effective_scope,
-            )
-        elif resolved_any_scope is None:
-            lib_roots = self._resolve_lib_roots(repo_root=repo_root)
-            if not lib_roots:
-                raise ToolExecutionError(
-                    "code_file_not_found",
-                    "Requested code file does not exist",
-                    details={"path": request.path, "scope": effective_scope},
-                )
-            target_file, output_path = self._resolve_file_from_named_roots(
-                named_roots=lib_roots,
-                path_value=normalized_path,
-                scope=effective_scope,
-            )
-
-        if request.start_line is not None and request.end_line is not None and request.end_line < request.start_line:
-            raise ToolExecutionError(
-                "invalid_line_range",
-                "end_line must be greater than or equal to start_line",
-                details={"start_line": request.start_line, "end_line": request.end_line},
-            )
-        if not target_file.is_file():
-            raise ToolExecutionError(
-                "code_file_not_found",
-                "Requested code file does not exist",
-                details={"path": request.path},
-            )
-
-        file_text = target_file.read_text(encoding="utf-8", errors="replace")
-        all_lines = file_text.splitlines()
-        effective_start_line = request.start_line
-        effective_end_line = request.end_line
-        if effective_start_line is None and effective_end_line is None and inferred_line is not None:
-            effective_start_line = max(1, inferred_line - self._CODE_AUTO_READ_WINDOW_RADIUS)
-            effective_end_line = min(len(all_lines), inferred_line + self._CODE_AUTO_READ_WINDOW_RADIUS)
-
-        start_index = (effective_start_line - 1) if effective_start_line is not None else 0
-        end_index = effective_end_line if effective_end_line is not None else len(all_lines)
-        sliced_lines = all_lines[start_index:end_index]
-        content = "\n".join(sliced_lines)
-
-        output_ref = output_path
-        if inferred_line is not None:
-            output_ref = f"{output_path}:{inferred_line}"
-
-        return ReadCodeFileOutput(
-            path=output_ref,
-            content=content,
-            start_line=effective_start_line,
-            end_line=effective_end_line,
-        )
-
-    def _resolve_all_scope_code_path(
-        self,
-        *,
-        repo_root: Path,
-        path_value: str,
-        config_root_filter: str | None = None,
-    ) -> tuple[Literal["code", "config", "lib"], Path, str] | None:
-        normalized = str(path_value or "").strip()
-        if not normalized:
-            return None
-
-        target_file = self._resolve_repo_file(repo_root=repo_root, path_value=normalized)
-        if target_file.is_file():
-            return "code", target_file, target_file.relative_to(repo_root).as_posix()
-
-        lib_roots = self._resolve_lib_roots(repo_root=repo_root)
-        if lib_roots:
-            try:
-                target_file, output_path = self._resolve_file_from_named_roots(
-                    named_roots=lib_roots,
-                    path_value=normalized,
-                    scope="lib",
-                )
-                return "lib", target_file, output_path
-            except ToolExecutionError:
-                pass
-
-        config_roots = self._filter_config_roots(
-            self._resolve_config_roots(repo_root=repo_root),
-            config_root_filter=config_root_filter,
-        )
-        if config_roots:
-            named_roots = [(root.name or "config", root) for root in config_roots]
-            try:
-                target_file, output_path = self._resolve_file_from_named_roots(
-                    named_roots=named_roots,
-                    path_value=normalized,
-                    scope="config",
-                )
-                return "config", target_file, output_path
-            except ToolExecutionError:
-                pass
-
-        return None
-
-    @staticmethod
-    def _extract_scoped_code_path(path_value: str) -> tuple[Literal["code", "config", "lib"] | None, str, int | None]:
-        normalized = str(path_value or "").strip()
-        if not normalized:
-            return None, "", None
-        prefix, separator, remainder = normalized.partition(":")
-        if separator != ":" or prefix not in {"code", "config", "lib"}:
-            scoped_path, inferred_line = ToolRegistry._extract_line_hint(normalized)
-            return None, scoped_path, inferred_line
-        scoped_path, inferred_line = ToolRegistry._extract_line_hint(remainder.strip())
-        return cast("Literal['code', 'config', 'lib']", prefix), scoped_path, inferred_line
-
-    @staticmethod
-    def _extract_line_hint(path_value: str) -> tuple[str, int | None]:
-        normalized = str(path_value or "").strip()
-        if ":" not in normalized:
-            return normalized, None
-        maybe_path, maybe_line = normalized.rsplit(":", 1)
-        if maybe_line.isdigit() and maybe_path.strip():
-            line_number = int(maybe_line)
-            if line_number >= 1:
-                return maybe_path.strip(), line_number
-        return normalized, None
-
-    def _resolve_file_from_named_roots(
-        self,
-        *,
-        named_roots: list[tuple[str, Path]],
-        path_value: str,
-        scope: Literal["config", "lib"],
-    ) -> tuple[Path, str]:
-        normalized = str(path_value or "").strip().replace("\\", "/")
-        if not normalized:
-            raise ToolExecutionError(
-                "invalid_code_path",
-                "Requested code path is empty",
-                details={"path": path_value, "scope": scope},
-            )
-
-        root_map = dict(named_roots)
-        root_name, separator, remainder = normalized.partition("/")
-        preferred_root: tuple[str, Path] | None = None
-        relative_path = normalized
-        if separator and root_name in root_map:
-            preferred_root = (root_name, root_map[root_name])
-            relative_path = remainder
-
-        if scope == "lib" and preferred_root is None:
-            raise ToolExecutionError(
-                "invalid_code_path",
-                "Lib scope path must be prefixed with '<repo-slug>/'",
-                details={
-                    "path": path_value,
-                    "scope": scope,
-                    "required_prefixes": sorted(root_map),
-                },
-            )
-
-        candidate_roots = [preferred_root] if preferred_root is not None else named_roots
-        for candidate in candidate_roots:
-            assert candidate is not None
-            root_label, root_path = candidate
-            target_file = self._resolve_repo_file(repo_root=root_path, path_value=relative_path)
-            if not target_file.is_file():
-                continue
-            relative = target_file.relative_to(root_path).as_posix()
-            display_path = relative if scope == "config" else f"{root_label}/{relative}"
-            return target_file, display_path
-
-        raise ToolExecutionError(
-            "code_file_not_found",
-            "Requested code file does not exist",
-            details={
-                "path": path_value,
-                "scope": scope,
-                "roots": [name for name, _root in named_roots],
-            },
-        )
-
-    def _get_row_context(self, request: GetRowContextInput) -> GetRowContextOutput:
-        # Returns normalized row context for loop planners.
-        return GetRowContextOutput(
-            row_id=request.row_id,
-            context={
-                "check_id": request.check_id,
-                "requirement_text": request.requirement_text,
-                "requirement_category": request.requirement_category,
-                "detailed_guidance": request.detailed_guidance,
-                "check_manual": request.check_manual,
-                "seed_evidence_ref_count": len(request.evidence_refs),
-            },
-        )
-
-    def _record_evidence_refs(self, request: RecordEvidenceRefsInput) -> RecordEvidenceRefsOutput:
-        existing = self._evidence_store.get(request.row_id, [])
-        seen = {(ref.ref_type, ref.ref_value) for ref in existing}
-        accepted = list(existing)
-
-        for ref in request.refs:
-            key = (ref.ref_type, ref.ref_value)
-            if key in seen:
-                continue
-            accepted.append(ref)
-            seen.add(key)
-
-        self._evidence_store[request.row_id] = accepted
-        return RecordEvidenceRefsOutput(
-            row_id=request.row_id,
-            accepted_count=len(accepted),
-            refs=accepted,
-        )
-
-    @staticmethod
-    def _record_skill_tool_usage(entry: dict[str, Any]) -> None:
-        try:
-            from vds_agent_core.skills.executor import SkillExecutor
-
-            SkillExecutor.record_tool_usage(dict(entry))
-        except Exception:
-            return
-
-    @staticmethod
-    def _normalize_skill_identifier(value: str) -> str:
-        normalized = str(value or "").strip().lower()
-        if not normalized:
-            return ""
-        normalized = re.sub(r"[\s_]+", "-", normalized)
-        normalized = re.sub(r"-{2,}", "-", normalized)
-        return normalized
-
-    @classmethod
-    def _build_skill_aliases(cls, *values: str | None) -> set[str]:
-        aliases: set[str] = set()
-        for value in values:
-            text = str(value or "").strip()
-            if not text:
-                continue
-            aliases.add(text)
-            normalized = cls._normalize_skill_identifier(text)
-            if normalized:
-                aliases.add(normalized)
-        return aliases
-
-    def _resolve_skills_runtime_policy(self) -> dict[str, Any]:
-        def _normalize_skill_directories(raw_directories: list[str]) -> list[str]:
-            normalized: list[str] = []
-            seen: set[str] = set()
-            for raw_path in raw_directories:
-                value = str(raw_path).strip()
-                if not value:
-                    continue
-                try:
-                    resolved = str(Path(value).expanduser().resolve(strict=False))
-                except Exception:
-                    resolved = value
-                if resolved in seen:
-                    continue
-                seen.add(resolved)
-                if Path(resolved).is_dir():
-                    normalized.append(resolved)
-            return normalized
-
-        def _env_bool(name: str) -> tuple[bool, bool]:
-            raw = os.getenv(name)
-            if raw is None:
-                return (False, False)
-            normalized = str(raw).strip().lower()
-            return (True, normalized in {"true", "1", "yes", "on"})
-
-        def _env_list(name: str) -> tuple[bool, list[str]]:
-            raw = os.getenv(name)
-            if raw is None:
-                return (False, [])
-            value = str(raw).strip()
-            if not value:
-                return (True, [])
-            if value.startswith("["):
-                try:
-                    parsed = json.loads(value)
-                except json.JSONDecodeError:
-                    return (True, [])
-                if isinstance(parsed, list):
-                    return (True, [str(item).strip() for item in parsed if str(item).strip()])
-                return (True, [])
-            return (True, [item.strip() for item in value.split(",") if item.strip()])
-
-        def _env_trust_tier_map(name: str) -> tuple[bool, dict[str, str]]:
-            raw = os.getenv(name)
-            if raw is None:
-                return (False, {})
-            value = str(raw).strip()
-            if not value:
-                return (True, {})
-            try:
-                parsed = json.loads(value)
-            except json.JSONDecodeError:
-                return (True, {})
-            if not isinstance(parsed, dict):
-                return (True, {})
-            validated: dict[str, str] = {}
-            for raw_name, raw_tier in parsed.items():
-                normalized_name = self._normalize_skill_identifier(str(raw_name))
-                tier = str(raw_tier).strip()
-                if normalized_name and tier:
-                    validated[normalized_name] = tier
-            return (True, validated)
-
-        defaults = {
-            "enabled": False,
-            "directories": [],
-            "allowlist": [],
-            "allowed_trust_tiers": [],
-            "default_trust_tier": "external-unverified",
-            "trust_tiers": {},
-            "allow_script_execution": False,
-        }
-        enabled_present, enabled_env = _env_bool("VDS_AUDIT_LLM__SKILLS_TOOLSET_ENABLED")
-        directories_present, directories_env = _env_list("VDS_AUDIT_LLM__SKILLS_DIRECTORIES")
-        allowlist_present, allowlist_env = _env_list("VDS_AUDIT_LLM__SKILLS_ALLOWLIST")
-        allowed_tiers_present, allowed_tiers_env = _env_list("VDS_AUDIT_LLM__SKILLS_ALLOWED_TRUST_TIERS")
-        allow_script_present, allow_script_env = _env_bool("VDS_AUDIT_LLM__SKILLS_ALLOW_SCRIPT_EXECUTION")
-        trust_tiers_present, trust_tiers_env = _env_trust_tier_map("VDS_AUDIT_LLM__SKILLS_TRUST_TIERS")
-        default_tier_raw = os.getenv("VDS_AUDIT_LLM__SKILLS_DEFAULT_TRUST_TIER")
-        default_tier_present = default_tier_raw is not None
-        default_tier_env = str(default_tier_raw or "").strip()
-        try:
-            from vds_audit_orchestrator.config import get_config
-
-            llm_cfg = get_config().llm
-        except Exception:
-            llm_cfg = None
-
-        policy = dict(defaults)
-        if llm_cfg is not None:
-            policy["enabled"] = bool(getattr(llm_cfg, "skills_toolset_enabled", False))
-            policy["directories"] = [
-                str(item).strip() for item in (getattr(llm_cfg, "skills_directories", []) or []) if str(item).strip()
-            ]
-            policy["allowlist"] = [
-                str(item).strip() for item in (getattr(llm_cfg, "skills_allowlist", []) or []) if str(item).strip()
-            ]
-            policy["allowed_trust_tiers"] = [
-                str(item).strip()
-                for item in (getattr(llm_cfg, "skills_allowed_trust_tiers", []) or [])
-                if str(item).strip()
-            ]
-            trust_tiers_cfg: dict[str, str] = {}
-            for raw_name, raw_tier in dict(getattr(llm_cfg, "skills_trust_tiers", {}) or {}).items():
-                normalized = self._normalize_skill_identifier(str(raw_name))
-                tier_value = str(raw_tier).strip()
-                if normalized and tier_value:
-                    trust_tiers_cfg[normalized] = tier_value
-            policy["trust_tiers"] = trust_tiers_cfg
-            default_tier_cfg = str(getattr(llm_cfg, "skills_default_trust_tier", "external-unverified")).strip()
-            policy["default_trust_tier"] = default_tier_cfg or "external-unverified"
-            policy["allow_script_execution"] = bool(getattr(llm_cfg, "skills_allow_script_execution", False))
-
-        # Environment/profile overrides must remain authoritative for runtime behavior.
-        if enabled_present:
-            policy["enabled"] = enabled_env
-        if directories_present:
-            policy["directories"] = directories_env
-        if allowlist_present:
-            policy["allowlist"] = allowlist_env
-        if allowed_tiers_present:
-            policy["allowed_trust_tiers"] = allowed_tiers_env
-        if trust_tiers_present:
-            policy["trust_tiers"] = trust_tiers_env
-        if default_tier_present and default_tier_env:
-            policy["default_trust_tier"] = default_tier_env
-        if allow_script_present:
-            policy["allow_script_execution"] = allow_script_env
-        resolved_directories = _normalize_skill_directories([str(item) for item in (policy.get("directories") or [])])
-        if not resolved_directories:
-            try:
-                from vds_audit_orchestrator.agents.toolsets.skills_toolset import DEFAULT_AUDIT_SKILLS
-            except Exception:
-                DEFAULT_AUDIT_SKILLS = []
-            resolved_directories = _normalize_skill_directories([str(item) for item in (DEFAULT_AUDIT_SKILLS or [])])
-        policy["directories"] = resolved_directories
-        return policy
-
-    @staticmethod
-    def _collect_skills_metadata(
-        *,
-        directories: list[str],
-        default_trust_tier: Literal["internal", "external-verified", "external-unverified"],
-    ) -> list[Any]:
-        try:
-            from vds_audit_orchestrator.agents.toolsets.skills_toolset import (
-                SkillsToolsetConfig,
-                get_skills_metadata,
-            )
-        except Exception:
-            return []
-        try:
-            return list(
-                get_skills_metadata(
-                    SkillsToolsetConfig(
-                        directories=directories,
-                        default_trust_tier=default_trust_tier,
-                    )
-                )
-            )
-        except Exception:
-            return []
-
-    def _build_skills_catalog(self, *, force_refresh: bool = False) -> list[dict[str, Any]]:
-        if self._skills_catalog_cache is not None and not force_refresh:
-            return list(self._skills_catalog_cache)
-
-        policy = self._resolve_skills_runtime_policy()
-        if not bool(policy.get("enabled")):
-            self._skills_catalog_cache = []
-            return []
-
-        directories = [str(item).strip() for item in (policy.get("directories") or []) if str(item).strip()]
-        if not directories:
-            self._skills_catalog_cache = []
-            return []
-
-        metadata = self._collect_skills_metadata(
-            directories=directories,
-            default_trust_tier=cast(
-                "Literal['internal', 'external-verified', 'external-unverified']",
-                str(policy.get("default_trust_tier") or "external-unverified"),
-            ),
-        )
-        allowlist = {
-            self._normalize_skill_identifier(item)
-            for item in (policy.get("allowlist") or [])
-            if self._normalize_skill_identifier(str(item))
-        }
-        allowed_trust_tiers = {
-            str(item).strip() for item in (policy.get("allowed_trust_tiers") or []) if str(item).strip()
-        }
-        trust_tier_overrides = {
-            self._normalize_skill_identifier(str(name)): str(tier).strip()
-            for name, tier in dict(policy.get("trust_tiers") or {}).items()
-            if self._normalize_skill_identifier(str(name)) and str(tier).strip()
-        }
-        default_trust_tier = str(policy.get("default_trust_tier") or "external-unverified")
-
-        catalog: list[dict[str, Any]] = []
-        seen: set[str] = set()
-        for item in metadata:
-            canonical_name = str(
-                getattr(item, "name", None)
-                or getattr(item, "canonical_name", None)
-                or getattr(item, "frontmatter_name", None)
-                or getattr(item, "metadata_name", None)
-                or ""
-            ).strip()
-            if not canonical_name:
-                continue
-            aliases = self._build_skill_aliases(
-                canonical_name,
-                str(getattr(item, "metadata_name", "") or ""),
-                str(getattr(item, "frontmatter_name", "") or ""),
-                str(getattr(item, "runtime_name", "") or ""),
-                str(getattr(item, "canonical_name", "") or ""),
-            )
-            if allowlist and aliases.isdisjoint(allowlist):
-                continue
-
-            trust_tier = str(getattr(item, "trust_tier", "") or "").strip() or default_trust_tier
-            for alias in aliases:
-                normalized_alias = self._normalize_skill_identifier(alias)
-                if normalized_alias in trust_tier_overrides:
-                    trust_tier = trust_tier_overrides[normalized_alias]
-                    break
-            if allowed_trust_tiers and trust_tier not in allowed_trust_tiers:
-                continue
-
-            path_value = str(getattr(item, "path", "") or "").strip()
-            if not path_value:
-                continue
-            path_obj = Path(path_value).expanduser().resolve()
-            if not path_obj.is_dir():
-                continue
-
-            normalized_name = self._normalize_skill_identifier(canonical_name)
-            if normalized_name in seen:
-                continue
-            seen.add(normalized_name)
-            catalog.append(
-                {
-                    "name": canonical_name,
-                    "description": str(getattr(item, "description", "") or "") or None,
-                    "trust_tier": trust_tier,
-                    "path": str(path_obj),
-                    "has_scripts": bool(getattr(item, "has_scripts", False)),
-                    "content_hash": str(getattr(item, "content_hash", "") or "") or None,
-                    "aliases": aliases,
-                }
-            )
-
-        catalog.sort(key=lambda row: str(row.get("name") or "").lower())
-        self._skills_catalog_cache = catalog
-        return list(catalog)
-
-    def _find_skill_entry(self, skill_name: str) -> dict[str, Any] | None:
-        normalized_query = self._normalize_skill_identifier(skill_name)
-        if not normalized_query:
-            return None
-        catalog = self._build_skills_catalog()
-        for entry in catalog:
-            aliases = {
-                self._normalize_skill_identifier(alias)
-                for alias in (entry.get("aliases") or set())
-                if self._normalize_skill_identifier(str(alias))
-            }
-            if normalized_query in aliases:
-                return entry
-
-        for entry in catalog:
-            name = self._normalize_skill_identifier(str(entry.get("name") or ""))
-            if normalized_query in name:
-                return entry
-        return None
-
-    @staticmethod
-    def _clip_text(content: str, *, max_chars: int) -> str:
-        if len(content) <= max_chars:
-            return content
-        return content[:max_chars]
-
-    @staticmethod
-    def _enumerate_skill_assets(skill_dir: Path) -> tuple[list[str], list[str]]:
-        resources: list[str] = []
-        scripts: list[str] = []
-
-        skill_md = skill_dir / "SKILL.md"
-        if skill_md.is_file():
-            resources.append("SKILL.md")
-
-        for folder_name in ("references", "assets"):
-            folder = skill_dir / folder_name
-            if not folder.is_dir():
-                continue
-            for path in sorted(folder.rglob("*")):
-                if not path.is_file():
-                    continue
-                resources.append(path.relative_to(skill_dir).as_posix())
-                if len(resources) >= 80:
-                    break
-            if len(resources) >= 80:
-                break
-
-        scripts_dir = skill_dir / "scripts"
-        if scripts_dir.is_dir():
-            for path in sorted(scripts_dir.rglob("*")):
-                if not path.is_file():
-                    continue
-                scripts.append(path.relative_to(skill_dir).as_posix())
-                if len(scripts) >= 50:
-                    break
-        return resources, scripts
-
-    @staticmethod
-    def _resolve_path_in_skill(
-        *,
-        skill_dir: Path,
-        relative_or_absolute: str,
-    ) -> tuple[Path | None, str | None]:
-        raw = Path(relative_or_absolute)
-        target = raw.expanduser().resolve() if raw.is_absolute() else (skill_dir / raw).resolve()
-        try:
-            target.relative_to(skill_dir)
-        except ValueError:
-            return None, "path_traversal_denied"
-        if not target.is_file():
-            return None, "resource_not_found"
-        return target, None
-
-    @staticmethod
-    def _resolve_skill_resource_candidates(resource_path: str) -> list[str]:
-        normalized = str(resource_path or "").strip()
-        if not normalized:
-            return ["SKILL.md"]
-        normalized_key = normalized.replace("\\", "/").strip().lower()
-        if normalized_key in {"@row-analysis", "row-analysis", "row_analysis", "references/row-analysis.md"}:
-            return ["references/row-analysis.md", "SKILL.md"]
-        if normalized_key in {"detect-migrations", "detect_migrations", "@detect-migrations"}:
-            return ["references/detection-strategy.md", "references/row-analysis.md", "SKILL.md"]
-        return [normalized]
-
-    @staticmethod
-    def _is_actionable_skill_resource_path(resource_path: Any) -> bool:
-        normalized = str(resource_path or "").strip().replace("\\", "/").lower()
-        if not normalized:
-            return False
-        if normalized.endswith("/skill.md") or normalized == "skill.md":
-            return False
-        if "row-analysis" in normalized:
-            return True
-        return normalized.startswith("references/")
-
-    def _list_skills(self, request: ListSkillsInput) -> ListSkillsOutput:
-        query = str(request.query or "").strip().lower()
-        items: list[SkillInfo] = []
-        for entry in self._build_skills_catalog():
-            name = str(entry.get("name") or "")
-            description = str(entry.get("description") or "")
-            if query and query not in name.lower() and query not in description.lower():
-                continue
-            items.append(
-                SkillInfo(
-                    name=name,
-                    description=description or None,
-                    trust_tier=str(entry.get("trust_tier") or "") or None,
-                    has_scripts=bool(entry.get("has_scripts", False)),
-                    path=str(entry.get("path") or ""),
-                )
-            )
-            if len(items) >= request.limit:
-                break
-        self._record_skill_tool_usage(
-            {
-                "tool": ToolName.LIST_SKILLS.value,
-                "query": request.query,
-                "results_count": len(items),
-                "success": True,
-                "effective": len(items) > 0,
-            }
-        )
-        return ListSkillsOutput(skills=items)
-
-    def _load_skill(self, request: LoadSkillInput) -> LoadSkillOutput:
-        entry = self._find_skill_entry(request.name)
-        if entry is None:
-            self._record_skill_tool_usage(
-                {
-                    "tool": ToolName.LOAD_SKILL.value,
-                    "skill": request.name,
-                    "success": False,
-                    "effective": False,
-                    "error": "skill_not_found",
-                }
-            )
-            return LoadSkillOutput(
-                name=request.name,
-                found=False,
-                error="skill_not_found",
-            )
-
-        skill_dir = Path(str(entry.get("path") or "")).resolve()
-        resources, scripts = self._enumerate_skill_assets(skill_dir)
-        output = LoadSkillOutput(
-            name=request.name,
-            found=True,
-            resolved_name=str(entry.get("name") or request.name),
-            path=str(skill_dir),
-            description=str(entry.get("description") or "") or None,
-            trust_tier=str(entry.get("trust_tier") or "") or None,
-            has_scripts=bool(entry.get("has_scripts", False)),
-            resources=resources,
-            scripts=scripts,
-            content_hash=str(entry.get("content_hash") or "") or None,
-        )
-        self._record_skill_tool_usage(
-            {
-                "tool": ToolName.LOAD_SKILL.value,
-                "skill": output.resolved_name,
-                "success": True,
-                "effective": bool(resources or scripts),
-            }
-        )
-        return output
-
-    def _read_skill_resource(self, request: ReadSkillResourceInput) -> ReadSkillResourceOutput:
-        entry = self._find_skill_entry(request.name)
-        requested_resource_path = str(request.resource_path or "").strip() or "SKILL.md"
-        if entry is None:
-            self._record_skill_tool_usage(
-                {
-                    "tool": ToolName.READ_SKILL_RESOURCE.value,
-                    "skill": request.name,
-                    "resource": requested_resource_path,
-                    "requested_resource": requested_resource_path,
-                    "success": False,
-                    "effective": False,
-                    "error": "skill_not_found",
-                }
-            )
-            return ReadSkillResourceOutput(
-                name=request.name,
-                resource_path=requested_resource_path,
-                success=False,
-                error="skill_not_found",
-            )
-
-        skill_dir = Path(str(entry.get("path") or "")).resolve()
-        target: Path | None = None
-        error: str | None = None
-        resolved_resource_path = requested_resource_path
-        for candidate in self._resolve_skill_resource_candidates(requested_resource_path):
-            maybe_target, maybe_error = self._resolve_path_in_skill(
-                skill_dir=skill_dir,
-                relative_or_absolute=candidate,
-            )
-            if maybe_target is not None:
-                target = maybe_target
-                resolved_resource_path = candidate
-                error = None
-                break
-            if maybe_error and error is None:
-                error = maybe_error
-        if target is None:
-            self._record_skill_tool_usage(
-                {
-                    "tool": ToolName.READ_SKILL_RESOURCE.value,
-                    "skill": str(entry.get("name") or request.name),
-                    "resource": requested_resource_path,
-                    "requested_resource": requested_resource_path,
-                    "success": False,
-                    "effective": False,
-                    "error": error or "resource_not_found",
-                }
-            )
-            return ReadSkillResourceOutput(
-                name=str(entry.get("name") or request.name),
-                resource_path=requested_resource_path,
-                success=False,
-                error=error or "resource_not_found",
-            )
-
-        try:
-            content = target.read_text(encoding="utf-8", errors="replace")
-        except OSError as exc:
-            self._record_skill_tool_usage(
-                {
-                    "tool": ToolName.READ_SKILL_RESOURCE.value,
-                    "skill": str(entry.get("name") or request.name),
-                    "resource": resolved_resource_path,
-                    "requested_resource": requested_resource_path,
-                    "success": False,
-                    "effective": False,
-                    "error": f"read_failed:{exc}",
-                }
-            )
-            return ReadSkillResourceOutput(
-                name=str(entry.get("name") or request.name),
-                resource_path=resolved_resource_path,
-                success=False,
-                error="resource_read_failed",
-            )
-
-        clipped = self._clip_text(content, max_chars=request.max_chars)
-        informational = bool(clipped.strip())
-        effective = informational and self._is_actionable_skill_resource_path(resolved_resource_path)
-        skill_name = str(entry.get("name") or request.name)
-        resource_fell_back = resolved_resource_path != requested_resource_path
-        self._record_skill_tool_usage(
-            {
-                "tool": ToolName.READ_SKILL_RESOURCE.value,
-                "skill": skill_name,
-                "resource": resolved_resource_path,
-                "requested_resource": requested_resource_path,
-                "success": True,
-                "effective": effective,
-                "informational": informational,
-                "benefit_signal": effective,
-                "content_length": len(clipped),
-            }
-        )
-        # P172-F (TSK-172.36): emit observable fallback event when SKILL.md served instead of
-        # the requested resource, so callers can surface silent fallbacks in telemetry.
-        if resource_fell_back:
-            self._record_skill_tool_usage(
-                {
-                    "event": "skill_resource_fallback",
-                    "tool": ToolName.READ_SKILL_RESOURCE.value,
-                    "skill_name": skill_name,
-                    "requested_resource": requested_resource_path,
-                    "actual_resource": resolved_resource_path,
-                    "fallback_reason": "requested_resource_missing",
-                }
-            )
-        return ReadSkillResourceOutput(
-            name=skill_name,
-            resource_path=resolved_resource_path,
-            success=True,
-            content=clipped,
-            ref=str(target),
-            requested_resource_fallback=resource_fell_back,
-            fallback_reason="requested_resource_missing" if resource_fell_back else None,
-        )
-
-    def _run_skill_script(self, request: RunSkillScriptInput) -> RunSkillScriptOutput:
-        policy = self._resolve_skills_runtime_policy()
-        if not bool(policy.get("allow_script_execution")):
-            self._record_skill_tool_usage(
-                {
-                    "tool": ToolName.RUN_SKILL_SCRIPT.value,
-                    "skill": request.name,
-                    "script": request.script_path,
-                    "success": False,
-                    "effective": False,
-                    "error": "script_execution_disabled",
-                }
-            )
-            return RunSkillScriptOutput(
-                name=request.name,
-                script_path=request.script_path,
-                success=False,
-                error="script_execution_disabled",
-            )
-
-        entry = self._find_skill_entry(request.name)
-        if entry is None:
-            self._record_skill_tool_usage(
-                {
-                    "tool": ToolName.RUN_SKILL_SCRIPT.value,
-                    "skill": request.name,
-                    "script": request.script_path,
-                    "success": False,
-                    "effective": False,
-                    "error": "skill_not_found",
-                }
-            )
-            return RunSkillScriptOutput(
-                name=request.name,
-                script_path=request.script_path,
-                success=False,
-                error="skill_not_found",
-            )
-
-        skill_dir = Path(str(entry.get("path") or "")).resolve()
-        script_path, error = self._resolve_path_in_skill(
-            skill_dir=skill_dir,
-            relative_or_absolute=request.script_path,
-        )
-        if script_path is None:
-            self._record_skill_tool_usage(
-                {
-                    "tool": ToolName.RUN_SKILL_SCRIPT.value,
-                    "skill": str(entry.get("name") or request.name),
-                    "script": request.script_path,
-                    "success": False,
-                    "effective": False,
-                    "error": error or "script_not_found",
-                }
-            )
-            return RunSkillScriptOutput(
-                name=str(entry.get("name") or request.name),
-                script_path=request.script_path,
-                success=False,
-                error=error or "script_not_found",
-            )
-
-        command = [str(script_path), *request.args]
-        try:
-            completed = subprocess.run(
-                command,
-                check=False,
-                capture_output=True,
-                text=True,
-                timeout=request.timeout_seconds,
-            )
-        except subprocess.TimeoutExpired:
-            self._record_skill_tool_usage(
-                {
-                    "tool": ToolName.RUN_SKILL_SCRIPT.value,
-                    "skill": str(entry.get("name") or request.name),
-                    "script": request.script_path,
-                    "success": False,
-                    "effective": False,
-                    "error": "timeout",
-                }
-            )
-            return RunSkillScriptOutput(
-                name=str(entry.get("name") or request.name),
-                script_path=request.script_path,
-                success=False,
-                error="script_timeout",
-            )
-        except OSError as exc:
-            self._record_skill_tool_usage(
-                {
-                    "tool": ToolName.RUN_SKILL_SCRIPT.value,
-                    "skill": str(entry.get("name") or request.name),
-                    "script": request.script_path,
-                    "success": False,
-                    "effective": False,
-                    "error": f"execution_error:{exc}",
-                }
-            )
-            return RunSkillScriptOutput(
-                name=str(entry.get("name") or request.name),
-                script_path=request.script_path,
-                success=False,
-                error="script_execution_failed",
-            )
-
-        stdout = self._clip_text(str(completed.stdout or ""), max_chars=6000)
-        stderr = self._clip_text(str(completed.stderr or ""), max_chars=4000)
-        success = completed.returncode == 0
-        self._record_skill_tool_usage(
-            {
-                "tool": ToolName.RUN_SKILL_SCRIPT.value,
-                "skill": str(entry.get("name") or request.name),
-                "script": request.script_path,
-                "success": success,
-                "effective": bool(success and stdout.strip()),
-                "returncode": completed.returncode,
-            }
-        )
-        return RunSkillScriptOutput(
-            name=str(entry.get("name") or request.name),
-            script_path=request.script_path,
-            success=success,
-            stdout=stdout,
-            stderr=stderr,
-            returncode=int(completed.returncode),
-            error=None if success else "script_failed",
-        )
-
-    def _get_doc_query_adapter(self) -> StateBackedEvidenceQueryAdapter:
-        if self._doc_query_adapter is None:
-            self._doc_query_adapter = StateBackedEvidenceQueryAdapter(state_dsn=self._state_dsn)
-        return self._doc_query_adapter
-
-    def _get_state_store(self) -> PostgresStateStore:
-        if self._state_store is None:
-            self._state_store = PostgresStateStore(self._state_dsn)
-        return self._state_store
-
-    def _resolve_repo_root(self, *, require_exists: bool) -> Path:
-        repo_root = Path(self._repo_path).resolve() if self._repo_path else None
-        if repo_root is None:
-            raise ToolExecutionError(
-                "missing_runtime_context",
-                "repo_path is required for code tools",
-                details={"required": ["repo_path"]},
-            )
-        if require_exists and (not repo_root.exists() or not repo_root.is_dir()):
-            raise ToolExecutionError(
-                "repo_path_not_found",
-                "Configured repo_path does not exist or is not a directory",
-                details={"repo_path": self._repo_path},
-            )
-        return repo_root
-
-    @staticmethod
-    def _split_rg_line(line: str) -> tuple[str | None, str | None, str]:
-        parts = line.split(":", 2)
-        if len(parts) != 3:
-            return None, None, ""
-        return parts[0], parts[1], parts[2]
-
-    @staticmethod
-    def _extract_doc_ref_candidates(ref: str) -> dict[str, str]:
-        normalized = str(ref or "").strip()
-        if not normalized:
-            return {}
-        if normalized.startswith("chunk:"):
-            return {"chunk_id": normalized.removeprefix("chunk:").strip()}
-        if normalized.startswith("source_uri:"):
-            return {"source_uri": normalized.removeprefix("source_uri:").strip()}
-        if normalized.startswith("document_id:"):
-            return {"document_id": normalized.removeprefix("document_id:").strip()}
-        if "://" in normalized:
-            try:
-                page_id = parse_qs(urlparse(normalized).query).get("pageId", [None])[0]
-            except Exception:
-                page_id = None
-            if page_id and str(page_id).strip().isdigit():
-                return {"document_id": str(page_id).strip()}
-            return {"source_uri": normalized}
-        return {"document_id": normalized}
-
-    def _lookup_doc_chunk(
-        self,
-        *,
-        chunk_id: str | None,
-        source_uri: str | None,
-        document_id: str | None,
-        repo_key: str | None,
-    ) -> Mapping[str, Any] | None:
-        store = self._get_state_store()
-        with store._conn.cursor() as cur:
-            cur.execute(
-                """
-                WITH scoped_project AS (
-                    SELECT id
-                    FROM audit_state.projects
-                    WHERE project_key = %s
-                    LIMIT 1
-                ),
-                scoped_repo AS (
-                    SELECT repos.id
-                    FROM audit_state.repos AS repos
-                    JOIN scoped_project
-                      ON scoped_project.id = repos.project_id
-                    WHERE %s::text IS NOT NULL
-                      AND repos.repo_key = %s
-                    LIMIT 1
-                )
-                SELECT
-                    d.document_id,
-                    d.source_uri,
-                    d.source_type,
-                    d.page_id,
-                    d.metadata AS document_metadata,
-                    c.chunk_id,
-                    c.content_text
-                FROM audit_state.corpus_documents AS d
-                JOIN audit_state.corpus_chunks AS c
-                  ON c.document_pk = d.id
-                JOIN audit_state.retrieval_snapshots AS s
-                  ON s.id = d.snapshot_id
-                WHERE d.project_id = (SELECT id FROM scoped_project)
-                  AND (
-                      %s::text IS NULL
-                      OR d.repo_id = (SELECT id FROM scoped_repo)
-                      OR (d.repo_id IS NULL AND d.source_type NOT IN ('code_file', 'ops_repo_file'))
-                  )
-                  AND (
-                      (%s::text IS NOT NULL AND c.chunk_id = %s)
-                      OR (%s::text IS NOT NULL AND d.source_uri = %s)
-                      OR (%s::text IS NOT NULL AND d.document_id = %s)
-                  )
-                ORDER BY s.created_at DESC, s.id DESC, d.document_id ASC, c.chunk_id ASC
-                LIMIT 1
-                """,
-                (
-                    self._project_key,
-                    repo_key,
-                    repo_key,
-                    repo_key,
-                    chunk_id,
-                    chunk_id,
-                    source_uri,
-                    source_uri,
-                    document_id,
-                    document_id,
-                ),
-            )
-            return cur.fetchone()
-
-    @classmethod
-    def _is_excluded_docs_artifact(
-        cls,
-        *,
-        source_uri: str | None,
-        document_id: str | None,
-        source_type: str | None = None,
-        metadata: Mapping[str, Any] | None = None,
-    ) -> bool:
-        metadata_map = metadata if isinstance(metadata, Mapping) else {}
-        source_type_candidates = {
-            str(source_type or "").strip().lower(),
-            str(metadata_map.get("source_type") or "").strip().lower(),
-            str(metadata_map.get("resource_type") or "").strip().lower(),
-        }
-        source_type_candidates.discard("")
-        if source_type_candidates & cls._DOC_EXCLUDED_SOURCE_TYPES:
-            return True
-
-        doc_class = str(metadata_map.get("doc_class") or "").strip().lower()
-        if doc_class in cls._DOC_EXCLUDED_DOC_CLASSES or "code" in doc_class:
-            return True
-
-        source_uri_text = str(source_uri or "").strip().lower()
-        document_id_text = str(document_id or "").strip().lower()
-        if source_uri_text.startswith("repo://") or source_uri_text.startswith("bitbucket://"):
-            return True
-
-        candidates = (
-            source_uri_text,
-            document_id_text,
-            str(metadata_map.get("file_path") or "").strip().lower(),
-            str(metadata_map.get("source_path") or "").strip().lower(),
-            str(metadata_map.get("source_uri") or "").strip().lower(),
-            str(metadata_map.get("title") or "").strip().lower(),
-            str(metadata_map.get("page_title") or "").strip().lower(),
-            str(metadata_map.get("source_page_title") or "").strip().lower(),
-            str(metadata_map.get("document_title") or "").strip().lower(),
-        )
-        haystack = " ".join(item for item in candidates if item)
-        return any(marker in haystack for marker in cls._DOC_EXCLUDED_PATH_MARKERS)
-
-    @classmethod
-    def _is_hash_only_document_without_source(cls, *, source_uri: str | None, document_id: str | None) -> bool:
-        """Filter synthetic hash IDs that lack a resolvable source URI.
-
-        These IDs commonly originate from generated artifacts and frequently fail
-        `read_doc_chunk` with `doc_chunk_excluded`, causing low-value tool loops.
-        """
-        source = str(source_uri or "").strip()
-        if source:
-            return False
-        doc_id = str(document_id or "").strip().lower()
-        if not doc_id:
-            return False
-        return bool(cls._SYNTHETIC_DOCUMENT_ID_PATTERN.fullmatch(doc_id))
-
-    @classmethod
-    def _resolve_repo_file(
-        cls,
-        *,
-        repo_root: Path,
-        path_value: str,
-        allow_project_parent: bool = False,
-    ) -> Path:
-        candidate = Path(path_value)
-        resolved = candidate.resolve() if candidate.is_absolute() else (repo_root / candidate).resolve()
-        try:
-            resolved.relative_to(repo_root)
-        except ValueError:
-            # Allow paths within the project-level parent when requested (DD-123.11).
-            if allow_project_parent:
-                project_parent = cls._derive_project_parent(repo_root)
-                if project_parent is not None:
-                    try:
-                        resolved.relative_to(project_parent)
-                        return resolved
-                    except ValueError:
-                        pass
-            raise ToolExecutionError(
-                "path_traversal_denied",
-                "Requested path escapes configured repository root",
-                details={"path": path_value, "repo_path": str(repo_root)},
-            ) from None
-        return resolved