@ngocsangairvds/vsaf 3.2.13 → 3.2.15

package/tools/vds-scripts/audit_orchestrator/tests/unit/agents/test_tool_registry.py

@@ -1,2548 +0,0 @@
-"""Tests for tool registry strict schema validation (Phase 61)."""
-
-from __future__ import annotations
-
-import json
-import subprocess
-from pathlib import Path
-from types import SimpleNamespace
-from typing import Any
-from unittest.mock import Mock
-
-import pytest
-from pydantic import ValidationError
-from vds_audit_orchestrator.agents.tool_registry import (
-    ToolExecutionError,
-    ToolName,
-    ToolRegistry,
-)
-
-
-class TestToolRegistrySchemas:
-    """Validate strict typed tool schemas and wrapper behavior."""
-
-    def test_search_docs_rejects_invalid_payload_type(self) -> None:
-        registry = ToolRegistry()
-
-        with pytest.raises(ValidationError):
-            registry.invoke(ToolName.SEARCH_DOCS, {"query": 123, "limit": 2})
-
-    def test_read_code_file_rejects_extra_fields(self) -> None:
-        registry = ToolRegistry()
-
-        with pytest.raises(ValidationError):
-            registry.invoke(
-                ToolName.READ_CODE_FILE,
-                {
-                    "path": "src/main.py",
-                    "start_line": 1,
-                    "unknown": "not-allowed",
-                },
-            )
-
-    def test_search_code_requires_repo_path(self) -> None:
-        registry = ToolRegistry()
-
-        with pytest.raises(ToolExecutionError, match="missing_runtime_context"):
-            registry.invoke(ToolName.SEARCH_CODE, {"query": "auth flow", "limit": 3})
-
-    def test_run_code_search_query_decodes_with_replacement(self, monkeypatch, tmp_path: Path) -> None:
-        registry = ToolRegistry(repo_path=str(tmp_path))
-        captured: dict[str, object] = {}
-
-        def fake_run(*args, **kwargs):
-            captured.update(kwargs)
-            return subprocess.CompletedProcess(args[0], 1, "", "")
-
-        monkeypatch.setattr(subprocess, "run", fake_run)
-
-        registry._run_code_search_query(query="auth", search_root=tmp_path)
-
-        assert captured["text"] is True
-        assert captured["encoding"] == "utf-8"
-        assert captured["errors"] == "replace"
-
-    def test_skills_runtime_policy_falls_back_to_default_catalog_when_configured_dirs_missing(
-        self,
-        monkeypatch: pytest.MonkeyPatch,
-        tmp_path: Path,
-    ) -> None:
-        skill_dir = tmp_path / "skills" / "hexagonal-compliance-skill"
-        skill_dir.mkdir(parents=True)
-
-        from vds_audit_orchestrator.agents.toolsets import skills_toolset
-
-        monkeypatch.setattr(skills_toolset, "DEFAULT_AUDIT_SKILLS", [str(tmp_path / "skills")])
-
-        class FakeLLM:
-            skills_toolset_enabled = True
-            skills_directories = [str(tmp_path / "missing-skills")]
-            skills_allowlist: list[str] = []
-            skills_allowed_trust_tiers = ["internal", "external-verified", "external-unverified"]
-            skills_trust_tiers: dict[str, str] = {}
-            skills_default_trust_tier = "internal"
-            skills_allow_script_execution = False
-
-        class FakeConfig:
-            llm = FakeLLM()
-
-        import vds_audit_orchestrator.config as config_module
-
-        monkeypatch.setattr(config_module, "get_config", FakeConfig)
-
-        registry = ToolRegistry()
-        policy = registry._resolve_skills_runtime_policy()
-
-        assert policy["directories"] == [str((tmp_path / "skills").resolve())]
-
-    def test_record_evidence_refs_deduplicates_refs(self) -> None:
-        registry = ToolRegistry()
-
-        first = registry.invoke(
-            ToolName.RECORD_EVIDENCE_REFS,
-            {
-                "row_id": "row_1",
-                "refs": [
-                    {"ref_type": "path", "ref_value": "docs/readme.md", "verified": True},
-                    {"ref_type": "path", "ref_value": "docs/readme.md", "verified": True},
-                ],
-            },
-        )
-
-        second = registry.invoke(
-            ToolName.RECORD_EVIDENCE_REFS,
-            {
-                "row_id": "row_1",
-                "refs": [
-                    {"ref_type": "url", "ref_value": "https://example.test", "verified": False},
-                ],
-            },
-        )
-
-        assert first.payload["accepted_count"] == 1
-        assert second.payload["accepted_count"] == 2
-        assert {ref["ref_value"] for ref in second.payload["refs"]} == {
-            "docs/readme.md",
-            "https://example.test",
-        }
-
-    def test_record_evidence_refs_accepts_list_line_range_from_runtime_payload(self) -> None:
-        registry = ToolRegistry()
-
-        result = registry.invoke(
-            ToolName.RECORD_EVIDENCE_REFS,
-            {
-                "row_id": "row_1",
-                "refs": [
-                    {
-                        "ref_type": "code_chunk",
-                        "ref_value": "src/main.py",
-                        "verified": True,
-                        "line_range": [1, 220],
-                    }
-                ],
-            },
-        )
-
-        assert result.payload["accepted_count"] == 1
-        assert result.payload["refs"][0]["line_range"] == (1, 220)
-
-    def test_record_evidence_refs_accepts_string_line_range_and_source_uri_alias(self) -> None:
-        registry = ToolRegistry()
-
-        result = registry.invoke(
-            ToolName.RECORD_EVIDENCE_REFS,
-            {
-                "row_id": "row_1",
-                "refs": [
-                    {
-                        "ref_type": "confluence_page",
-                        "ref_value": "https://confluence.example/pages/viewpage.action?pageId=123",
-                        "verified": True,
-                        "line_range": "1:220",
-                        "source_uri": "https://confluence.example/pages/viewpage.action?pageId=123",
-                        "chunk_id": "chunk-001",
-                        "excerpt": "Authentication policy mandates token validation.",
-                        "verification_reason": "excerpt_verified_in_context",
-                        "ref_hash": "abc123hash",
-                    }
-                ],
-            },
-        )
-
-        assert result.payload["accepted_count"] == 1
-        ref = result.payload["refs"][0]
-        assert ref["line_range"] == (1, 220)
-        assert ref["source_url"] == "https://confluence.example/pages/viewpage.action?pageId=123"
-        assert ref["chunk_id"] == "chunk-001"
-        assert ref["excerpt"] == "Authentication policy mandates token validation."
-        assert ref["verification_reason"] == "excerpt_verified_in_context"
-        assert ref["ref_hash"] == "abc123hash"
-
-    def test_search_docs_delegates_to_state_backed_adapter(self) -> None:
-        registry = ToolRegistry(
-            state_dsn="postgresql://user:pass@host/db",
-            project_key="project_a",
-            repo_key="repo_a",
-        )
-        fake_response = SimpleNamespace(
-            meta=SimpleNamespace(status="ok", reason=None),
-            results=[
-                SimpleNamespace(
-                    chunk_id="chunk-001",
-                    source_uri="https://docs.example/doc",
-                    document_id="doc-001",
-                    lexical_rank=3.0,
-                    content_text="auth matched content",
-                ),
-            ],
-        )
-        adapter = Mock()
-        adapter.query_with_meta.return_value = fake_response
-        registry._doc_query_adapter = adapter
-
-        result = registry.invoke(ToolName.SEARCH_DOCS, {"query": "auth", "limit": 5})
-
-        adapter.query_with_meta.assert_called_once_with(
-            query_text="auth",
-            project_key="project_a",
-            repo_key="repo_a",
-            top_k=25,
-        )
-        assert result.payload["hits"] == [
-            {
-                "ref": "chunk:chunk-001",
-                "read_ref": "chunk:chunk-001",
-                "title": "https://docs.example/doc",
-                "score": 0.75,
-                "excerpt": "auth matched content",
-                "chunk_id": "chunk-001",
-                "document_id": "doc-001",
-                "page_id": None,
-                "page_title": None,
-                "space_key": None,
-                "source_url": "https://docs.example/doc",
-                "source_type": None,
-                "doc_class": None,
-            },
-        ]
-
-    def test_search_docs_raises_machine_readable_when_provider_not_ready(self) -> None:
-        registry = ToolRegistry(
-            state_dsn="postgresql://user:pass@host/db",
-            project_key="project_a",
-        )
-        adapter = Mock()
-        adapter.query_with_meta.return_value = SimpleNamespace(
-            meta=SimpleNamespace(status="not_ready", reason="snapshot_not_found"),
-            results=[],
-        )
-        registry._doc_query_adapter = adapter
-
-        with pytest.raises(ToolExecutionError) as exc_info:
-            registry.invoke(ToolName.SEARCH_DOCS, {"query": "x", "limit": 1})
-
-        payload = json.loads(str(exc_info.value))
-        assert payload["error"]["code"] == "provider_not_ready"
-        assert payload["error"]["details"]["reason"] == "snapshot_not_found"
-
-    def test_search_docs_does_not_retry_without_repo_scope_when_repo_scoped_result_empty(self) -> None:
-        registry = ToolRegistry(
-            state_dsn="postgresql://user:pass@host/db",
-            project_key="project_a",
-            repo_key="repo_a",
-        )
-        adapter = Mock()
-        adapter.query_with_meta.side_effect = [
-            SimpleNamespace(meta=SimpleNamespace(status="ok", reason=None), results=[]),
-        ]
-        registry._doc_query_adapter = adapter
-
-        result = registry.invoke(ToolName.SEARCH_DOCS, {"query": "architecture", "limit": 3})
-
-        assert adapter.query_with_meta.call_count == 1
-        first_call = adapter.query_with_meta.call_args_list[0].kwargs
-        assert first_call["repo_key"] == "repo_a"
-        assert result.payload["hits"] == []
-
-    def test_search_docs_retries_project_scope_when_repo_scope_is_excluded_only(self) -> None:
-        registry = ToolRegistry(
-            state_dsn="postgresql://user:pass@host/db",
-            project_key="project_a",
-            repo_key="repo_a",
-        )
-        adapter = Mock()
-        adapter.query_with_meta.side_effect = [
-            SimpleNamespace(
-                meta=SimpleNamespace(status="ok", reason=None),
-                results=[
-                    SimpleNamespace(
-                        chunk_id="chunk-artifact",
-                        source_uri=None,
-                        document_id="doc-artifact",
-                        lexical_rank=5.0,
-                        content_text="architecture checklist export",
-                        document_metadata={
-                            "source_type": "code_file",
-                            "doc_class": "canonical_code",
-                            "file_path": "reports/verification/live_eval/run-1/audit-checklist.json",
-                        },
-                    ),
-                ],
-            ),
-            SimpleNamespace(
-                meta=SimpleNamespace(status="ok", reason=None),
-                results=[
-                    SimpleNamespace(
-                        chunk_id="chunk-doc",
-                        source_uri="https://confluence.example/architecture",
-                        document_id="74014721",
-                        lexical_rank=2.0,
-                        content_text="architecture interface boundaries",
-                        document_metadata={
-                            "source_type": "confluence_page",
-                            "doc_class": "canonical_doc",
-                        },
-                    ),
-                ],
-            ),
-        ]
-        registry._doc_query_adapter = adapter
-
-        result = registry.invoke(ToolName.SEARCH_DOCS, {"query": "architecture", "limit": 5})
-
-        assert adapter.query_with_meta.call_count == 2
-        assert adapter.query_with_meta.call_args_list[0].kwargs["repo_key"] == "repo_a"
-        assert adapter.query_with_meta.call_args_list[1].kwargs["repo_key"] is None
-        assert [hit["ref"] for hit in result.payload["hits"]] == ["chunk:chunk-doc"]
-
-    def test_search_docs_deduplicates_hits_by_ref(self) -> None:
-        registry = ToolRegistry(
-            state_dsn="postgresql://user:pass@host/db",
-            project_key="project_a",
-            repo_key="repo_a",
-        )
-        adapter = Mock()
-        adapter.query_with_meta.return_value = SimpleNamespace(
-            meta=SimpleNamespace(status="ok", reason=None),
-            results=[
-                SimpleNamespace(
-                    chunk_id="chunk-1",
-                    source_uri=None,
-                    document_id="127700065",
-                    lexical_rank=4.0,
-                    content_text="postman first hit",
-                ),
-                SimpleNamespace(
-                    chunk_id="chunk-2",
-                    source_uri=None,
-                    document_id="127700065",
-                    lexical_rank=3.0,
-                    content_text="postman duplicate hit",
-                ),
-                SimpleNamespace(
-                    chunk_id="chunk-3",
-                    source_uri=None,
-                    document_id="92200507",
-                    lexical_rank=2.0,
-                    content_text="postman second doc",
-                ),
-            ],
-        )
-        registry._doc_query_adapter = adapter
-
-        result = registry.invoke(ToolName.SEARCH_DOCS, {"query": "postman", "limit": 5})
-
-        refs = [hit["ref"] for hit in result.payload["hits"]]
-        assert refs == ["chunk:chunk-1", "chunk:chunk-2", "chunk:chunk-3"]
-
-    def test_search_docs_prefers_metadata_title_when_source_uri_missing(self) -> None:
-        registry = ToolRegistry(
-            state_dsn="postgresql://user:pass@host/db",
-            project_key="project_a",
-            repo_key="repo_a",
-        )
-        adapter = Mock()
-        adapter.query_with_meta.return_value = SimpleNamespace(
-            meta=SimpleNamespace(status="ok", reason=None),
-            results=[
-                SimpleNamespace(
-                    chunk_id="chunk-1",
-                    source_uri=None,
-                    document_id="74014721",
-                    lexical_rank=4.0,
-                    content_text="KBNV App Center integration flow",
-                    document_metadata={
-                        "title": "MINIAPP.02.04.02 KBNV cho App Center",
-                        "source_type": "confluence_page",
-                        "doc_class": "canonical_doc",
-                    },
-                )
-            ],
-        )
-        registry._doc_query_adapter = adapter
-
-        result = registry.invoke(ToolName.SEARCH_DOCS, {"query": "KBNV App Center", "limit": 5})
-
-        assert len(result.payload["hits"]) == 1
-        assert result.payload["hits"][0]["ref"] == "chunk:chunk-1"
-        assert result.payload["hits"][0]["title"] == "MINIAPP.02.04.02 KBNV cho App Center"
-
-    def test_search_docs_prefers_source_page_title_for_attachment_metadata(self) -> None:
-        registry = ToolRegistry(
-            state_dsn="postgresql://user:pass@host/db",
-            project_key="project_a",
-            repo_key="repo_a",
-        )
-        adapter = Mock()
-        adapter.query_with_meta.return_value = SimpleNamespace(
-            meta=SimpleNamespace(status="ok", reason=None),
-            results=[
-                SimpleNamespace(
-                    chunk_id="chunk-1",
-                    source_uri=None,
-                    document_id="87410482",
-                    lexical_rank=4.0,
-                    content_text="mini app test cases",
-                    document_metadata={
-                        "title": "KBKTCN_SUPPERAPP_App Center.xlsx",
-                        "source_page_title": "MINIAPP.05. Test",
-                        "source_type": "confluence_attachment",
-                    },
-                )
-            ],
-        )
-        registry._doc_query_adapter = adapter
-
-        result = registry.invoke(ToolName.SEARCH_DOCS, {"query": "mini app test cases", "limit": 5})
-
-        assert len(result.payload["hits"]) == 1
-        assert result.payload["hits"][0]["title"] == "MINIAPP.05. Test"
-
-    def test_search_docs_prioritizes_confluence_page_over_attachment_on_tie(self) -> None:
-        registry = ToolRegistry(
-            state_dsn="postgresql://user:pass@host/db",
-            project_key="project_a",
-            repo_key="repo_a",
-        )
-        adapter = Mock()
-        adapter.query_with_meta.return_value = SimpleNamespace(
-            meta=SimpleNamespace(status="ok", reason=None),
-            results=[
-                SimpleNamespace(
-                    chunk_id="chunk-attachment",
-                    source_uri=None,
-                    document_id="87410482",
-                    lexical_rank=3.0,
-                    content_text="quy trình release mini app",
-                    document_metadata={
-                        "source_type": "confluence_attachment",
-                        "title": "Release checklist.xlsx",
-                    },
-                ),
-                SimpleNamespace(
-                    chunk_id="chunk-page",
-                    source_uri=None,
-                    document_id="84283962",
-                    lexical_rank=3.0,
-                    content_text="quy trình release mini app",
-                    document_metadata={
-                        "source_type": "confluence_page",
-                        "title": "MINIAPP.03 Quy trình phát triển",
-                    },
-                ),
-            ],
-        )
-        registry._doc_query_adapter = adapter
-
-        result = registry.invoke(ToolName.SEARCH_DOCS, {"query": "quy trình release mini app", "limit": 5})
-
-        assert [hit["ref"] for hit in result.payload["hits"]] == ["chunk:chunk-page", "chunk:chunk-attachment"]
-
-    def test_search_docs_derives_title_from_excerpt_when_metadata_missing(self) -> None:
-        registry = ToolRegistry(
-            state_dsn="postgresql://user:pass@host/db",
-            project_key="project_a",
-            repo_key="repo_a",
-        )
-        adapter = Mock()
-        adapter.query_with_meta.return_value = SimpleNamespace(
-            meta=SimpleNamespace(status="ok", reason=None),
-            results=[
-                SimpleNamespace(
-                    chunk_id="chunk-2",
-                    source_uri=None,
-                    document_id="87410475",
-                    lexical_rank=4.0,
-                    content_text="# MINIAPP.03.2. Thiết kế CSDL\n\nNội dung thiết kế chi tiết",
-                    document_metadata={},
-                )
-            ],
-        )
-        registry._doc_query_adapter = adapter
-
-        result = registry.invoke(ToolName.SEARCH_DOCS, {"query": "thiết kế CSDL", "limit": 5})
-
-        assert len(result.payload["hits"]) == 1
-        assert result.payload["hits"][0]["ref"] == "chunk:chunk-2"
-        assert result.payload["hits"][0]["title"] == "MINIAPP.03.2. Thiết kế CSDL"
-
-    def test_search_docs_refines_low_quality_title_using_lookup_row(self) -> None:
-        registry = ToolRegistry(
-            state_dsn="postgresql://user:pass@host/db",
-            project_key="project_a",
-            repo_key="repo_a",
-        )
-        adapter = Mock()
-        adapter.query_with_meta.return_value = SimpleNamespace(
-            meta=SimpleNamespace(status="ok", reason=None),
-            results=[
-                SimpleNamespace(
-                    chunk_id="chunk-2",
-                    source_uri=None,
-                    document_id="87410482",
-                    lexical_rank=4.0,
-                    content_text="release | mini | app | rollout |",
-                    document_metadata={},
-                )
-            ],
-        )
-        registry._doc_query_adapter = adapter
-
-        def _lookup(*, chunk_id, source_uri, document_id, repo_key):
-            _ = chunk_id, source_uri, repo_key
-            if chunk_id == "chunk-2":
-                return {
-                    "chunk_id": "seed-chunk",
-                    "source_uri": None,
-                    "document_id": "87410482",
-                    "source_type": "confluence_page",
-                    "document_metadata": {},
-                    "content_text": "## MINIAPP.04 Release và Deployment\n\nMô tả quy trình release",
-                }
-            return None
-
-        registry._lookup_doc_chunk = _lookup  # type: ignore[method-assign]
-
-        result = registry.invoke(ToolName.SEARCH_DOCS, {"query": "release mini app", "limit": 5})
-
-        assert len(result.payload["hits"]) == 1
-        assert result.payload["hits"][0]["title"] == "MINIAPP.04 Release và Deployment"
-
-    def test_search_docs_fallback_title_uses_confluence_page_label_for_numeric_doc_id(self) -> None:
-        registry = ToolRegistry(
-            state_dsn="postgresql://user:pass@host/db",
-            project_key="project_a",
-            repo_key="repo_a",
-        )
-        adapter = Mock()
-        adapter.query_with_meta.return_value = SimpleNamespace(
-            meta=SimpleNamespace(status="ok", reason=None),
-            results=[
-                SimpleNamespace(
-                    chunk_id="chunk-3",
-                    source_uri=None,
-                    document_id="87410482",
-                    lexical_rank=4.0,
-                    content_text="| Col 1 | Col 2 | Col 3 |",
-                    document_metadata={},
-                )
-            ],
-        )
-        registry._doc_query_adapter = adapter
-
-        def _lookup(*, chunk_id, source_uri, document_id, repo_key):
-            _ = chunk_id, source_uri, repo_key
-            if chunk_id == "chunk-3":
-                return {
-                    "chunk_id": "seed-chunk",
-                    "source_uri": None,
-                    "document_id": "87410482",
-                    "source_type": "confluence_page",
-                    "document_metadata": {},
-                    "content_text": "| Col 1 | Col 2 | Col 3 | Col 4 |",
-                }
-            return None
-
-        registry._lookup_doc_chunk = _lookup  # type: ignore[method-assign]
-
-        result = registry.invoke(ToolName.SEARCH_DOCS, {"query": "col", "limit": 5})
-
-        assert len(result.payload["hits"]) == 1
-        assert result.payload["hits"][0]["title"] == "Confluence page 87410482"
-
-    def test_search_docs_filters_hash_only_document_ids_without_source_uri(self) -> None:
-        registry = ToolRegistry(
-            state_dsn="postgresql://user:pass@host/db",
-            project_key="project_a",
-            repo_key="repo_a",
-        )
-        adapter = Mock()
-        adapter.query_with_meta.return_value = SimpleNamespace(
-            meta=SimpleNamespace(status="ok", reason=None),
-            results=[
-                SimpleNamespace(
-                    chunk_id="chunk-hash",
-                    source_uri=None,
-                    document_id="898a59bb22e442e7",
-                    lexical_rank=5.0,
-                    content_text="synthetic artifact chunk",
-                ),
-                SimpleNamespace(
-                    chunk_id="chunk-doc",
-                    source_uri=None,
-                    document_id="92200507",
-                    lexical_rank=3.0,
-                    content_text="support workflow confluence document chunk",
-                ),
-            ],
-        )
-        registry._doc_query_adapter = adapter
-
-        result = registry.invoke(ToolName.SEARCH_DOCS, {"query": "support workflow", "limit": 5})
-
-        assert [hit["ref"] for hit in result.payload["hits"]] == ["chunk:chunk-doc"]
-
-    def test_search_docs_filters_hits_not_readable_under_scope_exclusion(self) -> None:
-        registry = ToolRegistry(
-            state_dsn="postgresql://user:pass@host/db",
-            project_key="project_a",
-            repo_key="repo_a",
-        )
-        adapter = Mock()
-        adapter.query_with_meta.return_value = SimpleNamespace(
-            meta=SimpleNamespace(status="ok", reason=None),
-            results=[
-                SimpleNamespace(
-                    chunk_id="chunk-excluded",
-                    source_uri=None,
-                    document_id="92200507",
-                    lexical_rank=4.0,
-                    content_text="support workflow handbook",
-                ),
-                SimpleNamespace(
-                    chunk_id="chunk-readable",
-                    source_uri=None,
-                    document_id="92200508",
-                    lexical_rank=3.0,
-                    content_text="support workflow runbook",
-                ),
-            ],
-        )
-        registry._doc_query_adapter = adapter
-
-        def _lookup(*, chunk_id, source_uri, document_id, repo_key):
-            _ = chunk_id, source_uri, repo_key
-            if chunk_id == "chunk-excluded":
-                return {
-                    "chunk_id": "chunk-excluded",
-                    "source_uri": "",
-                    "document_id": "92200507",
-                    "source_type": "generated",
-                    "document_metadata": {"doc_class": "generated_artifact"},
-                }
-            if chunk_id == "chunk-readable":
-                return {
-                    "chunk_id": "chunk-readable",
-                    "source_uri": "https://confluence.example/support",
-                    "document_id": "92200508",
-                    "source_type": "confluence_page",
-                    "document_metadata": {"doc_class": "canonical_doc"},
-                }
-            return None
-
-        registry._lookup_doc_chunk = _lookup  # type: ignore[method-assign]
-
-        result = registry.invoke(ToolName.SEARCH_DOCS, {"query": "support workflow", "limit": 5})
-
-        assert [hit["ref"] for hit in result.payload["hits"]] == ["chunk:chunk-readable"]
-
-    def test_search_docs_filters_metadata_marked_code_or_report_artifacts(self) -> None:
-        registry = ToolRegistry(
-            state_dsn="postgresql://user:pass@host/db",
-            project_key="project_a",
-            repo_key="repo_a",
-        )
-        adapter = Mock()
-        adapter.query_with_meta.return_value = SimpleNamespace(
-            meta=SimpleNamespace(status="ok", reason=None),
-            results=[
-                SimpleNamespace(
-                    chunk_id="chunk-artifact",
-                    source_uri=None,
-                    document_id="4ec4e588187e6771",
-                    lexical_rank=5.0,
-                    content_text="architecture quality summary from generated report",
-                    document_metadata={
-                        "source_type": "code_file",
-                        "doc_class": "canonical_code",
-                        "file_path": "reports/verification/live_eval/run-1/audit-checklist.json",
-                    },
-                ),
-                SimpleNamespace(
-                    chunk_id="chunk-doc",
-                    source_uri="https://confluence.example/architecture",
-                    document_id="74014721",
-                    lexical_rank=2.0,
-                    content_text="architecture interface boundaries and design decisions",
-                    document_metadata={
-                        "source_type": "confluence_page",
-                        "doc_class": "canonical_doc",
-                        "source_path": "docs/architecture.md",
-                    },
-                ),
-            ],
-        )
-        registry._doc_query_adapter = adapter
-
-        result = registry.invoke(ToolName.SEARCH_DOCS, {"query": "architecture", "limit": 5})
-
-        assert [hit["ref"] for hit in result.payload["hits"]] == ["chunk:chunk-doc"]
-
-    def test_search_docs_uses_docs_intent_recovery_query_when_scope_hits_are_excluded(self) -> None:
-        registry = ToolRegistry(
-            state_dsn="postgresql://user:pass@host/db",
-            project_key="project_a",
-            repo_key="repo_a",
-        )
-        adapter = Mock()
-        adapter.query_with_meta.side_effect = [
-            SimpleNamespace(
-                meta=SimpleNamespace(status="ok", reason=None),
-                results=[
-                    SimpleNamespace(
-                        chunk_id="chunk-artifact-1",
-                        source_uri=None,
-                        document_id="doc-artifact-1",
-                        lexical_rank=5.0,
-                        content_text="generated checklist output",
-                        document_metadata={
-                            "source_type": "code_file",
-                            "doc_class": "canonical_code",
-                            "file_path": "reports/verification/live_eval/run-1/audit-checklist.json",
-                        },
-                    ),
-                ],
-            ),
-            SimpleNamespace(
-                meta=SimpleNamespace(status="ok", reason=None),
-                results=[
-                    SimpleNamespace(
-                        chunk_id="chunk-artifact-2",
-                        source_uri=None,
-                        document_id="doc-artifact-2",
-                        lexical_rank=4.0,
-                        content_text="generated checklist output",
-                        document_metadata={
-                            "source_type": "code_file",
-                            "doc_class": "canonical_code",
-                            "file_path": "reports/verification/live_eval/run-2/audit-checklist.json",
-                        },
-                    ),
-                ],
-            ),
-            SimpleNamespace(
-                meta=SimpleNamespace(status="ok", reason=None),
-                results=[
-                    SimpleNamespace(
-                        chunk_id="chunk-doc",
-                        source_uri="https://confluence.example/version-doc",
-                        document_id="127700065",
-                        lexical_rank=2.0,
-                        content_text="Tài liệu Confluence version 1.0 cho quy trình tích hợp.",
-                        document_metadata={
-                            "source_type": "confluence_page",
-                            "doc_class": "canonical_doc",
-                        },
-                    ),
-                ],
-            ),
-        ]
-        registry._doc_query_adapter = adapter
-
-        result = registry.invoke(
-            ToolName.SEARCH_DOCS,
-            {"query": "Tài liệu quản lý phiên bản (Wiki/Gitbook/Confluence) khớp với version của code.", "limit": 1},
-        )
-
-        assert adapter.query_with_meta.call_count == 3
-        assert adapter.query_with_meta.call_args_list[0].kwargs["repo_key"] == "repo_a"
-        assert adapter.query_with_meta.call_args_list[1].kwargs["repo_key"] is None
-        assert adapter.query_with_meta.call_args_list[2].kwargs["repo_key"] == "repo_a"
-        assert adapter.query_with_meta.call_args_list[2].kwargs["query_text"] == "tài liệu version confluence"
-        assert [hit["ref"] for hit in result.payload["hits"]] == ["chunk:chunk-doc"]
-
-    def test_search_docs_uses_docs_intent_recovery_query_when_hits_are_low_confidence(self) -> None:
-        registry = ToolRegistry(
-            state_dsn="postgresql://user:pass@host/db",
-            project_key="project_a",
-            repo_key="repo_a",
-        )
-        adapter = Mock()
-        adapter.query_with_meta.side_effect = [
-            SimpleNamespace(
-                meta=SimpleNamespace(status="ok", reason=None),
-                results=[
-                    SimpleNamespace(
-                        chunk_id="chunk-attachment",
-                        source_uri=None,
-                        document_id="87410482",
-                        lexical_rank=0.002,
-                        content_text="Bảng testcase mini app app center",
-                        document_metadata={
-                            "source_type": "confluence_attachment",
-                            "title": "VDS_VIS_SuperApp_KBKTCN_Webportal.v.1.xlsx",
-                        },
-                    ),
-                ],
-            ),
-            SimpleNamespace(
-                meta=SimpleNamespace(status="ok", reason=None),
-                results=[
-                    SimpleNamespace(
-                        chunk_id="chunk-page",
-                        source_uri="https://confluence.example/miniapp-app-center",
-                        document_id="94667191",
-                        lexical_rank=0.2,
-                        content_text="Tài liệu tích hợp App Center cho MiniApp.",
-                        document_metadata={
-                            "source_type": "confluence_page",
-                            "title": "MINIAPP.02.04.02 KBNV cho App Center",
-                            "doc_class": "canonical_doc",
-                        },
-                    ),
-                ],
-            ),
-        ]
-        registry._doc_query_adapter = adapter
-
-        result = registry.invoke(ToolName.SEARCH_DOCS, {"query": "tài liệu tích hợp app center", "limit": 1})
-
-        assert adapter.query_with_meta.call_count == 2
-        assert adapter.query_with_meta.call_args_list[0].kwargs["repo_key"] == "repo_a"
-        assert adapter.query_with_meta.call_args_list[1].kwargs["repo_key"] == "repo_a"
-        assert adapter.query_with_meta.call_args_list[1].kwargs["query_text"] == "tài liệu confluence"
-        assert [hit["ref"] for hit in result.payload["hits"]] == ["chunk:chunk-page"]
-
-    def test_search_docs_docs_intent_prefers_page_hits_over_low_score_attachment_hits(self) -> None:
-        registry = ToolRegistry(
-            state_dsn="postgresql://user:pass@host/db",
-            project_key="project_a",
-            repo_key="repo_a",
-        )
-        adapter = Mock()
-        adapter.query_with_meta.return_value = SimpleNamespace(
-            meta=SimpleNamespace(status="ok", reason=None),
-            results=[
-                SimpleNamespace(
-                    chunk_id="chunk-attachment",
-                    source_uri=None,
-                    document_id="87410482",
-                    lexical_rank=0.002,
-                    content_text="Bảng testcase mini app app center",
-                    document_metadata={
-                        "source_type": "confluence_attachment",
-                        "title": "VDS_VIS_SuperApp_KBKTCN_Webportal.v.1.xlsx",
-                    },
-                ),
-                SimpleNamespace(
-                    chunk_id="chunk-page",
-                    source_uri=None,
-                    document_id="94667191",
-                    lexical_rank=0.2,
-                    content_text="Tài liệu tích hợp App Center cho MiniApp.",
-                    document_metadata={
-                        "source_type": "confluence_page",
-                        "title": "MINIAPP.02.04.02 KBNV cho App Center",
-                    },
-                ),
-            ],
-        )
-        registry._doc_query_adapter = adapter
-
-        def _lookup(*, chunk_id, source_uri, document_id, repo_key):
-            _ = chunk_id, source_uri, repo_key
-            if chunk_id == "chunk-attachment":
-                return {
-                    "chunk_id": "chunk-attachment",
-                    "source_uri": "",
-                    "document_id": "87410482",
-                    "source_type": "confluence_attachment",
-                    "document_metadata": {"source_type": "confluence_attachment"},
-                }
-            if chunk_id == "chunk-page":
-                return {
-                    "chunk_id": "chunk-page",
-                    "source_uri": "",
-                    "document_id": "94667191",
-                    "source_type": "confluence_page",
-                    "document_metadata": {"source_type": "confluence_page"},
-                }
-            return None
-
-        registry._lookup_doc_chunk = _lookup  # type: ignore[method-assign]
-
-        result = registry.invoke(ToolName.SEARCH_DOCS, {"query": "tài liệu tích hợp app center", "limit": 3})
-
-        assert [hit["ref"] for hit in result.payload["hits"]] == ["chunk:chunk-page"]
-
-    def test_search_docs_docs_intent_reorders_low_confidence_hits_after_high_confidence_hits(self) -> None:
-        registry = ToolRegistry(
-            state_dsn="postgresql://user:pass@host/db",
-            project_key="project_a",
-            repo_key="repo_a",
-        )
-        adapter = Mock()
-        adapter.query_with_meta.return_value = SimpleNamespace(
-            meta=SimpleNamespace(status="ok", reason=None),
-            results=[
-                SimpleNamespace(
-                    chunk_id="chunk-low",
-                    source_uri=None,
-                    document_id="87410482",
-                    lexical_rank=0.002,
-                    content_text="tài liệu tích hợp app center và hướng dẫn mini app",
-                    document_metadata={
-                        "source_type": "confluence_page",
-                        "title": "MINIAPP.05. Test",
-                    },
-                ),
-                SimpleNamespace(
-                    chunk_id="chunk-high",
-                    source_uri=None,
-                    document_id="94667191",
-                    lexical_rank=0.4,
-                    content_text="tài liệu app center",
-                    document_metadata={
-                        "source_type": "confluence_page",
-                        "title": "MINIAPP.02.04.02 KBNV cho App Center",
-                    },
-                ),
-            ],
-        )
-        registry._doc_query_adapter = adapter
-
-        def _lookup(*, chunk_id, source_uri, document_id, repo_key):
-            _ = chunk_id, source_uri, repo_key
-            return {
-                "chunk_id": f"chunk-{document_id}",
-                "source_uri": "",
-                "document_id": document_id,
-                "source_type": "confluence_page",
-                "document_metadata": {"source_type": "confluence_page"},
-            }
-
-        registry._lookup_doc_chunk = _lookup  # type: ignore[method-assign]
-
-        result = registry.invoke(ToolName.SEARCH_DOCS, {"query": "tài liệu tích hợp app center", "limit": 2})
-
-        assert [hit["ref"] for hit in result.payload["hits"]] == ["chunk:chunk-high", "chunk:chunk-low"]
-
-    def test_search_docs_uses_support_flow_recovery_query_when_log_requirement_is_excluded(self) -> None:
-        registry = ToolRegistry(
-            state_dsn="postgresql://user:pass@host/db",
-            project_key="project_a",
-            repo_key="repo_a",
-        )
-        adapter = Mock()
-        adapter.query_with_meta.side_effect = [
-            SimpleNamespace(
-                meta=SimpleNamespace(status="ok", reason=None),
-                results=[
-                    SimpleNamespace(
-                        chunk_id="chunk-artifact-1",
-                        source_uri=None,
-                        document_id="doc-artifact-1",
-                        lexical_rank=5.0,
-                        content_text="generated checklist output",
-                        document_metadata={
-                            "source_type": "code_file",
-                            "doc_class": "canonical_code",
-                            "file_path": "reports/verification/live_eval/run-1/audit-checklist.json",
-                        },
-                    ),
-                ],
-            ),
-            SimpleNamespace(
-                meta=SimpleNamespace(status="ok", reason=None),
-                results=[
-                    SimpleNamespace(
-                        chunk_id="chunk-artifact-2",
-                        source_uri=None,
-                        document_id="doc-artifact-2",
-                        lexical_rank=4.0,
-                        content_text="generated checklist output",
-                        document_metadata={
-                            "source_type": "code_file",
-                            "doc_class": "canonical_code",
-                            "file_path": "reports/verification/live_eval/run-2/audit-checklist.json",
-                        },
-                    ),
-                ],
-            ),
-            SimpleNamespace(
-                meta=SimpleNamespace(status="ok", reason=None),
-                results=[
-                    SimpleNamespace(
-                        chunk_id="chunk-doc",
-                        source_uri="https://confluence.example/l3-support-process",
-                        document_id="97400253",
-                        lexical_rank=2.0,
-                        content_text="Quy trình hỗ trợ L3 cho log đóng gói và data dump.",
-                        document_metadata={
-                            "source_type": "confluence_page",
-                            "doc_class": "canonical_doc",
-                        },
-                    ),
-                ],
-            ),
-        ]
-        registry._doc_query_adapter = adapter
-
-        result = registry.invoke(
-            ToolName.SEARCH_DOCS,
-            {
-                "query": "Có quy trình đóng gói Log và Data dump để gửi về đội L3 khi cần điều tra sâu.",
-                "limit": 1,
-            },
-        )
-
-        assert adapter.query_with_meta.call_count == 3
-        assert adapter.query_with_meta.call_args_list[0].kwargs["repo_key"] == "repo_a"
-        assert adapter.query_with_meta.call_args_list[1].kwargs["repo_key"] is None
-        assert adapter.query_with_meta.call_args_list[2].kwargs["repo_key"] == "repo_a"
-        assert adapter.query_with_meta.call_args_list[2].kwargs["query_text"] == "quy trình hỗ trợ"
-        assert [hit["ref"] for hit in result.payload["hits"]] == ["chunk:chunk-doc"]
-
-    def test_search_docs_requires_high_signal_term_when_present(self) -> None:
-        registry = ToolRegistry(
-            state_dsn="postgresql://user:pass@host/db",
-            project_key="project_a",
-            repo_key="repo_a",
-        )
-        adapter = Mock()
-        adapter.query_with_meta.return_value = SimpleNamespace(
-            meta=SimpleNamespace(status="ok", reason=None),
-            results=[
-                SimpleNamespace(
-                    chunk_id="chunk-1",
-                    source_uri=None,
-                    document_id="doc-general",
-                    lexical_rank=4.0,
-                    content_text="Integration guide for partner onboarding only.",
-                ),
-                SimpleNamespace(
-                    chunk_id="chunk-2",
-                    source_uri=None,
-                    document_id="doc-sandbox",
-                    lexical_rank=3.0,
-                    content_text="Sandbox simulation endpoint usage for integration tests.",
-                ),
-            ],
-        )
-        registry._doc_query_adapter = adapter
-
-        result = registry.invoke(ToolName.SEARCH_DOCS, {"query": "sandbox simulation", "limit": 5})
-
-        assert [hit["ref"] for hit in result.payload["hits"]] == ["chunk:chunk-2"]
-
-    def test_search_docs_keeps_high_confidence_hit_without_required_term_match(self) -> None:
-        registry = ToolRegistry(
-            state_dsn="postgresql://user:pass@host/db",
-            project_key="project_a",
-            repo_key="repo_a",
-        )
-        adapter = Mock()
-        adapter.query_with_meta.return_value = SimpleNamespace(
-            meta=SimpleNamespace(status="ok", reason=None),
-            results=[
-                SimpleNamespace(
-                    chunk_id="chunk-1",
-                    source_uri=None,
-                    document_id="doc-governance",
-                    lexical_rank=3.0,
-                    content_text="Operational oversight process for partner integrations.",
-                ),
-            ],
-        )
-        registry._doc_query_adapter = adapter
-
-        result = registry.invoke(ToolName.SEARCH_DOCS, {"query": "governance oversight", "limit": 5})
-
-        assert [hit["ref"] for hit in result.payload["hits"]] == ["chunk:chunk-1"]
-
-    def test_read_doc_chunk_uses_scoped_state_lookup(self) -> None:
-        registry = ToolRegistry(
-            state_dsn="postgresql://user:pass@host/db",
-            project_key="project_a",
-            repo_key="repo_a",
-        )
-
-        captured: dict[str, Any] = {}
-        row = {
-            "document_id": "doc-001",
-            "source_uri": "https://docs.example/doc",
-            "chunk_id": "chunk-001",
-            "content_text": "hello from state",
-        }
-
-        class _Cursor:
-            def __enter__(self) -> _Cursor:
-                return self
-
-            def __exit__(self, exc_type, exc, tb) -> None:  # type: ignore[no-untyped-def]
-                return None
-
-            def execute(self, sql: str, params: tuple[Any, ...]) -> None:
-                captured["sql"] = sql
-                captured["params"] = params
-
-            def fetchone(self) -> dict[str, Any]:
-                return row
-
-        class _Conn:
-            def __init__(self) -> None:
-                self._cursor = _Cursor()
-
-            def cursor(self) -> _Cursor:
-                return self._cursor
-
-        registry._state_store = SimpleNamespace(_conn=_Conn())
-
-        result = registry.invoke(
-            ToolName.READ_DOC_CHUNK,
-            {"ref": "source_uri:https://docs.example/doc"},
-        )
-
-        assert "audit_state.corpus_documents" in captured["sql"]
-        assert captured["params"][0] == "project_a"
-        assert captured["params"][1] == "repo_a"
-        assert result.payload == {
-            "ref": "chunk:chunk-001",
-            "chunk_id": "chunk-001",
-            "content": "hello from state",
-            "page_id": None,
-            "page_title": None,
-            "source_url": "https://docs.example/doc",
-            "space_key": None,
-            "start_line": None,
-            "end_line": None,
-        }
-
-    def test_read_doc_chunk_retries_without_repo_scope_when_repo_scoped_not_found(self) -> None:
-        registry = ToolRegistry(
-            state_dsn="postgresql://user:pass@host/db",
-            project_key="project_a",
-            repo_key="repo_a",
-        )
-
-        params_history: list[tuple[Any, ...]] = []
-        responses: list[dict[str, Any] | None] = [None]
-        row = {
-            "document_id": "doc-010",
-            "source_uri": "https://docs.example/doc-fallback",
-            "chunk_id": "chunk-010",
-            "content_text": "fallback row",
-        }
-        responses.append(row)
-
-        class _Cursor:
-            def __enter__(self) -> _Cursor:
-                return self
-
-            def __exit__(self, exc_type, exc, tb) -> None:  # type: ignore[no-untyped-def]
-                return None
-
-            def execute(self, sql: str, params: tuple[Any, ...]) -> None:
-                del sql
-                params_history.append(params)
-
-            def fetchone(self) -> dict[str, Any] | None:
-                return responses.pop(0) if responses else row
-
-        class _Conn:
-            def cursor(self) -> _Cursor:
-                return _Cursor()
-
-        registry._state_store = SimpleNamespace(_conn=_Conn())
-
-        result = registry.invoke(
-            ToolName.READ_DOC_CHUNK,
-            {"ref": "source_uri:https://docs.example/doc-fallback"},
-        )
-
-        assert len(params_history) == 2
-        assert params_history[0][1] == "repo_a"
-        assert params_history[1][1] is None
-        assert result.payload["chunk_id"] == "chunk-010"
-
-    def test_read_doc_chunk_extracts_document_id_from_confluence_page_url(self) -> None:
-        registry = ToolRegistry(
-            state_dsn="postgresql://user:pass@host/db",
-            project_key="project_a",
-            repo_key="repo_a",
-        )
-
-        captured: dict[str, Any] = {}
-        row = {
-            "document_id": "74014721",
-            "source_uri": None,
-            "chunk_id": "chunk-74014721-0",
-            "content_text": "confluence chunk",
-        }
-
-        class _Cursor:
-            def __enter__(self) -> _Cursor:
-                return self
-
-            def __exit__(self, exc_type, exc, tb) -> None:  # type: ignore[no-untyped-def]
-                return None
-
-            def execute(self, sql: str, params: tuple[Any, ...]) -> None:
-                captured["sql"] = sql
-                captured["params"] = params
-
-            def fetchone(self) -> dict[str, Any]:
-                return row
-
-        class _Conn:
-            def cursor(self) -> _Cursor:
-                return _Cursor()
-
-        registry._state_store = SimpleNamespace(_conn=_Conn())
-
-        result = registry.invoke(
-            ToolName.READ_DOC_CHUNK,
-            {"ref": "http://10.254.136.35:8090/pages/viewpage.action?pageId=74014721"},
-        )
-
-        assert "audit_state.corpus_documents" in captured["sql"]
-        assert captured["params"][8] == "74014721"
-        assert captured["params"][9] == "74014721"
-        assert result.payload["ref"] == "chunk:chunk-74014721-0"
-        assert result.payload["chunk_id"] == "chunk-74014721-0"
-
-    def test_read_doc_chunk_rejects_excluded_artifact_content(self) -> None:
-        registry = ToolRegistry(
-            state_dsn="postgresql://user:pass@host/db",
-            project_key="project_a",
-            repo_key="repo_a",
-        )
-        row = {
-            "document_id": "4ec4e588187e6771",
-            "source_uri": None,
-            "source_type": "confluence_page",
-            "document_metadata": {
-                "source_type": "code_file",
-                "doc_class": "canonical_code",
-                "file_path": "reports/verification/live_eval/run-1/audit-checklist.json",
-            },
-            "chunk_id": "chunk-artifact",
-            "content_text": "generated checklist output",
-        }
-
-        class _Cursor:
-            def __enter__(self) -> _Cursor:
-                return self
-
-            def __exit__(self, exc_type, exc, tb) -> None:  # type: ignore[no-untyped-def]
-                return None
-
-            def execute(self, sql: str, params: tuple[Any, ...]) -> None:
-                del sql, params
-
-            def fetchone(self) -> dict[str, Any]:
-                return row
-
-        class _Conn:
-            def cursor(self) -> _Cursor:
-                return _Cursor()
-
-        registry._state_store = SimpleNamespace(_conn=_Conn())
-
-        with pytest.raises(ToolExecutionError) as exc_info:
-            registry.invoke(
-                ToolName.READ_DOC_CHUNK,
-                {"ref": "document_id:4ec4e588187e6771"},
-            )
-
-        payload = json.loads(str(exc_info.value))
-        assert payload["error"]["code"] == "doc_chunk_excluded"
-
-    @pytest.mark.parametrize(
-        ("source_uri", "document_id", "title", "page_title", "expected"),
-        [
-            # Existing markers (regression)
-            ("document://attachment:audit-checklist.json", "abc123", "audit-checklist.json", None, True),
-            ("document://attachment:workflow-summary.json", "def456", "workflow-summary.json", None, True),
-            # New markers added for corpus hygiene
-            (
-                "document://attachment:audit-checklist.retrieval-trace.json",
-                "rt1",
-                "audit-checklist.retrieval-trace.json",
-                None,
-                True,
-            ),
-            (
-                "document://attachment:audit-checklist.security-evidence.preflight.json",
-                "se1",
-                "audit-checklist.security-evidence.preflight.json",
-                None,
-                True,
-            ),
-            ("document://attachment:run-history.json", "rh1", "run-history.json", None, True),
-            ("attachment://88730243/att88730245", "attachment:att88730245", "project-readiness.json", None, True),
-            (None, "audit results - miniapp-be", None, None, True),
-            (
-                "document://attachment:att88727031",
-                "attachment:att88727031",
-                None,
-                "code_evidence_pack.json",
-                True,
-            ),
-            # Negative cases — real docs must NOT be excluded
-            ("https://confluence/display/PROJ/API+Design", "page123", "API Design Guide", None, False),
-            ("https://confluence/display/PROJ/BRD", "brd456", "Business Requirements Document", None, False),
-        ],
-    )
-    def test_is_excluded_docs_artifact_catches_new_patterns(
-        self,
-        source_uri: str | None,
-        document_id: str | None,
-        title: str | None,
-        page_title: str | None,
-        expected: bool,
-    ) -> None:
-        metadata: dict[str, Any] = {}
-        if title:
-            metadata["title"] = title
-        if page_title:
-            metadata["page_title"] = page_title
-        result = ToolRegistry._is_excluded_docs_artifact(
-            source_uri=source_uri,
-            document_id=document_id,
-            metadata=metadata,
-        )
-        assert result is expected, (
-            f"Expected {expected} for source_uri={source_uri!r}, document_id={document_id!r}, title={title!r}"
-        )
-
-    def test_search_code_maps_rg_output_deterministically(
-        self, monkeypatch: pytest.MonkeyPatch, tmp_path: Path
-    ) -> None:
-        repo_path = tmp_path / "repo"
-        repo_path.mkdir()
-
-        registry = ToolRegistry(repo_path=str(repo_path))
-        stdout = "\n".join(
-            [
-                f"{repo_path / 'b.py'}:7:delta",
-                f"{repo_path / 'a.py'}:12:beta",
-                f"{repo_path / 'a.py'}:3:alpha",
-            ],
-        )
-
-        monkeypatch.setattr(
-            "vds_audit_orchestrator.agents.tool_registry.subprocess.run",
-            lambda *args, **kwargs: SimpleNamespace(returncode=0, stdout=stdout, stderr=""),
-        )
-
-        result = registry.invoke(ToolName.SEARCH_CODE, {"query": "x", "limit": 2})
-        assert [hit["ref"] for hit in result.payload["hits"]] == ["code:a.py:3", "code:a.py:12"]
-        assert [hit["excerpt"] for hit in result.payload["hits"]] == ["alpha", "beta"]
-        assert result.payload["hits"][0]["score"] >= result.payload["hits"][1]["score"]
-
-    def test_search_code_runs_rg_in_ignore_case_mode(
-        self,
-        monkeypatch: pytest.MonkeyPatch,
-        tmp_path: Path,
-    ) -> None:
-        repo_path = tmp_path / "repo"
-        repo_path.mkdir()
-        registry = ToolRegistry(repo_path=str(repo_path))
-        captured: dict[str, Any] = {}
-
-        def _fake_run(*args, **kwargs):  # type: ignore[no-untyped-def]
-            captured["command"] = list(args[0])
-            return SimpleNamespace(returncode=1, stdout="", stderr="")
-
-        monkeypatch.setattr(
-            "vds_audit_orchestrator.agents.tool_registry.subprocess.run",
-            _fake_run,
-        )
-
-        registry.invoke(ToolName.SEARCH_CODE, {"query": "Hexagonal", "limit": 3})
-
-        command = captured.get("command") or []
-        assert "--ignore-case" in command
-
-    def test_search_code_uses_code_scoped_globs_before_broad_fallback(
-        self,
-        monkeypatch: pytest.MonkeyPatch,
-        tmp_path: Path,
-    ) -> None:
-        repo_path = tmp_path / "repo"
-        repo_path.mkdir()
-        registry = ToolRegistry(repo_path=str(repo_path))
-        commands: list[list[str]] = []
-
-        def _fake_run(*args, **kwargs):  # type: ignore[no-untyped-def]
-            command = list(args[0])
-            commands.append(command)
-            return SimpleNamespace(returncode=1, stdout="", stderr="")
-
-        monkeypatch.setattr(
-            "vds_audit_orchestrator.agents.tool_registry.subprocess.run",
-            _fake_run,
-        )
-
-        registry.invoke(ToolName.SEARCH_CODE, {"query": "Hexagonal", "limit": 3})
-
-        assert commands
-        assert any("-g" in command for command in commands)
-        assert any("-g" not in command for command in commands)
-        assert any("*.py" in command for command in commands)
-
-    def test_search_code_falls_back_to_broad_hits_when_code_scoped_is_empty(
-        self,
-        monkeypatch: pytest.MonkeyPatch,
-        tmp_path: Path,
-    ) -> None:
-        repo_path = tmp_path / "repo"
-        repo_path.mkdir()
-        registry = ToolRegistry(repo_path=str(repo_path))
-        docs_path = repo_path / "docs" / "DEPLOYMENT_GUIDE.md"
-        call_count = {"value": 0}
-
-        def _fake_run(*args, **kwargs):  # type: ignore[no-untyped-def]
-            command = list(args[0])
-            call_count["value"] += 1
-            if "-g" in command:
-                return SimpleNamespace(returncode=1, stdout="", stderr="")
-            return SimpleNamespace(
-                returncode=0,
-                stdout=f"{docs_path}:32:offline deployment instructions",
-                stderr="",
-            )
-
-        monkeypatch.setattr(
-            "vds_audit_orchestrator.agents.tool_registry.subprocess.run",
-            _fake_run,
-        )
-
-        result = registry.invoke(ToolName.SEARCH_CODE, {"query": "offline deployment", "limit": 3})
-
-        assert call_count["value"] >= 2
-        assert result.payload["hits"]
-        assert result.payload["hits"][0]["title"] == "docs/DEPLOYMENT_GUIDE.md"
-
-    def test_search_code_prefers_observability_paths_for_logging_query(
-        self,
-        monkeypatch: pytest.MonkeyPatch,
-        tmp_path: Path,
-    ) -> None:
-        repo_path = tmp_path / "repo"
-        repo_path.mkdir()
-        registry = ToolRegistry(repo_path=str(repo_path))
-        logging_path = repo_path / "src" / "logging" / "request_logger.py"
-        constants_path = repo_path / "src" / "constants.py"
-
-        def _fake_run(*args, **kwargs):  # type: ignore[no-untyped-def]
-            query = str(args[0][-2])
-            if query == "structured logging format":
-                stdout = ""
-            elif query in {"structured", "logging"}:
-                stdout = "\n".join(
-                    [
-                        f"{constants_path}:4:STRUCTURED_EVENT = 'request'",
-                        f"{logging_path}:22:def configure_structured_logging():",
-                    ],
-                )
-            elif query == "format":
-                stdout = f"{logging_path}:30:formatter = JSONFormatter()"
-            else:
-                stdout = ""
-            return SimpleNamespace(returncode=0, stdout=stdout, stderr="")
-
-        monkeypatch.setattr(
-            "vds_audit_orchestrator.agents.tool_registry.subprocess.run",
-            _fake_run,
-        )
-
-        result = registry.invoke(ToolName.SEARCH_CODE, {"query": "structured logging format", "limit": 3})
-
-        assert result.payload["hits"]
-        assert result.payload["hits"][0]["title"] == "src/logging/request_logger.py"
-        assert result.payload["hits"][0]["score"] > result.payload["hits"][-1]["score"]
-
-    def test_search_code_alerting_query_filters_slack_time_false_positive(
-        self,
-        monkeypatch: pytest.MonkeyPatch,
-        tmp_path: Path,
-    ) -> None:
-        repo_path = tmp_path / "repo"
-        repo_path.mkdir()
-        registry = ToolRegistry(repo_path=str(repo_path))
-        false_positive_path = repo_path / "src" / "scheduler" / "timing.py"
-        test_fixture_path = repo_path / "tests" / "unit" / "alerting" / "test_alert_rules.py"
-        alerting_path = repo_path / "config" / "alerting" / "slack_alert_rules.yml"
-
-        def _fake_run(*args, **kwargs):  # type: ignore[no-untyped-def]
-            stdout = "\n".join(
-                [
-                    f"{false_positive_path}:12:batch_overhead_ms: Slack time for formatting + bookkeeping",
-                    f"{test_fixture_path}:19:slack alert receiver test fixture",
-                    f"{alerting_path}:22:alertmanager receiver sends slack webhook notification",
-                ],
-            )
-            return SimpleNamespace(returncode=0, stdout=stdout, stderr="")
-
-        monkeypatch.setattr(
-            "vds_audit_orchestrator.agents.tool_registry.subprocess.run",
-            _fake_run,
-        )
-
-        result = registry.invoke(
-            ToolName.SEARCH_CODE,
-            {"query": "alerting rules via email slack telegram channels", "limit": 5},
-        )
-
-        titles = [hit["title"] for hit in result.payload["hits"]]
-        assert "config/alerting/slack_alert_rules.yml" in titles
-        assert "src/scheduler/timing.py" not in titles
-        assert "tests/unit/alerting/test_alert_rules.py" not in titles
-
-    def test_search_code_security_scan_query_filters_internal_and_test_paths(
-        self,
-        monkeypatch: pytest.MonkeyPatch,
-        tmp_path: Path,
-    ) -> None:
-        repo_path = tmp_path / "repo"
-        repo_path.mkdir()
-        registry = ToolRegistry(repo_path=str(repo_path))
-        internal_path = repo_path / "src" / "vds_audit_orchestrator" / "engine" / "row_evaluator_types.py"
-        internal_publisher_path = (
-            repo_path
-            / "audit_orchestrator"
-            / "src"
-            / "vds_audit_orchestrator"
-            / "publishers"
-            / "confluence_publisher.py"
-        )
-        test_path = repo_path / "tests" / "unit" / "security" / "test_scans.py"
-        false_positive_path = repo_path / "src" / "scheduler" / "timing.py"
-        pipeline_path = repo_path / ".github" / "workflows" / "security_scan.yml"
-
-        def _fake_run(*args, **kwargs):  # type: ignore[no-untyped-def]
-            stdout = "\n".join(
-                [
-                    f"{internal_path}:44:high/critical vulnerability scoring constants",
-                    f"{internal_publisher_path}:88:high critical fail severity mapping",
-                    f"{test_path}:20:sast dast unit fixture",
-                    f"{false_positive_path}:26:importance level high critical for queue jobs",
-                    f"{pipeline_path}:12:name: SAST and DAST scan",
-                ],
-            )
-            return SimpleNamespace(returncode=0, stdout=stdout, stderr="")
-
-        monkeypatch.setattr(
-            "vds_audit_orchestrator.agents.tool_registry.subprocess.run",
-            _fake_run,
-        )
-
-        result = registry.invoke(
-            ToolName.SEARCH_CODE,
-            {"query": "SAST DAST vulnerability high critical security scan", "limit": 5},
-        )
-
-        titles = [hit["title"] for hit in result.payload["hits"]]
-        assert ".github/workflows/security_scan.yml" in titles
-        assert "src/vds_audit_orchestrator/engine/row_evaluator_types.py" not in titles
-        assert "audit_orchestrator/src/vds_audit_orchestrator/publishers/confluence_publisher.py" not in titles
-        assert "tests/unit/security/test_scans.py" not in titles
-        assert "src/scheduler/timing.py" not in titles
-
-    def test_build_code_search_queries_security_scan_omits_generic_severity_terms(self, tmp_path: Path) -> None:
-        repo_path = tmp_path / "repo"
-        repo_path.mkdir()
-        registry = ToolRegistry(repo_path=str(repo_path))
-
-        queries = registry._build_code_search_queries("SAST DAST vulnerability high critical security scan")
-        lowered = [query.lower() for query in queries]
-
-        assert "high" not in lowered
-        assert "critical" not in lowered
-        assert "sast" in lowered
-        assert "dast" in lowered
-
-    def test_extract_query_terms_mixed_language_filters_low_signal_and_keeps_high_signal_short_terms(self) -> None:
-        terms = ToolRegistry._extract_query_terms("Kiểm tra phân tích SQL kết nối cơ sở dữ liệu repository")
-
-        assert "sql" in terms
-        assert "repository" in terms
-        assert "kiem" not in terms
-        assert "tra" not in terms
-        assert "phan" not in terms
-        assert "tich" not in terms
-
-    def test_is_db_decoupling_query_accepts_vietnamese_and_ascii_aliases(self) -> None:
-        assert ToolRegistry._is_db_decoupling_query("Kiểm tra kết nối cơ sở dữ liệu liên service")
-        assert ToolRegistry._is_db_decoupling_query("check datasource connection string and schema access")
-
-    def test_build_code_search_queries_db_intent_adds_specialized_expansions(self, tmp_path: Path) -> None:
-        repo_path = tmp_path / "repo"
-        repo_path.mkdir()
-        registry = ToolRegistry(repo_path=str(repo_path))
-
-        queries = registry._build_code_search_queries("Kiểm tra datasource và schema repository")
-        lowered = {query.lower() for query in queries}
-
-        assert len(queries) <= 12
-        assert "datasource" in lowered
-        assert "entitymanager" in lowered
-        assert "@repository" in lowered
-        assert "datasource entitymanager nativequery" in lowered
-
-    def test_build_code_search_queries_project_scope_dependency_adds_source_structure_expansions(
-        self, tmp_path: Path
-    ) -> None:
-        repo_path = tmp_path / "repo"
-        repo_path.mkdir()
-        registry = ToolRegistry(repo_path=str(repo_path))
-
-        queries = registry._build_code_search_queries(
-            "No circular dependency in dependency graph between modules/services for clean architecture"
-        )
-        lowered = {query.lower() for query in queries}
-
-        assert len(queries) <= 10
-        assert "module service import" in lowered
-        assert "client integration config" in lowered
-        assert "port adapter usecase" in lowered
-
-    def test_search_code_db_intent_uses_adaptive_ripgrep_max_count(
-        self,
-        monkeypatch: pytest.MonkeyPatch,
-        tmp_path: Path,
-    ) -> None:
-        repo_path = tmp_path / "repo"
-        repo_path.mkdir()
-        registry = ToolRegistry(repo_path=str(repo_path))
-
-        observed_max_counts: list[int] = []
-
-        def _fake_run_code_search_query(  # type: ignore[no-untyped-def]
-            *,
-            query: str,
-            search_root: Path,
-            scope_globs: tuple[str, ...] | None = None,
-            max_count: int = 5,
-        ) -> Any:
-            _ = query, search_root, scope_globs
-            observed_max_counts.append(int(max_count))
-            return SimpleNamespace(returncode=1, stdout="", stderr="")
-
-        monkeypatch.setattr(registry, "_run_code_search_query", _fake_run_code_search_query)
-
-        registry.invoke(
-            ToolName.SEARCH_CODE,
-            {"query": "Kiểm tra datasource connection string schema repository", "limit": 3},
-        )
-        assert 12 in observed_max_counts
-        assert 20 in observed_max_counts
-
-        observed_max_counts.clear()
-        registry.invoke(ToolName.SEARCH_CODE, {"query": "hexagonal architecture adapter", "limit": 3})
-        assert set(observed_max_counts) == {5}
-
-    def test_code_path_relevance_bonus_for_db_query_demotes_service_impl_paths(self) -> None:
-        query = "database schema datasource native sql repository"
-        config_bonus = ToolRegistry._code_path_relevance_bonus(
-            path_value="src/main/java/com/example/config/database/CampaignDatabaseConfig.java",
-            query=query,
-        )
-        repository_bonus = ToolRegistry._code_path_relevance_bonus(
-            path_value="src/main/java/com/example/repository/campaign/ConfigurationRepository.java",
-            query=query,
-        )
-        service_bonus = ToolRegistry._code_path_relevance_bonus(
-            path_value="src/main/java/com/example/service/impl/ApprovalManagementServiceImpl.java",
-            query=query,
-        )
-
-        assert config_bonus > service_bonus
-        assert repository_bonus > service_bonus
-        assert config_bonus > 0.0
-
-    def test_search_code_scope_config_returns_config_only_hits(
-        self,
-        monkeypatch: pytest.MonkeyPatch,
-        tmp_path: Path,
-    ) -> None:
-        repo_path = tmp_path / "repo"
-        repo_path.mkdir()
-        config_root = repo_path / "config" / "service-a" / "staging"
-        config_root.mkdir(parents=True)
-
-        registry = ToolRegistry(
-            repo_path=str(repo_path),
-            config_root=str(config_root),
-        )
-
-        def _fake_run(*args, **kwargs):  # type: ignore[no-untyped-def]
-            command = list(args[0])
-            search_root = Path(str(command[-1]))
-            if search_root == config_root:
-                stdout = f"{config_root / 'application.yml'}:12:needle-config-value"
-                return SimpleNamespace(returncode=0, stdout=stdout, stderr="")
-            return SimpleNamespace(returncode=1, stdout="", stderr="")
-
-        monkeypatch.setattr(
-            "vds_audit_orchestrator.agents.tool_registry.subprocess.run",
-            _fake_run,
-        )
-
-        result = registry.invoke(
-            ToolName.SEARCH_CODE,
-            {"query": "needle-config-value", "scope": "config", "limit": 5},
-        )
-
-        assert len(result.payload["hits"]) == 1
-        hit = result.payload["hits"][0]
-        assert hit["ref"] == "config:application.yml:12"
-        assert hit["title"] == "application.yml"
-        assert hit["excerpt"] == "needle-config-value"
-        assert hit["source"] == "config"
-
-    def test_search_code_scope_all_emits_source_tags_for_code_config_and_lib(
-        self,
-        monkeypatch: pytest.MonkeyPatch,
-        tmp_path: Path,
-    ) -> None:
-        repo_path = tmp_path / "repo"
-        repo_path.mkdir()
-        config_root = repo_path / "config" / "service-a"
-        config_root.mkdir(parents=True)
-        lib_root = repo_path / "libs" / "shared-core"
-        lib_root.mkdir(parents=True)
-
-        registry = ToolRegistry(
-            repo_path=str(repo_path),
-            config_root=str(config_root),
-            lib_roots=[str(lib_root)],
-        )
-
-        def _fake_run(*args, **kwargs):  # type: ignore[no-untyped-def]
-            command = list(args[0])
-            search_root = Path(str(command[-1]))
-            if search_root == repo_path:
-                stdout = f"{repo_path / 'src' / 'main.py'}:5:needle"
-                return SimpleNamespace(returncode=0, stdout=stdout, stderr="")
-            if search_root == config_root:
-                stdout = f"{config_root / 'production.yml'}:8:needle"
-                return SimpleNamespace(returncode=0, stdout=stdout, stderr="")
-            if search_root == lib_root:
-                stdout = f"{lib_root / 'src' / 'helper.py'}:4:needle"
-                return SimpleNamespace(returncode=0, stdout=stdout, stderr="")
-            return SimpleNamespace(returncode=1, stdout="", stderr="")
-
-        monkeypatch.setattr(
-            "vds_audit_orchestrator.agents.tool_registry.subprocess.run",
-            _fake_run,
-        )
-
-        result = registry.invoke(ToolName.SEARCH_CODE, {"query": "needle", "scope": "all", "limit": 10})
-        hits = result.payload["hits"]
-
-        assert hits
-        assert {"code", "config", "lib"} == {item["source"] for item in hits}
-        assert any(item["ref"].startswith("code:") for item in hits)
-        assert any(item["ref"].startswith("config:") for item in hits)
-        assert any(item["ref"].startswith("lib:") for item in hits)
-
-    def test_search_code_scope_config_resolves_env_app_config_root(
-        self,
-        monkeypatch: pytest.MonkeyPatch,
-        tmp_path: Path,
-    ) -> None:
-        # VDS_AUDIT_APP_CONFIG_PATH is treated as a trusted external root.
-        # When the app-config tree contains a subdirectory matching the repo
-        # name, _resolve_env_config_root resolves it and the config scope
-        # search includes it.
-        repo_path = tmp_path / "service-a"
-        repo_path.mkdir()
-        app_config_root = tmp_path / "app-config"
-        (app_config_root / "service-a" / "staging").mkdir(parents=True)
-
-        registry = ToolRegistry(repo_path=str(repo_path))
-        observed_roots: list[Path] = []
-
-        def _fake_run(*args, **kwargs):  # type: ignore[no-untyped-def]
-            command = list(args[0])
-            observed_roots.append(Path(str(command[-1])))
-            return SimpleNamespace(returncode=1, stdout="", stderr="")
-
-        monkeypatch.setenv("VDS_AUDIT_APP_CONFIG_PATH", str(app_config_root))
-        monkeypatch.delenv("VDS_AUDIT_CONFIG_ROOT", raising=False)
-        monkeypatch.setattr(
-            "vds_audit_orchestrator.agents.tool_registry.subprocess.run",
-            _fake_run,
-        )
-
-        registry.invoke(ToolName.SEARCH_CODE, {"query": "needle", "scope": "config", "limit": 3})
-
-        # The resolved config root (app-config/service-a) is trusted and searched.
-        assert len(observed_roots) >= 1
-        assert any("service-a" in str(root) for root in observed_roots)
-
-    def test_search_code_scope_config_resolves_env_config_root(
-        self,
-        monkeypatch: pytest.MonkeyPatch,
-        tmp_path: Path,
-    ) -> None:
-        # VDS_AUDIT_CONFIG_ROOT is treated as a trusted external root.
-        # The config scope search includes it even though it lives outside
-        # the active repository directory.
-        repo_path = tmp_path / "service-a"
-        repo_path.mkdir()
-        external_config_root = tmp_path / "external-config"
-        external_config_root.mkdir()
-
-        registry = ToolRegistry(repo_path=str(repo_path))
-        observed_roots: list[Path] = []
-
-        def _fake_run(*args, **kwargs):  # type: ignore[no-untyped-def]
-            command = list(args[0])
-            observed_roots.append(Path(str(command[-1])))
-            return SimpleNamespace(returncode=1, stdout="", stderr="")
-
-        monkeypatch.setenv("VDS_AUDIT_CONFIG_ROOT", str(external_config_root))
-        monkeypatch.delenv("VDS_AUDIT_APP_CONFIG_PATH", raising=False)
-        monkeypatch.setattr(
-            "vds_audit_orchestrator.agents.tool_registry.subprocess.run",
-            _fake_run,
-        )
-
-        registry.invoke(ToolName.SEARCH_CODE, {"query": "needle", "scope": "config", "limit": 3})
-
-        # The env-specified config root is trusted and searched.
-        assert len(observed_roots) >= 1
-        assert any("external-config" in str(root) for root in observed_roots)
-
-    def test_search_code_scope_all_ignores_external_env_lib_roots(
-        self,
-        monkeypatch: pytest.MonkeyPatch,
-        tmp_path: Path,
-    ) -> None:
-        repo_path = tmp_path / "repo"
-        repo_path.mkdir()
-        external_lib_root = tmp_path / "shared-libs" / "common"
-        external_lib_root.mkdir(parents=True)
-        registry = ToolRegistry(repo_path=str(repo_path))
-        observed_roots: list[Path] = []
-
-        def _fake_run(*args, **kwargs):  # type: ignore[no-untyped-def]
-            command = list(args[0])
-            observed_roots.append(Path(str(command[-1])))
-            return SimpleNamespace(returncode=1, stdout="", stderr="")
-
-        monkeypatch.setenv("VDS_AUDIT_LIB_ROOTS", str(external_lib_root))
-        monkeypatch.setattr(
-            "vds_audit_orchestrator.agents.tool_registry.subprocess.run",
-            _fake_run,
-        )
-
-        registry.invoke(ToolName.SEARCH_CODE, {"query": "needle", "scope": "all", "limit": 3})
-
-        assert external_lib_root not in observed_roots
-        assert observed_roots
-        assert set(observed_roots) == {repo_path}
-
-    def test_code_path_relevance_bonus_applies_business_control_domain_weighting_and_penalties(self) -> None:
-        query = "pricing sla support security compliance controls"
-
-        domain_path_bonus = ToolRegistry._code_path_relevance_bonus(
-            path_value="src/billing/pricing_sla_support_security_compliance_service.py",
-            query=query,
-        )
-        internal_path_bonus = ToolRegistry._code_path_relevance_bonus(
-            path_value="src/vds_audit_orchestrator/agents/helpers/config_loader.py",
-            query=query,
-        )
-        test_path_bonus = ToolRegistry._code_path_relevance_bonus(
-            path_value="tests/unit/billing/test_controls.py",
-            query=query,
-        )
-        dotfile_path_bonus = ToolRegistry._code_path_relevance_bonus(
-            path_value=".github/workflows/ci.yml",
-            query=query,
-        )
-
-        assert domain_path_bonus > 0.0
-        assert internal_path_bonus < 0.0
-        assert test_path_bonus < 0.0
-        assert dotfile_path_bonus < 0.0
-        assert domain_path_bonus > internal_path_bonus
-
-    def test_search_code_business_control_query_demotes_internal_test_and_dotfile_paths(
-        self,
-        monkeypatch: pytest.MonkeyPatch,
-        tmp_path: Path,
-    ) -> None:
-        repo_path = tmp_path / "repo"
-        repo_path.mkdir()
-        registry = ToolRegistry(repo_path=str(repo_path))
-        domain_path = repo_path / "src" / "billing" / "pricing_sla_support_security_compliance_service.py"
-        internal_path = repo_path / "src" / "vds_audit_orchestrator" / "agents" / "helpers" / "config_loader.py"
-        test_path = repo_path / "tests" / "unit" / "billing" / "test_controls.py"
-        dotfile_path = repo_path / ".github" / "workflows" / "ci.yml"
-        excerpt = "pricing sla support security compliance controls workflow"
-
-        def _fake_run(*args, **kwargs):  # type: ignore[no-untyped-def]
-            query = str(args[0][-2])
-            if query == "pricing sla support security compliance controls":
-                stdout = ""
-            else:
-                stdout = "\n".join(
-                    [
-                        f"{internal_path}:5:{excerpt}",
-                        f"{dotfile_path}:9:{excerpt}",
-                        f"{test_path}:14:{excerpt}",
-                        f"{domain_path}:28:{excerpt}",
-                    ],
-                )
-            return SimpleNamespace(returncode=0, stdout=stdout, stderr="")
-
-        monkeypatch.setattr(
-            "vds_audit_orchestrator.agents.tool_registry.subprocess.run",
-            _fake_run,
-        )
-
-        result = registry.invoke(
-            ToolName.SEARCH_CODE, {"query": "pricing sla support security compliance controls", "limit": 4}
-        )
-
-        titles = [hit["title"] for hit in result.payload["hits"]]
-        assert titles[0] == "src/billing/pricing_sla_support_security_compliance_service.py"
-        assert titles.index("src/billing/pricing_sla_support_security_compliance_service.py") < titles.index(
-            "src/vds_audit_orchestrator/agents/helpers/config_loader.py",
-        )
-        assert titles.index("src/billing/pricing_sla_support_security_compliance_service.py") < titles.index(
-            "tests/unit/billing/test_controls.py",
-        )
-        assert titles.index("src/billing/pricing_sla_support_security_compliance_service.py") < titles.index(
-            ".github/workflows/ci.yml",
-        )
-
-    def test_read_code_file_blocks_path_traversal(self, tmp_path: Path) -> None:
-        repo_path = tmp_path / "repo"
-        repo_path.mkdir()
-        registry = ToolRegistry(repo_path=str(repo_path))
-
-        with pytest.raises(ToolExecutionError) as exc_info:
-            registry.invoke(ToolName.READ_CODE_FILE, {"path": "../secret.txt"})
-
-        payload = json.loads(str(exc_info.value))
-        assert payload["error"]["code"] == "path_traversal_denied"
-
-    def test_read_code_file_supports_line_slicing(self, tmp_path: Path) -> None:
-        repo_path = tmp_path / "repo"
-        repo_path.mkdir()
-        file_path = repo_path / "src" / "main.py"
-        file_path.parent.mkdir(parents=True)
-        file_path.write_text("line1\nline2\nline3\nline4\n", encoding="utf-8")
-
-        registry = ToolRegistry(repo_path=str(repo_path))
-        result = registry.invoke(
-            ToolName.READ_CODE_FILE,
-            {"path": "src/main.py", "start_line": 2, "end_line": 3},
-        )
-
-        assert result.payload == {"path": "src/main.py", "content": "line2\nline3", "start_line": 2, "end_line": 3}
-
-    def test_read_code_file_scope_config_reads_from_config_root(self, tmp_path: Path) -> None:
-        repo_path = tmp_path / "repo"
-        repo_path.mkdir()
-        config_root = repo_path / "config" / "service-a" / "staging"
-        config_root.mkdir(parents=True)
-        config_file = config_root / "application.yml"
-        config_file.write_text("spring:\n  profiles: staging\n", encoding="utf-8")
-
-        registry = ToolRegistry(
-            repo_path=str(repo_path),
-            config_root=str(config_root),
-        )
-        result = registry.invoke(
-            ToolName.READ_CODE_FILE,
-            {"path": "application.yml", "scope": "config"},
-        )
-
-        assert result.payload["path"] == "application.yml"
-        assert "profiles: staging" in result.payload["content"]
-
-    def test_read_code_file_scope_lib_reads_from_named_lib_root(self, tmp_path: Path) -> None:
-        repo_path = tmp_path / "repo"
-        repo_path.mkdir()
-        lib_root = repo_path / "libs" / "shared-core"
-        lib_file = lib_root / "src" / "helpers.py"
-        lib_file.parent.mkdir(parents=True)
-        lib_file.write_text("def helper() -> str:\n    return 'ok'\n", encoding="utf-8")
-
-        registry = ToolRegistry(
-            repo_path=str(repo_path),
-            lib_roots=[str(lib_root)],
-        )
-        result = registry.invoke(
-            ToolName.READ_CODE_FILE,
-            {"path": "shared-core/src/helpers.py", "scope": "lib"},
-        )
-
-        assert result.payload["path"] == "shared-core/src/helpers.py"
-        assert "def helper" in result.payload["content"]
-
-    def test_read_code_file_scope_lib_requires_repo_prefix(self, tmp_path: Path) -> None:
-        repo_path = tmp_path / "repo"
-        repo_path.mkdir()
-        lib_root = repo_path / "libs" / "shared-core"
-        lib_file = lib_root / "src" / "helpers.py"
-        lib_file.parent.mkdir(parents=True)
-        lib_file.write_text("def helper() -> str:\n    return 'ok'\n", encoding="utf-8")
-
-        registry = ToolRegistry(
-            repo_path=str(repo_path),
-            lib_roots=[str(lib_root)],
-        )
-
-        with pytest.raises(ToolExecutionError) as exc_info:
-            registry.invoke(
-                ToolName.READ_CODE_FILE,
-                {"path": "src/helpers.py", "scope": "lib"},
-            )
-
-        payload = json.loads(str(exc_info.value))
-        assert payload["error"]["code"] == "invalid_code_path"
-        assert "required_prefixes" in payload["error"]["details"]
-        assert payload["error"]["details"]["required_prefixes"] == ["shared-core"]
-
-    def test_read_code_file_scope_config_resolves_env_app_config_root(
-        self,
-        monkeypatch: pytest.MonkeyPatch,
-        tmp_path: Path,
-    ) -> None:
-        # VDS_AUDIT_APP_CONFIG_PATH is a trusted external root. When the
-        # app-config tree contains a subdirectory matching the repo name,
-        # _resolve_env_config_root resolves it and config-scoped file reads
-        # can reach files inside it.
-        repo_path = tmp_path / "service-a"
-        repo_path.mkdir()
-        app_config_root = tmp_path / "app-config"
-        config_file = app_config_root / "service-a" / "staging" / "application.yml"
-        config_file.parent.mkdir(parents=True)
-        config_file.write_text("env: staging\n", encoding="utf-8")
-
-        registry = ToolRegistry(repo_path=str(repo_path))
-        monkeypatch.setenv("VDS_AUDIT_APP_CONFIG_PATH", str(app_config_root))
-        monkeypatch.delenv("VDS_AUDIT_CONFIG_ROOT", raising=False)
-
-        result = registry.invoke(
-            ToolName.READ_CODE_FILE,
-            {"path": "staging/application.yml", "scope": "config"},
-        )
-
-        assert result.payload["content"].strip() == "env: staging"
-
-    def test_read_code_file_scope_config_resolves_env_config_root(
-        self,
-        monkeypatch: pytest.MonkeyPatch,
-        tmp_path: Path,
-    ) -> None:
-        # VDS_AUDIT_CONFIG_ROOT is a trusted external root. Config-scoped file
-        # reads can reach files inside it even though it lives outside the repo.
-        repo_path = tmp_path / "service-a"
-        repo_path.mkdir()
-        external_config_root = tmp_path / "external-config"
-        config_file = external_config_root / "application.yml"
-        config_file.parent.mkdir(parents=True)
-        config_file.write_text("env: external\n", encoding="utf-8")
-
-        registry = ToolRegistry(repo_path=str(repo_path))
-        monkeypatch.setenv("VDS_AUDIT_CONFIG_ROOT", str(external_config_root))
-        monkeypatch.delenv("VDS_AUDIT_APP_CONFIG_PATH", raising=False)
-
-        result = registry.invoke(
-            ToolName.READ_CODE_FILE,
-            {"path": "application.yml", "scope": "config"},
-        )
-
-        assert result.payload["content"].strip() == "env: external"
-
-    def test_read_code_file_scope_lib_rejects_external_env_lib_roots(
-        self,
-        monkeypatch: pytest.MonkeyPatch,
-        tmp_path: Path,
-    ) -> None:
-        repo_path = tmp_path / "repo"
-        repo_path.mkdir()
-        external_lib_root = tmp_path / "shared-libs" / "shared-core"
-        lib_file = external_lib_root / "src" / "helpers.py"
-        lib_file.parent.mkdir(parents=True)
-        lib_file.write_text("def helper() -> str:\n    return 'external'\n", encoding="utf-8")
-
-        registry = ToolRegistry(repo_path=str(repo_path))
-        monkeypatch.setenv("VDS_AUDIT_LIB_ROOTS", str(external_lib_root))
-
-        with pytest.raises(ToolExecutionError) as exc_info:
-            registry.invoke(
-                ToolName.READ_CODE_FILE,
-                {"path": "shared-core/src/helpers.py", "scope": "lib"},
-            )
-
-        payload = json.loads(str(exc_info.value))
-        assert payload["error"]["code"] == "code_file_not_found"
-
-    def test_skill_tools_list_load_and_read_resource(self, monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
-        skill_dir = tmp_path / "skills" / "research-skill"
-        skill_dir.mkdir(parents=True)
-        (skill_dir / "SKILL.md").write_text(
-            "---\nname: research-skill\ndescription: research helper\n---\nUse this skill.\n",
-            encoding="utf-8",
-        )
-        (skill_dir / "references").mkdir()
-        (skill_dir / "references" / "guide.md").write_text("reference text", encoding="utf-8")
-
-        registry = ToolRegistry()
-        monkeypatch.setattr(
-            registry,
-            "_resolve_skills_runtime_policy",
-            lambda: {
-                "enabled": True,
-                "directories": [str(tmp_path / "skills")],
-                "allowlist": [],
-                "allowed_trust_tiers": ["internal", "external-verified", "external-unverified"],
-                "default_trust_tier": "internal",
-                "trust_tiers": {},
-                "allow_script_execution": False,
-            },
-        )
-        monkeypatch.setattr(
-            registry,
-            "_collect_skills_metadata",
-            lambda **_kwargs: [
-                SimpleNamespace(
-                    name="research-skill",
-                    metadata_name="research-skill",
-                    frontmatter_name="research-skill",
-                    runtime_name="research-skill",
-                    canonical_name="research-skill",
-                    description="research helper",
-                    path=str(skill_dir),
-                    trust_tier="internal",
-                    has_scripts=False,
-                    content_hash="abc123",
-                ),
-            ],
-        )
-
-        listed = registry.invoke(ToolName.LIST_SKILLS, {"query": "research", "limit": 10})
-        assert listed.payload["skills"][0]["name"] == "research-skill"
-
-        loaded = registry.invoke(ToolName.LOAD_SKILL, {"name": "research-skill"})
-        assert loaded.payload["found"] is True
-        assert "SKILL.md" in loaded.payload["resources"]
-
-        read = registry.invoke(
-            ToolName.READ_SKILL_RESOURCE,
-            {"name": "research-skill", "resource_path": "SKILL.md", "max_chars": 2000},
-        )
-        assert read.payload["success"] is True
-        assert "Use this skill." in read.payload["content"]
-        assert read.payload["ref"] == str((skill_dir / "SKILL.md").resolve())
-
-    def test_skill_tools_accept_alias_argument_names(self, monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
-        skill_dir = tmp_path / "skills" / "research-skill"
-        skill_dir.mkdir(parents=True)
-        (skill_dir / "SKILL.md").write_text(
-            "---\nname: research-skill\ndescription: research helper\n---\nUse this skill.\n",
-            encoding="utf-8",
-        )
-
-        registry = ToolRegistry()
-        monkeypatch.setattr(
-            registry,
-            "_resolve_skills_runtime_policy",
-            lambda: {
-                "enabled": True,
-                "directories": [str(tmp_path / "skills")],
-                "allowlist": [],
-                "allowed_trust_tiers": ["internal", "external-verified", "external-unverified"],
-                "default_trust_tier": "internal",
-                "trust_tiers": {},
-                "allow_script_execution": False,
-            },
-        )
-        monkeypatch.setattr(
-            registry,
-            "_collect_skills_metadata",
-            lambda **_kwargs: [
-                SimpleNamespace(
-                    name="research-skill",
-                    metadata_name="research-skill",
-                    frontmatter_name="research-skill",
-                    runtime_name="research-skill",
-                    canonical_name="research-skill",
-                    description="research helper",
-                    path=str(skill_dir),
-                    trust_tier="internal",
-                    has_scripts=False,
-                    content_hash="abc123",
-                ),
-            ],
-        )
-
-        loaded = registry.invoke(ToolName.LOAD_SKILL, {"skill_name": "research-skill"})
-        assert loaded.payload["found"] is True
-
-        read = registry.invoke(
-            ToolName.READ_SKILL_RESOURCE,
-            {"skill_name": "research-skill", "resource_name": "SKILL.md", "max_chars": 2000},
-        )
-        assert read.payload["success"] is True
-        assert "Use this skill." in read.payload["content"]
-
-        script = registry.invoke(
-            ToolName.RUN_SKILL_SCRIPT,
-            {"skill_name": "research-skill", "script": "scripts/run.sh", "args": [], "timeout_seconds": 30},
-        )
-        assert script.payload["success"] is False
-        assert script.payload["error"] == "script_execution_disabled"
-
-    def test_read_skill_resource_row_analysis_falls_back_to_skill_md(
-        self,
-        monkeypatch: pytest.MonkeyPatch,
-        tmp_path: Path,
-    ) -> None:
-        skill_dir = tmp_path / "skills" / "research-skill"
-        skill_dir.mkdir(parents=True)
-        (skill_dir / "SKILL.md").write_text(
-            "---\nname: research-skill\ndescription: research helper\n---\nFallback guidance.\n",
-            encoding="utf-8",
-        )
-
-        registry = ToolRegistry()
-        monkeypatch.setattr(
-            registry,
-            "_resolve_skills_runtime_policy",
-            lambda: {
-                "enabled": True,
-                "directories": [str(tmp_path / "skills")],
-                "allowlist": [],
-                "allowed_trust_tiers": ["internal", "external-verified", "external-unverified"],
-                "default_trust_tier": "internal",
-                "trust_tiers": {},
-                "allow_script_execution": False,
-            },
-        )
-        monkeypatch.setattr(
-            registry,
-            "_collect_skills_metadata",
-            lambda **_kwargs: [
-                SimpleNamespace(
-                    name="research-skill",
-                    metadata_name="research-skill",
-                    frontmatter_name="research-skill",
-                    runtime_name="research-skill",
-                    canonical_name="research-skill",
-                    description="research helper",
-                    path=str(skill_dir),
-                    trust_tier="internal",
-                    has_scripts=False,
-                    content_hash="abc123",
-                ),
-            ],
-        )
-
-        read = registry.invoke(
-            ToolName.READ_SKILL_RESOURCE,
-            {"name": "research-skill", "resource_path": "references/row-analysis.md", "max_chars": 2000},
-        )
-
-        assert read.payload["success"] is True
-        assert read.payload["resource_path"] == "SKILL.md"
-        assert "Fallback guidance." in read.payload["content"]
-        assert read.payload["ref"] == str((skill_dir / "SKILL.md").resolve())
-
-    def test_run_skill_script_returns_disabled_when_policy_blocks_execution(self) -> None:
-        registry = ToolRegistry()
-        registry._resolve_skills_runtime_policy = lambda: {  # type: ignore[method-assign]
-            "enabled": True,
-            "directories": [],
-            "allowlist": [],
-            "allowed_trust_tiers": [],
-            "default_trust_tier": "internal",
-            "trust_tiers": {},
-            "allow_script_execution": False,
-        }
-
-        result = registry.invoke(
-            ToolName.RUN_SKILL_SCRIPT,
-            {"name": "research-skill", "script_path": "scripts/run.sh", "args": [], "timeout_seconds": 30},
-        )
-
-        assert result.payload["success"] is False
-        assert result.payload["error"] == "script_execution_disabled"
-
-    def test_resolve_skills_runtime_policy_honors_env_overrides_when_config_unavailable(
-        self,
-        monkeypatch: pytest.MonkeyPatch,
-        tmp_path: Path,
-    ) -> None:
-        skills_a = tmp_path / "skills-a"
-        skills_b = tmp_path / "skills-b"
-        skills_a.mkdir()
-        skills_b.mkdir()
-        registry = ToolRegistry()
-        monkeypatch.setenv("VDS_AUDIT_LLM__SKILLS_TOOLSET_ENABLED", "true")
-        monkeypatch.setenv("VDS_AUDIT_LLM__SKILLS_DIRECTORIES", json.dumps([str(skills_a), str(skills_b)]))
-        monkeypatch.setenv("VDS_AUDIT_LLM__SKILLS_ALLOWLIST", "research-skill,vds-scripts-skill")
-        monkeypatch.setenv("VDS_AUDIT_LLM__SKILLS_ALLOWED_TRUST_TIERS", '["internal","external-verified"]')
-        monkeypatch.setenv("VDS_AUDIT_LLM__SKILLS_DEFAULT_TRUST_TIER", "internal")
-        monkeypatch.setenv("VDS_AUDIT_LLM__SKILLS_TRUST_TIERS", '{"research-skill":"internal"}')
-        monkeypatch.setenv("VDS_AUDIT_LLM__SKILLS_ALLOW_SCRIPT_EXECUTION", "yes")
-
-        def _raise_config_error() -> Any:
-            raise RuntimeError("config unavailable")
-
-        monkeypatch.setattr("vds_audit_orchestrator.config.get_config", _raise_config_error)
-
-        policy = registry._resolve_skills_runtime_policy()
-
-        assert policy["enabled"] is True
-        # Paths are resolved via Path.resolve(strict=False) in _normalize_skill_directories.
-        assert policy["directories"] == [str(skills_a.resolve()), str(skills_b.resolve())]
-        assert policy["allowlist"] == ["research-skill", "vds-scripts-skill"]
-        assert policy["allowed_trust_tiers"] == ["internal", "external-verified"]
-        assert policy["default_trust_tier"] == "internal"
-        assert policy["trust_tiers"] == {"research-skill": "internal"}
-        assert policy["allow_script_execution"] is True
-
-
-def test_lookup_doc_chunk_excludes_ops_repo_file_from_repo_null_fallback() -> None:
-    registry = ToolRegistry(
-        state_dsn="postgresql://user:pass@host/db",
-        project_key="project-a",
-    )
-
-    captured: dict[str, Any] = {}
-
-    class _Cursor:
-        def execute(self, sql: str, params: tuple[Any, ...]) -> None:
-            captured["sql"] = sql
-            captured["params"] = params
-
-        def fetchone(self) -> None:
-            return None
-
-    class _CursorContext:
-        def __init__(self) -> None:
-            self._cursor = _Cursor()
-
-        def __enter__(self) -> _Cursor:
-            return self._cursor
-
-        def __exit__(self, exc_type, exc, tb) -> bool:  # type: ignore[no-untyped-def]
-            _ = exc_type, exc, tb
-            return False
-
-    class _Conn:
-        def cursor(self) -> _CursorContext:
-            return _CursorContext()
-
-    registry._state_store = SimpleNamespace(_conn=_Conn())  # type: ignore[assignment]
-
-    result = registry._lookup_doc_chunk(
-        chunk_id="chunk-1",
-        source_uri=None,
-        document_id=None,
-        repo_key="repo-a",
-    )
-
-    assert result is None
-    sql = str(captured.get("sql") or "")
-    assert "d.source_type NOT IN ('code_file', 'ops_repo_file')" in sql
-
-
-# ---------------------------------------------------------------------------
-# P172-F: TSK-172.35–37 — Skill resource fallback telemetry
-# ---------------------------------------------------------------------------
-
-
-class TestResourceFallbackTelemetry:
-    """Verify requested_resource_fallback flag + skill_resource_fallback telemetry event."""
-
-    def _make_registry_with_skill(
-        self,
-        monkeypatch: pytest.MonkeyPatch,
-        tmp_path: Path,
-        *,
-        has_row_analysis: bool = False,
-    ) -> ToolRegistry:
-        """Helper: ToolRegistry with a research-skill directory."""
-        skill_dir = tmp_path / "skills" / "research-skill"
-        skill_dir.mkdir(parents=True)
-        (skill_dir / "SKILL.md").write_text(
-            "---\nname: research-skill\n---\nSkill guidance.\n",
-            encoding="utf-8",
-        )
-        if has_row_analysis:
-            refs = skill_dir / "references"
-            refs.mkdir()
-            (refs / "row-analysis.md").write_text("Row analysis content.", encoding="utf-8")
-
-        registry = ToolRegistry()
-        monkeypatch.setattr(
-            registry,
-            "_resolve_skills_runtime_policy",
-            lambda: {
-                "enabled": True,
-                "directories": [str(tmp_path / "skills")],
-                "allowlist": [],
-                "allowed_trust_tiers": ["internal", "external-verified", "external-unverified"],
-                "default_trust_tier": "internal",
-                "trust_tiers": {},
-                "allow_script_execution": False,
-            },
-        )
-        monkeypatch.setattr(
-            registry,
-            "_collect_skills_metadata",
-            lambda **_kwargs: [
-                SimpleNamespace(
-                    name="research-skill",
-                    metadata_name="research-skill",
-                    frontmatter_name="research-skill",
-                    runtime_name="research-skill",
-                    canonical_name="research-skill",
-                    description="research helper",
-                    path=str(skill_dir),
-                    trust_tier="internal",
-                    has_scripts=False,
-                    content_hash="abc123",
-                ),
-            ],
-        )
-        return registry
-
-    def test_fallback_sets_requested_resource_fallback_flag(
-        self,
-        monkeypatch: pytest.MonkeyPatch,
-        tmp_path: Path,
-    ) -> None:
-        """TSK-172.35: requested_resource_fallback=True when references/row-analysis.md absent."""
-        registry = self._make_registry_with_skill(monkeypatch, tmp_path, has_row_analysis=False)
-        read = registry.invoke(
-            ToolName.READ_SKILL_RESOURCE,
-            {"name": "research-skill", "resource_path": "references/row-analysis.md"},
-        )
-        assert read.payload["success"] is True
-        assert read.payload["requested_resource_fallback"] is True
-
-    def test_fallback_sets_fallback_reason(
-        self,
-        monkeypatch: pytest.MonkeyPatch,
-        tmp_path: Path,
-    ) -> None:
-        """TSK-172.35: fallback_reason='requested_resource_missing' when SKILL.md fallback fires."""
-        registry = self._make_registry_with_skill(monkeypatch, tmp_path, has_row_analysis=False)
-        read = registry.invoke(
-            ToolName.READ_SKILL_RESOURCE,
-            {"name": "research-skill", "resource_path": "references/row-analysis.md"},
-        )
-        assert read.payload["fallback_reason"] == "requested_resource_missing"
-
-    def test_no_fallback_when_resource_exists_directly(
-        self,
-        monkeypatch: pytest.MonkeyPatch,
-        tmp_path: Path,
-    ) -> None:
-        """TSK-172.35: requested_resource_fallback=False when references/row-analysis.md exists."""
-        registry = self._make_registry_with_skill(monkeypatch, tmp_path, has_row_analysis=True)
-        read = registry.invoke(
-            ToolName.READ_SKILL_RESOURCE,
-            {"name": "research-skill", "resource_path": "references/row-analysis.md"},
-        )
-        assert read.payload["success"] is True
-        assert read.payload["requested_resource_fallback"] is False
-
-    def test_fallback_reason_none_when_no_fallback(
-        self,
-        monkeypatch: pytest.MonkeyPatch,
-        tmp_path: Path,
-    ) -> None:
-        """TSK-172.35: fallback_reason=None when resource resolves directly."""
-        registry = self._make_registry_with_skill(monkeypatch, tmp_path, has_row_analysis=True)
-        read = registry.invoke(
-            ToolName.READ_SKILL_RESOURCE,
-            {"name": "research-skill", "resource_path": "references/row-analysis.md"},
-        )
-        assert read.payload["fallback_reason"] is None
-
-    def test_fallback_emits_skill_resource_fallback_event(
-        self,
-        monkeypatch: pytest.MonkeyPatch,
-        tmp_path: Path,
-    ) -> None:
-        """TSK-172.36: _record_skill_tool_usage called with event='skill_resource_fallback'."""
-        registry = self._make_registry_with_skill(monkeypatch, tmp_path, has_row_analysis=False)
-        recorded: list[dict[str, Any]] = []
-        monkeypatch.setattr(
-            registry,
-            "_record_skill_tool_usage",
-            lambda entry: recorded.append(dict(entry)),
-        )
-
-        registry.invoke(
-            ToolName.READ_SKILL_RESOURCE,
-            {"name": "research-skill", "resource_path": "references/row-analysis.md"},
-        )
-
-        fallback_events = [e for e in recorded if e.get("event") == "skill_resource_fallback"]
-        assert len(fallback_events) == 1
-        evt = fallback_events[0]
-        assert evt["skill_name"] == "research-skill"
-        assert evt["requested_resource"] == "references/row-analysis.md"
-        assert evt["actual_resource"] == "SKILL.md"
-        assert evt["fallback_reason"] == "requested_resource_missing"
-
-    def test_no_fallback_event_when_resource_found_directly(
-        self,
-        monkeypatch: pytest.MonkeyPatch,
-        tmp_path: Path,
-    ) -> None:
-        """TSK-172.36: No skill_resource_fallback event when resource resolves without fallback."""
-        registry = self._make_registry_with_skill(monkeypatch, tmp_path, has_row_analysis=True)
-        recorded: list[dict[str, Any]] = []
-        monkeypatch.setattr(
-            registry,
-            "_record_skill_tool_usage",
-            lambda entry: recorded.append(dict(entry)),
-        )
-
-        registry.invoke(
-            ToolName.READ_SKILL_RESOURCE,
-            {"name": "research-skill", "resource_path": "references/row-analysis.md"},
-        )
-
-        fallback_events = [e for e in recorded if e.get("event") == "skill_resource_fallback"]
-        assert len(fallback_events) == 0
-
-    def test_effective_max_depth_5_and_search_cap_architecture(self) -> None:
-        """TSK-172.37: effective_max_depth=5 and search cap allows 3+ searches for architecture rows."""
-        from vds_audit_orchestrator.engine.tool_first_planner import (
-            effective_max_depth,
-            effective_search_attempt_cap,
-        )
-
-        assert effective_max_depth("1. decoupling") == 5
-        assert effective_max_depth("2. dependency management") == 5
-        # cap = min_search_patterns(3) + 1 = 4, so search_code_attempt_count < 4 allows 4 attempts
-        assert effective_search_attempt_cap("1. decoupling") >= 4