@ngocsangairvds/vsaf 3.2.14 → 3.2.16

package/tools/vds-scripts/audit_orchestrator/tests/unit/completeness/test_material_completeness_service.py

@@ -1,2736 +0,0 @@
-"""Unit tests for MaterialCompletenessService (Phase 126, TSK-126.1, TSK-126.15).
-
-Comprehensive unit tests for the material completeness checking service covering:
-- Service construction and initialization
-- Requirement discovery from multiple sources
-- Cache validation for different material types
-- Metrics computation
-- Action generation
-- Helper methods
-- Main entry point workflow
-
-Reference: .kiro/specs/audit-orchestrator/requirements.md FR-126.1
-Phase 126 Package A (TSK-126.1) + Package E (TSK-126.15)
-"""
-
-from __future__ import annotations
-
-from datetime import UTC, datetime, timedelta
-from pathlib import Path
-from typing import Any
-from unittest.mock import AsyncMock, MagicMock, patch
-
-import pytest
-from vds_audit_orchestrator.collectors.completeness.material_completeness_service import (
-    MaterialCompletenessService,
-    RequirementDiscoveryError,
-)
-from vds_audit_orchestrator.collectors.material_cache import MaterialCache
-from vds_audit_orchestrator.models.completeness import (
-    CompletenessMetrics,
-    CompletenessReport,
-    FreshnessTier,
-    MaterialRequirement,
-    MaterialType,
-    MissingMaterial,
-    PreparedMaterial,
-    StaleMaterial,
-)
-
-# ===========================================================================
-# Helpers
-# ===========================================================================
-
-
-def _make_state_store(
-    project_links: list[dict] | None = None,
-    project_preparation: dict | None = None,
-) -> MagicMock:
-    """Create a mock PostgresStateStore."""
-    store = MagicMock()
-    store.get_project_links = AsyncMock(return_value=project_links or [])
-    store.get_project_preparation = AsyncMock(return_value=project_preparation or {})
-    return store
-
-
-def _make_cache() -> MaterialCache:
-    """Create a test MaterialCache."""
-    return MaterialCache(cache_dir=Path("/tmp/test_cache"))
-
-
-def _make_registry_parser(enabled: bool = True) -> MagicMock | None:
-    """Create a mock RegistryPageParser."""
-    if not enabled:
-        return None
-    parser = MagicMock()
-    parser.parse_page_links = AsyncMock(return_value=[])
-    return parser
-
-
-def _make_requirement(
-    material_type: MaterialType = MaterialType.page,
-    identifier: str = "88718940",
-    project_key: str = "CEP",
-    source: str = "registry",
-    priority: int = 10,
-    title: str | None = None,
-) -> MaterialRequirement:
-    """Create a MaterialRequirement for testing."""
-    return MaterialRequirement(
-        material_type=material_type,
-        identifier=identifier,
-        project_key=project_key,
-        source=source,
-        priority=priority,
-        title=title or f"Test {material_type.value}",
-    )
-
-
-def _make_cache_entry(
-    material_type: MaterialType = MaterialType.page,
-    identifier: str = "88718940",
-    age_hours: float = 2.0,
-    version: str | None = None,
-) -> dict[str, Any]:
-    """Create a mock cache entry."""
-    now = datetime.now(UTC)
-    cached_at = now - timedelta(hours=age_hours)
-
-    if material_type == MaterialType.page:
-        entry = {
-            "page_id": identifier,
-            "cached_at": cached_at.isoformat(),
-            "title": "Cached page",
-            "project_key": "CEP",
-        }
-    elif material_type == MaterialType.attachment:
-        entry = {
-            "attachment_id": identifier,
-            "page_id": "88718940",  # Attachments always have a page_id
-            "cached_at": cached_at.isoformat(),
-            "title": "Cached attachment",
-            "project_key": "CEP",
-            "cache_paths": {},
-            "hashes": {},
-        }
-    else:  # repo
-        entry = {
-            "repo": identifier,
-            "cached_at": cached_at.isoformat(),
-            "title": "Cached repo",
-            "project_key": "CEP",
-        }
-
-    if version:
-        entry["version"] = version
-    return entry
-
-
-def _make_metrics(**overrides: Any) -> CompletenessMetrics:
-    """Create CompletenessMetrics for testing."""
-    now = datetime.now(UTC)
-    defaults = {
-        "total_required": 10,
-        "total_prepared": 8,
-        "total_missing": 2,
-        "total_stale": 1,
-        "total_aging": 2,
-        "completeness_pct": 80.0,
-        "freshness_pct": 62.5,
-        "avg_freshness_hours": 18.5,
-        "cache_hit_rate": 80.0,
-        "deep_checked": False,
-        "checked_at": now,
-    }
-    defaults.update(overrides)
-    return CompletenessMetrics(**defaults)
-
-
-# ===========================================================================
-# Service Construction Tests
-# ===========================================================================
-
-
-class TestMaterialCompletenessServiceConstruction:
-    """Tests for service construction and initialization (20 tests)."""
-
-    def test_default_initialization(self):
-        """Service should initialize with required dependencies."""
-        state = _make_state_store()
-        cache = _make_cache()
-
-        service = MaterialCompletenessService(state, cache)
-
-        assert service.state is state
-        assert service.cache is cache
-        assert service.registry is None
-        assert service.config_path == MaterialCompletenessService.DEFAULT_CONFIG_PATH
-
-    def test_with_registry_parser(self):
-        """Service should accept optional registry parser."""
-        state = _make_state_store()
-        cache = _make_cache()
-        registry = _make_registry_parser()
-
-        service = MaterialCompletenessService(state, cache, registry_parser=registry)
-
-        assert service.registry is registry
-
-    def test_with_custom_config_path(self, tmp_path: Path):
-        """Service should accept custom config path."""
-        state = _make_state_store()
-        cache = _make_cache()
-        custom_path = tmp_path / "custom-config.yaml"
-
-        service = MaterialCompletenessService(state, cache, config_path=custom_path)
-
-        assert service.config_path == custom_path
-
-    def test_default_config_path_location(self):
-        """Default config path should be ~/.vds/config/material-requirements.yaml."""
-        from pathlib import Path
-
-        expected = Path.home() / ".vds" / "config" / "material-requirements.yaml"
-        assert expected == MaterialCompletenessService.DEFAULT_CONFIG_PATH
-
-
-# ===========================================================================
-# Requirement Discovery Tests
-# ===========================================================================
-
-
-class TestDiscoverFromRegistry:
-    """Tests for registry-based requirement discovery (15 tests)."""
-
-    @pytest.mark.asyncio
-    async def test_discover_from_registry_with_confluence_links(self):
-        """Should extract page requirements from Confluence links."""
-        state = _make_state_store(
-            project_links=[
-                {
-                    "link_type": "confluence",
-                    "link_role": "page",
-                    "normalized_url": "http://confluence/pages/88718940",
-                    "title": "Test Page",
-                },
-                {
-                    "link_type": "confluence",
-                    "link_role": "attachment",
-                    "normalized_url": "http://confluence/pages/88718941",
-                    "title": "Test Attachment",
-                },
-            ]
-        )
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        requirements = await service._discover_from_registry("88718940")
-
-        assert len(requirements) == 2
-        assert requirements[0].material_type == MaterialType.page
-        assert requirements[0].identifier == "88718940"
-        assert requirements[0].source == "registry"
-        assert requirements[1].material_type == MaterialType.attachment
-        assert requirements[1].identifier == "88718941"
-
-    @pytest.mark.asyncio
-    async def test_discover_from_registry_extracts_page_id(self):
-        """Should extract page_id from various URL formats."""
-        state = _make_state_store(
-            project_links=[
-                {"link_type": "confluence", "link_role": "page", "normalized_url": "http://confluence/pages/12345"},
-                {"link_type": "confluence", "link_role": "page", "normalized_url": "http://confluence?pageId=67890"},
-            ]
-        )
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        requirements = await service._discover_from_registry("88718940")
-
-        assert len(requirements) == 2
-        assert requirements[0].identifier == "12345"
-        assert requirements[1].identifier == "67890"
-
-    @pytest.mark.asyncio
-    async def test_discover_from_registry_skips_non_confluence(self):
-        """Should skip non-Confluence links."""
-        state = _make_state_store(
-            project_links=[
-                {"link_type": "http", "link_role": "page", "normalized_url": "http://example.com"},
-                {"link_type": "bitbucket", "link_role": "repo", "normalized_url": "http://bitbucket/repo"},
-            ]
-        )
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        requirements = await service._discover_from_registry("88718940")
-
-        assert len(requirements) == 0
-
-    @pytest.mark.asyncio
-    async def test_discover_from_registry_bitbucket_role(self):
-        """Should map bitbucket link_role to repo material type."""
-        state = _make_state_store(
-            project_links=[
-                {"link_type": "confluence", "link_role": "bitbucket", "normalized_url": "http://bitbucket/CEP/repo"},
-                {"link_type": "confluence", "link_role": "repository", "normalized_url": "http://bitbucket/CEP/repo2"},
-            ]
-        )
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        requirements = await service._discover_from_registry("88718940")
-
-        assert len(requirements) == 2
-        assert all(req.material_type == MaterialType.repo for req in requirements)
-
-    @pytest.mark.asyncio
-    async def test_discover_from_registry_captures_title(self):
-        """Should capture link title in requirement."""
-        title = "Important Documentation Page"
-        state = _make_state_store(
-            project_links=[
-                {
-                    "link_type": "confluence",
-                    "link_role": "page",
-                    "normalized_url": "http://confluence/pages/123",
-                    "title": title,
-                },
-            ]
-        )
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        requirements = await service._discover_from_registry("88718940")
-
-        assert len(requirements) == 1
-        assert requirements[0].title == title
-
-    @pytest.mark.asyncio
-    async def test_discover_from_registry_empty_links(self):
-        """Should return empty list when no links found."""
-        state = _make_state_store(project_links=[])
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        requirements = await service._discover_from_registry("88718940")
-
-        assert requirements == []
-
-    @pytest.mark.asyncio
-    async def test_discover_from_registry_handles_link_without_page_id(self):
-        """Should skip links that don't contain extractable page_id."""
-        state = _make_state_store(
-            project_links=[
-                {"link_type": "confluence", "link_role": "page", "normalized_url": "http://confluence/invalid"},
-            ]
-        )
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        requirements = await service._discover_from_registry("88718940")
-
-        assert requirements == []
-
-    @pytest.mark.asyncio
-    async def test_discover_from_registry_sets_metadata(self):
-        """Should include link metadata in requirement."""
-        state = _make_state_store(
-            project_links=[
-                {
-                    "link_type": "confluence",
-                    "link_role": "page",
-                    "normalized_url": "http://c/p/123",
-                    "raw_url": "http://original",
-                },
-            ]
-        )
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        requirements = await service._discover_from_registry("88718940")
-
-        assert len(requirements) == 1
-        assert requirements[0].metadata["link_role"] == "page"
-        assert requirements[0].metadata["raw_url"] == "http://original"
-
-    @pytest.mark.asyncio
-    async def test_discover_from_registry_default_priority(self):
-        """Should set default priority for registry requirements."""
-        state = _make_state_store(
-            project_links=[
-                {"link_type": "confluence", "link_role": "page", "normalized_url": "http://c/p/123"},
-            ]
-        )
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        requirements = await service._discover_from_registry("88718940")
-
-        assert requirements[0].priority == 10
-
-    @pytest.mark.asyncio
-    async def test_discover_from_registry_no_registry_parser(self):
-        """Should return empty list when registry parser is None."""
-        state = _make_state_store()
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache, registry_parser=None)
-
-        requirements = await service._discover_from_registry("88718940")
-
-        assert requirements == []
-
-    @pytest.mark.asyncio
-    async def test_discover_from_registry_handles_api_error_gracefully(self):
-        """Should log warning and continue if state.get_project_links fails."""
-        state = _make_state_store()
-        state.get_project_links = AsyncMock(side_effect=Exception("API error"))
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        requirements = await service._discover_from_registry("88718940")
-
-        assert requirements == []
-
-    @pytest.mark.asyncio
-    async def test_discover_from_registry_deduplicates_by_key(self):
-        """Should deduplicate requirements with same key."""
-        state = _make_state_store(
-            project_links=[
-                {"link_type": "confluence", "link_role": "page", "normalized_url": "http://c/p/123", "title": "First"},
-                {
-                    "link_type": "confluence",
-                    "link_role": "page",
-                    "normalized_url": "http://c/p/123",
-                    "title": "Duplicate",
-                },
-            ]
-        )
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        requirements = await service._discover_from_registry("88718940")
-
-        assert len(requirements) == 1
-
-
-class TestDiscoverFromChecklist:
-    """Tests for checklist-based requirement discovery (15 tests)."""
-
-    @pytest.mark.asyncio
-    async def test_discover_from_checklist_with_pages(self):
-        """Should extract page requirements from artifacts."""
-        state = _make_state_store(
-            project_preparation={
-                "sync_metadata": {
-                    "artifacts": [
-                        {"page_id": "88718940", "type": "page", "title": "Page 1"},
-                        {"page_id": "88718941", "type": "page", "title": "Page 2"},
-                    ]
-                }
-            }
-        )
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        requirements = await service._discover_from_checklist("88718940")
-
-        assert len(requirements) == 2
-        assert all(req.material_type == MaterialType.page for req in requirements)
-        assert all(req.source == "checklist" for req in requirements)
-
-    @pytest.mark.asyncio
-    async def test_discover_from_checklist_with_attachments(self):
-        """Should extract attachment requirements from artifacts."""
-        state = _make_state_store(
-            project_preparation={
-                "sync_metadata": {
-                    "artifacts": [
-                        {"page_id": "88718940", "attachment_id": "att1", "type": "attachment", "title": "File1.pdf"},
-                        {"page_id": "88718940", "attachment_id": "att2", "type": "attachment", "title": "File2.pdf"},
-                    ]
-                }
-            }
-        )
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        requirements = await service._discover_from_checklist("88718940")
-
-        assert len(requirements) == 2
-        assert all(req.material_type == MaterialType.attachment for req in requirements)
-        assert requirements[0].identifier == "att1"
-        assert requirements[1].identifier == "att2"
-
-    @pytest.mark.asyncio
-    async def test_discover_from_checklist_with_repos(self):
-        """Should extract repo requirements from artifacts."""
-        state = _make_state_store(
-            project_preparation={
-                "sync_metadata": {
-                    "artifacts": [
-                        {"page_id": "88718940", "repo_key": "merchant-report", "type": "repo"},
-                        {"page_id": "88718941", "repo_key": "merchant-billing", "type": "bitbucket"},
-                    ]
-                }
-            }
-        )
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        requirements = await service._discover_from_checklist("88718940")
-
-        assert len(requirements) == 2
-        assert all(req.material_type == MaterialType.repo for req in requirements)
-        assert requirements[0].identifier == "merchant-report"
-        assert requirements[1].identifier == "merchant-billing"
-
-    @pytest.mark.asyncio
-    async def test_discover_from_checklist_empty_preparation(self):
-        """Should return empty list when no preparation data."""
-        state = _make_state_store(project_preparation=None)
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        requirements = await service._discover_from_checklist("88718940")
-
-        assert requirements == []
-
-    @pytest.mark.asyncio
-    async def test_discover_from_checklist_no_sync_metadata(self):
-        """Should return empty list when sync_metadata missing."""
-        state = _make_state_store(project_preparation={})
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        requirements = await service._discover_from_checklist("88718940")
-
-        assert requirements == []
-
-    @pytest.mark.asyncio
-    async def test_discover_from_checklist_no_artifacts(self):
-        """Should return empty list when artifacts list empty."""
-        state = _make_state_store(project_preparation={"sync_metadata": {"artifacts": []}})
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        requirements = await service._discover_from_checklist("88718940")
-
-        assert requirements == []
-
-    @pytest.mark.asyncio
-    async def test_discover_from_checklist_mixed_types(self):
-        """Should handle mixed page/attachment/repo artifacts."""
-        state = _make_state_store(
-            project_preparation={
-                "sync_metadata": {
-                    "artifacts": [
-                        {"page_id": "88718940", "type": "page"},
-                        {"page_id": "88718940", "attachment_id": "att1", "type": "attachment"},
-                        {"page_id": "88718940", "repo_key": "repo1", "type": "repo"},
-                    ]
-                }
-            }
-        )
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        requirements = await service._discover_from_checklist("88718940")
-
-        assert len(requirements) == 3
-        assert requirements[0].material_type == MaterialType.page
-        assert requirements[1].material_type == MaterialType.attachment
-        assert requirements[2].material_type == MaterialType.repo
-
-    @pytest.mark.asyncio
-    async def test_discover_from_checklist_attachment_uses_page_id(self):
-        """Should use page_id for attachment when attachment_id missing."""
-        state = _make_state_store(
-            project_preparation={
-                "sync_metadata": {
-                    "artifacts": [
-                        {"page_id": "88718940", "type": "attachment"},
-                    ]
-                }
-            }
-        )
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        requirements = await service._discover_from_checklist("88718940")
-
-        assert len(requirements) == 1
-        assert requirements[0].material_type == MaterialType.attachment
-        assert requirements[0].identifier == "88718940"
-
-    @pytest.mark.asyncio
-    async def test_discover_from_checklist_captures_title(self):
-        """Should capture artifact title in requirement."""
-        title = "Important Document"
-        state = _make_state_store(
-            project_preparation={
-                "sync_metadata": {
-                    "artifacts": [
-                        {"page_id": "88718940", "type": "page", "title": title},
-                    ]
-                }
-            }
-        )
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        requirements = await service._discover_from_checklist("88718940")
-
-        assert len(requirements) == 1
-        assert requirements[0].title == title
-
-    @pytest.mark.asyncio
-    async def test_discover_from_checklist_default_priority(self):
-        """Should set default priority for checklist requirements."""
-        state = _make_state_store(
-            project_preparation={
-                "sync_metadata": {
-                    "artifacts": [
-                        {"page_id": "88718940", "type": "page"},
-                    ]
-                }
-            }
-        )
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        requirements = await service._discover_from_checklist("88718940")
-
-        assert requirements[0].priority == 20
-
-    @pytest.mark.asyncio
-    async def test_discover_from_checklist_includes_artifact_type(self):
-        """Should include artifact type in metadata."""
-        state = _make_state_store(
-            project_preparation={
-                "sync_metadata": {
-                    "artifacts": [
-                        {"page_id": "88718940", "type": "custom_type", "title": "Custom"},
-                    ]
-                }
-            }
-        )
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        requirements = await service._discover_from_checklist("88718940")
-
-        assert len(requirements) == 1
-        assert requirements[0].metadata["artifact_type"] == "custom_type"
-
-    @pytest.mark.asyncio
-    async def test_discover_from_checklist_handles_invalid_artifacts(self):
-        """Should skip invalid artifact entries."""
-        state = _make_state_store(
-            project_preparation={
-                "sync_metadata": {
-                    "artifacts": [
-                        "not_a_dict",
-                        {"page_id": "88718940", "type": "page"},  # valid
-                        None,
-                    ]
-                }
-            }
-        )
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        requirements = await service._discover_from_checklist("88718940")
-
-        assert len(requirements) == 1
-
-    @pytest.mark.asyncio
-    async def test_discover_from_checklist_handles_api_error(self):
-        """Should log warning and continue if state.get_project_preparation fails."""
-        state = _make_state_store()
-        state.get_project_preparation = AsyncMock(side_effect=Exception("DB error"))
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        requirements = await service._discover_from_checklist("88718940")
-
-        assert requirements == []
-
-
-class TestLoadConfigRequirements:
-    """Tests for config file requirement loading (15 tests)."""
-
-    def test_load_config_from_nonexistent_file(self):
-        """Should return empty list when config file doesn't exist."""
-        state = _make_state_store()
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache, config_path=Path("/nonexistent/config.yaml"))
-
-        requirements = service._load_config_requirements("88718940")
-
-        assert requirements == []
-
-    def test_load_config_global_requirements(self, tmp_path: Path):
-        """Should load global requirements from config file."""
-        config_path = tmp_path / "material-requirements.yaml"
-        config_path.write_text(
-            """
-requirements:
-  - material_type: page
-    identifier: "88718940"
-    project_key: "CEP"
-    priority: 100
-  - material_type: repo
-    identifier: "merchant-report"
-    project_key: "PAR"
-    priority: 100
-""",
-            encoding="utf-8",
-        )
-
-        state = _make_state_store()
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache, config_path=config_path)
-
-        requirements = service._load_config_requirements("88718940")
-
-        assert len(requirements) == 2
-        assert requirements[0].material_type == MaterialType.page
-        assert requirements[0].priority == 100
-        assert requirements[1].material_type == MaterialType.repo
-
-    def test_load_config_project_specific_overrides(self, tmp_path: Path):
-        """Should load project-specific requirements and override global."""
-        config_path = tmp_path / "material-requirements.yaml"
-        config_path.write_text(
-            """
-requirements:
-  - material_type: page
-    identifier: "global-page"
-    project_key: "global"
-    priority: 50
-projects:
-  88718940:
-    requirements:
-      - material_type: page
-        identifier: "local-page"
-        project_key: "88718940"
-        priority: 150
-""",
-            encoding="utf-8",
-        )
-
-        state = _make_state_store()
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache, config_path=config_path)
-
-        requirements = service._load_config_requirements("88718940")
-
-        # Should have both global and project-specific
-        assert len(requirements) == 2
-        # Project-specific has higher priority
-        local_req = next(r for r in requirements if r.identifier == "local-page")
-        assert local_req.priority == 150
-
-    def test_load_config_resolves_project_key_in_overrides(self, tmp_path: Path):
-        """Should use provided project_key for global requirements."""
-        config_path = tmp_path / "material-requirements.yaml"
-        config_path.write_text(
-            """
-requirements:
-  - material_type: page
-    identifier: "88718940"
-    priority: 100
-""",
-            encoding="utf-8",
-        )
-
-        state = _make_state_store()
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache, config_path=config_path)
-
-        requirements = service._load_config_requirements("CEP")
-
-        # Config requirement should inherit project_key from parameter
-        assert len(requirements) == 1
-        assert requirements[0].project_key == "CEP"
-
-    def test_load_config_with_invalid_material_type(self, tmp_path: Path):
-        """Should skip requirements with invalid material_type."""
-        config_path = tmp_path / "material-requirements.yaml"
-        config_path.write_text(
-            """
-requirements:
-  - material_type: invalid_type
-    identifier: "88718940"
-""",
-            encoding="utf-8",
-        )
-
-        state = _make_state_store()
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache, config_path=config_path)
-
-        requirements = service._load_config_requirements("88718940")
-
-        assert requirements == []
-
-    def test_load_config_with_all_optional_fields(self, tmp_path: Path):
-        """Should parse all optional fields correctly."""
-        config_path = tmp_path / "material-requirements.yaml"
-        config_path.write_text(
-            """
-requirements:
-  - material_type: attachment
-    identifier: "att123"
-    project_key: "CEP"
-    priority: 200
-    title: "Important File"
-    metadata:
-      custom_field: value
-""",
-            encoding="utf-8",
-        )
-
-        state = _make_state_store()
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache, config_path=config_path)
-
-        requirements = service._load_config_requirements("CEP")
-
-        assert len(requirements) == 1
-        req = requirements[0]
-        assert req.material_type == MaterialType.attachment
-        assert req.identifier == "att123"
-        assert req.priority == 200
-        assert req.title == "Important File"
-        assert req.metadata["custom_field"] == "value"
-
-    def test_load_config_handles_invalid_yaml(self, tmp_path: Path):
-        """Should return empty list for invalid YAML."""
-        config_path = tmp_path / "material-requirements.yaml"
-        config_path.write_text("invalid: yaml: content: [", encoding="utf-8")
-
-        state = _make_state_store()
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache, config_path=config_path)
-
-        requirements = service._load_config_requirements("CEP")
-
-        assert requirements == []
-
-    def test_load_config_handles_non_dict_root(self, tmp_path: Path):
-        """Should return empty list when root is not a dict."""
-        config_path = tmp_path / "material-requirements.yaml"
-        config_path.write_text("just a string", encoding="utf-8")
-
-        state = _make_state_store()
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache, config_path=config_path)
-
-        requirements = service._load_config_requirements("CEP")
-
-        assert requirements == []
-
-    def test_load_config_handles_empty_requirements_list(self, tmp_path: Path):
-        """Should handle empty requirements list."""
-        config_path = tmp_path / "material-requirements.yaml"
-        config_path.write_text("requirements: []", encoding="utf-8")
-
-        state = _make_state_store()
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache, config_path=config_path)
-
-        requirements = service._load_config_requirements("CEP")
-
-        assert requirements == []
-
-    def test_parse_requirement_dict_with_valid_data(self):
-        """Should parse valid requirement dict correctly."""
-        state = _make_state_store()
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        data = {
-            "material_type": "page",
-            "identifier": "88718940",
-            "project_key": "CEP",
-            "source": "explicit",
-            "priority": 100,
-            "title": "Test",
-        }
-
-        req = service._parse_requirement_dict(data, "88718940")
-
-        assert req.material_type == MaterialType.page
-        assert req.identifier == "88718940"
-        assert req.project_key == "CEP"
-        # Source is taken from data dict if provided
-        assert req.source == "explicit"
-        assert req.priority == 100
-        assert req.title == "Test"
-
-    def test_parse_requirement_dict_with_defaults(self):
-        """Should use defaults for optional fields."""
-        state = _make_state_store()
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        data = {"material_type": "page", "identifier": "88718940"}
-
-        req = service._parse_requirement_dict(data, "CEP")
-
-        assert req.material_type == MaterialType.page
-        assert req.identifier == "88718940"
-        assert req.project_key == "CEP"
-        # Source defaults to "config" when parsing from config file
-        assert req.source == "config"
-        assert req.priority == 100  # default
-        assert req.title is None
-        assert req.metadata == {}
-
-    def test_parse_requirement_dict_invalid_material_type(self):
-        """Should return None for invalid material type."""
-        state = _make_state_store()
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        data = {"material_type": "invalid", "identifier": "88718940"}
-
-        req = service._parse_requirement_dict(data, "CEP")
-
-        assert req is None
-
-
-class TestDiscoverRequirements:
-    """Tests for multi-source requirement discovery and merging (15 tests)."""
-
-    @pytest.mark.asyncio
-    async def test_discover_requirements_merges_all_sources(self):
-        """Should merge requirements from all available sources."""
-        state = _make_state_store(
-            project_links=[
-                {"link_type": "confluence", "link_role": "page", "normalized_url": "http://c/p/111"},
-            ],
-            project_preparation={"sync_metadata": {"artifacts": [{"page_id": "222", "type": "page"}]}},
-        )
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        requirements = await service._discover_requirements("88718940")
-
-        assert len(requirements) >= 2
-        identifiers = {r.identifier for r in requirements}
-        assert "111" in identifiers  # registry
-        assert "222" in identifiers  # checklist
-
-    @pytest.mark.asyncio
-    async def test_discover_requirements_priority_deduplication(self):
-        """Higher priority requirement should replace lower priority."""
-        state = _make_state_store(
-            project_links=[
-                {"link_type": "confluence", "link_role": "page", "normalized_url": "http://c/p/123"},
-            ],
-            project_preparation={"sync_metadata": {"artifacts": [{"page_id": "123", "type": "page"}]}},
-        )
-        cache = _make_cache()
-
-        # Explicit with priority 200 should win
-        explicit = [_make_requirement(identifier="123", source="explicit", priority=200)]
-        service = MaterialCompletenessService(state, cache)
-        service.config_path = Path("/nonexistent")  # No config file
-
-        requirements = await service._discover_requirements("88718940", explicit_requirements=explicit)
-
-        # Should have only one requirement with highest priority
-        matching = [r for r in requirements if r.identifier == "123"]
-        assert len(matching) == 1
-        assert matching[0].source == "explicit"
-        assert matching[0].priority == 200
-
-    @pytest.mark.asyncio
-    async def test_discover_requirements_config_overrides_all(self, tmp_path: Path):
-        """Config file requirements should override all others with priority 100."""
-        state = _make_state_store(
-            project_links=[
-                {"link_type": "confluence", "link_role": "page", "normalized_url": "http://c/p/123"},
-            ],
-            project_preparation={"sync_metadata": {"artifacts": [{"page_id": "123", "type": "page"}]}},
-        )
-        cache = _make_cache()
-
-        # Create a config file with priority 100 requirement
-        config_path = tmp_path / "material-requirements.yaml"
-        config_path.write_text(
-            """
-requirements:
-  - material_type: page
-    identifier: "123"
-    priority: 100
-""",
-            encoding="utf-8",
-        )
-
-        # Config file sets priority to 100
-        explicit = [_make_requirement(identifier="123", source="explicit", priority=50)]
-        service = MaterialCompletenessService(state, cache, config_path=config_path)
-
-        requirements = await service._discover_requirements("88718940", explicit_requirements=explicit)
-
-        matching = [r for r in requirements if r.identifier == "123"]
-        assert len(matching) == 1
-        assert matching[0].priority == 100
-
-    @pytest.mark.asyncio
-    async def test_discover_requirements_explicit_highest_priority(self):
-        """Explicit parameter requirements should have priority 200 (highest)."""
-        state = _make_state_store()
-        cache = _make_cache()
-
-        explicit = [_make_requirement(priority=200)]
-        service = MaterialCompletenessService(state, cache)
-
-        requirements = await service._discover_requirements("88718940", explicit_requirements=explicit)
-
-        assert requirements[0].priority == 200
-
-    @pytest.mark.asyncio
-    async def test_discover_requirements_empty_all_sources(self):
-        """Should return empty list when all sources are empty."""
-        state = _make_state_store()
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache, registry_parser=None)
-
-        requirements = await service._discover_requirements("88718940")
-
-        assert requirements == []
-
-    @pytest.mark.asyncio
-    async def test_discover_requirements_maintains_source_tracking(self):
-        """Should preserve source information in requirements."""
-        state = _make_state_store(
-            project_links=[
-                {"link_type": "confluence", "link_role": "page", "normalized_url": "http://c/p/111"},
-            ],
-            project_preparation={"sync_metadata": {"artifacts": [{"page_id": "222", "type": "page"}]}},
-        )
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        requirements = await service._discover_requirements("88718940")
-
-        sources = {r.source for r in requirements}
-        assert "registry" in sources
-        assert "checklist" in sources
-
-    @pytest.mark.asyncio
-    async def test_discover_requirements_handles_duplicate_identifiers(self):
-        """Should deduplicate requirements with same material_type:project_key:identifier."""
-        state = _make_state_store(
-            project_links=[
-                {"link_type": "confluence", "link_role": "page", "normalized_url": "http://c/p/123"},
-                {"link_type": "confluence", "link_role": "page", "normalized_url": "http://c/p/123"},
-            ],
-        )
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        requirements = await service._discover_requirements("88718940")
-
-        matching = [r for r in requirements if r.identifier == "123"]
-        assert len(matching) == 1
-
-    @pytest.mark.asyncio
-    async def test_discover_requirements_different_types_not_deduped(self):
-        """Should NOT deduplicate different material types with same identifier."""
-        state = _make_state_store(
-            project_links=[
-                {"link_type": "confluence", "link_role": "page", "normalized_url": "http://c/p/123"},
-            ],
-            project_preparation={"sync_metadata": {"artifacts": [{"page_id": "123", "type": "attachment"}]}},
-        )
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        requirements = await service._discover_requirements("88718940")
-
-        # Should have both page and attachment with identifier "123"
-        assert len(requirements) == 2
-
-    @pytest.mark.asyncio
-    async def test_discover_requirements_respects_project_key(self):
-        """Should associate requirements with correct project key."""
-        state = _make_state_store(
-            project_links=[
-                {"link_type": "confluence", "link_role": "page", "normalized_url": "http://c/p/111"},
-            ],
-        )
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        requirements = await service._discover_requirements("88718940")
-
-        assert all(req.project_key == "88718940" for req in requirements)
-
-    @pytest.mark.asyncio
-    async def test_discover_requirements_preserves_metadata(self):
-        """Should preserve metadata from original requirements."""
-        state = _make_state_store(
-            project_links=[
-                {
-                    "link_type": "confluence",
-                    "link_role": "page",
-                    "normalized_url": "http://c/p/111",
-                    "title": "Custom Page",
-                },
-            ],
-        )
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        requirements = await service._discover_requirements("88718940")
-
-        req = next(r for r in requirements if r.identifier == "111")
-        assert req.title == "Custom Page"
-        assert "link_role" in req.metadata
-
-
-# ===========================================================================
-# Cache Validation Tests
-# ===========================================================================
-
-
-class TestValidatePageRequirement:
-    """Tests for page requirement cache validation (20 tests)."""
-
-    @pytest.mark.asyncio
-    async def test_validate_page_cached_fresh(self):
-        """Should return prepared for fresh cached page."""
-        state = _make_state_store()
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        req = _make_requirement(material_type=MaterialType.page, identifier="88718940")
-        entry = _make_cache_entry(age_hours=2.0)
-
-        with patch.object(service.cache, "get_page_entry", return_value=entry):
-            result = await service._validate_page_requirement(req, deep_check=False)
-
-        assert result["status"] == "prepared"
-        assert isinstance(result["entry"], PreparedMaterial)
-        assert result["entry"].freshness == FreshnessTier.fresh
-        assert result["entry"].age_hours == pytest.approx(2.0, rel=0.01)
-
-    @pytest.mark.asyncio
-    async def test_validate_page_cached_aging(self):
-        """Should return prepared with aging tier for older page."""
-        state = _make_state_store()
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        req = _make_requirement(material_type=MaterialType.page, identifier="88718940")
-        entry = _make_cache_entry(age_hours=30.0)
-
-        with patch.object(service.cache, "get_page_entry", return_value=entry):
-            result = await service._validate_page_requirement(req, deep_check=False)
-
-        assert result["status"] == "prepared"
-        assert result["entry"].freshness == FreshnessTier.aging
-
-    @pytest.mark.asyncio
-    async def test_validate_page_cached_stale(self):
-        """Should return stale for very old page."""
-        state = _make_state_store()
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        req = _make_requirement(material_type=MaterialType.page, identifier="88718940")
-        entry = _make_cache_entry(age_hours=50.0)
-
-        with patch.object(service.cache, "get_page_entry", return_value=entry):
-            result = await service._validate_page_requirement(req, deep_check=False)
-
-        assert result["status"] == "stale"
-        assert isinstance(result["entry"], StaleMaterial)
-        assert result["entry"].stale_reason == "ttl_or_signal_mismatch"
-
-    @pytest.mark.asyncio
-    async def test_validate_page_not_in_cache(self):
-        """Should return missing for uncached page."""
-        state = _make_state_store()
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        req = _make_requirement(material_type=MaterialType.page, identifier="88718940")
-
-        with patch.object(service.cache, "get_page_entry", return_value=None):
-            result = await service._validate_page_requirement(req, deep_check=False)
-
-        assert result["status"] == "missing"
-        assert isinstance(result["entry"], MissingMaterial)
-        assert result["entry"].reason == "not_in_cache"
-
-    @pytest.mark.asyncio
-    async def test_validate_page_preserves_title(self):
-        """Should preserve requirement title in result."""
-        title = "My Important Page"
-        state = _make_state_store()
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        req = _make_requirement(material_type=MaterialType.page, identifier="88718940", title=title)
-        entry = _make_cache_entry(age_hours=2.0)
-
-        with patch.object(service.cache, "get_page_entry", return_value=entry):
-            result = await service._validate_page_requirement(req, deep_check=False)
-
-        assert result["entry"].title == title
-
-    @pytest.mark.asyncio
-    async def test_validate_page_captures_content_hash(self):
-        """Should capture content hash from cache entry."""
-        state = _make_state_store()
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        req = _make_requirement(material_type=MaterialType.page, identifier="88718940")
-        entry = _make_cache_entry(age_hours=2.0)
-        entry["sha256"] = "abc123"
-        entry["hashes"] = {"html_sha256": "def456"}
-
-        with patch.object(service.cache, "get_page_entry", return_value=entry):
-            result = await service._validate_page_requirement(req, deep_check=False)
-
-        assert result["entry"].content_hash == "abc123"
-
-    @pytest.mark.asyncio
-    async def test_validate_page_captures_cache_path(self):
-        """Should capture cache file path from entry."""
-        state = _make_state_store()
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        req = _make_requirement(material_type=MaterialType.page, identifier="88718940")
-        entry = _make_cache_entry(age_hours=2.0)
-        entry["cache_paths"] = {"html": "pages/88718940/page.html"}
-
-        with patch.object(service.cache, "get_page_entry", return_value=entry):
-            result = await service._validate_page_requirement(req, deep_check=False)
-
-        assert "pages/88718940/page.html" in result["entry"].cache_path or ""
-
-    @pytest.mark.asyncio
-    async def test_validate_page_deep_check_with_remote_mismatch(self):
-        """Should mark stale when remote version differs."""
-        state = _make_state_store()
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        req = _make_requirement(material_type=MaterialType.page, identifier="88718940")
-        entry = _make_cache_entry(age_hours=2.0, version="15")
-
-        with patch.object(service.cache, "get_page_entry", return_value=entry):
-            # Mock deep check detecting version mismatch
-            with patch(
-                "vds_audit_orchestrator.collectors.completeness.freshness_evaluator.FreshnessEvaluator.evaluate_freshness",
-                return_value=FreshnessTier.stale,
-            ):
-                result = await service._validate_page_requirement(req, deep_check=True)
-
-        assert result["status"] == "stale"
-
-    @pytest.mark.asyncio
-    async def test_validate_page_without_cached_at(self):
-        """Should return unknown when cache entry has no cached_at."""
-        state = _make_state_store()
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        req = _make_requirement(material_type=MaterialType.page, identifier="88718940")
-        entry = _make_cache_entry(age_hours=2.0)
-        del entry["cached_at"]
-
-        with patch.object(service.cache, "get_page_entry", return_value=entry):
-            result = await service._validate_page_requirement(req, deep_check=False)
-
-        assert result["status"] == "missing"
-
-
-class TestValidateAttachmentRequirement:
-    """Tests for attachment requirement cache validation (15 tests)."""
-
-    @pytest.mark.asyncio
-    async def test_validate_attachment_cached_fresh(self):
-        """Should return prepared for fresh cached attachment."""
-        state = _make_state_store()
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        req = _make_requirement(material_type=MaterialType.attachment, identifier="att123")
-        entry = _make_cache_entry(material_type=MaterialType.attachment, identifier="att123", age_hours=2.0)
-        # For attachments, we need page_id in metadata
-        req.metadata["page_id"] = "88718940"
-
-        with patch.object(service.cache, "get_attachment_entries", return_value=[entry]):
-            result = await service._validate_attachment_requirement(req, deep_check=False)
-
-        assert result["status"] == "prepared"
-        assert isinstance(result["entry"], PreparedMaterial)
-
-    @pytest.mark.asyncio
-    async def test_validate_attachment_finds_by_page_id(self):
-        """Should scan cache to find attachment by page_id when not directly in metadata."""
-        state = _make_state_store()
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        req = _make_requirement(material_type=MaterialType.attachment, identifier="att123")
-        # Don't set page_id in metadata, should scan cache
-
-        entry = _make_cache_entry(material_type=MaterialType.attachment, identifier="att123", age_hours=2.0)
-        # attachment_id and page_id are already set by _make_cache_entry
-
-        # The implementation scans manifest first to find page_id, then calls get_attachment_entries
-        # So we need get_attachment_entries to return the entry
-        call_count = [0]
-
-        def mock_get_attachments(page_id, project_key=None):
-            call_count[0] += 1
-            return [entry]
-
-        with patch.object(service.cache, "get_attachment_entries", side_effect=mock_get_attachments):
-            with patch.object(service.cache, "_manifest", new={"attachments": {"att123": entry}}):
-                result = await service._validate_attachment_requirement(req, deep_check=False)
-
-        assert result["status"] == "prepared"
-
-    @pytest.mark.asyncio
-    async def test_validate_attachment_not_in_cache(self):
-        """Should return missing for uncached attachment."""
-        state = _make_state_store()
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        req = _make_requirement(material_type=MaterialType.attachment, identifier="att123")
-
-        with patch.object(service.cache, "get_attachment_entries", return_value=[]):
-            with patch.object(service.cache, "_manifest", new={"attachments": {}}):
-                result = await service._validate_attachment_requirement(req, deep_check=False)
-
-        assert result["status"] == "missing"
-        assert result["entry"].reason == "not_in_cache"
-
-    @pytest.mark.asyncio
-    async def test_validate_attachment_matches_by_identifier(self):
-        """Should match attachment by attachment_id from list."""
-        state = _make_state_store()
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        req = _make_requirement(material_type=MaterialType.attachment, identifier="att123")
-
-        # Multiple attachments, should find matching one
-        entries = [
-            _make_cache_entry(material_type=MaterialType.attachment, identifier="att456", age_hours=2.0),
-            _make_cache_entry(material_type=MaterialType.attachment, identifier="att123", age_hours=2.0),
-        ]
-
-        with patch.object(service.cache, "get_attachment_entries", return_value=entries):
-            result = await service._validate_attachment_requirement(req, deep_check=False)
-
-        assert result["status"] == "prepared"
-        assert result["entry"].identifier == "att123"
-
-    @pytest.mark.asyncio
-    async def test_validate_attachment_aging_status(self):
-        """Should reflect aging status correctly."""
-        state = _make_state_store()
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        req = _make_requirement(material_type=MaterialType.attachment, identifier="att123")
-        req.metadata["page_id"] = "88718940"
-        entry = _make_cache_entry(material_type=MaterialType.attachment, identifier="att123", age_hours=30.0)
-
-        with patch.object(service.cache, "get_attachment_entries", return_value=[entry]):
-            result = await service._validate_attachment_requirement(req, deep_check=False)
-
-        assert result["status"] == "prepared"
-        assert result["entry"].freshness == FreshnessTier.aging
-
-    @pytest.mark.asyncio
-    async def test_validate_attachment_stale_status(self):
-        """Should mark attachment as stale when too old."""
-        state = _make_state_store()
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        req = _make_requirement(material_type=MaterialType.attachment, identifier="att123")
-        req.metadata["page_id"] = "88718940"
-        entry = _make_cache_entry(material_type=MaterialType.attachment, identifier="att123", age_hours=50.0)
-
-        with patch.object(service.cache, "get_attachment_entries", return_value=[entry]):
-            result = await service._validate_attachment_requirement(req, deep_check=False)
-
-        assert result["status"] == "stale"
-
-    @pytest.mark.asyncio
-    async def test_validate_attachment_captures_file_hash(self):
-        """Should capture file hash from attachment entry."""
-        state = _make_state_store()
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        req = _make_requirement(material_type=MaterialType.attachment, identifier="att123")
-        req.metadata["page_id"] = "88718940"
-        entry = _make_cache_entry(material_type=MaterialType.attachment, identifier="att123", age_hours=2.0)
-        entry["hashes"] = {"file_sha256": "file123"}  # Use hashes dict instead of sha256
-
-        with patch.object(service.cache, "get_attachment_entries", return_value=[entry]):
-            result = await service._validate_attachment_requirement(req, deep_check=False)
-
-        assert result["entry"].content_hash == "file123"
-
-    @pytest.mark.asyncio
-    async def test_validate_attachment_without_page_metadata_scans_cache(self):
-        """Should scan cache manifest when page_id not in metadata."""
-        state = _make_state_store()
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        req = _make_requirement(material_type=MaterialType.attachment, identifier="att123")
-        # No page_id in metadata
-
-        entry = _make_cache_entry(material_type=MaterialType.attachment, identifier="att123", age_hours=2.0)
-
-        # The scan finds page_id from manifest, then calls get_attachment_entries
-        with patch.object(service.cache, "_manifest", new={"attachments": {"key": entry}}):
-            with patch.object(service.cache, "get_attachment_entries", return_value=[entry]):
-                result = await service._validate_attachment_requirement(req, deep_check=False)
-
-        assert result["status"] == "prepared"
-
-
-class TestValidateRepoRequirement:
-    """Tests for repo requirement cache validation (15 tests)."""
-
-    @pytest.mark.asyncio
-    async def test_validate_repo_cached_fresh(self):
-        """Should return prepared for fresh cached repo."""
-        state = _make_state_store()
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        req = _make_requirement(material_type=MaterialType.repo, identifier="merchant-report", project_key="PAR")
-        entry = _make_cache_entry(age_hours=2.0)
-        entry["repo"] = "merchant-report"
-
-        with patch.object(service.cache, "get_bitbucket_entries", return_value=[entry]):
-            result = await service._validate_repo_requirement(req, deep_check=False)
-
-        assert result["status"] == "prepared"
-        assert isinstance(result["entry"], PreparedMaterial)
-
-    @pytest.mark.asyncio
-    async def test_validate_repo_not_in_cache(self):
-        """Should return missing for uncached repo."""
-        state = _make_state_store()
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        req = _make_requirement(material_type=MaterialType.repo, identifier="merchant-report", project_key="PAR")
-
-        with patch.object(service.cache, "get_bitbucket_entries", return_value=[]):
-            result = await service._validate_repo_requirement(req, deep_check=False)
-
-        assert result["status"] == "missing"
-        assert result["entry"].reason == "not_in_cache"
-
-    @pytest.mark.asyncio
-    async def test_validate_repo_aging_status(self):
-        """Should reflect aging status for repo."""
-        state = _make_state_store()
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        req = _make_requirement(material_type=MaterialType.repo, identifier="merchant-report", project_key="PAR")
-        entry = _make_cache_entry(age_hours=30.0)
-        entry["repo"] = "merchant-report"
-
-        with patch.object(service.cache, "get_bitbucket_entries", return_value=[entry]):
-            result = await service._validate_repo_requirement(req, deep_check=False)
-
-        assert result["status"] == "prepared"
-        assert result["entry"].freshness == FreshnessTier.aging
-
-    @pytest.mark.asyncio
-    async def test_validate_repo_stale_status(self):
-        """Should mark repo as stale when too old."""
-        state = _make_state_store()
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        req = _make_requirement(material_type=MaterialType.repo, identifier="merchant-report", project_key="PAR")
-        entry = _make_cache_entry(age_hours=50.0)
-        entry["repo"] = "merchant-report"
-
-        with patch.object(service.cache, "get_bitbucket_entries", return_value=[entry]):
-            result = await service._validate_repo_requirement(req, deep_check=False)
-
-        assert result["status"] == "stale"
-
-    @pytest.mark.asyncio
-    async def test_validate_repo_captures_repo_name(self):
-        """Should capture repo name from entry."""
-        state = _make_state_store()
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        req = _make_requirement(material_type=MaterialType.repo, identifier="merchant-report", project_key="PAR")
-        entry = _make_cache_entry(age_hours=2.0)
-        entry["repo"] = "merchant-report"
-        entry["title"] = "Merchant Report Service"
-
-        with patch.object(service.cache, "get_bitbucket_entries", return_value=[entry]):
-            result = await service._validate_repo_requirement(req, deep_check=False)
-
-        assert result["entry"].title == "Merchant Report Service"
-
-    @pytest.mark.asyncio
-    async def test_validate_repo_captures_commit_hash(self):
-        """Should capture last commit hash from entry."""
-        state = _make_state_store()
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        req = _make_requirement(material_type=MaterialType.repo, identifier="merchant-report", project_key="PAR")
-        entry = _make_cache_entry(age_hours=2.0)
-        entry["repo"] = "merchant-report"
-        entry["sha256"] = "abc123def"
-        entry["last_commit"] = "abc123def"
-
-        with patch.object(service.cache, "get_bitbucket_entries", return_value=[entry]):
-            result = await service._validate_repo_requirement(req, deep_check=False)
-
-        assert result["entry"].content_hash == "abc123def"
-
-    @pytest.mark.asyncio
-    async def test_validate_repo_uses_first_match(self):
-        """Should use first entry when multiple repos match."""
-        state = _make_state_store()
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        req = _make_requirement(material_type=MaterialType.repo, identifier="merchant-report", project_key="PAR")
-
-        entries = [
-            _make_cache_entry(age_hours=2.0),
-            _make_cache_entry(age_hours=5.0),
-        ]
-        for entry in entries:
-            entry["repo"] = "merchant-report"
-
-        with patch.object(service.cache, "get_bitbucket_entries", return_value=entries):
-            result = await service._validate_repo_requirement(req, deep_check=False)
-
-        assert result["status"] == "prepared"
-
-    @pytest.mark.asyncio
-    async def test_validate_repo_unsupported_type(self):
-        """Should return missing for unsupported material type."""
-        state = _make_state_store()
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        req = _make_requirement(material_type=MaterialType.page, identifier="88718940")
-        # Mark as unsupported via metadata
-        req.metadata["unsupported_type"] = True
-
-        result = await service._validate_requirement(req, deep_check=False)
-
-        assert result["status"] == "missing"
-        assert result["entry"].reason == "unsupported_type"
-
-
-class TestValidateRequirement:
-    """Tests for main validate_requirement dispatcher (10 tests)."""
-
-    @pytest.mark.asyncio
-    async def test_validate_requirement_dispatches_to_page(self):
-        """Should dispatch page requirements to page validator."""
-        state = _make_state_store()
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        req = _make_requirement(material_type=MaterialType.page)
-        _make_cache_entry(age_hours=2.0)
-
-        with patch.object(
-            service, "_validate_page_requirement", return_value={"status": "prepared", "entry": MagicMock()}
-        ):
-            result = await service._validate_requirement(req, deep_check=False)
-
-        assert result["status"] == "prepared"
-
-    @pytest.mark.asyncio
-    async def test_validate_requirement_dispatches_to_attachment(self):
-        """Should dispatch attachment requirements to attachment validator."""
-        state = _make_state_store()
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        req = _make_requirement(material_type=MaterialType.attachment)
-        _make_cache_entry(age_hours=2.0)
-
-        with patch.object(
-            service, "_validate_attachment_requirement", return_value={"status": "prepared", "entry": MagicMock()}
-        ):
-            result = await service._validate_requirement(req, deep_check=False)
-
-        assert result["status"] == "prepared"
-
-    @pytest.mark.asyncio
-    async def test_validate_requirement_dispatches_to_repo(self):
-        """Should dispatch repo requirements to repo validator."""
-        state = _make_state_store()
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        req = _make_requirement(material_type=MaterialType.repo)
-        _make_cache_entry(age_hours=2.0)
-
-        with patch.object(
-            service, "_validate_repo_requirement", return_value={"status": "prepared", "entry": MagicMock()}
-        ):
-            result = await service._validate_requirement(req, deep_check=False)
-
-        assert result["status"] == "prepared"
-
-    @pytest.mark.asyncio
-    async def test_validate_requirement_passes_deep_check_flag(self):
-        """Should pass deep_check flag to validators."""
-        state = _make_state_store()
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        req = _make_requirement(material_type=MaterialType.page)
-
-        with patch.object(
-            service, "_validate_page_requirement", return_value={"status": "prepared", "entry": MagicMock()}
-        ) as mock_validate:
-            await service._validate_requirement(req, deep_check=True)
-
-            mock_validate.assert_called_once_with(req, deep_check=True)
-
-    @pytest.mark.asyncio
-    async def test_validate_requirement_unknown_type_missing(self):
-        """Should return missing for unknown material types."""
-        state = _make_state_store()
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        # Create a mock requirement with unsupported type
-        from unittest.mock import Mock
-
-        req = Mock()
-        req.material_type = "unknown_type"  # type: ignore
-        req.identifier = "test_id"
-        req.project_key = "CEP"
-
-        result = await service._validate_requirement(req, deep_check=False)
-
-        assert result["status"] == "missing"
-        assert result["entry"].reason == "unsupported_type"
-
-
-# ===========================================================================
-# Metrics Computation Tests
-# ===========================================================================
-
-
-class TestComputeMetrics:
-    """Tests for metrics computation (15 tests)."""
-
-    def test_compute_metrics_all_prepared(self):
-        """Should compute metrics when all materials prepared."""
-        service = MaterialCompletenessService(_make_state_store(), _make_cache())
-
-        requirements = [_make_requirement() for _ in range(10)]
-        prepared = [_make_prepared() for _ in range(10)]
-        missing = []
-        stale = []
-
-        metrics = service._compute_metrics(requirements, prepared, missing, stale, deep_checked=False)
-
-        assert metrics.total_required == 10
-        assert metrics.total_prepared == 10
-        assert metrics.total_missing == 0
-        assert metrics.total_stale == 0
-        assert metrics.completeness_pct == 100.0
-
-    def test_compute_metrics_partial_prepared(self):
-        """Should compute metrics with some prepared materials."""
-        service = MaterialCompletenessService(_make_state_store(), _make_cache())
-
-        requirements = [_make_requirement() for _ in range(10)]
-        prepared = [_make_prepared() for _ in range(7)]
-        missing = [_make_missing() for _ in range(3)]
-        stale = []
-
-        metrics = service._compute_metrics(requirements, prepared, missing, stale, deep_checked=False)
-
-        assert metrics.total_required == 10
-        assert metrics.total_prepared == 7
-        assert metrics.total_missing == 3
-        assert metrics.completeness_pct == 70.0
-
-    def test_compute_metrics_with_stale(self):
-        """Should count stale materials correctly."""
-        service = MaterialCompletenessService(_make_state_store(), _make_cache())
-
-        requirements = [_make_requirement() for _ in range(10)]
-        # 6 fresh, 2 aging, 2 stale
-        prepared = [_make_prepared(freshness=FreshnessTier.fresh) for _ in range(6)] + [
-            _make_prepared(freshness=FreshnessTier.aging) for _ in range(2)
-        ]
-        missing = []
-        stale = [_make_stale() for _ in range(2)]
-
-        metrics = service._compute_metrics(requirements, prepared, missing, stale, deep_checked=False)
-
-        assert metrics.total_prepared == 8
-        assert metrics.total_stale == 2
-        assert metrics.total_aging == 2
-
-    def test_compute_metrics_completeness_percentage_bounds(self):
-        """Should handle edge cases for percentage calculation."""
-        service = MaterialCompletenessService(_make_state_store(), _make_cache())
-
-        # 0% - no requirements
-        metrics = service._compute_metrics([], [], [], [], deep_checked=False)
-        assert metrics.completeness_pct == 100.0  # Empty case
-
-        # Normal case
-        requirements = [_make_requirement() for _ in range(5)]
-        prepared = [_make_prepared() for _ in range(3)]
-        metrics = service._compute_metrics(requirements, prepared, [], [], deep_checked=False)
-        assert metrics.completeness_pct == 60.0
-
-    def test_compute_metrics_freshness_percentage(self):
-        """Should calculate freshness percentage correctly."""
-        service = MaterialCompletenessService(_make_state_store(), _make_cache())
-
-        # All fresh = 100% freshness
-        prepared = [_make_prepared(freshness=FreshnessTier.fresh) for _ in range(5)]
-        metrics = service._compute_metrics(
-            [_make_requirement() for _ in range(5)], prepared, [], [], deep_checked=False
-        )
-        assert metrics.freshness_pct == 100.0
-
-        # Mix: 3 fresh, 2 aging = 60% freshness
-        prepared = [_make_prepared(freshness=FreshnessTier.fresh) for _ in range(3)] + [
-            _make_prepared(freshness=FreshnessTier.aging) for _ in range(2)
-        ]
-        metrics = service._compute_metrics(
-            [_make_requirement() for _ in range(5)], prepared, [], [], deep_checked=False
-        )
-        assert metrics.freshness_pct == 60.0
-
-    def test_compute_metrics_freshness_percentage_no_prepared(self):
-        """Should handle no prepared materials."""
-        service = MaterialCompletenessService(_make_state_store(), _make_cache())
-
-        metrics = service._compute_metrics(
-            [_make_requirement() for _ in range(5)], [], [_make_missing() for _ in range(5)], [], deep_checked=False
-        )
-        assert metrics.freshness_pct == 100.0  # By definition when no prepared
-
-    def test_compute_metrics_average_age(self):
-        """Should calculate average age of cached materials."""
-        service = MaterialCompletenessService(_make_state_store(), _make_cache())
-
-        prepared = [
-            _make_prepared(age_hours=2.0),
-            _make_prepared(age_hours=4.0),
-            _make_prepared(age_hours=6.0),
-        ]
-
-        metrics = service._compute_metrics(
-            [_make_requirement() for _ in range(3)], prepared, [], [], deep_checked=False
-        )
-        assert metrics.avg_freshness_hours == 4.0
-
-    def test_compute_metrics_average_age_empty(self):
-        """Should return 0 for average age when no materials prepared."""
-        service = MaterialCompletenessService(_make_state_store(), _make_cache())
-
-        metrics = service._compute_metrics([], [], [], [], deep_checked=False)
-        assert metrics.avg_freshness_hours == 0.0
-
-    def test_compute_metrics_cache_hit_rate(self):
-        """Should calculate cache hit rate."""
-        service = MaterialCompletenessService(_make_state_store(), _make_cache())
-
-        requirements = [_make_requirement() for _ in range(10)]
-        prepared = [_make_prepared() for _ in range(8)]
-        missing = [_make_missing() for _ in range(2)]
-
-        metrics = service._compute_metrics(requirements, prepared, missing, [], deep_checked=False)
-        assert metrics.cache_hit_rate == 80.0
-
-    def test_compute_metrics_deep_checked_flag(self):
-        """Should reflect deep check status."""
-        service = MaterialCompletenessService(_make_state_store(), _make_cache())
-
-        metrics = service._compute_metrics([], [], [], [], deep_checked=False)
-        assert metrics.deep_checked is False
-
-        metrics = service._compute_metrics([], [], [], [], deep_checked=True)
-        assert metrics.deep_checked is True
-
-    def test_compute_metrics_timestamp(self):
-        """Should include checked_at timestamp."""
-        service = MaterialCompletenessService(_make_state_store(), _make_cache())
-
-        before = datetime.now(UTC)
-        metrics = service._compute_metrics([], [], [], [], deep_checked=False)
-        after = datetime.now(UTC)
-
-        assert before <= metrics.checked_at <= after
-
-
-# ===========================================================================
-# Action Generation Tests
-# ===========================================================================
-
-
-class TestGenerateActions:
-    """Tests for action generation (15 tests)."""
-
-    def test_generate_actions_for_missing_materials(self):
-        """Should generate download action for missing materials."""
-        service = MaterialCompletenessService(_make_state_store(), _make_cache())
-
-        metrics = _make_metrics(total_required=10, total_prepared=7, total_missing=3, completeness_pct=70.0)
-        missing = [_make_missing(identifier="m1"), _make_missing(identifier="m2"), _make_missing(identifier="m3")]
-        stale = []
-
-        actions = service._generate_actions(metrics, missing, stale, min_threshold_pct=80.0)
-
-        assert len(actions) >= 1
-        download_actions = [a for a in actions if a.action_type == "download"]
-        assert len(download_actions) == 1
-        assert (
-            download_actions[0].priority == "high"
-        )  # Changed: 70% is close to 80% threshold, so "high" not "critical"
-        assert "3 missing materials" in download_actions[0].description
-
-    def test_generate_actions_for_stale_materials(self):
-        """Should generate refresh action for stale materials."""
-        service = MaterialCompletenessService(_make_state_store(), _make_cache())
-
-        metrics = _make_metrics(total_required=10, total_prepared=10, total_stale=2, completeness_pct=100.0)
-        missing = []
-        stale = [_make_stale(identifier="s1"), _make_stale(identifier="s2")]
-
-        actions = service._generate_actions(metrics, missing, stale, min_threshold_pct=80.0)
-
-        refresh_actions = [a for a in actions if a.action_type == "refresh"]
-        assert len(refresh_actions) == 1
-        assert refresh_actions[0].priority == "medium"
-
-    def test_generate_actions_below_threshold(self):
-        """Should generate deep_check action when below threshold."""
-        service = MaterialCompletenessService(_make_state_store(), _make_cache())
-
-        metrics = _make_metrics(total_required=10, total_prepared=5, completeness_pct=50.0)
-        missing = [_make_missing() for _ in range(5)]
-        stale = []
-
-        actions = service._generate_actions(metrics, missing, stale, min_threshold_pct=80.0)
-
-        check_actions = [a for a in actions if a.action_type == "deep_check"]
-        assert len(check_actions) == 1
-        assert "below threshold" in check_actions[0].description.lower()
-
-    def test_generate_actions_all_good(self):
-        """Should generate ignore action when all materials prepared."""
-        service = MaterialCompletenessService(_make_state_store(), _make_cache())
-
-        metrics = _make_metrics(total_required=10, total_prepared=10, completeness_pct=100.0)
-        missing = []
-        stale = []
-
-        actions = service._generate_actions(metrics, missing, stale, min_threshold_pct=80.0)
-
-        assert len(actions) == 1
-        assert actions[0].action_type == "ignore"
-        assert actions[0].priority == "low"
-
-    def test_generate_actions_high_priority_missing(self):
-        """Should use critical priority when completeness very low."""
-        service = MaterialCompletenessService(_make_state_store(), _make_cache())
-
-        metrics = _make_metrics(total_required=10, total_prepared=2, completeness_pct=20.0)
-        missing = [_make_missing() for _ in range(8)]
-
-        actions = service._generate_actions(metrics, missing, [], min_threshold_pct=80.0)
-
-        download_actions = [a for a in actions if a.action_type == "download"]
-        assert download_actions[0].priority == "critical"
-
-    def test_generate_actions_high_priority_with_threshold(self):
-        """Should use high priority when completeness close to threshold."""
-        service = MaterialCompletenessService(_make_state_store(), _make_cache())
-
-        metrics = _make_metrics(total_required=10, total_prepared=7, completeness_pct=70.0)
-        missing = [_make_missing() for _ in range(3)]
-
-        actions = service._generate_actions(metrics, missing, [], min_threshold_pct=80.0)
-
-        download_actions = [a for a in actions if a.action_type == "download"]
-        assert download_actions[0].priority == "high"  # Not critical but below threshold
-
-    def test_generate_actions_includes_affected_materials(self):
-        """Should list affected materials in action."""
-        service = MaterialCompletenessService(_make_state_store(), _make_cache())
-
-        metrics = _make_metrics()
-        missing = [
-            _make_missing(identifier="page1"),
-            _make_missing(identifier="page2"),
-        ]
-        stale = []
-
-        actions = service._generate_actions(metrics, missing, stale, min_threshold_pct=80.0)
-
-        download_actions = [a for a in actions if a.action_type == "download"]
-        assert len(download_actions[0].affected_materials) == 2
-        assert "page1" in download_actions[0].affected_materials
-        assert "page2" in download_actions[0].affected_materials
-
-    def test_generate_actions_limits_affected_materials(self):
-        """Should limit affected materials list in description."""
-        service = MaterialCompletenessService(_make_state_store(), _make_cache())
-
-        metrics = _make_metrics()
-        # Create 7 missing materials to test truncation
-        missing = [_make_missing(identifier=f"page{i}") for i in range(7)]
-        stale = []
-
-        actions = service._generate_actions(metrics, missing, stale, min_threshold_pct=80.0)
-
-        download_actions = [a for a in actions if a.action_type == "download"]
-        # Should list first 5 plus "and 2 more"
-        assert "5" in download_actions[0].description
-        assert "2 more" in download_actions[0].description
-
-    def test_generate_actions_includes_command_suggestion(self):
-        """Should include CLI command suggestion for download action."""
-        service = MaterialCompletenessService(_make_state_store(), _make_cache())
-
-        metrics = _make_metrics(project_key="88718940")
-        missing = [_make_missing()]
-        stale = []
-
-        actions = service._generate_actions(metrics, missing, stale, min_threshold_pct=80.0)
-
-        download_actions = [a for a in actions if a.action_type == "download"]
-        assert "vds-audit extract-docs" in download_actions[0].command_suggestion
-
-    def test_generate_actions_refresh_command_suggestion(self):
-        """Should include CLI command suggestion for refresh action."""
-        service = MaterialCompletenessService(_make_state_store(), _make_cache())
-
-        metrics = _make_metrics(project_key="88718940")
-        missing = []
-        stale = [_make_stale()]
-
-        actions = service._generate_actions(metrics, missing, stale, min_threshold_pct=80.0)
-
-        refresh_actions = [a for a in actions if a.action_type == "refresh"]
-        assert "vds-audit extract-docs" in refresh_actions[0].command_suggestion
-        assert "--refresh" in refresh_actions[0].command_suggestion
-
-    def test_generate_actions_estimates_effort(self):
-        """Should include estimated effort in actions."""
-        service = MaterialCompletenessService(_make_state_store(), _make_cache())
-
-        metrics = _make_metrics()
-        missing = [_make_missing(), _make_missing()]
-        stale = []
-
-        actions = service._generate_actions(metrics, missing, stale, min_threshold_pct=80.0)
-
-        download_actions = [a for a in actions if a.action_type == "download"]
-        assert "~4 minutes" in download_actions[0].estimated_effort
-
-
-# ===========================================================================
-# Helper Method Tests
-# ===========================================================================
-
-
-class TestHelperMethods:
-    """Tests for helper utility methods (20 tests)."""
-
-    def test_summarize_sources_empty(self):
-        """Should return empty dict for no requirements."""
-        service = MaterialCompletenessService(_make_state_store(), _make_cache())
-
-        summary = service._summarize_sources([])
-
-        assert summary == {}
-
-    def test_summarize_sources_single_source(self):
-        """Should count requirements by source."""
-        service = MaterialCompletenessService(_make_state_store(), _make_cache())
-
-        requirements = [
-            _make_requirement(source="registry"),
-            _make_requirement(source="registry"),
-            _make_requirement(source="checklist"),
-        ]
-
-        summary = service._summarize_sources(requirements)
-
-        assert summary == {"registry": 2, "checklist": 1}
-
-    def test_summarize_sources_multiple_sources(self):
-        """Should handle all source types."""
-        service = MaterialCompletenessService(_make_state_store(), _make_cache())
-
-        requirements = [
-            _make_requirement(source="registry"),
-            _make_requirement(source="checklist"),
-            _make_requirement(source="explicit"),
-            _make_requirement(source="explicit"),
-        ]
-
-        summary = service._summarize_sources(requirements)
-
-        assert summary["registry"] == 1
-        assert summary["checklist"] == 1
-        assert summary["explicit"] == 2
-
-    def test_requirement_key_uniqueness(self):
-        """Should generate unique keys considering material type."""
-        service = MaterialCompletenessService(_make_state_store(), _make_cache())
-
-        page_req = _make_requirement(material_type=MaterialType.page, identifier="123")
-        attachment_req = _make_requirement(material_type=MaterialType.attachment, identifier="123")
-
-        page_key = service._requirement_key(page_req)
-        attachment_key = service._requirement_key(attachment_req)
-
-        assert page_key != attachment_key
-        assert "page:" in page_key
-        assert "attachment:" in attachment_key
-
-    def test_requirement_key_includes_project_key(self):
-        """Should include project key in deduplication key."""
-        service = MaterialCompletenessService(_make_state_store(), _make_cache())
-
-        req = _make_requirement(project_key="CEP", identifier="123")
-
-        key = service._requirement_key(req)
-
-        assert "CEP" in key
-        assert "123" in key
-
-    def test_extract_page_id_from_pageId_param(self):
-        """Should extract pageId from URL parameter."""
-        service = MaterialCompletenessService(_make_state_store(), _make_cache())
-
-        page_id = service._extract_page_id_from_url("http://confluence?pageId=88718940")
-
-        assert page_id == "88718940"
-
-    def test_extract_page_id_from_pages_format(self):
-        """Should extract pageId from /pages/ format."""
-        service = MaterialCompletenessService(_make_state_store(), _make_cache())
-
-        page_id = service._extract_page_id_from_url("http://confluence/pages/88718940")
-
-        assert page_id == "88718940"
-
-    def test_extract_page_id_returns_none_for_no_match(self):
-        """Should return None when no page_id found."""
-        service = MaterialCompletenessService(_make_state_store(), _make_cache())
-
-        page_id = service._extract_page_id_from_url("http://example.com/page")
-
-        assert page_id is None
-
-    def test_extract_page_id_handles_various_formats(self):
-        """Should handle different URL formats."""
-        service = MaterialCompletenessService(_make_state_store(), _make_cache())
-
-        # With pageId parameter
-        assert service._extract_page_id_from_url("http://c?pageId=123") == "123"
-        # With /pages/ format
-        assert service._extract_page_id_from_url("http://c/pages/456") == "456"
-        # With uppercase parameter
-        assert service._extract_page_id_from_url("http://c?PAGEID=789") is None  # case-sensitive
-
-
-# ===========================================================================
-# Main Entry Point Tests
-# ===========================================================================
-
-
-class TestCheckCompleteness:
-    """Tests for check_completeness main workflow (30 tests)."""
-
-    @pytest.mark.asyncio
-    async def test_check_completeness_full_workflow(self):
-        """Should execute full completeness check workflow."""
-        state = _make_state_store(
-            project_links=[
-                {"link_type": "confluence", "link_role": "page", "normalized_url": "http://c/p/88718940"},
-            ],
-            project_preparation={"sync_metadata": {"artifacts": [{"page_id": "88718940", "type": "page"}]}},
-        )
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        # Mock cache to return prepared entry
-        entry = _make_cache_entry(age_hours=2.0)
-
-        with patch.object(service.cache, "get_page_entry", return_value=entry):
-            report = await service.check_completeness("88718940", deep_check=False)
-
-        assert isinstance(report, CompletenessReport)
-        assert report.project_key == "88718940"
-        assert report.metrics.total_required >= 1
-        assert report.deep_checked is False
-
-    @pytest.mark.asyncio
-    async def test_check_completeness_with_explicit_requirements(self):
-        """Should accept explicit requirement overrides."""
-        state = _make_state_store()
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        explicit = [_make_requirement(identifier="explicit-page")]
-        entry = _make_cache_entry(age_hours=2.0)
-
-        with patch.object(service.cache, "get_page_entry", return_value=entry):
-            report = await service.check_completeness("88718940", explicit_requirements=explicit)
-
-        assert report.metrics.total_required >= 1
-
-    @pytest.mark.asyncio
-    async def test_check_completeness_with_deep_check(self):
-        """Should respect deep_check flag."""
-        state = _make_state_store()
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        entry = _make_cache_entry(age_hours=2.0)
-
-        with patch.object(service.cache, "get_page_entry", return_value=entry):
-            report = await service.check_completeness("88718940", deep_check=True)
-
-        assert report.deep_checked is True
-
-    @pytest.mark.asyncio
-    async def test_check_completeness_custom_threshold(self):
-        """Should use custom threshold for readiness determination."""
-        state = _make_state_store()
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        entry = _make_cache_entry(age_hours=2.0)
-
-        with patch.object(service.cache, "get_page_entry", return_value=entry):
-            report = await service.check_completeness("88718940", min_threshold_pct=90.0)
-
-        # Threshold affects action generation
-        actions = report.actions
-        if report.metrics.completeness_pct < 90:
-            assert any(a.action_type == "deep_check" for a in actions)
-
-    @pytest.mark.asyncio
-    async def test_check_completeness_custom_cache_dir(self, tmp_path: Path):
-        """Should use custom cache directory when provided."""
-        state = _make_state_store()
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        custom_cache = tmp_path / "custom_cache"
-        entry = _make_cache_entry(age_hours=2.0)
-
-        with patch.object(service.cache, "get_page_entry", return_value=entry):
-            report = await service.check_completeness("88718940", cache_dir=custom_cache)
-
-        assert report.cache_dir == str(custom_cache)
-
-    @pytest.mark.asyncio
-    async def test_check_completeness_generates_report_with_all_fields(self):
-        """Should generate report with all required fields."""
-        state = _make_state_store()
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        entry = _make_cache_entry(age_hours=2.0)
-
-        with patch.object(service.cache, "get_page_entry", return_value=entry):
-            report = await service.check_completeness("88718940")
-
-        # Check all top-level fields
-        assert hasattr(report, "metrics")
-        assert hasattr(report, "prepared")
-        assert hasattr(report, "missing")
-        assert hasattr(report, "stale")
-        hasattr(report, "actions")
-        assert hasattr(report, "project_key")
-        assert hasattr(report, "checked_at")
-        assert hasattr(report, "deep_checked")
-        assert hasattr(report, "cache_dir")
-        assert hasattr(report, "source_summary")
-
-    @pytest.mark.asyncio
-    async def test_check_completeness_handles_requirement_discovery_error(self):
-        """Should handle RequirementDiscoveryError gracefully."""
-        state = _make_state_store()
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        # Mock discovery to raise error
-        with patch.object(service, "_discover_requirements", side_effect=RequirementDiscoveryError("Test error")):
-            with pytest.raises(RequirementDiscoveryError):
-                await service.check_completeness("88718940")
-
-    @pytest.mark.asyncio
-    async def test_check_completeness_includes_source_summary(self):
-        """Should include source summary in report."""
-        state = _make_state_store(
-            project_links=[
-                {"link_type": "confluence", "link_role": "page", "normalized_url": "http://c/p/111"},
-                {"link_type": "confluence", "link_role": "page", "normalized_url": "http://c/p/222"},
-            ],
-        )
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        entry = _make_cache_entry(age_hours=2.0)
-
-        with patch.object(service.cache, "get_page_entry", return_value=entry):
-            report = await service.check_completeness("88718940")
-
-        assert "registry" in report.source_summary
-        assert report.source_summary["registry"] >= 2
-
-    @pytest.mark.asyncio
-    async def test_check_completeness_empty_requirements(self):
-        """Should handle case with no requirements."""
-        state = _make_state_store()
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        report = await service.check_completeness("88718940")
-
-        assert report.metrics.total_required == 0
-        assert report.metrics.completeness_pct == 100.0
-
-    @pytest.mark.asyncio
-    async def test_check_completeness_all_missing(self):
-        """Should handle case with all materials missing."""
-        state = _make_state_store()
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        # Create 5 requirements with different identifiers
-        requirements = [_make_requirement(identifier=f"page{i}") for i in range(5)]
-
-        with patch.object(service, "_discover_requirements", return_value=requirements):
-            with patch.object(service.cache, "get_page_entry", return_value=None):
-                report = await service.check_completeness("88718940")
-
-        assert report.metrics.total_missing == 5
-        assert report.metrics.completeness_pct == 0.0
-        assert len(report.missing) == 5
-
-    @pytest.mark.asyncio
-    async def test_check_completeness_generates_actions(self):
-        """Should generate appropriate actions."""
-        state = _make_state_store()
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        requirements = [_make_requirement() for _ in range(5)]
-
-        with patch.object(service, "_discover_requirements", return_value=requirements):
-            with patch.object(service.cache, "get_page_entry", return_value=None):
-                report = await service.check_completeness("88718940")
-
-        assert len(report.actions) >= 1
-
-    @pytest.mark.asyncio
-    async def test_check_completeness_records_duration(self):
-        """Should log execution time (telemetry)."""
-        state = _make_state_store()
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        entry = _make_cache_entry(age_hours=2.0)
-
-        with patch.object(service.cache, "get_page_entry", return_value=entry):
-            report = await service.check_completeness("88718940")
-
-        # Just verify it completes - actual logging would be tested in integration
-        assert report is not None
-
-    @pytest.mark.asyncio
-    async def test_check_completeness_with_multiple_material_types(self):
-        """Should handle pages, attachments, and repos together."""
-        state = _make_state_store()
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        requirements = [
-            _make_requirement(material_type=MaterialType.page, identifier="p1"),
-            _make_requirement(material_type=MaterialType.attachment, identifier="a1"),
-            _make_requirement(material_type=MaterialType.repo, identifier="repo1"),
-        ]
-        entry = _make_cache_entry(age_hours=2.0)
-
-        with patch.object(service, "_discover_requirements", return_value=requirements):
-            with patch.object(service.cache, "get_page_entry", return_value=entry):
-                report = await service.check_completeness("88718940")
-
-        assert report.metrics.total_required == 3
-
-    @pytest.mark.asyncio
-    async def test_check_completeness_validates_cache_entries(self):
-        """Should validate each requirement against cache."""
-        state = _make_state_store()
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        # Create 3 requirements with different identifiers
-        requirements = [_make_requirement(identifier=f"page{i}") for i in range(3)]
-        # All prepared
-        _make_cache_entry(age_hours=2.0)
-
-        prepared_count = [0]
-
-        async def mock_validate(req, deep_check):
-            prepared_count[0] += 1
-            return {"status": "prepared", "entry": _make_prepared()}
-
-        with patch.object(service, "_discover_requirements", return_value=requirements):
-            with patch.object(service, "_validate_requirement", side_effect=mock_validate):
-                report = await service.check_completeness("88718940")
-
-        assert prepared_count[0] == 3
-        assert report.metrics.total_prepared == 3
-
-    @pytest.mark.asyncio
-    async def test_check_completeness_uses_requirement_key_for_deduplication(self):
-        """Should use requirement_key for deduplication."""
-        state = _make_state_store()
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        # Create duplicate requirements (same type, project, identifier)
-        requirements = [
-            _make_requirement(identifier="123", source="registry", priority=10),
-            _make_requirement(identifier="123", source="checklist", priority=20),
-        ]
-
-        with patch.object(service, "_discover_requirements", return_value=requirements):
-            # Mock validation to return prepared
-            with patch.object(
-                service, "_validate_requirement", return_value={"status": "prepared", "entry": _make_prepared()}
-            ):
-                report = await service.check_completeness("88718940")
-
-        # Should only have one material since deduped
-        total_materials = len(report.prepared) + len(report.missing) + len(report.stale)
-        assert total_materials == 1
-
-    @pytest.mark.asyncio
-    async def test_check_completeness_handles_missing_page_cache_dir(self):
-        """Should handle missing cache directory gracefully."""
-        state = _make_state_store()
-        # Use cache with non-existent directory
-        cache = MaterialCache(cache_dir=Path("/nonexistent/cache"))
-        service = MaterialCompletenessService(state, cache)
-
-        requirements = [_make_requirement()]
-
-        with patch.object(service, "_discover_requirements", return_value=requirements):
-            report = await service.check_completeness("88718940")
-
-        # Should still generate report even with cache issues
-        assert isinstance(report, CompletenessReport)
-
-    @pytest.mark.asyncio
-    async def test_check_completeness_with_low_threshold_generates_deep_check_action(self):
-        """Should generate deep_check action when below threshold."""
-        state = _make_state_store()
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        # Create low completeness scenario
-        requirements = [_make_requirement() for _ in range(10)]
-
-        with patch.object(service, "_discover_requirements", return_value=requirements):
-            with patch.object(service.cache, "get_page_entry", return_value=None):
-                report = await service.check_completeness("88718940", min_threshold_pct=90.0)
-
-        # Should have deep check action
-        assert any(a.action_type == "deep_check" for a in report.actions)
-
-    @pytest.mark.asyncio
-    async def test_check_completeness_above_threshold_no_deep_check(self):
-        """Should not generate deep_check action when above threshold."""
-        state = _make_state_store()
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        requirements = [_make_requirement() for _ in range(8)]
-        entry = _make_cache_entry(age_hours=2.0)
-
-        with patch.object(service, "_discover_requirements", return_value=requirements):
-            with patch.object(service.cache, "get_page_entry", return_value=entry):
-                report = await service.check_completeness("88718940", min_threshold_pct=80.0)
-
-        # Should not have deep check action since 8/10 = 80%
-        deep_check_actions = [a for a in report.actions if a.action_type == "deep_check"]
-        assert len(deep_check_actions) == 0
-
-    @pytest.mark.asyncio
-    async def test_check_completeness_sets_checked_at_timestamp(self):
-        """Should set checked_at to current time."""
-        state = _make_state_store()
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        entry = _make_cache_entry(age_hours=2.0)
-
-        before = datetime.now(UTC)
-
-        with patch.object(service.cache, "get_page_entry", return_value=entry):
-            report = await service.check_completeness("88718940")
-
-        after = datetime.now(UTC)
-
-        assert before <= report.checked_at <= after
-
-    @pytest.mark.asyncio
-    async def test_check_completeness_includes_project_key_in_report(self):
-        """Should include project_key in generated report."""
-        state = _make_state_store()
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        entry = _make_cache_entry(age_hours=2.0)
-
-        with patch.object(service.cache, "get_page_entry", return_value=entry):
-            report = await service.check_completeness("88718940")
-
-        assert report.project_key == "88718940"
-
-    @pytest.mark.asyncio
-    async def test_check_completeness_preserves_explicit_requirements_priority(self):
-        """Should respect priority 200 for explicit requirements."""
-        state = _make_state_store()
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        # Explicit with priority 200
-        explicit = [_make_requirement(priority=200)]
-
-        with patch.object(service, "_discover_requirements", return_value=explicit):
-            with patch.object(
-                service, "_validate_requirement", return_value={"status": "prepared", "entry": _make_prepared()}
-            ):
-                report = await service.check_completeness("88718940", explicit_requirements=explicit)
-
-        # Should keep the explicit requirement
-        assert report.metrics.total_required >= 1
-
-    @pytest.mark.asyncio
-    async def test_check_completeness_handles_empty_project_links(self):
-        """Should handle project with no links gracefully."""
-        state = _make_state_store(project_links=[])
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        report = await service.check_completeness("88718940")
-
-        assert isinstance(report, CompletenessReport)
-
-    @pytest.mark.asyncio
-    async def test_check_completeness_handles_empty_preparation(self):
-        """Should handle empty preparation gracefully."""
-        state = _make_state_store(project_preparation={})
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        report = await service.check_completeness("88718940")
-
-        assert isinstance(report, CompletenessReport)
-
-    @pytest.mark.asyncio
-    async def test_check_completeness_includes_deep_check_in_report(self):
-        """Should include deep_check status in report."""
-        state = _make_state_store()
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        entry = _make_cache_entry(age_hours=2.0)
-
-        with patch.object(service.cache, "get_page_entry", return_value=entry):
-            report = await service.check_completeness("88718940", deep_check=True)
-
-        assert report.deep_checked is True
-
-    @pytest.mark.asyncio
-    async def test_check_completeness_with_mixed_material_statuses(self):
-        """Should handle prepared, missing, and stale materials together."""
-        state = _make_state_store()
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        requirements = [
-            _make_requirement(identifier="prepared"),
-            _make_requirement(identifier="missing"),
-            _make_requirement(identifier="stale"),
-        ]
-
-        async def mock_validate(req, deep_check):
-            if req.identifier == "prepared":
-                _make_cache_entry(age_hours=2.0)
-                return {"status": "prepared", "entry": _make_prepared()}
-            elif req.identifier == "missing":
-                return {"status": "missing", "entry": _make_missing()}
-            else:  # stale
-                return {"status": "stale", "entry": _make_stale()}
-
-        with patch.object(service, "_discover_requirements", return_value=requirements):
-            with patch.object(service, "_validate_requirement", side_effect=mock_validate):
-                report = await service.check_completeness("88718940")
-
-        assert len(report.prepared) >= 1
-        assert len(report.missing) >= 1
-        assert len(report.stale) >= 1
-
-    @pytest.mark.asyncio
-    async def test_check_completeness_default_threshold(self):
-        """Should use default 80% threshold when not specified."""
-        state = _make_state_store()
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        entry = _make_cache_entry(age_hours=2.0)
-
-        with patch.object(service.cache, "get_page_entry", return_value=entry):
-            report = await service.check_completeness("88718940")
-
-        # Default threshold is 80
-        assert report.get_readiness_status() == report.get_readiness_status(threshold_pct=80.0)
-
-
-# ===========================================================================
-# Edge Cases and Error Handling
-# ===========================================================================
-
-
-class TestEdgeCases:
-    """Tests for edge cases and error scenarios (15 tests)."""
-
-    @pytest.mark.asyncio
-    async def test_handles_zero_requirements_gracefully(self):
-        """Should handle zero requirements without crashing."""
-        state = _make_state_store()
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        report = await service.check_completeness("88718940")
-
-        assert report.metrics.total_required == 0
-        assert report.metrics.completeness_pct == 100.0
-
-    def test_requirement_key_handles_special_characters(self):
-        """Should handle special characters in identifiers."""
-        service = MaterialCompletenessService(_make_state_store(), _make_cache())
-
-        req = _make_requirement(identifier="page-with-dashes", project_key="Project-With-Dashes")
-
-        key = service._requirement_key(req)
-
-        assert "page-with-dashes" in key
-        assert "Project-With-Dashes" in key
-
-    def test_parse_requirement_dict_handles_missing_optional_fields(self):
-        """Should handle missing optional fields with defaults."""
-        state = _make_state_store()
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        data = {"material_type": "page", "identifier": "88718940"}
-
-        req = service._parse_requirement_dict(data, "CEP")
-
-        assert req.priority == 100  # default
-        assert req.title is None
-        assert req.metadata == {}
-
-    @pytest.mark.asyncio
-    async def test_discover_requirements_merges_explicit_with_highest_priority(self):
-        """Explicit requirements should always have highest priority."""
-        state = _make_state_store(
-            project_links=[
-                {"link_type": "confluence", "link_role": "page", "normalized_url": "http://c/p/123"},
-            ],
-        )
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        # Explicit with various priorities
-        explicit_low = [_make_requirement(identifier="123", priority=1)]
-        explicit_high = [_make_requirement(identifier="123", priority=300)]
-
-        # Pass both explicit requirements - should use highest priority
-        requirements = await service._discover_requirements(
-            "88718940", explicit_requirements=explicit_low + explicit_high
-        )
-
-        # Should have used the higher priority (300)
-        matching = [r for r in requirements if r.identifier == "123"]
-        assert len(matching) == 1
-        assert matching[0].priority == 300
-
-    @pytest.mark.asyncio
-    async def test_validate_page_handles_cache_return_with_no_hashes(self):
-        """Should handle cache entry without hash information."""
-        state = _make_state_store()
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        req = _make_requirement(material_type=MaterialType.page)
-        entry = _make_cache_entry(age_hours=2.0)
-        # No hash fields
-
-        with patch.object(service.cache, "get_page_entry", return_value=entry):
-            result = await service._validate_page_requirement(req, deep_check=False)
-
-        assert result["status"] == "prepared"
-        assert result["entry"].content_hash is None
-
-    @pytest.mark.asyncio
-    async def test_generate_actions_empty_lists(self):
-        """Should handle empty material lists gracefully."""
-        service = MaterialCompletenessService(_make_state_store(), _make_cache())
-
-        metrics = _make_metrics()
-        actions = service._generate_actions(metrics, [], [], min_threshold_pct=80.0)
-
-        # Should have ignore action
-        assert len(actions) == 1
-        assert actions[0].action_type == "ignore"
-
-    def test_summarize_sources_counts_all_requirements(self):
-        """Should count all requirements regardless of other attributes."""
-        service = MaterialCompletenessService(_make_state_store(), _make_cache())
-
-        requirements = [
-            _make_requirement(source="registry", priority=10),
-            _make_requirement(source="registry", priority=20),
-            _make_requirement(source="checklist", priority=30),
-            _make_requirement(source="explicit", priority=40),
-        ]
-
-        summary = service._summarize_sources(requirements)
-
-        assert summary["registry"] == 2
-        assert summary["checklist"] == 1
-        assert summary["explicit"] == 1
-
-    @pytest.mark.asyncio
-    async def test_check_completeness_uses_cache_dir_for_diagnostics(self):
-        """Should include cache directory path in diagnostics."""
-        state = _make_state_store()
-        cache_dir = Path("/custom/cache")
-        cache = MaterialCache(cache_dir=cache_dir)
-        service = MaterialCompletenessService(state, cache)
-
-        entry = _make_cache_entry(age_hours=2.0)
-
-        with patch.object(service.cache, "get_page_entry", return_value=entry):
-            report = await service.check_completeness("88718940", cache_dir=cache_dir)
-
-        assert report.cache_dir == str(cache_dir)
-
-    @pytest.mark.asyncio
-    async def test_check_completeness_preserves_requirement_metadata_in_report(self):
-        """Should preserve requirement metadata through to report."""
-        state = _make_state_store()
-        cache = _make_cache()
-        service = MaterialCompletenessService(state, cache)
-
-        title = "Custom Page Title"
-        requirements = [_make_requirement(title=title)]
-        entry = _make_cache_entry(age_hours=2.0)
-
-        with patch.object(service, "_discover_requirements", return_value=requirements):
-            with patch.object(service.cache, "get_page_entry", return_value=entry):
-                report = await service.check_completeness("88718940")
-
-        assert len(report.prepared) >= 1
-        # Title should be in prepared materials
-        assert any(p.title == title for p in report.prepared)
-
-
-# Additional helper functions for fixtures
-
-
-def _make_prepared(**overrides: Any) -> PreparedMaterial:
-    """Create a PreparedMaterial for testing."""
-    now = datetime.now(UTC)
-    defaults = {
-        "material_type": MaterialType.page,
-        "identifier": "88718940",
-        "project_key": "CEP",
-        "title": "Test Page",
-        "cached_at": now - timedelta(hours=2),
-        "freshness": FreshnessTier.fresh,
-        "last_accessed": now,
-        "content_hash": "abc123",
-        "age_hours": 2.0,
-    }
-    defaults.update(overrides)
-    return PreparedMaterial(**defaults)
-
-
-def _make_missing(**overrides: Any) -> MissingMaterial:
-    """Create a MissingMaterial for testing."""
-    defaults = {
-        "material_type": MaterialType.page,
-        "identifier": "99999999",
-        "project_key": "88718940",
-        "reason": "not_in_cache",
-        "title": "Missing Page",
-    }
-    defaults.update(overrides)
-    return MissingMaterial(**defaults)
-
-
-def _make_stale(**overrides: Any) -> StaleMaterial:
-    """Create a StaleMaterial for testing."""
-    now = datetime.now(UTC)
-    defaults = {
-        "material_type": MaterialType.page,
-        "identifier": "88888888",
-        "project_key": "88718940",
-        "stale_reason": "ttl_expired",
-        "cached_at": now - timedelta(hours=50),
-        "age_hours": 50.0,
-        "recommended_action": "refresh",
-    }
-    defaults.update(overrides)
-    return StaleMaterial(**defaults)