@ngocsangairvds/vsaf 3.2.14 → 3.2.16

package/tools/vds-scripts/audit_orchestrator/tests/test_agents/test_docs_agent.py

@@ -1,2044 +0,0 @@
-"""Tests for DocumentationAgent."""
-
-from __future__ import annotations
-
-from unittest.mock import AsyncMock, MagicMock
-
-import pytest
-from vds_audit_orchestrator.agents.docs_agent import (
-    DocumentationAgent,
-    DocumentationDimension,
-    DocumentationQualityOutput,
-)
-from vds_audit_orchestrator.agents.pydantic_base import DocFindings
-from vds_audit_orchestrator.models.evidence import Evidence, EvidenceBundle, EvidenceStatus
-
-
-def build_doc_output(score: float = 0.85) -> DocumentationQualityOutput:
-    """Build structured documentation quality output for tests."""
-    dimension = DocumentationDimension(
-        score=score,
-        missing_sections=[],
-        issues=[],
-        outdated_indicators=[],
-        notes="",
-    )
-    return DocumentationQualityOutput(
-        completeness=dimension,
-        clarity=dimension,
-        currency=dimension,
-        structure=dimension,
-        overall_score=score,
-        summary="Documentation analysis complete",
-        recommendations=["Improve documentation"] if score < 0.9 else [],
-    )
-
-
-@pytest.fixture(autouse=True)
-def mock_pydantic_ai_output(monkeypatch) -> None:
-    """Default PydanticAI output for tests that enable LLM."""
-    monkeypatch.setattr(
-        DocumentationAgent,
-        "_run_pydantic_agent",
-        AsyncMock(return_value=build_doc_output()),
-    )
-
-
-@pytest.fixture
-def mock_evidence_bundle():
-    """Create a mock evidence bundle with documentation."""
-    return EvidenceBundle(
-        repository="test-repo",
-        git_evidence=[
-            Evidence(
-                source="git_file",
-                source_id="README.md",
-                title="README.md",
-                content="# Project Title\n\n## Installation\n\nRun pip install.\n\n## Usage\n\nRun main.py.",
-                content_hash="hash1",
-                status=EvidenceStatus.FOUND,
-            ),
-            Evidence(
-                source="git_file",
-                source_id="docs/other.md",
-                title="Other Doc",
-                content="Some content.",
-                content_hash="hash2",
-                status=EvidenceStatus.FOUND,
-            ),
-        ],
-        confluence_evidence=[
-            Evidence(
-                source="confluence_page",
-                source_id="12345",
-                title="Architecture",
-                content="<h1>Architecture</h1><p>Details about the system architecture and design patterns used in this project. This content needs to be long enough to bypass the heuristic length check.</p>",
-                content_hash="hash3",
-                status=EvidenceStatus.FOUND,
-                source_url="http://confluence/12345",
-            )
-        ],
-    )
-
-
-@pytest.fixture
-def mock_settings():
-    """Create mock settings for testing."""
-    settings = MagicMock()
-    settings.enabled = True
-    settings.model_standard = "test-model"
-    return settings
-
-
-class TestDocumentationAgentBasic:
-    """Basic tests for DocumentationAgent (existing tests)."""
-
-    @pytest.mark.asyncio
-    async def test_analyze_bundle_missing(self):
-        """Test handling of missing evidence bundle."""
-        agent = DocumentationAgent()
-        result = await agent.analyze({})
-        assert result.success is False
-        assert result.error and "Evidence bundle missing" in result.error
-
-    @pytest.mark.asyncio
-    async def test_analyze_heuristic(self, mock_evidence_bundle):
-        """Test heuristic analysis (no LLM)."""
-        # Ensure no LLM client
-        mock_settings = MagicMock()
-        mock_settings.enabled = False
-        agent = DocumentationAgent(settings=mock_settings)
-
-        result = await agent.analyze(mock_evidence_bundle)
-
-        assert result.success is True
-        findings = result.findings
-
-        # Check metadata counts
-        # Only README.md matches the filter (title starts with readme OR source_id ends with readme.md)
-        assert result.metadata["readme_count"] == 1
-        assert result.metadata["confluence_count"] == 1
-
-        # Check findings for README
-        # The sample README has Installation and Usage, but missing Configuration
-        completeness_findings = [
-            f for f in findings if f.get("dimension") == "completeness" and "README" in f.get("description", "")
-        ]
-        # Should detect missing sections in heuristic mode
-        assert len(completeness_findings) > 0
-        assert "configuration" in completeness_findings[0]["description"]
-
-    @pytest.mark.asyncio
-    async def test_analyze_heuristic_details(self):
-        """Test specific heuristic logic on a poor README."""
-        mock_settings = MagicMock()
-        mock_settings.enabled = False
-        agent = DocumentationAgent(settings=mock_settings)
-
-        bundle = EvidenceBundle(
-            repository="test",
-            git_evidence=[
-                Evidence(
-                    source="git_file",
-                    source_id="README.md",
-                    title="README.md",
-                    # Missing headings, has TODO
-                    content="Just some text without any headings structure. TODO: write more documentation here. This text must be longer than 50 characters to trigger analysis.",
-                    content_hash="h",
-                    status=EvidenceStatus.FOUND,
-                )
-            ],
-        )
-
-        result = await agent.analyze(bundle)
-        findings = result.findings
-
-        # Check structure finding (no headings)
-        structure = [f for f in findings if f.get("dimension") == "structure"]
-        assert len(structure) > 0
-        assert "lacks proper heading structure" in structure[0]["description"]
-
-        # Check currency finding (TODO)
-        currency = [f for f in findings if f.get("dimension") == "currency"]
-        assert len(currency) > 0
-        assert "outdated markers" in currency[0]["description"]
-
-    @pytest.mark.asyncio
-    async def test_analyze_llm(self, mock_evidence_bundle, mock_settings):
-        """Test LLM-based analysis."""
-
-        agent = DocumentationAgent(settings=mock_settings)
-        result = await agent.analyze(mock_evidence_bundle)
-
-        assert result.success is True
-        findings = result.findings
-
-        # Check for overall assessment finding
-        assessments = [f for f in findings if f.get("type") == "doc_quality_assessment"]
-        # Should have one for README and one for Confluence page
-        assert len(assessments) >= 2
-
-        # Check values for one of them
-        readme_assessment = next(f for f in assessments if "README" in f["description"])
-        assert readme_assessment["scores"]["overall"] == 0.85
-        assert readme_assessment["severity"] == "info"  # > 0.7
-
-
-class TestMultiDocumentScenarios:
-    """Test cases for multi-document scenarios."""
-
-    @pytest.mark.asyncio
-    async def test_multi_document_with_readme_contributing_license(self, mock_settings):
-        """Test analysis of multiple document types (README + CONTRIBUTING + LICENSE)."""
-
-        bundle = EvidenceBundle(
-            repository="test-repo",
-            git_evidence=[
-                Evidence(
-                    source="git_file",
-                    source_id="README.md",
-                    title="README.md",
-                    content="# My Project\n\n## Installation\n\npip install myproject\n\n## Usage\n\nmyproject --help\n\n## Configuration\n\nCreate config.yaml",
-                    content_hash="hash1",
-                    status=EvidenceStatus.FOUND,
-                ),
-                Evidence(
-                    source="git_file",
-                    source_id="CONTRIBUTING.md",
-                    title="CONTRIBUTING.md",
-                    content="# Contributing\n\n## Setup\n\ngit clone repo\n\n## Testing\n\npytest tests/",
-                    content_hash="hash2",
-                    status=EvidenceStatus.FOUND,
-                ),
-                Evidence(
-                    source="git_file",
-                    source_id="LICENSE",
-                    title="LICENSE",
-                    content="MIT License\n\nCopyright (c) 2026\n\nPermission is hereby granted...",
-                    content_hash="hash3",
-                    status=EvidenceStatus.FOUND,
-                ),
-            ],
-            confluence_evidence=[],
-        )
-
-        agent = DocumentationAgent(settings=mock_settings)
-        result = await agent.analyze(bundle)
-
-        assert result.success is True
-
-        assert result.metadata["readme_count"] == 1  # Only README.md matches the filter
-
-        # Check that README was analyzed
-        assessments = [f for f in result.findings if f.get("type") == "doc_quality_assessment"]
-        assert len(assessments) == 1  # Only README.md is counted as readme
-        assert "README" in assessments[0]["description"]
-
-    @pytest.mark.asyncio
-    async def test_multiple_readme_files(self, mock_settings):
-        """Test handling of multiple README files in different directories."""
-
-        bundle = EvidenceBundle(
-            repository="test-repo",
-            git_evidence=[
-                Evidence(
-                    source="git_file",
-                    source_id="README.md",
-                    title="README.md",
-                    content="# Root README\n\nMain project documentation.",
-                    content_hash="hash1",
-                    status=EvidenceStatus.FOUND,
-                ),
-                Evidence(
-                    source="git_file",
-                    source_id="docs/README.md",
-                    title="README.md",
-                    content="# Docs README\n\nDocumentation specific to the docs folder.",
-                    content_hash="hash2",
-                    status=EvidenceStatus.FOUND,
-                ),
-                Evidence(
-                    source="git_file",
-                    source_id="readme.md",
-                    title="readme.md",
-                    content="# Lowercase readme\n\nAnother readme file.",
-                    content_hash="hash3",
-                    status=EvidenceStatus.FOUND,
-                ),
-            ],
-            confluence_evidence=[],
-        )
-
-        agent = DocumentationAgent(settings=mock_settings)
-        result = await agent.analyze(bundle)
-
-        assert result.success is True
-        assert result.metadata["readme_count"] == 3  # All three match the filter
-
-    @pytest.mark.asyncio
-    async def test_multiple_confluence_pages(self, mock_settings):
-        """Test analysis of multiple Confluence pages."""
-
-        bundle = EvidenceBundle(
-            repository="test-repo",
-            git_evidence=[],
-            confluence_evidence=[
-                Evidence(
-                    source="confluence_page",
-                    source_id="12345",
-                    title="Architecture Overview",
-                    content="<h1>Architecture</h1><p>Detailed architecture documentation with sufficient content length to pass basic validation checks and trigger proper LLM analysis for quality assessment.</p>",
-                    content_hash="hash1",
-                    status=EvidenceStatus.FOUND,
-                    source_url="http://confluence/12345",
-                ),
-                Evidence(
-                    source="confluence_page",
-                    source_id="67890",
-                    title="API Documentation",
-                    content="<h1>API Reference</h1><p>Complete API documentation with endpoints, parameters, and examples that meet the minimum content requirements for thorough analysis.</p>",
-                    content_hash="hash2",
-                    status=EvidenceStatus.FOUND,
-                    source_url="http://confluence/67890",
-                ),
-            ],
-        )
-
-        agent = DocumentationAgent(settings=mock_settings)
-        result = await agent.analyze(bundle)
-
-        assert result.success is True
-        assert result.metadata["confluence_count"] == 2
-
-        # Check that both pages were analyzed
-        assessments = [f for f in result.findings if f.get("type") == "doc_quality_assessment"]
-        assert len(assessments) == 2
-
-    @pytest.mark.asyncio
-    async def test_mixed_git_and_confluence(self, mock_settings):
-        """Test analysis with both git documentation and Confluence pages."""
-
-        bundle = EvidenceBundle(
-            repository="test-repo",
-            git_evidence=[
-                Evidence(
-                    source="git_file",
-                    source_id="README.md",
-                    title="README.md",
-                    content="# Project\n\nComplete documentation for the project.",
-                    content_hash="hash1",
-                    status=EvidenceStatus.FOUND,
-                ),
-            ],
-            confluence_evidence=[
-                Evidence(
-                    source="confluence_page",
-                    source_id="12345",
-                    title="Architecture",
-                    content="<h1>Architecture</h1><p>Complete architecture documentation.</p>",
-                    content_hash="hash2",
-                    status=EvidenceStatus.FOUND,
-                    source_url="http://confluence/12345",
-                ),
-            ],
-        )
-
-        agent = DocumentationAgent(settings=mock_settings)
-        result = await agent.analyze(bundle)
-
-        assert result.success is True
-        assert result.metadata["readme_count"] == 1
-        assert result.metadata["confluence_count"] == 1
-
-        # Should have assessments for both
-        assessments = [f for f in result.findings if f.get("type") == "doc_quality_assessment"]
-        assert len(assessments) == 2
-
-
-class TestEmptyMissingDocumentation:
-    """Test cases for empty/missing documentation scenarios."""
-
-    @pytest.mark.asyncio
-    async def test_empty_readme_content(self, mock_settings):
-        """Test handling of README with empty content."""
-
-        bundle = EvidenceBundle(
-            repository="test-repo",
-            git_evidence=[
-                Evidence(
-                    source="git_file",
-                    source_id="README.md",
-                    title="README.md",
-                    content="",  # Empty content
-                    content_hash="hash1",
-                    status=EvidenceStatus.FOUND,
-                ),
-            ],
-            confluence_evidence=[],
-        )
-
-        agent = DocumentationAgent(settings=mock_settings)
-        result = await agent.analyze(bundle)
-
-        assert result.success is True
-
-        # Should have error finding for insufficient content
-        errors = [f for f in result.findings if f.get("severity") == "error"]
-        assert len(errors) > 0
-        assert "insufficient content" in errors[0]["description"]
-        assert errors[0]["dimension"] == "completeness"
-
-    @pytest.mark.asyncio
-    async def test_very_short_readme_content(self, mock_settings):
-        """Test handling of README with very short content (< 50 chars)."""
-
-        bundle = EvidenceBundle(
-            repository="test-repo",
-            git_evidence=[
-                Evidence(
-                    source="git_file",
-                    source_id="README.md",
-                    title="README.md",
-                    content="Short text",  # < 50 characters
-                    content_hash="hash1",
-                    status=EvidenceStatus.FOUND,
-                ),
-            ],
-            confluence_evidence=[],
-        )
-
-        agent = DocumentationAgent(settings=mock_settings)
-        result = await agent.analyze(bundle)
-
-        assert result.success is True
-
-        # Should have error finding for insufficient content
-        errors = [f for f in result.findings if f.get("severity") == "error"]
-        assert len(errors) > 0
-        assert "insufficient content" in errors[0]["description"]
-        assert "10 chars" in errors[0]["description"]
-
-    @pytest.mark.asyncio
-    async def test_no_documentation_at_all(self):
-        """Test handling of bundle with no documentation."""
-        agent = DocumentationAgent()
-
-        bundle = EvidenceBundle(
-            repository="test-repo",
-            git_evidence=[],
-            confluence_evidence=[],
-        )
-
-        result = await agent.analyze(bundle)
-
-        assert result.success is True
-        assert result.metadata["readme_count"] == 0
-        assert result.metadata["confluence_count"] == 0
-        assert len(result.findings) == 0
-
-    @pytest.mark.asyncio
-    async def test_confluence_page_too_short(self, mock_settings):
-        """Test handling of Confluence page with insufficient content."""
-
-        bundle = EvidenceBundle(
-            repository="test-repo",
-            git_evidence=[],
-            confluence_evidence=[
-                Evidence(
-                    source="confluence_page",
-                    source_id="12345",
-                    title="Short Page",
-                    content="<p>Short</p>",  # < 100 characters
-                    content_hash="hash1",
-                    status=EvidenceStatus.FOUND,
-                    source_url="http://confluence/12345",
-                ),
-            ],
-        )
-
-        agent = DocumentationAgent(settings=mock_settings)
-        result = await agent.analyze(bundle)
-
-        assert result.success is True
-
-        # Should have warning for short content
-        warnings = [f for f in result.findings if f.get("severity") == "warning"]
-        assert len(warnings) > 0
-        assert "too short" in warnings[0]["description"]
-
-
-class TestLLMTimeoutAndErrorHandling:
-    """Test cases for LLM timeout and error handling."""
-
-    @pytest.mark.asyncio
-    async def test_llm_timeout_fallback_to_heuristic(self, mock_settings):
-        """Test that LLM timeout falls back to heuristic analysis."""
-        bundle = EvidenceBundle(
-            repository="test-repo",
-            git_evidence=[
-                Evidence(
-                    source="git_file",
-                    source_id="README.md",
-                    title="README.md",
-                    content="# Project\n\nDocumentation without install guide or usage instructions. Need more content.",
-                    content_hash="hash1",
-                    status=EvidenceStatus.FOUND,
-                ),
-            ],
-            confluence_evidence=[],
-        )
-
-        agent = DocumentationAgent(settings=mock_settings)
-        agent._run_pydantic_agent = AsyncMock(side_effect=TimeoutError("LLM request timed out"))
-        result = await agent.analyze(bundle)
-
-        assert result.success is True
-
-        # Should have heuristic findings as fallback
-        findings = result.findings
-        assert len(findings) > 0
-
-        # Check that heuristic analysis detected missing sections
-        # The content lacks "installation" and "usage" keywords, so both should be detected
-        completeness = [f for f in findings if f.get("dimension") == "completeness"]
-        assert len(completeness) > 0
-        # The heuristic checks for "installation", "usage", "configuration"
-        # Since content lacks these, it should report missing sections
-        assert (
-            "missing" in completeness[0]["description"].lower()
-            or "installation" in completeness[0]["description"].lower()
-        )
-
-    @pytest.mark.asyncio
-    async def test_llm_generic_exception_fallback(self, mock_settings):
-        """Test that generic LLM exceptions fall back to heuristic analysis."""
-        bundle = EvidenceBundle(
-            repository="test-repo",
-            git_evidence=[
-                Evidence(
-                    source="git_file",
-                    source_id="README.md",
-                    title="README.md",
-                    content="# Project\n\nTODO: Add proper documentation",
-                    content_hash="hash1",
-                    status=EvidenceStatus.FOUND,
-                ),
-            ],
-            confluence_evidence=[],
-        )
-
-        agent = DocumentationAgent(settings=mock_settings)
-        agent._run_pydantic_agent = AsyncMock(side_effect=RuntimeError("LLM service unavailable"))
-        result = await agent.analyze(bundle)
-
-        assert result.success is True
-
-        # Should have heuristic findings as fallback
-        findings = result.findings
-        assert len(findings) > 0
-
-    @pytest.mark.asyncio
-    async def test_llm_json_parse_error_fallback(self, mock_settings):
-        """Test that invalid JSON from LLM falls back to heuristic analysis."""
-        bundle = EvidenceBundle(
-            repository="test-repo",
-            git_evidence=[
-                Evidence(
-                    source="git_file",
-                    source_id="README.md",
-                    title="README.md",
-                    content="# Project\n\nDocumentation content here that is long enough to pass the fifty character minimum threshold.",
-                    content_hash="hash1",
-                    status=EvidenceStatus.FOUND,
-                ),
-            ],
-            confluence_evidence=[],
-        )
-
-        agent = DocumentationAgent(settings=mock_settings)
-        agent._run_pydantic_agent = AsyncMock(side_effect=ValueError("Invalid LLM output"))
-        result = await agent.analyze(bundle)
-
-        # Should catch JSON error and fall back to heuristic analysis
-        assert result.success is True
-
-        # Should have heuristic findings as fallback
-        findings = result.findings
-        # The heuristic analysis should find missing sections since content lacks required keywords
-        completeness_findings = [f for f in findings if f.get("dimension") == "completeness"]
-        assert len(completeness_findings) > 0
-
-    @pytest.mark.asyncio
-    async def test_llm_malformed_json_response(self, mock_settings):
-        """Test handling of malformed JSON response from LLM."""
-        bundle = EvidenceBundle(
-            repository="test-repo",
-            git_evidence=[
-                Evidence(
-                    source="git_file",
-                    source_id="README.md",
-                    title="README.md",
-                    content="# Project\n\nValid content that is long enough to pass the fifty character minimum threshold.",
-                    content_hash="hash1",
-                    status=EvidenceStatus.FOUND,
-                ),
-            ],
-            confluence_evidence=[],
-        )
-
-        agent = DocumentationAgent(settings=mock_settings)
-        agent._run_pydantic_agent = AsyncMock(side_effect=ValueError("Malformed LLM output"))
-        result = await agent.analyze(bundle)
-
-        # Should catch JSON error and fall back to heuristic analysis
-        assert result.success is True
-
-        # Should have heuristic findings as fallback
-        findings = result.findings
-        assert len(findings) > 0
-
-
-class TestConfluenceIntegrationFailures:
-    """Test cases for Confluence integration failures."""
-
-    @pytest.mark.asyncio
-    async def test_confluence_page_without_source_url(self, mock_settings):
-        """Test handling of Confluence page missing source_url."""
-
-        bundle = EvidenceBundle(
-            repository="test-repo",
-            git_evidence=[],
-            confluence_evidence=[
-                Evidence(
-                    source="confluence_page",
-                    source_id="12345",
-                    title="Architecture",
-                    content="<h1>Architecture</h1><p>Complete architecture documentation.</p>",
-                    content_hash="hash1",
-                    status=EvidenceStatus.FOUND,
-                    # source_url is missing
-                ),
-            ],
-        )
-
-        agent = DocumentationAgent(settings=mock_settings)
-        result = await agent.analyze(bundle)
-
-        assert result.success is True
-
-        # Should still work, using source_id as location
-        assessments = [f for f in result.findings if f.get("type") == "doc_quality_assessment"]
-        assert len(assessments) == 1
-        assert assessments[0]["location"] == "12345"  # source_id used as fallback
-
-    @pytest.mark.asyncio
-    async def test_confluence_page_with_html_content(self, mock_settings):
-        """Test handling of Confluence page with HTML content."""
-
-        bundle = EvidenceBundle(
-            repository="test-repo",
-            git_evidence=[],
-            confluence_evidence=[
-                Evidence(
-                    source="confluence_page",
-                    source_id="12345",
-                    title="API Docs",
-                    content="<h1>API Documentation</h1><p>This page contains <strong>HTML</strong> content with <em>formatting</em>.</p><ul><li>Item 1</li><li>Item 2</li></ul>",
-                    content_hash="hash1",
-                    status=EvidenceStatus.FOUND,
-                    source_url="http://confluence/12345",
-                ),
-            ],
-        )
-
-        agent = DocumentationAgent(settings=mock_settings)
-        result = await agent.analyze(bundle)
-
-        assert result.success is True
-        assert result.metadata["confluence_count"] == 1
-
-    @pytest.mark.asyncio
-    async def test_confluence_markdown_wrapped_response(self, mock_settings):
-        """Test handling of Confluence content that's markdown-wrapped."""
-
-        bundle = EvidenceBundle(
-            repository="test-repo",
-            git_evidence=[],
-            confluence_evidence=[
-                Evidence(
-                    source="confluence_page",
-                    source_id="12345",
-                    title="Architecture",
-                    content="<h1>Architecture</h1><p>Complete documentation.</p>",
-                    content_hash="hash1",
-                    status=EvidenceStatus.FOUND,
-                    source_url="http://confluence/12345",
-                ),
-            ],
-        )
-
-        agent = DocumentationAgent(settings=mock_settings)
-        agent._run_pydantic_agent = AsyncMock(return_value=build_doc_output(0.75))
-        result = await agent.analyze(bundle)
-
-        assert result.success is True
-        assessments = [f for f in result.findings if f.get("type") == "doc_quality_assessment"]
-        assert len(assessments) == 1
-        assert assessments[0]["scores"]["overall"] == 0.75
-
-
-class TestLargeReadmeContent:
-    """Test cases for large README content handling."""
-
-    @pytest.mark.asyncio
-    async def test_large_readme_truncation(self, mock_settings):
-        """Test that large README content is truncated for LLM analysis."""
-
-        # Create content larger than 8000 characters
-        large_content = "# Large README\n\n" + "## Section\n\n" + "Content line.\n" * 1000
-
-        bundle = EvidenceBundle(
-            repository="test-repo",
-            git_evidence=[
-                Evidence(
-                    source="git_file",
-                    source_id="README.md",
-                    title="README.md",
-                    content=large_content,
-                    content_hash="hash1",
-                    status=EvidenceStatus.FOUND,
-                ),
-            ],
-            confluence_evidence=[],
-        )
-
-        agent = DocumentationAgent(settings=mock_settings)
-        result = await agent.analyze(bundle)
-
-        assert result.success is True
-        assert result.metadata["readme_count"] == 1
-
-    @pytest.mark.asyncio
-    async def test_readme_exactly_8000_chars(self, mock_settings):
-        """Test README with exactly 8000 characters (boundary case)."""
-
-        # Create content exactly 8000 characters
-        # "# Boundary Test\n\n" is 17 characters, so we need 7983 more
-        base_content = "# Boundary Test\n\n" + "x" * 7983
-        assert len(base_content) == 8000
-
-        bundle = EvidenceBundle(
-            repository="test-repo",
-            git_evidence=[
-                Evidence(
-                    source="git_file",
-                    source_id="README.md",
-                    title="README.md",
-                    content=base_content,
-                    content_hash="hash1",
-                    status=EvidenceStatus.FOUND,
-                ),
-            ],
-            confluence_evidence=[],
-        )
-
-        agent = DocumentationAgent(settings=mock_settings)
-        result = await agent.analyze(bundle)
-
-        assert result.success is True
-
-    @pytest.mark.asyncio
-    async def test_readme_over_8000_chars(self, mock_settings):
-        """Test README with over 8000 characters should be truncated."""
-
-        # Create content over 8000 characters
-        large_content = "# Large README\n\n" + "x" * 10000
-        initial_length = len(large_content)
-        assert initial_length > 8000
-
-        bundle = EvidenceBundle(
-            repository="test-repo",
-            git_evidence=[
-                Evidence(
-                    source="git_file",
-                    source_id="README.md",
-                    title="README.md",
-                    content=large_content,
-                    content_hash="hash1",
-                    status=EvidenceStatus.FOUND,
-                ),
-            ],
-            confluence_evidence=[],
-        )
-
-        agent = DocumentationAgent(settings=mock_settings)
-        result = await agent.analyze(bundle)
-
-        assert result.success is True
-        # The truncation happens in _llm_analyze_quality
-        # We can't directly test the truncated content length, but we verify it works
-
-    @pytest.mark.asyncio
-    async def test_multiple_large_documents(self, mock_settings):
-        """Test handling multiple large documents."""
-
-        # Create large content for multiple files
-        large_content = "# Large Document\n\n" + "Content.\n" * 2000
-
-        bundle = EvidenceBundle(
-            repository="test-repo",
-            git_evidence=[
-                Evidence(
-                    source="git_file",
-                    source_id="README.md",
-                    title="README.md",
-                    content=large_content,
-                    content_hash="hash1",
-                    status=EvidenceStatus.FOUND,
-                ),
-                Evidence(
-                    source="git_file",
-                    source_id="docs/README.md",
-                    title="README.md",
-                    content=large_content,
-                    content_hash="hash2",
-                    status=EvidenceStatus.FOUND,
-                ),
-            ],
-            confluence_evidence=[
-                Evidence(
-                    source="confluence_page",
-                    source_id="12345",
-                    title="Architecture",
-                    content="<h1>Architecture</h1>" + "<p>Content.</p>" * 1000,
-                    content_hash="hash3",
-                    status=EvidenceStatus.FOUND,
-                    source_url="http://confluence/12345",
-                ),
-            ],
-        )
-
-        agent = DocumentationAgent(settings=mock_settings)
-        result = await agent.analyze(bundle)
-
-        assert result.success is True
-        assert result.metadata["readme_count"] == 2
-        assert result.metadata["confluence_count"] == 1
-
-
-class TestDocumentationQualityScores:
-    """Test cases for different documentation quality scores."""
-
-    @pytest.mark.asyncio
-    async def test_high_quality_score(self, mock_settings):
-        """Test documentation with high quality score (> 0.7)."""
-        bundle = EvidenceBundle(
-            repository="test-repo",
-            git_evidence=[
-                Evidence(
-                    source="git_file",
-                    source_id="README.md",
-                    title="README.md",
-                    content="# Excellent Project\n\nComplete documentation that is long enough to pass the fifty character minimum.",
-                    content_hash="hash1",
-                    status=EvidenceStatus.FOUND,
-                ),
-            ],
-            confluence_evidence=[],
-        )
-
-        agent = DocumentationAgent(settings=mock_settings)
-        agent._run_pydantic_agent = AsyncMock(return_value=build_doc_output(0.92))
-        result = await agent.analyze(bundle)
-
-        assert result.success is True
-
-        assessments = [f for f in result.findings if f.get("type") == "doc_quality_assessment"]
-        assert len(assessments) == 1
-        assert assessments[0]["severity"] == "info"  # High score = info
-        assert assessments[0]["scores"]["overall"] == 0.92
-
-    @pytest.mark.asyncio
-    async def test_medium_quality_score(self, mock_settings):
-        """Test documentation with medium quality score (0.4 - 0.7)."""
-        bundle = EvidenceBundle(
-            repository="test-repo",
-            git_evidence=[
-                Evidence(
-                    source="git_file",
-                    source_id="README.md",
-                    title="README.md",
-                    content="# Average Project\n\nSome documentation that is long enough to pass the fifty character minimum.",
-                    content_hash="hash1",
-                    status=EvidenceStatus.FOUND,
-                ),
-            ],
-            confluence_evidence=[],
-        )
-
-        agent = DocumentationAgent(settings=mock_settings)
-        agent._run_pydantic_agent = AsyncMock(return_value=build_doc_output(0.55))
-        result = await agent.analyze(bundle)
-
-        assert result.success is True
-
-        assessments = [f for f in result.findings if f.get("type") == "doc_quality_assessment"]
-        assert len(assessments) == 1
-        assert assessments[0]["severity"] == "warning"  # Medium score = warning
-        assert assessments[0]["scores"]["overall"] == 0.55
-
-    @pytest.mark.asyncio
-    async def test_low_quality_score(self, mock_settings):
-        """Test documentation with low quality score (< 0.4)."""
-        bundle = EvidenceBundle(
-            repository="test-repo",
-            git_evidence=[
-                Evidence(
-                    source="git_file",
-                    source_id="README.md",
-                    title="README.md",
-                    content="Bad docs but this content is long enough to pass the fifty character minimum threshold.",
-                    content_hash="hash1",
-                    status=EvidenceStatus.FOUND,
-                ),
-            ],
-            confluence_evidence=[],
-        )
-
-        agent = DocumentationAgent(settings=mock_settings)
-        agent._run_pydantic_agent = AsyncMock(return_value=build_doc_output(0.25))
-        result = await agent.analyze(bundle)
-
-        assert result.success is True
-
-        assessments = [f for f in result.findings if f.get("type") == "doc_quality_assessment"]
-        assert len(assessments) == 1
-        assert assessments[0]["severity"] == "error"  # Low score = error
-        assert assessments[0]["scores"]["overall"] == 0.25
-
-    @pytest.mark.asyncio
-    async def test_dimension_specific_low_scores(self, mock_settings):
-        """Test that low dimension scores generate specific findings."""
-        dimension_output = DocumentationQualityOutput(
-            completeness=DocumentationDimension(
-                score=0.3,
-                missing_sections=["API docs"],
-                notes="Missing key sections",
-            ),
-            clarity=DocumentationDimension(
-                score=0.4,
-                issues=["Technical jargon"],
-                notes="Too technical",
-            ),
-            currency=DocumentationDimension(
-                score=0.3,
-                outdated_indicators=["deprecated"],
-                notes="Old references",
-            ),
-            structure=DocumentationDimension(
-                score=0.7,
-                notes="",
-            ),
-            overall_score=0.6,
-            summary="Mixed quality",
-            recommendations=["Improve completeness", "Clarify language"],
-        )
-
-        bundle = EvidenceBundle(
-            repository="test-repo",
-            git_evidence=[
-                Evidence(
-                    source="git_file",
-                    source_id="README.md",
-                    title="README.md",
-                    content="# Project\n\nContent here that is long enough to pass the fifty character minimum threshold for analysis.",
-                    content_hash="hash1",
-                    status=EvidenceStatus.FOUND,
-                ),
-            ],
-            confluence_evidence=[],
-        )
-
-        agent = DocumentationAgent(settings=mock_settings)
-        agent._run_pydantic_agent = AsyncMock(return_value=dimension_output)
-        result = await agent.analyze(bundle)
-
-        assert result.success is True
-
-        # Check for dimension-specific findings (scores < 0.5)
-        dimension_findings = [f for f in result.findings if f.get("type") == "doc_quality" and f.get("dimension")]
-        assert len(dimension_findings) >= 3  # At least completeness, clarity, currency
-
-        dimensions = {f["dimension"] for f in dimension_findings}
-        assert "completeness" in dimensions
-        assert "clarity" in dimensions
-        assert "currency" in dimensions
-
-
-class TestCrossReferenceValidation:
-    """Test cases for cross-reference validation between documents."""
-
-    @pytest.mark.asyncio
-    async def test_cross_reference_between_readme_and_confluence(self, mock_settings):
-        """Test cross-references between README and Confluence documentation."""
-
-        # README references Confluence
-        readme_content = """# Project
-
-See [Architecture Documentation](http://confluence/12345) for details.
-
-## Installation
-
-Run setup script.
-"""
-
-        bundle = EvidenceBundle(
-            repository="test-repo",
-            git_evidence=[
-                Evidence(
-                    source="git_file",
-                    source_id="README.md",
-                    title="README.md",
-                    content=readme_content,
-                    content_hash="hash1",
-                    status=EvidenceStatus.FOUND,
-                ),
-            ],
-            confluence_evidence=[
-                Evidence(
-                    source="confluence_page",
-                    source_id="12345",
-                    title="Architecture",
-                    content="<h1>Architecture</h1><p>Detailed architecture documentation with cross-references to other pages and sufficient content length for analysis.</p>",
-                    content_hash="hash2",
-                    status=EvidenceStatus.FOUND,
-                    source_url="http://confluence/12345",
-                ),
-            ],
-        )
-
-        agent = DocumentationAgent(settings=mock_settings)
-        result = await agent.analyze(bundle)
-
-        assert result.success is True
-        assert result.metadata["readme_count"] == 1
-        assert result.metadata["confluence_count"] == 1
-
-    @pytest.mark.asyncio
-    async def test_consistency_checks_across_docs(self, mock_settings):
-        """Test consistency checking across multiple documentation files."""
-
-        bundle = EvidenceBundle(
-            repository="test-repo",
-            git_evidence=[
-                Evidence(
-                    source="git_file",
-                    source_id="README.md",
-                    title="README.md",
-                    content="# Project v1.0\n\nInstallation instructions.",
-                    content_hash="hash1",
-                    status=EvidenceStatus.FOUND,
-                ),
-                Evidence(
-                    source="git_file",
-                    source_id="CHANGELOG.md",
-                    title="CHANGELOG.md",
-                    content="# Changelog\n\n## v1.0\n\nInitial release.",
-                    content_hash="hash2",
-                    status=EvidenceStatus.FOUND,
-                ),
-            ],
-            confluence_evidence=[],
-        )
-
-        agent = DocumentationAgent(settings=mock_settings)
-        result = await agent.analyze(bundle)
-
-        assert result.success is True
-        # Only README is counted, but CHANGELOG is still in git_evidence
-        assert result.metadata["readme_count"] == 1
-
-    @pytest.mark.asyncio
-    async def test_related_document_detection(self, mock_settings):
-        """Test detection of related documentation files."""
-
-        bundle = EvidenceBundle(
-            repository="test-repo",
-            git_evidence=[
-                Evidence(
-                    source="git_file",
-                    source_id="README.md",
-                    title="README.md",
-                    content="# Project\n\nSee CONTRIBUTING.md for contribution guidelines.",
-                    content_hash="hash1",
-                    status=EvidenceStatus.FOUND,
-                ),
-                Evidence(
-                    source="git_file",
-                    source_id="CONTRIBUTING.md",
-                    title="CONTRIBUTING.md",
-                    content="# Contributing\n\nHow to contribute.",
-                    content_hash="hash2",
-                    status=EvidenceStatus.FOUND,
-                ),
-                Evidence(
-                    source="git_file",
-                    source_id="LICENSE",
-                    title="LICENSE",
-                    content="MIT License",
-                    content_hash="hash3",
-                    status=EvidenceStatus.FOUND,
-                ),
-            ],
-            confluence_evidence=[],
-        )
-
-        agent = DocumentationAgent(settings=mock_settings)
-        result = await agent.analyze(bundle)
-
-        assert result.success is True
-        # Only README.md is counted
-        assert result.metadata["readme_count"] == 1
-
-
-class TestVariousDocTypesAndSources:
-    """Test cases for various doc_types and source combinations."""
-
-    @pytest.mark.asyncio
-    async def test_readme_doc_type(self, mock_settings):
-        """Test README doc type specifically."""
-
-        bundle = EvidenceBundle(
-            repository="test-repo",
-            git_evidence=[
-                Evidence(
-                    source="git_file",
-                    source_id="README.md",
-                    title="README.md",
-                    content="# Project\n\nComplete README",
-                    content_hash="hash1",
-                    status=EvidenceStatus.FOUND,
-                ),
-            ],
-            confluence_evidence=[],
-        )
-
-        agent = DocumentationAgent(settings=mock_settings)
-        result = await agent.analyze(bundle)
-
-        assert result.success is True
-        assert result.metadata["readme_count"] == 1
-
-    @pytest.mark.asyncio
-    async def test_confluence_doc_type(self, mock_settings):
-        """Test Confluence doc type specifically."""
-
-        bundle = EvidenceBundle(
-            repository="test-repo",
-            git_evidence=[],
-            confluence_evidence=[
-                Evidence(
-                    source="confluence_page",
-                    source_id="12345",
-                    title="Architecture",
-                    content="<h1>Architecture</h1><p>Complete documentation.</p>",
-                    content_hash="hash1",
-                    status=EvidenceStatus.FOUND,
-                    source_url="http://confluence/12345",
-                ),
-            ],
-        )
-
-        agent = DocumentationAgent(settings=mock_settings)
-        result = await agent.analyze(bundle)
-
-        assert result.success is True
-        assert result.metadata["confluence_count"] == 1
-
-    @pytest.mark.asyncio
-    async def test_non_readme_git_files_excluded(self, mock_settings):
-        """Test that non-README git files are excluded from README count."""
-
-        bundle = EvidenceBundle(
-            repository="test-repo",
-            git_evidence=[
-                Evidence(
-                    source="git_file",
-                    source_id="docs/guide.md",
-                    title="User Guide",
-                    content="# User Guide\n\nComplete documentation",
-                    content_hash="hash1",
-                    status=EvidenceStatus.FOUND,
-                ),
-                Evidence(
-                    source="git_file",
-                    source_id="CHANGELOG.md",
-                    title="CHANGELOG.md",
-                    content="# Changelog",
-                    content_hash="hash2",
-                    status=EvidenceStatus.FOUND,
-                ),
-                Evidence(
-                    source="git_file",
-                    source_id="README.md",
-                    title="README.md",
-                    content="# README",
-                    content_hash="hash3",
-                    status=EvidenceStatus.FOUND,
-                ),
-            ],
-            confluence_evidence=[],
-        )
-
-        agent = DocumentationAgent(settings=mock_settings)
-        result = await agent.analyze(bundle)
-
-        assert result.success is True
-        # Only README.md should be counted
-        assert result.metadata["readme_count"] == 1
-
-    @pytest.mark.asyncio
-    async def test_mixed_sources_with_various_status(self, mock_settings):
-        """Test handling of various evidence statuses."""
-
-        bundle = EvidenceBundle(
-            repository="test-repo",
-            git_evidence=[
-                Evidence(
-                    source="git_file",
-                    source_id="README.md",
-                    title="README.md",
-                    content="# Project\n\nDocumentation",
-                    content_hash="hash1",
-                    status=EvidenceStatus.FOUND,
-                ),
-                Evidence(
-                    source="git_file",
-                    source_id="docs/README.md",
-                    title="README.md",
-                    content="# Docs",
-                    content_hash="hash2",
-                    status=EvidenceStatus.MISSING,  # Should still be analyzed if content exists
-                ),
-            ],
-            confluence_evidence=[
-                Evidence(
-                    source="confluence_page",
-                    source_id="12345",
-                    title="Architecture",
-                    content="<h1>Architecture</h1><p>Content</p>",
-                    content_hash="hash3",
-                    status=EvidenceStatus.FOUND,
-                    source_url="http://confluence/12345",
-                ),
-            ],
-        )
-
-        agent = DocumentationAgent(settings=mock_settings)
-        result = await agent.analyze(bundle)
-
-        assert result.success is True
-        assert result.metadata["readme_count"] == 2  # Both README files counted regardless of status
-
-    @pytest.mark.asyncio
-    async def test_case_insensitive_readme_detection(self, mock_settings):
-        """Test that README detection is case-insensitive."""
-
-        bundle = EvidenceBundle(
-            repository="test-repo",
-            git_evidence=[
-                Evidence(
-                    source="git_file",
-                    source_id="README.md",
-                    title="README.md",
-                    content="# Project 1",
-                    content_hash="hash1",
-                    status=EvidenceStatus.FOUND,
-                ),
-                Evidence(
-                    source="git_file",
-                    source_id="readme.md",
-                    title="readme.md",
-                    content="# Project 2",
-                    content_hash="hash2",
-                    status=EvidenceStatus.FOUND,
-                ),
-                Evidence(
-                    source="git_file",
-                    source_id="ReadMe.md",
-                    title="ReadMe.md",
-                    content="# Project 3",
-                    content_hash="hash3",
-                    status=EvidenceStatus.FOUND,
-                ),
-            ],
-            confluence_evidence=[],
-        )
-
-        agent = DocumentationAgent(settings=mock_settings)
-        result = await agent.analyze(bundle)
-
-        assert result.success is True
-        # All should be detected (lowercase title starts with "readme" or source_id ends with "readme.md")
-        assert result.metadata["readme_count"] == 3
-
-    @pytest.mark.asyncio
-    async def test_readme_in_subdirectory(self, mock_settings):
-        """Test README files in subdirectories."""
-
-        bundle = EvidenceBundle(
-            repository="test-repo",
-            git_evidence=[
-                Evidence(
-                    source="git_file",
-                    source_id="src/README.md",
-                    title="README.md",
-                    content="# Source README",
-                    content_hash="hash1",
-                    status=EvidenceStatus.FOUND,
-                ),
-                Evidence(
-                    source="git_file",
-                    source_id="docs/guides/README.md",
-                    title="README.md",
-                    content="# Guides README",
-                    content_hash="hash2",
-                    status=EvidenceStatus.FOUND,
-                ),
-            ],
-            confluence_evidence=[],
-        )
-
-        agent = DocumentationAgent(settings=mock_settings)
-        result = await agent.analyze(bundle)
-
-        assert result.success is True
-        assert result.metadata["readme_count"] == 2
-
-
-class TestEdgeCases:
-    """Additional edge case tests."""
-
-    @pytest.mark.asyncio
-    async def test_evidence_bundle_dict_with_evidence_key(self):
-        """Test evidence bundle passed as dict with 'evidence' key."""
-        agent = DocumentationAgent()
-
-        bundle_data = {
-            "evidence": EvidenceBundle(
-                repository="test-repo",
-                git_evidence=[],
-                confluence_evidence=[],
-            ),
-        }
-
-        result = await agent.analyze(bundle_data)
-
-        assert result.success is True
-
-    @pytest.mark.asyncio
-    async def test_evidence_bundle_dict_with_evidence_bundle_key(self):
-        """Test evidence bundle passed as dict with 'evidence_bundle' key."""
-        agent = DocumentationAgent()
-
-        bundle_data = {
-            "evidence_bundle": EvidenceBundle(
-                repository="test-repo",
-                git_evidence=[],
-                confluence_evidence=[],
-            ),
-        }
-
-        result = await agent.analyze(bundle_data)
-
-        assert result.success is True
-
-    @pytest.mark.asyncio
-    async def test_llm_disabled_settings(self, mock_settings):
-        """Test with LLM explicitly disabled in settings."""
-        mock_settings.enabled = False
-
-        bundle = EvidenceBundle(
-            repository="test-repo",
-            git_evidence=[
-                Evidence(
-                    source="git_file",
-                    source_id="README.md",
-                    title="README.md",
-                    content="# Project\n\nInstallation and usage docs here.",
-                    content_hash="hash1",
-                    status=EvidenceStatus.FOUND,
-                ),
-            ],
-            confluence_evidence=[],
-        )
-
-        agent = DocumentationAgent(settings=mock_settings)
-        result = await agent.analyze(bundle)
-
-        assert result.success is True
-        assert result.metadata["llm_enabled"] is False
-
-    @pytest.mark.asyncio
-    async def test_special_characters_in_content(self, mock_settings):
-        """Test handling of special characters in documentation content."""
-
-        content = """# Project
-
-## Installation
-
-Run: `pip install package==1.0.0`
-
-## Configuration
-
-Edit `config.json`:
-
-```json
-{
-  "key": "value",
-  "nested": {
-    "array": [1, 2, 3]
-  }
-}
-```
-
-## Usage
-
-```bash
-$ command --option value
-```
-
-Special chars: < > & " ' © ® ™
-"""
-
-        bundle = EvidenceBundle(
-            repository="test-repo",
-            git_evidence=[
-                Evidence(
-                    source="git_file",
-                    source_id="README.md",
-                    title="README.md",
-                    content=content,
-                    content_hash="hash1",
-                    status=EvidenceStatus.FOUND,
-                ),
-            ],
-            confluence_evidence=[],
-        )
-
-        agent = DocumentationAgent(settings=mock_settings)
-        result = await agent.analyze(bundle)
-
-        assert result.success is True
-
-    @pytest.mark.asyncio
-    async def test_unicode_content(self, mock_settings):
-        """Test handling of unicode characters in content."""
-
-        content = """# 多语言项目
-
-## 日本語サポート
-
-このプロジェクトは日本語をサポートしています。
-
-## 中文支持
-
-此项目支持中文。
-
-## 한국어 지원
-
-이 프로젝트는 한국어를 지원합니다.
-
-## Arabic
-
-دعم اللغة العربية.
-
-## Emoji Support
-
-✨ 🚀 🎉 ⭐ 💻
-"""
-
-        bundle = EvidenceBundle(
-            repository="test-repo",
-            git_evidence=[
-                Evidence(
-                    source="git_file",
-                    source_id="README.md",
-                    title="README.md",
-                    content=content,
-                    content_hash="hash1",
-                    status=EvidenceStatus.FOUND,
-                ),
-            ],
-            confluence_evidence=[],
-        )
-
-        agent = DocumentationAgent(settings=mock_settings)
-        result = await agent.analyze(bundle)
-
-        assert result.success is True
-
-
-@pytest.mark.asyncio
-async def test_docs_analysis_passes_toolsets_to_pydantic_agent(monkeypatch, mock_settings):
-    """Docs analysis should forward configured toolsets to _run_pydantic_agent."""
-    bundle = EvidenceBundle(
-        repository="test-repo",
-        git_evidence=[
-            Evidence(
-                source="git_file",
-                source_id="README.md",
-                title="README.md",
-                content="# Title\n\nUsage docs.",
-                content_hash="hash-readme",
-                status=EvidenceStatus.FOUND,
-            )
-        ],
-        confluence_evidence=[],
-    )
-    agent = DocumentationAgent(settings=mock_settings)
-    monkeypatch.setattr(agent, "_build_analysis_toolsets", lambda: ["toolset-docs"])
-    run_mock = AsyncMock(return_value=build_doc_output(0.7))
-    monkeypatch.setattr(agent, "_run_pydantic_agent", run_mock)
-
-    result = await agent.analyze(bundle)
-
-    assert result.success is True
-    assert run_mock.await_args.kwargs["toolsets"] == ["toolset-docs"]
-    assert run_mock.await_args.kwargs["max_tool_calls"] is None
-    assert "Use TOOL-FIRST analysis when tools are available" in run_mock.await_args.kwargs["user_prompt"]
-
-
-@pytest.mark.asyncio
-async def test_docs_analysis_evidence_first_when_tools_unavailable(monkeypatch, mock_settings):
-    """Docs analysis should keep evidence-first guidance even when toolsets are unavailable."""
-    bundle = EvidenceBundle(
-        repository="test-repo",
-        git_evidence=[
-            Evidence(
-                source="git_file",
-                source_id="README.md",
-                title="README.md",
-                content="# Title\n\nUsage docs.",
-                content_hash="hash-readme",
-                status=EvidenceStatus.FOUND,
-            )
-        ],
-        confluence_evidence=[],
-    )
-    agent = DocumentationAgent(settings=mock_settings)
-    monkeypatch.setattr(agent, "_build_analysis_toolsets", lambda: [])
-    run_mock = AsyncMock(return_value=build_doc_output(0.7))
-    monkeypatch.setattr(agent, "_run_pydantic_agent", run_mock)
-
-    result = await agent.analyze(bundle)
-
-    assert result.success is True
-    assert run_mock.await_args.kwargs["toolsets"] == []
-    assert run_mock.await_args.kwargs["max_tool_calls"] == 0
-    assert "Use TOOL-FIRST analysis when tools are available" in run_mock.await_args.kwargs["user_prompt"]
-
-
-@pytest.mark.asyncio
-async def test_docs_analysis_retries_after_invalid_tool_with_allowlist_prompt(monkeypatch, mock_settings):
-    """Invalid tool usage should trigger one allowlist-guided retry."""
-    bundle = EvidenceBundle(
-        repository="test-repo",
-        git_evidence=[
-            Evidence(
-                source="git_file",
-                source_id="README.md",
-                title="README.md",
-                content="# Title\n\nUsage docs.",
-                content_hash="hash-readme",
-                status=EvidenceStatus.FOUND,
-            )
-        ],
-        confluence_evidence=[],
-    )
-    agent = DocumentationAgent(settings=mock_settings)
-    monkeypatch.setattr(agent, "_build_analysis_toolsets", lambda: ["toolset-docs"])
-    monkeypatch.setattr(
-        agent,
-        "_resolve_tool_policy",
-        lambda: (["search_evidence", "read_evidence_document"], {}),
-    )
-    run_prompts: list[str] = []
-    expected = DocFindings(
-        readme_score=7.0,
-        confluence_score=0.0,
-        api_docs_score=0.0,
-        notes=["README content reviewed", "Usage guidance present"],
-        confidence=0.8,
-        missing_sections=["configuration"],
-        strengths=["Basic usage section exists"],
-        recommendations=["Add setup prerequisites", "Add troubleshooting"],
-    )
-
-    async def _fake_run(**kwargs):
-        run_prompts.append(kwargs["user_prompt"])
-        if len(run_prompts) == 1:
-            raise RuntimeError("Tool 'run_shell' not allowed for this session")
-        agent._last_agent_run_telemetry = {"event_tool_count_by_name": {"read_evidence_document": 1}}
-        return expected
-
-    monkeypatch.setattr(agent, "_run_pydantic_agent", _fake_run)
-
-    result = await agent.analyze(bundle)
-
-    assert result.success is True
-    assert len(run_prompts) == 2
-    assert "TOOL ALLOWLIST GUARD" in run_prompts[1]
-
-
-@pytest.mark.asyncio
-async def test_docs_analysis_cadence_guard_pivots_search_only_burst(monkeypatch, mock_settings):
-    """Search-only burst should trigger cadence pivot prompt once."""
-    bundle = EvidenceBundle(
-        repository="test-repo",
-        git_evidence=[
-            Evidence(
-                source="git_file",
-                source_id="README.md",
-                title="README.md",
-                content="# Title\n\nUsage docs.",
-                content_hash="hash-readme",
-                status=EvidenceStatus.FOUND,
-            )
-        ],
-        confluence_evidence=[],
-    )
-    agent = DocumentationAgent(settings=mock_settings)
-    monkeypatch.setattr(agent, "_build_analysis_toolsets", lambda: ["toolset-docs"])
-    monkeypatch.setattr(
-        agent,
-        "_resolve_tool_policy",
-        lambda: (
-            ["search_evidence", "read_evidence_document"],
-            {"search_only_burst_min_tool_calls": 4, "search_only_burst_min_search_calls": 4},
-        ),
-    )
-    run_prompts: list[str] = []
-    expected = DocFindings(
-        readme_score=7.0,
-        confluence_score=0.0,
-        api_docs_score=0.0,
-        notes=["README content reviewed", "Usage section identified"],
-        confidence=0.8,
-        missing_sections=["configuration section"],
-        strengths=["Basic usage guidance exists"],
-        recommendations=["Add config examples", "Add troubleshooting notes"],
-    )
-
-    async def _fake_run(**kwargs):
-        run_prompts.append(kwargs["user_prompt"])
-        if len(run_prompts) == 1:
-            agent._last_agent_run_telemetry = {
-                "event_tool_calls_completed": 4,
-                "event_tool_count_by_name": {"search_evidence": 4, "read_evidence_document": 0},
-            }
-        else:
-            agent._last_agent_run_telemetry = {
-                "event_tool_calls_completed": 4,
-                "event_tool_count_by_name": {"search_evidence": 2, "read_evidence_document": 1},
-            }
-        return expected
-
-    monkeypatch.setattr(agent, "_run_pydantic_agent", _fake_run)
-
-    result = await agent.analyze(bundle)
-
-    assert result.success is True
-    assert len(run_prompts) == 2
-    assert "CADENCE PIVOT GUARD" in run_prompts[1]
-
-
-@pytest.mark.asyncio
-async def test_docs_analysis_concrete_read_guard_retries_when_confluence_present(monkeypatch, mock_settings):
-    """When Confluence evidence exists, docs agent should retry with concrete-read guard."""
-    bundle = EvidenceBundle(
-        repository="test-repo",
-        git_evidence=[],
-        confluence_evidence=[
-            Evidence(
-                source="confluence",
-                source_id="page-1",
-                title="Security Architecture",
-                content="Authentication and authorization design.",
-                content_hash="hash-page-1",
-                status=EvidenceStatus.FOUND,
-            )
-        ],
-    )
-    agent = DocumentationAgent(settings=mock_settings)
-    monkeypatch.setattr(agent, "_build_analysis_toolsets", lambda: ["toolset-docs"])
-    monkeypatch.setattr(
-        agent,
-        "_resolve_tool_policy",
-        lambda: (["list_evidence_documents", "search_evidence", "read_evidence_document"], {}),
-    )
-    run_prompts: list[str] = []
-    expected = DocFindings(
-        readme_score=0.0,
-        confluence_score=8.0,
-        api_docs_score=0.0,
-        notes=["Confluence docs reviewed"],
-        confidence=0.85,
-        missing_sections=[],
-        strengths=["Architecture documented"],
-        recommendations=[],
-    )
-
-    async def _fake_run(**kwargs):
-        run_prompts.append(kwargs["user_prompt"])
-        if len(run_prompts) == 1:
-            agent._last_agent_run_telemetry = {
-                "event_tool_calls_completed": 2,
-                "event_tool_count_by_name": {
-                    "list_evidence_documents": 1,
-                    "search_evidence": 1,
-                    "read_evidence_document": 0,
-                },
-            }
-        else:
-            agent._last_agent_run_telemetry = {
-                "event_tool_calls_completed": 3,
-                "event_tool_count_by_name": {
-                    "list_evidence_documents": 1,
-                    "search_evidence": 1,
-                    "read_evidence_document": 1,
-                },
-            }
-        return expected
-
-    monkeypatch.setattr(agent, "_run_pydantic_agent", _fake_run)
-
-    result = await agent.analyze(bundle)
-
-    assert result.success is True
-    assert len(run_prompts) == 2
-    assert "CONCRETE READ GUARD" in run_prompts[1]
-
-
-@pytest.mark.asyncio
-async def test_docs_analysis_concrete_read_retry_rebuilds_toolsets(monkeypatch, mock_settings):
-    """Concrete-read retry should rebuild toolsets so per-run counters do not leak across retries."""
-    bundle = EvidenceBundle(
-        repository="test-repo",
-        git_evidence=[],
-        confluence_evidence=[
-            Evidence(
-                source="confluence",
-                source_id="page-1",
-                title="Security Architecture",
-                content="Authentication and authorization design.",
-                content_hash="hash-page-1",
-                status=EvidenceStatus.FOUND,
-            )
-        ],
-    )
-    agent = DocumentationAgent(settings=mock_settings)
-    toolset_instances: list[object] = []
-
-    def _build_toolsets():
-        marker = object()
-        toolset_instances.append(marker)
-        return [marker]
-
-    monkeypatch.setattr(agent, "_build_analysis_toolsets", _build_toolsets)
-    monkeypatch.setattr(
-        agent,
-        "_resolve_tool_policy",
-        lambda: (["list_evidence_documents", "search_evidence", "read_evidence_document"], {}),
-    )
-    run_kwargs: list[dict[str, object]] = []
-    expected = DocFindings(
-        readme_score=0.0,
-        confluence_score=8.0,
-        api_docs_score=0.0,
-        notes=["Confluence docs reviewed", "Concrete read completed"],
-        confidence=0.85,
-        missing_sections=[],
-        strengths=["Architecture documented"],
-        recommendations=[],
-    )
-
-    async def _fake_run(**kwargs):
-        run_kwargs.append(kwargs)
-        if len(run_kwargs) == 1:
-            agent._last_agent_run_telemetry = {
-                "event_tool_calls_completed": 2,
-                "event_tool_count_by_name": {
-                    "list_evidence_documents": 1,
-                    "search_evidence": 1,
-                    "read_evidence_document": 0,
-                },
-            }
-        else:
-            agent._last_agent_run_telemetry = {
-                "event_tool_calls_completed": 2,
-                "event_tool_count_by_name": {
-                    "list_evidence_documents": 1,
-                    "read_evidence_document": 1,
-                },
-            }
-        return expected
-
-    monkeypatch.setattr(agent, "_run_pydantic_agent", _fake_run)
-
-    result = await agent.analyze(bundle)
-
-    assert result.success is True
-    assert len(run_kwargs) == 2
-    assert run_kwargs[0]["toolsets"] != run_kwargs[1]["toolsets"]
-    assert run_kwargs[1]["max_tool_calls"] == 4
-
-
-@pytest.mark.asyncio
-async def test_docs_analysis_concrete_read_guard_returns_policy_violation_if_unsatisfied(monkeypatch, mock_settings):
-    """Concrete-read guard should fail cleanly when no evidence read happens after retry."""
-    bundle = EvidenceBundle(
-        repository="test-repo",
-        git_evidence=[],
-        confluence_evidence=[
-            Evidence(
-                source="confluence",
-                source_id="page-1",
-                title="Security Architecture",
-                content="Authentication and authorization design.",
-                content_hash="hash-page-1",
-                status=EvidenceStatus.FOUND,
-            )
-        ],
-    )
-    agent = DocumentationAgent(settings=mock_settings)
-    monkeypatch.setattr(agent, "_build_analysis_toolsets", lambda: ["toolset-docs"])
-    monkeypatch.setattr(
-        agent,
-        "_resolve_tool_policy",
-        lambda: (["list_evidence_documents", "search_evidence", "read_evidence_document"], {}),
-    )
-
-    expected = DocFindings(
-        readme_score=0.0,
-        confluence_score=7.0,
-        api_docs_score=0.0,
-        notes=[],
-        confidence=0.7,
-        missing_sections=[],
-        strengths=[],
-        recommendations=[],
-    )
-
-    async def _fake_run(**kwargs):
-        agent._last_agent_run_telemetry = {
-            "event_tool_calls_completed": 2,
-            "event_tool_count_by_name": {
-                "list_evidence_documents": 1,
-                "search_evidence": 1,
-                "read_evidence_document": 0,
-            },
-        }
-        return expected
-
-    monkeypatch.setattr(agent, "_run_pydantic_agent", _fake_run)
-
-    result = await agent.analyze(bundle)
-
-    assert result.success is False
-    assert result.metadata["analysis_method"] == "pydantic_ai_policy_violation"
-    assert result.error is not None
-    assert "concrete-read guard unsatisfied" in str(result.error)
-
-
-@pytest.mark.asyncio
-async def test_docs_concrete_read_guard_uses_evidence_corpus_when_confluence_list_empty(monkeypatch, mock_settings):
-    """Concrete-read guard should still trigger when corpus is available but row confluence list is empty."""
-    bundle = EvidenceBundle(repository="test-repo", git_evidence=[], confluence_evidence=[])
-    agent = DocumentationAgent(settings=mock_settings)
-    monkeypatch.setattr(agent, "_build_analysis_toolsets", lambda: ["toolset-docs"])
-    monkeypatch.setattr(
-        agent,
-        "_resolve_tool_policy",
-        lambda: (["list_evidence_documents", "search_evidence", "read_evidence_document"], {}),
-    )
-    run_prompts: list[str] = []
-    expected = DocFindings(
-        readme_score=0.0,
-        confluence_score=7.0,
-        api_docs_score=0.0,
-        notes=["Corpus evidence contains architecture context", "One concrete doc read completed"],
-        confidence=0.75,
-        missing_sections=["runbook"],
-        strengths=["Architecture documentation exists"],
-        recommendations=["Add operational runbook", "Add API endpoint examples"],
-    )
-
-    async def _fake_run(**kwargs):
-        run_prompts.append(kwargs["user_prompt"])
-        if len(run_prompts) == 1:
-            agent._last_agent_run_telemetry = {
-                "event_tool_calls_completed": 1,
-                "event_tool_count_by_name": {"list_evidence_documents": 1, "read_evidence_document": 0},
-            }
-        else:
-            agent._last_agent_run_telemetry = {
-                "event_tool_calls_completed": 2,
-                "event_tool_count_by_name": {"list_evidence_documents": 1, "read_evidence_document": 1},
-            }
-        return expected
-
-    monkeypatch.setattr(agent, "_run_pydantic_agent", _fake_run)
-    stub_corpus = type("StubCorpus", (), {"get_context_summary": lambda self, max_chars=4000: "stub"})()
-
-    result = await agent._analyze_with_pydantic_agent(
-        evidence_bundle=bundle,
-        profile={},
-        readme_files=[],
-        confluence_pages=[],
-        evidence_corpus=stub_corpus,
-    )
-
-    assert result is expected
-    assert len(run_prompts) == 2
-    assert "CONCRETE READ GUARD" in run_prompts[1]
-
-
-@pytest.mark.asyncio
-async def test_docs_signal_quality_guard_retries_in_synthesis_mode(monkeypatch, mock_settings):
-    """Thin docs signal should trigger one synthesis-only retry with guard prompt."""
-    bundle = EvidenceBundle(
-        repository="test-repo",
-        git_evidence=[
-            Evidence(
-                source="git_file",
-                source_id="README.md",
-                title="README.md",
-                content="# Title\n\nUsage docs with setup details and more context for robust analysis output.",
-                content_hash="hash-readme",
-                status=EvidenceStatus.FOUND,
-            )
-        ],
-        confluence_evidence=[],
-    )
-    agent = DocumentationAgent(settings=mock_settings)
-    monkeypatch.setattr(agent, "_build_analysis_toolsets", lambda: ["toolset-docs"])
-    monkeypatch.setattr(
-        agent,
-        "_resolve_tool_policy",
-        lambda: (["list_evidence_documents", "search_evidence", "read_evidence_document"], {}),
-    )
-    run_kwargs: list[dict[str, object]] = []
-    expected = DocFindings(
-        readme_score=7.2,
-        confluence_score=0.0,
-        api_docs_score=0.0,
-        notes=["README has setup steps", "Project usage is partially documented"],
-        confidence=0.8,
-        missing_sections=["configuration reference"],
-        strengths=["Clear quickstart section"],
-        recommendations=["Add API examples", "Add troubleshooting section"],
-    )
-
-    async def _fake_run(**kwargs):
-        run_kwargs.append(kwargs)
-        if len(run_kwargs) == 1:
-            agent._last_agent_run_telemetry = {
-                "event_tool_calls_completed": 2,
-                "event_tool_count_by_name": {"search_evidence": 2, "read_evidence_document": 1},
-            }
-            return DocFindings(
-                readme_score=7.0,
-                confluence_score=0.0,
-                api_docs_score=0.0,
-                notes=[],
-                confidence=0.8,
-                missing_sections=[],
-                strengths=[],
-                recommendations=[],
-            )
-        agent._last_agent_run_telemetry = {"event_tool_calls_completed": 0, "event_tool_count_by_name": {}}
-        return expected
-
-    monkeypatch.setattr(agent, "_run_pydantic_agent", _fake_run)
-
-    result = await agent.analyze(bundle)
-
-    assert result.success is True
-    assert len(run_kwargs) == 2
-    assert run_kwargs[1]["max_tool_calls"] == 0
-    assert run_kwargs[1]["toolsets"] == []
-    assert "DOC SIGNAL QUALITY GUARD" in str(run_kwargs[1]["user_prompt"])
-
-
-@pytest.mark.asyncio
-async def test_docs_signal_quality_guard_returns_policy_violation_if_unsatisfied(monkeypatch, mock_settings):
-    """Docs signal guard should fail cleanly when output remains empty after retry."""
-    bundle = EvidenceBundle(
-        repository="test-repo",
-        git_evidence=[
-            Evidence(
-                source="git_file",
-                source_id="README.md",
-                title="README.md",
-                content="# Title\n\nUsage docs.",
-                content_hash="hash-readme",
-                status=EvidenceStatus.FOUND,
-            )
-        ],
-        confluence_evidence=[],
-    )
-    agent = DocumentationAgent(settings=mock_settings)
-    monkeypatch.setattr(agent, "_build_analysis_toolsets", lambda: ["toolset-docs"])
-    monkeypatch.setattr(
-        agent,
-        "_resolve_tool_policy",
-        lambda: (["list_evidence_documents", "search_evidence", "read_evidence_document"], {}),
-    )
-
-    async def _fake_run(**kwargs):
-        agent._last_agent_run_telemetry = {
-            "event_tool_calls_completed": 1,
-            "event_tool_count_by_name": {"search_evidence": 1, "read_evidence_document": 1},
-        }
-        return DocFindings(
-            readme_score=6.8,
-            confluence_score=0.0,
-            api_docs_score=0.0,
-            notes=[],
-            confidence=0.8,
-            missing_sections=[],
-            strengths=[],
-            recommendations=[],
-        )
-
-    monkeypatch.setattr(agent, "_run_pydantic_agent", _fake_run)
-
-    result = await agent.analyze(bundle)
-
-    assert result.success is False
-    assert result.metadata["analysis_method"] == "pydantic_ai_policy_violation"
-    assert result.error is not None
-    assert "docs signal guard unsatisfied" in str(result.error)
-
-
-def test_docs_build_analysis_toolsets_disables_skills(monkeypatch, mock_settings):
-    """Documentation analysis should drop skills toolsets to avoid noisy script calls."""
-
-    class _SkillToolset:
-        skills = {"llm-analysis-skill": object()}
-        _vds_skill_metadata = []
-
-    class _OtherToolset:
-        pass
-
-    agent = DocumentationAgent(settings=mock_settings)
-    monkeypatch.setattr(
-        "vds_audit_orchestrator.agents.docs_agent._build_toolsets",
-        lambda *_: [_SkillToolset(), _OtherToolset()],
-    )
-
-    toolsets = agent._build_analysis_toolsets()
-
-    assert len(toolsets) == 1
-    assert isinstance(toolsets[0], _OtherToolset)