@ngocsangairvds/vsaf 3.2.14 → 3.2.16

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

@@ -1,1234 +0,0 @@
-"""Documentation Analysis Agent (TSK-047).
-
-Provides LLM-powered documentation quality analysis across multiple dimensions:
-- Completeness: Are all required sections present?
-- Clarity: Is the documentation clear and understandable?
-- Currency: Are there signs of outdated information?
-- Structure: Is the documentation well-organized?
-
-Migrated to PydanticAI patterns (Phase 8).
-"""
-
-from __future__ import annotations
-
-import re
-from typing import Any
-
-from pydantic import BaseModel, Field, confloat
-
-from vds_audit_orchestrator.agents.base import AgentResult, BaseAgent
-from vds_audit_orchestrator.agents.pydantic_base import (
-    AuditDeps,
-    DocFindings,
-    _build_toolsets,
-)
-from vds_audit_orchestrator.agents.toolsets.evidence_corpus import create_evidence_corpus_toolset
-from vds_audit_orchestrator.agents.toolsets.vector_evidence import (
-    create_vector_evidence_toolset,
-    is_vector_evidence_ready,
-)
-from vds_audit_orchestrator.config import get_config
-from vds_audit_orchestrator.errors import AUDIT_ERROR_CODES, AuditError
-from vds_audit_orchestrator.evidence.corpus import EvidenceCorpus, deserialize_evidence_corpus
-from vds_audit_orchestrator.models.evidence import Evidence, EvidenceBundle
-from vds_audit_orchestrator.models.task import AuditTask
-
-# System prompt for documentation quality analysis using DocFindings output
-DOC_QUALITY_SYSTEM_PROMPT = """You are a documentation quality analyst for enterprise software projects.
-You analyze README files, Confluence pages, and API documentation to assess quality.
-
-Evaluate documentation on these dimensions, scoring each from 0.0 to 10.0:
-
-1. README QUALITY (0.0-10.0):
-   - Purpose statement and project overview
-   - Installation instructions
-   - Usage examples with code snippets
-   - Configuration options
-   - Contributing guidelines
-   - License information
-
-2. CONFLUENCE QUALITY (0.0-10.0):
-   - Architecture overview
-   - API documentation
-   - Troubleshooting guides
-   - Runbooks and operational docs
-   - Diagram presence
-
-3. API DOCUMENTATION (0.0-10.0):
-   - OpenAPI/Swagger specs
-   - Endpoint descriptions
-   - Request/response examples
-   - Error handling documentation
-
-ANALYSIS GUIDELINES:
-- Identify missing required sections
-- Note strengths in the documentation
-- Provide actionable recommendations
-- Be specific about what needs improvement
-- Consider the project context from the profile
-
-Your confidence score (0.0-1.0) should reflect:
-- How much documentation you had to analyze
-- Quality of evidence provided
-- Certainty about your assessments
-
-Return your analysis as a structured DocFindings object."""
-
-# System prompt for per-document analysis (used in fallback/individual analysis path)
-PER_DOC_QUALITY_SYSTEM_PROMPT = """You are a documentation quality analyst for enterprise software projects.
-Evaluate documentation on these dimensions, scoring each from 0.0 to 1.0:
-
-1. COMPLETENESS (0.0-1.0): Are essential sections present?
-   - For README: Purpose, Installation, Usage, Configuration, Contributing
-   - For Confluence: Overview, Architecture, API docs, Troubleshooting
-
-2. CLARITY (0.0-1.0): Is the documentation clear?
-   - Clear language, no jargon without explanation
-   - Good examples and code snippets
-   - Logical flow of information
-
-3. CURRENCY (0.0-1.0): Is the content up-to-date?
-   - No references to deprecated features
-   - Version numbers are current
-   - No "TODO" or "TBD" placeholders in critical sections
-
-4. STRUCTURE (0.0-1.0): Is it well-organized?
-   - Proper headings hierarchy
-   - Table of contents for long docs
-   - Consistent formatting
-
-Return JSON only:
-{
-  "completeness": {"score": 0.0-1.0, "missing_sections": [], "notes": ""},
-  "clarity": {"score": 0.0-1.0, "issues": [], "notes": ""},
-  "currency": {"score": 0.0-1.0, "outdated_indicators": [], "notes": ""},
-  "structure": {"score": 0.0-1.0, "issues": [], "notes": ""},
-  "overall_score": 0.0-1.0,
-  "summary": "Brief overall assessment",
-  "recommendations": ["List of improvement suggestions"]
-}"""
-
-
-class DocumentationDimension(BaseModel):
-    """Structured score and notes for a documentation dimension."""
-
-    score: confloat(ge=0.0, le=1.0)  # type: ignore[valid-type]
-    missing_sections: list[str] = Field(default_factory=list)
-    issues: list[str] = Field(default_factory=list)
-    outdated_indicators: list[str] = Field(default_factory=list)
-    notes: str = ""
-
-
-class DocumentationQualityOutput(BaseModel):
-    """Structured output for per-document quality analysis."""
-
-    completeness: DocumentationDimension
-    clarity: DocumentationDimension
-    currency: DocumentationDimension
-    structure: DocumentationDimension
-    overall_score: confloat(ge=0.0, le=1.0)  # type: ignore[valid-type]
-    summary: str
-    recommendations: list[str] = Field(default_factory=list)
-
-
-class DocumentationAgent(BaseAgent):
-    """Agent for LLM-powered documentation quality analysis.
-
-    Analyzes README files from git_evidence and Confluence pages from
-    confluence_evidence, evaluating quality across multiple dimensions.
-
-    Uses PydanticAI patterns with:
-    - AuditDeps for dependency injection
-    - DocFindings for structured output
-    - Automatic confidence validation via @agent.output_validator
-    """
-
-    AGENT_NAME = "DocumentationAgent"
-    _DEFAULT_TOOL_ALLOWLIST: tuple[str, ...] = (
-        "list_evidence_documents",
-        "search_evidence",
-        "read_evidence_document",
-        "search_evidence_vector",
-    )
-
-    async def analyze(
-        self,
-        evidence: EvidenceBundle | dict[str, Any] | AuditTask,
-        profile: dict[str, Any] | None = None,
-        evidence_corpus: EvidenceCorpus | dict[str, Any] | None = None,
-    ) -> AgentResult:
-        """Analyze documentation quality using LLM.
-
-        Args:
-            evidence: Evidence bundle containing git and Confluence documentation.
-            profile: Optional project profile for context-aware analysis.
-
-        Returns:
-            AgentResult with quality findings and scores.
-        """
-        findings: list[dict[str, Any]] = []
-        metadata: dict[str, Any] = {
-            "readme_count": 0,
-            "confluence_count": 0,
-            "llm_enabled": self.llm_available,
-        }
-
-        # Normalize evidence input
-        evidence_bundle = self._normalize_evidence(evidence)
-        if evidence_bundle is None:
-            return self._result(
-                agent_name=self.AGENT_NAME,
-                success=False,
-                error=AuditError(
-                    code=AUDIT_ERROR_CODES["AGENT_EVIDENCE_MISSING"],
-                    message="Evidence bundle missing",
-                    template_params={"agent_name": self.AGENT_NAME},
-                ),
-            )
-        resolved_corpus = deserialize_evidence_corpus(evidence_corpus)
-        if isinstance(evidence, AuditTask):
-            payload = evidence.input_data
-            if resolved_corpus is None:
-                resolved_corpus = deserialize_evidence_corpus(payload.get("evidence_corpus"))
-        elif isinstance(evidence, dict):
-            if resolved_corpus is None:
-                resolved_corpus = deserialize_evidence_corpus(evidence.get("evidence_corpus"))
-
-        # Collect README files from git evidence
-        readme_files = [
-            e
-            for e in evidence_bundle.git_evidence
-            if e.title.lower().startswith("readme") or e.source_id.lower().endswith("readme.md")
-        ]
-        metadata["readme_count"] = len(readme_files)
-
-        # Collect Confluence pages
-        confluence_pages = evidence_bundle.confluence_evidence
-        metadata["confluence_count"] = len(confluence_pages)
-
-        # Try PydanticAI-based analysis first (preferred path)
-        if self.settings.enabled and self._pydantic_model is not None:
-            try:
-                doc_findings = await self._analyze_with_pydantic_agent(
-                    evidence_bundle=evidence_bundle,
-                    profile=profile or {},
-                    readme_files=readme_files,
-                    confluence_pages=confluence_pages,
-                    evidence_corpus=resolved_corpus,
-                )
-                findings.extend(
-                    self._convert_doc_findings_to_findings(
-                        doc_findings,
-                        evidence_bundle,
-                    )
-                )
-                metadata["analysis_method"] = "pydantic_ai"
-                metadata["confidence"] = doc_findings.confidence
-                metadata["scores"] = {
-                    "readme": doc_findings.readme_score,
-                    "confluence": doc_findings.confluence_score,
-                    "api_docs": doc_findings.api_docs_score,
-                    "overall": doc_findings.overall_score,
-                }
-            except Exception as e:
-                if self._is_tool_policy_violation_error(str(e)):
-                    return self._result(
-                        agent_name=self.AGENT_NAME,
-                        success=False,
-                        error=str(e),
-                        metadata={**metadata, "analysis_method": "pydantic_ai_policy_violation"},
-                    )
-                self.logger.warning(
-                    "pydantic_ai_analysis_failed",
-                    error=str(e),
-                )
-                # Fall back to per-document analysis
-                findings.extend(
-                    await self._analyze_documents_individually(
-                        readme_files,
-                        confluence_pages,
-                    )
-                )
-                metadata["analysis_method"] = "fallback_individual"
-        else:
-            # Use individual document analysis (heuristic or per-document LLM)
-            findings.extend(
-                await self._analyze_documents_individually(
-                    readme_files,
-                    confluence_pages,
-                )
-            )
-            metadata["analysis_method"] = "individual"
-
-        # Add basic length check findings for very short pages
-        for page in confluence_pages:
-            if len(page.content) < 100:
-                findings.append(
-                    {
-                        "type": "doc_quality",
-                        "severity": "warning",
-                        "dimension": "completeness",
-                        "description": f"Page '{page.title}' is too short ({len(page.content)} chars)",
-                        "location": page.source_url,
-                    }
-                )
-
-        return self._result(
-            agent_name=self.AGENT_NAME,
-            success=True,
-            findings=findings,
-            metadata=metadata,
-        )
-
-    @staticmethod
-    def _is_tool_policy_violation_error(error: str) -> bool:
-        lowered = error.lower()
-        return (
-            "tool policy violation" in lowered
-            or "cadence guard unsatisfied" in lowered
-            or "concrete-read guard unsatisfied" in lowered
-            or "docs signal guard unsatisfied" in lowered
-        )
-
-    def _resolve_tool_policy(self) -> tuple[list[str], dict[str, Any]]:
-        try:
-            cfg = get_config().agentic
-        except Exception:
-            return (list(self._DEFAULT_TOOL_ALLOWLIST), {})
-        configured_allowlist = cfg.tool_allowlists.get("docs", [])
-        allowlist = [str(item).strip() for item in configured_allowlist if str(item).strip()]
-        if not allowlist:
-            allowlist = list(self._DEFAULT_TOOL_ALLOWLIST)
-        non_progress_policy = cfg.non_progress_policy.model_dump()
-        return (allowlist, non_progress_policy)
-
-    @staticmethod
-    def _is_invalid_tool_usage_error(error: str) -> bool:
-        lowered = error.lower()
-        return (
-            "tool" in lowered
-            and (
-                "not found" in lowered
-                or "unknown tool" in lowered
-                or "invalid tool" in lowered
-                or "not allowed" in lowered
-                or "not in available tools" in lowered
-            )
-            and "invalid tool call arguments" not in lowered
-        )
-
-    @staticmethod
-    def _parse_tool_name_from_invalid_tool_error(error: str) -> str | None:
-        patterns = (
-            r"tool '([^']+)'",
-            r'tool "([^"]+)"',
-            r"unknown tool[:\s]+([a-zA-Z0-9_./-]+)",
-            r"invalid tool[:\s]+([a-zA-Z0-9_./-]+)",
-        )
-        for pattern in patterns:
-            match = re.search(pattern, error, flags=re.IGNORECASE)
-            if match:
-                value = str(match.group(1)).strip()
-                if value:
-                    return value
-        return None
-
-    @staticmethod
-    def _is_low_signal_search_burst(
-        telemetry: dict[str, Any] | None,
-        *,
-        policy: dict[str, Any] | None = None,
-    ) -> bool:
-        if not isinstance(telemetry, dict):
-            return False
-        policy_values = dict(policy or {})
-
-        def _ival(name: str, default: int) -> int:
-            raw = policy_values.get(name, default)
-            try:
-                return int(raw)
-            except (TypeError, ValueError):
-                return default
-
-        min_tool_calls = _ival("search_only_burst_min_tool_calls", 4)
-        min_search_calls = _ival("search_only_burst_min_search_calls", 4)
-        max_read_calls = _ival("search_only_burst_max_read_calls", 0)
-        usage = telemetry.get("usage")
-        usage_tool_calls = int(usage.get("tool_calls", 0) or 0) if isinstance(usage, dict) else 0
-        event_tool_calls = int(telemetry.get("event_tool_calls_completed", telemetry.get("event_tool_calls", 0)) or 0)
-        tool_calls = max(usage_tool_calls, event_tool_calls)
-        by_name = telemetry.get("event_tool_count_by_name")
-        if not isinstance(by_name, dict):
-            return False
-        search_calls = (
-            int(by_name.get("list_directory", 0) or 0)
-            + int(by_name.get("grep_search", 0) or 0)
-            + int(by_name.get("search_evidence", 0) or 0)
-            + int(by_name.get("search_evidence_vector", 0) or 0)
-        )
-        read_calls = (
-            int(by_name.get("read_file", 0) or 0)
-            + int(by_name.get("read_evidence_document", 0) or 0)
-            + int(by_name.get("get_definition", 0) or 0)
-            + int(by_name.get("find_references", 0) or 0)
-            + int(by_name.get("workspace_symbol", 0) or 0)
-        )
-        return tool_calls >= min_tool_calls and search_calls >= min_search_calls and read_calls <= max_read_calls
-
-    @staticmethod
-    def _needs_concrete_read_retry(
-        telemetry: dict[str, Any] | None,
-        *,
-        confluence_count: int,
-        evidence_corpus_available: bool,
-    ) -> bool:
-        if not isinstance(telemetry, dict):
-            return False
-        if confluence_count <= 0 and not evidence_corpus_available:
-            return False
-        by_name = telemetry.get("event_tool_count_by_name")
-        if not isinstance(by_name, dict):
-            return False
-        docs_search_or_list_calls = (
-            int(by_name.get("list_evidence_documents", 0) or 0)
-            + int(by_name.get("search_evidence", 0) or 0)
-            + int(by_name.get("search_evidence_vector", 0) or 0)
-        )
-        docs_read_calls = int(by_name.get("read_evidence_document", 0) or 0)
-        return docs_search_or_list_calls >= 1 and docs_read_calls == 0
-
-    @staticmethod
-    def _needs_doc_signal_retry(
-        quality_summary: dict[str, Any] | None,
-        *,
-        readme_count: int,
-        confluence_count: int,
-        evidence_corpus_available: bool,
-    ) -> bool:
-        if not isinstance(quality_summary, dict):
-            return False
-        if (readme_count + confluence_count) <= 0 and not evidence_corpus_available:
-            return False
-        flags = quality_summary.get("quality_flags")
-        if not isinstance(flags, list):
-            return False
-        return "docs_signal_too_thin" in {str(item) for item in flags}
-
-    def _normalize_evidence(
-        self,
-        evidence: EvidenceBundle | dict[str, Any] | AuditTask,
-    ) -> EvidenceBundle | None:
-        """Normalize evidence input to EvidenceBundle.
-
-        Args:
-            evidence: Raw evidence input (bundle or dict).
-
-        Returns:
-            Normalized EvidenceBundle or None if invalid.
-        """
-        if isinstance(evidence, EvidenceBundle):
-            return evidence
-        if isinstance(evidence, AuditTask):
-            payload = evidence.input_data
-            bundle = payload.get("evidence_bundle") or payload.get("evidence")
-            if isinstance(bundle, EvidenceBundle):
-                return bundle
-            if isinstance(bundle, dict):
-                try:
-                    return EvidenceBundle.model_validate(bundle)
-                except Exception as exc:
-                    self.logger.debug("evidence_bundle_validation_failed", error=str(exc))
-                    return None
-        if isinstance(evidence, dict):
-            bundle = evidence.get("evidence_bundle") or evidence.get("evidence")
-            if isinstance(bundle, EvidenceBundle):
-                return bundle
-            if isinstance(bundle, dict):
-                try:
-                    return EvidenceBundle.model_validate(bundle)
-                except Exception as exc:
-                    self.logger.debug("evidence_bundle_validation_failed", error=str(exc))
-                    return None
-        return None
-
-    async def _analyze_with_pydantic_agent(
-        self,
-        evidence_bundle: EvidenceBundle,
-        profile: dict[str, Any],
-        readme_files: list[Evidence],
-        confluence_pages: list[Evidence],
-        evidence_corpus: Any = None,  # Added for Phase 15
-    ) -> DocFindings:
-        """Run analysis using the PydanticAI agent with AuditDeps.
-
-        Args:
-            evidence_bundle: The full evidence bundle.
-            profile: Project profile for context.
-            readme_files: List of README evidence items.
-            confluence_pages: List of Confluence evidence items.
-            evidence_corpus: Optional evidence corpus from Phase 15.
-
-        Returns:
-            DocFindings with structured analysis results.
-        """
-        # Build dependencies for the agent using AuditDeps
-        deps = AuditDeps.from_evidence_bundle(
-            evidence=evidence_bundle,
-            profile=profile,
-            settings=self.settings,
-            evidence_corpus=evidence_corpus,
-        )
-
-        def _build_default_toolsets() -> list[Any]:
-            refreshed_toolsets = self._build_analysis_toolsets()
-            if deps.evidence_corpus is not None:
-                try:
-                    refreshed_toolsets.append(create_evidence_corpus_toolset())
-                except Exception as exc:
-                    self.logger.warning("docs_evidence_corpus_toolset_unavailable", error=str(exc))
-            try:
-                if is_vector_evidence_ready(deps=deps):
-                    refreshed_toolsets.append(create_vector_evidence_toolset())
-            except Exception as exc:
-                self.logger.warning("docs_vector_evidence_toolset_unavailable", error=str(exc))
-            return refreshed_toolsets
-
-        toolsets = _build_default_toolsets()
-        available_skill_names = self._collect_available_skill_names(toolsets)
-        max_tool_calls = 0 if not toolsets else None
-
-        # Prepare documentation content for analysis
-        readme_content = self._prepare_content_summary(readme_files, "README", max_chars=6000)
-        confluence_content = self._prepare_content_summary(confluence_pages, "Confluence", max_chars=6000)
-
-        # Get context summary from corpus if available
-        context_summary = ""
-        if evidence_corpus:
-            context_summary = evidence_corpus.get_context_summary(max_chars=4000)
-
-        # Build the user prompt with documentation context
-        user_prompt = self._build_analysis_prompt(
-            readme_content=readme_content,
-            confluence_content=confluence_content,
-            profile=profile,
-            readme_count=len(readme_files),
-            confluence_count=len(confluence_pages),
-            context_summary=context_summary,
-            available_skill_names=available_skill_names,
-        )
-
-        allowlist, non_progress_policy = self._resolve_tool_policy()
-        guard_prompt = user_prompt
-        used_allowlist_retry = False
-        used_cadence_retry = False
-        used_concrete_read_retry = False
-        used_doc_signal_retry = False
-
-        while True:
-            try:
-                output = await self._run_pydantic_agent(
-                    system_prompt=DOC_QUALITY_SYSTEM_PROMPT,
-                    user_prompt=guard_prompt,
-                    result_type=DocFindings,
-                    complexity="standard",
-                    deps=deps,
-                    prompt_type="docs_analysis",
-                    toolsets=toolsets,
-                    max_tool_calls=max_tool_calls,
-                )
-            except Exception as exc:
-                message = str(exc)
-                if self._is_invalid_tool_usage_error(message):
-                    attempted_tool = self._parse_tool_name_from_invalid_tool_error(message)
-                    self.logger.warning(
-                        "docs_invalid_tool_usage_allowlist",
-                        error=message,
-                        attempted_tool=attempted_tool,
-                        allowed_tools=allowlist,
-                    )
-                    if used_allowlist_retry:
-                        raise RuntimeError(
-                            "docs tool policy violation: invalid tool usage "
-                            f"(attempted={attempted_tool or 'unknown'}, allowlist={allowlist})"
-                        ) from exc
-                    used_allowlist_retry = True
-                    guard_prompt = (
-                        user_prompt
-                        + "\n\nTOOL ALLOWLIST GUARD:\n"
-                        + f"- Allowed tools for DocumentationAgent: {', '.join(allowlist)}.\n"
-                        + f"- Invalid tool requested: {attempted_tool or 'unknown'}.\n"
-                        + "- Use only allowlisted tools and call one tool per turn.\n"
-                        + "- If search/list results are low-signal, pivot to read_evidence_document."
-                    )
-                    toolsets = _build_default_toolsets()
-                    max_tool_calls = 0 if not toolsets else None
-                    continue
-                raise
-
-            telemetry = getattr(self, "_last_agent_run_telemetry", {})
-            if self._is_low_signal_search_burst(telemetry, policy=non_progress_policy):
-                self.logger.warning(
-                    "docs_low_signal_cadence_guard",
-                    observed_tool_names=(telemetry.get("event_tool_names") if isinstance(telemetry, dict) else None),
-                    observed_tool_counts=(
-                        telemetry.get("event_tool_count_by_name") if isinstance(telemetry, dict) else None
-                    ),
-                )
-                if used_cadence_retry:
-                    raise RuntimeError("docs cadence guard unsatisfied: low-signal repetition without pivot")
-                used_cadence_retry = True
-                guard_prompt = (
-                    user_prompt
-                    + "\n\nCADENCE PIVOT GUARD:\n"
-                    + "- Stop search/list-only bursts.\n"
-                    + "- Pivot from list/search tools to read_evidence_document on a concrete match.\n"
-                    + "- Do not finish without at least one high-signal evidence read."
-                )
-                toolsets = _build_default_toolsets()
-                max_tool_calls = 0 if not toolsets else None
-                continue
-            if self._needs_concrete_read_retry(
-                telemetry,
-                confluence_count=len(confluence_pages),
-                evidence_corpus_available=deps.evidence_corpus is not None,
-            ):
-                self.logger.warning(
-                    "docs_concrete_read_guard_retry",
-                    observed_tool_counts=(
-                        telemetry.get("event_tool_count_by_name") if isinstance(telemetry, dict) else None
-                    ),
-                    confluence_count=len(confluence_pages),
-                    evidence_corpus_available=deps.evidence_corpus is not None,
-                )
-                if used_concrete_read_retry:
-                    raise RuntimeError(
-                        "docs concrete-read guard unsatisfied: confluence evidence available "
-                        "but read_evidence_document was never called"
-                    )
-                used_concrete_read_retry = True
-                guard_prompt = (
-                    user_prompt
-                    + "\n\nCONCRETE READ GUARD:\n"
-                    + "- Confluence evidence exists for this run.\n"
-                    + "- Call list_evidence_documents/search_evidence only to identify a concrete title.\n"
-                    + "- Then call read_evidence_document on at least one relevant title before finishing.\n"
-                    + "- Call read_evidence_document within the first 2 tool turns on this retry.\n"
-                    + "- If one read fails, retry a different concrete title."
-                )
-                toolsets = _build_default_toolsets()
-                max_tool_calls = 4 if toolsets else 0
-                continue
-            quality_summary = self._build_response_quality_summary(
-                output,
-                telemetry if isinstance(telemetry, dict) else None,
-            )
-            if self._needs_doc_signal_retry(
-                quality_summary,
-                readme_count=len(readme_files),
-                confluence_count=len(confluence_pages),
-                evidence_corpus_available=deps.evidence_corpus is not None,
-            ):
-                self.logger.warning(
-                    "docs_signal_quality_guard_retry",
-                    quality_flags=quality_summary.get("quality_flags"),
-                    doc_signal_count=quality_summary.get("doc_signal_count"),
-                    observed_tool_counts=(
-                        telemetry.get("event_tool_count_by_name") if isinstance(telemetry, dict) else None
-                    ),
-                )
-                if used_doc_signal_retry:
-                    raise RuntimeError(
-                        "docs signal guard unsatisfied: expected concrete documentation notes/recommendations"
-                    )
-                used_doc_signal_retry = True
-                guard_prompt = (
-                    user_prompt
-                    + "\n\nDOC SIGNAL QUALITY GUARD:\n"
-                    + "- Return non-empty documentation analysis grounded in concrete evidence.\n"
-                    + "- Provide at least 2 notes and at least 2 actionable recommendations.\n"
-                    + "- If docs are missing, list missing sections explicitly and explain evidence gaps.\n"
-                    + "- Use evidence already retrieved; do not continue broad search loops.\n"
-                    + "- Return only DocFindings JSON."
-                )
-                # Synthesis-only retry prevents additional low-signal search churn.
-                toolsets = []
-                max_tool_calls = 0
-                continue
-            return output
-
-    def _build_analysis_toolsets(self) -> list[Any]:
-        """Build optional MCP/skills toolsets for evidence-grounded analysis."""
-        try:
-            toolsets = _build_toolsets(get_config().llm)
-            filtered: list[Any] = []
-            dropped = 0
-            for toolset in toolsets:
-                has_skills_map = isinstance(getattr(toolset, "skills", None), dict)
-                has_skill_metadata = isinstance(getattr(toolset, "_vds_skill_metadata", None), list)
-                if has_skills_map or has_skill_metadata:
-                    dropped += 1
-                    continue
-                filtered.append(toolset)
-            if dropped:
-                self.logger.info("docs_analysis_skills_toolset_disabled", dropped_toolsets=dropped)
-            return filtered
-        except Exception as exc:
-            self.logger.warning("docs_analysis_toolsets_failed", error=str(exc))
-            return []
-
-    @staticmethod
-    def _collect_available_skill_names(toolsets: list[Any]) -> list[str]:
-        names: list[str] = []
-        for toolset in toolsets:
-            skills_map = getattr(toolset, "skills", None)
-            if isinstance(skills_map, dict) and skills_map:
-                for skill_name in skills_map:
-                    name = str(skill_name or "").strip()
-                    if name and name not in names:
-                        names.append(name)
-                continue
-            metadata = getattr(toolset, "_vds_skill_metadata", None)
-            if not isinstance(metadata, list):
-                continue
-            for entry in metadata:
-                name = str(getattr(entry, "name", "") or "").strip()
-                if name and name not in names:
-                    names.append(name)
-        return names
-
-    @staticmethod
-    def _is_missing_skill_error(error: str) -> bool:
-        lowered = error.lower()
-        return "skill" in lowered and "not found" in lowered
-
-    @staticmethod
-    def _parse_skill_name_from_error(error: str) -> str | None:
-        patterns = (
-            r"skill '([^']+)'",
-            r'skill "([^"]+)"',
-            r"skill_name['\"]?\s*[:=]\s*['\"]([^'\"]+)['\"]",
-        )
-        for pattern in patterns:
-            match = re.search(pattern, error, flags=re.IGNORECASE)
-            if match:
-                name = str(match.group(1)).strip()
-                if name:
-                    return name
-        return None
-
-    @staticmethod
-    def _drop_skill_from_toolsets(toolsets: list[Any], skill_name: str) -> tuple[list[Any], int]:
-        if not skill_name:
-            return list(toolsets), 0
-
-        removed_count = 0
-        updated_toolsets: list[Any] = []
-        for toolset in toolsets:
-            skills_map = getattr(toolset, "skills", None)
-            metadata = getattr(toolset, "_vds_skill_metadata", None)
-            if isinstance(skills_map, dict):
-                if skill_name in skills_map:
-                    skills_map.pop(skill_name, None)
-                    removed_count += 1
-                if isinstance(metadata, list):
-                    filtered_metadata = [
-                        item for item in metadata if str(getattr(item, "name", "") or "").strip() != skill_name
-                    ]
-                    toolset._vds_skill_metadata = filtered_metadata
-                if skills_map:
-                    updated_toolsets.append(toolset)
-                continue
-            if isinstance(metadata, list):
-                matched = False
-                filtered_metadata = []
-                for item in metadata:
-                    name = str(getattr(item, "name", "") or "").strip()
-                    if name == skill_name:
-                        matched = True
-                        continue
-                    filtered_metadata.append(item)
-                if matched:
-                    removed_count += 1
-                    toolset._vds_skill_metadata = filtered_metadata
-                    if filtered_metadata:
-                        updated_toolsets.append(toolset)
-                    continue
-            updated_toolsets.append(toolset)
-        return updated_toolsets, removed_count
-
-    @staticmethod
-    def _drop_all_skill_toolsets(toolsets: list[Any]) -> tuple[list[Any], int]:
-        filtered_toolsets: list[Any] = []
-        removed = 0
-        for toolset in toolsets:
-            has_skills_map = isinstance(getattr(toolset, "skills", None), dict)
-            has_skill_metadata = isinstance(getattr(toolset, "_vds_skill_metadata", None), list)
-            if has_skills_map or has_skill_metadata:
-                removed += 1
-                continue
-            filtered_toolsets.append(toolset)
-        return filtered_toolsets, removed
-
-    def _prepare_content_summary(
-        self,
-        docs: list[Evidence],
-        label: str,
-        *,
-        max_chars: int = 6000,
-    ) -> str:
-        """Build a bounded, human-readable summary for a list of documents.
-
-        This is used by the aggregated PydanticAI path to provide concise context
-        without exceeding prompt limits.
-        """
-        if not docs:
-            return f"(No {label} documents found.)"
-
-        lines: list[str] = [f"### {label} Documents ({len(docs)})", ""]
-        remaining = max_chars - sum(len(line) + 1 for line in lines)
-        if remaining <= 0:
-            return lines[0][:max_chars]
-
-        # Include up to N documents, with per-doc excerpt budget.
-        per_doc_budget = max(500, min(1500, remaining // max(1, min(len(docs), 4))))
-
-        for doc in docs:
-            if remaining <= 0:
-                break
-
-            title = doc.title or doc.source_id or "Untitled"
-            location = doc.source_url or doc.source_id or ""
-            header = f"- **{title}**" + (f" ({location})" if location else "")
-
-            block: list[str] = [header]
-            excerpt = (doc.content or "").strip().replace("\r\n", "\n")
-            if len(excerpt) > per_doc_budget:
-                excerpt = excerpt[:per_doc_budget].rstrip() + "\n...(truncated)"
-            if excerpt:
-                block.extend(["```", excerpt, "```", ""])
-            else:
-                block.append("(empty)")
-                block.append("")
-
-            block_len = sum(len(line) + 1 for line in block)
-            if block_len > remaining:
-                # Try a smaller excerpt if we are tight on space.
-                tight_budget = max(0, remaining - (len(header) + 1 + len("```\n```\n\n") + 10))
-                if tight_budget <= 0:
-                    break
-                excerpt = (doc.content or "").strip().replace("\r\n", "\n")
-                excerpt = excerpt[:tight_budget].rstrip() + "\n...(truncated)"
-                block = [header, "```", excerpt, "```", ""]
-                block_len = sum(len(line) + 1 for line in block)
-                if block_len > remaining:
-                    break
-
-            lines.extend(block)
-            remaining -= block_len
-
-        rendered = "\n".join(lines).strip()
-        if len(rendered) > max_chars:
-            rendered = rendered[:max_chars].rstrip() + "\n...(truncated)"
-        return rendered
-
-    def _build_analysis_prompt(
-        self,
-        readme_content: str,
-        confluence_content: str,
-        profile: dict[str, Any],
-        readme_count: int,
-        confluence_count: int,
-        context_summary: str = "",
-        available_skill_names: list[str] | None = None,
-    ) -> str:
-        """Build the user prompt for documentation analysis.
-
-        Args:
-            readme_content: Prepared README content summary.
-            confluence_content: Prepared Confluence content summary.
-            profile: Project profile dictionary.
-            readme_count: Number of README files.
-            confluence_count: Number of Confluence pages.
-            context_summary: Optional summary of external evidence context.
-
-        Returns:
-            Formatted user prompt string.
-        """
-        domain = profile.get("domain", "unknown")
-        criticality = profile.get("criticality", "medium")
-
-        prompt = f"""Analyze the documentation quality for this project.
-
-## Project Context
-- Domain: {domain}
-- Criticality: {criticality}
-- README files: {readme_count}
-- Confluence pages: {confluence_count}
-
-## README Documentation
-{readme_content}
-
-## Confluence Documentation
-{confluence_content}
-"""
-
-        if context_summary:
-            prompt += f"\n{context_summary}\n"
-
-        if available_skill_names:
-            prompt += (
-                "\nSkill usage constraints:\n"
-                f"- Available skills: {', '.join(available_skill_names)}\n"
-                "- Use only the available skill names exactly as listed.\n"
-                "- Do not invent or call missing skill names.\n"
-            )
-
-        prompt += """
-## Instructions
-0. Use TOOL-FIRST analysis when tools are available:
-   - retrieve focused evidence snippets first,
-   - cite only retrieved evidence in conclusions,
-   - avoid assumptions not grounded in retrieved docs.
-1. Score each documentation category (0-10 scale)
-2. Identify missing sections that should be present
-3. Note documentation strengths
-4. Provide specific, actionable recommendations
-5. Set confidence based on evidence quality and coverage
-6. Ensure output is substantive:
-   - include at least 2 notes and 2 recommendations when documentation exists,
-   - if documentation is missing/insufficient, include explicit missing sections + evidence-gap notes.
-
-Return your analysis as a DocFindings object."""
-
-        return prompt
-
-    def _convert_doc_findings_to_findings(
-        self,
-        doc_findings: DocFindings,
-        evidence_bundle: EvidenceBundle,
-    ) -> list[dict[str, Any]]:
-        """Convert DocFindings to standardized finding dictionaries.
-
-        Args:
-            doc_findings: Structured DocFindings from LLM.
-            evidence_bundle: Original evidence bundle for location info.
-
-        Returns:
-            List of finding dictionaries.
-        """
-        findings: list[dict[str, Any]] = []
-        repo_path = str(evidence_bundle.repository) if evidence_bundle.repository else "unknown"
-
-        # Overall assessment finding
-        overall_score = doc_findings.overall_score
-        severity = "error" if overall_score < 4.0 else "warning" if overall_score < 7.0 else "info"
-
-        findings.append(
-            {
-                "type": "doc_quality_assessment",
-                "severity": severity,
-                "description": f"Documentation quality score: {overall_score:.1f}/10.0",
-                "location": repo_path,
-                "scores": {
-                    "readme": doc_findings.readme_score,
-                    "confluence": doc_findings.confluence_score,
-                    "api_docs": doc_findings.api_docs_score,
-                    "overall": overall_score,
-                },
-                "confidence": doc_findings.confidence,
-                "strengths": doc_findings.strengths,
-                "recommendations": doc_findings.recommendations,
-            }
-        )
-
-        # Add findings for missing sections
-        for section in doc_findings.missing_sections:
-            findings.append(
-                {
-                    "type": "doc_quality",
-                    "severity": "warning",
-                    "dimension": "completeness",
-                    "description": f"Missing documentation section: {section}",
-                    "location": repo_path,
-                }
-            )
-
-        # Add findings for low individual scores
-        score_thresholds = [
-            ("readme", doc_findings.readme_score, "README documentation"),
-            ("confluence", doc_findings.confluence_score, "Confluence documentation"),
-            ("api_docs", doc_findings.api_docs_score, "API documentation"),
-        ]
-
-        for dimension, score, label in score_thresholds:
-            if score < 5.0:
-                findings.append(
-                    {
-                        "type": "doc_quality",
-                        "severity": "warning" if score >= 3.0 else "error",
-                        "dimension": dimension,
-                        "description": f"{label} has low quality score ({score:.1f}/10.0)",
-                        "location": repo_path,
-                    }
-                )
-
-        # Add notes as informational findings
-        for note in doc_findings.notes:
-            findings.append(
-                {
-                    "type": "doc_quality_note",
-                    "severity": "info",
-                    "description": note,
-                    "location": repo_path,
-                }
-            )
-
-        return findings
-
-    async def _analyze_documents_individually(
-        self,
-        readme_files: list[Evidence],
-        confluence_pages: list[Evidence],
-    ) -> list[dict[str, Any]]:
-        """Analyze documents individually (fallback method).
-
-        Args:
-            readme_files: List of README evidence items.
-            confluence_pages: List of Confluence evidence items.
-
-        Returns:
-            List of findings from individual analysis.
-        """
-        findings: list[dict[str, Any]] = []
-
-        # Analyze README files
-        for readme in readme_files:
-            readme_findings = await self._analyze_document(
-                doc=readme,
-                doc_type="README",
-            )
-            findings.extend(readme_findings)
-
-        # Analyze Confluence pages
-        for page in confluence_pages:
-            page_findings = await self._analyze_document(
-                doc=page,
-                doc_type="Confluence",
-            )
-            findings.extend(page_findings)
-
-        return findings
-
-    async def _analyze_document(
-        self,
-        doc: Evidence,
-        doc_type: str,
-    ) -> list[dict[str, Any]]:
-        """Analyze a single document using LLM or heuristics.
-
-        Args:
-            doc: The Evidence object containing the document.
-            doc_type: Type of document (README, Confluence).
-
-        Returns:
-            List of findings from the analysis.
-        """
-        findings: list[dict[str, Any]] = []
-
-        # Skip empty or very short documents
-        if len(doc.content) < 50:
-            findings.append(
-                {
-                    "type": "doc_quality",
-                    "severity": "error",
-                    "dimension": "completeness",
-                    "description": f"{doc_type} '{doc.title}' has insufficient content ({len(doc.content)} chars)",
-                    "location": doc.source_url or doc.source_id,
-                }
-            )
-            return findings
-
-        # Attempt LLM analysis
-        if self.settings.enabled:
-            try:
-                analysis = await self._llm_analyze_quality(doc, doc_type)
-                findings.extend(self._convert_analysis_to_findings(analysis, doc, doc_type))
-            except Exception as e:
-                self.logger.warning(
-                    "llm_analysis_failed",
-                    doc_title=doc.title,
-                    doc_type=doc_type,
-                    error=str(e),
-                )
-                # Fall back to heuristic analysis
-                findings.extend(self._heuristic_analysis(doc, doc_type))
-        else:
-            # No LLM available, use heuristic analysis
-            findings.extend(self._heuristic_analysis(doc, doc_type))
-
-        return findings
-
-    async def _llm_analyze_quality(
-        self,
-        doc: Evidence,
-        doc_type: str,
-    ) -> DocumentationQualityOutput:
-        """Call LLM to analyze document quality (per-document analysis).
-
-        Args:
-            doc: The Evidence object containing the document.
-            doc_type: Type of document.
-
-        Returns:
-            Parsed JSON response from LLM.
-        """
-        # Truncate content if too long (keep first 8000 chars for analysis)
-        content = doc.content[:8000] if len(doc.content) > 8000 else doc.content
-
-        user_prompt = f"""Analyze this {doc_type} documentation:
-
-Title: {doc.title}
-Source: {doc.source_id}
-
-Content:
----
-{content}
----
-
-Provide quality assessment as JSON."""
-
-        return await self._run_pydantic_agent(
-            system_prompt=PER_DOC_QUALITY_SYSTEM_PROMPT,
-            user_prompt=user_prompt,
-            result_type=DocumentationQualityOutput,
-            complexity="standard",
-        )
-
-    def _convert_analysis_to_findings(
-        self,
-        analysis: DocumentationQualityOutput,
-        doc: Evidence,
-        doc_type: str,
-    ) -> list[dict[str, Any]]:
-        """Convert LLM analysis to standardized findings.
-
-        Args:
-            analysis: Parsed LLM response.
-            doc: The analyzed document.
-            doc_type: Type of document.
-
-        Returns:
-            List of finding dictionaries.
-        """
-        findings: list[dict[str, Any]] = []
-        location = doc.source_url or doc.source_id
-
-        # Add overall quality finding
-        overall_score = analysis.overall_score
-        severity = "error" if overall_score < 0.4 else "warning" if overall_score < 0.7 else "info"
-
-        findings.append(
-            {
-                "type": "doc_quality_assessment",
-                "severity": severity,
-                "description": f"{doc_type} '{doc.title}' quality score: {overall_score:.2f}/1.0",
-                "location": location,
-                "scores": {
-                    "completeness": analysis.completeness.score,
-                    "clarity": analysis.clarity.score,
-                    "currency": analysis.currency.score,
-                    "structure": analysis.structure.score,
-                    "overall": overall_score,
-                },
-                "summary": analysis.summary,
-                "recommendations": analysis.recommendations,
-            }
-        )
-
-        # Add specific dimension findings for low scores
-        dimension_map = {
-            "completeness": analysis.completeness,
-            "clarity": analysis.clarity,
-            "currency": analysis.currency,
-            "structure": analysis.structure,
-        }
-        for dimension, dim_data in dimension_map.items():
-            score = dim_data.score
-
-            if score < 0.5:
-                issues = dim_data.missing_sections or dim_data.issues or dim_data.outdated_indicators
-                findings.append(
-                    {
-                        "type": "doc_quality",
-                        "severity": "warning",
-                        "dimension": dimension,
-                        "description": f"{doc_type} '{doc.title}' has low {dimension} score ({score:.2f})",
-                        "location": location,
-                        "issues": issues,
-                        "notes": dim_data.notes,
-                    }
-                )
-
-        return findings
-
-    def _heuristic_analysis(
-        self,
-        doc: Evidence,
-        doc_type: str,
-    ) -> list[dict[str, Any]]:
-        """Perform heuristic analysis when LLM is unavailable.
-
-        Args:
-            doc: The Evidence object containing the document.
-            doc_type: Type of document.
-
-        Returns:
-            List of findings from heuristic analysis.
-        """
-        findings: list[dict[str, Any]] = []
-        content = doc.content.lower()
-        location = doc.source_url or doc.source_id
-
-        # Check for common required sections in README
-        if doc_type == "README":
-            required_sections = ["installation", "usage", "configuration"]
-            missing = [s for s in required_sections if s not in content]
-            if missing:
-                findings.append(
-                    {
-                        "type": "doc_quality",
-                        "severity": "warning",
-                        "dimension": "completeness",
-                        "description": f"README '{doc.title}' missing sections: {', '.join(missing)}",
-                        "location": location,
-                    }
-                )
-
-        # Check for outdated indicators
-        outdated_indicators = ["todo", "tbd", "fixme", "deprecated", "obsolete"]
-        found_indicators = [ind for ind in outdated_indicators if ind in content]
-        if found_indicators:
-            markers = ", ".join(found_indicators)
-            findings.append(
-                {
-                    "type": "doc_quality",
-                    "severity": "info",
-                    "dimension": "currency",
-                    "description": f"{doc_type} '{doc.title}' contains outdated markers: {markers}",
-                    "location": location,
-                }
-            )
-
-        # Check structure (heading presence)
-        if "#" not in doc.content and "<h" not in content:
-            findings.append(
-                {
-                    "type": "doc_quality",
-                    "severity": "warning",
-                    "dimension": "structure",
-                    "description": f"{doc_type} '{doc.title}' lacks proper heading structure",
-                    "location": location,
-                }
-            )
-
-        return findings