@ngocsangairvds/vsaf 3.2.14 → 3.2.15

package/tools/vds-scripts/audit_orchestrator/docs/CONTENT_ANALYSIS_APPROACH.md

@@ -1,1041 +0,0 @@
-# Content-Based Audit Scoring: Implementation Approach
-
-**Version:** 1.0.0
-**Status:** DRAFT
-**Created:** 2026-01-31
-
----
-
-## 1. Problem Statement
-
-Current audit scoring is **binary** (pass/fail based on existence). We need to evolve to **content-based scoring** that:
-
-1. **Analyzes audit checklist requirements** - Extract what each check is asking for
-2. **Gathers evidence from code/docs** - Find actual implementation in codebase and Confluence
-3. **Scores compliance level** - Graduated 0-10 based on evidence quality and completeness
-4. **Provides actionable feedback** - What's missing, what needs improvement
-
----
-
-## 2. Proposed Architecture
-
-```
-┌─────────────────────────────────────────────────────────────────────────────┐
-│                    CONTENT-BASED AUDIT SCORING FLOW                         │
-├─────────────────────────────────────────────────────────────────────────────┤
-│                                                                             │
-│  ┌──────────────────┐                                                       │
-│  │ AUDIT TEMPLATE   │  Contains checklist items with:                       │
-│  │ (Excel/Sheets)   │  - Check ID, Description, Expected Evidence          │
-│  └────────┬─────────┘  - Section, Weight, Severity                         │
-│           │                                                                 │
-│           ▼                                                                 │
-│  ┌──────────────────┐                                                       │
-│  │ REQUIREMENT      │  NLP extraction of:                                   │
-│  │ ANALYZER         │  - Key entities (files, APIs, configs)               │
-│  │                  │  - Compliance criteria keywords                       │
-│  └────────┬─────────┘  - Evidence type expected                            │
-│           │                                                                 │
-│           ▼                                                                 │
-│  ┌──────────────────────────────────────────────────────────────┐          │
-│  │                    EVIDENCE COLLECTORS                        │          │
-│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐           │          │
-│  │  │ Code        │  │ Confluence  │  │ External    │           │          │
-│  │  │ Analyzer    │  │ Analyzer    │  │ Systems     │           │          │
-│  │  │             │  │             │  │             │           │          │
-│  │  │ - Files     │  │ - Pages     │  │ - SonarQube │           │          │
-│  │  │ - Patterns  │  │ - Content   │  │ - Bitbucket │           │          │
-│  │  │ - Structure │  │ - Sections  │  │ - Jira      │           │          │
-│  │  └─────────────┘  └─────────────┘  └─────────────┘           │          │
-│  └────────┬─────────────────┬─────────────────┬─────────────────┘          │
-│           │                 │                 │                             │
-│           └─────────────────┼─────────────────┘                             │
-│                             ▼                                               │
-│  ┌──────────────────┐                                                       │
-│  │ SEMANTIC         │  Compare requirement vs evidence:                     │
-│  │ MATCHER          │  - Keyword matching                                   │
-│  │                  │  - Semantic similarity (embeddings)                   │
-│  └────────┬─────────┘  - Structure/completeness analysis                   │
-│           │                                                                 │
-│           ▼                                                                 │
-│  ┌──────────────────┐                                                       │
-│  │ COMPLIANCE       │  Calculate graduated score:                           │
-│  │ SCORER           │  - Evidence exists (0-2 pts)                         │
-│  │                  │  - Content matches requirement (0-4 pts)              │
-│  └────────┬─────────┘  - Quality/completeness (0-2 pts)                    │
-│           │            - Recency/maintenance (0-2 pts)                      │
-│           ▼                                                                 │
-│  ┌──────────────────┐                                                       │
-│  │ AUDIT RESULT     │  - Score: 0-10 per check                             │
-│  │                  │  - Maturity Level: 1-5                               │
-│  │                  │  - Evidence links                                     │
-│  └──────────────────┘  - Improvement recommendations                       │
-│                                                                             │
-└─────────────────────────────────────────────────────────────────────────────┘
-```
-
----
-
-## 3. Core Components
-
-### 3.1 Requirement Analyzer
-
-Extracts structured requirements from audit checklist descriptions.
-
-```python
-@dataclass
-class ExtractedRequirement:
-    """Structured requirement extracted from audit check description."""
-
-    check_id: str
-    raw_description: str
-
-    # Extracted entities
-    expected_files: list[str]           # e.g., ["README.md", "SECURITY.md"]
-    expected_sections: list[str]        # e.g., ["Installation", "Usage"]
-    expected_patterns: list[str]        # e.g., ["error handling", "logging"]
-    expected_configs: list[str]         # e.g., ["branch protection", "CI/CD"]
-
-    # Evidence type
-    evidence_type: EvidenceType         # CODE, DOCUMENTATION, CONFIG, METRIC
-    evidence_sources: list[str]         # Where to look for evidence
-
-    # Compliance keywords for matching
-    compliance_keywords: list[str]      # Key terms for semantic matching
-    required_elements: list[str]        # Must-have elements
-    optional_elements: list[str]        # Nice-to-have elements
-
-
-class RequirementAnalyzer:
-    """Extract structured requirements from audit descriptions."""
-
-    # Pattern matchers for common requirement types
-    FILE_PATTERNS = [
-        r"(?:must have|requires?|should have|contains?)\s+[`'\"]?(\w+\.\w+)[`'\"]?",
-        r"(?:file|document)\s+(?:named?|called)\s+[`'\"]?(\w+\.\w+)[`'\"]?",
-    ]
-
-    SECTION_PATTERNS = [
-        r"(?:section|heading|chapter)\s+(?:for|on|about)\s+[`'\"]?([^`'\"]+)[`'\"]?",
-        r"(?:must include|should have)\s+(?:a\s+)?[`'\"]?(\w+)[`'\"]?\s+section",
-    ]
-
-    CONFIG_PATTERNS = [
-        r"(?:enable|configure|set up)\s+[`'\"]?([^`'\"]+)[`'\"]?",
-        r"(?:branch protection|CI/CD|quality gate|coverage)",
-    ]
-
-    def analyze(self, check: AuditCheck) -> ExtractedRequirement:
-        """Extract structured requirement from check description."""
-        description = check.description.lower()
-
-        # Extract file references
-        expected_files = self._extract_files(description)
-
-        # Extract section requirements
-        expected_sections = self._extract_sections(description)
-
-        # Extract configuration requirements
-        expected_configs = self._extract_configs(description)
-
-        # Determine evidence type
-        evidence_type = self._determine_evidence_type(check)
-
-        # Extract compliance keywords using NLP
-        compliance_keywords = self._extract_keywords(description)
-
-        return ExtractedRequirement(
-            check_id=check.id,
-            raw_description=check.description,
-            expected_files=expected_files,
-            expected_sections=expected_sections,
-            expected_patterns=[],
-            expected_configs=expected_configs,
-            evidence_type=evidence_type,
-            evidence_sources=self._determine_sources(evidence_type),
-            compliance_keywords=compliance_keywords,
-            required_elements=self._extract_required(description),
-            optional_elements=self._extract_optional(description),
-        )
-```
-
-### 3.2 Evidence Collectors
-
-#### 3.2.1 Code Evidence Collector
-
-```python
-class CodeEvidenceCollector:
-    """Collect evidence from codebase."""
-
-    async def collect(
-        self,
-        repo_path: Path,
-        requirement: ExtractedRequirement,
-    ) -> list[Evidence]:
-        """Gather code evidence matching requirement."""
-        evidence_list = []
-
-        # 1. Check for expected files
-        for file_pattern in requirement.expected_files:
-            matches = await self._find_files(repo_path, file_pattern)
-            for match in matches:
-                content = await self._read_file(match)
-                evidence_list.append(Evidence(
-                    source="git_file",
-                    source_id=str(match),
-                    title=match.name,
-                    content=content,
-                    status=EvidenceStatus.FOUND,
-                ))
-
-        # 2. Search for patterns in code
-        for pattern in requirement.compliance_keywords:
-            matches = await self._search_content(repo_path, pattern)
-            for match in matches:
-                evidence_list.append(Evidence(
-                    source="git_file",
-                    source_id=match.file_path,
-                    title=Path(match.file_path).name,
-                    content=match.context,
-                    status=EvidenceStatus.FOUND,
-                ))
-
-        # 3. Analyze code structure
-        structure = await self._analyze_structure(repo_path)
-        evidence_list.append(Evidence(
-            source="git_file",
-            source_id=str(repo_path),
-            title=repo_path.name,
-            content=json.dumps(structure.to_dict(), indent=2),
-            status=EvidenceStatus.FOUND,
-            metadata={"content_type": "structure_analysis"},
-        ))
-
-        return evidence_list
-
-    async def _analyze_structure(self, repo_path: Path) -> CodeStructure:
-        """Analyze code structure for compliance indicators."""
-        return CodeStructure(
-            has_src_layout=await self._check_src_layout(repo_path),
-            has_tests=await self._check_tests(repo_path),
-            has_ci_config=await self._check_ci(repo_path),
-            has_dockerfile=await self._check_dockerfile(repo_path),
-            has_documentation=await self._check_docs(repo_path),
-            test_coverage=await self._get_coverage(repo_path),
-            type_hint_ratio=await self._check_type_hints(repo_path),
-        )
-```
-
-#### 3.2.2 Confluence Evidence Collector
-
-```python
-class ConfluenceEvidenceCollector:
-    """Collect evidence from Confluence documentation."""
-
-    def __init__(self, confluence_client: ConfluenceClient):
-        self.client = confluence_client
-
-    async def collect(
-        self,
-        requirement: ExtractedRequirement,
-        space_key: str,
-        project_name: str,
-    ) -> list[Evidence]:
-        """Gather Confluence documentation evidence."""
-        evidence_list = []
-
-        # 1. Search for relevant pages
-        search_queries = self._build_search_queries(requirement, project_name)
-
-        for query in search_queries:
-            pages = await self.client.search_content(
-                cql=f'space = "{space_key}" AND text ~ "{query}"',
-                limit=10,
-            )
-
-            for page in pages:
-                # Get full page content
-                content = await self.client.get_page_content(page.id)
-
-                # Analyze page structure
-                analysis = self._analyze_page_content(content)
-
-                evidence_list.append(Evidence(
-                    source="confluence_page",
-                    source_id=page.url,
-                    title=page.title,
-                    content=content,
-                    status=EvidenceStatus.FOUND,
-                    metadata={
-                        "page_id": page.id,
-                        "space": space_key,
-                        "last_modified": page.last_modified,
-                        "author": page.author,
-                        "analysis": analysis.model_dump(),
-                    },
-                ))
-
-        # 2. Check for specific documentation pages
-        for doc_type in requirement.expected_sections:
-            page = await self._find_documentation_page(
-                space_key, project_name, doc_type
-            )
-            if page:
-                evidence_list.append(await self._collect_page_evidence(page))
-
-        return evidence_list
-
-    def _analyze_page_content(self, content: str) -> ContentAnalysis:
-        """Analyze Confluence page content quality."""
-        soup = BeautifulSoup(content, "html.parser")
-
-        # Extract text content
-        text = soup.get_text()
-
-        # Analyze structure
-        headings = [h.text for h in soup.find_all(["h1", "h2", "h3", "h4"])]
-        code_blocks = soup.find_all("code") + soup.find_all("pre")
-        tables = soup.find_all("table")
-        images = soup.find_all("img")
-        links = soup.find_all("a")
-
-        return ContentAnalysis(
-            word_count=len(text.split()),
-            heading_count=len(headings),
-            headings=headings,
-            code_block_count=len(code_blocks),
-            table_count=len(tables),
-            image_count=len(images),
-            link_count=len(links),
-            has_toc="toc" in content.lower() or len(headings) > 5,
-            readability_score=self._calculate_readability(text),
-        )
-```
-
-### 3.3 Semantic Matcher
-
-Matches requirements against collected evidence using semantic analysis.
-
-```python
-class SemanticMatcher:
-    """Match requirements against evidence using semantic analysis."""
-
-    def __init__(self, embedding_model: str = "text-embedding-3-small"):
-        self.embedding_model = embedding_model
-        self._embeddings_cache: dict[str, list[float]] = {}
-
-    async def match(
-        self,
-        requirement: ExtractedRequirement,
-        evidence_list: list[Evidence],
-    ) -> MatchResult:
-        """Calculate semantic match between requirement and evidence."""
-
-        # 1. Keyword matching (fast, deterministic)
-        keyword_score = self._keyword_match(requirement, evidence_list)
-
-        # 2. Structural matching (check required elements)
-        structure_score = self._structure_match(requirement, evidence_list)
-
-        # 3. Semantic similarity (embeddings-based)
-        semantic_score = await self._semantic_match(requirement, evidence_list)
-
-        # 4. Completeness scoring
-        completeness_score = self._completeness_match(requirement, evidence_list)
-
-        # Weighted combination
-        final_score = (
-            keyword_score * 0.25 +
-            structure_score * 0.30 +
-            semantic_score * 0.25 +
-            completeness_score * 0.20
-        )
-
-        return MatchResult(
-            overall_score=final_score * 10,  # Scale to 0-10
-            keyword_score=keyword_score,
-            structure_score=structure_score,
-            semantic_score=semantic_score,
-            completeness_score=completeness_score,
-            matched_evidence=self._get_best_matches(evidence_list),
-            missing_elements=self._identify_gaps(requirement, evidence_list),
-        )
-
-    def _keyword_match(
-        self,
-        requirement: ExtractedRequirement,
-        evidence_list: list[Evidence],
-    ) -> float:
-        """Score based on keyword presence in evidence."""
-        if not requirement.compliance_keywords:
-            return 1.0  # No keywords required
-
-        all_evidence_text = " ".join(
-            e.content if isinstance(e.content, str) else str(e.content)
-            for e in evidence_list
-        ).lower()
-
-        matched = sum(
-            1 for kw in requirement.compliance_keywords
-            if kw.lower() in all_evidence_text
-        )
-
-        return matched / len(requirement.compliance_keywords)
-
-    def _structure_match(
-        self,
-        requirement: ExtractedRequirement,
-        evidence_list: list[Evidence],
-    ) -> float:
-        """Score based on structural requirements met."""
-        required = requirement.required_elements
-        if not required:
-            return 1.0
-
-        found = 0
-        for element in required:
-            for evidence in evidence_list:
-                if self._element_present(element, evidence):
-                    found += 1
-                    break
-
-        return found / len(required)
-
-    async def _semantic_match(
-        self,
-        requirement: ExtractedRequirement,
-        evidence_list: list[Evidence],
-    ) -> float:
-        """Score based on semantic similarity using embeddings."""
-        if not evidence_list:
-            return 0.0
-
-        # Get requirement embedding
-        req_embedding = await self._get_embedding(requirement.raw_description)
-
-        # Get evidence embeddings and find best match
-        max_similarity = 0.0
-        for evidence in evidence_list:
-            content = evidence.content if isinstance(evidence.content, str) else str(evidence.content)
-            if len(content) > 100:  # Only meaningful content
-                ev_embedding = await self._get_embedding(content[:2000])  # Truncate
-                similarity = self._cosine_similarity(req_embedding, ev_embedding)
-                max_similarity = max(max_similarity, similarity)
-
-        return max_similarity
-
-    def _completeness_match(
-        self,
-        requirement: ExtractedRequirement,
-        evidence_list: list[Evidence],
-    ) -> float:
-        """Score based on evidence completeness."""
-        if not evidence_list:
-            return 0.0
-
-        scores = []
-
-        # Check file existence
-        if requirement.expected_files:
-            found_files = sum(
-                1 for f in requirement.expected_files
-                if any(f in e.source_id for e in evidence_list)
-            )
-            scores.append(found_files / len(requirement.expected_files))
-
-        # Check section coverage
-        if requirement.expected_sections:
-            found_sections = 0
-            for section in requirement.expected_sections:
-                for evidence in evidence_list:
-                    if hasattr(evidence, 'analysis') and evidence.analysis:
-                        if section.lower() in [h.lower() for h in evidence.analysis.headings]:
-                            found_sections += 1
-                            break
-            scores.append(found_sections / len(requirement.expected_sections))
-
-        # Check content depth
-        for evidence in evidence_list:
-            if hasattr(evidence, 'analysis') and evidence.analysis:
-                depth_score = min(1.0, evidence.analysis.word_count / 500)  # 500 words = 1.0
-                scores.append(depth_score)
-
-        return sum(scores) / len(scores) if scores else 0.5
-```
-
-### 3.4 Compliance Scorer
-
-```python
-class ComplianceScorer:
-    """Calculate graduated compliance scores."""
-
-    def score(
-        self,
-        requirement: ExtractedRequirement,
-        evidence_list: list[Evidence],
-        match_result: MatchResult,
-    ) -> ComplianceScore:
-        """Calculate final compliance score with breakdown."""
-
-        # Component scores (each 0-1, scaled to weight)
-        existence_score = self._score_existence(evidence_list) * 2.0      # 0-2 pts
-        content_score = match_result.overall_score * 0.4                   # 0-4 pts
-        quality_score = self._score_quality(evidence_list) * 2.0          # 0-2 pts
-        recency_score = self._score_recency(evidence_list) * 2.0          # 0-2 pts
-
-        total_score = existence_score + content_score + quality_score + recency_score
-
-        # Determine maturity level
-        maturity = self._determine_maturity(total_score, evidence_list)
-
-        # Generate recommendations
-        recommendations = self._generate_recommendations(
-            requirement, evidence_list, match_result
-        )
-
-        return ComplianceScore(
-            check_id=requirement.check_id,
-            total_score=min(10.0, total_score),
-
-            # Score breakdown
-            existence_score=existence_score,
-            content_score=content_score,
-            quality_score=quality_score,
-            recency_score=recency_score,
-
-            # Maturity
-            maturity_level=maturity,
-
-            # Evidence
-            evidence_count=len(evidence_list),
-            evidence_sources=[e.source_id for e in evidence_list[:5]],
-
-            # Gaps and recommendations
-            missing_elements=match_result.missing_elements,
-            recommendations=recommendations,
-
-            # Confidence
-            confidence=self._calculate_confidence(evidence_list, match_result),
-        )
-
-    def _score_existence(self, evidence_list: list[Evidence]) -> float:
-        """Score for evidence existence (0-1)."""
-        if not evidence_list:
-            return 0.0
-        if len(evidence_list) >= 3:
-            return 1.0
-        return len(evidence_list) / 3.0
-
-    def _score_quality(self, evidence_list: list[Evidence]) -> float:
-        """Score for evidence quality (0-1)."""
-        if not evidence_list:
-            return 0.0
-
-        quality_scores = []
-        for evidence in evidence_list:
-            if hasattr(evidence, 'analysis') and evidence.analysis:
-                analysis = evidence.analysis
-
-                # Word count factor
-                word_factor = min(1.0, analysis.word_count / 1000)
-
-                # Structure factor
-                structure_factor = min(1.0, analysis.heading_count / 5)
-
-                # Code examples factor
-                code_factor = min(1.0, analysis.code_block_count / 3)
-
-                quality_scores.append(
-                    word_factor * 0.4 + structure_factor * 0.3 + code_factor * 0.3
-                )
-
-        return sum(quality_scores) / len(quality_scores) if quality_scores else 0.5
-
-    def _score_recency(self, evidence_list: list[Evidence]) -> float:
-        """Score for evidence recency (0-1)."""
-        if not evidence_list:
-            return 0.0
-
-        now = datetime.now(UTC)
-        recency_scores = []
-
-        for evidence in evidence_list:
-            if evidence.metadata and "last_modified" in evidence.metadata:
-                last_modified = evidence.metadata["last_modified"]
-                age_days = (now - last_modified).days
-
-                if age_days <= 30:
-                    recency_scores.append(1.0)
-                elif age_days <= 90:
-                    recency_scores.append(0.8)
-                elif age_days <= 180:
-                    recency_scores.append(0.6)
-                elif age_days <= 365:
-                    recency_scores.append(0.4)
-                else:
-                    recency_scores.append(0.2)
-
-        return sum(recency_scores) / len(recency_scores) if recency_scores else 0.5
-
-    def _determine_maturity(
-        self,
-        score: float,
-        evidence_list: list[Evidence],
-    ) -> MaturityLevel:
-        """Determine maturity level from score and evidence quality."""
-        # Base maturity from score
-        if score >= 8.0:
-            base_maturity = MaturityLevel.OPTIMIZING
-        elif score >= 6.0:
-            base_maturity = MaturityLevel.MANAGED
-        elif score >= 4.0:
-            base_maturity = MaturityLevel.DEFINED
-        elif score >= 2.0:
-            base_maturity = MaturityLevel.REPEATABLE
-        else:
-            base_maturity = MaturityLevel.INITIAL
-
-        # Adjust based on evidence characteristics
-        has_automation = any(
-            e.metadata and e.metadata.get("automation") for e in evidence_list
-        )
-        has_documentation = any(
-            e.source == "confluence_page" for e in evidence_list
-        )
-
-        if not has_documentation and base_maturity.value > 2:
-            # Can't be above REPEATABLE without documentation
-            return MaturityLevel.REPEATABLE
-
-        if not has_automation and base_maturity.value > 3:
-            # Can't be above DEFINED without automation evidence
-            return MaturityLevel.DEFINED
-
-        return base_maturity
-```
-
----
-
-## 4. Integration with Existing Checks
-
-### 4.1 Enhanced Check Base Class
-
-```python
-class ContentAwareCheck(BaseCheck):
-    """Base class for content-aware checks with evidence gathering."""
-
-    def __init__(self):
-        self.requirement_analyzer = RequirementAnalyzer()
-        self.code_collector = CodeEvidenceCollector()
-        self.confluence_collector = ConfluenceEvidenceCollector()
-        self.semantic_matcher = SemanticMatcher()
-        self.compliance_scorer = ComplianceScorer()
-
-    async def execute(self, context: CheckContext) -> CheckResult:
-        """Execute content-aware check with evidence gathering."""
-
-        # 1. Analyze requirement from check definition
-        requirement = self.requirement_analyzer.analyze(context.check)
-
-        # 2. Collect evidence from multiple sources
-        evidence_list = []
-
-        # Code evidence
-        if requirement.evidence_type in [EvidenceType.CODE, EvidenceType.ANY]:
-            code_evidence = await self.code_collector.collect(
-                context.repo_path, requirement
-            )
-            evidence_list.extend(code_evidence)
-
-        # Confluence evidence
-        if requirement.evidence_type in [EvidenceType.DOCUMENTATION, EvidenceType.ANY]:
-            if context.confluence_space:
-                confluence_evidence = await self.confluence_collector.collect(
-                    requirement,
-                    context.confluence_space,
-                    context.project_name,
-                )
-                evidence_list.extend(confluence_evidence)
-
-        # 3. Match requirement against evidence
-        match_result = await self.semantic_matcher.match(requirement, evidence_list)
-
-        # 4. Calculate compliance score
-        compliance = self.compliance_scorer.score(
-            requirement, evidence_list, match_result
-        )
-
-        # 5. Build result
-        return CheckResult(
-            check_id=context.check.id,
-            status=self._score_to_status(compliance.total_score),
-            score=compliance.total_score,
-            max_score=10.0,
-            maturity_level=compliance.maturity_level,
-            probes=[],  # Detailed probe results
-            evidence=[e.source_id for e in evidence_list],
-            confidence=compliance.confidence,
-            recommendations=compliance.recommendations,
-            execution_time_ms=0,
-            error_message=None,
-        )
-```
-
-### 4.2 Migrating Existing Checks
-
-```python
-# Example: Migrate git_file_exists to content-aware
-
-@CheckRegistry.register("git_file_exists")
-class GitFileExistsCheck(ContentAwareCheck):
-    """Content-aware file existence check with quality scoring."""
-
-    async def execute(self, context: CheckContext) -> CheckResult:
-        file_path = context.check_config.get("path", "README.md")
-        full_path = context.repo_path / file_path
-
-        # Basic existence
-        if not full_path.exists():
-            return CheckResult(
-                status=CheckStatus.FAIL,
-                score=0.0,
-                maturity_level=MaturityLevel.INITIAL,
-                evidence=[],
-                recommendations=[f"Create {file_path}"],
-            )
-
-        # Content analysis
-        content = full_path.read_text(errors="ignore")
-        analysis = self._analyze_content(content, file_path)
-
-        # Score based on content quality
-        score = self._calculate_score(analysis)
-
-        return CheckResult(
-            status=self._score_to_status(score),
-            score=score,
-            maturity_level=MaturityLevel.from_score(score),
-            evidence=[str(full_path)],
-            content_analysis=analysis,
-            recommendations=self._generate_recommendations(analysis),
-        )
-
-    def _analyze_content(self, content: str, file_path: str) -> ContentAnalysis:
-        """Analyze file content for quality metrics."""
-        lines = content.split("\n")
-        words = content.split()
-
-        # Detect sections (markdown headers)
-        sections = [
-            line.lstrip("#").strip()
-            for line in lines
-            if line.startswith("#")
-        ]
-
-        # Detect code blocks
-        code_blocks = content.count("```")
-
-        return ContentAnalysis(
-            exists=True,
-            file_path=file_path,
-            word_count=len(words),
-            line_count=len(lines),
-            section_count=len(sections),
-            sections_found=sections,
-            code_block_count=code_blocks // 2,
-            link_count=content.count("]("),
-            image_count=content.count("!["),
-            readability_score=self._flesch_kincaid(content),
-        )
-
-    def _calculate_score(self, analysis: ContentAnalysis) -> float:
-        """Calculate graduated score from content analysis."""
-        score = 0.0
-
-        # Existence (2 pts)
-        score += 2.0
-
-        # Content depth (0-3 pts based on word count)
-        if analysis.word_count >= 500:
-            score += 3.0
-        elif analysis.word_count >= 200:
-            score += 2.0
-        elif analysis.word_count >= 100:
-            score += 1.0
-
-        # Structure (0-2 pts based on sections)
-        if analysis.section_count >= 5:
-            score += 2.0
-        elif analysis.section_count >= 3:
-            score += 1.0
-
-        # Examples (0-2 pts based on code blocks)
-        if analysis.code_block_count >= 3:
-            score += 2.0
-        elif analysis.code_block_count >= 1:
-            score += 1.0
-
-        # Links/references (0-1 pt)
-        if analysis.link_count >= 3:
-            score += 1.0
-
-        return min(10.0, score)
-```
-
----
-
-## 5. Confluence Integration
-
-### 5.1 Documentation Mapping
-
-Map audit requirements to expected Confluence pages:
-
-```python
-DOCUMENTATION_MAPPING = {
-    # Check type -> Expected Confluence page patterns
-    "architecture_doc": [
-        "{project}-architecture",
-        "{project}-design",
-        "architecture-overview",
-    ],
-    "api_documentation": [
-        "{project}-api",
-        "api-reference",
-        "api-documentation",
-    ],
-    "deployment_guide": [
-        "{project}-deployment",
-        "deployment-guide",
-        "runbook",
-    ],
-    "security_documentation": [
-        "{project}-security",
-        "security-guidelines",
-        "threat-model",
-    ],
-    "onboarding_guide": [
-        "{project}-onboarding",
-        "getting-started",
-        "developer-guide",
-    ],
-}
-
-
-class ConfluenceDocumentationChecker:
-    """Check documentation completeness in Confluence."""
-
-    async def check_documentation_exists(
-        self,
-        doc_type: str,
-        project_name: str,
-        space_key: str,
-    ) -> tuple[bool, list[Evidence]]:
-        """Check if required documentation exists."""
-        patterns = DOCUMENTATION_MAPPING.get(doc_type, [])
-
-        for pattern in patterns:
-            page_title = pattern.format(project=project_name)
-            page = await self.client.get_page_by_title(space_key, page_title)
-
-            if page:
-                content = await self.client.get_page_content(page.id)
-                analysis = self._analyze_page_content(content)
-
-                return True, [Evidence(
-                    source="confluence_page",
-                    source_id=page.url,
-                    title=page.title,
-                    content=content,
-                    status=EvidenceStatus.FOUND,
-                    metadata={
-                        "page_id": page.id,
-                        "last_modified": page.last_modified,
-                        "analysis": analysis.model_dump(),
-                    },
-                )]
-
-        return False, []
-```
-
-### 5.2 Content Quality Scoring for Confluence
-
-```python
-class ConfluenceContentScorer:
-    """Score Confluence documentation quality."""
-
-    SECTION_WEIGHTS = {
-        # Architecture docs
-        "overview": 1.5,
-        "components": 2.0,
-        "data flow": 1.5,
-        "dependencies": 1.0,
-        "decisions": 1.0,
-
-        # API docs
-        "endpoints": 2.0,
-        "authentication": 1.5,
-        "examples": 2.0,
-        "errors": 1.0,
-
-        # Deployment docs
-        "prerequisites": 1.0,
-        "installation": 2.0,
-        "configuration": 1.5,
-        "troubleshooting": 1.0,
-    }
-
-    def score(self, content: str, doc_type: str) -> float:
-        """Score Confluence page content quality."""
-        analysis = self._analyze(content)
-
-        # Section coverage score
-        required_sections = self._get_required_sections(doc_type)
-        found_sections = [
-            s.lower() for s in analysis.headings
-        ]
-
-        section_score = sum(
-            self.SECTION_WEIGHTS.get(section, 1.0)
-            for section in required_sections
-            if any(section in h for h in found_sections)
-        ) / sum(self.SECTION_WEIGHTS.get(s, 1.0) for s in required_sections)
-
-        # Content depth score
-        depth_score = min(1.0, analysis.word_count / 1000)
-
-        # Quality indicators
-        quality_score = (
-            (0.2 if analysis.code_block_count >= 2 else 0.0) +
-            (0.2 if analysis.table_count >= 1 else 0.0) +
-            (0.2 if analysis.image_count >= 1 else 0.0) +
-            (0.2 if analysis.link_count >= 5 else 0.0) +
-            (0.2 if analysis.has_toc else 0.0)
-        )
-
-        # Combined score (0-10)
-        total = (section_score * 4 + depth_score * 3 + quality_score * 3)
-
-        return min(10.0, total)
-```
-
----
-
-## 6. Implementation Roadmap
-
-### Phase 1: Core Infrastructure (Sprint 1-2)
-
-| Task | Description | Effort |
-|------|-------------|--------|
-| TSK-501 | Implement `RequirementAnalyzer` | M |
-| TSK-502 | Implement `Evidence` and `ContentAnalysis` models | S |
-| TSK-503 | Implement `CodeEvidenceCollector` | M |
-| TSK-504 | Implement `SemanticMatcher` (keyword-based first) | M |
-| TSK-505 | Implement `ComplianceScorer` | M |
-
-### Phase 2: Confluence Integration (Sprint 3)
-
-| Task | Description | Effort |
-|------|-------------|--------|
-| TSK-601 | Implement `ConfluenceEvidenceCollector` | M |
-| TSK-602 | Add Confluence page content analysis | M |
-| TSK-603 | Create documentation mapping config | S |
-| TSK-604 | Integrate with existing Confluence checks | M |
-
-### Phase 3: Semantic Analysis (Sprint 4)
-
-| Task | Description | Effort |
-|------|-------------|--------|
-| TSK-701 | Add embedding-based semantic matching | L |
-| TSK-702 | Implement similarity scoring | M |
-| TSK-703 | Add gap detection and recommendations | M |
-
-### Phase 4: Check Migration (Sprint 5-6)
-
-| Task | Description | Effort |
-|------|-------------|--------|
-| TSK-801 | Migrate `git_file_exists` to content-aware | M |
-| TSK-802 | Migrate `git_file_content` to content-aware | M |
-| TSK-803 | Migrate `confluence_page_exists` to content-aware | M |
-| TSK-804 | Create new documentation quality checks | L |
-
----
-
-## 7. Configuration Schema
-
-LLM-based analysis can be slow for large evidence sets. Use batching, evidence
-readiness gates, and grounding validation to keep latency bounded and ensure
-the output stays anchored to real code and Confluence artifacts.
-
-```yaml
-# audit_config.yaml
-content_analysis:
-  # Enable content-based scoring
-  enabled: true
-
-  # Minimum score thresholds by maturity level
-  maturity_thresholds:
-    initial: 0
-    repeatable: 2
-    defined: 4
-    managed: 6
-    optimizing: 8
-
-  # Evidence collection settings
-  evidence_collection:
-    code:
-      enabled: true
-      max_file_size_kb: 500
-      search_depth: 3
-
-    confluence:
-      enabled: true
-      spaces:
-        - key: "INS"
-          name: "Insurance Project"
-        - key: "VDS"
-          name: "VDS Platform"
-      search_limit: 10
-
-  # Evidence readiness gate (prevents low-signal LLM runs)
-  evidence_readiness:
-    enabled: true
-    min_docs: 5
-    min_code_files: 3
-    evidence_project: null
-    max_evidence_chars: 8000
-
-  # Grounding validation (require evidence anchors)
-  grounding:
-    strict: false
-
-  # Batch controls for LLM analysis
-  batch:
-    size: 5
-    row_timeout_ms: 45000
-    batch_timeout_ms: null
-    resume: false
-    checkpoint_dir: null
-
-  # Semantic matching settings
-  semantic_matching:
-    enabled: true
-    model: "text-embedding-3-small"
-    similarity_threshold: 0.7
-
-  # Scoring weights
-  scoring_weights:
-    existence: 0.2
-    content_match: 0.4
-    quality: 0.2
-    recency: 0.2
-```
-
----
-
-## 8. References
-
-- [TrustCloud - Automating Evidence Collection](https://www.trustcloud.ai/security-questionnaires/automating-evidence-collection-for-regulatory-compliance-tools-best-practices/)
-- [Secureframe - Automated Evidence Collection](https://secureframe.com/blog/automated-evidence-collection)
-- [Cloud Security Alliance - Compliance Automation](https://cloudsecurityalliance.org/blog/2025/04/29/a-new-era-for-compliance-introducing-the-compliance-automation-revolution-car)
-- [IBM - NLP for Data Analysis](https://ibm.com)
-- [Semantic Similarity with Transformers](https://medium.com)