@ngocsangairvds/vsaf 3.2.14 → 3.2.15

package/tools/vds-scripts/audit_orchestrator/src/vds_audit_orchestrator/collectors/registry_parser.py

@@ -1,3063 +0,0 @@
-"""Registry page parsing logic for Phase 14 (Material Extraction)."""
-
-from __future__ import annotations
-
-import asyncio
-import json
-import re
-import time
-from collections import deque
-from pathlib import Path
-from typing import Any, cast
-from urllib.parse import parse_qs, unquote_plus, urlparse, urlsplit
-
-from bs4 import BeautifulSoup
-from structlog import get_logger
-
-from vds_audit_orchestrator.clients.confluence_cli_client import ConfluenceCliClient
-from vds_audit_orchestrator.errors import DataSourceError
-from vds_audit_orchestrator.identity import normalize_storage_key
-from vds_audit_orchestrator.models.registry import (
-    ChecklistProfile,
-    ChildPage,
-    ConfluenceAncestryNode,
-    DocumentLink,
-    DocumentRole,
-    LinkSource,
-    ParseDiagnostics,
-    ProjectMaterial,
-    ProjectRegistry,
-    RootChildType,
-    SkippedNode,
-    SkippedNodeReason,
-)
-
-logger = get_logger()
-
-# Phase 24: Mapping version for header heuristics (FR-13.1.12).
-# Increment when header synonym mappings or link-column priority changes.
-MAPPING_VERSION = "1.0.0"
-_CACHE_MISS = object()
-_PLAIN_TEXT_URL_PATTERN = re.compile(r"https?://[^\s\"'<>]+", re.IGNORECASE)
-
-
-class RegistryPageParser:
-    """Parser for Confluence registry pages."""
-
-    MAX_RETRIES = 8
-    MAX_BACKOFF_SECONDS = 60.0
-    MIN_TIMEOUT_SECONDS = 0.1
-    MAX_PARSE_CONCURRENCY = 16
-    MAX_PARENT_CHAIN_DEPTH = 12
-    _REPOSITORY_TITLE_PREFIX = "repository - "
-
-    def __init__(
-        self,
-        client: ConfluenceCliClient,
-        *,
-        recursive_depth: int = 2,
-        retries: int = 2,
-        backoff: float = 1.0,
-        parse_concurrency: int = 3,
-        checklist_page: str | None = None,
-        max_projects: int | None = None,
-        step_timeout: float | None = None,
-        prefetch_dir: Path | str | None = None,
-        adaptive_depth: bool = True,
-        adaptive_max_depth: int = 2,
-    ):
-        self.client = client
-        self.recursive_depth = recursive_depth
-        normalized_retries = max(0, int(retries))
-        if normalized_retries > self.MAX_RETRIES:
-            logger.warning(
-                "registry_parser_retries_capped",
-                requested=normalized_retries,
-                capped=self.MAX_RETRIES,
-            )
-        self.retries = min(normalized_retries, self.MAX_RETRIES)
-
-        normalized_backoff = max(0.0, float(backoff))
-        if normalized_backoff > self.MAX_BACKOFF_SECONDS:
-            logger.warning(
-                "registry_parser_backoff_capped",
-                requested=normalized_backoff,
-                capped=self.MAX_BACKOFF_SECONDS,
-            )
-        self.backoff = min(normalized_backoff, self.MAX_BACKOFF_SECONDS)
-        # Keep this conservative because Confluence APIs can degrade under parallel page fetches.
-        normalized_parse_concurrency = max(1, int(parse_concurrency))
-        if normalized_parse_concurrency > self.MAX_PARSE_CONCURRENCY:
-            logger.warning(
-                "registry_parser_parse_concurrency_capped",
-                requested=normalized_parse_concurrency,
-                capped=self.MAX_PARSE_CONCURRENCY,
-            )
-        self.parse_concurrency = min(normalized_parse_concurrency, self.MAX_PARSE_CONCURRENCY)
-        # Phase 24: Explicit checklist page override (TSK-241.2.4).
-        self.checklist_page_override = checklist_page
-        # Phase 24 TSK-243: Budget controls for timeout resilience.
-        self.max_projects = max_projects  # None means no limit
-        if step_timeout is None:
-            self.step_timeout = None
-        else:
-            normalized_timeout = max(self.MIN_TIMEOUT_SECONDS, float(step_timeout))
-            if normalized_timeout != float(step_timeout):
-                logger.warning(
-                    "registry_parser_step_timeout_normalized",
-                    requested=step_timeout,
-                    normalized=normalized_timeout,
-                    min_timeout=self.MIN_TIMEOUT_SECONDS,
-                )
-            self.step_timeout = normalized_timeout
-        # Phase 24 TSK-243.4.5: Prefetch directory for local artifact parsing.
-        self.prefetch_dir = Path(prefetch_dir) if prefetch_dir else None
-        # Phase 35: Adaptive deepening controls.
-        self.adaptive_depth = bool(adaptive_depth)
-        self.adaptive_max_depth = max(1, int(adaptive_max_depth))
-        self._prefetch_manifest: dict | None = None
-        self._prefetch_pages: dict[str, dict] = {}  # page_id -> page data
-        self._prefetch_children_by_parent: dict[str, list[dict]] = {}
-        self._network_children_cache: dict[tuple[str, bool], list[dict]] = {}
-        self._network_page_cache: dict[str, dict | None] = {}
-        self._project_parse_cache: dict[str, ProjectMaterial | None] = {}
-        # Best-effort resolution cache: normalized Confluence URL -> page_id (or None when unresolved).
-        self._resolved_confluence_page_ids: dict[str, str | None] = {}
-        # Cross-server CQL resolution cache for /display links.
-        self._server_scoped_clients: dict[str, ConfluenceCliClient] = {}
-        self._server_scoped_timeout = int(getattr(client, "_timeout", 120) or 120)
-        self._diag_prefetch_hits = 0
-        self._diag_prefetch_misses = 0
-        self._diag_network_fetches = 0
-        self._diag_fallback_fetches = 0
-        self._diag_step_timings_ms: dict[str, int] = {}
-        self._diag_retry_count = 0
-        self._diag_rate_limit_events = 0
-        self._diag_retry_after_seconds: int | None = None
-
-    def _reset_parse_diagnostics_tracking(self) -> None:
-        """Reset parser-level diagnostics counters for a new parse."""
-        self._diag_prefetch_hits = 0
-        self._diag_prefetch_misses = 0
-        self._diag_network_fetches = 0
-        self._diag_fallback_fetches = 0
-        self._diag_step_timings_ms = {}
-        self._diag_retry_count = 0
-        self._diag_rate_limit_events = 0
-        self._diag_retry_after_seconds = None
-        self._network_children_cache = {}
-        self._network_page_cache = {}
-        self._project_parse_cache = {}
-        self._resolved_confluence_page_ids = {}
-
-    def _record_step_timing(self, step: str, started_at: float) -> None:
-        """Record elapsed timing for a parsing step."""
-        elapsed_ms = max(0, int((time.monotonic() - started_at) * 1000))
-        self._diag_step_timings_ms[step] = self._diag_step_timings_ms.get(step, 0) + elapsed_ms
-
-    @staticmethod
-    def _extract_retry_after_seconds(exc: DataSourceError) -> int | None:
-        """Extract Retry-After seconds from error context/message when present."""
-        context = exc.context if isinstance(exc.context, dict) else {}
-        context_value = context.get("retry_after_seconds")
-        if context_value is not None:
-            try:
-                return int(context_value)
-            except (TypeError, ValueError):
-                pass
-
-        fragments = [
-            str(exc),
-            str(context.get("stderr") or ""),
-            str(context.get("stdout") or ""),
-            str(context.get("error") or ""),
-        ]
-        blob = "\n".join(fragments).lower()
-        match = re.search(r"retry[- ]after\s*[:=]?\s*(\d+)", blob)
-        if not match:
-            return None
-        return int(match.group(1))
-
-    @staticmethod
-    def _is_rate_limited(exc: DataSourceError) -> bool:
-        """Detect whether an error indicates rate limiting (429 / Retry-After)."""
-        context = exc.context if isinstance(exc.context, dict) else {}
-        if bool(context.get("rate_limited")):
-            return True
-        fragments = [
-            str(exc),
-            str(context.get("stderr") or ""),
-            str(context.get("stdout") or ""),
-            str(context.get("error") or ""),
-        ]
-        blob = "\n".join(fragments).lower()
-        return "429" in blob or "retry-after" in blob or "rate limit" in blob
-
-    @staticmethod
-    def _page_id(page: dict[str, object] | None) -> str | None:
-        """Extract page ID from heterogeneous payloads (id/page_id)."""
-        if not isinstance(page, dict):
-            return None
-        raw = page.get("id")
-        if raw is None:
-            raw = page.get("page_id")
-        if raw is None:
-            return None
-        normalized = str(raw).strip()
-        return normalized or None
-
-    @staticmethod
-    def _parent_id(page: dict[str, object] | None) -> str | None:
-        """Extract parent ID from heterogeneous payloads."""
-        if not isinstance(page, dict):
-            return None
-        raw = page.get("parent_id")
-        if raw is None:
-            raw = page.get("parentId")
-        if raw is None:
-            raw = page.get("parent_page_id")
-        if raw is None:
-            return None
-        normalized = str(raw).strip()
-        return normalized or None
-
-    def _page_url(self, page: dict[str, object] | None, *, fallback_page_id: str | None = None) -> str:
-        """Resolve page URL from links or schema fallbacks (page_url/url)."""
-        if not isinstance(page, dict):
-            if fallback_page_id:
-                return f"/pages/viewpage.action?pageId={fallback_page_id}"
-            return ""
-
-        links_raw = page.get("_links")
-        links = links_raw if isinstance(links_raw, dict) else {}
-        base_url = str((links or {}).get("base") or "").strip()
-        if not base_url:
-            base_url = self._resolve_base_url(str((links or {}).get("self") or ""))
-        web_ui = str((links or {}).get("webui") or "").strip()
-        if base_url and web_ui:
-            return f"{base_url}{web_ui}"
-
-        for key in ("page_url", "url"):
-            value = str(page.get(key) or "").strip()
-            if value:
-                return value
-
-        self_link = str((links or {}).get("self") or "").strip()
-        if self_link:
-            return self_link
-        if fallback_page_id:
-            return f"/pages/viewpage.action?pageId={fallback_page_id}"
-        return ""
-
-    @staticmethod
-    def _lineage_node(
-        *,
-        page_id: str,
-        title: str | None,
-        page_url: str | None,
-    ) -> dict[str, str | None]:
-        return {
-            "page_id": str(page_id or "").strip(),
-            "title": str(title).strip() if isinstance(title, str) and str(title).strip() else None,
-            "page_url": str(page_url).strip() if isinstance(page_url, str) and str(page_url).strip() else None,
-        }
-
-    def _derive_department_from_lineage(
-        self,
-        *,
-        lineage: list[dict[str, str | None]],
-        registry_root_id: str,
-        registry_root_title: str | None,
-        projects_root_id: str | None,
-        candidate_root_id: str,
-    ) -> tuple[str | None, str | None, str]:
-        if not lineage:
-            return None, None, "unassigned:lineage_empty"
-        if len(lineage) < 2:
-            return None, None, "unassigned:lineage_missing_ancestor"
-
-        ancestors = lineage[:-1]
-
-        def _node_after_anchor(anchor_id: str | None) -> tuple[dict[str, str | None] | None, str]:
-            normalized_anchor = str(anchor_id or "").strip()
-            if not normalized_anchor:
-                return None, "anchor_missing"
-            for index, node in enumerate(ancestors):
-                if str(node.get("page_id") or "").strip() != normalized_anchor:
-                    continue
-                if index + 1 < len(ancestors):
-                    return ancestors[index + 1], "ok"
-                return None, "anchor_has_no_descendant"
-            return None, "anchor_not_in_lineage"
-
-        normalized_projects_root = str(projects_root_id or "").strip()
-        normalized_registry_root = str(registry_root_id or "").strip()
-        if normalized_projects_root and normalized_projects_root != normalized_registry_root:
-            node_after_projects_root, projects_root_status = _node_after_anchor(projects_root_id)
-            if node_after_projects_root is not None:
-                page_id = str(node_after_projects_root.get("page_id") or "").strip()
-                title = str(node_after_projects_root.get("title") or "").strip()
-                if page_id:
-                    return title or f"page-{page_id}", page_id, "derived_from_projects_root_lineage"
-                return None, None, "unassigned:department_node_missing_page_id"
-
-        container_ancestors: list[tuple[int, dict[str, str | None]]] = []
-        for index, node in enumerate(ancestors):
-            title = str(node.get("title") or "").strip()
-            if self.classify_root_child(title) == RootChildType.PROJECT_CONTAINER:
-                container_ancestors.append((index, node))
-
-        if container_ancestors:
-            candidate_projects_root = str(projects_root_id or "").strip()
-            selected_index, selected_node = container_ancestors[-1]
-            selected_page_id = str(selected_node.get("page_id") or "").strip()
-            selected_title = str(selected_node.get("title") or "").strip()
-            projects_root_index: int | None = None
-            if candidate_projects_root:
-                for container_index, container_node in container_ancestors:
-                    if str(container_node.get("page_id") or "").strip() == candidate_projects_root:
-                        projects_root_index = container_index
-                        break
-            if selected_page_id:
-                if selected_page_id == str(registry_root_id or "").strip():
-                    return (
-                        selected_title or f"page-{selected_page_id}",
-                        selected_page_id,
-                        "derived_from_registry_root_anchor",
-                    )
-                if selected_page_id == candidate_projects_root:
-                    return (
-                        selected_title or f"page-{selected_page_id}",
-                        selected_page_id,
-                        "derived_from_projects_root_anchor",
-                    )
-                if selected_page_id == str(candidate_root_id or "").strip():
-                    return (
-                        selected_title or f"page-{selected_page_id}",
-                        selected_page_id,
-                        "derived_from_candidate_root_anchor",
-                    )
-                if projects_root_index is not None and selected_index > projects_root_index:
-                    return (
-                        selected_title or f"page-{selected_page_id}",
-                        selected_page_id,
-                        "derived_from_projects_root_lineage",
-                    )
-                if selected_page_id == str(candidate_root_id or "").strip():
-                    return (
-                        selected_title or f"page-{selected_page_id}",
-                        selected_page_id,
-                        "derived_from_candidate_root_anchor",
-                    )
-
-                for anchor_id, anchor_reason in (
-                    (projects_root_id, "derived_from_projects_root_lineage"),
-                    (candidate_root_id, "derived_from_candidate_root_lineage"),
-                ):
-                    normalized_anchor = str(anchor_id or "").strip()
-                    if not normalized_anchor:
-                        continue
-                    for container_index, container_node in container_ancestors:
-                        if str(container_node.get("page_id") or "").strip() != normalized_anchor:
-                            continue
-                        if selected_index > container_index:
-                            return selected_title or f"page-{selected_page_id}", selected_page_id, anchor_reason
-
-                return (
-                    selected_title or f"page-{selected_page_id}",
-                    selected_page_id,
-                    "derived_from_lineage_nearest_container",
-                )
-
-        def _node_after_anchor(anchor_id: str | None) -> tuple[dict[str, str | None] | None, str]:
-            normalized_anchor = str(anchor_id or "").strip()
-            if not normalized_anchor:
-                return None, "anchor_missing"
-            for index, node in enumerate(ancestors):
-                if str(node.get("page_id") or "").strip() != normalized_anchor:
-                    continue
-                if index + 1 < len(ancestors):
-                    return ancestors[index + 1], "ok"
-                return None, "anchor_has_no_descendant"
-            return None, "anchor_not_in_lineage"
-
-        projects_root_status = "anchor_missing"
-        if projects_root_id:
-            node_after_projects_root, projects_root_status = _node_after_anchor(projects_root_id)
-            if node_after_projects_root is not None:
-                page_id = str(node_after_projects_root.get("page_id") or "").strip()
-                title = str(node_after_projects_root.get("title") or "").strip()
-                if page_id:
-                    return title or f"page-{page_id}", page_id, "derived_from_projects_root_lineage"
-                return None, None, "unassigned:department_node_missing_page_id"
-            if projects_root_status == "anchor_has_no_descendant":
-                normalized_projects_root = str(projects_root_id or "").strip()
-                normalized_registry_root = str(registry_root_id or "").strip()
-                if normalized_projects_root and normalized_projects_root != normalized_registry_root:
-                    for node in ancestors:
-                        page_id = str(node.get("page_id") or "").strip()
-                        if page_id != normalized_projects_root:
-                            continue
-                        title = str(node.get("title") or "").strip()
-                        return title or f"page-{page_id}", page_id, "derived_from_projects_root_anchor"
-                if normalized_projects_root and normalized_projects_root == normalized_registry_root:
-                    root_title = str(registry_root_title or "").strip()
-                    if root_title and self.classify_root_child(root_title) == RootChildType.PROJECT_CONTAINER:
-                        return root_title, normalized_registry_root, "derived_from_registry_root_anchor"
-                    # Department-level entry: single ancestor IS the registry root.
-                    # The entry page is both root and department (self-referencing).
-                    if len(ancestors) == 1:
-                        ancestor_id = str(ancestors[0].get("page_id") or "").strip()
-                        ancestor_title = str(ancestors[0].get("title") or "").strip()
-                        if ancestor_id == normalized_registry_root:
-                            return (
-                                ancestor_title or f"page-{ancestor_id}",
-                                ancestor_id,
-                                "derived_from_department_entry_self_reference",
-                            )
-                return None, None, "unassigned:lineage_missing_department_after_projects_root"
-
-        node_after_candidate_root, candidate_status = _node_after_anchor(candidate_root_id)
-        if node_after_candidate_root is not None:
-            page_id = str(node_after_candidate_root.get("page_id") or "").strip()
-            title = str(node_after_candidate_root.get("title") or "").strip()
-            if page_id:
-                if page_id == str(registry_root_id).strip() or (
-                    projects_root_id and page_id == str(projects_root_id).strip()
-                ):
-                    return None, None, "unassigned:lineage_resolved_container_not_department"
-                return title or f"page-{page_id}", page_id, "derived_from_candidate_root_lineage"
-            return None, None, "unassigned:department_node_missing_page_id"
-
-        if candidate_status == "anchor_has_no_descendant":
-            normalized_candidate_root = str(candidate_root_id or "").strip()
-            if normalized_candidate_root and normalized_candidate_root not in {
-                str(registry_root_id).strip(),
-                str(projects_root_id or "").strip(),
-            }:
-                for node in ancestors:
-                    page_id = str(node.get("page_id") or "").strip()
-                    if page_id != normalized_candidate_root:
-                        continue
-                    title = str(node.get("title") or "").strip()
-                    return title or f"page-{page_id}", page_id, "derived_from_candidate_root_anchor"
-            # Department-level entry: single ancestor IS the candidate root.
-            if len(ancestors) == 1:
-                ancestor_id = str(ancestors[0].get("page_id") or "").strip()
-                ancestor_title = str(ancestors[0].get("title") or "").strip()
-                if ancestor_id and ancestor_id == str(candidate_root_id or "").strip():
-                    return (
-                        ancestor_title or f"page-{ancestor_id}",
-                        ancestor_id,
-                        "derived_from_department_entry_self_reference",
-                    )
-            return None, None, "unassigned:lineage_missing_department_after_candidate_root"
-        if projects_root_id and projects_root_status == "anchor_not_in_lineage":
-            return None, None, "unassigned:projects_root_not_in_lineage"
-        if candidate_status == "anchor_not_in_lineage":
-            return None, None, "unassigned:candidate_root_not_in_lineage"
-        return None, None, "unassigned:department_not_resolved"
-
-    def _apply_lineage_metadata(
-        self,
-        *,
-        material: ProjectMaterial,
-        lineage: list[dict[str, str | None]],
-        registry_root_id: str,
-        registry_root_title: str | None,
-        projects_root_id: str | None,
-        candidate_root_id: str,
-    ) -> None:
-        normalized_lineage: list[dict[str, str | None]] = []
-        for node in lineage:
-            if not isinstance(node, dict):
-                continue
-            page_id = str(node.get("page_id") or "").strip()
-            if not page_id:
-                continue
-            normalized_lineage.append(
-                self._lineage_node(
-                    page_id=page_id,
-                    title=str(node.get("title") or "").strip() or None,
-                    page_url=str(node.get("page_url") or "").strip() or None,
-                )
-            )
-
-        effective_registry_root_title = str(registry_root_title or "").strip() or None
-        ancestry_nodes = list(normalized_lineage)
-        if normalized_lineage:
-            first_node = normalized_lineage[0]
-            root_page_id = str(first_node.get("page_id") or "").strip() or None
-            root_title = str(first_node.get("title") or "").strip() or None
-            if root_page_id and root_page_id == str(registry_root_id or "").strip():
-                fallback_root_title = effective_registry_root_title
-                if normalized_lineage and len(normalized_lineage) > 1:
-                    next_node_title = str(normalized_lineage[1].get("title") or "").strip() or None
-                    if next_node_title and self.classify_root_child(next_node_title) == RootChildType.PROJECT_CONTAINER:
-                        fallback_root_title = next_node_title
-                if not root_title:
-                    root_title = fallback_root_title
-            material.root_page_id = root_page_id
-            material.root_title = root_title
-            material.root_storage_key = normalize_storage_key(root_title or root_page_id or "unassigned")
-            if root_page_id and root_page_id == str(registry_root_id or "").strip():
-                material.root_assignment_reason = "derived_from_registry_root_lineage_head"
-                if len(normalized_lineage) > 1 and root_title == root_page_id:
-                    ancestry_nodes = normalized_lineage[1:]
-            elif root_page_id and root_page_id == str(candidate_root_id or "").strip():
-                material.root_assignment_reason = "derived_from_candidate_root_lineage_head"
-            else:
-                material.root_assignment_reason = "derived_from_lineage_head"
-            if str(first_node.get("page_id") or "").strip() == str(registry_root_id or "").strip():
-                lineage_root_title = str(first_node.get("title") or "").strip() or None
-                if lineage_root_title:
-                    effective_registry_root_title = lineage_root_title
-        else:
-            material.root_page_id = None
-            material.root_title = None
-            material.root_storage_key = None
-            material.root_assignment_reason = "unassigned:lineage_empty"
-
-        material.confluence_ancestry_path = [
-            ConfluenceAncestryNode(
-                page_id=str(node.get("page_id") or ""),
-                title=node.get("title"),
-                page_url=node.get("page_url"),
-            )
-            for node in ancestry_nodes
-        ]
-        department, department_page_id, assignment_reason = self._derive_department_from_lineage(
-            lineage=normalized_lineage,
-            registry_root_id=registry_root_id,
-            registry_root_title=effective_registry_root_title,
-            projects_root_id=projects_root_id,
-            candidate_root_id=candidate_root_id,
-        )
-        material.department = department
-        material.department_page_id = department_page_id
-        material.department_storage_key = normalize_storage_key(department or "unassigned")
-        material.department_assignment_reason = assignment_reason
-
-    async def _build_parent_chain_lineage(
-        self,
-        *,
-        leaf_page: dict[str, object],
-        max_depth: int | None = None,
-    ) -> list[dict[str, str | None]]:
-        """Walk parent links upward and return normalized lineage from root to leaf."""
-        raw_ancestors = leaf_page.get("ancestors")
-        if isinstance(raw_ancestors, list):
-            lineage: list[dict[str, str | None]] = []
-            for ancestor in raw_ancestors:
-                if not isinstance(ancestor, dict):
-                    continue
-                ancestor_id = self._page_id(ancestor)
-                if not ancestor_id:
-                    continue
-                lineage.append(
-                    self._lineage_node(
-                        page_id=ancestor_id,
-                        title=str(ancestor.get("title", "")).strip() or None,
-                        page_url=self._page_url(ancestor, fallback_page_id=ancestor_id),
-                    )
-                )
-            leaf_page_id = self._page_id(leaf_page)
-            if leaf_page_id:
-                lineage.append(
-                    self._lineage_node(
-                        page_id=leaf_page_id,
-                        title=str(leaf_page.get("title", "")).strip() or None,
-                        page_url=self._page_url(leaf_page, fallback_page_id=leaf_page_id),
-                    )
-                )
-            if lineage:
-                return lineage
-
-        effective_max_depth = max(1, int(max_depth or self.MAX_PARENT_CHAIN_DEPTH))
-        lineage_reversed: list[dict[str, str | None]] = []
-        current_page = leaf_page
-        seen_page_ids: set[str] = set()
-
-        for _ in range(effective_max_depth):
-            current_page_id = self._page_id(current_page)
-            if not current_page_id or current_page_id in seen_page_ids:
-                break
-            seen_page_ids.add(current_page_id)
-            lineage_reversed.append(
-                self._lineage_node(
-                    page_id=current_page_id,
-                    title=str(current_page.get("title", "")).strip() or None,
-                    page_url=self._page_url(current_page, fallback_page_id=current_page_id),
-                )
-            )
-            parent_id = self._parent_id(current_page)
-            if not parent_id:
-                break
-            parent_page = self._get_prefetch_page(parent_id) or await self._get_page_with_cache(parent_id)
-            if not isinstance(parent_page, dict):
-                break
-            current_page = parent_page
-
-        return list(reversed(lineage_reversed))
-
-    def _projects_root_id_from_lineage(self, lineage: list[dict[str, str | None]]) -> str | None:
-        """Infer the projects-root/container page from a normalized ancestry lineage."""
-        for node in lineage[:-1]:
-            page_id = str(node.get("page_id") or "").strip()
-            title = str(node.get("title") or "").strip()
-            if not page_id or not title:
-                continue
-            if self.classify_root_child(title) == RootChildType.PROJECT_CONTAINER:
-                return page_id
-        return None
-
-    @staticmethod
-    def _title_looks_like_department_container(title: str | None) -> bool:
-        normalized = str(title or "").strip()
-        if not normalized:
-            return False
-        return bool(re.match(r"^\d+\.\d+\.\d+(?:\s|$)", normalized))
-
-    async def _resolve_effective_registry_root_context(
-        self,
-        *,
-        page_id: str,
-        page_payload: dict[str, object] | None,
-    ) -> tuple[dict[str, object] | None, str, str | None]:
-        payload = page_payload if isinstance(page_payload, dict) else None
-        normalized_page_id = str(page_id or "").strip()
-        if payload is None and max(1, int(self.recursive_depth or 1)) > 1:
-            try:
-                fetched_payload = await self._retry(
-                    lambda: self.client.get_page(normalized_page_id), page_id=normalized_page_id
-                )
-            except Exception:
-                fetched_payload = None
-            if isinstance(fetched_payload, dict):
-                payload = fetched_payload
-        title = str((payload or {}).get("title") or "").strip() or normalized_page_id
-
-        if (
-            self.classify_root_child(title) != RootChildType.PROJECT_CONTAINER
-            or not self._title_looks_like_department_container(title)
-            or not isinstance(payload, dict)
-        ):
-            return payload, normalized_page_id, title or None
-
-        if self._parent_id(payload) is None and not isinstance(payload.get("ancestors"), list):
-            enriched_payload = await self._retry(
-                lambda: self.client.get_page(normalized_page_id, expand="ancestors"),
-                page_id=normalized_page_id,
-                expand="ancestors",
-            )
-            if isinstance(enriched_payload, dict):
-                payload = enriched_payload
-
-        lineage = await self._build_parent_chain_lineage(leaf_page=payload, max_depth=3)
-        container_ancestors = [
-            node
-            for node in lineage[:-1]
-            if self.classify_root_child(str(node.get("title") or "").strip()) == RootChildType.PROJECT_CONTAINER
-        ]
-        if container_ancestors:
-            selected = container_ancestors[-1]
-            selected_id = str(selected.get("page_id") or "").strip() or normalized_page_id
-            selected_title = str(selected.get("title") or "").strip() or title
-            return payload, selected_id, selected_title or None
-
-        return payload, normalized_page_id, title or None
-
-    async def _parse_registry_entry_as_project(
-        self,
-        *,
-        page_id: str,
-        page_payload: dict[str, object] | None,
-    ) -> ProjectMaterial | None:
-        """Parse a direct project-page registry entry and backfill ancestry from parent links."""
-        payload = page_payload if isinstance(page_payload, dict) else await self._get_page_with_cache(page_id)
-        if not isinstance(payload, dict):
-            return None
-
-        if self._parent_id(payload) is None and not isinstance(payload.get("ancestors"), list):
-            enriched_payload = await self._retry(
-                lambda: self.client.get_page(page_id, expand="ancestors"),
-                page_id=page_id,
-                expand="ancestors",
-            )
-            if isinstance(enriched_payload, dict):
-                payload = enriched_payload
-
-        title = str(payload.get("title") or "").strip() or page_id
-        material = await self.parse_project_page(page_id, title, page_payload=payload)
-        if material is None:
-            return None
-
-        descendant_pages = await self._collect_atomic_project_descendants(page_id=page_id, max_depth=2)
-        material.child_pages = [
-            ChildPage(
-                page_id=page["page_id"],
-                title=page["title"],
-                page_url=page["page_url"],
-                depth=page["depth"],
-            )
-            for page in descendant_pages
-        ]
-        material.bitbucket_projects = self._derive_bitbucket_projects_from_child_pages(
-            [page["payload"] for page in descendant_pages if isinstance(page.get("payload"), dict)]
-        )
-
-        lineage = await self._build_parent_chain_lineage(leaf_page=payload)
-        if not lineage:
-            lineage = [
-                self._lineage_node(
-                    page_id=page_id,
-                    title=title,
-                    page_url=self._page_url(payload, fallback_page_id=page_id),
-                )
-            ]
-        registry_root_node = lineage[0]
-        candidate_root_id = str(lineage[-2].get("page_id") or "").strip() if len(lineage) >= 2 else page_id
-        self._apply_lineage_metadata(
-            material=material,
-            lineage=lineage,
-            registry_root_id=str(registry_root_node.get("page_id") or "").strip() or page_id,
-            registry_root_title=str(registry_root_node.get("title") or "").strip() or title,
-            projects_root_id=self._projects_root_id_from_lineage(lineage),
-            candidate_root_id=candidate_root_id,
-        )
-        return material
-
-    @classmethod
-    def _repository_slug_from_title(cls, title: str) -> tuple[str, str] | None:
-        normalized_title = str(title or "").strip()
-        if not normalized_title:
-            return None
-        lowered = normalized_title.casefold()
-        if not lowered.startswith(cls._REPOSITORY_TITLE_PREFIX):
-            return None
-        suffix = normalized_title[len(cls._REPOSITORY_TITLE_PREFIX) :].strip()
-        normalized_suffix = normalize_storage_key(suffix)
-        if not normalized_suffix:
-            return None
-        parts = [part for part in normalized_suffix.split("-") if part]
-        if len(parts) >= 2:
-            return parts[0].upper(), "-".join(parts[1:])
-        return "", normalized_suffix
-
-    @staticmethod
-    def _local_repo_path_for_slug(*, bitbucket_project_key: str, repo_slug: str) -> str | None:
-        project_key = str(bitbucket_project_key or "").strip().lower()
-        slug = str(repo_slug or "").strip()
-        if not project_key or not slug:
-            return None
-        candidate = Path.home() / ".vds" / "cache" / "repos" / f"{project_key}-project" / slug
-        if candidate.exists() and candidate.is_dir():
-            return str(candidate)
-        return None
-
-    def _derive_bitbucket_projects_from_child_pages(self, child_pages: list[dict[str, object]]) -> list[dict[str, Any]]:
-        grouped: dict[str, dict[str, Any]] = {}
-        for child in child_pages:
-            title = str(child.get("title") or "").strip()
-            page_id = self._page_id(child)
-            repo_identity = self._repository_slug_from_title(title)
-            if repo_identity is None:
-                continue
-            bitbucket_project_key, repo_slug = repo_identity
-            if not bitbucket_project_key or not repo_slug:
-                continue
-            group = grouped.setdefault(
-                bitbucket_project_key,
-                {
-                    "bitbucket_project_key": bitbucket_project_key,
-                    "display_name": bitbucket_project_key,
-                    "source": "registry_child_repository_pages",
-                    "repos": [],
-                },
-            )
-            group["repos"].append(
-                {
-                    "repo_storage_key": f"{bitbucket_project_key.lower()}:{repo_slug}",
-                    "repo_slug": repo_slug,
-                    "repo_url": None,
-                    "default_branch": "main",
-                    "status": "discovered",
-                    "path": self._page_url(child, fallback_page_id=str(page_id or repo_slug)),
-                    "source_page_id": str(page_id or ""),
-                    "source_title": title,
-                    "fetch_reason": "registry_child_repository_page",
-                    "local_code_path": self._local_repo_path_for_slug(
-                        bitbucket_project_key=bitbucket_project_key,
-                        repo_slug=repo_slug,
-                    ),
-                }
-            )
-
-        return [
-            {
-                **payload,
-                "repos": sorted(
-                    payload["repos"],
-                    key=lambda item: (
-                        str(item.get("repo_slug") or ""),
-                        str(item.get("repo_storage_key") or ""),
-                    ),
-                ),
-            }
-            for _, payload in sorted(grouped.items(), key=lambda item: item[0])
-        ]
-
-    async def _collect_atomic_project_descendants(self, *, page_id: str, max_depth: int) -> list[dict[str, Any]]:
-        descendants: list[dict[str, Any]] = []
-        queue: deque[tuple[str, int]] = deque([(page_id, 0)])
-        seen: set[str] = {str(page_id).strip()}
-
-        while queue:
-            current_page_id, depth = queue.popleft()
-            if depth >= max_depth:
-                continue
-            children = await self._get_children(current_page_id)
-            for child in children:
-                child_page_id = self._page_id(child)
-                if not child_page_id or child_page_id in seen:
-                    continue
-                seen.add(child_page_id)
-                descendants.append(
-                    {
-                        "page_id": str(child_page_id),
-                        "title": str(child.get("title") or "").strip() or str(child_page_id),
-                        "page_url": self._page_url(child, fallback_page_id=str(child_page_id)),
-                        "depth": depth + 1,
-                        "payload": child,
-                    }
-                )
-                queue.append((str(child_page_id), depth + 1))
-
-        descendants.sort(
-            key=lambda item: (
-                int(item.get("depth") or 0),
-                str(item.get("title") or ""),
-                str(item.get("page_id") or ""),
-            )
-        )
-        return descendants
-
-    @classmethod
-    def _looks_like_atomic_project_entry(
-        cls, *, root_payload: dict[str, Any] | None, root_children: list[dict[str, object]]
-    ) -> bool:
-        title = str((root_payload or {}).get("title") or "").strip()
-        if cls.classify_root_child(title) == RootChildType.PROJECT_CONTAINER:
-            return False
-        return any(
-            cls._repository_slug_from_title(str(child.get("title") or "")) is not None for child in root_children
-        )
-
-    def _load_prefetch_artifacts(self) -> bool:
-        """Load crawl-tree artifacts from prefetch directory (Phase 24 TSK-243.4.5).
-
-        This method loads the crawl_manifest.json and indexes child pages by ID
-        for fast lookup during parsing. This allows the parser to use local
-        artifacts instead of making network calls.
-
-        Returns:
-            True if prefetch artifacts were loaded successfully, False otherwise.
-        """
-        self._prefetch_manifest = None
-        self._prefetch_pages = {}
-        self._prefetch_children_by_parent = {}
-        if not self.prefetch_dir or not self.prefetch_dir.exists():
-            return False
-
-        manifest_path = self.prefetch_dir / "crawl_manifest.json"
-        if not manifest_path.exists():
-            logger.debug("prefetch_manifest_not_found", path=str(manifest_path))
-            return False
-
-        try:
-            with manifest_path.open("r", encoding="utf-8") as f:
-                self._prefetch_manifest = json.load(f)
-        except (json.JSONDecodeError, OSError) as e:
-            logger.warning("prefetch_manifest_load_failed", path=str(manifest_path), error=str(e))
-            return False
-
-        if self._prefetch_manifest is None:
-            return False
-
-        # Index child pages by ID for fast lookup.
-        child_pages = self._prefetch_manifest.get("child_pages", [])
-        for page in child_pages:
-            page_id = self._page_id(page)
-            if page_id:
-                self._prefetch_pages[page_id] = page
-            parent_id = self._parent_id(page)
-            if parent_id:
-                self._prefetch_children_by_parent.setdefault(parent_id, []).append(page)
-
-        # Also index the root page.
-        root_page = self._prefetch_manifest.get("page")
-        root_page_id = self._page_id(root_page)
-        manifest_root_id = str(self._prefetch_manifest.get("root_page_id") or "").strip()
-        if root_page_id and isinstance(root_page, dict):
-            self._prefetch_pages[root_page_id] = root_page
-
-        logger.info(
-            "prefetch_artifacts_loaded",
-            manifest_path=str(manifest_path),
-            root_page_id=manifest_root_id or self._prefetch_manifest.get("root_page_id"),
-            child_pages_count=len(child_pages),
-            indexed_pages=len(self._prefetch_pages),
-        )
-        return True
-
-    def _get_prefetch_page(self, page_id: str) -> dict | None:
-        """Get a page from prefetch cache by ID.
-
-        Args:
-            page_id: The Confluence page ID.
-
-        Returns:
-            Page data dict if found in prefetch cache, None otherwise.
-        """
-        page = self._prefetch_pages.get(str(page_id))
-        if page is None:
-            self._diag_prefetch_misses += 1
-            return None
-        self._diag_prefetch_hits += 1
-        return page
-
-    def _get_prefetch_children(self, parent_id: str) -> list[dict] | None:
-        """Get child pages from prefetch cache.
-
-        Args:
-            parent_id: The parent page ID.
-
-        Returns:
-            List of child page dicts if found in prefetch cache, None otherwise.
-        """
-        if not self._prefetch_manifest:
-            return None
-
-        parent_id_str = str(parent_id)
-
-        # If parent is the root page, return all child_pages.
-        root_page_id = str(self._prefetch_manifest.get("root_page_id") or "").strip()
-        if root_page_id and parent_id_str == root_page_id:
-            self._diag_prefetch_hits += 1
-            return self._prefetch_manifest.get("child_pages", [])
-
-        # For non-root pages, use indexed parent->children map.
-        children = self._prefetch_children_by_parent.get(parent_id_str, [])
-        if children:
-            self._diag_prefetch_hits += 1
-            return children
-
-        # Known page with no children is still a prefetch hit (leaf).
-        if parent_id_str in self._prefetch_pages:
-            self._diag_prefetch_hits += 1
-            return []
-
-        self._diag_prefetch_misses += 1
-        return None
-
-    async def _get_children(self, parent_id: str, *, expand: str | None = None) -> list[dict]:
-        """Get child pages with prefetch + network cache fallback.
-
-        Uses prefetch artifacts when available, then reuses in-memory network
-        results to avoid repeated downloads across multi-pass traversal.
-        """
-        prefetch_children = self._get_prefetch_children(parent_id)
-        if prefetch_children is not None:
-            logger.debug(
-                "using_prefetch_children",
-                parent_id=parent_id,
-                count=len(prefetch_children),
-            )
-            return prefetch_children
-
-        needs_body = expand == "body.storage"
-        cache_key = (str(parent_id), needs_body)
-        if cache_key in self._network_children_cache:
-            children = self._network_children_cache[cache_key]
-            logger.debug(
-                "network_children_cache_hit",
-                parent_id=parent_id,
-                count=len(children),
-                expand=expand,
-            )
-            return children
-
-        rich_key = (str(parent_id), True)
-        if not needs_body and rich_key in self._network_children_cache:
-            children = self._network_children_cache[rich_key]
-            logger.debug(
-                "network_children_cache_hit",
-                parent_id=parent_id,
-                count=len(children),
-                expand="body.storage",
-                reused_for_expand=expand,
-            )
-            return children
-
-        self._diag_network_fetches += 1
-        if self.prefetch_dir is not None:
-            self._diag_fallback_fetches += 1
-        children = await self._retry(
-            lambda cid=parent_id, child_expand=expand: self.client.get_child_pages(cid, expand=child_expand),
-            parent_id=parent_id,
-            expand=expand,
-        )
-        normalized_children = children or []
-        self._network_children_cache[cache_key] = normalized_children
-        logger.debug(
-            "network_children_fetched",
-            parent_id=parent_id,
-            count=len(normalized_children),
-            expand=expand,
-        )
-        return normalized_children
-
-    @staticmethod
-    def classify_root_child(title: str) -> RootChildType:
-        """Deterministically classify a root child page by title pattern (Phase 24).
-
-        This implements FR-24.1.2: deterministic root-child classification based on
-        title patterns. The classification is used by checklist-first mode to avoid
-        unnecessary deep traversal.
-
-        Classification rules:
-        - "3.1" prefix or "checklist" in title → CHECKLIST
-        - "3.2" prefix or "hệ thống"/"nền tảng" in title → PROJECT_CONTAINER
-        - "audit history" in title → AUDIT_HISTORY
-        - Otherwise → UNKNOWN
-
-        Args:
-            title: The page title to classify.
-
-        Returns:
-            RootChildType indicating the classification.
-        """
-        normalized = (title or "").strip().lower()
-        if not normalized:
-            return RootChildType.UNKNOWN
-
-        # Check for checklist page (3.1 prefix or "checklist" keyword).
-        if normalized.startswith("3.1") or "checklist" in normalized:
-            return RootChildType.CHECKLIST
-
-        # Check for project container (3.2 prefix or Vietnamese keywords).
-        if normalized.startswith("3.2"):
-            return RootChildType.PROJECT_CONTAINER
-        if "hệ thống" in normalized or "nền tảng" in normalized:
-            return RootChildType.PROJECT_CONTAINER
-
-        # Check for audit history (excluded from project discovery).
-        if "audit history" in normalized:
-            return RootChildType.AUDIT_HISTORY
-
-        # Phase 133: Exclude publisher-created audit artifact pages.
-        if any(
-            normalized.startswith(p)
-            for p in (
-                "project analysis -",
-                "project audit -",
-                "audit results -",
-                "repository -",
-            )
-        ):
-            return RootChildType.AUDIT_HISTORY
-
-        return RootChildType.UNKNOWN
-
-    @staticmethod
-    def _classify_checklist_profile_id(title: str) -> tuple[str, int]:
-        """Classify checklist profile id from title patterns (Phase 101)."""
-        normalized = (title or "").strip().lower()
-        if not normalized:
-            return "default", 0
-        matches: list[str] = []
-        keyword_map: tuple[tuple[str, tuple[str, ...]], ...] = (
-            ("backend", ("backend", "back-end", "phía sau", "máy chủ")),
-            ("frontend", ("frontend", "front-end", "front end", "giao diện", "giao dien", "phía trước")),
-            ("mobile", ("mobile", "ios", "android", "mini app", "miniapp", "di động")),
-            ("infra", ("infra", "infrastructure", "devops", "platform", "hạ tầng")),
-        )
-        for profile_id, keywords in keyword_map:
-            if any(keyword in normalized for keyword in keywords):
-                matches.append(profile_id)
-        if len(matches) == 1:
-            return matches[0], 1
-        if len(matches) > 1:
-            return "default", len(matches)
-        return "default", 0
-
-    @staticmethod
-    def _extract_checklist_version(title: str) -> tuple[str, tuple[int, ...]]:
-        """Extract version suffix from a checklist title (Phase 112).
-
-        Returns (base_title, version_tuple) where base_title is the title with the
-        version suffix stripped, and version_tuple is a comparable tuple of integers.
-        Titles without a version suffix are treated as (0,) — the lowest version —
-        so that a versioned successor (e.g. "v1.1") always supersedes the original.
-
-        Examples:
-            "3.1 Checklist đánh giá v1.1"  → ("3.1 Checklist đánh giá", (1, 1))
-            "3.1 Checklist đánh giá"        → ("3.1 Checklist đánh giá", (0,))
-            "Checklist v2"                  → ("Checklist", (2,))
-        """
-        # Match trailing version patterns: v1, v1.0, v1.1, V2.3.1, etc.
-        version_re = re.compile(r"\s+v(\d+(?:\.\d+)*)\s*$", re.IGNORECASE)
-        match = version_re.search((title or "").strip())
-        if match:
-            base = (title or "").strip()[: match.start()].strip()
-            version = tuple(int(part) for part in match.group(1).split("."))
-            return base, version
-        return (title or "").strip(), (0,)
-
-    @staticmethod
-    def _profile_display_name(profile_id: str, fallback_title: str | None = None) -> str:
-        fallback = str(fallback_title or "").strip()
-        if fallback:
-            return fallback
-        mapping = {
-            "backend": "Backend Checklist",
-            "frontend": "Frontend Checklist",
-            "mobile": "Mobile Checklist",
-            "infra": "Infrastructure Checklist",
-            "default": "Default Checklist",
-        }
-        return mapping.get(profile_id, "Default Checklist")
-
-    @staticmethod
-    def _build_checklist_profiles(
-        checklist_candidates: list[dict[str, Any]],
-    ) -> tuple[list[ChecklistProfile], dict[str, int]]:
-        """Build deterministic checklist profile catalog from discovered candidates."""
-        if not checklist_candidates:
-            return [], {
-                "candidate_count": 0,
-                "classified_count": 0,
-                "ambiguous_count": 0,
-                "superseded_count": 0,
-            }
-
-        profile_priority: dict[str, int] = {
-            "backend": 10,
-            "frontend": 20,
-            "mobile": 30,
-            "infra": 40,
-            "default": 100,
-        }
-        grouped: dict[str, dict[str, Any]] = {}
-        classified_count = 0
-        ambiguous_count = 0
-
-        superseded_count = 0
-        for index, candidate in enumerate(checklist_candidates):
-            title = str(candidate.get("title") or "").strip()
-            profile_id_raw, match_count = RegistryPageParser._classify_checklist_profile_id(title)
-            profile_id = str(candidate.get("profile_id") or profile_id_raw).strip().lower() or "default"
-            if match_count == 1:
-                classified_count += 1
-            elif match_count > 1:
-                ambiguous_count += 1
-
-            page_id = str(candidate.get("id") or "").strip()
-            page_url = str(candidate.get("url") or "").strip()
-            if not page_id:
-                continue
-
-            bucket = grouped.setdefault(
-                profile_id,
-                {
-                    "page_ids": [],
-                    "page_urls": [],
-                    "titles": [],
-                    "display_name": RegistryPageParser._profile_display_name(profile_id, title),
-                    "first_index": index,
-                },
-            )
-            if page_id not in bucket["page_ids"]:
-                bucket["page_ids"].append(page_id)
-                bucket["page_urls"].append(page_url)
-                bucket["titles"].append(title)
-            bucket["first_index"] = min(int(bucket["first_index"]), index)
-
-        # Phase 112: Version-aware deduplication within each profile bucket.
-        # When multiple pages share the same base title (differing only by a version
-        # suffix like "v1.1"), keep only the highest-versioned page.  The legacy
-        # page (no version suffix, treated as v0) is superseded by any versioned
-        # successor.  This prevents legacy page IDs (e.g. 88716673) from persisting
-        # alongside their current replacements (e.g. 88722450).
-        for profile_id, bucket in grouped.items():
-            page_ids = bucket["page_ids"]
-            page_urls = bucket["page_urls"]
-            titles = bucket.get("titles", [])
-            if len(page_ids) <= 1:
-                continue
-            # Group by base title → pick highest version per group
-            base_groups: dict[str, list[tuple[int, str, str, str, tuple[int, ...]]]] = {}
-            for i, (pid, purl) in enumerate(zip(page_ids, page_urls, strict=False)):
-                t = titles[i] if i < len(titles) else ""
-                base_title, version = RegistryPageParser._extract_checklist_version(t)
-                base_key = base_title.lower().strip()
-                base_groups.setdefault(base_key, []).append((i, pid, purl, t, version))
-            keep_ids: list[str] = []
-            keep_urls: list[str] = []
-            keep_titles: list[str] = []
-            for base_key, entries in base_groups.items():
-                if len(entries) == 1:
-                    _, pid, purl, t, _ = entries[0]
-                    keep_ids.append(pid)
-                    keep_urls.append(purl)
-                    keep_titles.append(t)
-                else:
-                    # Sort by version descending, keep only the highest
-                    entries.sort(key=lambda e: e[4], reverse=True)
-                    winner = entries[0]
-                    _, pid, purl, t, ver = winner
-                    keep_ids.append(pid)
-                    keep_urls.append(purl)
-                    keep_titles.append(t)
-                    for loser in entries[1:]:
-                        superseded_count += 1
-                        logger.info(
-                            "checklist_page_superseded_by_version",
-                            profile_id=profile_id,
-                            superseded_page_id=loser[1],
-                            superseded_title=loser[3],
-                            superseded_version=".".join(str(v) for v in loser[4]),
-                            kept_page_id=pid,
-                            kept_title=t,
-                            kept_version=".".join(str(v) for v in ver),
-                        )
-            bucket["page_ids"] = keep_ids
-            bucket["page_urls"] = keep_urls
-            bucket["titles"] = keep_titles
-
-        profiles: list[ChecklistProfile] = []
-        for profile_id, payload in sorted(
-            grouped.items(),
-            key=lambda item: (
-                profile_priority.get(item[0], 1000),
-                int(item[1].get("first_index", 0)),
-                item[0],
-            ),
-        ):
-            repo_type_filters = [profile_id] if profile_id in {"backend", "frontend", "mobile", "infra"} else None
-            profiles.append(
-                ChecklistProfile(
-                    profile_id=profile_id,
-                    display_name=str(payload.get("display_name") or "Default Checklist"),
-                    page_ids=[str(page_id) for page_id in payload.get("page_ids", []) if str(page_id).strip()],
-                    page_urls=[str(page_url) for page_url in payload.get("page_urls", []) if str(page_url).strip()],
-                    priority=profile_priority.get(profile_id, 1000),
-                    repo_type_filters=repo_type_filters,
-                    loader_hints={"source": "registry_parser_root_discovery"},
-                )
-            )
-        return profiles, {
-            "candidate_count": len(checklist_candidates),
-            "classified_count": classified_count,
-            "ambiguous_count": ambiguous_count,
-            "superseded_count": superseded_count,
-        }
-
-    @staticmethod
-    def _is_project_candidate_title(title: str) -> tuple[bool, SkippedNodeReason | None]:
-        """Heuristic filter to skip obvious non-project nodes in registry trees.
-
-        Phase 24 TSK-242: Enhanced filtering with reason codes for telemetry.
-
-        Returns:
-            Tuple of (is_candidate, skip_reason) where skip_reason is None if
-            the page is a valid project candidate.
-        """
-        normalized = (title or "").strip().lower()
-        if not normalized:
-            return False, SkippedNodeReason.EMPTY_TITLE
-
-        # Exact matches for known non-project pages.
-        excluded_exact = {
-            "audit history",
-            "lịch sử audit",
-            "lịch sử đánh giá",
-        }
-        if normalized in excluded_exact:
-            return False, SkippedNodeReason.AUDIT_HISTORY
-
-        # Patterns that indicate checklist/template pages (not projects).
-        checklist_patterns = {
-            "checklist",
-            "template",
-            "mẫu đánh giá",
-            "tiêu chí đánh giá",
-        }
-        if any(pattern in normalized for pattern in checklist_patterns):
-            return False, SkippedNodeReason.CHECKLIST_NODE
-
-        # Patterns that indicate audit history pages.
-        audit_history_patterns = {
-            "audit history",
-            "lịch sử audit",
-            "kết quả audit",
-            "audit result",
-        }
-        if any(pattern in normalized for pattern in audit_history_patterns):
-            return False, SkippedNodeReason.AUDIT_HISTORY
-
-        # Phase 133: Exclude publisher-created audit artifact pages that should
-        # not be re-discovered as project candidates.  These pages are created
-        # by confluence_publisher._resolve_publish_parent() with deterministic
-        # title prefixes.  Without this filter, parse-registry treats them as
-        # project candidates, inflating the project count and causing readiness
-        # failures on non-project pages.
-        audit_artifact_prefixes = (
-            "project analysis -",
-            "project audit -",
-            "audit results -",
-            "repository -",
-        )
-        if any(normalized.startswith(prefix) for prefix in audit_artifact_prefixes):
-            return False, SkippedNodeReason.AUDIT_HISTORY
-
-        return True, None
-
-    @staticmethod
-    def normalize_url(url: str) -> str:
-        """Normalize a URL for deduplication (Phase 24 TSK-242).
-
-        Normalization rules:
-        - Remove trailing slashes
-        - Normalize Confluence pageId URLs to canonical form
-        - Normalize Bitbucket URLs to canonical form
-        - Convert to lowercase for comparison
-
-        Args:
-            url: The URL to normalize.
-
-        Returns:
-            Normalized URL string.
-        """
-        raw = (url or "").strip()
-        if not raw:
-            return ""
-
-        # Remove trailing slashes (but not from root paths).
-        while raw.endswith("/") and len(raw) > 1 and not raw.endswith("://"):
-            raw = raw[:-1]
-
-        try:
-            parsed = urlparse(raw)
-        except Exception:
-            return raw.lower()
-
-        # Normalize Confluence URLs.
-        if parsed.path.startswith("/pages/viewpage.action"):
-            qs = parse_qs(parsed.query)
-            page_ids = qs.get("pageId", [])
-            if page_ids:
-                # Canonical form: just the pageId parameter.
-                normalized_path = f"/pages/viewpage.action?pageId={page_ids[0]}"
-                return f"{parsed.scheme}://{parsed.netloc}{normalized_path}".lower()
-
-        # Normalize /display/ URLs.
-        if parsed.path.startswith("/display/"):
-            # Remove any trailing query params for display URLs.
-            return f"{parsed.scheme}://{parsed.netloc}{parsed.path}".lower()
-
-        # Normalize Bitbucket URLs.
-        if "bitbucket" in parsed.netloc.lower() or "git" in parsed.netloc.lower():
-            # Remove common trailing paths like /browse.
-            path = parsed.path
-            if path.endswith("/browse"):
-                path = path[:-7]
-            return f"{parsed.scheme}://{parsed.netloc}{path}".lower()
-
-        return raw.lower()
-
-    def deduplicate_links(self, links: list[DocumentLink]) -> list[DocumentLink]:
-        """Deduplicate document links by normalized URL (Phase 24 TSK-242).
-
-        When duplicates are found, the first occurrence is kept.
-
-        Args:
-            links: List of document links to deduplicate.
-
-        Returns:
-            Deduplicated list of document links.
-        """
-        seen_urls: set[str] = set()
-        deduplicated: list[DocumentLink] = []
-
-        for link in links:
-            normalized = self.normalize_url(link.url)
-            if normalized in seen_urls:
-                logger.debug(
-                    "duplicate_link_skipped",
-                    url=link.url,
-                    normalized_url=normalized,
-                )
-                continue
-            seen_urls.add(normalized)
-            deduplicated.append(link)
-
-        if len(links) != len(deduplicated):
-            logger.info(
-                "links_deduplicated",
-                original_count=len(links),
-                deduplicated_count=len(deduplicated),
-                removed_count=len(links) - len(deduplicated),
-            )
-
-        return deduplicated
-
-    async def _retry(self, fn, *, timeout: float | None = None, **log_ctx):
-        """Retry vds-cli backed calls (Confluence can be flaky/slow).
-
-        Args:
-            fn: Async function to call.
-            timeout: Optional per-call timeout in seconds (overrides step_timeout).
-            **log_ctx: Additional context for logging.
-
-        Returns:
-            Result of the function call, or None if all retries failed.
-        """
-        retries = self.retries
-        base_delay = self.backoff
-        effective_timeout = timeout if timeout is not None else self.step_timeout
-
-        for attempt in range(retries + 1):
-            try:
-                if effective_timeout is not None:
-                    return await asyncio.wait_for(fn(), timeout=effective_timeout)
-                return await fn()
-            except TimeoutError:
-                logger.warning(
-                    "confluence_request_timeout",
-                    attempt=attempt + 1,
-                    timeout_seconds=effective_timeout,
-                    **log_ctx,
-                )
-                if attempt >= retries:
-                    return None
-                self._diag_retry_count += 1
-                raw_delay = base_delay * (2**attempt)
-                delay = min(raw_delay, self.MAX_BACKOFF_SECONDS)
-                if delay != raw_delay:
-                    logger.debug(
-                        "confluence_retry_delay_capped",
-                        raw_delay_seconds=raw_delay,
-                        capped_delay_seconds=delay,
-                        max_backoff_seconds=self.MAX_BACKOFF_SECONDS,
-                        **log_ctx,
-                    )
-                await asyncio.sleep(delay)
-            except DataSourceError as exc:
-                rate_limited = self._is_rate_limited(exc)
-                retry_after_seconds = self._extract_retry_after_seconds(exc)
-                if rate_limited:
-                    self._diag_rate_limit_events += 1
-                if retry_after_seconds is not None:
-                    self._diag_retry_after_seconds = max(self._diag_retry_after_seconds or 0, retry_after_seconds)
-                if attempt >= retries:
-                    logger.warning("confluence_request_failed", attempt=attempt + 1, error=str(exc), **log_ctx)
-                    return None
-                self._diag_retry_count += 1
-                raw_delay = base_delay * (2**attempt)
-                delay = raw_delay
-                if retry_after_seconds is not None:
-                    delay = max(delay, float(retry_after_seconds))
-                delay = min(delay, self.MAX_BACKOFF_SECONDS)
-                logger.warning(
-                    "confluence_request_retry",
-                    attempt=attempt + 1,
-                    retries=retries,
-                    delay_seconds=delay,
-                    max_backoff_seconds=self.MAX_BACKOFF_SECONDS,
-                    rate_limited=rate_limited,
-                    retry_after_seconds=retry_after_seconds,
-                    error=str(exc),
-                    **log_ctx,
-                )
-                await asyncio.sleep(delay)
-        return None
-
-    async def parse_registry(self, root_id: str) -> ProjectRegistry:
-        """Parse the registry structure starting from a root page.
-
-        Args:
-            root_id: The ID of the registry root page (e.g. 88716667).
-
-        Returns:
-            ProjectRegistry object containing discovered projects.
-            If some pages fail or timeout, returns partial results with
-            diagnostics indicating the failures (Phase 24 TSK-243).
-        """
-        start_time = time.monotonic()
-        diagnostics = ParseDiagnostics()
-        self._reset_parse_diagnostics_tracking()
-
-        # Phase 24 TSK-243.4.5: Try to load prefetch artifacts first.
-        prefetch_load_started = time.monotonic()
-        prefetch_loaded = self._load_prefetch_artifacts()
-        self._record_step_timing("prefetch_load", prefetch_load_started)
-        diagnostics.prefetch_pages_indexed = len(self._prefetch_pages)
-        if prefetch_loaded:
-            logger.info("using_prefetch_artifacts", prefetch_dir=str(self.prefetch_dir))
-
-        root_page_payload = self._get_prefetch_page(root_id)
-        root_children = await self._get_children(root_id)
-        (
-            root_page_payload,
-            effective_registry_root_id,
-            effective_registry_root_title,
-        ) = await self._resolve_effective_registry_root_context(
-            page_id=root_id,
-            page_payload=root_page_payload if isinstance(root_page_payload, dict) else None,
-        )
-
-        registry = ProjectRegistry(
-            registry_url=f"/pages/viewpage.action?pageId={root_id}",
-            registry_page_id=root_id,
-            mapping_version=MAPPING_VERSION,
-        )
-
-        if self._looks_like_atomic_project_entry(
-            root_payload=root_page_payload if isinstance(root_page_payload, dict) else None,
-            root_children=root_children,
-        ):
-            direct_project = await self._parse_registry_entry_as_project(
-                page_id=root_id,
-                page_payload=root_page_payload if isinstance(root_page_payload, dict) else None,
-            )
-            if direct_project is not None:
-                registry.projects = [direct_project]
-
-        # Phase 36 hard cutover: checklist-first is the only supported runtime mode.
-        discovery_started = time.monotonic()
-        projects_root_id, checklist_candidates = await self._find_projects_root_and_checklist_deterministic(root_id)
-        self._record_step_timing("discover_root_and_checklist", discovery_started)
-
-        # Phase 101: Populate dynamic checklist profile catalog.
-        checklist_profiles, checklist_discovery_diag = self._build_checklist_profiles(checklist_candidates)
-        registry.checklist_profiles = checklist_profiles
-        logger.info(
-            "checklist_profile_discovery",
-            candidate_count=checklist_discovery_diag["candidate_count"],
-            classified_count=checklist_discovery_diag["classified_count"],
-            ambiguous_count=checklist_discovery_diag["ambiguous_count"],
-            superseded_count=checklist_discovery_diag.get("superseded_count", 0),
-            profile_count=len(checklist_profiles),
-            profile_ids=[profile.profile_id for profile in checklist_profiles],
-        )
-
-        candidate_roots = await self._derive_candidate_roots(root_id, projects_root_id)
-        root_title = str((root_page_payload or {}).get("title") or "").strip()
-
-        # Phase 24 TSK-242: Collect skipped nodes for telemetry.
-        all_skipped_nodes: list[SkippedNode] = []
-        if projects_root_id and str(projects_root_id).strip() != str(root_id).strip():
-            root_container_page = next(
-                (
-                    page
-                    for page in root_children
-                    if str(self._page_id(page) or "").strip() == str(projects_root_id).strip()
-                ),
-                None,
-            )
-            if isinstance(root_container_page, dict):
-                all_skipped_nodes.append(
-                    SkippedNode(
-                        page_id=str(projects_root_id),
-                        title=str(root_container_page.get("title", "")),
-                        reason=SkippedNodeReason.PROJECT_CONTAINER,
-                        details="Container page with child pages is parsed recursively, not as an atomic project leaf",
-                    )
-                )
-
-        aggregated_projects: list[ProjectMaterial] = []
-        for candidate in candidate_roots:
-            logger.debug(
-                "registry_candidate_root_parse_start",
-                candidate_root_id=candidate,
-                recursive_depth=max(1, int(self.recursive_depth or 1)),
-            )
-            find_projects_started = time.monotonic()
-            base_depth = max(1, int(self.recursive_depth or 1))
-            projects, skipped_nodes, parse_stats = await self._find_projects(
-                candidate,
-                recursive_depth=base_depth,
-                registry_root_id=effective_registry_root_id,
-                registry_root_title=effective_registry_root_title or root_title or None,
-                projects_root_id=projects_root_id,
-            )
-            self._record_step_timing("find_projects", find_projects_started)
-            all_skipped_nodes.extend(skipped_nodes)
-
-            # Phase 24 TSK-243: Aggregate diagnostics.
-            diagnostics.total_pages_attempted += int(str(parse_stats.get("attempted", 0)))
-            diagnostics.total_pages_succeeded += int(str(parse_stats.get("succeeded", 0)))
-            diagnostics.adaptive_candidate_count += int(str(parse_stats.get("candidate_count", 0)))
-            diagnostics.adaptive_no_links_count += int(str(parse_stats.get("no_links_count", 0)))
-            timed_out = parse_stats.get("timed_out", [])
-            if isinstance(timed_out, list):
-                diagnostics.timed_out_pages.extend(timed_out)
-            failed = parse_stats.get("failed", [])
-            if isinstance(failed, list):
-                diagnostics.failed_pages.extend(failed)
-            diagnostics.max_projects_reached = diagnostics.max_projects_reached or bool(
-                parse_stats.get("max_projects_reached", False)
-            )
-
-            if projects:
-                aggregated_projects.extend(projects)
-                aggregated_projects = self._deduplicate_and_sort_projects(aggregated_projects)
-                registry.projects = aggregated_projects
-
-        # Phase 35: Adaptive deepening (checklist-first only, explicit depth remains authoritative).
-        base_depth = max(1, int(self.recursive_depth or 1))
-        adaptive_target_depth = max(base_depth, int(self.adaptive_max_depth))
-        explicit_depth_override = base_depth > 1
-        adaptive_no_links_signal = diagnostics.adaptive_no_links_count > 0
-        adaptive_zero_candidate_signal = (not registry.projects) and diagnostics.adaptive_candidate_count == 0
-        adaptive_trigger = bool(
-            self.adaptive_depth
-            and not explicit_depth_override
-            and (adaptive_no_links_signal or adaptive_zero_candidate_signal)
-            and adaptive_target_depth > base_depth
-        )
-        if adaptive_trigger:
-            diagnostics.adaptive_depth_applied = True
-            diagnostics.adaptive_depth_from = base_depth
-            diagnostics.adaptive_depth_to = base_depth
-            if adaptive_zero_candidate_signal and not adaptive_no_links_signal:
-                diagnostics.adaptive_trigger_reason = "zero_projects_with_zero_candidates"
-            else:
-                diagnostics.adaptive_trigger_reason = (
-                    "zero_projects_with_no_links_signal"
-                    if not registry.projects
-                    else "partial_projects_with_no_links_signal"
-                )
-
-            merged_projects = list(registry.projects)
-            for depth in range(base_depth + 1, adaptive_target_depth + 1):
-                adaptive_find_started = time.monotonic()
-                pass_projects: list[ProjectMaterial] = []
-                for candidate in candidate_roots:
-                    projects, skipped_nodes, parse_stats = await self._find_projects(
-                        candidate,
-                        recursive_depth=depth,
-                        registry_root_id=effective_registry_root_id,
-                        registry_root_title=root_title or effective_registry_root_title or None,
-                        projects_root_id=projects_root_id,
-                    )
-                    all_skipped_nodes.extend(skipped_nodes)
-
-                    diagnostics.total_pages_attempted += int(str(parse_stats.get("attempted", 0)))
-                    diagnostics.total_pages_succeeded += int(str(parse_stats.get("succeeded", 0)))
-                    timed_out = parse_stats.get("timed_out", [])
-                    if isinstance(timed_out, list):
-                        diagnostics.timed_out_pages.extend(timed_out)
-                    failed = parse_stats.get("failed", [])
-                    if isinstance(failed, list):
-                        diagnostics.failed_pages.extend(failed)
-                    diagnostics.max_projects_reached = diagnostics.max_projects_reached or bool(
-                        parse_stats.get("max_projects_reached", False)
-                    )
-                    if projects:
-                        pass_projects.extend(projects)
-
-                merged_projects.extend(pass_projects)
-                merged_projects = self._deduplicate_and_sort_projects(merged_projects)
-                registry.projects = merged_projects
-                diagnostics.adaptive_depth_to = depth
-                self._record_step_timing("find_projects_adaptive", adaptive_find_started)
-
-        root_entry_looks_container = bool(root_children) and not self._looks_like_atomic_project_entry(
-            root_payload=root_page_payload if isinstance(root_page_payload, dict) else None,
-            root_children=root_children,
-        )
-        if not registry.projects and not diagnostics.prefetch_insufficient_coverage and not root_entry_looks_container:
-            direct_project = await self._parse_registry_entry_as_project(
-                page_id=root_id,
-                page_payload=root_page_payload if isinstance(root_page_payload, dict) else None,
-            )
-            if direct_project is not None:
-                registry.projects = [direct_project]
-
-        # Phase 24 TSK-242: Persist skipped-node telemetry.
-        registry.skipped_nodes = all_skipped_nodes
-        if all_skipped_nodes:
-            logger.info(
-                "registry_skipped_nodes",
-                total_skipped=len(all_skipped_nodes),
-                by_reason={
-                    reason.value: sum(1 for n in all_skipped_nodes if n.reason == reason)
-                    for reason in SkippedNodeReason
-                    if any(n.reason == reason for n in all_skipped_nodes)
-                },
-            )
-
-        if not registry.projects:
-            prefetch_hint: str | None = None
-            if prefetch_loaded and diagnostics.prefetch_pages_indexed > 0:
-                diagnostics.prefetch_insufficient_coverage = True
-                prefetch_hint = (
-                    "Prefetch artifacts may be too shallow for project discovery. "
-                    "Rebuild crawl artifacts with deeper traversal (for this registry layout, start with depth>=2). "
-                    "If using CLI bootstrap, parse-registry supports --staged-crawl-mode with --prefetch-depth."
-                )
-                diagnostics.prefetch_hint = prefetch_hint
-            logger.warning(
-                "projects_not_found",
-                root_id=root_id,
-                projects_root_id=projects_root_id,
-                prefetch_loaded=prefetch_loaded,
-                prefetch_pages_indexed=diagnostics.prefetch_pages_indexed,
-                prefetch_hint=prefetch_hint,
-            )
-
-        # Phase 24 TSK-243: Finalize diagnostics.
-        elapsed_ms = int((time.monotonic() - start_time) * 1000)
-        diagnostics.parse_duration_ms = elapsed_ms
-        diagnostics.partial_success = bool(
-            diagnostics.timed_out_pages or diagnostics.failed_pages or diagnostics.max_projects_reached
-        )
-        diagnostics.prefetch_hits = self._diag_prefetch_hits
-        diagnostics.prefetch_misses = self._diag_prefetch_misses
-        diagnostics.network_fetches = self._diag_network_fetches
-        diagnostics.fallback_fetches = self._diag_fallback_fetches
-        diagnostics.timed_out_pages = self._deduplicate_page_ids(diagnostics.timed_out_pages)
-        diagnostics.failed_pages = self._deduplicate_page_ids(diagnostics.failed_pages)
-        diagnostics.step_timings_ms = dict(self._diag_step_timings_ms)
-        diagnostics.retry_count = self._diag_retry_count
-        diagnostics.rate_limit_events = self._diag_rate_limit_events
-        diagnostics.retry_after_seconds = self._diag_retry_after_seconds
-        diagnostics.effective_retries = self.retries
-        diagnostics.effective_backoff_seconds = self.backoff
-        diagnostics.max_backoff_seconds = self.MAX_BACKOFF_SECONDS
-        diagnostics.effective_step_timeout_seconds = self.step_timeout
-        has_transient_failures = bool(diagnostics.timed_out_pages or diagnostics.failed_pages)
-        diagnostics.can_retry = bool(has_transient_failures or diagnostics.rate_limit_events > 0)
-        if has_transient_failures and not registry.projects:
-            diagnostics.result_status = "fail_fast"
-            diagnostics.result_message = (
-                "No projects were parsed because all candidate pages failed or timed out. "
-                "Retry with higher --timeout/--step-timeout, lower --parse-concurrency, or smaller --max-projects."
-            )
-        elif diagnostics.partial_success:
-            diagnostics.result_status = "partial_success"
-            diagnostics.result_message = (
-                "Registry parsed partially: some pages failed or timed out, but partial project results are available."
-            )
-        else:
-            diagnostics.result_status = "success"
-            diagnostics.result_message = "Registry parsed successfully."
-        registry.diagnostics = diagnostics
-
-        if diagnostics.result_status == "fail_fast":
-            logger.error(
-                "registry_parse_fail_fast",
-                duration_ms=elapsed_ms,
-                projects_found=len(registry.projects),
-                timed_out_count=len(diagnostics.timed_out_pages),
-                failed_count=len(diagnostics.failed_pages),
-            )
-        elif diagnostics.partial_success:
-            logger.warning(
-                "registry_parse_partial_success",
-                duration_ms=elapsed_ms,
-                projects_found=len(registry.projects),
-                timed_out_count=len(diagnostics.timed_out_pages),
-                failed_count=len(diagnostics.failed_pages),
-                max_projects_reached=diagnostics.max_projects_reached,
-            )
-        else:
-            logger.info(
-                "registry_parse_complete",
-                duration_ms=elapsed_ms,
-                projects_found=len(registry.projects),
-            )
-
-        return registry
-
-    @staticmethod
-    def _deduplicate_page_ids(page_ids: list[str]) -> list[str]:
-        """Return deterministic unique page IDs (numeric-first ordering)."""
-        deduped = {str(page_id).strip() for page_id in page_ids if str(page_id).strip()}
-        return sorted(deduped, key=RegistryPageParser._page_id_sort_key)
-
-    @staticmethod
-    def _page_id_sort_key(page_id: str) -> tuple[int, int | str, str]:
-        raw = str(page_id).strip()
-        if raw.isdigit():
-            return (0, int(raw), raw)
-        return (1, raw, raw)
-
-    @classmethod
-    def _deduplicate_and_sort_projects(cls, projects: list[ProjectMaterial]) -> list[ProjectMaterial]:
-        """Deduplicate project materials by page_id and return deterministic order."""
-        by_page_id: dict[str, ProjectMaterial] = {}
-        for project in projects:
-            page_id = str(project.page_id).strip()
-            if not page_id or page_id in by_page_id:
-                continue
-            by_page_id[page_id] = project
-        return [by_page_id[page_id] for page_id in sorted(by_page_id, key=cls._page_id_sort_key)]
-
-    async def _derive_candidate_roots(self, root_id: str, projects_root_id: str | None) -> list[str]:
-        """Build ordered candidate roots for resilient hierarchy traversal.
-
-        Keeps the discovered projects root first when available, then adds other
-        non-checklist root children as fallback start points.
-        """
-        candidates: list[str] = []
-        seen: set[str] = set()
-
-        def _add(candidate_id: str | None) -> None:
-            normalized = str(candidate_id or "").strip()
-            if not normalized or normalized in seen:
-                return
-            seen.add(normalized)
-            candidates.append(normalized)
-
-        _add(projects_root_id)
-        if not projects_root_id or str(projects_root_id).strip() == str(root_id).strip():
-            _add(root_id)
-
-        root_children = await self._get_children(root_id)
-        for child in root_children:
-            child_id = self._page_id(child)
-            if not child_id:
-                continue
-            child_title = str(child.get("title", "")).strip()
-            classification = self.classify_root_child(child_title)
-            if classification in {RootChildType.CHECKLIST, RootChildType.AUDIT_HISTORY}:
-                continue
-            _add(child_id)
-
-        logger.info(
-            "registry_candidate_roots_derived",
-            root_id=root_id,
-            projects_root_id=projects_root_id,
-            candidates=candidates,
-        )
-        return candidates
-
-    async def _find_projects_root_and_checklist_deterministic(
-        self, root_id: str
-    ) -> tuple[str | None, list[dict[str, str]]]:
-        """Find projects root and checklist using deterministic classification (Phase 24).
-
-        This implements the checklist-first discovery strategy (FR-24.2.1) which uses
-        deterministic title pattern matching instead of flexible heuristics.
-        Phase 24 TSK-243.4.5: Uses prefetch artifacts when available.
-
-        Args:
-            root_id: The registry root page ID.
-
-        Returns:
-            Tuple of (projects_root_id, checklist_candidates) where checklist_candidates
-            is ordered by deterministic discovery sequence.
-        """
-        # Phase 24: Handle explicit checklist override (TSK-241.2.4).
-        checklist_candidates: list[dict[str, str]] = []
-        if self.checklist_page_override:
-            checklist_candidates.append(
-                {
-                    "id": self.checklist_page_override,
-                    "title": "Explicit override",
-                    "url": f"/pages/viewpage.action?pageId={self.checklist_page_override}",
-                    "profile_id": "default",
-                }
-            )
-            logger.info(
-                "checklist_page_override_used",
-                page_id=self.checklist_page_override,
-            )
-
-        results = await self._get_children(root_id)
-
-        projects_root_id: str | None = None
-        root_page = self._get_prefetch_page(root_id)
-        root_title = str((root_page or {}).get("title") or "").strip() if isinstance(root_page, dict) else ""
-        inferred_projects_root_title = ""
-        if results:
-            for page in results:
-                title = str(page.get("title", "")).strip()
-                if self.classify_root_child(title) == RootChildType.PROJECT_CONTAINER:
-                    inferred_projects_root_title = title
-                    break
-        if not root_title and (max(1, int(self.recursive_depth or 1)) > 1 or not inferred_projects_root_title):
-            try:
-                root_page = await self._retry(lambda: self.client.get_page(root_id), page_id=root_id)
-            except Exception:
-                root_page = None
-            root_title = str((root_page or {}).get("title") or "").strip() if isinstance(root_page, dict) else ""
-        root_classification = self.classify_root_child(root_title)
-        if root_classification == RootChildType.PROJECT_CONTAINER and not inferred_projects_root_title:
-            projects_root_id = root_id
-
-        # Classify each root child deterministically.
-        for page in results:
-            title = str(page.get("title", "")).strip()
-            page_id = self._page_id(page)
-            if not page_id:
-                continue
-            classification = self.classify_root_child(title)
-
-            logger.debug(
-                "root_child_classified",
-                page_id=page_id,
-                title=title,
-                classification=classification.value,
-            )
-
-            if classification == RootChildType.CHECKLIST:
-                page_url = self._page_url(page, fallback_page_id=page_id)
-                profile_id, _ = self._classify_checklist_profile_id(title)
-                checklist_candidates.append(
-                    {
-                        "id": page_id,
-                        "title": title,
-                        "url": page_url,
-                        "profile_id": profile_id,
-                    }
-                )
-                logger.info(
-                    "checklist_page_discovered_deterministic",
-                    page_id=page_id,
-                    title=title,
-                    profile_id=profile_id,
-                )
-
-            elif classification == RootChildType.PROJECT_CONTAINER and not projects_root_id:
-                projects_root_id = page_id
-                logger.info(
-                    "projects_root_discovered_deterministic",
-                    page_id=page_id,
-                    title=title,
-                )
-                logger.info(
-                    "projects_root_marked_recursive_container",
-                    page_id=page_id,
-                    title=title,
-                )
-
-        # FR-269 (DD-153): Emit structured diagnostic when checklist discovery fails.
-        if not checklist_candidates:
-            child_titles = [str(page.get("title", "")).strip() for page in results if self._page_id(page)]
-            logger.warning(
-                "checklist_discovery_failed",
-                root_id=root_id,
-                searched_patterns=[
-                    "title starting with '3.1'",
-                    "title containing 'checklist'",
-                ],
-                child_pages_found=child_titles,
-                child_page_count=len(child_titles),
-                guidance=(
-                    "No checklist page was discovered among root children. "
-                    "Pass --checklist-page <PAGE_ID> explicitly to bypass "
-                    "automatic discovery."
-                ),
-            )
-
-        return projects_root_id, checklist_candidates
-
-    async def _find_projects(
-        self,
-        parent_id: str,
-        *,
-        recursive_depth: int | None = None,
-        registry_root_id: str,
-        registry_root_title: str | None,
-        projects_root_id: str | None,
-    ) -> tuple[list[ProjectMaterial], list[SkippedNode], dict[str, object]]:
-        """Find individual project pages under the parent.
-
-        Phase 24 TSK-242: Enhanced to track skipped nodes for telemetry.
-        Phase 24 TSK-243: Enhanced to support max_projects limit and track
-        timeout/failure statistics for partial-success behavior.
-        Phase 24 TSK-243.4.5: Uses prefetch artifacts when available.
-
-        Returns:
-            Tuple of (projects, skipped_nodes, parse_stats) where:
-            - projects: Successfully parsed project materials
-            - skipped_nodes: Records of pages that were filtered out during parsing
-            - parse_stats: Dictionary with parsing statistics:
-              - attempted: Total pages attempted
-              - succeeded: Pages successfully parsed
-              - timed_out: List of page IDs that timed out
-              - failed: List of page IDs that failed (non-timeout)
-              - max_projects_reached: Whether max_projects limit was hit
-        """
-        projects: list[ProjectMaterial] = []
-        skipped_nodes: list[SkippedNode] = []
-        parse_stats: dict[str, object] = {
-            "attempted": 0,
-            "succeeded": 0,
-            "timed_out": [],
-            "failed": [],
-            "max_projects_reached": False,
-            "candidate_count": 0,
-            "no_links_count": 0,
-        }
-
-        # Depth-limited traversal: recursive_depth=1 means direct children only.
-        # Avoid using CQL ancestor queries because Confluence does not provide true depth limits.
-        effective_recursive_depth = self.recursive_depth if recursive_depth is None else recursive_depth
-        max_depth = max(1, int(effective_recursive_depth or 1))
-        root_payload = self._prefetch_pages.get(str(parent_id), {})
-        if not isinstance(root_payload, dict):
-            root_payload = {}
-        root_title = str(root_payload.get("title") or "").strip()
-        if not root_title and parent_id != str(registry_root_id).strip():
-            registry_children = await self._get_children(str(registry_root_id).strip())
-            for registry_child in registry_children:
-                if str(self._page_id(registry_child) or "").strip() != str(parent_id).strip():
-                    continue
-                root_title = str(registry_child.get("title") or "").strip()
-                if root_title:
-                    break
-        should_fetch_root_title = (
-            not root_title
-            and max_depth > 1
-            and (
-                parent_id != str(registry_root_id).strip()
-                or str(projects_root_id or "").strip() == str(registry_root_id).strip()
-            )
-        )
-        if should_fetch_root_title:
-            fetched_root = await self._retry(lambda: self.client.get_page(parent_id), page_id=parent_id)
-            if isinstance(fetched_root, dict):
-                root_payload = fetched_root
-                root_title = str(fetched_root.get("title") or "").strip()
-        root_url = self._page_url(root_payload, fallback_page_id=parent_id)
-        root_lineage = [self._lineage_node(page_id=parent_id, title=root_title or None, page_url=root_url)]
-        normalized_registry_root_id = str(registry_root_id or "").strip()
-        normalized_parent_id = str(parent_id or "").strip()
-        if normalized_registry_root_id and normalized_registry_root_id != normalized_parent_id:
-            registry_root_payload = self._prefetch_pages.get(normalized_registry_root_id, {})
-            if not isinstance(registry_root_payload, dict):
-                registry_root_payload = {}
-            registry_root_url = self._page_url(registry_root_payload, fallback_page_id=normalized_registry_root_id)
-            root_lineage = [
-                self._lineage_node(
-                    page_id=normalized_registry_root_id,
-                    title=registry_root_title or None,
-                    page_url=registry_root_url,
-                ),
-                *root_lineage,
-            ]
-
-        queue: deque[tuple[str, int, list[dict[str, str | None]]]] = deque([(parent_id, 0, root_lineage)])
-        seen: set[str] = {parent_id}
-        container_page_ids: set[str] = set()
-        pages: list[dict[str, object]] = []
-        discovery_started = time.monotonic()
-        logger.debug(
-            "registry_project_traversal_start",
-            parent_id=parent_id,
-            max_depth=max_depth,
-        )
-
-        while queue:
-            current_id, depth, current_lineage = queue.popleft()
-            if depth >= max_depth:
-                continue
-
-            # Checklist-first keeps root discovery lightweight, but when fetching
-            # leaf candidate pages (depth + 1 == max_depth), include body.storage
-            # to avoid per-page follow-up get_page calls.
-            expand = "body.storage" if (depth + 1) >= max_depth else None
-            children = await self._get_children(current_id, expand=expand)
-            if children:
-                container_page_ids.add(current_id)
-
-            for child in children:
-                page_id = self._page_id(child)
-                if not page_id:
-                    continue
-                if page_id in seen:
-                    # Track duplicate pages.
-                    skipped_nodes.append(
-                        SkippedNode(
-                            page_id=str(page_id),
-                            title=str(child.get("title", "")),
-                            reason=SkippedNodeReason.DUPLICATE,
-                            details="Page already processed in traversal",
-                        )
-                    )
-                    continue
-                if depth == 0 and current_id == parent_id:
-                    classification = self.classify_root_child(str(child.get("title", "")).strip())
-                    if str(current_id).strip() == str(registry_root_id).strip():
-                        if classification == RootChildType.CHECKLIST:
-                            skipped_nodes.append(
-                                SkippedNode(
-                                    page_id=str(page_id),
-                                    title=str(child.get("title", "")),
-                                    reason=SkippedNodeReason.CHECKLIST_NODE,
-                                    details="Checklist root branch pruned from project traversal",
-                                )
-                            )
-                            continue
-                        if classification == RootChildType.AUDIT_HISTORY:
-                            skipped_nodes.append(
-                                SkippedNode(
-                                    page_id=str(page_id),
-                                    title=str(child.get("title", "")),
-                                    reason=SkippedNodeReason.AUDIT_HISTORY,
-                                    details="Audit-history root branch pruned from project traversal",
-                                )
-                            )
-                            continue
-                    if classification == RootChildType.PROJECT_CONTAINER:
-                        skipped_nodes.append(
-                            SkippedNode(
-                                page_id=str(page_id),
-                                title=str(child.get("title", "")),
-                                reason=SkippedNodeReason.PROJECT_CONTAINER,
-                                details="Container page with child pages is parsed recursively, not as an atomic project leaf",
-                            )
-                        )
-                seen.add(page_id)
-                child_node = self._lineage_node(
-                    page_id=page_id,
-                    title=str(child.get("title", "")).strip() or None,
-                    page_url=self._page_url(child, fallback_page_id=page_id),
-                )
-                child_lineage = [*current_lineage, child_node]
-                pages.append(
-                    {
-                        "id": page_id,
-                        "title": child.get("title", ""),
-                        "page": child,
-                        "lineage": child_lineage,
-                    }
-                )
-                queue.append((page_id, depth + 1, child_lineage))
-
-        self._record_step_timing("discover_candidates", discovery_started)
-
-        # Parallelize parsing with bounded semaphore to reduce Confluence timeout pressure.
-        semaphore = asyncio.Semaphore(self.parse_concurrency)
-
-        # Phase 24 TSK-243: Track timeout and failure statistics.
-        timed_out_pages: list[str] = []
-        failed_pages: list[str] = []
-
-        async def _parse_with_sem(
-            p_id: str,
-            p_title: str,
-            page_payload: dict[str, object] | None,
-        ) -> tuple[ProjectMaterial | None, str | None]:
-            """Parse a project page with semaphore and timeout handling.
-
-            Returns:
-                Tuple of (material, error_type) where error_type is:
-                - None: Success
-                - "timeout": Page timed out
-                - "failed": Other error
-            """
-            async with semaphore:
-                try:
-                    if self.step_timeout is not None:
-                        material = await asyncio.wait_for(
-                            self.parse_project_page(p_id, p_title, page_payload=page_payload),
-                            timeout=self.step_timeout,
-                        )
-                    else:
-                        material = await self.parse_project_page(p_id, p_title, page_payload=page_payload)
-                    return material, None
-                except TimeoutError:
-                    logger.warning("project_parse_timeout", page_id=p_id, title=p_title)
-                    return None, "timeout"
-                except Exception as e:
-                    logger.warning("project_parse_failed", page_id=p_id, title=p_title, error=str(e))
-                    return None, "failed"
-
-        # Filter pages and track skipped nodes.
-        candidate_pages = []
-        for page in pages:
-            page_id = page.get("id")
-            page_title = str(page.get("title", ""))
-            if not page_id:
-                continue
-            page_lineage = page.get("lineage")
-            page_lineage_nodes = page_lineage if isinstance(page_lineage, list) else []
-            immediate_parent_matches_root = bool(page_lineage_nodes) and str(
-                page_lineage_nodes[-1].get("page_id") or ""
-            ).strip() == str(parent_id)
-            normalized_title = page_title.strip().casefold()
-            if (
-                immediate_parent_matches_root
-                and self.classify_root_child(page_title) == RootChildType.PROJECT_CONTAINER
-                and (str(page_id) in container_page_ids or normalized_title.startswith("3.2"))
-            ):
-                skipped_nodes.append(
-                    SkippedNode(
-                        page_id=str(page_id),
-                        title=page_title,
-                        reason=SkippedNodeReason.PROJECT_CONTAINER,
-                        details="Container page with child pages is parsed recursively, not as an atomic project leaf",
-                    )
-                )
-                logger.debug(
-                    "project_container_skipped_as_leaf",
-                    page_id=page_id,
-                    title=page_title,
-                )
-                continue
-
-            is_candidate, skip_reason = self._is_project_candidate_title(page_title)
-            if not is_candidate and skip_reason:
-                if skip_reason == SkippedNodeReason.CHECKLIST_NODE and str(page_id) in container_page_ids:
-                    is_candidate = True
-                    skip_reason = None
-                else:
-                    skipped_nodes.append(
-                        SkippedNode(
-                            page_id=str(page_id),
-                            title=page_title,
-                            reason=skip_reason,
-                            details=f"Filtered by title pattern: {page_title}",
-                        )
-                    )
-                    logger.debug(
-                        "project_candidate_skipped",
-                        page_id=page_id,
-                        title=page_title,
-                        reason=skip_reason.value,
-                    )
-                    continue
-            candidate_pages.append(page)
-
-        # Phase 24 TSK-243: Apply max_projects limit if configured.
-        max_projects_reached = False
-        parse_stats["candidate_count"] = len(candidate_pages)
-        if self.max_projects is not None and len(candidate_pages) > self.max_projects:
-            logger.info(
-                "max_projects_limit_applied",
-                total_candidates=len(candidate_pages),
-                max_projects=self.max_projects,
-            )
-            # Track skipped pages due to budget limit.
-            for page in candidate_pages[self.max_projects :]:
-                skipped_nodes.append(
-                    SkippedNode(
-                        page_id=str(page["id"]),
-                        title=str(page.get("title", "")),
-                        reason=SkippedNodeReason.MAX_PROJECTS_REACHED,
-                        details=f"Skipped due to --max-projects {self.max_projects} limit",
-                    )
-                )
-            candidate_pages = candidate_pages[: self.max_projects]
-            max_projects_reached = True
-
-        parse_stats["attempted"] = len(candidate_pages)
-        parse_stats["max_projects_reached"] = max_projects_reached
-
-        parse_started = time.monotonic()
-        tasks = [
-            _parse_with_sem(
-                str(page["id"]),
-                str(page.get("title", "")),
-                page.get("page") if isinstance(page.get("page"), dict) else None,
-            )
-            for page in candidate_pages
-        ]
-
-        results = await asyncio.gather(*tasks)
-        self._record_step_timing("parse_project_candidates", parse_started)
-        for idx, (material, error_type) in enumerate(results):
-            page = candidate_pages[idx]
-            page_id = str(page["id"])
-            page_title = str(page.get("title", ""))
-
-            if error_type == "timeout":
-                timed_out_pages.append(page_id)
-                skipped_nodes.append(
-                    SkippedNode(
-                        page_id=page_id,
-                        title=page_title,
-                        reason=SkippedNodeReason.TIMEOUT,
-                        details="Page parsing timed out",
-                    )
-                )
-            elif error_type == "failed":
-                failed_pages.append(page_id)
-                skipped_nodes.append(
-                    SkippedNode(
-                        page_id=page_id,
-                        title=page_title,
-                        reason=SkippedNodeReason.MALFORMED_PAGE,
-                        details="Failed to parse project page",
-                    )
-                )
-            elif material:
-                raw_lineage = page.get("lineage")
-                lineage = cast("list[dict[str, str | None]]", raw_lineage) if isinstance(raw_lineage, list) else []
-                self._apply_lineage_metadata(
-                    material=material,
-                    lineage=lineage,
-                    registry_root_id=registry_root_id,
-                    registry_root_title=registry_root_title,
-                    projects_root_id=projects_root_id,
-                    candidate_root_id=parent_id,
-                )
-
-                # Check if the project has any links - if not, track as skipped.
-                if not material.documents:
-                    parse_stats["no_links_count"] = int(str(parse_stats.get("no_links_count", 0))) + 1
-                    skipped_nodes.append(
-                        SkippedNode(
-                            page_id=page_id,
-                            title=page_title,
-                            reason=SkippedNodeReason.NO_LINKS,
-                            details="Page parsed but no document links found",
-                        )
-                    )
-                    logger.debug(
-                        "project_no_links",
-                        page_id=page_id,
-                        title=page_title,
-                    )
-                else:
-                    projects.append(material)
-                    current_success = parse_stats.get("succeeded", 0)
-                    parse_stats["succeeded"] = int(str(current_success)) + 1
-
-        parse_stats["timed_out"] = timed_out_pages
-        parse_stats["failed"] = failed_pages
-
-        return projects, skipped_nodes, parse_stats
-
-    async def _get_page_with_cache(self, page_id: str) -> dict | None:
-        """Get page body payload with in-memory cache to reduce re-downloads."""
-        cache_key = str(page_id).strip()
-        if cache_key in self._network_page_cache:
-            logger.debug("network_page_cache_hit", page_id=cache_key)
-            return self._network_page_cache[cache_key]
-
-        self._diag_network_fetches += 1
-        if self.prefetch_dir is not None:
-            self._diag_fallback_fetches += 1
-        page = await self._retry(
-            lambda: self.client.get_page(cache_key, expand="body.storage"),
-            page_id=cache_key,
-            expand="body.storage",
-        )
-        self._network_page_cache[cache_key] = page
-        logger.debug("network_page_fetched", page_id=cache_key, found=bool(page))
-        return page
-
-    async def parse_project_page(
-        self,
-        page_id: str,
-        title: str,
-        *,
-        page_payload: dict[str, object] | None = None,
-    ) -> ProjectMaterial | None:
-        """Parse a single project page to extract document links.
-
-        Args:
-            page_id: Confluence page ID.
-            title: Fallback title label (page title is preferred when available).
-        """
-        cache_key = str(page_id).strip()
-        cached_result = self._project_parse_cache.get(cache_key, _CACHE_MISS)
-        if cached_result is not _CACHE_MISS:
-            logger.debug("project_parse_cache_hit", page_id=cache_key, has_material=bool(cached_result))
-            if isinstance(cached_result, ProjectMaterial):
-                return cast("ProjectMaterial", cached_result).model_copy(deep=True)
-            return None
-
-        page = page_payload
-        body = ""
-        if isinstance(page, dict):
-            # Safe navigation with casts
-            page_body = page.get("body")
-            if isinstance(page_body, dict):
-                storage = page_body.get("storage")
-                if isinstance(storage, dict):
-                    body = str(storage.get("value") or "")
-
-        # If payload has no body, try prefetch cache before hitting network.
-        if not body:
-            prefetch_page = self._get_prefetch_page(page_id)
-            if prefetch_page is not None:
-                page = prefetch_page
-                page_body = page.get("body")
-                if isinstance(page_body, dict):
-                    storage = page_body.get("storage")
-                    if isinstance(storage, dict):
-                        body = str(storage.get("value") or "")
-
-        # If storage body is unavailable but crawl-tree captured local HTML, use it.
-        if not body and isinstance(page, dict):
-            html_path = page.get("html_path")
-            if isinstance(html_path, str) and html_path.strip():
-                html_file = Path(html_path)
-                try:
-                    if html_file.exists():
-                        body = html_file.read_text(encoding="utf-8")
-                except OSError:
-                    # Keep behavior resilient: fall through to network fetch if local read fails.
-                    body = ""
-
-        # If we still do not have body content, fetch full page over network.
-        # In prefetch mode, avoid network fallback for known prefetch pages that
-        # did not capture body/html (typically container nodes) so parse-registry
-        # can run fully offline and remain deterministic.
-        should_skip_network_fallback = bool(
-            self.prefetch_dir is not None and str(page_id) in self._prefetch_pages and not body
-        )
-        if not body and not should_skip_network_fallback:
-            page = await self._get_page_with_cache(page_id)
-        elif should_skip_network_fallback:
-            logger.debug("prefetch_body_missing_skip_network", page_id=page_id)
-        if not page:
-            self._project_parse_cache[cache_key] = None
-            return None
-
-        if not body and isinstance(page, dict):
-            page_body = page.get("body")
-            if isinstance(page_body, dict):
-                storage = page_body.get("storage")
-                if isinstance(storage, dict):
-                    body = str(storage.get("value") or "")
-
-        page_title = page.get("title")
-        resolved_title = page_title if isinstance(page_title, str) and page_title.strip() else str(title or "Unknown")
-        resolved_page_url = self._page_url(page, fallback_page_id=page_id)
-        base_url = self._resolve_base_url(resolved_page_url)
-
-        material = ProjectMaterial(
-            project_name=resolved_title,
-            page_id=page_id,
-            page_url=resolved_page_url,
-        )
-
-        # Extract links from tables
-        links = self._extract_links_from_html(body, base_url)
-
-        # Phase 24 TSK-242: Normalize and deduplicate links.
-        links = self.deduplicate_links(links)
-        await self._resolve_missing_confluence_page_ids(links)
-        material.documents = links
-
-        # Categorize links (using normalized URLs).
-        seen_confluence: set[str] = set()
-        seen_bitbucket: set[str] = set()
-        for doc in links:
-            normalized_url = self.normalize_url(doc.url)
-            if doc.source == LinkSource.CONFLUENCE:
-                if normalized_url not in seen_confluence:
-                    material.confluence_links.append(doc.url)
-                    seen_confluence.add(normalized_url)
-            elif doc.source == LinkSource.BITBUCKET and normalized_url not in seen_bitbucket:
-                material.bitbucket_links.append(doc.url)
-                seen_bitbucket.add(normalized_url)
-
-        self._project_parse_cache[cache_key] = material.model_copy(deep=True)
-        return material
-
-    def _resolve_base_url(self, absolute_url: str) -> str:
-        """Derive base URL from an absolute Confluence link."""
-        raw = (absolute_url or "").strip()
-        if not raw:
-            return ""
-        try:
-            parsed = urlsplit(raw)
-        except Exception:
-            return ""
-        if not parsed.scheme or not parsed.netloc:
-            return ""
-        return f"{parsed.scheme}://{parsed.netloc}"
-
-    def _extract_links_from_html(self, html_content: str, base_url: str) -> list[DocumentLink]:
-        """Extract document links from HTML tables."""
-        soup = BeautifulSoup(html_content, "html.parser")
-        links: list[DocumentLink] = []
-
-        # Find tables - usually structure is Role | Doc Type | Link
-        tables = soup.find_all("table")
-        for table in tables:
-            rows = table.find_all("tr")
-            if not rows:
-                continue
-
-            normalized_rows = self._normalize_table_rows(rows)
-            header_map, header_row_index = self._map_table_headers(rows)
-            link_cols = [idx for idx, key in header_map.items() if key == "link"]
-            for row_index, _row in enumerate(rows):
-                if row_index == header_row_index:
-                    continue
-
-                if row_index >= len(normalized_rows):
-                    continue
-                cells = normalized_rows[row_index]
-                if not cells:
-                    continue
-
-                role = self._extract_role(cells, header_map)
-                doc_type_vn, doc_number = self._extract_doc_type(cells, header_map, "doc_type_vn")
-                doc_type_en, _ = self._extract_doc_type(cells, header_map, "doc_type_en")
-
-                anchor_cells = [cells[idx] for idx in link_cols if idx < len(cells)] if link_cols else cells
-                for cell in anchor_cells:
-                    if cell is None:
-                        continue
-                    cell_seen_urls: set[str] = set()
-                    anchors = cell.find_all("a")
-                    for a in anchors:
-                        href = a.get("href")
-                        if not href:
-                            continue
-
-                        full_url = href if href.startswith("http") else f"{base_url}{href}"
-                        normalized_full_url = self.normalize_url(full_url)
-                        if normalized_full_url in cell_seen_urls:
-                            continue
-                        cell_seen_urls.add(normalized_full_url)
-                        source = self._determine_source(full_url)
-                        page_id = (
-                            self._extract_confluence_page_id(full_url) if source == LinkSource.CONFLUENCE else None
-                        )
-
-                        links.append(
-                            DocumentLink(
-                                role=role,
-                                doc_number=doc_number,
-                                # Prefer VN doc type when present; fall back to EN.
-                                doc_type=doc_type_vn or doc_type_en or "Unknown",
-                                doc_type_en=doc_type_en,
-                                url=full_url,
-                                page_id=page_id,
-                                source=source,
-                                title=a.get_text(strip=True),
-                            )
-                        )
-
-                    # Some Confluence pages keep URLs as plain text (e.g. <span class="nolink">...).
-                    for raw_url in self._extract_plain_urls_from_text(cell.get_text(" ", strip=True)):
-                        normalized_raw_url = self.normalize_url(raw_url)
-                        if normalized_raw_url in cell_seen_urls:
-                            continue
-                        cell_seen_urls.add(normalized_raw_url)
-                        source = self._determine_source(raw_url)
-                        page_id = self._extract_confluence_page_id(raw_url) if source == LinkSource.CONFLUENCE else None
-                        links.append(
-                            DocumentLink(
-                                role=role,
-                                doc_number=doc_number,
-                                doc_type=doc_type_vn or doc_type_en or "Unknown",
-                                doc_type_en=doc_type_en,
-                                url=raw_url,
-                                page_id=page_id,
-                                source=source,
-                                title=raw_url,
-                            )
-                        )
-        return links
-
-    @staticmethod
-    def _extract_plain_urls_from_text(raw_text: str) -> list[str]:
-        """Extract absolute URLs from plain text fragments."""
-        if not raw_text:
-            return []
-        urls: list[str] = []
-        seen: set[str] = set()
-        for match in _PLAIN_TEXT_URL_PATTERN.finditer(raw_text):
-            candidate = match.group(0).rstrip(").,;\"'!?]}")
-            if not candidate:
-                continue
-            if candidate in seen:
-                continue
-            seen.add(candidate)
-            urls.append(candidate)
-        return urls
-
-    def _normalize_table_rows(self, rows: list) -> list[list]:
-        """Normalize HTML table rows into a rectangular cell grid.
-
-        Confluence tables frequently use rowspan/colspan, which makes naive
-        `row.find_all('td')` extraction misalign columns. This helper expands
-        rowspans so cells can be referenced by consistent column index.
-        """
-        # Determine column count from the widest row (accounting for colspan).
-        max_cols = 0
-        for row in rows:
-            width = 0
-            for cell in row.find_all(["th", "td"]):
-                try:
-                    width += int(cell.get("colspan", 1))
-                except Exception:
-                    width += 1
-            max_cols = max(max_cols, width)
-
-        if max_cols == 0:
-            return []
-
-        span_cells: list = [None] * max_cols
-        span_remaining: list[int] = [0] * max_cols
-        normalized: list[list] = []
-
-        for row in rows:
-            row_cells: list = [None] * max_cols
-
-            # Fill from active rowspans.
-            for idx in range(max_cols):
-                if span_remaining[idx] > 0:
-                    row_cells[idx] = span_cells[idx]
-                    span_remaining[idx] -= 1
-                else:
-                    span_cells[idx] = None
-
-            col_idx = 0
-            for cell in row.find_all(["th", "td"]):
-                # Find next empty slot.
-                while col_idx < max_cols and row_cells[col_idx] is not None:
-                    col_idx += 1
-                if col_idx >= max_cols:
-                    break
-
-                try:
-                    colspan = int(cell.get("colspan", 1))
-                except Exception:
-                    colspan = 1
-                try:
-                    rowspan = int(cell.get("rowspan", 1))
-                except Exception:
-                    rowspan = 1
-
-                for offset in range(max(1, colspan)):
-                    target = col_idx + offset
-                    if target >= max_cols:
-                        break
-                    row_cells[target] = cell
-                    if rowspan > 1:
-                        span_cells[target] = cell
-                        span_remaining[target] = max(span_remaining[target], rowspan - 1)
-
-                col_idx += max(1, colspan)
-
-            normalized.append(row_cells)
-
-        return normalized
-
-    def _determine_source(self, url: str) -> LinkSource:
-        if self._looks_like_confluence_url(url):
-            return LinkSource.CONFLUENCE
-        if "bitbucket" in url or "git" in url:
-            return LinkSource.BITBUCKET
-        return LinkSource.OTHER
-
-    def _looks_like_confluence_url(self, url: str) -> bool:
-        """Best-effort detection for Confluence links.
-
-        Registry pages sometimes link to Confluence via IP-based URLs (e.g. 10.x) that
-        don't contain the substring "confluence". We detect those via known Confluence
-        URL shapes instead of relying solely on hostnames.
-        """
-        raw = (url or "").strip()
-        if not raw:
-            return False
-
-        try:
-            parsed = urlparse(raw)
-        except Exception:
-            return False
-
-        host = (parsed.hostname or "").lower()
-        if host in {"confluence.digital.vn", "10.254.136.35", "10.254.136.32"}:
-            return True
-
-        path = parsed.path or ""
-        if path.startswith("/display/"):
-            return True
-        if path.startswith("/pages/viewpage.action"):
-            qs = parse_qs(parsed.query)
-            page_ids = qs.get("pageId", [])
-            if page_ids and str(page_ids[0]).isdigit():
-                return True
-            # Confluence sometimes uses viewpage.action without pageId (rare) - treat as Confluence.
-            return True
-
-        qs = parse_qs(parsed.query)
-        page_ids = qs.get("pageId", [])
-        return bool(page_ids and str(page_ids[0]).isdigit())
-
-    def _extract_confluence_page_id(self, url: str) -> str | None:
-        """Best-effort extraction of numeric Confluence page ID from URL."""
-        raw = str(url or "").strip()
-        if not raw:
-            return None
-        if raw.isdigit():
-            return raw
-        try:
-            parsed = urlparse(raw)
-            qs = parse_qs(parsed.query)
-            for key in ("pageId", "pageid"):
-                values = qs.get(key, [])
-                for value in values:
-                    candidate = str(value or "").strip()
-                    if candidate.isdigit():
-                        return candidate
-        except Exception:
-            pass
-
-        match = re.search(r"(?:^|[?&])pageId=(\d+)", raw, flags=re.IGNORECASE)
-        if match:
-            return match.group(1)
-        return None
-
-    @staticmethod
-    def _extract_confluence_display_ref(url: str) -> tuple[str, str] | None:
-        """Extract (space_key, title) from /display/<SPACE>/<Title> URLs."""
-        raw = str(url or "").strip()
-        if not raw:
-            return None
-        try:
-            parsed = urlparse(raw)
-        except Exception:
-            return None
-        match = re.match(r"^/?display/([^/]+)/([^/]+)$", parsed.path)
-        if not match:
-            return None
-        space_key = str(match.group(1) or "").strip()
-        raw_title = str(match.group(2) or "").strip()
-        if not space_key or not raw_title:
-            return None
-        title = re.sub(r"\s+", " ", unquote_plus(raw_title).replace("+", " ")).strip()
-        if not title:
-            return None
-        return space_key, title
-
-    @staticmethod
-    def _extract_confluence_tiny_id(url: str) -> str | None:
-        """Extract the tinyId from a Confluence short URL (/x/<tinyId>)."""
-        raw = str(url or "").strip()
-        if not raw:
-            return None
-        try:
-            parsed = urlparse(raw)
-        except Exception:
-            return None
-        match = re.match(r"^/?x/([A-Za-z0-9_-]+)$", parsed.path)
-        if not match:
-            return None
-        return match.group(1)
-
-    @staticmethod
-    def _escape_cql(value: str) -> str:
-        return value.replace("\\", "\\\\").replace('"', '\\"')
-
-    @staticmethod
-    def _infer_confluence_server_from_url(url: str) -> str | None:
-        """Infer configured Confluence server alias from URL host when possible."""
-        raw = str(url or "").strip()
-        if not raw:
-            return None
-        try:
-            parsed = urlparse(raw)
-        except Exception:
-            return None
-        host = str(parsed.hostname or "").strip().lower()
-        if host in {"10.254.136.35", "10.254.136.32"}:
-            return "external"
-        if host == "confluence.digital.vn":
-            return "internal"
-        return None
-
-    def _confluence_client_for_url(self, url: str) -> ConfluenceCliClient:
-        """Select a server-aware Confluence client for cross-host /display resolution."""
-        server = self._infer_confluence_server_from_url(url)
-        if not server:
-            return self.client
-        raw_active_server = getattr(self.client, "_server", None)
-        if not isinstance(raw_active_server, str):
-            return self.client
-        active_server = raw_active_server.strip().lower()
-        if not active_server:
-            return self.client
-        if active_server == server:
-            return self.client
-        cached = self._server_scoped_clients.get(server)
-        if cached is not None:
-            return cached
-        scoped = ConfluenceCliClient.for_registry_discovery(
-            server=server,
-            timeout=self._server_scoped_timeout,
-        )
-        self._server_scoped_clients[server] = scoped
-        return scoped
-
-    async def _resolve_page_id_from_confluence_url(self, raw_url: str) -> str | None:
-        """Resolve numeric Confluence page_id from URL; supports /display lookup via CQL."""
-        url = str(raw_url or "").strip()
-        if not url:
-            return None
-        normalized_url = self.normalize_url(url)
-        cached = self._resolved_confluence_page_ids.get(normalized_url, _CACHE_MISS)
-        if cached is not _CACHE_MISS:
-            return cast("str | None", cached)
-
-        direct_page_id = self._extract_confluence_page_id(url)
-        if direct_page_id:
-            self._resolved_confluence_page_ids[normalized_url] = direct_page_id
-            return direct_page_id
-
-        tiny_id = self._extract_confluence_tiny_id(url)
-        if tiny_id:
-            try:
-                resolved_from_tiny = await self._confluence_client_for_url(url).resolve_tiny_url(tiny_id)
-            except Exception as exc:
-                logger.debug(
-                    "confluence_tiny_url_resolution_failed",
-                    page_url=url,
-                    tiny_id=tiny_id,
-                    error=str(exc),
-                )
-                resolved_from_tiny = None
-            self._resolved_confluence_page_ids[normalized_url] = resolved_from_tiny
-            return resolved_from_tiny
-
-        display_ref = self._extract_confluence_display_ref(url)
-        if not display_ref:
-            self._resolved_confluence_page_ids[normalized_url] = None
-            return None
-
-        space_key, title = display_ref
-        title_candidates = [title]
-        if "_" in title:
-            underscored_normalized = re.sub(r"\s+", " ", title.replace("_", " ")).strip()
-            if underscored_normalized and underscored_normalized not in title_candidates:
-                title_candidates.append(underscored_normalized)
-
-        resolved_page_id: str | None = None
-        for candidate_title in title_candidates:
-            cql = f'space="{self._escape_cql(space_key)}" and title="{self._escape_cql(candidate_title)}" and type=page'
-            # Fail fast on CQL lookup to avoid large retry storms during registry parsing.
-            try:
-                results = await self._confluence_client_for_url(url).search_cql(cql, limit=1)
-            except DataSourceError as exc:
-                logger.debug(
-                    "confluence_display_page_id_resolution_failed",
-                    page_url=url,
-                    space_key=space_key,
-                    title=candidate_title,
-                    error=str(exc),
-                )
-                continue
-            if not results:
-                continue
-            first = results[0]
-            if not isinstance(first, dict):
-                continue
-            candidate_id = str(first.get("id") or "").strip()
-            if candidate_id:
-                resolved_page_id = candidate_id
-                break
-
-        self._resolved_confluence_page_ids[normalized_url] = resolved_page_id
-        return resolved_page_id
-
-    async def _resolve_missing_confluence_page_ids(self, links: list[DocumentLink]) -> None:
-        """Backfill missing page_id for Confluence document links when resolvable."""
-        if not links:
-            return
-        # Keep prefetch mode fully local/offline; do not introduce network lookups.
-        if self.prefetch_dir is not None:
-            return
-        for link in links:
-            if link.source != LinkSource.CONFLUENCE:
-                continue
-            if str(link.page_id or "").strip():
-                continue
-            resolved_page_id = await self._resolve_page_id_from_confluence_url(link.url)
-            if resolved_page_id:
-                link.page_id = resolved_page_id
-
-    def _map_table_headers(self, rows: list) -> tuple[dict[int, str], int | None]:
-        header_row_index: int | None = None
-        header_map: dict[int, str] = {}
-
-        for index, row in enumerate(rows):
-            header_cells = row.find_all("th")
-            if not header_cells:
-                continue
-
-            header_row_index = index
-            for col_index, cell in enumerate(header_cells):
-                header_key = self._classify_header(cell.get_text(strip=True))
-                if header_key:
-                    header_map[col_index] = header_key
-            break
-
-        if header_row_index is None and rows:
-            first_cells = rows[0].find_all("td")
-            header_map_candidate: dict[int, str] = {}
-            for col_index, cell in enumerate(first_cells):
-                header_key = self._classify_header(cell.get_text(strip=True))
-                if header_key:
-                    header_map_candidate[col_index] = header_key
-            if header_map_candidate:
-                header_map = header_map_candidate
-                header_row_index = 0
-
-        return header_map, header_row_index
-
-    def _classify_header(self, text: str) -> str | None:
-        normalized = self._normalize_text(text)
-        if not normalized:
-            return None
-
-        # VN/EN column mapping for role/doc_type (tolerant matching).
-        if any(
-            key in normalized
-            for key in (
-                "role",
-                "vai tro",
-                "vai trò",
-                "phu trach",
-                "phụ trách",
-                "chuc nang",
-                "chức năng",
-                "owner",
-            )
-        ):
-            return "role"
-
-        # EN doc type must be detected before VN doc type because headers like
-        # "Doc Type EN" contain the substring "doc type".
-        if any(
-            key in normalized
-            for key in (
-                "doc type en",
-                "document type en",
-                "english doc type",
-                "english document type",
-                "tai lieu en",
-                "tài liệu en",
-                "loai tai lieu en",
-                "loại tài liệu en",
-                "english",
-            )
-        ):
-            return "doc_type_en"
-
-        if any(
-            key in normalized
-            for key in (
-                "doc type",
-                "document type",
-                "loai tai lieu",
-                "loại tài liệu",
-                "tai lieu",
-                "tài liệu",
-                "mo ta",
-                "mô tả",
-                "noi dung",
-                "nội dung",
-                "description",
-                "muc",
-                "hạng mục",
-            )
-        ):
-            return "doc_type_vn"
-
-        if any(
-            key in normalized
-            for key in (
-                "link tai lieu",
-                "link tài liệu",
-                "tai lieu link",
-                "tài liệu link",
-                "link",
-                "url",
-                "href",
-            )
-        ):
-            return "link"
-
-        return None
-
-    def _extract_role(self, cells: list, header_map: dict[int, str]) -> DocumentRole:
-        role_text = self._extract_cell_text(cells, header_map, "role")
-        if not role_text:
-            return DocumentRole.UNKNOWN
-
-        normalized = self._normalize_text(role_text)
-        compact = normalized.replace(" ", "")
-
-        # Try multiple tokens because registry cells often contain combined roles like "PO/BA".
-        tokens = {normalized, compact}
-        for raw in re.split(r"[,/;|\\-]+", role_text):
-            norm = self._normalize_text(raw)
-            if norm:
-                tokens.add(norm)
-                tokens.add(norm.replace(" ", ""))
-
-        role_map = {
-            "po": DocumentRole.PO,
-            "productowner": DocumentRole.PO,
-            "product owner": DocumentRole.PO,
-            "ba": DocumentRole.BA,
-            "businessanalyst": DocumentRole.BA,
-            "business analyst": DocumentRole.BA,
-            "sa": DocumentRole.SA,
-            "solutionarchitect": DocumentRole.SA,
-            "solution architect": DocumentRole.SA,
-            "dev": DocumentRole.DEV,
-            "developer": DocumentRole.DEV,
-            "development": DocumentRole.DEV,
-            "test": DocumentRole.TEST,
-            "tester": DocumentRole.TEST,
-            "qa": DocumentRole.TEST,
-            "qc": DocumentRole.TEST,
-        }
-
-        for candidate in tokens:
-            if candidate in role_map:
-                return role_map[candidate]
-
-        return DocumentRole.UNKNOWN
-
-    def _extract_doc_type(
-        self,
-        cells: list,
-        header_map: dict[int, str],
-        header_key: str,
-    ) -> tuple[str | None, int | None]:
-        doc_text = self._extract_cell_text(cells, header_map, header_key)
-        if not doc_text:
-            return None, None
-
-        doc_number, doc_label = self._split_doc_number(doc_text)
-        return doc_label, doc_number
-
-    def _extract_cell_text(self, cells: list, header_map: dict[int, str], key: str) -> str | None:
-        for index, header_key in header_map.items():
-            if header_key != key:
-                continue
-            if index >= len(cells):
-                return None
-            cell = cells[index]
-            if cell is None:
-                return None
-            return cell.get_text(strip=True)
-        return None
-
-    def _split_doc_number(self, text: str) -> tuple[int | None, str]:
-        match = re.match(r"^\s*(\d+)\s*[\.\)]\s*(.+)$", text)
-        if match:
-            return int(match.group(1)), match.group(2).strip()
-        return None, text.strip()
-
-    def _normalize_text(self, text: str) -> str:
-        cleaned = re.sub(r"[^\w\s]", " ", text.strip().lower())
-        return " ".join(cleaned.split())