@ngocsangairvds/vsaf 3.2.14 → 3.2.16

package/tools/vds-scripts/audit_orchestrator/src/vds_audit_orchestrator/misc_cmds.py

@@ -1,4689 +0,0 @@
-"""Miscellaneous commands for vds-audit CLI (Phase 91 decomposition)."""
-
-# pyright: reportUnusedVariable=false
-
-from __future__ import annotations
-
-import asyncio
-import dataclasses
-import json
-import os
-from dataclasses import dataclass, field
-from datetime import UTC, datetime
-from fnmatch import fnmatch
-from importlib import metadata
-from pathlib import Path
-from time import perf_counter
-from typing import Any, cast
-from uuid import uuid4
-
-import structlog
-import typer
-from rich.progress import Progress, SpinnerColumn, TextColumn
-from rich.table import Table
-from rich.tree import Tree
-from vds_platform_core.credentials import resolve_secret
-
-from vds_audit_orchestrator.checklist_query import (
-    ChecklistQueryFilters,
-    query_checklist_template,
-)
-from vds_audit_orchestrator.checks.registry import CheckRegistry
-from vds_audit_orchestrator.cli_common import _STATE_DSN_ENV_VAR, APP_NAME, _cli_state, _get_cli_ctx, app, console
-from vds_audit_orchestrator.cli_impl import (
-    _DEFAULT_EMBEDDING_BASE_URL,
-    _active_runtime_profile_name,
-    _DebugArtifactsCollector,
-    _emit_json,
-    _emit_sync_decision,
-    _load_manifest_payload_from_state,
-    _normalize_run_parameters,
-    _normalize_storage_key,
-    _parse_confluence_ref,
-    _parse_registry_metadata,
-    _persist_typed_run_terminal,
-    _project_storage_key_from_payload,
-    _require_consumer_state_dsn,
-    _require_producer_state_dsn,
-    _resolve_confluence_page_id,
-    _resolve_parse_manifest_payload,
-    _resolve_state_dsn,
-    _validate_required_credentials,
-    _write_debug_bundle,
-)
-from vds_audit_orchestrator.clients.confluence_cli_client import ConfluenceCliClient
-from vds_audit_orchestrator.collectors.checklist_parser import ChecklistParser
-from vds_audit_orchestrator.collectors.orchestrator import EvidenceOrchestrator
-from vds_audit_orchestrator.config import FeatureFlag, get_config
-from vds_audit_orchestrator.engine.auditor import AuditEngine
-from vds_audit_orchestrator.engine.checkpoint import (
-    AuditCheckpoint,
-    load_checkpoint,
-    save_checkpoint,
-)
-from vds_audit_orchestrator.engine.gap_analyzer import GapAnalyzer
-from vds_audit_orchestrator.engine.loader import (
-    ExcelLoader,
-    export_template_from_google_source,
-    load_template_from_google_sheet,
-    resolve_mapping_path,
-)
-from vds_audit_orchestrator.engine.mapping import load_mapping_file
-from vds_audit_orchestrator.engine.scorer import Scorer
-from vds_audit_orchestrator.engine.section_packs import get_default_registry
-from vds_audit_orchestrator.engine.template_analyzer import TemplateAnalyzer
-from vds_audit_orchestrator.engine.validator import TemplateValidator
-from vds_audit_orchestrator.engine.weight_policy import compute_adaptive_weights
-from vds_audit_orchestrator.errors import TemplateValidationError
-from vds_audit_orchestrator.evidence.bootstrap import resolve_checklist_profile
-from vds_audit_orchestrator.llm.cost_tracker import global_tracker
-from vds_audit_orchestrator.llm.provider import LLMProvider
-from vds_audit_orchestrator.models.checklist import AuditChecklist
-from vds_audit_orchestrator.models.enums import MaturityLevel
-from vds_audit_orchestrator.models.evidence import Evidence, EvidenceRequirement
-from vds_audit_orchestrator.models.gaps import GapAnalysisResult as RepoGapAnalysisResult
-from vds_audit_orchestrator.models.reporting import AuditRunReport
-from vds_audit_orchestrator.profiles.detection import resolve_profile, resolve_profile_async
-from vds_audit_orchestrator.profiles.models import ProjectProfile, default_profile
-from vds_audit_orchestrator.reports.reporting import build_metadata, generate_reports
-from vds_audit_orchestrator.seed import select_project
-from vds_audit_orchestrator.spec_sync_validator import validate_spec_sync
-from vds_audit_orchestrator.utils.debug_bundle import export_debug_bundle as export_debug_bundle_func
-
-logger = structlog.get_logger(__name__)
-
-
-def _log_hardened_path_error(
-    event: str,
-    exc: Exception,
-    *,
-    context: str,
-    recovery_action: str,
-    level: str = "warning",
-) -> None:
-    log_method = logger.exception if level == "exception" else logger.warning
-    log_method(
-        event,
-        error=str(exc),
-        error_type=type(exc).__name__,
-        source_module=__name__,
-        context=context,
-        recovery_action=recovery_action,
-    )
-
-
-# ---------------------------------------------------------------------------
-# embedding-check
-# ---------------------------------------------------------------------------
-
-
-@app.command(name="embedding-check")
-def embedding_check(
-    state_dsn: str | None = typer.Option(
-        None,
-        "--state-dsn",
-        envvar=_STATE_DSN_ENV_VAR,
-        help=f"State backend DSN for pgvector readiness check (fallback: {_STATE_DSN_ENV_VAR}).",
-    ),
-    embedding_base_url: str | None = typer.Option(
-        None,
-        "--embedding-base-url",
-        envvar="VDS_AUDIT_EMBEDDING__BASE_URL",
-        help="Embedding API base URL (default: config.embedding.base_url, fallback: config.llm.base_url, then http://127.0.0.1:11434).",
-    ),
-    model: str = typer.Option(
-        "bge-m3",
-        "--model",
-        help="Primary embedding model to verify (default: bge-m3).",
-    ),
-    allow_fallback: bool = typer.Option(
-        False,
-        "--allow-fallback/--no-allow-fallback",
-        help="When primary model is bge-m3 and unavailable, allow fallback to nomic-embed-text.",
-    ),
-    timeout_seconds: float = typer.Option(
-        15.0,
-        "--timeout-seconds",
-        min=1.0,
-        help="Timeout for Ollama probes in seconds.",
-    ),
-) -> None:
-    """Validate embedding + pgvector readiness (Python package `pgvector` is separate from Postgres extension `vector`)."""
-    # Resolve probe helpers via module lookup so test monkeypatches applied to
-    # `vds_audit_orchestrator.cli` are honored by this command path.
-    from vds_audit_orchestrator import cli as cli_module
-
-    resolved_state_dsn = _resolve_state_dsn(state_dsn, required=True)
-    assert resolved_state_dsn is not None
-    config = get_config()
-    resolved_embedding_base_url = (
-        embedding_base_url or config.embedding.base_url or config.llm.base_url or _DEFAULT_EMBEDDING_BASE_URL
-    )
-
-    errors: list[str] = []
-    checks = {
-        "ollama_reachable": False,
-        "model_available": False,
-        "embedding_dimensions_ok": False,
-        "pgvector_ready": False,
-    }
-    resolved_model: str | None = None
-    local_models: list[str] = []
-    probe: dict[str, Any] | None = None
-    pgvector: dict[str, Any] | None = None
-    fallback_used = False
-
-    try:
-        local_models = cli_module._fetch_ollama_local_models(
-            base_url=resolved_embedding_base_url,
-            timeout_seconds=timeout_seconds,
-        )
-        checks["ollama_reachable"] = True
-    except Exception as exc:
-        errors.append(f"Embedding endpoint reachability check failed at {resolved_embedding_base_url}: {exc}")
-
-    if checks["ollama_reachable"]:
-        try:
-            selection = cli_module._select_embedding_model_for_readiness(
-                requested_model=model,
-                local_models=local_models,
-                allow_fallback=allow_fallback,
-            )
-            resolved_model = str(selection["resolved_model"])
-            fallback_used = bool(selection["fallback_used"])
-            checks["model_available"] = True
-            probe = cli_module._probe_embedding_dimensions(
-                base_url=resolved_embedding_base_url,
-                model=resolved_model,
-                timeout_seconds=timeout_seconds,
-                expected_dimensions=cast("int | None", selection.get("expected_dimensions")),
-                api_key=resolve_secret(config.embedding.api_key),
-            )
-            checks["embedding_dimensions_ok"] = True
-        except Exception as exc:
-            errors.append(f"Embedding model check failed: {exc}")
-
-    try:
-        pgvector = cli_module._collect_pgvector_readiness(state_dsn=resolved_state_dsn)
-        checks["pgvector_ready"] = bool(pgvector.get("ready"))
-        if not checks["pgvector_ready"]:
-            errors.extend([str(item) for item in cast("list[Any]", pgvector.get("errors") or []) if str(item).strip()])
-    except Exception as exc:
-        errors.append(f"pgvector readiness check failed: {exc}")
-
-    status = "ok" if all(checks.values()) and not errors else "error"
-    payload = {
-        "status": status,
-        "operation": "embedding_check",
-        "requested_model": model,
-        "resolved_model": resolved_model,
-        "fallback_used": fallback_used,
-        "embedding_base_url": resolved_embedding_base_url,
-        "checks": checks,
-        "local_models": local_models,
-        "probe": probe,
-        "pgvector": pgvector,
-        "errors": errors,
-    }
-
-    if _cli_state.get("json_only"):
-        _emit_json(payload)
-    else:
-        table = Table(title="Embedding Readiness")
-        table.add_column("Check")
-        table.add_column("Status")
-        table.add_row("Ollama reachable", "yes" if checks["ollama_reachable"] else "no")
-        table.add_row("Model available", "yes" if checks["model_available"] else "no")
-        table.add_row("Embedding dimensions", "yes" if checks["embedding_dimensions_ok"] else "no")
-        table.add_row("pgvector readiness", "yes" if checks["pgvector_ready"] else "no")
-        table.add_row("Requested model", model)
-        table.add_row("Resolved model", resolved_model or "-")
-        table.add_row("Fallback used", "yes" if fallback_used else "no")
-        table.add_row("Embedding base URL", resolved_embedding_base_url)
-        console.print(table)
-        if errors:
-            for err in errors:
-                console.print(f"[red]- {err}[/red]")
-
-    if status != "ok":
-        raise typer.Exit(1)
-
-
-# ---------------------------------------------------------------------------
-# task-graph
-# ---------------------------------------------------------------------------
-
-
-@app.command(name="task-graph")
-def task_graph(
-    thread_id: str = typer.Option(..., help="Thread ID to identify the workflow"),
-    output: Path = typer.Option(
-        Path("task_graph.mmd"),
-        "--output",
-        "-o",
-        help="Output path for the Mermaid file",
-    ),
-    checkpointer: str = typer.Option(
-        "postgres",
-        help="Checkpointer type: memory or postgres",
-    ),
-    postgres_dsn: str | None = typer.Option(
-        None,
-        help="Postgres DSN for checkpointing (required if checkpointer=postgres)",
-        envvar="VDS_AUDIT_LANGGRAPH__POSTGRES_DSN",
-    ),
-) -> None:
-    """Generate a Mermaid diagram of the task graph for Phase 11 visualization.
-
-    Fetches the current workflow state from the checkpoint and generates a
-    Mermaid diagram showing all tasks with their status, dependencies, and
-    assignees.
-
-    Task nodes are colored by status:
-    - Green: completed
-    - Yellow: running
-    - Red: failed
-    - Gray: pending
-    - Orange: blocked
-    - Light gray: skipped
-
-    Examples:
-        # Generate task graph for a specific workflow
-        vds-audit task-graph --thread-id audit-123
-
-        # Specify custom output path
-        vds-audit task-graph --thread-id audit-123 --output my_tasks.mmd
-
-        # Use postgres checkpointer
-        vds-audit task-graph --thread-id audit-123 --checkpointer postgres
-    """
-    from vds_audit_orchestrator.agents.langgraph_workflow import build_audit_graph
-    from vds_audit_orchestrator.models.task import AuditTask
-
-    postgres_dsn = postgres_dsn or get_config().langgraph.postgres_dsn
-
-    async def _generate_task_graph() -> str:
-        """Fetch state and generate Mermaid diagram."""
-        graph = await build_audit_graph(checkpointer=checkpointer, postgres_dsn=postgres_dsn)
-        config = {"configurable": {"thread_id": thread_id}}
-        state = await graph.aget_state(config)  # type: ignore[arg-type]
-
-        if not state or not state.values:
-            raise ValueError(f"No workflow state found for thread_id: {thread_id}")
-
-        tasks_dict: dict[str, dict[str, Any]] = state.values.get("tasks", {})
-        if not tasks_dict:
-            raise ValueError(f"No tasks found in workflow state for thread_id: {thread_id}")
-
-        # Build Mermaid diagram
-        lines: list[str] = ["graph TD"]
-
-        # Track dependencies for edges
-        edges: list[tuple[str, str]] = []
-
-        for task_id, task_data in tasks_dict.items():
-            # Parse task data - it may be a dict or AuditTask
-            task = AuditTask.model_validate(task_data) if isinstance(task_data, dict) else task_data
-
-            # Determine status class
-            status_str = task.status if isinstance(task.status, str) else task.status.value
-            status_class = status_str.lower()
-
-            # Escape task type and assignee for Mermaid label
-            task_type = task.type.replace('"', '\\"')
-            assignee = task.assignee.replace('"', '\\"')
-
-            # Create node with label showing type and assignee
-            node_label = f"{task_type}<br/>{assignee}"
-            lines.append(f'    {task_id}["{node_label}"]:::{status_class}')
-
-            # Collect dependency edges
-            for dep_id in task.dependencies:
-                edges.append((dep_id, task_id))
-
-        # Add edges
-        for source, target in edges:
-            lines.append(f"    {source} --> {target}")
-
-        # Add class definitions for status coloring
-        lines.append("    classDef completed fill:#90EE90")
-        lines.append("    classDef running fill:#FFD700")
-        lines.append("    classDef failed fill:#FF6B6B")
-        lines.append("    classDef pending fill:#D3D3D3")
-        lines.append("    classDef blocked fill:#FFA500")
-        lines.append("    classDef skipped fill:#E8E8E8")
-
-        return "\n".join(lines)
-
-    try:
-        mermaid_content = asyncio.run(_generate_task_graph())
-
-        # Write to output file
-        output.parent.mkdir(parents=True, exist_ok=True)
-        output.write_text(mermaid_content, encoding="utf-8")
-
-        if _cli_state.get("json_only"):
-            _emit_json(
-                {
-                    "task_graph": "generated",
-                    "path": str(output.resolve()),
-                    "thread_id": thread_id,
-                }
-            )
-            return
-
-        console.print(f"[green]Task graph written to:[/green] {output.resolve()}")
-
-    except ValueError as e:
-        message = str(e)
-        if _cli_state.get("json_only"):
-            _emit_json({"error": message})
-        else:
-            console.print(f"[red]{message}[/red]")
-        raise typer.Exit(1) from e
-    except Exception as e:
-        message = f"Task graph generation failed: {e}"
-        if _cli_state.get("json_only"):
-            _emit_json({"error": message})
-        else:
-            console.print(f"[red]{message}[/red]")
-        raise typer.Exit(1) from e
-
-
-# ---------------------------------------------------------------------------
-# list-pending
-# ---------------------------------------------------------------------------
-
-
-@app.command(name="list-pending")
-def list_pending_approvals(
-    checkpointer: str = typer.Option(
-        "postgres",
-        help="Checkpointer type: memory or postgres",
-    ),
-    postgres_dsn: str | None = typer.Option(
-        None,
-        help="Postgres DSN for checkpointing (required if checkpointer=postgres)",
-        envvar="VDS_AUDIT_LANGGRAPH__POSTGRES_DSN",
-    ),
-) -> None:
-    """List all pending audit approvals awaiting human review.
-
-    Queries the checkpoint store for workflows paused at the human_review node.
-    """
-    from vds_audit_orchestrator.agents.approval import list_pending_approvals_cli
-
-    postgres_dsn = postgres_dsn or get_config().langgraph.postgres_dsn
-
-    pending = asyncio.run(
-        list_pending_approvals_cli(
-            checkpointer=checkpointer,
-            postgres_dsn=postgres_dsn,
-        )
-    )
-
-    if _cli_state.get("json_only"):
-        _emit_json({"pending_approvals": pending, "count": len(pending)})
-        return
-
-    if not pending:
-        console.print("[green]No pending approvals found.[/green]")
-        return
-
-    console.print(f"[bold]Pending Approvals ({len(pending)}):[/bold]\n")
-
-    table = Table()
-    table.add_column("Thread ID")
-    table.add_column("Repository")
-    table.add_column("Timestamp")
-    table.add_column("Findings")
-    table.add_column("Errors")
-
-    for item in pending:
-        table.add_row(
-            item["thread_id"],
-            item["repository"],
-            item["timestamp"],
-            str(item["agent_results_count"]),
-            str(item["errors_count"]),
-        )
-
-    console.print(table)
-    console.print("\n[dim]Use 'vds-audit approve <thread-id>' to approve or reject.[/dim]")
-
-
-# ---------------------------------------------------------------------------
-# approve
-# ---------------------------------------------------------------------------
-
-
-@app.command(name="approve")
-def approve_audit(
-    thread_id: str = typer.Argument(..., help="Thread ID of the audit to approve"),
-    approved: bool = typer.Option(True, "--approve/--reject", help="Approval decision"),
-    feedback: str | None = typer.Option(None, "--feedback", "-f", help="Reviewer feedback"),
-    reviewer: str | None = typer.Option(None, "--reviewer", "-r", help="Reviewer identifier"),
-    checkpointer: str = typer.Option(
-        "postgres",
-        help="Checkpointer type: memory or postgres",
-    ),
-    postgres_dsn: str | None = typer.Option(
-        None,
-        help="Postgres DSN for checkpointing (required if checkpointer=postgres)",
-        envvar="VDS_AUDIT_LANGGRAPH__POSTGRES_DSN",
-    ),
-) -> None:
-    """Approve or reject a pending audit review.
-
-    Resumes the LangGraph workflow with the human decision and logs
-    the approval to the audit trail.
-
-    Example:
-        vds-audit approve audit-123 --approve --feedback "Looks good, proceed."
-        vds-audit approve audit-123 --reject --reviewer "john.doe"
-    """
-    from vds_audit_orchestrator.agents.approval import process_approval_cli
-
-    postgres_dsn = postgres_dsn or get_config().langgraph.postgres_dsn
-
-    result = asyncio.run(
-        process_approval_cli(
-            thread_id=thread_id,
-            approved=approved,
-            feedback=feedback,
-            reviewer=reviewer,
-            checkpointer=checkpointer,
-            postgres_dsn=postgres_dsn,
-        )
-    )
-
-    if _cli_state.get("json_only"):
-        _emit_json({"approval": "processed" if approved else "rejected", "result": result})
-        return
-
-    action = "approved" if approved else "rejected"
-    console.print(f"[green]Audit {action} successfully.[/green]")
-    console.print(f"Thread ID: {thread_id}")
-    console.print(f"Final step: {result.get('step')}")
-
-    synthesis = result.get("synthesis")
-    if synthesis:
-        console.print(f"Total findings: {synthesis.get('total_findings', 0)}")
-
-
-# ---------------------------------------------------------------------------
-# list-materials
-# ---------------------------------------------------------------------------
-
-
-@app.command(name="list-materials")
-def list_materials(
-    evidence_dir: Path | None = typer.Option(
-        None,
-        "--evidence-dir",
-        help="Optional evidence directory used for filesystem tree rendering and project scope filtering.",
-    ),
-    tree: bool = typer.Option(
-        False,
-        "--tree",
-        help="Render a filesystem tree under --evidence-dir.",
-    ),
-    tree_depth: int = typer.Option(
-        3,
-        "--tree-depth",
-        min=1,
-        help="Maximum tree depth when --tree is enabled.",
-    ),
-    timestamps: bool = typer.Option(
-        False,
-        "--timestamps",
-        help="Include modified timestamps in tree output.",
-    ),
-    state_dsn: str | None = typer.Option(
-        None,
-        "--state-dsn",
-        envvar=_STATE_DSN_ENV_VAR,
-        help=f"Load materials manifest from centralized state DSN (fallback: {_STATE_DSN_ENV_VAR}).",
-    ),
-):
-    """List extracted materials and their status."""
-    try:
-        if tree and evidence_dir is None:
-            raise RuntimeError("--tree requires --evidence-dir.")
-
-        resolved_state_dsn = _require_consumer_state_dsn(state_dsn, command="list-materials")
-        data = _load_manifest_payload_from_state(resolved_state_dsn)
-        if not isinstance(data, dict):
-            raise RuntimeError("Centralized state payload is not a JSON object.")
-        projects_raw = data.get("projects")
-        if not isinstance(projects_raw, list):
-            raise RuntimeError("Centralized state payload is missing required 'projects' list.")
-        all_projects = [project for project in projects_raw if isinstance(project, dict)]
-
-        scope_root: Path | None = None
-        env_evidence_dir = str(os.getenv("VDS_AUDIT_EVIDENCE_DIR") or "").strip()
-        if evidence_dir is not None:
-            scope_root = evidence_dir.expanduser().resolve(strict=False)
-        elif env_evidence_dir:
-            scope_root = Path(env_evidence_dir).expanduser().resolve(strict=False)
-        scope_enabled = scope_root is not None
-        docs_scope_keys: set[str] = set()
-        if scope_enabled and scope_root is not None:
-            docs_root = scope_root / "docs"
-            if docs_root.exists() and docs_root.is_dir():
-                for child in docs_root.iterdir():
-                    if child.is_dir():
-                        normalized_child = _normalize_storage_key(child.name)
-                        if normalized_child:
-                            docs_scope_keys.add(normalized_child)
-
-        def _path_in_scope(path_text: str) -> bool:
-            if not scope_enabled or scope_root is None:
-                return True
-            normalized_path_text = path_text.strip()
-            if not normalized_path_text:
-                return False
-            candidate = Path(normalized_path_text).expanduser().resolve(strict=False)
-            try:
-                candidate.relative_to(scope_root)
-            except ValueError:
-                return False
-            return candidate.exists()
-
-        def _project_matches_evidence_scope(project: dict[str, Any]) -> bool:
-            if not scope_enabled or scope_root is None:
-                return True
-            for path_field in (
-                "materialized_content_root",
-                "corpus_path",
-                "tables_path",
-                "mentions_path",
-                "link_graph_path",
-                "manifest_path",
-            ):
-                raw_path = str(project.get(path_field) or "").strip()
-                if raw_path and _path_in_scope(raw_path):
-                    return True
-
-            for selector in (
-                str(project.get("project_storage_key") or "").strip(),
-                str(project.get("page_id") or "").strip(),
-                str(project.get("project_name") or "").strip(),
-                str(project.get("project_name_en") or "").strip(),
-            ):
-                normalized_selector = _normalize_storage_key(selector) if selector else ""
-                if normalized_selector and normalized_selector in docs_scope_keys:
-                    return True
-
-            return False
-
-        scoped_projects = [project for project in all_projects if _project_matches_evidence_scope(project)]
-        seen_project_keys: set[tuple[str, str, str]] = set()
-        projects: list[dict[str, Any]] = []
-        for project in scoped_projects:
-            dedupe_key = (
-                str(project.get("project_storage_key") or ""),
-                str(project.get("page_id") or ""),
-                str(project.get("project_name") or ""),
-            )
-            if dedupe_key in seen_project_keys:
-                continue
-            seen_project_keys.add(dedupe_key)
-            projects.append(project)
-
-        filtered_data = dict(data)
-        filtered_data["projects"] = projects
-
-        if _cli_state.get("json_only"):
-            _emit_json(filtered_data)
-            return
-
-        table = Table(title="Extracted Materials")
-        table.add_column("Project")
-        table.add_column("Page ID")
-        table.add_column("Docs")
-        table.add_column("Repos")
-        table.add_column("Quality")
-        table.add_column("Snapshot")
-
-        for proj in projects:
-            docs_count = len(proj.get("documents", []))
-            repos_count = len(proj.get("bitbucket_links", []))
-            linked_page_resolution = proj.get("linked_page_resolution") or {}
-            attachment_total = int(linked_page_resolution.get("attachment_total") or 0)
-            attachment_found = int(linked_page_resolution.get("attachments_found") or 0)
-            attachment_partial = int(linked_page_resolution.get("attachments_partial") or 0)
-            attachment_error = int(linked_page_resolution.get("attachments_error") or 0)
-            snapshot = proj.get("retrieval_snapshot") or {}
-            snapshot_key = str(snapshot.get("snapshot_key") or "")
-            docs_chunks = snapshot.get("docs_chunk_count")
-            code_chunks = snapshot.get("code_chunk_count")
-            quality_bits = []
-            if attachment_total:
-                quality_bits.append(f"att {attachment_found}/{attachment_total}")
-            if attachment_partial:
-                quality_bits.append(f"partial {attachment_partial}")
-            if attachment_error:
-                quality_bits.append(f"error {attachment_error}")
-            if docs_chunks is not None or code_chunks is not None:
-                quality_bits.append(f"chunks d={docs_chunks or 0} c={code_chunks or 0}")
-            quality_text = "; ".join(quality_bits) if quality_bits else "n/a"
-            snapshot_text = snapshot_key or str(proj.get("corpus_path") or "")
-            table.add_row(
-                proj.get("project_name", "Unknown"),
-                proj.get("page_id", ""),
-                str(docs_count),
-                str(repos_count),
-                quality_text,
-                snapshot_text,
-            )
-
-        console.print(table)
-        if tree and scope_root is not None:
-            rendered_root = Tree(str(scope_root))
-
-            def _render_tree(node: Tree, path: Path, *, depth: int) -> None:
-                if depth >= tree_depth:
-                    return
-                try:
-                    children = sorted(path.iterdir(), key=lambda child: (not child.is_dir(), child.name.casefold()))
-                except OSError as exc:
-                    _log_hardened_path_error(
-                        "list_materials_tree_iterdir_failed",
-                        exc,
-                        context=f"path={path}",
-                        recovery_action="skip_tree_branch",
-                    )
-                    return
-                for child in children:
-                    label = child.name
-                    if timestamps:
-                        try:
-                            modified = datetime.fromtimestamp(child.stat().st_mtime, tz=UTC).strftime(
-                                "%Y-%m-%d %H:%M:%S %Z"
-                            )
-                            label = f"{label} ({modified})"
-                        except OSError as exc:
-                            _log_hardened_path_error(
-                                "list_materials_tree_stat_failed",
-                                exc,
-                                context=f"path={child}",
-                                recovery_action="omit_timestamp_and_continue",
-                            )
-                            pass
-                    child_node = node.add(label)
-                    if child.is_dir():
-                        _render_tree(child_node, child, depth=depth + 1)
-
-            _render_tree(rendered_root, scope_root, depth=0)
-            console.print(rendered_root)
-
-    except Exception as e:
-        message = f"Failed to read materials: {e}"
-        if _cli_state.get("json_only"):
-            _emit_json({"error": message})
-        else:
-            console.print(f"[red]{message}[/red]")
-        raise typer.Exit(1) from e
-
-
-# ---------------------------------------------------------------------------
-# upload-results
-# ---------------------------------------------------------------------------
-
-
-@app.command(name="upload-results")
-def upload_results(
-    report_dir: Path = typer.Option(
-        ...,
-        "--report-dir",
-        help="Directory containing audit reports",
-        exists=True,
-    ),
-    parent_page: str = typer.Option(
-        ...,
-        "--parent-page",
-        help="Confluence parent page URL or ID",
-    ),
-    page_title: str = typer.Option(
-        ...,
-        "--page-title",
-        help="Title for the audit result page",
-    ),
-    timeout: int = typer.Option(
-        120,
-        "--timeout",
-        help="Timeout (seconds) for Confluence vds-cli calls",
-    ),
-    retries: int = typer.Option(
-        2,
-        "--retries",
-        help="Number of retries for transient Confluence errors",
-    ),
-    backoff: float = typer.Option(
-        1.0,
-        "--backoff",
-        help="Base backoff (seconds) for retries; exponential with attempt number",
-    ),
-    include_attachments: bool = typer.Option(
-        False,
-        "--include-attachments/--no-include-attachments",
-        help="Upload report attachments (xlsx, json, sarif, audit-checklist.*). Default is page-only mode.",
-    ),
-    thread_id: str | None = typer.Option(
-        None,
-        "--thread-id",
-        help="Workflow thread ID for provenance tracking",
-    ),
-    publish_mode: str = typer.Option(
-        "update",
-        "--publish-mode",
-        help="Publish mode: 'update' (overwrite if exists) or 'create-only' (fail if exists)",
-    ),
-    update_mode: str = typer.Option(
-        "full",
-        "--update-mode",
-        help="Update mode: 'full' or 'incremental' (delta/meta scoped updates with fallback)",
-    ),
-    include_attachments_index: bool = typer.Option(
-        False,
-        "--attachments-index",
-        help="Add attachments index section with links to uploaded files",
-    ),
-    priority_actions_limit: int = typer.Option(
-        10,
-        "--priority-actions-limit",
-        help="Max number of priority actions to display",
-    ),
-    checklist_collapsed: bool = typer.Option(
-        False,
-        help="Start with full checklist details collapsed",
-    ),
-    state_dsn: str | None = typer.Option(
-        None,
-        "--state-dsn",
-        envvar=_STATE_DSN_ENV_VAR,
-        help=f"Persist upload state metadata to backend DSN (required; fallback: {_STATE_DSN_ENV_VAR}).",
-    ),
-    debug_artifacts: bool = typer.Option(
-        False,
-        "--debug-artifacts/--no-debug-artifacts",
-        help="Write optional debug artifacts: cache_trace.jsonl, sync_plan.json, state_diff.json.",
-    ),
-    debug_artifacts_dir: Path | None = typer.Option(
-        None,
-        "--debug-artifacts-dir",
-        help="Directory for debug artifacts (defaults to --report-dir).",
-    ),
-    project_storage_key: str | None = typer.Option(
-        None,
-        "--project-storage-key",
-        help="Explicit project storage key for deterministic hierarchy placement. Overrides page-title inference.",
-    ),
-    repo_storage_key: str | None = typer.Option(
-        None,
-        "--repo-storage-key",
-        help="Explicit repo storage key for deterministic hierarchy placement. Overrides page-title inference.",
-    ),
-    project_name_hint: str | None = typer.Option(
-        None,
-        "--project-name-hint",
-        help="Phase 154 (AC-154.7.5): Explicit project name for stable hierarchy node titles.",
-    ),
-) -> None:
-    """Upload audit results to Confluence.
-
-    TSK-170B/343/344: Supports publish/update modes, attachments index, and upload counters.
-    TSK-940.69: Explicit --project-storage-key and --repo-storage-key flags for shared hierarchy.
-    """
-    from vds_audit_orchestrator.publishers.confluence_publisher import (
-        ConfluencePublisher,
-        PublishMode,
-        UpdateMode,
-    )
-
-    # Parse publish mode
-    try:
-        mode = PublishMode(publish_mode.lower().replace("_", "-"))
-    except ValueError:
-        console.print(f"[red]Invalid publish mode: {publish_mode}. Use 'update' or 'create-only'.[/red]")
-        raise typer.Exit(1) from None
-    try:
-        resolved_update_mode = UpdateMode(update_mode.lower().replace("_", "-"))
-    except ValueError:
-        console.print(f"[red]Invalid update mode: {update_mode}. Use 'full' or 'incremental'.[/red]")
-        raise typer.Exit(1) from None
-    resolved_state_dsn = _require_producer_state_dsn(state_dsn, command="upload-results")
-
-    # TSK-940.69: Use explicit keys when provided, fall back to page-title inference.
-    inferred_project_storage_key = project_storage_key or _normalize_storage_key(page_title)
-    inferred_repo_storage_key = repo_storage_key or inferred_project_storage_key
-
-    # Phase 154 (AC-154.7.5): Resolve project_name_hint from CLI or storage key.
-    resolved_project_name_hint = project_name_hint or inferred_project_storage_key
-
-    async def _run_upload() -> dict[str, Any]:
-        client = ConfluenceCliClient(timeout=timeout, retries=retries)
-        publisher = ConfluencePublisher(client, retries=retries, backoff=backoff, state_dsn=resolved_state_dsn)
-        result = await publisher.upload_results(
-            report_dir=report_dir,
-            parent_page=parent_page,
-            page_title=page_title,
-            include_attachments=include_attachments,
-            thread_id=thread_id,
-            publish_mode=mode,
-            update_mode=resolved_update_mode,
-            include_attachments_index=include_attachments_index,
-            priority_actions_limit=priority_actions_limit,
-            checklist_collapsed=checklist_collapsed,
-            project_storage_key=inferred_project_storage_key,
-            repo_storage_key=inferred_repo_storage_key,
-            hierarchy_target="repo",
-            project_name_hint=resolved_project_name_hint,
-        )
-        readiness_extended = False
-        readiness_summary: dict[str, Any] | None = None
-        if (report_dir / "readiness-report.json").exists():
-            readiness_extended = await publisher.extend_run_page_readiness(
-                page_id=result.page_id,
-                title=page_title,
-                report_dir=report_dir,
-            )
-            try:
-                raw = json.loads((report_dir / "readiness-report.json").read_text())
-                readiness_summary = {
-                    "readiness_score_pct": raw.get("readiness_score_pct"),
-                    "classification": raw.get("classification"),
-                    "confidence": raw.get("confidence"),
-                }
-            except (OSError, TypeError, ValueError) as exc:
-                _log_hardened_path_error(
-                    "upload_results_readiness_summary_parse_failed",
-                    exc,
-                    context=f"report_dir={report_dir}",
-                    recovery_action="set_readiness_summary_to_none",
-                )
-                readiness_summary = None
-        return {
-            "page_id": result.page_id,
-            "reused_existing_page": bool(getattr(result, "reused_existing_page", False)),
-            "attachments": result.attachments,
-            "attachments_index": result.attachments_index,
-            "update_mode": result.update_mode,
-            "effective_update_mode": result.effective_update_mode,
-            "fallback_reason": result.fallback_reason,
-            "counters": result.counters,
-            "project_root_page_id": getattr(result, "project_root_page_id", None),
-            "audit_root_page_id": getattr(result, "audit_root_page_id", None),
-            "repo_root_page_id": getattr(result, "repo_root_page_id", None),
-            "repo_run_page_id": getattr(result, "repo_run_page_id", None),
-            "project_analysis_root_page_id": getattr(result, "project_analysis_root_page_id", None),
-            "project_aggregate_page_id": getattr(result, "project_aggregate_page_id", None),
-            "sections_rendered": getattr(result, "sections_rendered", []),
-            "readiness_extended": readiness_extended,
-            "readiness_summary": readiness_summary,
-        }
-
-    try:
-        debug_trace = (
-            _DebugArtifactsCollector((debug_artifacts_dir or report_dir).resolve()) if debug_artifacts else None
-        )
-        upload_start = perf_counter()
-        result = asyncio.run(_run_upload())
-        upload_duration_ms = int((perf_counter() - upload_start) * 1000)
-        counters = result.get("counters") or {}
-        project_storage_key = inferred_project_storage_key
-
-        if result.get("readiness_summary"):
-            logger.info(
-                "upload_results_readiness_detected",
-                readiness_score_pct=result["readiness_summary"].get("readiness_score_pct"),
-                classification=result["readiness_summary"].get("classification"),
-                confidence=result["readiness_summary"].get("confidence"),
-                page_id=result.get("page_id"),
-                readiness_extended=result.get("readiness_extended"),
-            )
-
-        if debug_trace is not None:
-            debug_trace.add_sync_plan(
-                project_storage_key=project_storage_key,
-                resource_type="confluence_page",
-                resource_id=str(result.get("page_id") or parent_page),
-                decision="publish",
-                reason=f"publish_mode_{mode.value}",
-            )
-            if include_attachments:
-                debug_trace.add_sync_plan(
-                    project_storage_key=project_storage_key,
-                    resource_type="confluence_attachment",
-                    resource_id=str(result.get("page_id") or parent_page),
-                    decision="sync",
-                    reason="attachments_enabled",
-                )
-            if include_attachments_index:
-                debug_trace.add_sync_plan(
-                    project_storage_key=project_storage_key,
-                    resource_type="confluence_page_section",
-                    resource_id=str(result.get("page_id") or parent_page),
-                    decision="update",
-                    reason="attachments_index_enabled",
-                )
-
-        _emit_sync_decision(
-            logger,
-            trace=debug_trace,
-            command="upload-results",
-            project_storage_key=project_storage_key,
-            resource_type="confluence_page",
-            resource_id=str(result.get("page_id") or parent_page),
-            decision="published",
-            reason=f"effective_update_mode_{result.get('effective_update_mode')}",
-            token_before=None,
-            token_after=None,
-            duration_ms=upload_duration_ms,
-            bytes_downloaded=None,
-            cache_mode=None,
-            sync_policy=mode.value,
-        )
-        if include_attachments:
-            attachments_updated = int(counters.get("attachments_updated", len(result.get("attachments", []))))
-            attachments_skipped = int(counters.get("attachments_skipped", 0))
-            attachment_decision = "attachments_updated" if attachments_updated > 0 else "attachments_skipped"
-            attachment_reason = (
-                f"updated_{attachments_updated}_skipped_{attachments_skipped}"
-                if attachments_skipped > 0
-                else f"updated_{attachments_updated}"
-            )
-            _emit_sync_decision(
-                logger,
-                trace=debug_trace,
-                command="upload-results",
-                project_storage_key=project_storage_key,
-                resource_type="confluence_attachment",
-                resource_id=str(result.get("page_id") or parent_page),
-                decision=attachment_decision,
-                reason=attachment_reason,
-                token_before=None,
-                token_after=None,
-                duration_ms=None,
-                bytes_downloaded=None,
-                cache_mode=None,
-                sync_policy=result.get("effective_update_mode") or mode.value,
-            )
-        if include_attachments_index:
-            attachments_index_count = len(result.get("attachments_index", []))
-            _emit_sync_decision(
-                logger,
-                trace=debug_trace,
-                command="upload-results",
-                project_storage_key=project_storage_key,
-                resource_type="confluence_page_section",
-                resource_id=str(result.get("page_id") or parent_page),
-                decision="attachments_index_updated" if attachments_index_count > 0 else "attachments_index_skipped",
-                reason=f"attachments_index_count_{attachments_index_count}",
-                token_before=None,
-                token_after=None,
-                duration_ms=None,
-                bytes_downloaded=None,
-                cache_mode=None,
-                sync_policy=result.get("effective_update_mode") or mode.value,
-            )
-
-        debug_paths = (
-            debug_trace.write(
-                command="upload-results",
-                state_diff={
-                    "operation": "upload-results",
-                    "page_id": result.get("page_id"),
-                    "publish_mode": mode.value,
-                    "update_mode": result.get("update_mode"),
-                    "effective_update_mode": result.get("effective_update_mode"),
-                    "fallback_reason": result.get("fallback_reason"),
-                    "attachments_count": len(result.get("attachments", [])),
-                    "attachments_index_count": len(result.get("attachments_index", [])),
-                    "attachments_updated": int(counters.get("attachments_updated", 0)),
-                    "attachments_skipped": int(counters.get("attachments_skipped", 0)),
-                    "duration_ms": upload_duration_ms,
-                },
-            )
-            if debug_trace is not None
-            else None
-        )
-
-        if thread_id:
-            upload_run_parameters = _normalize_run_parameters(
-                {
-                    "schema": "audit-run.parameters.v1",
-                    "command": "upload-results",
-                    "thread_id": thread_id,
-                    "report_dir": report_dir,
-                    "parent_page": parent_page,
-                    "page_title": page_title,
-                    "timeout": timeout,
-                    "retries": retries,
-                    "backoff": backoff,
-                    "include_attachments": include_attachments,
-                    "publish_mode": mode.value,
-                    "update_mode": resolved_update_mode.value,
-                    "include_attachments_index": include_attachments_index,
-                    "priority_actions_limit": priority_actions_limit,
-                    "checklist_collapsed": checklist_collapsed,
-                    "debug_artifacts": debug_artifacts,
-                    "debug_artifacts_dir": debug_artifacts_dir,
-                    "runtime_profile": _active_runtime_profile_name(),
-                }
-            )
-            _persist_typed_run_terminal(
-                state_dsn=resolved_state_dsn,
-                run_id=thread_id,
-                project_key=project_storage_key,
-                repo_key=None,
-                run_type="upload_results",
-                terminal_status="completed",
-                event_type="publish_completed",
-                payload={
-                    "kind": "upload_results",
-                    "report_dir": str(report_dir),
-                    "parent_page": parent_page,
-                    "page_id": result.get("page_id"),
-                    "project_root_page_id": result.get("project_root_page_id"),
-                    "audit_root_page_id": result.get("audit_root_page_id"),
-                    "repo_root_page_id": result.get("repo_root_page_id"),
-                    "repo_run_page_id": result.get("repo_run_page_id"),
-                    "project_analysis_root_page_id": result.get("project_analysis_root_page_id"),
-                    "project_aggregate_page_id": result.get("project_aggregate_page_id"),
-                    "effective_update_mode": result.get("effective_update_mode"),
-                    "readiness_summary": result.get("readiness_summary"),
-                    "run_parameters": upload_run_parameters,
-                },
-            )
-        if _cli_state.get("json_only"):
-            if debug_paths is not None:
-                result["debug_artifacts"] = debug_paths
-            _emit_json(result)
-            return
-        console.print("[green]Upload complete.[/green]")
-        console.print(f"Page ID: {result.get('page_id')}")
-        console.print(f"Attachments: {len(result.get('attachments', []))}")
-        console.print(
-            f"Update mode: requested={result.get('update_mode')} effective={result.get('effective_update_mode')}"
-        )
-        if result.get("fallback_reason"):
-            console.print(f"[yellow]Fallback reason:[/yellow] {result.get('fallback_reason')}")
-        if isinstance(counters, dict):
-            console.print(
-                "Counters: "
-                f"rows_changed={counters.get('rows_changed', 0)}, "
-                f"rows_unchanged={counters.get('rows_unchanged', 0)}, "
-                f"attachments_updated={counters.get('attachments_updated', 0)}, "
-                f"attachments_skipped={counters.get('attachments_skipped', 0)}"
-            )
-        if result.get("attachments_index"):
-            console.print(f"Attachments indexed: {len(result.get('attachments_index', []))}")
-        if debug_paths is not None:
-            console.print(f"Debug artifacts: {debug_paths['cache_trace_path']}")
-    except ValueError as e:
-        # TSK-170B: Handle create-only mode errors gracefully
-        message = str(e)
-        if _cli_state.get("json_only"):
-            _emit_json({"error": message})
-        else:
-            console.print(f"[red]{message}[/red]")
-        raise typer.Exit(1) from e
-    except Exception as e:
-        message = f"Upload failed: {e}"
-        if _cli_state.get("json_only"):
-            _emit_json({"error": message})
-        else:
-            console.print(f"[red]{message}[/red]")
-            logger.exception("upload_failed")
-        raise typer.Exit(1) from e
-
-
-# ---------------------------------------------------------------------------
-# upload-project-results
-# ---------------------------------------------------------------------------
-
-
-@app.command(name="upload-project-results")
-def upload_project_results(
-    report_dir: Path = typer.Option(
-        ...,
-        "--report-dir",
-        help="Directory containing project readiness/aggregate reports",
-        exists=True,
-    ),
-    parent_page: str = typer.Option(
-        ...,
-        "--parent-page",
-        help="Confluence parent page URL or ID",
-    ),
-    page_title: str = typer.Option(
-        ...,
-        "--page-title",
-        help="Title for the project aggregate page",
-    ),
-    timeout: int = typer.Option(
-        120,
-        "--timeout",
-        help="Timeout (seconds) for Confluence vds-cli calls",
-    ),
-    retries: int = typer.Option(
-        2,
-        "--retries",
-        help="Number of retries for transient Confluence errors",
-    ),
-    backoff: float = typer.Option(
-        1.0,
-        "--backoff",
-        help="Base backoff (seconds) for retries; exponential with attempt number",
-    ),
-    include_attachments: bool = typer.Option(
-        True,
-        help="Upload project aggregate artifacts as attachments",
-    ),
-    thread_id: str | None = typer.Option(
-        None,
-        "--thread-id",
-        help="Workflow thread ID for provenance tracking",
-    ),
-    project_storage_key: str | None = typer.Option(
-        None,
-        "--project-storage-key",
-        help="Canonical project storage key for deterministic hierarchy path",
-    ),
-    unified_hierarchy: bool = typer.Option(
-        False,
-        "--unified-hierarchy/--no-unified-hierarchy",
-        help=(
-            "TSK-940.71 (FR-282): Place aggregate page under the shared 'Project Audit' node "
-            "alongside repo pages. Default places it under a separate 'Project Analysis' branch."
-        ),
-    ),
-    state_dsn: str | None = typer.Option(
-        None,
-        "--state-dsn",
-        envvar=_STATE_DSN_ENV_VAR,
-        help=f"Persist upload state metadata to backend DSN (required; fallback: {_STATE_DSN_ENV_VAR}).",
-    ),
-    project_name_hint: str | None = typer.Option(
-        None,
-        "--project-name-hint",
-        help="Phase 154 (AC-154.7.5): Explicit project name for stable hierarchy node titles.",
-    ),
-) -> None:
-    """Upload project-level readiness aggregate to Confluence.
-
-    TSK-940.71 (FR-282): Use --unified-hierarchy to place the aggregate page
-    under the shared 'Project Audit - {key}' node alongside repo pages,
-    instead of the default separate 'Project Analysis - {key}' branch.
-    """
-    from vds_audit_orchestrator.publishers.confluence_publisher import ConfluencePublisher
-
-    resolved_state_dsn = _require_producer_state_dsn(state_dsn, command="upload-project-results")
-    inferred_project_key = project_storage_key or _normalize_storage_key(page_title)
-    resolved_hierarchy_target = "repo" if unified_hierarchy else None
-    # Phase 154 (AC-154.7.5): Resolve project_name_hint from CLI or storage key.
-    resolved_project_name_hint = project_name_hint or inferred_project_key
-
-    async def _run_upload_project() -> dict[str, Any]:
-        client = ConfluenceCliClient(timeout=timeout, retries=retries)
-        publisher = ConfluencePublisher(client, retries=retries, backoff=backoff, state_dsn=resolved_state_dsn)
-        result = await publisher.publish_project_aggregate(
-            report_dir=report_dir,
-            parent_page=parent_page,
-            page_title=page_title,
-            include_attachments=include_attachments,
-            project_storage_key=inferred_project_key,
-            hierarchy_target=resolved_hierarchy_target,
-            project_name_hint=resolved_project_name_hint,
-        )
-        return {
-            "page_id": result.page_id,
-            "reused_existing_page": bool(getattr(result, "reused_existing_page", False)),
-            "attachments": result.attachments,
-            "project_root_page_id": getattr(result, "project_root_page_id", None),
-            "project_analysis_root_page_id": getattr(result, "project_analysis_root_page_id", None),
-            "project_aggregate_page_id": getattr(result, "project_aggregate_page_id", None),
-        }
-
-    try:
-        result = asyncio.run(_run_upload_project())
-        if thread_id:
-            upload_project_run_parameters = _normalize_run_parameters(
-                {
-                    "schema": "audit-run.parameters.v1",
-                    "command": "upload-project-results",
-                    "thread_id": thread_id,
-                    "report_dir": report_dir,
-                    "parent_page": parent_page,
-                    "page_title": page_title,
-                    "project_storage_key": inferred_project_key,
-                    "timeout": timeout,
-                    "retries": retries,
-                    "backoff": backoff,
-                    "include_attachments": include_attachments,
-                    "unified_hierarchy": unified_hierarchy,
-                    "runtime_profile": _active_runtime_profile_name(),
-                }
-            )
-            _persist_typed_run_terminal(
-                state_dsn=resolved_state_dsn,
-                run_id=thread_id,
-                project_key=inferred_project_key,
-                repo_key=None,
-                run_type="upload_project_results",
-                terminal_status="completed",
-                event_type="publish_completed",
-                payload={
-                    "kind": "upload_project_results",
-                    "report_dir": str(report_dir),
-                    "parent_page": parent_page,
-                    "page_id": result.get("page_id"),
-                    "project_root_page_id": result.get("project_root_page_id"),
-                    "project_analysis_root_page_id": result.get("project_analysis_root_page_id"),
-                    "project_aggregate_page_id": result.get("project_aggregate_page_id"),
-                    "run_parameters": upload_project_run_parameters,
-                },
-            )
-        if _cli_state.get("json_only"):
-            _emit_json(result)
-            return
-        console.print("[green]Project aggregate upload complete.[/green]")
-        console.print(f"Page ID: {result.get('page_id')}")
-        console.print(f"Attachments: {len(result.get('attachments', []))}")
-    except Exception as e:
-        message = f"Project aggregate upload failed: {e}"
-        error_context = {
-            "exception": str(e),
-            "exception_type": type(e).__name__,
-            "thread_id": thread_id,
-            "report_dir": str(report_dir),
-            "parent_page": parent_page,
-            "project_storage_key": inferred_project_key,
-        }
-        if _cli_state.get("json_only"):
-            _emit_json({"error": message})
-        else:
-            console.print(f"[red]{message}[/red]")
-            logger.exception("upload_project_results_failed", **error_context)
-        raise typer.Exit(1) from e
-
-
-# ---------------------------------------------------------------------------
-# publish-project-run
-# ---------------------------------------------------------------------------
-
-
-def _materialize_project_publish_repo_dirs(
-    *,
-    report_dir: Path,
-    include_existing_repos: bool = True,
-) -> tuple[Path, list[str]]:
-    """Return a repo root ready for repo-page publication.
-
-    Reuses existing `repos/<repo>/` directories when present. Otherwise, materializes
-    minimal repo report directories from `project-repo-results.json` using the
-    existing workflow helper. Returns `(repos_root, repo_keys)` and raises
-    `ValueError` when no repo-page material can be produced.
-    """
-    repos_root = report_dir / "repos"
-    repo_dirs = []
-    if include_existing_repos and repos_root.exists():
-        repo_dirs = [item for item in repos_root.iterdir() if item.is_dir()]
-    if repo_dirs:
-        repo_keys = sorted(item.name for item in repo_dirs)
-        return repos_root, repo_keys
-
-    project_repo_results_path = report_dir / "project-repo-results.json"
-    if not project_repo_results_path.exists():
-        raise ValueError(
-            "Project run root does not contain repo report directories or project-repo-results.json; "
-            "cannot publish repo pages from this artifact set."
-        )
-
-    try:
-        payload = json.loads(project_repo_results_path.read_text(encoding="utf-8"))
-    except (OSError, TypeError, ValueError) as exc:
-        raise ValueError(f"Failed to parse project-repo-results.json: {exc}") from exc
-
-    repo_results_payload = [item for item in payload if isinstance(item, dict)] if isinstance(payload, list) else []
-    if not repo_results_payload:
-        raise ValueError(
-            "project-repo-results.json contains no repo payloads; cannot publish repo pages from this artifact set."
-        )
-
-    from vds_audit_orchestrator import workflow_cmds as workflow_cmds_module
-
-    workflow_cmds_module._materialize_project_repo_report_dirs(
-        repos_root=repos_root,
-        repo_results_payload=repo_results_payload,
-    )
-
-    repo_dirs = [item for item in repos_root.iterdir() if item.is_dir()] if repos_root.exists() else []
-    if not repo_dirs:
-        raise ValueError(
-            "Repo report materialization completed without producing repo directories; "
-            "cannot publish repo pages from this artifact set."
-        )
-
-    repo_keys = sorted(item.name for item in repo_dirs)
-    return repos_root, repo_keys
-
-
-@app.command(name="publish-project-run")
-def publish_project_run(
-    report_dir: Path | None = typer.Option(
-        None,
-        "--report-dir",
-        help=(
-            "Existing project run root containing aggregate artifacts and repo payloads. "
-            "Required when --resume-run is not provided."
-        ),
-        exists=False,
-    ),
-    project_page: str = typer.Option(
-        ...,
-        "--project-page",
-        help="Canonical project page URL or ID used as the publication anchor",
-    ),
-    project_storage_key: str = typer.Option(
-        ...,
-        "--project-storage-key",
-        help="Canonical project storage key",
-    ),
-    project_title: str | None = typer.Option(
-        None,
-        "--project-title",
-        help="Explicit project title override for repo-page titles",
-    ),
-    aggregate_placement: str = typer.Option(
-        "project",
-        "--aggregate-placement",
-        help="Aggregate placement: 'project' for separate Project Analysis branch or 'unified' under Project Audit",
-    ),
-    include_attachments: bool = typer.Option(
-        False,
-        "--upload-attachments/--no-upload-attachments",
-        help="Upload attachments for repo and aggregate pages",
-    ),
-    thread_id: str | None = typer.Option(
-        None,
-        "--thread-id",
-        help="Typed-run thread ID for provenance tracking",
-    ),
-    state_dsn: str | None = typer.Option(
-        None,
-        "--state-dsn",
-        envvar=_STATE_DSN_ENV_VAR,
-        help=f"Persist publish state metadata to backend DSN (required; fallback: {_STATE_DSN_ENV_VAR}).",
-    ),
-    resume_run: str | None = typer.Option(
-        None,
-        "--resume-run",
-        help=(
-            "TSK-147.16: Resume publication from a specific prior run by thread_id. "
-            "Resolves report-dir from default layout. Ignored when --report-dir is also provided."
-        ),
-    ),
-) -> None:
-    """Publish repo pages and aggregate page from an existing project run root."""
-    from vds_audit_orchestrator import workflow_cmds as _workflow_cmds_module
-    from vds_audit_orchestrator.publishers.confluence_publisher import ConfluencePublisher
-
-    # TSK-147.16: Resolve report_dir from --resume-run when --report-dir is absent.
-    if report_dir is None and resume_run is not None:
-        report_dir = _workflow_cmds_module._default_workflow_project_run_root(
-            project_storage_key=project_storage_key,
-            thread_id=resume_run,
-            report_dir=None,
-        )
-        if thread_id is None:
-            thread_id = resume_run
-        logger.info(
-            "publish_project_run_resume_run_resolved",
-            resume_run=resume_run,
-            report_dir=str(report_dir),
-            thread_id=thread_id,
-        )
-    elif report_dir is not None and resume_run is not None:
-        logger.warning(
-            "publish_project_run_resume_run_ignored",
-            reason="--report-dir takes precedence over --resume-run when both are provided.",
-            resume_run=resume_run,
-            report_dir=str(report_dir),
-        )
-    elif report_dir is None:
-        raise typer.BadParameter("--report-dir is required when --resume-run is not provided.")
-
-    if not report_dir.exists():  # type: ignore[union-attr]
-        raise typer.BadParameter(f"--report-dir does not exist: {report_dir}")
-
-    resolved_state_dsn = _require_producer_state_dsn(state_dsn, command="publish-project-run")
-    placement = aggregate_placement.strip().lower()
-    if placement not in {"project", "unified"}:
-        raise typer.BadParameter("--aggregate-placement must be 'project' or 'unified'.")
-
-    aggregate_payload = None
-    aggregate_path = report_dir / "project-aggregate.json"
-    if aggregate_path.exists():
-        try:
-            loaded_payload = json.loads(aggregate_path.read_text(encoding="utf-8"))
-            aggregate_payload = loaded_payload if isinstance(loaded_payload, dict) else None
-        except (OSError, TypeError, ValueError) as exc:
-            raise ValueError(f"Failed to parse project-aggregate.json: {exc}") from exc
-    resolved_project_title = (
-        str(project_title or "")
-        or str((aggregate_payload or {}).get("project_title") or "")
-        or str((aggregate_payload or {}).get("project_name") or "")
-        or str(project_storage_key)
-    ).strip()
-    if not resolved_project_title:
-        resolved_project_title = project_storage_key
-
-    try:
-        repos_root, repo_keys = _materialize_project_publish_repo_dirs(report_dir=report_dir)
-    except ValueError as exc:
-        raise typer.BadParameter(str(exc)) from exc
-    if not repo_keys:
-        raise typer.BadParameter("No repo report directories are available for publish-project-run.")
-
-    async def _run_publish() -> dict[str, Any]:
-        client = ConfluenceCliClient()
-        publisher = ConfluencePublisher(client, state_dsn=resolved_state_dsn)
-        repo_page_ids: dict[str, str] = {}
-        for repo_key in repo_keys:
-            repo_report_dir = repos_root / repo_key
-            repo_report_dir / "workflow-summary.json"
-            # Phase 154 (AC-154.7.3): Canonical repo title uses repo_key only.
-            # Project context is encoded in the hierarchy node, not the repo page title.
-            repo_title = f"Audit Results - {repo_key}"
-            published = await publisher.upload_results(
-                report_dir=repo_report_dir,
-                parent_page=project_page,
-                page_title=repo_title,
-                include_attachments=include_attachments,
-                thread_id=f"{thread_id}:{repo_key}" if thread_id else None,
-                project_storage_key=project_storage_key,
-                repo_storage_key=repo_key,
-                hierarchy_target="repo",
-                project_name_hint=resolved_project_title,
-            )
-            repo_page_ids[repo_key] = str(published.page_id)
-
-        aggregate_title = f"Project Analysis - {resolved_project_title}"
-        aggregate_result = await publisher.publish_project_aggregate(
-            report_dir=report_dir,
-            parent_page=project_page,
-            page_title=aggregate_title,
-            include_attachments=include_attachments,
-            project_storage_key=project_storage_key,
-            hierarchy_target="repo" if placement == "unified" else None,
-            project_name_hint=resolved_project_title,
-        )
-        return {
-            "project_storage_key": project_storage_key,
-            "project_page": project_page,
-            "project_title": resolved_project_title,
-            "repo_pages_published": len(repo_page_ids),
-            "repo_page_ids": repo_page_ids,
-            "aggregate_page_id": str(aggregate_result.page_id),
-            "aggregate_placement": placement,
-        }
-
-    try:
-        result = asyncio.run(_run_publish())
-        if thread_id:
-            publish_run_parameters = _normalize_run_parameters(
-                {
-                    "schema": "audit-run.parameters.v1",
-                    "command": "publish-project-run",
-                    "thread_id": thread_id,
-                    "report_dir": report_dir,
-                    "project_page": project_page,
-                    "project_storage_key": project_storage_key,
-                    "project_title": resolved_project_title,
-                    "aggregate_placement": placement,
-                    "include_attachments": include_attachments,
-                    "runtime_profile": _active_runtime_profile_name(),
-                }
-            )
-            _persist_typed_run_terminal(
-                state_dsn=resolved_state_dsn,
-                run_id=thread_id,
-                project_key=project_storage_key,
-                repo_key=None,
-                run_type="publish_project_run",
-                terminal_status="completed",
-                event_type="publish_completed",
-                payload={
-                    "kind": "publish_project_run",
-                    "report_dir": str(report_dir),
-                    "project_page": project_page,
-                    "project_storage_key": project_storage_key,
-                    "project_title": resolved_project_title,
-                    "repo_page_ids": result["repo_page_ids"],
-                    "aggregate_page_id": result["aggregate_page_id"],
-                    "aggregate_placement": placement,
-                    "run_parameters": publish_run_parameters,
-                },
-            )
-        if _cli_state.get("json_only"):
-            _emit_json(result)
-            return
-        console.print("[green]Project run publish complete.[/green]")
-        console.print(f"Repo pages published: {result['repo_pages_published']}")
-        console.print(f"Aggregate page ID: {result['aggregate_page_id']}")
-    except Exception as exc:
-        message = f"Project run publish failed: {exc}"
-        if _cli_state.get("json_only"):
-            _emit_json({"error": message})
-        else:
-            console.print(f"[red]{message}[/red]")
-            logger.exception(
-                "publish_project_run_failed",
-                exception=str(exc),
-                exception_type=type(exc).__name__,
-                thread_id=thread_id,
-                report_dir=str(report_dir),
-                project_page=project_page,
-                project_storage_key=project_storage_key,
-            )
-        raise typer.Exit(1) from exc
-
-
-# ---------------------------------------------------------------------------
-# publish-system-doc helpers
-# ---------------------------------------------------------------------------
-
-
-def _resolve_system_doc_parent_reference(
-    *,
-    parent_page: str | None,
-    project_payload: dict[str, Any],
-    registry_metadata: dict[str, Any],
-) -> tuple[str, str]:
-    _ = project_payload
-    if parent_page and str(parent_page).strip():
-        return str(parent_page).strip(), "cli_override"
-
-    for key in ("registry_page_id", "registry_url"):
-        candidate = str(registry_metadata.get(key) or "").strip()
-        if candidate:
-            return candidate, "state_registry"
-
-    raise typer.BadParameter(
-        (
-            "Unable to resolve registry root page from state. "
-            "Provide --parent-page explicitly or run parse-registry first."
-        ),
-    )
-
-
-def _normalize_system_doc_sync_policy(raw_value: str) -> str:
-    value = (raw_value or "if-changed").strip().lower()
-    allowed = {"if-changed", "force", "dry-run"}
-    if value not in allowed:
-        raise typer.BadParameter("--sync-policy must be one of: if-changed, force, dry-run")
-    return value
-
-
-# ---------------------------------------------------------------------------
-# publish-system-doc
-# ---------------------------------------------------------------------------
-
-
-@app.command(name="publish-system-doc")
-def publish_system_doc(
-    project: str = typer.Option(
-        ...,
-        "--project",
-        help="Project identifier used to resolve state metadata (storage key, page ID, or project name).",
-    ),
-    parent_page: str | None = typer.Option(
-        None,
-        "--parent-page",
-        help="Optional explicit Confluence parent page URL or ID. Defaults to registry root from centralized state.",
-    ),
-    page_title: str = typer.Option(
-        "Audit System Documentation",
-        "--page-title",
-        help="System document page title.",
-    ),
-    sync_policy: str = typer.Option(
-        "if-changed",
-        "--sync-policy",
-        help="Sync policy: if-changed, force, or dry-run.",
-    ),
-    timeout: int = typer.Option(
-        120,
-        "--timeout",
-        help="Timeout (seconds) for Confluence calls.",
-    ),
-    retries: int = typer.Option(
-        2,
-        "--retries",
-        help="Number of retries for transient Confluence errors.",
-    ),
-    backoff: float = typer.Option(
-        1.0,
-        "--backoff",
-        help="Base backoff (seconds) for retries; exponential with attempt number.",
-    ),
-    confluence_server: str | None = typer.Option(
-        None,
-        "--confluence-server",
-        help="Confluence server key: internal|external. If omitted, inferred from parent page URL when possible.",
-    ),
-    thread_id: str | None = typer.Option(
-        None,
-        "--thread-id",
-        help="Optional run ID override; autogenerated when omitted.",
-    ),
-    debug_artifacts: bool = typer.Option(
-        False,
-        "--debug-artifacts/--no-debug-artifacts",
-        help="Write optional debug artifacts: cache_trace.jsonl, sync_plan.json, state_diff.json.",
-    ),
-    debug_artifacts_dir: Path | None = typer.Option(
-        None,
-        "--debug-artifacts-dir",
-        help="Directory for debug artifacts (defaults to current working directory).",
-    ),
-    state_dsn: str | None = typer.Option(
-        None,
-        "--state-dsn",
-        envvar=_STATE_DSN_ENV_VAR,
-        help=f"Persist publish lineage to backend DSN (required; fallback: {_STATE_DSN_ENV_VAR}).",
-    ),
-) -> None:
-    """Publish the Phase 106 multi-page Audit System Documentation hierarchy."""
-
-    from vds_audit_orchestrator.publishers.confluence_publisher import ConfluencePublisher
-    from vds_audit_orchestrator.publishers.hierarchy_publisher import publish_hierarchy
-
-    resolved_state_dsn = _require_producer_state_dsn(state_dsn, command="publish-system-doc")
-    normalized_sync_policy = _normalize_system_doc_sync_policy(sync_policy)
-
-    _validate_required_credentials(command="publish-system-doc", require_confluence=True)
-
-    manifest_payload, projects = _resolve_parse_manifest_payload(
-        state_dsn=resolved_state_dsn,
-        command="publish-system-doc",
-    )
-    try:
-        project_payload = select_project(projects, project)
-    except (ValueError, LookupError) as exc:
-        raise typer.BadParameter(str(exc)) from exc
-
-    project_storage_key = _project_storage_key_from_payload(project_payload)
-    registry_metadata = _parse_registry_metadata(manifest_payload)
-    requested_parent, parent_source = _resolve_system_doc_parent_reference(
-        parent_page=parent_page,
-        project_payload=project_payload,
-        registry_metadata=registry_metadata,
-    )
-    inferred_server = _parse_confluence_ref(requested_parent).server if requested_parent else None
-    resolved_server = confluence_server or inferred_server
-    confluence = ConfluenceCliClient(server=resolved_server, timeout=timeout, retries=retries)
-    resolved_parent_page_id = asyncio.run(_resolve_confluence_page_id(confluence, requested_parent))
-
-    effective_thread_id = (
-        thread_id or f"publish-system-doc-{datetime.now(UTC).strftime('%Y%m%d%H%M%S')}-{uuid4().hex[:8]}"
-    )
-    debug_trace = _DebugArtifactsCollector((debug_artifacts_dir or Path.cwd()).resolve()) if debug_artifacts else None
-    publish_start = perf_counter()
-
-    if debug_trace is not None:
-        debug_trace.add_sync_plan(
-            project_storage_key=project_storage_key,
-            resource_type="confluence_page",
-            resource_id=resolved_parent_page_id,
-            decision="publish",
-            reason=f"sync_policy_{normalized_sync_policy}",
-        )
-
-    try:
-        publisher = ConfluencePublisher(confluence, retries=retries, backoff=backoff, state_dsn=resolved_state_dsn)
-        hierarchy_result = asyncio.run(
-            publish_hierarchy(
-                publisher,
-                parent_page_id=resolved_parent_page_id,
-                page_title=page_title,
-                project_storage_key=project_storage_key,
-                state_dsn=resolved_state_dsn,
-                sync_policy=normalized_sync_policy,
-                source_root=Path.cwd(),
-            )
-        )
-        result = {
-            "page_id": hierarchy_result.root_page_id,
-            "parent_page_id": resolved_parent_page_id,
-            "decision": hierarchy_result.decision,
-            "reason": hierarchy_result.reason,
-            "token_before": None,
-            "token_after": hierarchy_result.root_content_hash,
-            "source_fingerprint": None,
-            "rendered_hash": hierarchy_result.root_content_hash,
-            "remote_managed_hash": None,
-            "updated_at": None,
-            "dry_run": hierarchy_result.dry_run,
-            "child_results": [dataclasses.asdict(item) for item in hierarchy_result.child_results],
-            "hierarchy": True,
-            "root_page_id": hierarchy_result.root_page_id,
-            "root_title": hierarchy_result.root_title,
-            "live_data_populated": hierarchy_result.live_data_populated,
-        }
-        duration_ms = int((perf_counter() - publish_start) * 1000)
-        decision = str(result.get("decision") or "").strip() or ("published" if result.get("page_id") else "no-op")
-        reason = str(result.get("reason") or "").strip() or "publisher_response"
-
-        _emit_sync_decision(
-            logger,
-            trace=debug_trace,
-            command="publish-system-doc",
-            project_storage_key=project_storage_key,
-            resource_type="confluence_page",
-            resource_id=str(result.get("page_id") or resolved_parent_page_id),
-            decision=decision,
-            reason=reason,
-            token_before=result.get("token_before"),
-            token_after=result.get("token_after"),
-            duration_ms=duration_ms,
-            bytes_downloaded=None,
-            cache_mode=None,
-            sync_policy=normalized_sync_policy,
-        )
-
-        publish_payload: dict[str, Any] = {
-            "kind": "publish_system_doc",
-            "thread_id": effective_thread_id,
-            "project_storage_key": project_storage_key,
-            "page_title": page_title,
-            "requested_parent": requested_parent,
-            "resolved_parent_page_id": resolved_parent_page_id,
-            "parent_source": parent_source,
-            "page_id": result.get("page_id"),
-            "sync_policy": normalized_sync_policy,
-            "decision": decision,
-            "reason": reason,
-            "token_before": result.get("token_before"),
-            "token_after": result.get("token_after"),
-            "source_fingerprint": result.get("source_fingerprint"),
-            "rendered_hash": result.get("rendered_hash"),
-            "remote_managed_hash": result.get("remote_managed_hash"),
-            "updated_at": result.get("updated_at"),
-            "duration_ms": duration_ms,
-            "hierarchy": True,
-            "child_results": result.get("child_results"),
-            "root_page_id": result.get("root_page_id"),
-            "live_data_populated": result.get("live_data_populated"),
-        }
-        _persist_typed_run_terminal(
-            state_dsn=resolved_state_dsn,
-            run_id=effective_thread_id,
-            project_key=project_storage_key,
-            repo_key=None,
-            run_type="publish_system_doc",
-            terminal_status="completed",
-            event_type="publish_completed",
-            payload=publish_payload,
-        )
-
-        output: dict[str, Any] = {
-            "command": "publish-system-doc",
-            "thread_id": effective_thread_id,
-            "registry": registry_metadata,
-            "project": {
-                "project_storage_key": project_storage_key,
-                "project_name": project_payload.get("project_name"),
-                "project_name_en": project_payload.get("project_name_en"),
-                "page_id": project_payload.get("page_id"),
-            },
-            "parent": {
-                "requested": requested_parent,
-                "resolved_page_id": resolved_parent_page_id,
-                "source": parent_source,
-            },
-            "sync": {
-                "policy": normalized_sync_policy,
-                "decision": decision,
-                "reason": reason,
-                "token_before": result.get("token_before"),
-                "token_after": result.get("token_after"),
-                "source_fingerprint": result.get("source_fingerprint"),
-                "rendered_hash": result.get("rendered_hash"),
-                "remote_managed_hash": result.get("remote_managed_hash"),
-                "hierarchy": True,
-            },
-            "publish": {
-                "page_id": result.get("page_id"),
-                "parent_page_id": result.get("parent_page_id") or resolved_parent_page_id,
-                "updated_at": result.get("updated_at"),
-                "dry_run": bool(result.get("dry_run")),
-                "root_page_id": result.get("root_page_id"),
-                "child_results": result.get("child_results"),
-                "live_data_populated": result.get("live_data_populated"),
-            },
-            "duration_ms": duration_ms,
-        }
-
-        debug_paths = (
-            debug_trace.write(
-                command="publish-system-doc",
-                state_diff={
-                    "operation": "publish-system-doc",
-                    "thread_id": effective_thread_id,
-                    "project_storage_key": project_storage_key,
-                    "resolved_parent_page_id": resolved_parent_page_id,
-                    "page_id": result.get("page_id"),
-                    "sync_policy": normalized_sync_policy,
-                    "decision": decision,
-                    "reason": reason,
-                    "token_before": result.get("token_before"),
-                    "token_after": result.get("token_after"),
-                    "source_fingerprint": result.get("source_fingerprint"),
-                    "rendered_hash": result.get("rendered_hash"),
-                    "remote_managed_hash": result.get("remote_managed_hash"),
-                    "duration_ms": duration_ms,
-                },
-            )
-            if debug_trace is not None
-            else None
-        )
-        if debug_paths is not None:
-            output["debug_artifacts"] = debug_paths
-
-        if _cli_state.get("json_only"):
-            _emit_json(output)
-            return
-
-        console.print("[green]System document publish complete.[/green]")
-        console.print(f"Thread ID: {effective_thread_id}")
-        console.print(f"Project: {project_storage_key}")
-        console.print(f"Parent page: {resolved_parent_page_id} ({parent_source})")
-        console.print(f"Root page ID: {result.get('root_page_id')}")
-        console.print(f"Sync: policy={normalized_sync_policy}")
-        console.print(f"Decision: {decision} ({reason})")
-        if debug_paths is not None:
-            console.print(f"Debug artifacts: {debug_paths['cache_trace_path']}")
-    except Exception as exc:
-        try:
-            _persist_typed_run_terminal(
-                state_dsn=resolved_state_dsn,
-                run_id=effective_thread_id,
-                project_key=project_storage_key,
-                repo_key=None,
-                run_type="publish_system_doc",
-                terminal_status="failed",
-                event_type="run_failed",
-                payload={
-                    "kind": "publish_system_doc",
-                    "thread_id": effective_thread_id,
-                    "project_storage_key": project_storage_key,
-                    "sync_policy": normalized_sync_policy,
-                    "error": str(exc),
-                },
-            )
-        except Exception:
-            logger.exception("publish_system_doc_failed_to_persist_terminal")
-
-        message = f"publish-system-doc failed: {exc}"
-        if _cli_state.get("json_only"):
-            _emit_json({"error": message, "thread_id": effective_thread_id})
-        else:
-            console.print(f"[red]{message}[/red]")
-            logger.exception("publish_system_doc_failed")
-        raise typer.Exit(1) from exc
-
-
-# ---------------------------------------------------------------------------
-# approval-history
-# ---------------------------------------------------------------------------
-
-
-@app.command(name="approval-history")
-def approval_history(
-    thread_id: str = typer.Argument(..., help="Thread ID to look up"),
-) -> None:
-    """Get the approval decision history for a thread.
-
-    Retrieves the audit log entry for a previous approval decision.
-
-    Example:
-        vds-audit approval-history audit-123
-    """
-    from vds_audit_orchestrator.agents.approval import get_approval_history_cli
-
-    decision = get_approval_history_cli(thread_id)
-
-    if _cli_state.get("json_only"):
-        if decision:
-            _emit_json({"decision": decision})
-        else:
-            _emit_json({"decision": None, "message": "No decision found for this thread"})
-        return
-
-    if not decision:
-        console.print(f"[yellow]No approval decision found for thread: {thread_id}[/yellow]")
-        raise typer.Exit(1)
-
-    console.print(f"[bold]Approval Decision for {thread_id}[/bold]\n")
-    console.print(f"Status: {decision['status']}")
-    console.print(f"Approved: {decision['approved']}")
-    console.print(f"Decided at: {decision['decided_at']}")
-    if decision.get("reviewer"):
-        console.print(f"Reviewer: {decision['reviewer']}")
-    if decision.get("feedback"):
-        console.print(f"Feedback: {decision['feedback']}")
-
-
-# ---------------------------------------------------------------------------
-# _load_baseline_scores (helper for audit command)
-# ---------------------------------------------------------------------------
-
-
-def _load_baseline_scores(path: Path) -> dict[str, float]:
-    """Load baseline scores from a prior JSON report."""
-    raw = json.loads(path.read_text(encoding="utf-8"))
-    repos = raw.get("repositories")
-    if not isinstance(repos, list):
-        return {}
-    scores: dict[str, float] = {}
-    for repo in repos:
-        if not isinstance(repo, dict):
-            continue
-        name = repo.get("repo_name") or repo.get("repository_name")
-        score = repo.get("total_score") or repo.get("overall_score")
-        if name and isinstance(score, (int, float)):
-            scores[str(name)] = float(score)
-    return scores
-
-
-# ---------------------------------------------------------------------------
-# status
-# ---------------------------------------------------------------------------
-
-
-@app.command()
-def status() -> None:
-    """Check orchestrator status."""
-    config = get_config()
-    llm = config.llm
-    status_payload: dict[str, Any] = {
-        "status": "ok",
-        "service": APP_NAME,
-        "runtime_profile": _cli_state.get("runtime_profile", {}),
-        "config": {
-            "llm_enabled": bool(llm.enabled or config.features.llm_enabled),
-            "llm_protocol": llm.protocol.value,
-            "agent_runtime_mode": llm.agent_runtime_mode.value,
-            "model_simple": llm.model_simple,
-            "model_standard": llm.model_standard,
-            "model_complex": llm.model_complex,
-            "llm_base_url": llm.base_url,
-            "active_profile": os.getenv("VDS_AUDIT_ACTIVE_PROFILE") or None,
-            "state_dsn_set": bool((os.getenv(_STATE_DSN_ENV_VAR) or "").strip()),
-            "langgraph_postgres_dsn_set": bool((os.getenv("VDS_AUDIT_LANGGRAPH__POSTGRES_DSN") or "").strip()),
-        },
-    }
-
-    if _cli_state.get("json_only"):
-        _emit_json(status_payload)
-        return
-
-    console.print(f"[green]{APP_NAME} is operational.[/green]")
-    console.print(
-        f"LLM protocol: [bold]{llm.protocol.value}[/bold] "
-        f"(model standard: [bold]{llm.model_standard}[/bold], profile: [bold]{status_payload['config']['active_profile'] or 'none'}[/bold])"
-    )
-
-
-# ---------------------------------------------------------------------------
-# list-checks
-# ---------------------------------------------------------------------------
-
-
-@app.command(name="list-checks")
-def list_checks(
-    category: str | None = typer.Option(None, "--category", "-c", help="Filter by category"),
-    detailed: bool = typer.Option(False, "--detailed", "-d", help="Show detailed check information"),
-) -> None:
-    """List available audit checks with descriptions and configuration options."""
-    if category:
-        checks = CheckRegistry.list_checks_by_category(category)
-        if not checks:
-            console.print(f"[yellow]No checks found in category '{category}'[/yellow]")
-            console.print(f"Available categories: {', '.join(CheckRegistry.get_categories())}")
-            raise typer.Exit(1)
-    else:
-        checks = CheckRegistry.list_checks()
-
-    if _cli_state.get("json_only"):
-        result: dict[str, Any] = {"checks": [], "count": len(checks)}
-        for check_name in checks:
-            check_metadata = CheckRegistry.get_metadata(check_name)
-            if check_metadata:
-                check_data = check_metadata.to_dict()
-                check_data["registered"] = check_name in CheckRegistry._checks
-                result["checks"].append(check_data)
-            else:
-                result["checks"].append(
-                    {
-                        "check_type": check_name,
-                        "registered": True,
-                    }
-                )
-        if category:
-            result["category"] = category
-        result["summary"] = CheckRegistry.get_summary()
-        _emit_json(result)
-        return
-
-    # Summary table
-    summary = CheckRegistry.get_summary()
-    console.print(f"[bold]Available Checks ({len(checks)}):[/bold]")
-    console.print(f"Categories: {', '.join(summary['categories'])}\n")
-
-    # Group by category
-    categories = CheckRegistry.get_categories()
-    for cat in categories:
-        cat_checks = CheckRegistry.list_checks_by_category(cat)
-        if category and cat != category:
-            continue
-        if not cat_checks:
-            continue
-
-        console.print(f"[bold cyan]{cat.upper()}[/bold cyan] ({len(cat_checks)} checks)")
-
-        if detailed:
-            for check_name in cat_checks:
-                check_metadata = CheckRegistry.get_metadata(check_name)
-                if check_metadata:
-                    # Severity color
-                    severity_colors = {
-                        "Critical": "red",
-                        "High": "bright_red",
-                        "Medium": "yellow",
-                        "Low": "blue",
-                        "Info": "dim",
-                    }
-                    sev_color = severity_colors.get(check_metadata.default_severity.value, "white")
-
-                    console.print(f"  [bold green]{check_name}[/bold green]")
-                    console.print(f"    Name: {check_metadata.name}")
-                    console.print(f"    Description: {check_metadata.description}")
-                    console.print(f"    Severity: [{sev_color}]{check_metadata.default_severity.value}[/{sev_color}]")
-                    if check_metadata.tags:
-                        console.print(f"    Tags: {', '.join(check_metadata.tags)}")
-
-                    # Config schema
-                    if check_metadata.config_schema:
-                        console.print("    Configuration:")
-                        for param, schema in check_metadata.config_schema.items():
-                            required = "[red]*[/red]" if schema.get("required") else ""
-                            console.print(f"      - {param}{required} ({schema.get('type', 'any')})")
-                            if schema.get("description"):
-                                console.print(f"        {schema['description']}")
-                    console.print()
-        else:
-            for check_name in cat_checks:
-                check_metadata = CheckRegistry.get_metadata(check_name)
-                desc = check_metadata.description if check_metadata else ""
-                console.print(f"  [bold green]{check_name}[/bold green]: {desc}")
-        console.print()
-
-
-# ---------------------------------------------------------------------------
-# Template validation helpers
-# ---------------------------------------------------------------------------
-
-
-@dataclass
-class TemplateValidationResult:
-    """Result of template validation."""
-
-    valid: bool = False
-    template_name: str | None = None
-    template_version: str | None = None
-    section_count: int = 0
-    check_count: int = 0
-    errors: list[str] = field(default_factory=list)
-    warnings: list[str] = field(default_factory=list)
-
-    def to_dict(self) -> dict[str, Any]:
-        """Convert to dictionary for JSON output."""
-        return {
-            "valid": self.valid,
-            "template_name": self.template_name,
-            "template_version": self.template_version,
-            "section_count": self.section_count,
-            "check_count": self.check_count,
-            "errors": self.errors,
-            "warnings": self.warnings,
-        }
-
-
-def _validate_template_weights(template: Any) -> tuple[list[str], list[str]]:
-    """Validate template weights and return errors/warnings."""
-    errors: list[str] = []
-    warnings: list[str] = []
-
-    if not template.sections:
-        warnings.append("Template has no sections defined")
-        return errors, warnings
-
-    # Check section weights sum to ~100
-    total_section_weight = sum(s.weight for s in template.sections)
-    if abs(total_section_weight - 100.0) > 0.1:
-        warnings.append(f"Section weights sum to {total_section_weight:.1f}, expected 100.0")
-
-    # Check internal section weights
-    for section in template.sections:
-        if not section.checks:
-            warnings.append(f"Section '{section.name}' has no checks defined")
-            continue
-
-        weights = [c.weight for c in section.checks if c.weight is not None]
-        if weights:
-            section_total = sum(weights)
-            if abs(section_total - 100.0) > 0.1:
-                warnings.append(f"Section '{section.name}' check weights sum to {section_total:.1f}, expected 100.0")
-
-    return errors, warnings
-
-
-def _load_template(
-    template: Path | None,
-    template_url: str | None,
-    template_sheet: str | None,
-    template_gid: int | None,
-    template_table_index: int | None,
-    template_map: str | None,
-    gs_auth_method: str | None,
-    gs_credentials_path: Path | None,
-    gs_oauth_credentials_path: Path | None,
-    gs_api_key: str | None,
-) -> Any:
-    """Load template from Excel or Google Sheets."""
-    if template and template_url:
-        raise ValueError("Provide either --template or --template-url (not both)")
-
-    if template:
-        loader = ExcelLoader()
-        return loader.load(template)
-    elif template_url:
-        # Resolve mapping path (supports both file paths and bundled mapping names)
-        mapping_path = resolve_mapping_path(template_map) if template_map else None
-        mapping = load_mapping_file(mapping_path) if mapping_path else None
-        return load_template_from_google_sheet(
-            spreadsheet_url=template_url,
-            sheet_name=template_sheet,
-            sheet_gid=template_gid,
-            doc_table_index=template_table_index,
-            template_map=mapping,
-            auth_method=gs_auth_method,
-            credentials_path=gs_credentials_path,
-            oauth_credentials_path=gs_oauth_credentials_path,
-            api_key=gs_api_key,
-        )
-    else:
-        raise ValueError("Must provide either --template or --template-url")
-
-
-# ---------------------------------------------------------------------------
-# validate-template
-# ---------------------------------------------------------------------------
-
-
-@app.command(name="validate-template")
-def validate_template(
-    template: Path | None = typer.Option(None, "--template", "-t", help="Path to Excel template", exists=True),
-    template_url: str | None = typer.Option(
-        None,
-        "--template-url",
-        "--google-sheet",
-        "-g",
-        help="Google Sheet URL for rubric-style template",
-    ),
-    template_sheet: str | None = typer.Option(
-        None,
-        "--template-sheet",
-        "--sheet-name",
-        help="Sheet name in Google Sheet",
-    ),
-    template_gid: int | None = typer.Option(
-        None,
-        "--template-gid",
-        "--sheet-gid",
-        help="Sheet GID in Google Sheet",
-    ),
-    template_table_index: int | None = typer.Option(
-        None,
-        "--template-table-index",
-        help="Google Docs table index (0-based)",
-    ),
-    template_map: Path | None = typer.Option(
-        None,
-        "--template-map",
-        help="Optional JSON mapping file for rubric-style sheets",
-        exists=True,
-    ),
-    gs_auth_method: str | None = typer.Option(None, "--gs-auth-method", help="Google Sheets auth method"),
-    gs_credentials_path: Path | None = typer.Option(
-        None, "--gs-credentials-path", help="Google Sheets service account credentials path"
-    ),
-    gs_oauth_credentials_path: Path | None = typer.Option(
-        None, "--gs-oauth-credentials-path", help="Google Sheets OAuth credentials path"
-    ),
-    gs_api_key: str | None = typer.Option(None, "--gs-api-key", help="Google Sheets API key"),
-) -> None:
-    """Validate an audit template without running an audit.
-
-    Checks template syntax, weight sums, and check definitions.
-    Use this command to verify templates before running audits.
-    """
-    json_only = _cli_state.get("json_only", False)
-    result = TemplateValidationResult()
-
-    # Validate input arguments
-    if template and template_url:
-        error_msg = "Provide either --template or --template-url (not both)"
-        if json_only:
-            result.errors.append(error_msg)
-            _emit_json(result.to_dict())
-        else:
-            console.print(f"[red]Error:[/red] {error_msg}")
-        raise typer.Exit(1)
-
-    if not template and not template_url:
-        error_msg = "Must provide either --template or --template-url"
-        if json_only:
-            result.errors.append(error_msg)
-            _emit_json(result.to_dict())
-        else:
-            console.print(f"[red]Error:[/red] {error_msg}")
-        raise typer.Exit(1)
-
-    # Load template with progress indicator
-    try:
-        if not json_only:
-            with Progress(
-                SpinnerColumn(),
-                TextColumn("[progress.description]{task.description}"),
-                transient=True,
-            ) as progress:
-                progress.add_task("Loading template...", total=None)
-                audit_template = _load_template(
-                    template=template,
-                    template_url=template_url,
-                    template_sheet=template_sheet,
-                    template_gid=template_gid,
-                    template_table_index=template_table_index,
-                    template_map=str(template_map) if template_map else None,
-                    gs_auth_method=gs_auth_method,
-                    gs_credentials_path=gs_credentials_path,
-                    gs_oauth_credentials_path=gs_oauth_credentials_path,
-                    gs_api_key=gs_api_key,
-                )
-        else:
-            audit_template = _load_template(
-                template=template,
-                template_url=template_url,
-                template_sheet=template_sheet,
-                template_gid=template_gid,
-                template_table_index=template_table_index,
-                template_map=str(template_map) if template_map else None,
-                gs_auth_method=gs_auth_method,
-                gs_credentials_path=gs_credentials_path,
-                gs_oauth_credentials_path=gs_oauth_credentials_path,
-                gs_api_key=gs_api_key,
-            )
-
-    except (OSError, RuntimeError, TypeError, ValueError) as e:
-        _log_hardened_path_error(
-            "validate_template_load_failed",
-            e,
-            context=f"template={template}, template_url={template_url}",
-            recovery_action="emit_cli_error_and_exit",
-            level="exception",
-        )
-        error_msg = f"Failed to load template: {e}"
-        if json_only:
-            result.errors.append(error_msg)
-            _emit_json(result.to_dict())
-        else:
-            console.print(f"[red]Error:[/red] {error_msg}")
-            logger.exception("Template load failed")
-        raise typer.Exit(1) from e
-
-    # Populate result metadata
-    result.template_name = getattr(audit_template, "name", None)
-    result.template_version = getattr(audit_template, "version", None)
-    result.section_count = len(audit_template.sections) if audit_template.sections else 0
-    result.check_count = sum(len(s.checks) for s in audit_template.sections) if audit_template.sections else 0
-
-    # Run validator
-    validator = TemplateValidator()
-    try:
-        validator.validate(audit_template)
-    except TemplateValidationError as e:
-        result.errors.append(str(e))
-
-    # Check weight sums
-    weight_errors, weight_warnings = _validate_template_weights(audit_template)
-    result.errors.extend(weight_errors)
-    result.warnings.extend(weight_warnings)
-
-    # Determine validity
-    result.valid = len(result.errors) == 0
-
-    # Output results
-    if json_only:
-        _emit_json(result.to_dict())
-    else:
-        if result.valid:
-            console.print("[green]Template is valid.[/green]")
-        else:
-            console.print("[red]Template validation failed.[/red]")
-
-        # Template info table
-        info_table = Table(title="Template Info", show_header=False)
-        info_table.add_column("Property", style="bold")
-        info_table.add_column("Value")
-        info_table.add_row("Name", result.template_name or "(not set)")
-        info_table.add_row("Version", result.template_version or "(not set)")
-        info_table.add_row("Sections", str(result.section_count))
-        info_table.add_row("Checks", str(result.check_count))
-        console.print(info_table)
-
-    # Errors
-    if result.errors:
-        console.print("\n[bold red]Errors:[/bold red]")
-        for error in result.errors:
-            console.print(f"  [red]x[/red] {error}")
-
-    # Warnings
-    if result.warnings:
-        console.print("\n[bold yellow]Warnings:[/bold yellow]")
-        for warning in result.warnings:
-            console.print(f"  [yellow]![/yellow] {warning}")
-
-    if not result.valid:
-        raise typer.Exit(1)
-
-
-# ---------------------------------------------------------------------------
-# query-checklist
-# ---------------------------------------------------------------------------
-
-
-def _query_checklist_page_id(
-    *,
-    checklist_page: str | None,
-    project_storage_key: str | None,
-    checklist_profile: str | None,
-    state_dsn: str | None,
-) -> tuple[str, dict[str, Any]]:
-    if checklist_page:
-        ref = _parse_confluence_ref(checklist_page)
-        page_id = ref.page_id or checklist_page.strip()
-        return page_id, {"source": "explicit_page", "checklist_profile": checklist_profile}
-
-    resolved_state_dsn = _require_consumer_state_dsn(state_dsn, command="query-checklist")
-    manifest_payload = _load_manifest_payload_from_state(resolved_state_dsn)
-    projects = manifest_payload.get("projects") if isinstance(manifest_payload, dict) else []
-    if not isinstance(projects, list):
-        raise typer.BadParameter("Centralized state payload is missing 'projects' entries.")
-    if not project_storage_key:
-        raise typer.BadParameter("Provide either --checklist-page or --project-storage-key.")
-    project_payload = select_project([p for p in projects if isinstance(p, dict)], project_storage_key)
-    repo_type = None
-    bitbucket_entries = project_payload.get("bitbucket")
-    if isinstance(bitbucket_entries, list) and bitbucket_entries:
-        first_repo = bitbucket_entries[0] if isinstance(bitbucket_entries[0], dict) else {}
-        repo_type = str(first_repo.get("repo_type") or "").strip() or None
-    bootstrap = resolve_checklist_profile(
-        explicit_page_id=None,
-        explicit_profile=checklist_profile,
-        repo_type=repo_type,
-        state_dsn=resolved_state_dsn,
-        state_registry_loader=_load_manifest_payload_from_state,
-    )
-    return bootstrap.page_id, {
-        "source": bootstrap.source,
-        "checklist_profile": bootstrap.profile_id,
-        "project_storage_key": project_storage_key,
-    }
-
-
-@app.command(name="query-checklist")
-def query_checklist(
-    checklist_page: str | None = typer.Option(None, "--checklist-page", help="Explicit checklist page ID or URL."),
-    project_storage_key: str | None = typer.Option(
-        None, "--project-storage-key", help="Project storage key used for checklist bootstrap resolution."
-    ),
-    checklist_profile: str | None = typer.Option(
-        None, "--checklist-profile", help="Optional checklist profile identifier for bootstrap resolution."
-    ),
-    target: str | None = typer.Option(
-        None,
-        "--target",
-        help="Reuse workflow-style row selector semantics (row index, check id, row key, or content query). Canonical CL-* check-id matching is best-effort because source checklist pages may only expose parser-local ids unless canonical aliases are present.",
-    ),
-    category: str | None = typer.Option(None, "--category", help="Filter rows by requirement_category or section_id."),
-    summary_only: bool = typer.Option(False, "--summary-only", help="Return checklist summary without row payloads."),
-    state_dsn: str | None = typer.Option(
-        None, "--state-dsn", envvar=_STATE_DSN_ENV_VAR, help=f"Centralized state DSN (fallback: {_STATE_DSN_ENV_VAR})."
-    ),
-    confluence_server: str | None = typer.Option(
-        None,
-        "--confluence-server",
-        help="Confluence server key: internal|external. If omitted, inferred from page URL when possible.",
-    ),
-) -> None:
-    """Query source checklist content directly without running workflow evaluation."""
-    if not checklist_page and not project_storage_key:
-        raise typer.BadParameter("Provide either --checklist-page or --project-storage-key.")
-
-    inferred_server = _parse_confluence_ref(checklist_page).server if checklist_page else None
-    client = ConfluenceCliClient.for_registry_discovery(server=confluence_server or inferred_server)
-    page_id, query_meta = _query_checklist_page_id(
-        checklist_page=checklist_page,
-        project_storage_key=project_storage_key,
-        checklist_profile=checklist_profile,
-        state_dsn=state_dsn,
-    )
-    parser = ChecklistParser(client)
-    template = asyncio.run(parser.parse_checklist(page_id))
-    if template is None:
-        raise typer.BadParameter(f"Checklist page '{page_id}' could not be parsed.")
-
-    result = query_checklist_template(
-        template,
-        filters=ChecklistQueryFilters(target=target, category=category, summary_only=summary_only),
-    )
-    payload = {
-        "checklist_page_id": page_id,
-        "template_name": result.template_name,
-        "template_version": result.template_version,
-        "total_rows": result.total_rows,
-        "returned_rows": result.returned_rows,
-        "target": result.target,
-        "category": result.category,
-        "query_meta": query_meta,
-        "rows": [row.__dict__ for row in result.rows],
-    }
-    if _cli_state.get("json_only"):
-        _emit_json(payload)
-        return
-
-    console.print(f"[bold]Checklist:[/bold] {result.template_name} (page {page_id})")
-    console.print(f"Rows returned: {result.returned_rows} / {result.total_rows}")
-    if category:
-        console.print(f"Category filter: {category}")
-    if target:
-        console.print(f"Target filter: {target}")
-    if summary_only:
-        return
-    for row in result.rows:
-        console.print(
-            f"- [{row.row_index + 1}] {row.row_id} | {row.check_id or '-'} | {row.requirement_category or row.section_id or '-'} | {row.description}"
-        )
-
-
-# ---------------------------------------------------------------------------
-# validate-checklist
-# ---------------------------------------------------------------------------
-
-
-@app.command(name="validate-checklist")
-def validate_checklist(
-    checklist_json: Path | None = typer.Option(
-        None,
-        "--checklist-json",
-        help="Path to audit-checklist.json. Defaults to <report-dir>/audit-checklist.json.",
-    ),
-    report_dir: Path = typer.Option(
-        Path(),
-        "--report-dir",
-        help="Directory that contains checklist artifacts.",
-    ),
-    checklist_xlsx: Path | None = typer.Option(
-        None,
-        "--checklist-xlsx",
-        help="Path to audit-checklist.xlsx. Defaults to <report-dir>/audit-checklist.xlsx.",
-    ),
-    require_xlsx: bool = typer.Option(
-        False,
-        "--require-xlsx/--no-require-xlsx",
-        help="Require <report-dir>/audit-checklist.xlsx to exist.",
-    ),
-    emit_metadata: bool = typer.Option(
-        True,
-        "--emit-metadata/--no-emit-metadata",
-        help="Write deterministic validation metadata to <report-dir>/audit-checklist.validation.json.",
-    ),
-) -> None:
-    """Validate canonical checklist artifacts (audit-checklist.json/xlsx)."""
-    json_only = _cli_state.get("json_only", False)
-    resolved_report_dir = report_dir.resolve()
-    resolved_report_dir.mkdir(parents=True, exist_ok=True)
-    resolved_checklist_json = (
-        checklist_json.resolve() if checklist_json else (resolved_report_dir / "audit-checklist.json")
-    )
-    resolved_checklist_xlsx = (
-        checklist_xlsx.resolve() if checklist_xlsx else (resolved_report_dir / "audit-checklist.xlsx")
-    )
-
-    errors: list[str] = []
-    warnings_list: list[str] = []
-    checklist: AuditChecklist | None = None
-
-    if not resolved_checklist_json.exists():
-        errors.append(f"Checklist JSON not found: {resolved_checklist_json}")
-    else:
-        try:
-            checklist = AuditChecklist.model_validate_json(resolved_checklist_json.read_text(encoding="utf-8"))
-        except (OSError, TypeError, ValueError) as exc:
-            _log_hardened_path_error(
-                "validate_checklist_json_parse_failed",
-                exc,
-                context=f"checklist_json={resolved_checklist_json}",
-                recovery_action="append_validation_error_and_continue",
-            )
-            errors.append(f"Invalid checklist JSON schema/content: {exc}")
-
-    if checklist is not None and not checklist.validate_row_count():
-        errors.append(
-            f"Row count mismatch: template_row_count={checklist.template_row_count}, actual_rows={len(checklist.rows)}"
-        )
-
-    if require_xlsx and not resolved_checklist_xlsx.exists():
-        errors.append(f"Checklist XLSX not found: {resolved_checklist_xlsx}")
-    elif not require_xlsx and not resolved_checklist_xlsx.exists():
-        warnings_list.append(f"Checklist XLSX not found (optional): {resolved_checklist_xlsx}")
-    elif resolved_checklist_xlsx.exists():
-        from vds_audit_orchestrator.validators.checklist_validator import ChecklistValidator
-
-        xlsx_validation = ChecklistValidator().validate_excel(resolved_checklist_xlsx)
-        if not xlsx_validation.valid:
-            for item in xlsx_validation.errors:
-                loc = f" row={item.row}" if item.row else ""
-                col = f" column={item.column}" if item.column else ""
-                errors.append(f"[{item.code}]{loc}{col} {item.message}")
-
-    payload: dict[str, Any] = {
-        "valid": len(errors) == 0,
-        "checklist_json": str(resolved_checklist_json),
-        "checklist_xlsx": str(resolved_checklist_xlsx),
-        "require_xlsx": require_xlsx,
-        "errors": errors,
-        "warnings": warnings_list,
-        "validated_at": datetime.now(UTC).isoformat(),
-    }
-    if checklist is not None:
-        payload["summary"] = {
-            "template_name": checklist.template_name,
-            "template_version": checklist.template_version,
-            "template_row_count": checklist.template_row_count,
-            "total_rows": checklist.total_rows,
-            "overall_score": checklist.overall_score,
-            "overall_score_1_5": checklist.overall_score_1_5,
-            "status_counts": {
-                "pass": checklist.pass_count,
-                "partial": checklist.partial_count,
-                "fail": checklist.fail_count,
-                "na": checklist.na_count,
-                "error": checklist.error_count,
-            },
-            "stability_flags": checklist.stability_flags,
-        }
-    if resolved_checklist_xlsx.exists():
-        payload["xlsx_validated"] = True
-
-    if emit_metadata:
-        metadata_path = resolved_report_dir / "audit-checklist.validation.json"
-        metadata_path.write_text(json.dumps(payload, indent=2, ensure_ascii=False, default=str), encoding="utf-8")
-        payload["metadata_path"] = str(metadata_path)
-
-    if json_only:
-        _emit_json(payload)
-    else:
-        if payload["valid"]:
-            console.print("[green]Checklist validation passed.[/green]")
-        else:
-            console.print("[red]Checklist validation failed.[/red]")
-        if payload.get("errors"):
-            for err in errors:
-                console.print(f"[red]- {err}[/red]")
-        if payload.get("warnings"):
-            for warning in warnings_list:
-                console.print(f"[yellow]- {warning}[/yellow]")
-
-    if errors:
-        raise typer.Exit(1)
-
-
-# ---------------------------------------------------------------------------
-# validate-spec-sync helpers
-# ---------------------------------------------------------------------------
-
-
-def _has_required_spec_sync_files(specs_dir: Path) -> bool:
-    candidate = specs_dir.resolve()
-    has_separated = all((candidate / name).exists() for name in ("requirements.md", "design.md", "tasks.md"))
-    has_unified = (candidate / "spec.md").exists()
-    return candidate.exists() and (has_separated or has_unified)
-
-
-def _resolve_validate_spec_sync_paths(specs_dir: Path, agents_file: Path) -> tuple[Path, Path]:
-    """Resolve spec + AGENTS paths with parent-directory auto-discovery for defaults."""
-    default_specs_dir = Path(".kiro/specs/audit-orchestrator")
-    default_agents_file = Path("AGENTS.md")
-    cwd = Path.cwd().resolve()
-
-    if specs_dir == default_specs_dir:
-        direct_specs_dir = (cwd / specs_dir).resolve()
-        if _has_required_spec_sync_files(direct_specs_dir):
-            resolved_specs_dir = direct_specs_dir
-        else:
-            resolved_specs_dir = direct_specs_dir
-            for parent in (cwd, *cwd.parents):
-                for root_name in (".gpt-5.4", ".kiro"):
-                    candidate = (parent / root_name / "specs" / "audit-orchestrator").resolve()
-                    if _has_required_spec_sync_files(candidate):
-                        resolved_specs_dir = candidate
-                        break
-                if _has_required_spec_sync_files(resolved_specs_dir):
-                    break
-    else:
-        resolved_specs_dir = specs_dir.resolve()
-
-    # Always try direct resolution first, then parent-directory walk for known
-    # agent-file names (AGENTS.md, CLAUDE.md, copilot-instructions.md).
-    # This handles the current default (AGENTS.md) plus legacy explicit filenames
-    # when CWD is a subdirectory of the repo root.
-    _KNOWN_AGENTS_FILENAMES: tuple[str, ...] = ("AGENTS.md", "CLAUDE.md", ".github/copilot-instructions.md")
-    direct_agents = (cwd / agents_file).resolve()
-    if direct_agents.exists():
-        resolved_agents_file = direct_agents
-    else:
-        resolved_agents_file = direct_agents
-        # Walk parent directories looking for the file by its basename or known variants
-        search_names: list[str] = [agents_file.name]
-        if agents_file == default_agents_file:
-            # Default mode: also try other known filenames
-            search_names = list(dict.fromkeys([agents_file.name, *_KNOWN_AGENTS_FILENAMES]))
-        for parent in (cwd, *cwd.parents):
-            for filename in search_names:
-                candidate = (parent / filename).resolve()
-                if candidate.exists():
-                    resolved_agents_file = candidate
-                    break
-            if resolved_agents_file.exists():
-                break
-
-    return resolved_specs_dir, resolved_agents_file
-
-
-# ---------------------------------------------------------------------------
-# validate-spec-sync
-# ---------------------------------------------------------------------------
-
-
-@app.command(name="validate-spec-sync")
-def validate_spec_sync_command(
-    specs_dir: Path = typer.Option(
-        Path(".kiro/specs/audit-orchestrator"),
-        "--specs-dir",
-        help="Directory containing requirements.md, design.md, and tasks.md.",
-    ),
-    agents_file: Path = typer.Option(
-        Path("AGENTS.md"),
-        "--agents-file",
-        help="Path to AGENTS.md to validate against the spec files.",
-    ),
-) -> None:
-    """Validate spec sync across the triplet headers, baseline count, and agent instructions file."""
-    resolved_specs_dir, resolved_agents = _resolve_validate_spec_sync_paths(specs_dir, agents_file)
-    requirements_path = (resolved_specs_dir / "requirements.md").resolve()
-    design_path = (resolved_specs_dir / "design.md").resolve()
-    tasks_path = (resolved_specs_dir / "tasks.md").resolve()
-    spec_path = (resolved_specs_dir / "spec.md").resolve()
-
-    if spec_path.exists():
-        result = validate_spec_sync(
-            spec_path=spec_path,
-            agents_path=resolved_agents,
-        )
-    else:
-        result = validate_spec_sync(
-            requirements_path=requirements_path,
-            design_path=design_path,
-            tasks_path=tasks_path,
-            agents_path=resolved_agents,
-        )
-    payload = result.to_payload()
-
-    if _cli_state.get("json_only"):
-        _emit_json(payload)
-    elif payload["valid"]:
-        console.print("[green]Spec sync validation passed.[/green]")
-    else:
-        console.print("[red]Spec sync validation failed.[/red]")
-        for error in payload["errors"]:
-            console.print(f"[red]- {error}[/red]")
-
-    if not payload["valid"]:
-        raise typer.Exit(1)
-
-
-# ---------------------------------------------------------------------------
-# Template analysis helpers
-# ---------------------------------------------------------------------------
-
-
-def _build_template_criteria(audit_template: Any) -> list[dict[str, Any]]:
-    criteria: list[dict[str, Any]] = []
-    for section in audit_template.sections:
-        for check in section.checks:
-            criteria.append(
-                {
-                    "rule": check.id,
-                    "group": section.name,
-                    "check_text": check.description,
-                    "notes": check.remediation_steps or "",
-                }
-            )
-    return criteria
-
-
-def _expected_evidence_text(reqs: list[EvidenceRequirement]) -> str:
-    parts = []
-    for req in reqs:
-        label = req.source
-        if req.path_pattern:
-            label = f"{label}:{req.path_pattern}"
-        elif req.page_title_pattern:
-            label = f"{label}:{req.page_title_pattern}"
-        parts.append(label)
-    return ", ".join(parts) if parts else "evidence required"
-
-
-def _map_requirement_dict(req: dict[str, Any]) -> EvidenceRequirement:
-    return EvidenceRequirement(
-        source=req.get("source", "git_file"),
-        path_pattern=req.get("path_pattern"),
-        page_title_pattern=req.get("page_title_pattern"),
-        required_sections=req.get("required_sections", []),
-        required_keywords=[],
-        min_content_length=0,
-        max_age_days=None,
-        weight=1.0,
-        critical=bool(req.get("critical", False)),
-    )
-
-
-def _matches_requirement(req: EvidenceRequirement, evidence: Evidence) -> bool:
-    if req.source and evidence.source != req.source:
-        return False
-    if req.path_pattern:
-        return fnmatch(evidence.source_id, req.path_pattern)
-    if req.page_title_pattern:
-        needle = req.page_title_pattern.lower()
-        return needle in (evidence.title or "").lower() or needle in (evidence.source_id or "").lower()
-    return True
-
-
-def _analysis_results_to_requirements(
-    analysis_results: list[dict[str, Any]],
-) -> tuple[dict[str, list[EvidenceRequirement]], list[dict[str, Any]], list[EvidenceRequirement]]:
-    per_check_requirements: dict[str, list[EvidenceRequirement]] = {}
-    checks: list[dict[str, Any]] = []
-    all_requirements: list[EvidenceRequirement] = []
-
-    for item in analysis_results:
-        if not isinstance(item, dict):
-            continue
-        check_id = item.get("rule") or item.get("check_id") or ""
-        if not check_id:
-            continue
-        reqs = [_map_requirement_dict(req) for req in item.get("evidence_requirements", []) if isinstance(req, dict)]
-        per_check_requirements[check_id] = reqs
-        all_requirements.extend(reqs)
-        checks.append(
-            {
-                "id": check_id,
-                "criterion": item.get("check_text", ""),
-                "expected_evidence": _expected_evidence_text(reqs),
-            }
-        )
-
-    return per_check_requirements, checks, all_requirements
-
-
-def _analysis_results_to_check_configs(
-    analysis_results: list[dict[str, Any]],
-    repo_name: str | None = None,
-) -> list[dict[str, Any]]:
-    def _first_requirement(reqs: list[dict[str, Any]], source: str) -> dict[str, Any] | None:
-        for req in reqs:
-            if isinstance(req, dict) and req.get("source") == source:
-                return req
-        return None
-
-    configs: list[dict[str, Any]] = []
-    for item in analysis_results:
-        if not isinstance(item, dict):
-            continue
-        check_id = item.get("rule") or item.get("check_id") or ""
-        if not check_id:
-            continue
-        check_type = item.get("check_type") or "llm_content_evaluation"
-        reqs = item.get("evidence_requirements", [])
-        if not isinstance(reqs, list):
-            reqs = []
-
-        check_config: dict[str, Any] = {}
-        if check_type in {"git_file_exists", "git_file_content"}:
-            req = _first_requirement(reqs, "git_file")
-            if req:
-                path_pattern = req.get("path_pattern")
-                if path_pattern:
-                    check_config["path"] = path_pattern
-                if check_type == "git_file_content":
-                    sections = req.get("required_sections") or []
-                    if sections:
-                        check_config["contains"] = sections[0]
-        elif check_type == "confluence_page_exists":
-            req = _first_requirement(reqs, "confluence_page")
-            if req:
-                title = req.get("page_title_pattern") or req.get("path_pattern")
-                if title:
-                    check_config["title"] = title
-        elif check_type.startswith("sonarqube") and repo_name:
-            check_config["project_key"] = repo_name
-
-        configs.append(
-            {
-                "check_id": check_id,
-                "check_type": check_type,
-                "check_config": check_config,
-                "applicability": item.get("applicability"),
-                "gap_severity_if_missing": item.get("gap_severity_if_missing"),
-                "gap_category": item.get("gap_category"),
-                "evidence_requirements": reqs,
-                "notes": item.get("notes") or "",
-                "check_text": item.get("check_text") or "",
-            }
-        )
-    return configs
-
-
-# ---------------------------------------------------------------------------
-# analyze-template
-# ---------------------------------------------------------------------------
-
-
-@app.command(name="analyze-template")
-def analyze_template(
-    template: Path | None = typer.Option(None, "--template", "-t", help="Path to Excel template", exists=True),
-    template_url: str | None = typer.Option(
-        None,
-        "--template-url",
-        "--google-sheet",
-        "-g",
-        help="Google Sheet or Doc URL for rubric-style template",
-    ),
-    template_sheet: str | None = typer.Option(
-        None,
-        "--template-sheet",
-        "--sheet-name",
-        help="Sheet name in Google Sheet",
-    ),
-    template_gid: int | None = typer.Option(
-        None,
-        "--template-gid",
-        "--sheet-gid",
-        help="Sheet GID in Google Sheet",
-    ),
-    template_table_index: int | None = typer.Option(
-        None,
-        "--template-table-index",
-        help="Table index for Google Docs templates (0-based)",
-    ),
-    template_map: Path | None = typer.Option(
-        None,
-        "--template-map",
-        help="Optional JSON mapping file for rubric-style sheets",
-        exists=True,
-    ),
-    project_profile: Path | None = typer.Option(None, "--project-profile", help="Project profile file path"),
-    profile_map: Path | None = typer.Option(None, "--profile-map", help="Profile map rules file path"),
-    repo_path: Path | None = typer.Option(
-        None,
-        "--repo-path",
-        help="Repository path for profile detection (defaults to CWD)",
-    ),
-    llm_enabled: bool | None = typer.Option(
-        None,
-        "--llm/--no-llm",
-        help="Enable or disable LLM analysis for template extraction",
-    ),
-    llm_model: str | None = typer.Option(None, "--llm-model", help="Override LLM model name"),
-    output: Path = typer.Option(
-        Path("template_analysis.json"),
-        "--output",
-        "-o",
-        help="Output path for template analysis JSON",
-    ),
-    check_config_output: Path | None = typer.Option(
-        None,
-        "--check-config-output",
-        help="Optional output path for generated check config JSON",
-    ),
-    gs_auth_method: str | None = typer.Option(None, "--gs-auth-method", help="Google Sheets auth method"),
-    gs_credentials_path: Path | None = typer.Option(
-        None, "--gs-credentials-path", help="Google Sheets service account credentials path"
-    ),
-    gs_oauth_credentials_path: Path | None = typer.Option(
-        None, "--gs-oauth-credentials-path", help="Google Sheets OAuth credentials path"
-    ),
-    gs_api_key: str | None = typer.Option(None, "--gs-api-key", help="Google Sheets API key"),
-) -> None:
-    """Analyze a template and extract evidence requirements."""
-    try:
-        audit_template = _load_template(
-            template=template,
-            template_url=template_url,
-            template_sheet=template_sheet,
-            template_gid=template_gid,
-            template_table_index=template_table_index,
-            template_map=str(template_map) if template_map else None,
-            gs_auth_method=gs_auth_method,
-            gs_credentials_path=gs_credentials_path,
-            gs_oauth_credentials_path=gs_oauth_credentials_path,
-            gs_api_key=gs_api_key,
-        )
-    except (OSError, RuntimeError, TypeError, ValueError) as exc:
-        _log_hardened_path_error(
-            "analyze_template_load_failed",
-            exc,
-            context=f"template={template}, template_url={template_url}",
-            recovery_action="emit_cli_error_and_exit",
-            level="exception",
-        )
-        message = f"Failed to load template: {exc}"
-        if _cli_state.get("json_only"):
-            _emit_json({"error": message})
-        else:
-            console.print(f"[red]{message}[/red]")
-        raise typer.Exit(1) from exc
-
-    repo_root = repo_path.resolve() if repo_path else Path.cwd()
-    if project_profile:
-        profile_resolution = resolve_profile(
-            repo_path=repo_root,
-            project_id=repo_root.name,
-            cli_profile=project_profile,
-            profile_map_path=profile_map,
-        )
-        profile_obj = profile_resolution.profile
-    else:
-        profile_obj = default_profile(project_id=repo_root.name, name=repo_root.name)
-
-    provider = LLMProvider()
-    use_llm = provider.enabled if llm_enabled is None else llm_enabled
-    llm_client = None
-    model_name = llm_model
-    if use_llm:
-        try:
-            llm_client = provider.get_async_client()
-            if not model_name:
-                model_name = provider.get_model("complex")
-        except (OSError, RuntimeError, TypeError, ValueError, LookupError, ImportError) as exc:
-            _log_hardened_path_error(
-                "template_llm_unavailable",
-                exc,
-                context=f"llm_enabled={use_llm}, model_name={model_name}",
-                recovery_action="continue_without_template_llm",
-            )
-
-    criteria = _build_template_criteria(audit_template)
-
-    analyzer = TemplateAnalyzer(llm_client=llm_client, model=model_name)
-    try:
-        results = asyncio.run(analyzer.analyze_template(criteria, profile_obj))
-    except (OSError, RuntimeError, TypeError, ValueError) as exc:
-        _log_hardened_path_error(
-            "analyze_template_execution_failed",
-            exc,
-            context=f"repo_path={repo_root}",
-            recovery_action="emit_cli_error_and_exit",
-            level="exception",
-        )
-        message = f"Template analysis failed: {exc}"
-        if _cli_state.get("json_only"):
-            _emit_json({"error": message})
-        else:
-            console.print(f"[red]{message}[/red]")
-        raise typer.Exit(1) from exc
-
-    payload = {
-        "template": {
-            "name": getattr(audit_template, "name", None),
-            "version": getattr(audit_template, "version", None),
-        },
-        "profile": profile_obj.to_dict() if isinstance(profile_obj, ProjectProfile) else profile_obj,
-        "criteria_count": len(results),
-        "results": [r.model_dump() for r in results],
-    }
-    output_path = output.resolve()
-    output_path.write_text(json.dumps(payload, indent=2, sort_keys=True), encoding="utf-8")
-    check_config_path: Path | None = None
-    if check_config_output is not None:
-        check_configs = _analysis_results_to_check_configs([r.model_dump() for r in results], repo_root.name)
-        check_config_payload = {
-            "template": payload["template"],
-            "profile": payload["profile"],
-            "criteria_count": payload["criteria_count"],
-            "check_configs": check_configs,
-        }
-        check_config_path = check_config_output.resolve()
-        check_config_path.write_text(
-            json.dumps(check_config_payload, indent=2, sort_keys=True),
-            encoding="utf-8",
-        )
-
-    if _cli_state.get("json_only"):
-        _emit_json(payload)
-        return
-
-    console.print(f"[green]Template analysis written to:[/green] {output_path}")
-    if check_config_path is not None:
-        console.print(f"[green]Check config output written to:[/green] {check_config_path}")
-
-
-# ---------------------------------------------------------------------------
-# analyze-gaps
-# ---------------------------------------------------------------------------
-
-
-@app.command(name="analyze-gaps")
-def analyze_gaps(
-    repo_path: Path = typer.Argument(..., help="Repository path to analyze"),
-    template_analysis: Path | None = typer.Option(
-        None,
-        "--template-analysis",
-        help="Path to template analysis JSON (from analyze-template)",
-        exists=True,
-    ),
-    template: Path | None = typer.Option(None, "--template", "-t", help="Path to Excel template", exists=True),
-    template_url: str | None = typer.Option(
-        None,
-        "--template-url",
-        "--google-sheet",
-        "-g",
-        help="Google Sheet or Doc URL for rubric-style template",
-    ),
-    template_sheet: str | None = typer.Option(
-        None,
-        "--template-sheet",
-        "--sheet-name",
-        help="Sheet name in Google Sheet",
-    ),
-    template_gid: int | None = typer.Option(
-        None,
-        "--template-gid",
-        "--sheet-gid",
-        help="Sheet GID in Google Sheet",
-    ),
-    template_table_index: int | None = typer.Option(
-        None,
-        "--template-table-index",
-        help="Table index for Google Docs templates (0-based)",
-    ),
-    template_map: Path | None = typer.Option(
-        None,
-        "--template-map",
-        help="Optional JSON mapping file for rubric-style sheets",
-        exists=True,
-    ),
-    project_profile: Path | None = typer.Option(None, "--project-profile", help="Project profile file path"),
-    profile_map: Path | None = typer.Option(None, "--profile-map", help="Profile map rules file path"),
-    llm_enabled: bool | None = typer.Option(
-        None,
-        "--llm/--no-llm",
-        help="Enable or disable LLM analysis for gap evaluation",
-    ),
-    llm_model: str | None = typer.Option(None, "--llm-model", help="Override LLM model name"),
-    output: Path = typer.Option(
-        Path("gap_analysis.json"),
-        "--output",
-        "-o",
-        help="Output path for gap analysis JSON",
-    ),
-    gs_auth_method: str | None = typer.Option(None, "--gs-auth-method", help="Google Sheets auth method"),
-    gs_credentials_path: Path | None = typer.Option(
-        None, "--gs-credentials-path", help="Google Sheets service account credentials path"
-    ),
-    gs_oauth_credentials_path: Path | None = typer.Option(
-        None, "--gs-oauth-credentials-path", help="Google Sheets OAuth credentials path"
-    ),
-    gs_api_key: str | None = typer.Option(None, "--gs-api-key", help="Google Sheets API key"),
-) -> None:
-    """Analyze gaps for a repository using template analysis + evidence collection."""
-    repo_root = repo_path.resolve()
-    if project_profile:
-        profile_resolution = resolve_profile(
-            repo_path=repo_root,
-            project_id=repo_root.name,
-            cli_profile=project_profile,
-            profile_map_path=profile_map,
-        )
-        profile_obj = profile_resolution.profile
-    else:
-        profile_obj = default_profile(project_id=repo_root.name, name=repo_root.name)
-
-    analysis_payload: dict[str, Any] = {}
-    if template_analysis:
-        analysis_payload = json.loads(template_analysis.read_text(encoding="utf-8"))
-    else:
-        if not template and not template_url:
-            message = "Provide --template-analysis or a template source (--template/--template-url)."
-            if _cli_state.get("json_only"):
-                _emit_json({"error": message})
-            else:
-                console.print(f"[red]{message}[/red]")
-            raise typer.Exit(1)
-
-        audit_template = _load_template(
-            template=template,
-            template_url=template_url,
-            template_sheet=template_sheet,
-            template_gid=template_gid,
-            template_table_index=template_table_index,
-            template_map=str(template_map) if template_map else None,
-            gs_auth_method=gs_auth_method,
-            gs_credentials_path=gs_credentials_path,
-            gs_oauth_credentials_path=gs_oauth_credentials_path,
-            gs_api_key=gs_api_key,
-        )
-
-        provider = LLMProvider()
-        use_llm = provider.enabled if llm_enabled is None else llm_enabled
-        llm_client = None
-        model_name = llm_model
-        if use_llm:
-            try:
-                llm_client = provider.get_client()
-                if not model_name:
-                    model_name = provider.get_model("complex")
-            except (OSError, RuntimeError, TypeError, ValueError, LookupError, ImportError) as exc:
-                _log_hardened_path_error(
-                    "gap_llm_unavailable",
-                    exc,
-                    context=f"llm_enabled={use_llm}, model_name={model_name}",
-                    recovery_action="continue_without_gap_llm",
-                )
-
-        criteria = _build_template_criteria(audit_template)
-
-        analyzer = TemplateAnalyzer(llm_client=llm_client, model=model_name)
-        results = asyncio.run(analyzer.analyze_template(criteria, profile_obj))
-        analysis_payload = {
-            "template": {
-                "name": getattr(audit_template, "name", None),
-                "version": getattr(audit_template, "version", None),
-            },
-            "profile": profile_obj.to_dict() if isinstance(profile_obj, ProjectProfile) else profile_obj,
-            "criteria_count": len(results),
-            "results": [r.model_dump() for r in results],
-        }
-
-    analysis_results = analysis_payload.get("results", [])
-    if not isinstance(analysis_results, list) or not analysis_results:
-        message = "Template analysis results are missing or empty."
-        if _cli_state.get("json_only"):
-            _emit_json({"error": message})
-        else:
-            console.print(f"[red]{message}[/red]")
-        raise typer.Exit(1)
-
-    per_check_requirements, checks, all_requirements = _analysis_results_to_requirements(analysis_results)
-
-    orchestrator = EvidenceOrchestrator(repo_path=repo_root)
-    bundle = asyncio.run(orchestrator.collect_bundle(all_requirements))
-    evidence_map: dict[str, list[Evidence]] = {}
-    for check in checks:
-        check_id = check.get("id", "")
-        reqs = per_check_requirements.get(check_id, [])
-        matched: list[Evidence] = []
-        for evidence in bundle.all_evidence:
-            if any(_matches_requirement(req, evidence) for req in reqs):
-                matched.append(evidence)
-        evidence_map[check_id] = matched
-
-    provider = LLMProvider()
-    use_llm = provider.enabled if llm_enabled is None else llm_enabled
-    gap_llm_client: Any | None = None
-    model_name = llm_model
-    if use_llm:
-        try:
-            gap_llm_client = provider.get_async_client()
-            if not model_name:
-                model_name = provider.get_model("complex")
-        except (OSError, RuntimeError, TypeError, ValueError, LookupError, ImportError) as exc:
-            _log_hardened_path_error(
-                "gap_llm_unavailable",
-                exc,
-                context=f"llm_enabled={use_llm}, model_name={model_name}",
-                recovery_action="continue_without_gap_llm",
-            )
-
-    gap_analyzer = GapAnalyzer(llm_client=gap_llm_client, model=model_name)
-    gap_results_raw = asyncio.run(gap_analyzer.analyze_batch(checks, evidence_map, profile_obj))
-    gap_results = [r for r in gap_results_raw if not isinstance(r, dict)]
-    gaps = [gap for result in gap_results for gap in result.gaps]
-    aligned = [practice for result in gap_results for practice in result.aligned_practices]
-    avg_score = sum(result.score for result in gap_results) / len(gap_results) if gap_results else 0.0
-    overall_score = avg_score * 10.0
-    maturity = MaturityLevel.from_score(avg_score).value
-
-    # Convert LLM findings to domain models
-    from vds_audit_orchestrator.models.gaps import (
-        AlignedPractice,
-        BestPracticeLevel,
-        Gap,
-        GapCategory,
-        GapSeverity,
-    )
-
-    domain_gaps: list[Gap] = []
-    for gap in gaps:
-        # Map string severity/category to Enums with fallback
-        try:
-            sev = GapSeverity(gap.severity.capitalize())
-        except ValueError:
-            sev = GapSeverity.MEDIUM
-
-        try:
-            cat = GapCategory(gap.category.capitalize())
-        except ValueError:
-            cat = GapCategory.COMPLIANCE
-
-        domain_gaps.append(
-            Gap(
-                check_id="llm_gap_analysis",
-                criterion="Repo-level Gap Analysis",
-                description=gap.description,
-                severity=sev,
-                category=cat,
-                expected_evidence="Gap analysis reasoning",
-                actual_status="Identified by LLM",
-                impact_description=f"Gap in {gap.category} affecting {gap.severity} severity",
-                recommendation=gap.recommendation,
-                remediation_effort=gap.remediation_effort,
-                remediation_steps=gap.remediation_steps,
-            )
-        )
-
-    domain_aligned: list[AlignedPractice] = []
-    for practice in aligned:
-        try:
-            level = BestPracticeLevel(practice.best_practice_level.capitalize())
-        except ValueError:
-            level = BestPracticeLevel.GOOD
-
-        domain_aligned.append(
-            AlignedPractice(
-                check_id="llm_gap_analysis",
-                criterion="Repo-level Gap Analysis",
-                description=practice.description,
-                best_practice_level=level,
-                notable_aspects=practice.notable_aspects,
-            )
-        )
-
-    repo_gap = RepoGapAnalysisResult(
-        repository=repo_root.name,
-        gaps=domain_gaps,
-        aligned_practices=domain_aligned,
-        overall_score=overall_score,
-        maturity_level=maturity,
-    )
-    payload = repo_gap.model_dump(mode="json")
-    output_path = output.resolve()
-    output_path.write_text(json.dumps(payload, indent=2, sort_keys=True), encoding="utf-8")
-
-    if _cli_state.get("json_only"):
-        _emit_json(payload)
-        return
-
-    console.print(f"[green]Gap analysis written to:[/green] {output_path}")
-
-
-# ---------------------------------------------------------------------------
-# export-template
-# ---------------------------------------------------------------------------
-
-
-@app.command(name="export-template")
-def export_template(
-    template_url: str | None = typer.Option(
-        None,
-        "--template-url",
-        "--google-sheet",
-        "-g",
-        help="Google Sheet or Doc URL for rubric-style template",
-    ),
-    template_sheet: str | None = typer.Option(
-        None,
-        "--template-sheet",
-        "--sheet-name",
-        help="Sheet name in Google Sheet",
-    ),
-    template_gid: int | None = typer.Option(
-        None,
-        "--template-gid",
-        "--sheet-gid",
-        help="Sheet GID in Google Sheet",
-    ),
-    template_table_index: int | None = typer.Option(
-        None,
-        "--template-table-index",
-        help="Table index for Google Docs templates (0-based)",
-    ),
-    template_map: Path | None = typer.Option(
-        None,
-        "--template-map",
-        help="Path to mapping JSON for rubric-style template",
-        exists=True,
-    ),
-    output: Path = typer.Option(
-        Path("audit_template.xlsx"),
-        "--output",
-        "-o",
-        help="Output Excel path for the exported template",
-    ),
-    gs_auth_method: str | None = typer.Option(None, "--gs-auth-method", help="Google Sheets auth method"),
-    gs_credentials_path: Path | None = typer.Option(
-        None, "--gs-credentials-path", help="Google Sheets credentials path"
-    ),
-    gs_oauth_credentials_path: Path | None = typer.Option(
-        None, "--gs-oauth-credentials-path", help="Google Sheets OAuth credentials path"
-    ),
-    gs_api_key: str | None = typer.Option(None, "--gs-api-key", help="Google Sheets API key"),
-) -> None:
-    """Export a Google Sheet or Doc template to an Excel workbook."""
-    if not template_url:
-        message = "Must provide --template-url to export a Google template"
-        if _cli_state.get("json_only"):
-            _emit_json({"error": message})
-        else:
-            console.print(f"[red]{message}[/red]")
-        raise typer.Exit(1)
-
-    try:
-        mapping_path = resolve_mapping_path(template_map) if template_map else None
-        mapping = load_mapping_file(mapping_path) if mapping_path else None
-        export_template_from_google_source(
-            output_path=output.resolve(),
-            template_url=template_url,
-            sheet_name=template_sheet,
-            sheet_gid=template_gid,
-            doc_table_index=template_table_index,
-            template_map=mapping,
-            auth_method=gs_auth_method,
-            credentials_path=gs_credentials_path,
-            oauth_credentials_path=gs_oauth_credentials_path,
-            api_key=gs_api_key,
-        )
-    except (OSError, RuntimeError, TypeError, ValueError) as exc:
-        _log_hardened_path_error(
-            "export_template_failed",
-            exc,
-            context=f"template_url={template_url}, output={output}",
-            recovery_action="emit_cli_error_and_exit",
-            level="exception",
-        )
-        message = f"Failed to export template: {exc}"
-        if _cli_state.get("json_only"):
-            _emit_json({"error": message})
-        else:
-            console.print(f"[red]{message}[/red]")
-        raise typer.Exit(1) from exc
-    except (LookupError, ImportError) as exc:
-        _log_hardened_path_error(
-            "export_template_failed_unexpected",
-            exc,
-            context=f"template_url={template_url}, output={output}",
-            recovery_action="emit_cli_error_and_exit",
-            level="exception",
-        )
-        message = f"Failed to export template: {exc}"
-        if _cli_state.get("json_only"):
-            _emit_json({"error": message})
-        else:
-            console.print(f"[red]{message}[/red]")
-        raise typer.Exit(1) from exc
-
-    payload = {"output": str(output.resolve()), "source": template_url}
-    if _cli_state.get("json_only"):
-        _emit_json(payload)
-    else:
-        console.print(f"[green]Template exported to:[/green] {output.resolve()}")
-
-
-# ---------------------------------------------------------------------------
-# Audit helpers
-# ---------------------------------------------------------------------------
-
-
-async def _run_gap_analysis_for_repo(
-    *,
-    repo_path: Path,
-    audit_template: Any,
-    profile_obj: ProjectProfile,
-    llm_client: Any | None,
-    llm_model: str | None,
-) -> RepoGapAnalysisResult | None:
-    criteria = _build_template_criteria(audit_template)
-    analyzer = TemplateAnalyzer(llm_client=llm_client, model=llm_model)
-    results = await analyzer.analyze_template(criteria, profile_obj)
-    analysis_results = [r.model_dump() for r in results]
-    if not analysis_results:
-        return None
-
-    per_check_requirements, checks, all_requirements = _analysis_results_to_requirements(analysis_results)
-    orchestrator = EvidenceOrchestrator(repo_path=repo_path)
-    bundle = await orchestrator.collect_bundle(all_requirements, profile=profile_obj)
-
-    evidence_map: dict[str, list[Evidence]] = {}
-    for check in checks:
-        check_id = check.get("id", "")
-        reqs = per_check_requirements.get(check_id, [])
-        matched: list[Evidence] = []
-        for evidence in bundle.all_evidence:
-            if any(_matches_requirement(req, evidence) for req in reqs):
-                matched.append(evidence)
-        evidence_map[check_id] = matched
-
-    gap_analyzer = GapAnalyzer(llm_client=llm_client, model=llm_model)
-    gap_results_raw = await gap_analyzer.analyze_batch(checks, evidence_map, profile_obj)
-    gap_results = [r for r in gap_results_raw if not isinstance(r, dict)]
-    gaps = [gap for result in gap_results for gap in result.gaps]
-    aligned = [practice for result in gap_results for practice in result.aligned_practices]
-    avg_score = sum(result.score for result in gap_results) / len(gap_results) if gap_results else 0.0
-    overall_score = avg_score * 10.0
-    maturity = MaturityLevel.from_score(avg_score).value
-
-    return RepoGapAnalysisResult(
-        repository=repo_path.name,
-        gaps=gaps,  # type: ignore[arg-type]
-        aligned_practices=aligned,  # type: ignore[arg-type]
-        overall_score=overall_score,
-        maturity_level=maturity,
-    )
-
-
-def _format_duration(seconds: float) -> str:
-    """Format duration in human-readable format."""
-    if seconds < 60:
-        return f"{seconds:.1f}s"
-    elif seconds < 3600:
-        mins = int(seconds // 60)
-        secs = int(seconds % 60)
-        return f"{mins}m {secs}s"
-    else:
-        hours = int(seconds // 3600)
-        mins = int((seconds % 3600) // 60)
-        return f"{hours}h {mins}m"
-
-
-def _dry_run_output(audit_template: Any, repos: list[Path], profile_obj: ProjectProfile | None) -> None:
-    """Output dry-run preview information."""
-    template_name = getattr(audit_template, "name", None)
-    template_version = getattr(audit_template, "version", None)
-    section_count = len(audit_template.sections) if audit_template.sections else 0
-    check_count = sum(len(s.checks) for s in audit_template.sections) if audit_template.sections else 0
-
-    dry_run_result = {
-        "dry_run": True,
-        "template": {
-            "name": template_name,
-            "version": template_version,
-            "section_count": section_count,
-            "check_count": check_count,
-        },
-        "repositories": [{"name": repo.name, "path": str(repo.resolve())} for repo in repos],
-        "repository_count": len(repos),
-    }
-
-    if profile_obj:
-        dry_run_result["profile"] = profile_obj.model_dump(mode="json")
-
-    if _cli_state.get("json_only"):
-        _emit_json(dry_run_result)
-        return
-
-    console.print("[bold cyan]Dry-run mode:[/bold cyan] No checks will be executed.\n")
-
-    info_table = Table(title="Template Info", show_header=False)
-    info_table.add_column("Property", style="bold")
-    info_table.add_column("Value")
-    info_table.add_row("Name", template_name or "(not set)")
-    info_table.add_row("Version", template_version or "(not set)")
-    info_table.add_row("Sections", str(section_count))
-    info_table.add_row("Checks", str(check_count))
-    console.print(info_table)
-
-    if audit_template.sections:
-        console.print("\n[bold]Sections:[/bold]")
-        for section in audit_template.sections:
-            checks_count = len(section.checks) if section.checks else 0
-            console.print(f"  - {section.name}: {checks_count} checks ({section.weight:.1f}%)")
-
-    if profile_obj:
-        console.print("\n[bold]Detected Profile:[/bold]")
-        console.print(f"  Domain: {profile_obj.domain.value}")
-        console.print(f"  Type: {profile_obj.project_type.value}")
-        console.print(f"  Risk: {profile_obj.risk_level.value}")
-        console.print("  [dim]Source: Profile Detector (confidence: N/A)[/dim]")
-
-    console.print()
-    repo_table = Table(title=f"Repositories to Audit ({len(repos)})")
-    repo_table.add_column("#", style="dim")
-    repo_table.add_column("Repository")
-    repo_table.add_column("Path")
-    for idx, repo in enumerate(repos, 1):
-        repo_table.add_row(str(idx), repo.name, str(repo.resolve()))
-    console.print(repo_table)
-
-    estimated_time = len(repos) * check_count * 0.5
-    console.print(f"\n[green]Would audit {len(repos)} repositories with {check_count} checks.[/green]")
-    console.print(f"[dim]Estimated time: ~{_format_duration(estimated_time)}[/dim]")
-
-
-def _suggest_fix_for_template_error(error: Exception) -> None:
-    """Provide actionable guidance for template errors."""
-    error_str = str(error).lower()
-
-    if "section weights" in error_str:
-        console.print("\n[dim]To fix: Ensure section weights in your template sum to 100.0[/dim]")
-    elif "check" in error_str and "not found" in error_str:
-        console.print("\n[dim]To fix: Use 'vds-audit-orchestrator list-checks' to see available check types[/dim]")
-    elif "file" in error_str or "sheet" in error_str:
-        console.print("\n[dim]To fix: Verify the template file path and format[/dim]")
-    else:
-        console.print("\n[dim]To fix: Use 'vds-audit-orchestrator validate-template' to check your template[/dim]")
-
-
-def _suggest_fix_for_audit_error(error: Exception) -> None:
-    """Provide actionable guidance for audit errors."""
-    error_str = str(error).lower()
-
-    if "permission" in error_str or "access" in error_str:
-        console.print("\n[dim]To fix: Check file/directory permissions and access rights[/dim]")
-    elif "template" in error_str:
-        console.print("\n[dim]To fix: Validate your template with 'vds-audit-orchestrator validate-template'[/dim]")
-    elif "network" in error_str or "connection" in error_str:
-        console.print("\n[dim]To fix: Check network connectivity and API credentials[/dim]")
-    else:
-        console.print("\n[dim]To debug: Run with --verbose flag for more details[/dim]")
-
-
-def _validate_checkpoint(
-    checkpoint: AuditCheckpoint,
-    repo: Path,
-    template: Any,
-) -> None:
-    errors: list[str] = []
-    if checkpoint.template_name and checkpoint.template_name != getattr(template, "name", ""):
-        errors.append(
-            f"template name mismatch (checkpoint={checkpoint.template_name}, template={getattr(template, 'name', '')})"
-        )
-    tpl_version = getattr(template, "version", "")
-    if checkpoint.template_version and checkpoint.template_version != tpl_version:
-        errors.append(f"template version mismatch (checkpoint={checkpoint.template_version}, template={tpl_version})")
-    repo_name = checkpoint.metadata.get("repo_name")
-    if repo_name and repo_name != repo.name:
-        errors.append(f"repository mismatch (checkpoint={repo_name}, repo={repo.name})")
-    if errors:
-        raise ValueError("Checkpoint is incompatible: " + "; ".join(errors))
-
-
-def _create_checkpoint(repo: Path, template: Any, started_at: datetime) -> AuditCheckpoint:
-    return AuditCheckpoint(
-        audit_id=str(uuid4()),
-        template_name=getattr(template, "name", "unknown"),
-        template_version=getattr(template, "version", "unknown"),
-        metadata={
-            "repo_name": repo.name,
-            "repo_path": str(repo),
-            "started_at": started_at.isoformat(),
-        },
-    )
-
-
-# ---------------------------------------------------------------------------
-# audit
-# ---------------------------------------------------------------------------
-
-
-@app.command()
-def audit(
-    repo_path: Path = typer.Argument(..., help="Path to repository or directory of repositories", exists=True),
-    template: Path | None = typer.Option(None, "--template", "-t", help="Path to Excel template", exists=True),
-    template_url: str | None = typer.Option(
-        None,
-        "--template-url",
-        "--google-sheet",
-        "-g",
-        help="Google Sheet URL for rubric-style template",
-    ),
-    template_sheet: str | None = typer.Option(
-        None,
-        "--template-sheet",
-        "--sheet-name",
-        help="Sheet name in Google Sheet",
-    ),
-    template_gid: int | None = typer.Option(
-        None,
-        "--template-gid",
-        "--sheet-gid",
-        help="Sheet GID in Google Sheet",
-    ),
-    template_table_index: int | None = typer.Option(
-        None,
-        "--template-table-index",
-        help="Google Docs table index (0-based)",
-    ),
-    template_map: Path | None = typer.Option(
-        None,
-        "--template-map",
-        help="Optional JSON mapping file for rubric-style sheets",
-        exists=True,
-    ),
-    gs_auth_method: str | None = typer.Option(None, "--gs-auth-method", help="Google Sheets auth method"),
-    gs_credentials_path: Path | None = typer.Option(
-        None, "--gs-credentials-path", help="Google Sheets service account credentials path"
-    ),
-    gs_oauth_credentials_path: Path | None = typer.Option(
-        None, "--gs-oauth-credentials-path", help="Google Sheets OAuth credentials path"
-    ),
-    gs_api_key: str | None = typer.Option(None, "--gs-api-key", help="Google Sheets API key"),
-    project_profile: Path | None = typer.Option(
-        None,
-        "--project-profile",
-        help="Explicit project profile file",
-        exists=True,
-    ),
-    profile_map: Path | None = typer.Option(None, "--profile-map", help="Profile map rules file", exists=True),
-    adaptive_weights: bool = typer.Option(
-        True, "--adaptive-weights/--no-adaptive-weights", help="Enable adaptive weighting"
-    ),
-    gap_analysis: bool = typer.Option(
-        False,
-        "--gap-analysis/--no-gap-analysis",
-        help="Run evidence gap analysis and include results in reports",
-    ),
-    gap_llm: bool | None = typer.Option(
-        None,
-        "--gap-llm/--no-gap-llm",
-        help="Enable or disable LLM usage for gap analysis",
-    ),
-    gap_llm_model: str | None = typer.Option(
-        None,
-        "--gap-llm-model",
-        help="Override LLM model name for gap analysis",
-    ),
-    section_packs: bool = typer.Option(
-        True, "--section-packs/--no-section-packs", help="Enable section pack inclusion/exclusion"
-    ),
-    section_pack: list[str] | None = typer.Option(
-        None, "--section-pack", help="Section pack names to apply (repeatable)"
-    ),
-    baseline: Path | None = typer.Option(
-        None, "--baseline", help="Baseline JSON report for trend indicators", exists=True
-    ),
-    resume: Path | None = typer.Option(None, "--resume", help="Resume from checkpoint file", exists=True),
-    checkpoint: Path | None = typer.Option(None, "--checkpoint", help="Enable checkpointing to specified file"),
-    output: Path | None = typer.Option(None, "--output", "-o", help="Output report path"),
-    concurrency: int = typer.Option(5, "--concurrency", "-c", help="Check concurrency per repo"),
-    dry_run: bool = typer.Option(False, "--dry-run", help="Preview repositories without running checks"),
-) -> None:
-    """Run audit against repositories."""
-    ctx = _get_cli_ctx()
-    started_at = datetime.now(UTC)
-
-    # 1. Load Template
-    try:
-        validator = TemplateValidator()
-
-        if template and template_url:
-            raise ValueError("Provide either --template or --template-url (not both)")
-
-        if template:
-            loader = ExcelLoader()
-            audit_template = loader.load(template)
-        elif template_url:
-            mapping_path = resolve_mapping_path(str(template_map) if template_map else None)
-            mapping = load_mapping_file(mapping_path) if mapping_path else None
-            audit_template = load_template_from_google_sheet(
-                spreadsheet_url=template_url,
-                sheet_name=template_sheet,
-                sheet_gid=template_gid,
-                doc_table_index=template_table_index,
-                template_map=mapping,
-                auth_method=gs_auth_method,
-                credentials_path=gs_credentials_path,
-                oauth_credentials_path=gs_oauth_credentials_path,
-                api_key=gs_api_key,
-            )
-        else:
-            raise ValueError("Must provide either --template or --template-url")
-
-        validator.validate(audit_template)
-    except Exception as e:
-        if _cli_state["json_only"]:
-            _emit_json({"error": str(e)})
-        else:
-            console.print(f"[red]Failed to load template:[/red] {e}")
-            _suggest_fix_for_template_error(e)
-        raise typer.Exit(1) from e
-
-    # 2. Discover Repositories
-    repos = []
-    if (repo_path / ".git").exists():
-        repos = [repo_path]
-    else:
-        repos = [p for p in repo_path.iterdir() if p.is_dir() and (p / ".git").exists()]
-
-    if not repos:
-        if _cli_state["json_only"]:
-            _emit_json({"error": "No repositories found", "guidance": "Ensure the path contains git repositories"})
-        else:
-            console.print("[yellow]No git repositories found.[/yellow]")
-            console.print(
-                "[dim]Hint: Provide a path to a git repository or a directory containing git repositories.[/dim]"
-            )
-        raise typer.Exit(1)
-
-    flags = get_config().features
-    checkpoint_enabled = flags.is_enabled(FeatureFlag.CHECKPOINT_ENABLED)
-    adaptive_weighting_enabled = flags.is_enabled(FeatureFlag.ADAPTIVE_WEIGHTING_ENABLED)
-    if adaptive_weights and not adaptive_weighting_enabled:
-        message = "Adaptive weighting is disabled via feature flags (VDS_AUDIT_ADAPTIVE_WEIGHTING_ENABLED)."
-        if _cli_state["json_only"]:
-            _emit_json({"error": message})
-        else:
-            console.print(f"[red]{message}[/red]")
-        raise typer.Exit(1)
-    if (resume or checkpoint) and not checkpoint_enabled:
-        message = "Checkpoint/resume is disabled via feature flags (VDS_AUDIT_CHECKPOINT_ENABLED)."
-        if _cli_state["json_only"]:
-            _emit_json({"error": message})
-        else:
-            console.print(f"[red]{message}[/red]")
-        raise typer.Exit(1)
-
-    if dry_run and (resume or checkpoint):
-        message = "Checkpoint/resume cannot be used with --dry-run."
-        if _cli_state["json_only"]:
-            _emit_json({"error": message})
-        else:
-            console.print(f"[red]{message}[/red]")
-        raise typer.Exit(1)
-
-    baseline_scores: dict[str, float] = {}
-    if baseline:
-        try:
-            baseline_scores = _load_baseline_scores(baseline)
-        except (OSError, RuntimeError, TypeError, ValueError, LookupError, ImportError) as exc:
-            _log_hardened_path_error(
-                "audit_baseline_load_failed",
-                exc,
-                context=f"baseline={baseline}",
-                recovery_action="emit_cli_error_and_exit",
-                level="exception",
-            )
-            if _cli_state["json_only"]:
-                _emit_json({"error": f"Failed to read baseline: {exc}"})
-            else:
-                console.print(f"[red]Failed to read baseline:[/red] {exc}")
-            raise typer.Exit(1) from exc
-
-    # 3. Dry-run mode - preview without executing checks
-    if dry_run:
-        profile_obj = None
-        try:
-            resolution = resolve_profile(
-                repo_path=repos[0],
-                project_id=repos[0].name,
-                cli_profile=project_profile,
-                profile_map_path=profile_map,
-            )
-            profile_obj = resolution.profile
-        except (OSError, RuntimeError, TypeError, ValueError, LookupError, ImportError) as exc:
-            _log_hardened_path_error(
-                "profile_detection_failed_dry_run",
-                exc,
-                context=f"repo={repos[0]}, profile_map={profile_map}",
-                recovery_action="continue_with_default_profile_preview",
-            )
-        _dry_run_output(audit_template, repos, profile_obj)
-        raise typer.Exit(0)
-
-    gap_llm_client = None
-    gap_model_name = gap_llm_model
-    if gap_analysis:
-        provider = LLMProvider()
-        use_llm = provider.enabled if gap_llm is None else gap_llm
-        if use_llm:
-            try:
-                gap_llm_client = provider.get_client()
-                if not gap_model_name:
-                    gap_model_name = provider.get_model("complex")
-            except (OSError, RuntimeError, TypeError, ValueError, LookupError, ImportError) as exc:
-                _log_hardened_path_error(
-                    "gap_llm_unavailable",
-                    exc,
-                    context=f"llm_enabled={use_llm}, model_name={gap_model_name}",
-                    recovery_action="continue_without_gap_llm",
-                )
-
-    checkpoint_plan: dict[Path, tuple[AuditCheckpoint | None, Path | None]] = {}
-    checkpoint_paths: list[Path] = []
-    if resume or checkpoint:
-        if len(repos) > 1:
-            if resume and resume.is_file():
-                message = "When auditing multiple repositories, --resume must point to a directory of checkpoints."
-                if _cli_state["json_only"]:
-                    _emit_json({"error": message})
-                else:
-                    console.print(f"[red]{message}[/red]")
-                raise typer.Exit(1)
-            if checkpoint and checkpoint.exists() and checkpoint.is_file():
-                message = "When auditing multiple repositories, --checkpoint must point to a directory."
-                if _cli_state["json_only"]:
-                    _emit_json({"error": message})
-                else:
-                    console.print(f"[red]{message}[/red]")
-                raise typer.Exit(1)
-            checkpoint_dir = checkpoint or resume or Path(".audit_checkpoints")
-            if resume and not checkpoint_dir.exists():
-                message = f"Checkpoint directory not found: {checkpoint_dir}"
-                if _cli_state["json_only"]:
-                    _emit_json({"error": message})
-                else:
-                    console.print(f"[red]{message}[/red]")
-                raise typer.Exit(1)
-            checkpoint_dir.mkdir(parents=True, exist_ok=True)
-            for repo in repos:
-                per_repo_path = checkpoint_dir / f"{repo.name}.checkpoint.json"
-                if resume:
-                    if not per_repo_path.exists():
-                        message = f"Checkpoint not found for repo {repo.name}: {per_repo_path}"
-                        if _cli_state["json_only"]:
-                            _emit_json({"error": message})
-                        else:
-                            console.print(f"[red]{message}[/red]")
-                        raise typer.Exit(1)
-                    cp = load_checkpoint(per_repo_path)
-                    _validate_checkpoint(cp, repo, audit_template)
-                else:
-                    cp = _create_checkpoint(repo, audit_template, started_at)
-                save_checkpoint(cp, per_repo_path)
-                checkpoint_plan[repo] = (cp, per_repo_path)
-                checkpoint_paths.append(per_repo_path)
-        else:
-            repo = repos[0]
-            checkpoint_path = checkpoint or resume
-            single_cp: AuditCheckpoint | None = None
-            if resume:
-                single_cp = load_checkpoint(resume)
-                _validate_checkpoint(single_cp, repo, audit_template)
-            if checkpoint_path:
-                if single_cp is None:
-                    single_cp = _create_checkpoint(repo, audit_template, started_at)
-                save_checkpoint(single_cp, checkpoint_path)
-                checkpoint_plan[repo] = (single_cp, checkpoint_path)
-                checkpoint_paths.append(checkpoint_path)
-
-    # 4. Run Audit
-    if ctx.verbose and not _cli_state["json_only"]:
-        console.print(f"[dim]Starting audit with {len(repos)} repositories...[/dim]\n")
-    engine = AuditEngine(concurrency=concurrency)
-    scorer = Scorer()
-    registry = get_default_registry() if section_packs else None
-    results = []
-
-    async def run_all():
-        async def _run_repo(repo: Path) -> tuple[Any, Any]:
-            checkpoint_data = checkpoint_plan.get(repo, (None, None))
-            audit_id = checkpoint_data[0].audit_id if checkpoint_data[0] is not None else str(uuid4())
-            template_for_repo = audit_template
-            profile_result = None
-            pack_result = None
-            adaptive_result = None
-
-            if adaptive_weights or section_packs or gap_analysis:
-                try:
-                    resolution = await resolve_profile_async(
-                        repo_path=repo,
-                        project_id=repo.name,
-                        cli_profile=project_profile,
-                        profile_map_path=profile_map,
-                    )
-                    profile_result = resolution.profile
-                except (OSError, RuntimeError, TypeError, ValueError, LookupError, ImportError) as exc:
-                    _log_hardened_path_error(
-                        "profile_resolution_failed",
-                        exc,
-                        context=f"repo={repo}, profile_map={profile_map}",
-                        recovery_action="continue_with_repo_name_profile",
-                    )
-
-            project_key = profile_result.project_id if profile_result is not None else repo.name
-            context_vars = {
-                "audit_id": str(audit_id),
-                "project_key": str(project_key),
-            }
-
-            if section_packs and registry is not None and profile_result is not None:
-                pack_result = registry.apply_packs(template_for_repo, profile_result, section_pack)
-                template_for_repo = registry.filter_template_sections(
-                    template_for_repo,
-                    profile_result,
-                    section_pack,
-                )
-                if pack_result.generated_sections:
-                    from vds_audit_orchestrator.models.template import AuditSection
-                    from vds_audit_orchestrator.models.template import AuditTemplate as AuditTemplateModel
-
-                    generated = [AuditSection.model_validate(section) for section in pack_result.generated_sections]
-                    template_for_repo = AuditTemplateModel(
-                        name=template_for_repo.name,
-                        version=template_for_repo.version,
-                        sections=[*template_for_repo.sections, *generated],
-                    )
-
-            if adaptive_weights and profile_result is not None:
-                adaptive_result = compute_adaptive_weights(template_for_repo, profile_result)
-
-            audit_result = await engine.audit_repo(
-                repo,
-                template_for_repo,
-                context_vars=context_vars,
-                dry_run=dry_run,
-                checkpoint=checkpoint_data[0],
-                checkpoint_path=checkpoint_data[1],
-                checkpoint_enabled=checkpoint_enabled,
-                scorer=scorer,
-                use_adaptive_weights=adaptive_weights and profile_result is not None,
-                adaptive_weights=adaptive_result,
-                profile=profile_result,
-            )
-
-            if gap_analysis:
-                gap_profile = profile_result or default_profile(project_id=repo.name, name=repo.name)
-                try:
-                    gap_result = await _run_gap_analysis_for_repo(
-                        repo_path=repo,
-                        audit_template=template_for_repo,
-                        profile_obj=gap_profile,
-                        llm_client=gap_llm_client,
-                        llm_model=gap_model_name,
-                    )
-                    if gap_result is not None:
-                        audit_result = audit_result.model_copy(update={"gap_analysis": gap_result})
-                except Exception as exc:
-                    logger.warning("gap_analysis_failed", repo=str(repo), error=str(exc))
-
-            from vds_audit_orchestrator.observability.metrics import record_gaps
-
-            record_gaps(
-                repository=repo.name,
-                severity_counts={
-                    "critical": audit_result.critical_issues,
-                    "high": audit_result.high_issues,
-                    "medium": audit_result.medium_issues,
-                    "low": audit_result.low_issues,
-                },
-            )
-
-            audit_metadata = dict(audit_result.audit_metadata)
-            audit_metadata["audit_id"] = str(audit_id)
-            audit_result = audit_result.model_copy(update={"audit_metadata": audit_metadata})
-
-            return audit_result, pack_result
-
-        tasks = [_run_repo(repo) for repo in repos]
-        return await asyncio.gather(*tasks)
-
-    try:
-        if _cli_state["json_only"]:
-            results = asyncio.run(run_all())
-        else:
-            with Progress(
-                SpinnerColumn(),
-                TextColumn("[progress.description]{task.description}"),
-                transient=True,
-            ) as progress:
-                progress.add_task(f"Auditing {len(repos)} repositories...", total=len(repos))
-                results = asyncio.run(run_all())
-    except Exception as e:
-        if _cli_state["json_only"]:
-            _emit_json({"error": str(e)})
-        else:
-            console.print(f"[red]Audit failed:[/red] {e}")
-            _suggest_fix_for_audit_error(e)
-        raise typer.Exit(1) from e
-
-    processed_results = []
-    for repo_result_tuple in results:
-        repo_result, pack_result = repo_result_tuple
-        if pack_result is not None:
-            repo_result.audit_metadata["section_packs"] = pack_result.to_dict()
-        if baseline_scores:
-            baseline_score = baseline_scores.get(repo_result.repo_name)
-            if baseline_score is not None:
-                repo_result = repo_result.model_copy(
-                    update={
-                        "baseline_score": baseline_score,
-                        "score_delta": repo_result.total_score - baseline_score,
-                    }
-                )
-        processed_results.append(repo_result)
-    results = processed_results
-
-    finished_at = datetime.now(UTC)
-    try:
-        orchestrator_version = metadata.version("vds-audit-orchestrator")
-    except metadata.PackageNotFoundError:
-        orchestrator_version = "unknown"
-
-    inputs: dict[str, str] = {
-        "repo_path": str(repo_path),
-        "concurrency": str(concurrency),
-    }
-    if template:
-        inputs["template"] = str(template)
-    if template_url:
-        inputs["template_url"] = template_url
-    if template_sheet:
-        inputs["template_sheet"] = template_sheet
-    if template_gid is not None:
-        inputs["template_gid"] = str(template_gid)
-    if template_map:
-        inputs["template_map"] = str(template_map)
-    if template_table_index is not None:
-        inputs["template_table_index"] = str(template_table_index)
-    if gs_auth_method:
-        inputs["gs_auth_method"] = gs_auth_method
-    if gs_credentials_path:
-        inputs["gs_credentials_path"] = str(gs_credentials_path)
-    if gs_oauth_credentials_path:
-        inputs["gs_oauth_credentials_path"] = str(gs_oauth_credentials_path)
-    if gs_api_key:
-        inputs["gs_api_key"] = "set"
-    if project_profile:
-        inputs["project_profile"] = str(project_profile)
-    if profile_map:
-        inputs["profile_map"] = str(profile_map)
-    inputs["adaptive_weights"] = str(adaptive_weights)
-    inputs["gap_analysis"] = str(gap_analysis)
-    if gap_analysis:
-        inputs["gap_llm_enabled"] = str(gap_llm if gap_llm is not None else bool(gap_llm_client))
-        if gap_model_name:
-            inputs["gap_llm_model"] = gap_model_name
-    inputs["section_packs"] = str(section_packs)
-    if section_pack:
-        inputs["section_pack"] = ",".join(section_pack)
-    if baseline:
-        inputs["baseline"] = str(baseline)
-    if output:
-        inputs["output"] = str(output)
-    cost_summary = global_tracker.summary()
-    if cost_summary.get("total_cost_usd", 0) > 0 or cost_summary.get("total_input_tokens", 0) > 0:
-        inputs["llm_cost_usd"] = str(cost_summary.get("total_cost_usd"))
-        inputs["llm_input_tokens"] = str(cost_summary.get("total_input_tokens"))
-        inputs["llm_output_tokens"] = str(cost_summary.get("total_output_tokens"))
-
-    meta = build_metadata(
-        template_name=getattr(audit_template, "name", None),
-        template_version=getattr(audit_template, "version", None),
-        started_at=started_at,
-        finished_at=finished_at,
-        orchestrator_version=orchestrator_version,
-        inputs=inputs,
-    ).model_copy(update={"repo_count": len(repos)})
-
-    report = AuditRunReport(metadata=meta, repositories=results)
-    debug_bundle_path = _cli_state.get("debug_bundle")
-    if debug_bundle_path:
-        try:
-            _write_debug_bundle(
-                debug_bundle_path,
-                report,
-                inputs,
-                cost_summary,
-                _cli_state.get("log_capture"),
-            )
-        except (OSError, RuntimeError, TypeError, ValueError, LookupError, ImportError) as exc:
-            _log_hardened_path_error(
-                "debug_bundle_failed",
-                exc,
-                context=f"debug_bundle_path={debug_bundle_path}",
-                recovery_action="continue_without_debug_bundle",
-            )
-
-    report_paths = None
-    if ctx.reports and not ctx.json_only:
-        report_paths = generate_reports(
-            report,
-            report_dir=ctx.report_dir,
-            excel_path=output,
-            include_markdown=ctx.markdown,
-            include_sarif=ctx.sarif,
-        )
-
-    duration = (finished_at - started_at).total_seconds()
-
-    if _cli_state["json_only"]:
-        payload = report.model_dump(mode="json", exclude_none=True)
-        if report_paths:
-            payload["report_paths"] = {
-                "excel": str(report_paths.excel),
-                "json": str(report_paths.json),
-                "markdown": str(report_paths.markdown) if report_paths.markdown else None,
-                "sarif": str(report_paths.sarif) if report_paths.sarif else None,
-            }
-        _emit_json(payload)
-    else:
-        console.print("[green]Audit Complete![/green]")
-        console.print(f"[dim]Duration: {_format_duration(duration)}[/dim]\n")
-
-        if report_paths:
-            console.print(f"Excel report: [bold]{report_paths.excel}[/bold]")
-            console.print(f"JSON report: [bold]{report_paths.json}[/bold]")
-            if report_paths.markdown:
-                console.print(f"Markdown report: [bold]{report_paths.markdown}[/bold]")
-            if report_paths.sarif:
-                console.print(f"SARIF report: [bold]{report_paths.sarif}[/bold]")
-            console.print()
-        else:
-            console.print("[yellow]Reports are disabled; no files were written.[/yellow]\n")
-
-        table = Table(title="Audit Summary")
-        table.add_column("Repository")
-        table.add_column("Score", justify="right")
-        table.add_column("Critical", justify="right")
-        table.add_column("High", justify="right")
-        table.add_column("Medium", justify="right")
-        table.add_column("Low", justify="right")
-
-        total_critical = 0
-        total_high = 0
-        total_medium = 0
-        total_low = 0
-
-        for res in processed_results:
-            color = "green" if res.total_score >= 80 else "yellow" if res.total_score >= 50 else "red"
-            table.add_row(
-                res.repo_name,
-                f"[{color}]{res.total_score:.1f}[/{color}]",
-                str(res.critical_issues),
-                str(res.high_issues),
-                str(res.medium_issues),
-                str(res.low_issues),
-            )
-            total_critical += res.critical_issues
-            total_high += res.high_issues
-            total_medium += res.medium_issues
-            total_low += res.low_issues
-
-        console.print(table)
-
-        console.print("\n[bold]Overall Statistics:[/bold]")
-        console.print(f"  Repositories audited: {len(results)}")
-        console.print(f"  Total issues found: {total_critical + total_high + total_medium + total_low}")
-        if total_critical > 0:
-            console.print(
-                "  1. Address [red]Critical[/red] issues immediately - these represent security or compliance risks"
-            )
-        if total_high > 0:
-            console.print(f"  [red]Critical issues: {total_critical}[/red]")
-        if total_high > 0:
-            console.print(f"  [bright_red]High issues: {total_high}[/bright_red]")
-        if total_medium > 0:
-            console.print(f"  [yellow]Medium issues: {total_medium}[/yellow]")
-        if total_low > 0:
-            console.print(f"  [blue]Low issues: {total_low}[/blue]")
-        cost_summary = global_tracker.summary()
-        if cost_summary.get("total_cost_usd", 0) > 0 or cost_summary.get("total_input_tokens", 0) > 0:
-            console.print(f"  LLM cost (USD): {cost_summary.get('total_cost_usd')}")
-            console.print(
-                "  LLM tokens: "
-                f"{cost_summary.get('total_input_tokens')} in / {cost_summary.get('total_output_tokens')} out"
-            )
-
-        if total_critical > 0 or total_high > 0:
-            console.print("\n[bold yellow]Recommended Actions:[/bold yellow]")
-            if total_critical > 0:
-                console.print(
-                    "  1. Address [red]Critical[/red] issues immediately - these represent security or compliance risks"
-                )
-            if total_high > 0:
-                console.print(
-                    "  2. Prioritize [bright_red]High[/bright_red] issues to reduce risks and improve compliance"
-                )
-            if total_medium > 0:
-                console.print("  3. Review [yellow]Medium[/yellow] issues during regular development cycles")
-            if total_low > 0:
-                console.print("  4. Consider [blue]Low[/blue] issues as technical debt to be addressed over time")
-
-        if global_tracker.summary().get("total_cost_usd", 0) > 0:
-            console.print("\n[dim]LLM usage may incur costs. Monitor API usage.[/dim]")
-
-    if any(res.total_score < 50 for res in results):
-        raise typer.Exit(1)
-
-
-# ---------------------------------------------------------------------------
-# export-debug-bundle
-# ---------------------------------------------------------------------------
-
-
-@app.command(name="export-debug-bundle")
-def export_debug_bundle(
-    audit_id: str = typer.Argument(..., help="The ID of the audit to export artifacts for"),
-    output: Path = typer.Option(None, "--output", "-o", help="Output path for the zip bundle"),
-) -> None:
-    """Export a debug bundle for a specific audit execution.
-
-    Collects logs, checkpoints, and environment info into a ZIP file
-    for troubleshooting.
-    """
-    try:
-        path = export_debug_bundle_func(audit_id=audit_id, output_file=output)
-        console.print(f"[green]Debug bundle exported to: {path}[/green]")
-    except (OSError, RuntimeError, TypeError, ValueError, LookupError, ImportError) as e:
-        _log_hardened_path_error(
-            "export_debug_bundle_failed",
-            e,
-            context=f"audit_id={audit_id}, output={output}",
-            recovery_action="emit_cli_error_and_exit",
-            level="exception",
-        )
-        console.print(f"[red]Failed to export debug bundle: {e}[/red]")
-        raise typer.Exit(1) from e
-
-
-# ---------------------------------------------------------------------------
-# backfill-page-registry (Phase 154, FR-154.4, TSK-154.20)
-# ---------------------------------------------------------------------------
-
-
-@app.command(name="backfill-page-registry")
-def backfill_page_registry(
-    state_dsn: str | None = typer.Option(
-        None,
-        "--state-dsn",
-        envvar=_STATE_DSN_ENV_VAR,
-        help=f"Centralized state DSN (required; fallback: {_STATE_DSN_ENV_VAR}).",
-    ),
-    project_key: str | None = typer.Option(
-        None,
-        "--project-storage-key",
-        help="Limit backfill to a specific project storage key. If omitted, scans all completed runs.",
-    ),
-    dry_run: bool = typer.Option(
-        False,
-        "--dry-run/--no-dry-run",
-        help="Report what would be registered without writing.",
-    ),
-) -> None:
-    """Backfill the published_pages registry from existing run payload data.
-
-    Scans completed workflow runs in audit_state.runs, extracts
-    confluence_repo_page_ids and confluence_aggregate_page_id from
-    payload JSONB, and registers them in the published_pages table.
-
-    Idempotent: re-running updates existing entries rather than duplicating.
-    """
-    resolved_state_dsn = _resolve_state_dsn(state_dsn, required=True)
-    assert resolved_state_dsn is not None
-
-    from vds_audit_orchestrator.state.store import PostgresStateStore
-
-    store = PostgresStateStore(resolved_state_dsn)
-
-    try:
-        runs = store.list_runs(status="completed")
-        if project_key:
-            runs = [r for r in runs if r.get("project_key") == project_key]
-
-        registered = 0
-        skipped = 0
-        errors = 0
-        cross_project_skipped = 0
-
-        # Pre-load existing page→project mapping for cross-project dedup.
-        # Prevents registering a page_id under project A when it already
-        # belongs to project B (e.g. Auto Payment payload containing Core
-        # Payment page IDs).
-        existing_page_owners: dict[str, str] = {}
-        with store._conn.cursor() as _cur:
-            _cur.execute("SELECT confluence_page_id, project_key FROM audit_state.published_pages")
-            for _row in _cur:
-                existing_page_owners[_row["confluence_page_id"]] = _row["project_key"]
-
-        def _run_rank(run: dict[str, Any]) -> tuple[datetime, int, int]:
-            started_at = run.get("started_at")
-            if not isinstance(started_at, datetime):
-                started_at = datetime.min.replace(tzinfo=UTC)
-            run_type = str(run.get("run_type") or "")
-            run_priority = 1 if run_type == "publish_project_run" else 0
-            run_id = run.get("id")
-            run_id_int = int(run_id) if isinstance(run_id, int | float) else 0
-            return (started_at, run_priority, run_id_int)
-
-        latest_candidates: dict[tuple[str, str, str], dict[str, Any]] = {}
-        for run in runs:
-            run_project_key = str(run.get("project_key") or "")
-            if not run_project_key:
-                skipped += 1
-                continue
-
-            payload = run.get("payload") or {}
-            if not isinstance(payload, dict):
-                skipped += 1
-                continue
-
-            rank = _run_rank(run)
-
-            repo_page_ids = payload.get("confluence_repo_page_ids") or {}
-            if isinstance(repo_page_ids, dict):
-                for repo_key, page_id in repo_page_ids.items():
-                    if not repo_key or not page_id:
-                        skipped += 1
-                        continue
-                    logical_key = (run_project_key, str(repo_key), "repo_run")
-                    candidate = {
-                        "project_key": run_project_key,
-                        "repo_key": str(repo_key),
-                        "hierarchy_role": "repo_run",
-                        "confluence_page_id": str(page_id),
-                        "source_run_id": str(run.get("run_id") or ""),
-                        "rank": rank,
-                    }
-                    existing = latest_candidates.get(logical_key)
-                    if existing is None or candidate["rank"] > existing["rank"]:
-                        latest_candidates[logical_key] = candidate
-
-            aggregate_page_id = payload.get("confluence_aggregate_page_id")
-            if aggregate_page_id:
-                logical_key = (run_project_key, "", "aggregate")
-                candidate = {
-                    "project_key": run_project_key,
-                    "repo_key": "",
-                    "hierarchy_role": "aggregate",
-                    "confluence_page_id": str(aggregate_page_id),
-                    "source_run_id": str(run.get("run_id") or ""),
-                    "rank": rank,
-                }
-                existing = latest_candidates.get(logical_key)
-                if existing is None or candidate["rank"] > existing["rank"]:
-                    latest_candidates[logical_key] = candidate
-
-        for logical_key in sorted(latest_candidates):
-            candidate = latest_candidates[logical_key]
-            run_project_key = str(candidate["project_key"])
-            repo_key = str(candidate["repo_key"])
-            hierarchy_role = str(candidate["hierarchy_role"])
-            page_id_str = str(candidate["confluence_page_id"])
-
-            owning_project = existing_page_owners.get(page_id_str)
-            if owning_project and owning_project != run_project_key:
-                log_context = {
-                    "confluence_page_id": page_id_str,
-                    "run_project_key": run_project_key,
-                    "owning_project": owning_project,
-                    "source_run_id": candidate.get("source_run_id"),
-                }
-                if hierarchy_role == "aggregate":
-                    logger.warning(
-                        "backfill_cross_project_dedup_skipped",
-                        hierarchy_role="aggregate",
-                        **log_context,
-                    )
-                else:
-                    logger.warning(
-                        "backfill_cross_project_dedup_skipped",
-                        repo_key=repo_key,
-                        hierarchy_role=hierarchy_role,
-                        **log_context,
-                    )
-                cross_project_skipped += 1
-                continue
-
-            try:
-                if not dry_run:
-                    store.register_published_page(
-                        project_key=run_project_key,
-                        repo_key=repo_key,
-                        hierarchy_role=hierarchy_role,
-                        confluence_page_id=page_id_str,
-                    )
-                existing_page_owners[page_id_str] = run_project_key
-                registered += 1
-            except Exception as exc:
-                if hierarchy_role == "aggregate":
-                    logger.warning(
-                        "backfill_page_registry_aggregate_error",
-                        project_key=run_project_key,
-                        page_id=page_id_str,
-                        source_run_id=candidate.get("source_run_id"),
-                        error=str(exc),
-                    )
-                else:
-                    logger.warning(
-                        "backfill_page_registry_repo_error",
-                        project_key=run_project_key,
-                        repo_key=repo_key,
-                        page_id=page_id_str,
-                        source_run_id=candidate.get("source_run_id"),
-                        error=str(exc),
-                    )
-                errors += 1
-
-        summary = {
-            "registered": registered,
-            "skipped": skipped,
-            "errors": errors,
-            "cross_project_skipped": cross_project_skipped,
-        }
-        if dry_run:
-            summary["mode"] = "dry_run"
-
-        _emit_json(summary)
-
-        if errors > 0:
-            console.print(f"[yellow]Backfill completed with {errors} error(s).[/yellow]")
-        else:
-            msg = f"Backfill complete: {registered} registered, {skipped} skipped."
-            if cross_project_skipped:
-                msg += f" {cross_project_skipped} cross-project conflict(s) skipped."
-            console.print(f"[green]{msg}[/green]")
-    finally:
-        store.close()
-
-
-# ---------------------------------------------------------------------------
-# archive-stale-page
-# ---------------------------------------------------------------------------
-
-
-def _build_archive_title(base_title: str, source_page_id: str) -> str:
-    """Build the canonical archive title for stale Confluence pages."""
-
-    return f"[ARCHIVED] {base_title} - {source_page_id}"
-
-
-def _extract_archive_base_title(title: str, source_page_id: str) -> str:
-    """Normalize legacy/current archived titles back to their base title."""
-
-    normalized = title.strip()
-    if normalized.startswith("[ARCHIVED] "):
-        normalized = normalized.removeprefix("[ARCHIVED] ").strip()
-    if normalized.startswith("ARCHIVED DUPLICATE - "):
-        normalized = normalized.removeprefix("ARCHIVED DUPLICATE - ").strip()
-    if normalized.endswith(f" - {source_page_id}"):
-        normalized = normalized[: -len(f" - {source_page_id}")].rstrip()
-    if normalized.endswith(" (duplicate)"):
-        normalized = normalized[: -len(" (duplicate)")].rstrip()
-    return normalized
-
-
-def _page_parent_id(page_payload: dict[str, Any] | None) -> str | None:
-    """Extract the immediate parent page id from a Confluence page payload."""
-
-    if not isinstance(page_payload, dict):
-        return None
-    ancestors = page_payload.get("ancestors")
-    if not isinstance(ancestors, list) or not ancestors:
-        return None
-    last = ancestors[-1]
-    if not isinstance(last, dict):
-        return None
-    parent_id = last.get("id")
-    return str(parent_id) if parent_id else None
-
-
-@app.command(name="archive-stale-page")
-def archive_stale_page(
-    page_id: str = typer.Option(..., "--page-id", help="Source Confluence page id or URL to archive."),
-    archive_parent: str = typer.Option(
-        ..., "--archive-parent", help="Archive parent Confluence page id or URL that will receive the page."
-    ),
-    expected_title: str = typer.Option(
-        ..., "--expected-title", help="Required current page title guard before rename/move."
-    ),
-    dry_run: bool = typer.Option(
-        False,
-        "--dry-run/--no-dry-run",
-        help="Report the intended archive operation without performing rename or move.",
-    ),
-    confluence_server: str | None = typer.Option(
-        None,
-        "--confluence-server",
-        "--server",
-        help="Explicit Confluence server label (internal|external). If omitted, infer from page refs.",
-    ),
-    timeout: int = typer.Option(30, "--timeout", help="Confluence client timeout in seconds."),
-    retries: int = typer.Option(3, "--retries", help="Retry count for Confluence client calls."),
-) -> None:
-    """Archive a stale Confluence page by renaming it and reparenting it safely."""
-
-    _validate_required_credentials(command="archive-stale-page", require_confluence=True)
-
-    inferred_server = _parse_confluence_ref(archive_parent).server or _parse_confluence_ref(page_id).server
-    resolved_server = confluence_server or inferred_server
-    confluence = ConfluenceCliClient(server=resolved_server, timeout=timeout, retries=retries)
-
-    try:
-        resolved_page_id = asyncio.run(_resolve_confluence_page_id(confluence, page_id))
-        resolved_parent_id = asyncio.run(_resolve_confluence_page_id(confluence, archive_parent))
-
-        page_payload = asyncio.run(confluence.get_page(resolved_page_id, expand="version,space,ancestors"))
-        if not isinstance(page_payload, dict) or not page_payload.get("title"):
-            message = f"Could not resolve source page {resolved_page_id}."
-            _emit_json({"status": "error", "error": message, "page_id": resolved_page_id})
-            raise typer.Exit(1)
-
-        live_title = str(page_payload.get("title"))
-        if live_title != expected_title:
-            message = "Current page title does not match --expected-title."
-            _emit_json(
-                {
-                    "status": "error",
-                    "error": message,
-                    "page_id": resolved_page_id,
-                    "live_title": live_title,
-                    "expected_title": expected_title,
-                }
-            )
-            raise typer.Exit(1)
-
-        archive_parent_payload = asyncio.run(confluence.get_page(resolved_parent_id, expand="version,space"))
-        if not isinstance(archive_parent_payload, dict) or not archive_parent_payload.get("title"):
-            message = f"Could not resolve archive parent page {resolved_parent_id}."
-            _emit_json({"status": "error", "error": message, "archive_parent_id": resolved_parent_id})
-            raise typer.Exit(1)
-
-        archive_parent_title = str(archive_parent_payload.get("title"))
-        old_parent_id = _page_parent_id(page_payload)
-        canonical_base_title = _extract_archive_base_title(live_title, resolved_page_id)
-        canonical_title = _build_archive_title(canonical_base_title, resolved_page_id)
-        payload: dict[str, Any] = {
-            "status": "ok",
-            "page_id": resolved_page_id,
-            "archive_parent_id": resolved_parent_id,
-            "archive_parent_title": archive_parent_title,
-            "old_title": live_title,
-            "new_title": canonical_title,
-            "old_parent_id": old_parent_id,
-        }
-
-        already_archived = live_title.startswith("[ARCHIVED]")
-        if already_archived and old_parent_id != resolved_parent_id:
-            message = "Refusing to normalize an archived page that is not already under the supplied archive parent."
-            payload["status"] = "error"
-            payload["error"] = message
-            _emit_json(payload)
-            raise typer.Exit(1)
-
-        if already_archived and live_title == canonical_title:
-            payload["mode"] = "noop_already_canonical"
-            _emit_json(payload)
-            return
-
-        if dry_run:
-            payload["mode"] = "dry_run"
-            _emit_json(payload)
-            return
-
-        asyncio.run(confluence.rename_page(resolved_page_id, canonical_title))
-        if not already_archived:
-            asyncio.run(confluence.move_page_to_parent(resolved_page_id, resolved_parent_id))
-
-        verified_page = asyncio.run(confluence.get_page(resolved_page_id, expand="version,space,ancestors"))
-        verified_title = str(verified_page.get("title")) if isinstance(verified_page, dict) else None
-        verified_parent_id = _page_parent_id(verified_page if isinstance(verified_page, dict) else None)
-        payload["verified_title"] = verified_title
-        payload["verified_parent_id"] = verified_parent_id
-
-        if verified_title != canonical_title or verified_parent_id != resolved_parent_id:
-            payload["status"] = "error"
-            payload["error"] = "Archive verification failed after rename/reparent."
-            _emit_json(payload)
-            raise typer.Exit(1)
-
-        payload["mode"] = "applied"
-        _emit_json(payload)
-    except typer.Exit:
-        raise
-    except Exception as exc:
-        logger.exception("archive_stale_page_failed", page_id=page_id, archive_parent=archive_parent)
-        _emit_json(
-            {
-                "status": "error",
-                "error": str(exc),
-                "page_id": page_id,
-                "archive_parent": archive_parent,
-            }
-        )
-        raise typer.Exit(1) from None