@ngocsangairvds/vsaf 3.2.14 → 3.2.16

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

@@ -1,3295 +0,0 @@
-"""Doctor commands for vds-audit CLI."""
-
-from __future__ import annotations
-
-import asyncio
-import contextlib
-import dataclasses
-import json
-import os
-import re
-import shlex
-import subprocess
-from collections import deque
-from datetime import UTC, datetime, timedelta
-from pathlib import Path
-from time import perf_counter, sleep
-from typing import Any, cast
-
-import typer
-from rich.table import Table
-from vds_agent_core.profiles import list_runtime_profile_names
-from vds_cli_common.env import load_shared_env
-from vds_cli_common.paths import get_shared_env_path, get_vds_log_root
-
-from vds_audit_orchestrator.config import get_config
-from vds_audit_orchestrator.confluence_connectivity import collect_confluence_connectivity_payload
-from vds_audit_orchestrator.state.store import PostgresStateStore
-
-from .cli_common import _PRIMARY_SHARED_ENV_PATH, _STATE_DSN_ENV_VAR, _cli_state, console, doctor_app, logger
-from .cli_impl import (
-    _VDS_CLI_PROJECT_DIR,
-    _collect_credentials_status,
-    _emit_json,
-    _invoke_state_api,
-    _load_state_api,
-    _probe_runtime_profiles_availability,
-    _resolve_project_key,
-    _resolve_runtime_log_file,
-    _resolve_state_dsn,
-    _state_command_candidates,
-    _state_connection_kwargs,
-)
-
-
-@doctor_app.command(name="credentials")
-def doctor_credentials(
-    require_state_dsn: bool = typer.Option(
-        False,
-        "--require-state-dsn",
-        help=f"Fail if {_STATE_DSN_ENV_VAR} is not set.",
-    ),
-    require_langgraph_dsn: bool = typer.Option(
-        False,
-        "--require-langgraph-dsn",
-        help="Fail if no LangGraph Postgres DSN env is set.",
-    ),
-) -> None:
-    """Validate credential and DSN readiness from the shared VDS env file plus shell env."""
-    status = _collect_credentials_status()
-    errors: list[str] = []
-    warnings_list: list[str] = []
-    if not bool(status.get("confluence_ready")):
-        errors.append("Confluence credentials missing")
-    if not bool(status.get("bitbucket_ready")):
-        errors.append("Bitbucket credentials missing")
-    if require_state_dsn and not bool(status.get("state_dsn_set")):
-        errors.append(f"{_STATE_DSN_ENV_VAR} not set")
-    if require_langgraph_dsn and not bool(status.get("langgraph_postgres_dsn_set")):
-        errors.append("LangGraph Postgres DSN not set")
-
-    codex_enabled = bool(status.get("codex_diagnostics_enabled"))
-    if codex_enabled:
-        codex_jwt_status = str(status.get("codex_jwt_status") or "").strip().upper()
-        codex_message = str(status.get("codex_jwt_message") or "").strip()
-        codex_remediation = str(status.get("codex_remediation") or "").strip()
-        codex_auth_mode = str(status.get("codex_auth_mode") or "").strip().lower()
-        if codex_jwt_status == "FAIL":
-            errors.append(codex_message or "Codex OAuth diagnostics failed.")
-        elif codex_jwt_status == "WARN":
-            warnings_list.append(codex_message or "Codex OAuth diagnostics reported warnings.")
-        if codex_auth_mode == "api_key":
-            warnings_list.append(
-                codex_remediation
-                or (
-                    "Run 'codex --login' to authenticate with your ChatGPT plan, "
-                    "or switch to model.llm.type: openai for API-key billing."
-                )
-            )
-
-    unique_warnings: list[str] = []
-    for item in warnings_list:
-        text = str(item).strip()
-        if text and text not in unique_warnings:
-            unique_warnings.append(text)
-
-    payload = {
-        "status": "error" if errors else ("warning" if unique_warnings else "ok"),
-        "checks": status,
-        "warnings": unique_warnings,
-        "errors": errors,
-    }
-    if _cli_state.get("json_only"):
-        _emit_json(payload)
-        if errors:
-            raise typer.Exit(1)
-        return
-
-    table = Table(title="Credential Readiness")
-    table.add_column("Check")
-    table.add_column("Value")
-    table.add_row("Env path", str(status["env_path"]))
-    table.add_row("Basic auth", "yes" if status["basic_auth_ready"] else "no")
-    table.add_row("Confluence ready", "yes" if status["confluence_ready"] else "no")
-    table.add_row("Bitbucket ready", "yes" if status["bitbucket_ready"] else "no")
-    table.add_row(_STATE_DSN_ENV_VAR, "set" if status["state_dsn_set"] else "missing")
-    table.add_row(
-        "LangGraph DSN",
-        "set" if status["langgraph_postgres_dsn_set"] else "missing",
-    )
-    if codex_enabled:
-        codex_jwt_status = str(status.get("codex_jwt_status") or "").strip().upper() or "FAIL"
-        codex_marker = {"PASS": "PASS", "WARN": "WARN", "FAIL": "FAIL"}.get(codex_jwt_status, codex_jwt_status)
-        table.add_row("LLM protocol", str(status.get("llm_protocol") or "-"))
-        table.add_row("Codex auth file", "yes" if status.get("codex_auth_file_exists") else "no")
-        table.add_row("Codex auth mode", str(status.get("codex_auth_mode") or "-"))
-        table.add_row("Codex access token", "present" if status.get("codex_access_token_present") else "missing")
-        table.add_row("Codex account_id", str(status.get("codex_account_id_masked") or "missing"))
-        table.add_row("Codex JWT status", codex_marker)
-        table.add_row("Codex plan type", str(status.get("codex_plan_type") or "unknown"))
-    console.print(table)
-
-    for warning in unique_warnings:
-        console.print(f"[yellow]- {warning}[/yellow]")
-    if errors:
-        for err in errors:
-            console.print(f"[red]- {err}[/red]")
-        raise typer.Exit(1)
-
-
-@doctor_app.command(name="profile-availability")
-def doctor_profile_availability(
-    profiles: str | None = typer.Option(
-        None,
-        "--profiles",
-        help="Comma-separated runtime profile names to inspect. Defaults to all configured runtime profiles when omitted.",
-    ),
-    mode: str = typer.Option(
-        "active",
-        "--mode",
-        help="Availability depth: credentials or active.",
-    ),
-    parallel_check: bool = typer.Option(
-        False,
-        "--parallel-check/--no-parallel-check",
-        help="Run profile availability checks in parallel using isolated worker processes.",
-    ),
-    parallel_workers: int = typer.Option(
-        4,
-        "--parallel-workers",
-        min=1,
-        help="Maximum worker processes used when --parallel-check is enabled.",
-    ),
-    probe_timeout_seconds: float = typer.Option(
-        30.0,
-        "--probe-timeout-seconds",
-        min=1.0,
-        help="Per-profile timeout budget when --parallel-check is enabled.",
-    ),
-) -> None:
-    """Inspect launch readiness for one or more runtime profiles."""
-    normalized_mode = str(mode or "").strip().lower()
-    if normalized_mode not in {"credentials", "active"}:
-        raise typer.BadParameter("--mode must be one of: credentials, active")
-
-    profile_list = [item.strip() for item in str(profiles or "").split(",") if item.strip()]
-    if not profile_list:
-        profile_list = list_runtime_profile_names()
-    if not profile_list:
-        raise typer.BadParameter(
-            "No runtime profiles are configured. Provide --profiles or configure ~/.vds/audit.profiles.yaml."
-        )
-
-    checks = _probe_runtime_profiles_availability(
-        profile_list,
-        mode=cast("Any", normalized_mode),
-        parallel=parallel_check,
-        max_workers=parallel_workers,
-        timeout_seconds=probe_timeout_seconds,
-    )
-    available_profiles = [item["profile"] for item in checks if item.get("availability_status") != "unavailable"]
-    unavailable_profiles = [item["profile"] for item in checks if item.get("availability_status") == "unavailable"]
-    degraded_profiles = [item["profile"] for item in checks if item.get("availability_status") == "degraded"]
-    payload = {
-        "status": "error" if unavailable_profiles else ("warning" if degraded_profiles else "ok"),
-        "mode": normalized_mode,
-        "parallel_check": parallel_check,
-        "parallel_workers": parallel_workers,
-        "probe_timeout_seconds": probe_timeout_seconds,
-        "requested_profiles": profile_list,
-        "checks": checks,
-        "available_profiles": available_profiles,
-        "unavailable_profiles": unavailable_profiles,
-        "degraded_profiles": degraded_profiles,
-    }
-
-    if _cli_state.get("json_only"):
-        _emit_json(payload)
-        if unavailable_profiles:
-            raise typer.Exit(1)
-        return
-
-    table = Table(title="Profile Availability")
-    table.add_column("Profile")
-    table.add_column("Availability")
-    table.add_column("Credentials")
-    table.add_column("Probe")
-    table.add_column("Reasons")
-    for item in checks:
-        reasons = ", ".join(str(code) for code in item.get("reason_codes") or [])
-        table.add_row(
-            str(item.get("profile") or "-"),
-            str(item.get("availability_status") or "-"),
-            str(item.get("credential_status") or "-"),
-            str(item.get("probe_status") or "-"),
-            reasons or "-",
-        )
-    console.print(table)
-    if unavailable_profiles:
-        raise typer.Exit(1)
-
-
-def _resolve_strict_require_effective_skill_flag() -> bool:
-    raw_value = os.getenv("VDS_AUDIT_AGENTIC_STRICT_REQUIRE_EFFECTIVE_SKILL")
-    if raw_value is None:
-        return True
-    return raw_value.strip().lower() in {"1", "true", "yes", "on"}
-
-
-def _collect_skill_policy_doctor_payload() -> dict[str, Any]:
-    config = get_config()
-    llm = config.llm
-    payload: dict[str, Any] = {
-        "status": "ok",
-        "skills_toolset_enabled": bool(llm.skills_toolset_enabled),
-        "skills_directories": [str(item) for item in llm.skills_directories],
-        "skills_allowlist": [str(item) for item in llm.skills_allowlist],
-        "allow_script_execution": bool(llm.skills_allow_script_execution),
-        "allowed_trust_tiers": [str(item) for item in llm.skills_allowed_trust_tiers],
-        "default_trust_tier": str(llm.skills_default_trust_tier),
-        "strict_require_effective_skill": _resolve_strict_require_effective_skill_flag(),
-        "runtime_skill_names": [],
-        "diagnostics": None,
-        "errors": [],
-        "warnings": [],
-    }
-    if not payload["skills_toolset_enabled"]:
-        payload["status"] = "disabled"
-        payload["message"] = "skills_toolset_disabled"
-        return payload
-    if not payload["skills_directories"]:
-        payload["status"] = "error"
-        payload["errors"] = ["skills_toolset_enabled=true but skills_directories is empty"]
-        return payload
-
-    try:
-        from vds_audit_orchestrator.agents.toolsets import (
-            SkillsToolsetConfig,
-            create_skills_toolset_from_config,
-        )
-        from vds_audit_orchestrator.agents.toolsets.skills_toolset import (
-            get_toolset_policy_diagnostics,
-            get_toolset_skill_metadata,
-        )
-
-        toolset = create_skills_toolset_from_config(
-            SkillsToolsetConfig(
-                directories=[str(item) for item in llm.skills_directories],
-                allowlist=[str(item) for item in llm.skills_allowlist],
-                allow_script_execution=bool(llm.skills_allow_script_execution),
-                allowed_trust_tiers=[str(item) for item in llm.skills_allowed_trust_tiers],
-                default_trust_tier=str(llm.skills_default_trust_tier),
-                trust_tiers={str(key): str(value) for key, value in llm.skills_trust_tiers.items()},
-            )
-        )
-        diagnostics = get_toolset_policy_diagnostics(toolset)
-        metadata = get_toolset_skill_metadata(toolset) or []
-        runtime_skills = getattr(toolset, "skills", None)
-        runtime_skill_names = sorted(str(name) for name in runtime_skills) if isinstance(runtime_skills, dict) else []
-        drop_reasons: list[dict[str, Any]] = []
-        blocked_tools: list[str] = []
-        if diagnostics is not None:
-            blocked_tools = [str(tool_name) for tool_name in list(getattr(diagnostics, "blocked_tools", []))]
-            for item in list(getattr(diagnostics, "dropped", [])):
-                if dataclasses.is_dataclass(item):
-                    drop_reasons.append(cast("dict[str, Any]", dataclasses.asdict(item)))
-                elif isinstance(item, dict):
-                    drop_reasons.append(dict(item))
-
-        payload["runtime_skill_names"] = runtime_skill_names
-        payload["diagnostics"] = {
-            "metadata_count": int(
-                getattr(diagnostics, "metadata_count", len(metadata)) if diagnostics is not None else len(metadata)
-            ),
-            "policy_eligible_count": int(
-                getattr(diagnostics, "policy_eligible_count", len(metadata))
-                if diagnostics is not None
-                else len(metadata)
-            ),
-            "runtime_loaded_count": int(
-                getattr(diagnostics, "runtime_loaded_count", len(runtime_skill_names))
-                if diagnostics is not None
-                else len(runtime_skill_names)
-            ),
-            "blocked_tools": blocked_tools,
-            "drop_reasons": drop_reasons,
-            # Backward-compatible alias for older consumers.
-            "dropped": list(drop_reasons),
-        }
-        diagnostics_payload = payload["diagnostics"] if isinstance(payload.get("diagnostics"), dict) else {}
-        metadata_count = int(diagnostics_payload.get("metadata_count", 0) or 0)
-        policy_eligible_count = int(diagnostics_payload.get("policy_eligible_count", 0) or 0)
-        runtime_loaded_count = int(diagnostics_payload.get("runtime_loaded_count", 0) or 0)
-        warnings_list: list[str] = []
-        if metadata_count == 0 and policy_eligible_count > 0:
-            warnings_list.append("skills_policy_counter_mismatch: policy_eligible_count>0 while metadata_count=0")
-        if metadata_count >= 0 and policy_eligible_count > metadata_count:
-            warnings_list.append("skills_policy_counter_mismatch: policy_eligible_count exceeds metadata_count")
-        if policy_eligible_count >= 0 and runtime_loaded_count > policy_eligible_count:
-            warnings_list.append("skills_policy_counter_mismatch: runtime_loaded_count exceeds policy_eligible_count")
-        if warnings_list:
-            payload["warnings"] = warnings_list
-            if payload.get("status") == "ok":
-                payload["status"] = "warning"
-    except Exception as exc:
-        payload["status"] = "error"
-        payload["errors"] = [str(exc)]
-    return payload
-
-
-@doctor_app.command(name="skills-policy")
-def doctor_skills_policy(
-    json_output: bool = typer.Option(False, "--json", help="Emit skill policy diagnostics as JSON."),
-) -> None:
-    """Show skill policy diagnostics (metadata/policy/runtime counts and drop reasons)."""
-    payload = _collect_skill_policy_doctor_payload()
-    errors_raw = payload.get("errors", [])
-    errors = [str(item) for item in errors_raw if str(item).strip()] if isinstance(errors_raw, list) else []
-    warnings_raw = payload.get("warnings", [])
-    warnings = [str(item) for item in warnings_raw if str(item).strip()] if isinstance(warnings_raw, list) else []
-    if _cli_state.get("json_only") or json_output:
-        _emit_json(payload)
-        if payload.get("status") == "error" or errors:
-            raise typer.Exit(1)
-        return
-
-    diagnostics = payload.get("diagnostics") if isinstance(payload.get("diagnostics"), dict) else {}
-    table = Table(title="Skill Policy Diagnostics")
-    table.add_column("Check")
-    table.add_column("Value")
-    table.add_row("Status", str(payload.get("status")))
-    table.add_row("Skills toolset enabled", "yes" if payload.get("skills_toolset_enabled") else "no")
-    table.add_row("Allow script execution", "yes" if payload.get("allow_script_execution") else "no")
-    table.add_row(
-        "Strict require effective skill",
-        "yes" if payload.get("strict_require_effective_skill") else "no",
-    )
-    table.add_row("Skills directories", ", ".join(cast("list[str]", payload.get("skills_directories") or [])) or "-")
-    table.add_row("Allowed trust tiers", ", ".join(cast("list[str]", payload.get("allowed_trust_tiers") or [])) or "-")
-    table.add_row("Default trust tier", str(payload.get("default_trust_tier") or "-"))
-    if diagnostics:
-        table.add_row("Metadata count", str(diagnostics.get("metadata_count")))
-        table.add_row("Policy eligible count", str(diagnostics.get("policy_eligible_count")))
-        table.add_row("Runtime loaded count", str(diagnostics.get("runtime_loaded_count")))
-        blocked = diagnostics.get("blocked_tools") if isinstance(diagnostics.get("blocked_tools"), list) else []
-        table.add_row("Blocked tools", ", ".join(str(item) for item in blocked) or "-")
-    runtime_skill_names = (
-        payload.get("runtime_skill_names") if isinstance(payload.get("runtime_skill_names"), list) else []
-    )
-    table.add_row("Runtime skill names", ", ".join(str(item) for item in runtime_skill_names) or "-")
-    console.print(table)
-
-    drop_reasons = diagnostics.get("drop_reasons") if isinstance(diagnostics.get("drop_reasons"), list) else []
-    if not drop_reasons and isinstance(diagnostics.get("dropped"), list):
-        drop_reasons = diagnostics.get("dropped")
-    if drop_reasons:
-        drops_table = Table(title="Dropped Skills")
-        drops_table.add_column("Skill")
-        drops_table.add_column("Reason")
-        drops_table.add_column("Runtime")
-        for item in drop_reasons:
-            if not isinstance(item, dict):
-                continue
-            drops_table.add_row(
-                str(item.get("skill_name") or "-"),
-                str(item.get("reason") or "-"),
-                str(item.get("runtime_name") or "-"),
-            )
-        console.print(drops_table)
-
-    if errors:
-        for err in errors:
-            console.print(f"[red]- {err}[/red]")
-        raise typer.Exit(1)
-    if warnings:
-        for warning in warnings:
-            console.print(f"[yellow]- {warning}[/yellow]")
-
-
-def _coerce_hierarchy_count(value: Any) -> int:
-    if isinstance(value, bool):
-        return int(value)
-    if isinstance(value, int):
-        return max(0, value)
-    if isinstance(value, float):
-        return max(0, int(value))
-    if isinstance(value, str):
-        text = value.strip()
-        if text.isdigit():
-            return int(text)
-    return 0
-
-
-def _select_project_for_hierarchy_readiness(manifest_payload: dict[str, Any]) -> str | None:
-    projects = manifest_payload.get("projects")
-    if not isinstance(projects, list):
-        return None
-    for entry in projects:
-        if not isinstance(entry, dict):
-            continue
-        for field_name in ("project_storage_key", "page_id", "project_name_en", "project_name"):
-            value = str(entry.get(field_name) or "").strip()
-            if value:
-                return value
-    return None
-
-
-def _bounded_hierarchy_anomalies(*, anomalies: dict[str, Any], sample_limit: int) -> dict[str, dict[str, Any]]:
-    bounded: dict[str, dict[str, Any]] = {}
-    for key in sorted(anomalies):
-        entry = anomalies.get(key)
-        if not isinstance(entry, dict):
-            continue
-        samples = entry.get("samples")
-        sample_list = samples if isinstance(samples, list) else []
-        bounded_samples = sample_list[:sample_limit]
-        bounded[key] = {
-            "count": _coerce_hierarchy_count(entry.get("count")),
-            "sample_count": len(bounded_samples),
-            "samples": bounded_samples,
-        }
-    return bounded
-
-
-def _collect_hierarchy_status_doctor_payload(
-    *,
-    state_dsn: str,
-    project: str | None,
-    sample_limit: int,
-) -> dict[str, Any]:
-    state_api = _load_state_api(required=True)
-    assert state_api is not None
-
-    project_selector = str(project or "").strip()
-    if not project_selector:
-        manifest_payload = _invoke_state_api(
-            state_api,
-            candidates=("load_manifest_payload",),
-            kwargs=_state_connection_kwargs(state_dsn),
-            required=True,
-        )
-        if not isinstance(manifest_payload, dict):
-            raise RuntimeError("State manifest payload is invalid (expected JSON object).")
-        project_selector = _select_project_for_hierarchy_readiness(manifest_payload)
-        if not project_selector:
-            raise RuntimeError("State manifest has no project selectors for hierarchy diagnostics.")
-
-    readiness_payload = _invoke_state_api(
-        state_api,
-        candidates=_state_command_candidates("readiness"),
-        kwargs={
-            "state_dsn": state_dsn,
-            "project": project_selector,
-            "project_identifier": project_selector,
-            "repo": None,
-            "repo_identifier": None,
-        },
-        required=True,
-    )
-    if not isinstance(readiness_payload, dict):
-        raise RuntimeError("State readiness returned invalid payload (expected JSON object).")
-
-    hierarchy_payload = readiness_payload.get("hierarchy")
-    if not isinstance(hierarchy_payload, dict):
-        raise RuntimeError("State readiness payload missing hierarchy diagnostics.")
-
-    anomalies_raw = hierarchy_payload.get("anomalies")
-    anomalies = anomalies_raw if isinstance(anomalies_raw, dict) else {}
-    bounded_anomalies = _bounded_hierarchy_anomalies(anomalies=anomalies, sample_limit=sample_limit)
-
-    anomaly_count = _coerce_hierarchy_count(hierarchy_payload.get("anomaly_count"))
-    if anomaly_count == 0:
-        anomaly_count = sum(_coerce_hierarchy_count(item.get("count")) for item in bounded_anomalies.values())
-    hierarchy_ready = bool(hierarchy_payload.get("hierarchy_ready")) and anomaly_count == 0
-
-    status = "pass" if hierarchy_ready else "warn"
-    warnings_list: list[str] = []
-    if status == "warn":
-        warnings_list.append("Hierarchy anomalies detected in centralized state metadata.")
-
-    return {
-        "status": status,
-        "operation": "doctor_hierarchy_status",
-        "project_selector_used": project_selector,
-        "sample_limit": sample_limit,
-        "hierarchy": {
-            "hierarchy_ready": hierarchy_ready,
-            "anomaly_count": anomaly_count,
-            "department_count": _coerce_hierarchy_count(hierarchy_payload.get("department_count")),
-            "project_count": _coerce_hierarchy_count(hierarchy_payload.get("project_count")),
-            "bitbucket_project_count": _coerce_hierarchy_count(hierarchy_payload.get("bitbucket_project_count")),
-            "repo_count": _coerce_hierarchy_count(hierarchy_payload.get("repo_count")),
-            "anomalies": bounded_anomalies,
-        },
-        "warnings": warnings_list,
-        "errors": [],
-    }
-
-
-@doctor_app.command(name="hierarchy-status")
-def doctor_hierarchy_status(
-    state_dsn: str | None = typer.Option(
-        None,
-        "--state-dsn",
-        envvar=_STATE_DSN_ENV_VAR,
-        help=f"State backend DSN (fallback: {_STATE_DSN_ENV_VAR}).",
-    ),
-    project: str | None = typer.Option(
-        None,
-        "--project",
-        help="Optional project selector (numeric Confluence page_id or URL containing pageId=<ID>).",
-    ),
-    sample_limit: int = typer.Option(
-        5,
-        "--sample-limit",
-        min=1,
-        max=20,
-        help="Maximum anomaly samples to return per anomaly type.",
-    ),
-    json_output: bool = typer.Option(False, "--json", help="Emit hierarchy diagnostics as JSON."),
-) -> None:
-    """Summarize hierarchy anomalies using centralized state readiness diagnostics."""
-    try:
-        resolved_state_dsn = _resolve_state_dsn(state_dsn, required=True)
-        assert resolved_state_dsn is not None
-        # FR-268 (AC-268.4): resolve --project through select_project() with junction table
-        resolved_project = (
-            _resolve_project_key(project_identifier=project, state_dsn=resolved_state_dsn) if project else project
-        )
-        payload = _collect_hierarchy_status_doctor_payload(
-            state_dsn=resolved_state_dsn,
-            project=resolved_project,
-            sample_limit=sample_limit,
-        )
-    except Exception as exc:
-        payload = {
-            "status": "fail",
-            "operation": "doctor_hierarchy_status",
-            "project_selector_used": str(project or "").strip() or None,
-            "sample_limit": sample_limit,
-            "hierarchy": None,
-            "warnings": [],
-            "errors": [str(exc)],
-        }
-        if _cli_state.get("json_only") or json_output:
-            _emit_json(payload)
-        else:
-            console.print("[red]Hierarchy diagnostics failed.[/red]")
-            console.print(f"[red]- {exc}[/red]")
-        raise typer.Exit(1) from exc
-
-    if _cli_state.get("json_only") or json_output:
-        _emit_json(payload)
-        return
-
-    hierarchy = payload.get("hierarchy") if isinstance(payload.get("hierarchy"), dict) else {}
-    status = str(payload.get("status") or "warn")
-    marker = {"pass": "[green]PASS[/green]", "warn": "[yellow]WARN[/yellow]", "fail": "[red]FAIL[/red]"}
-    table = Table(title="Hierarchy Status")
-    table.add_column("Check")
-    table.add_column("Value")
-    table.add_row("Status", marker.get(status, status.upper()))
-    table.add_row("Hierarchy ready", "yes" if bool(hierarchy.get("hierarchy_ready")) else "no")
-    table.add_row("Project selector used", str(payload.get("project_selector_used") or "-"))
-    table.add_row("Anomaly count", str(hierarchy.get("anomaly_count", 0)))
-    table.add_row("Departments", str(hierarchy.get("department_count", 0)))
-    table.add_row("Projects", str(hierarchy.get("project_count", 0)))
-    table.add_row("Bitbucket projects", str(hierarchy.get("bitbucket_project_count", 0)))
-    table.add_row("Repos", str(hierarchy.get("repo_count", 0)))
-    console.print(table)
-
-    anomalies = hierarchy.get("anomalies") if isinstance(hierarchy.get("anomalies"), dict) else {}
-    if anomalies:
-        anomalies_table = Table(title="Hierarchy Anomalies")
-        anomalies_table.add_column("Type")
-        anomalies_table.add_column("Count")
-        anomalies_table.add_column("Sample Count")
-        for key in sorted(anomalies):
-            item = anomalies.get(key)
-            if not isinstance(item, dict):
-                continue
-            anomalies_table.add_row(
-                key,
-                str(item.get("count", 0)),
-                str(item.get("sample_count", 0)),
-            )
-        console.print(anomalies_table)
-
-    for warning in payload.get("warnings", []) if isinstance(payload.get("warnings"), list) else []:
-        console.print(f"[yellow]- {warning}[/yellow]")
-
-
-def _collect_locks_doctor_payload(
-    *,
-    state_dsn: str,
-    stale_threshold_minutes: int,
-) -> dict[str, Any]:
-    stale_seconds = max(1, int(stale_threshold_minutes)) * 60
-    store = PostgresStateStore(state_dsn)
-    try:
-        raw_locks = store.list_advisory_locks()
-    finally:
-        store.close()
-
-    locks: list[dict[str, Any]] = []
-    stale_lock_count = 0
-    for entry in raw_locks:
-        if not isinstance(entry, dict):
-            continue
-        idle_seconds = float(entry.get("idle_seconds") or 0.0)
-        is_stale = idle_seconds >= stale_seconds
-        if is_stale:
-            stale_lock_count += 1
-        locks.append(
-            {
-                "pid": int(entry.get("pid") or 0),
-                "objid": int(entry.get("objid") or 0),
-                "granted": bool(entry.get("granted")),
-                "state": str(entry.get("state") or ""),
-                "idle_seconds": round(idle_seconds, 3),
-                "state_change": entry.get("state_change"),
-                "backend_start": entry.get("backend_start"),
-                "current_query": str(entry.get("current_query") or ""),
-                "stale": is_stale,
-            }
-        )
-
-    return {
-        "status": "warn" if stale_lock_count > 0 else "pass",
-        "operation": "doctor_locks",
-        "stale_threshold_minutes": stale_threshold_minutes,
-        "lock_count": len(locks),
-        "stale_lock_count": stale_lock_count,
-        "locks": locks,
-        "warnings": ["Stale advisory locks detected."] if stale_lock_count > 0 else [],
-        "errors": [],
-    }
-
-
-@doctor_app.command(name="locks")
-def doctor_locks(
-    state_dsn: str | None = typer.Option(
-        None,
-        "--state-dsn",
-        envvar=_STATE_DSN_ENV_VAR,
-        help=f"State backend DSN (fallback: {_STATE_DSN_ENV_VAR}).",
-    ),
-    stale_threshold_minutes: int = typer.Option(
-        10,
-        "--stale-threshold-minutes",
-        min=1,
-        max=240,
-        help="Threshold in minutes to classify advisory locks as stale.",
-    ),
-    json_output: bool = typer.Option(False, "--json", help="Emit lock diagnostics as JSON."),
-) -> None:
-    """Inspect active Postgres advisory locks and stale lock candidates."""
-    try:
-        resolved_state_dsn = _resolve_state_dsn(state_dsn, required=True)
-        assert resolved_state_dsn is not None
-        payload = _collect_locks_doctor_payload(
-            state_dsn=resolved_state_dsn,
-            stale_threshold_minutes=stale_threshold_minutes,
-        )
-    except Exception as exc:
-        payload = {
-            "status": "fail",
-            "operation": "doctor_locks",
-            "stale_threshold_minutes": stale_threshold_minutes,
-            "lock_count": 0,
-            "stale_lock_count": 0,
-            "locks": [],
-            "warnings": [],
-            "errors": [str(exc)],
-        }
-        if _cli_state.get("json_only") or json_output:
-            _emit_json(payload)
-        else:
-            console.print("[red]Lock diagnostics failed.[/red]")
-            console.print(f"[red]- {exc}[/red]")
-        raise typer.Exit(1) from exc
-
-    if _cli_state.get("json_only") or json_output:
-        _emit_json(payload)
-        return
-
-    status = str(payload.get("status") or "warn")
-    marker = {"pass": "[green]PASS[/green]", "warn": "[yellow]WARN[/yellow]", "fail": "[red]FAIL[/red]"}
-    table = Table(title="Advisory Locks")
-    table.add_column("Check")
-    table.add_column("Value")
-    table.add_row("Status", marker.get(status, status.upper()))
-    table.add_row("Stale threshold (minutes)", str(payload.get("stale_threshold_minutes", 10)))
-    table.add_row("Active lock count", str(payload.get("lock_count", 0)))
-    table.add_row("Stale lock count", str(payload.get("stale_lock_count", 0)))
-    console.print(table)
-
-    locks = payload.get("locks") if isinstance(payload.get("locks"), list) else []
-    if locks:
-        locks_table = Table(title="Lock Entries")
-        locks_table.add_column("PID")
-        locks_table.add_column("ObjID")
-        locks_table.add_column("State")
-        locks_table.add_column("Idle (s)")
-        locks_table.add_column("Granted")
-        locks_table.add_column("Stale")
-        for entry in locks:
-            if not isinstance(entry, dict):
-                continue
-            locks_table.add_row(
-                str(entry.get("pid", 0)),
-                str(entry.get("objid", 0)),
-                str(entry.get("state", "")),
-                str(entry.get("idle_seconds", 0)),
-                "yes" if bool(entry.get("granted")) else "no",
-                "yes" if bool(entry.get("stale")) else "no",
-            )
-        console.print(locks_table)
-
-    for warning in payload.get("warnings", []) if isinstance(payload.get("warnings"), list) else []:
-        console.print(f"[yellow]- {warning}[/yellow]")
-
-
-def _runtime_log_event_matches(
-    entry: dict[str, Any],
-    *,
-    level: str | None,
-    event: str | None,
-    audit_id: str | None,
-    agent: str | None,
-) -> bool:
-    if level and str(entry.get("level", "")).lower() != level.lower():
-        return False
-    if event and event.lower() not in str(entry.get("event", "")).lower():
-        return False
-    if audit_id and str(entry.get("audit_id", "")) != audit_id:
-        return False
-    return not (agent and str(entry.get("agent", "")) != agent)
-
-
-def _emit_runtime_log_event(entry: dict[str, Any], *, json_output: bool) -> None:
-    if _cli_state.get("json_only") or json_output:
-        typer.echo(json.dumps(entry, ensure_ascii=False))
-        return
-    timestamp = str(entry.get("timestamp", "-"))
-    level = str(entry.get("level", "info")).upper()
-    event = str(entry.get("event", "-"))
-    audit_id = str(entry.get("audit_id", "-"))
-    agent = str(entry.get("agent", "-"))
-    phase = str(entry.get("phase", "-"))
-    context_parts = [
-        f"audit_id={audit_id}",
-        f"agent={agent}",
-        f"phase={phase}",
-    ]
-
-    for key in ("repo", "check_id", "row_id", "task_id"):
-        value = entry.get(key)
-        if value is None:
-            continue
-        value_text = str(value).strip()
-        if value_text:
-            context_parts.append(f"{key}={value_text}")
-
-    error_context = entry.get("error_context")
-    error_code = None
-    if isinstance(error_context, dict):
-        raw_error_code = error_context.get("audit_error_code")
-        if raw_error_code is not None:
-            error_code = str(raw_error_code).strip() or None
-    if error_code is None:
-        raw_error_code = entry.get("audit_error_code")
-        if raw_error_code is not None:
-            error_code = str(raw_error_code).strip() or None
-    if error_code:
-        context_parts.append(f"audit_error_code={error_code}")
-
-    console.print(f"{timestamp} {level:<8} {event} {' '.join(context_parts)}")
-
-
-_CRAWL_STATUS_THROTTLE_EVENT_HINTS: tuple[str, ...] = (
-    "throttle",
-    "rate_limit",
-    "retry",
-    "timeout",
-    "http_429",
-)
-
-_MIGRATION_TELEMETRY_EVENT = "checklist_profile_migration_synthesized"
-_MIGRATION_LEGACY_FIELDS: tuple[str, ...] = (
-    "checklist_page_id",
-    "checklist_title",
-    "checklist_page_url",
-)
-_MIGRATION_PARSE_TIMESTAMP_FIELDS: tuple[str, ...] = (
-    "last_parse_registry_at",
-    "parse_registry_at",
-    "registry_parsed_at",
-    "last_registry_parse_at",
-)
-
-
-def _value_present(value: Any) -> bool:
-    if value is None:
-        return False
-    if isinstance(value, str):
-        return bool(value.strip())
-    if isinstance(value, list | dict | tuple | set):
-        return bool(value)
-    return True
-
-
-def _extract_parse_registry_timestamp(project_payload: dict[str, Any]) -> str | None:
-    for field_name in _MIGRATION_PARSE_TIMESTAMP_FIELDS:
-        raw_value = project_payload.get(field_name)
-        if _value_present(raw_value):
-            return str(raw_value).strip()
-    sync_metadata = project_payload.get("sync_metadata")
-    if isinstance(sync_metadata, dict):
-        for field_name in _MIGRATION_PARSE_TIMESTAMP_FIELDS:
-            raw_value = sync_metadata.get(field_name)
-            if _value_present(raw_value):
-                return str(raw_value).strip()
-    return None
-
-
-def _build_migration_project_entry(project_payload: dict[str, Any]) -> dict[str, Any]:
-    raw_profiles = project_payload.get("checklist_profiles")
-    profile_entries = (
-        [item for item in raw_profiles if isinstance(item, dict)] if isinstance(raw_profiles, list) else []
-    )
-    legacy_field_values = {field_name: project_payload.get(field_name) for field_name in _MIGRATION_LEGACY_FIELDS}
-    has_legacy_singular_fields = any(_value_present(value) for value in legacy_field_values.values())
-    has_checklist_profiles = len(profile_entries) > 0
-    has_project_checklist_page_id = _value_present(project_payload.get("checklist_page_id"))
-    return {
-        "project_page_id": str(project_payload.get("page_id") or "").strip() or None,
-        "project_storage_key": str(project_payload.get("project_storage_key") or "").strip() or None,
-        "project_name": str(project_payload.get("project_name") or project_payload.get("project_name_en") or "").strip()
-        or None,
-        "has_checklist_profiles": has_checklist_profiles,
-        "has_project_checklist_page_id": has_project_checklist_page_id,
-        "has_legacy_singular_fields": has_legacy_singular_fields,
-        "last_parse_registry_at": _extract_parse_registry_timestamp(project_payload),
-        "migration_ready": has_checklist_profiles or has_project_checklist_page_id,
-        "legacy_field_values": legacy_field_values,
-    }
-
-
-def _migration_pending_project_remediation(project_entry: dict[str, Any]) -> list[str]:
-    project_selector = str(
-        project_entry.get("project_page_id")
-        or project_entry.get("project_storage_key")
-        or project_entry.get("project_name")
-        or "unknown-project"
-    )
-    return [
-        (
-            f"Run parse-registry and refresh centralized state for project {project_selector}: "
-            "parse-registry -> sync repos -> extract-docs."
-        ),
-        (
-            "Populate project checklist_profiles[] in centralized state (profiles with page_ids[]) and rerun "
-            "doctor migration-readiness."
-        ),
-    ]
-
-
-def _collect_migration_readiness_doctor_payload(
-    *,
-    state_dsn: str,
-    project: str | None,
-) -> dict[str, Any]:
-    state_api = _load_state_api(required=True)
-    assert state_api is not None
-    manifest_payload = _invoke_state_api(
-        state_api,
-        candidates=("load_manifest_payload",),
-        kwargs=_state_connection_kwargs(state_dsn),
-        required=True,
-    )
-    if not isinstance(manifest_payload, dict):
-        raise RuntimeError("State manifest payload is invalid (expected JSON object).")
-
-    raw_projects = manifest_payload.get("projects")
-    projects = [entry for entry in raw_projects if isinstance(entry, dict)] if isinstance(raw_projects, list) else []
-    if not projects:
-        raise RuntimeError("Centralized state payload does not contain project entries.")
-
-    project_entries = [_build_migration_project_entry(project_payload) for project_payload in projects]
-    project_entries.sort(
-        key=lambda item: (
-            str(item.get("project_page_id") or ""),
-            str(item.get("project_storage_key") or ""),
-            str(item.get("project_name") or ""),
-        )
-    )
-
-    if project:
-        selected_entry = next(
-            (item for item in project_entries if str(item.get("project_page_id") or "") == project), None
-        )
-        if selected_entry is None:
-            raise RuntimeError(f"Project '{project}' not found in centralized state manifest.")
-        is_ready = bool(selected_entry.get("migration_ready"))
-        remediation = [] if is_ready else _migration_pending_project_remediation(selected_entry)
-        warnings_list: list[str] = []
-        if not is_ready:
-            warnings_list.append("Project migration is pending: checklist_profiles[] is missing.")
-        return {
-            "status": "pass" if is_ready else "warn",
-            "operation": "doctor_migration_readiness",
-            "scope": "project",
-            "project_selector_used": project,
-            "project": selected_entry,
-            "migration_ready": is_ready,
-            "remediation": remediation,
-            "warnings": warnings_list,
-            "errors": [],
-        }
-
-    total_projects = len(project_entries)
-    ready_projects = [item for item in project_entries if bool(item.get("migration_ready"))]
-    pending_projects = [item for item in project_entries if not bool(item.get("migration_ready"))]
-    warnings_list = ["Some projects are still pending checklist profile migration."] if pending_projects else []
-    remediation: list[str] = []
-    if pending_projects:
-        remediation = [
-            "Run parse-registry -> sync repos -> extract-docs for pending projects to refresh state metadata.",
-            "Ensure each pending project includes checklist_profiles[] with page_ids[] in centralized state.",
-            "Re-run doctor migration-readiness until migration_pending_count is zero.",
-        ]
-    return {
-        "status": "pass" if not pending_projects else "warn",
-        "operation": "doctor_migration_readiness",
-        "scope": "aggregate",
-        "total_projects": total_projects,
-        "migration_ready_count": len(ready_projects),
-        "migration_pending_count": len(pending_projects),
-        "migration_pending_projects": pending_projects,
-        "projects": project_entries,
-        "remediation": remediation,
-        "warnings": warnings_list,
-        "errors": [],
-    }
-
-
-@doctor_app.command(name="migration-readiness")
-def doctor_migration_readiness(
-    state_dsn: str | None = typer.Option(
-        None,
-        "--state-dsn",
-        envvar=_STATE_DSN_ENV_VAR,
-        help=f"State backend DSN (fallback: {_STATE_DSN_ENV_VAR}).",
-    ),
-    project: str | None = typer.Option(
-        None,
-        "--project",
-        help="Optional project selector (numeric Confluence page_id or URL containing pageId=<ID>).",
-    ),
-    json_output: bool = typer.Option(False, "--json", help="Emit migration readiness diagnostics as JSON."),
-) -> None:
-    """Report checklist profile migration readiness across centralized state projects."""
-    try:
-        resolved_state_dsn = _resolve_state_dsn(state_dsn, required=True)
-        assert resolved_state_dsn is not None
-        resolved_project = (
-            _resolve_project_key(project_identifier=project, state_dsn=resolved_state_dsn) if project else None
-        )
-        payload = _collect_migration_readiness_doctor_payload(
-            state_dsn=resolved_state_dsn,
-            project=resolved_project,
-        )
-    except Exception as exc:
-        payload = {
-            "status": "fail",
-            "operation": "doctor_migration_readiness",
-            "scope": "project" if project else "aggregate",
-            "project_selector_used": str(project or "").strip() or None,
-            "warnings": [],
-            "errors": [str(exc)],
-        }
-        if _cli_state.get("json_only") or json_output:
-            _emit_json(payload)
-        else:
-            console.print("[red]Migration readiness diagnostics failed.[/red]")
-            console.print(f"[red]- {exc}[/red]")
-        raise typer.Exit(1) from exc
-
-    if _cli_state.get("json_only") or json_output:
-        _emit_json(payload)
-        return
-
-    status = str(payload.get("status") or "warn")
-    marker = {"pass": "[green]PASS[/green]", "warn": "[yellow]WARN[/yellow]", "fail": "[red]FAIL[/red]"}
-    table = Table(title="Migration Readiness")
-    table.add_column("Check")
-    table.add_column("Value")
-    table.add_row("Status", marker.get(status, status.upper()))
-    table.add_row("Scope", str(payload.get("scope") or "aggregate"))
-    if str(payload.get("scope")) == "project":
-        project_payload = payload.get("project") if isinstance(payload.get("project"), dict) else {}
-        table.add_row("Project page_id", str(project_payload.get("project_page_id") or "-"))
-        table.add_row("Project key", str(project_payload.get("project_storage_key") or "-"))
-        table.add_row("Project name", str(project_payload.get("project_name") or "-"))
-        table.add_row("has_checklist_profiles", "yes" if project_payload.get("has_checklist_profiles") else "no")
-        table.add_row(
-            "has_legacy_singular_fields",
-            "yes" if project_payload.get("has_legacy_singular_fields") else "no",
-        )
-        table.add_row(
-            "last_parse_registry_at",
-            str(project_payload.get("last_parse_registry_at") or "-"),
-        )
-        table.add_row("migration_ready", "yes" if project_payload.get("migration_ready") else "no")
-    else:
-        table.add_row("Total projects", str(payload.get("total_projects", 0)))
-        table.add_row("Migration ready", str(payload.get("migration_ready_count", 0)))
-        table.add_row("Migration pending", str(payload.get("migration_pending_count", 0)))
-    console.print(table)
-
-    pending = (
-        payload.get("migration_pending_projects") if isinstance(payload.get("migration_pending_projects"), list) else []
-    )
-    if pending:
-        pending_table = Table(title="Pending Migration Projects")
-        pending_table.add_column("Project page_id")
-        pending_table.add_column("Project key")
-        pending_table.add_column("Project name")
-        pending_table.add_column("Legacy singular fields")
-        for entry in pending:
-            if not isinstance(entry, dict):
-                continue
-            pending_table.add_row(
-                str(entry.get("project_page_id") or "-"),
-                str(entry.get("project_storage_key") or "-"),
-                str(entry.get("project_name") or "-"),
-                "yes" if bool(entry.get("has_legacy_singular_fields")) else "no",
-            )
-        console.print(pending_table)
-
-    for warning in payload.get("warnings", []) if isinstance(payload.get("warnings"), list) else []:
-        console.print(f"[yellow]- {warning}[/yellow]")
-    for remediation_line in payload.get("remediation", []) if isinstance(payload.get("remediation"), list) else []:
-        console.print(f"[cyan]- {remediation_line}[/cyan]")
-
-
-def _parse_optional_since_datetime(since: str | None) -> datetime | None:
-    text = str(since or "").strip()
-    if not text:
-        return None
-    normalized = f"{text[:-1]}+00:00" if text.endswith("Z") else text
-    parsed = datetime.fromisoformat(normalized)
-    if parsed.tzinfo is None:
-        parsed = parsed.replace(tzinfo=UTC)
-    return parsed.astimezone(UTC)
-
-
-def _parse_log_timestamp(value: Any) -> datetime | None:
-    text = str(value or "").strip()
-    if not text:
-        return None
-    normalized = f"{text[:-1]}+00:00" if text.endswith("Z") else text
-    try:
-        parsed = datetime.fromisoformat(normalized)
-    except ValueError:
-        return None
-    if parsed.tzinfo is None:
-        parsed = parsed.replace(tzinfo=UTC)
-    return parsed.astimezone(UTC)
-
-
-def _resolve_project_event_filters(*, project: str | None) -> tuple[str | None, set[str], list[str]]:
-    if not project:
-        return None, set(), []
-    normalized_project = _resolve_project_key(project_identifier=project, state_dsn="")
-    filter_values: set[str] = {normalized_project}
-    warnings_list: list[str] = []
-    resolved_state_dsn = _resolve_state_dsn(None, required=False)
-    if not resolved_state_dsn:
-        warnings_list.append("State DSN not set; telemetry --project filtering uses direct log fields only.")
-        return normalized_project, filter_values, warnings_list
-
-    try:
-        state_api = _load_state_api(required=True)
-        assert state_api is not None
-        manifest_payload = _invoke_state_api(
-            state_api,
-            candidates=("load_manifest_payload",),
-            kwargs=_state_connection_kwargs(resolved_state_dsn),
-            required=True,
-        )
-        if not isinstance(manifest_payload, dict):
-            warnings_list.append("State manifest payload is invalid; project telemetry filter may be incomplete.")
-            return normalized_project, filter_values, warnings_list
-        raw_projects = manifest_payload.get("projects")
-        projects = [item for item in raw_projects if isinstance(item, dict)] if isinstance(raw_projects, list) else []
-        selected_project = next(
-            (item for item in projects if str(item.get("page_id") or "").strip() == normalized_project),
-            None,
-        )
-        if selected_project is None:
-            warnings_list.append(
-                f"Project '{normalized_project}' not found in state manifest for telemetry enrichment."
-            )
-            return normalized_project, filter_values, warnings_list
-
-        for field_name in ("checklist_page_id",):
-            raw_value = selected_project.get(field_name)
-            if _value_present(raw_value):
-                filter_values.add(str(raw_value).strip())
-        raw_profiles = selected_project.get("checklist_profiles")
-        if isinstance(raw_profiles, list):
-            for profile in raw_profiles:
-                if not isinstance(profile, dict):
-                    continue
-                raw_page_ids = profile.get("page_ids")
-                if not isinstance(raw_page_ids, list):
-                    continue
-                for page_id in raw_page_ids:
-                    page_text = str(page_id or "").strip()
-                    if page_text:
-                        filter_values.add(page_text)
-    except Exception as exc:
-        warnings_list.append(f"State enrichment for telemetry --project filter failed: {exc}")
-    return normalized_project, filter_values, warnings_list
-
-
-def _entry_matches_project_filters(entry: dict[str, Any], *, filter_values: set[str]) -> bool:
-    if not filter_values:
-        return True
-    candidates: set[str] = set()
-    for field_name in ("project_page_id", "project_id", "project", "project_storage_key", "page_id"):
-        raw_value = entry.get(field_name)
-        text = str(raw_value or "").strip()
-        if text:
-            candidates.add(text)
-    raw_page_ids = entry.get("page_ids")
-    if isinstance(raw_page_ids, list):
-        for page_id in raw_page_ids:
-            text = str(page_id or "").strip()
-            if text:
-                candidates.add(text)
-    return len(candidates.intersection(filter_values)) > 0
-
-
-def _collect_migration_telemetry_payload(
-    *,
-    since: datetime | None,
-    project: str | None,
-) -> dict[str, Any]:
-    normalized_project, filter_values, filter_warnings = _resolve_project_event_filters(project=project)
-    log_dir = get_vds_log_root()
-    log_files = sorted(log_dir.glob("vds-audit-runtime-*.jsonl"))
-
-    parse_errors = 0
-    entries_scanned = 0
-    event_count = 0
-    migration_source_counts: dict[str, int] = {}
-    latest_timestamp: datetime | None = None
-    latest_timestamp_text: str | None = None
-
-    for log_path in log_files:
-        if not log_path.is_file():
-            continue
-        with log_path.open("r", encoding="utf-8") as handle:
-            for raw_line in handle:
-                entries_scanned += 1
-                line = raw_line.strip()
-                if not line:
-                    continue
-                try:
-                    entry = json.loads(line)
-                except json.JSONDecodeError:
-                    parse_errors += 1
-                    continue
-                if not isinstance(entry, dict):
-                    continue
-                if str(entry.get("event") or "").strip() != _MIGRATION_TELEMETRY_EVENT:
-                    continue
-                if not _entry_matches_project_filters(entry, filter_values=filter_values):
-                    continue
-                event_timestamp = _parse_log_timestamp(entry.get("timestamp"))
-                if since is not None and (event_timestamp is None or event_timestamp < since):
-                    continue
-                event_count += 1
-                source = str(entry.get("migration_source") or "unknown").strip() or "unknown"
-                migration_source_counts[source] = migration_source_counts.get(source, 0) + 1
-                if event_timestamp is not None and (latest_timestamp is None or event_timestamp > latest_timestamp):
-                    latest_timestamp = event_timestamp
-                    latest_timestamp_text = event_timestamp.isoformat().replace("+00:00", "Z")
-
-    warnings_list = list(filter_warnings)
-    if not log_files:
-        warnings_list.append(f"No runtime logs found under {log_dir}.")
-    if parse_errors > 0:
-        warnings_list.append("Runtime logs contain malformed JSON lines; telemetry uses parsed entries only.")
-
-    safe_to_proceed = event_count == 0
-    advisory = (
-        "Safe to proceed: no checklist profile migration synthesis events detected in selected scope."
-        if safe_to_proceed
-        else (
-            "Migration synthesis events detected. Refresh project state and re-check before removing legacy fallback paths."
-        )
-    )
-    return {
-        "status": "pass" if safe_to_proceed else "warn",
-        "operation": "doctor_migration_telemetry",
-        "project_selector_used": normalized_project,
-        "since": since.isoformat().replace("+00:00", "Z") if since else None,
-        "event_name": _MIGRATION_TELEMETRY_EVENT,
-        "log_dir": str(log_dir),
-        "log_file_count": len(log_files),
-        "entries_scanned": entries_scanned,
-        "parse_errors": parse_errors,
-        "event_count": event_count,
-        "migration_source_counts": migration_source_counts,
-        "latest_timestamp": latest_timestamp_text,
-        "safe_to_proceed": safe_to_proceed,
-        "advisory": advisory,
-        "warnings": warnings_list,
-        "errors": [],
-    }
-
-
-@doctor_app.command(name="migration-telemetry")
-def doctor_migration_telemetry(
-    since: str | None = typer.Option(
-        None,
-        "--since",
-        help="Optional lower bound timestamp (ISO-8601, example: 2026-03-01T00:00:00Z).",
-    ),
-    project: str | None = typer.Option(
-        None,
-        "--project",
-        help="Optional project selector (numeric Confluence page_id or URL containing pageId=<ID>).",
-    ),
-    json_output: bool = typer.Option(False, "--json", help="Emit migration telemetry diagnostics as JSON."),
-) -> None:
-    """Summarize checklist profile migration synthesis telemetry from runtime logs."""
-    try:
-        since_dt = _parse_optional_since_datetime(since)
-    except ValueError as exc:
-        raise typer.BadParameter(
-            "--since must be ISO-8601 (for example: 2026-03-01T00:00:00Z).",
-            param_hint="--since",
-        ) from exc
-
-    try:
-        payload = _collect_migration_telemetry_payload(
-            since=since_dt,
-            project=project,
-        )
-    except Exception as exc:
-        payload = {
-            "status": "fail",
-            "operation": "doctor_migration_telemetry",
-            "project_selector_used": str(project or "").strip() or None,
-            "since": str(since or "").strip() or None,
-            "warnings": [],
-            "errors": [str(exc)],
-        }
-        if _cli_state.get("json_only") or json_output:
-            _emit_json(payload)
-        else:
-            console.print("[red]Migration telemetry diagnostics failed.[/red]")
-            console.print(f"[red]- {exc}[/red]")
-        raise typer.Exit(1) from exc
-
-    if _cli_state.get("json_only") or json_output:
-        _emit_json(payload)
-        return
-
-    status = str(payload.get("status") or "warn")
-    marker = {"pass": "[green]PASS[/green]", "warn": "[yellow]WARN[/yellow]", "fail": "[red]FAIL[/red]"}
-    table = Table(title="Migration Telemetry")
-    table.add_column("Check")
-    table.add_column("Value")
-    table.add_row("Status", marker.get(status, status.upper()))
-    table.add_row("Event", str(payload.get("event_name") or _MIGRATION_TELEMETRY_EVENT))
-    table.add_row("Since", str(payload.get("since") or "-"))
-    table.add_row("Project selector", str(payload.get("project_selector_used") or "-"))
-    table.add_row("Runtime log dir", str(payload.get("log_dir") or "-"))
-    table.add_row("Log files", str(payload.get("log_file_count", 0)))
-    table.add_row("Entries scanned", str(payload.get("entries_scanned", 0)))
-    table.add_row("Events detected", str(payload.get("event_count", 0)))
-    table.add_row("Latest event timestamp", str(payload.get("latest_timestamp") or "-"))
-    table.add_row("Safe to proceed", "yes" if payload.get("safe_to_proceed") else "no")
-    console.print(table)
-
-    source_counts = (
-        payload.get("migration_source_counts") if isinstance(payload.get("migration_source_counts"), dict) else {}
-    )
-    if source_counts:
-        source_table = Table(title="Migration Source Breakdown")
-        source_table.add_column("migration_source")
-        source_table.add_column("count")
-        for source in sorted(source_counts):
-            source_table.add_row(source, str(source_counts[source]))
-        console.print(source_table)
-
-    advisory = str(payload.get("advisory") or "").strip()
-    if advisory:
-        console.print(f"[cyan]{advisory}[/cyan]")
-    for warning in payload.get("warnings", []) if isinstance(payload.get("warnings"), list) else []:
-        console.print(f"[yellow]- {warning}[/yellow]")
-
-
-def _safe_int(value: Any) -> int:
-    if isinstance(value, bool):
-        return int(value)
-    if isinstance(value, int):
-        return value
-    if isinstance(value, float):
-        return int(value)
-    if isinstance(value, str):
-        text = value.strip()
-        if not text:
-            return 0
-        try:
-            return int(float(text))
-        except ValueError:
-            return 0
-    return 0
-
-
-def _collect_entry_error_total(entries: Any) -> int:
-    if not isinstance(entries, list):
-        return 0
-    total = 0
-    for entry in entries:
-        if not isinstance(entry, dict):
-            continue
-        status = str(entry.get("status") or "").strip().lower()
-        if status in {"error", "failed"}:
-            total += 1
-    return total
-
-
-_PERMISSION_DENIED_PATTERNS = (
-    "403",
-    "forbidden",
-    "unauthorized",
-    "not permitted",
-    "does not have permission",
-    "permission to view",
-)
-
-
-def _collect_permission_denied_pages(entries: Any) -> list[dict[str, Any]]:
-    """Extract pages whose error text matches permission-denied patterns (FR-192)."""
-    if not isinstance(entries, list):
-        return []
-    result: list[dict[str, Any]] = []
-    for entry in entries:
-        if not isinstance(entry, dict):
-            continue
-        status = str(entry.get("status") or "").strip().lower()
-        if status not in {"error", "failed"}:
-            continue
-        error_text = str(entry.get("error") or entry.get("error_message") or "").lower()
-        page_id = entry.get("page_id") or entry.get("id") or entry.get("content_id")
-        title = entry.get("title") or entry.get("name") or ""
-        if any(pat in error_text for pat in _PERMISSION_DENIED_PATTERNS):
-            result.append(
-                {
-                    "page_id": str(page_id or ""),
-                    "title": str(title),
-                    "error": str(entry.get("error") or entry.get("error_message") or ""),
-                }
-            )
-    return result
-
-
-def _discover_latest_crawl_manifest(root_dir: Path) -> Path | None:
-    if not root_dir.exists() or not root_dir.is_dir():
-        return None
-    candidates: list[Path] = []
-    for candidate in root_dir.rglob("crawl_manifest.json"):
-        if candidate.is_file():
-            candidates.append(candidate)
-    if not candidates:
-        return None
-    return max(candidates, key=lambda path: path.stat().st_mtime)
-
-
-def _load_json_dict(path: Path) -> dict[str, Any]:
-    payload = json.loads(path.read_text(encoding="utf-8"))
-    if not isinstance(payload, dict):
-        raise ValueError(f"Expected JSON object in {path}")
-    return payload
-
-
-def _runtime_entry_has_throttle_signal(entry: dict[str, Any]) -> bool:
-    event = str(entry.get("event") or "").strip().lower()
-    if any(token in event for token in _CRAWL_STATUS_THROTTLE_EVENT_HINTS):
-        return True
-    if entry.get("rate_limited") is True:
-        return True
-    status_code = entry.get("status_code")
-    if _safe_int(status_code) == 429:
-        return True
-    reason = str(entry.get("reason") or "").strip().lower()
-    return reason in {"http_429", "timeout"}
-
-
-def _summarize_runtime_logs_for_crawl_status(*, log_file: Path, tail: int) -> dict[str, Any]:
-    payload: dict[str, Any] = {
-        "log_file": str(log_file),
-        "exists": log_file.exists(),
-        "entries_scanned": 0,
-        "entries_considered": 0,
-        "parse_errors": 0,
-        "warning_total": 0,
-        "error_total": 0,
-        "throttle_total": 0,
-    }
-    if not log_file.exists():
-        return payload
-
-    recent_entries: deque[dict[str, Any]] = deque(maxlen=max(1, tail))
-    with log_file.open("r", encoding="utf-8") as handle:
-        for raw_line in handle:
-            payload["entries_scanned"] = int(payload["entries_scanned"]) + 1
-            line = raw_line.strip()
-            if not line:
-                continue
-            try:
-                entry = json.loads(line)
-            except json.JSONDecodeError:
-                payload["parse_errors"] = int(payload["parse_errors"]) + 1
-                continue
-            if isinstance(entry, dict):
-                recent_entries.append(entry)
-
-    payload["entries_considered"] = len(recent_entries)
-    for entry in recent_entries:
-        level = str(entry.get("level") or "").strip().lower()
-        if level == "warning":
-            payload["warning_total"] = int(payload["warning_total"]) + 1
-        if level in {"error", "critical"}:
-            payload["error_total"] = int(payload["error_total"]) + 1
-        if _runtime_entry_has_throttle_signal(entry):
-            payload["throttle_total"] = int(payload["throttle_total"]) + 1
-    return payload
-
-
-def _collect_crawl_manifest_status(*, manifest_payload: dict[str, Any], manifest_path: Path) -> dict[str, Any]:
-    crawl_section = manifest_payload.get("crawl")
-    if isinstance(crawl_section, dict):
-        resume_state = crawl_section.get("resume_state") if isinstance(crawl_section.get("resume_state"), dict) else {}
-        crawl_mode = crawl_section.get("crawl_mode") if isinstance(crawl_section.get("crawl_mode"), dict) else {}
-        if not crawl_mode:
-            crawl_mode = {
-                "page_concurrency": crawl_section.get("page_concurrency") or crawl_section.get("crawl_concurrency"),
-                "staged_mode": crawl_section.get("staged_mode") or crawl_section.get("staged_crawl_mode"),
-            }
-        if not resume_state:
-            resume_state = {
-                "nodes_processed": crawl_section.get("nodes_processed"),
-                "pending_queue_size": crawl_section.get("pending_queue_size"),
-                "skipped_unchanged": crawl_section.get("skipped_unchanged"),
-                "skipped_already_visited": crawl_section.get("skipped_already_visited"),
-                "completed": crawl_section.get("completed"),
-                "termination_reason": crawl_section.get("termination_reason"),
-            }
-        child_pages = (
-            manifest_payload.get("child_pages") if isinstance(manifest_payload.get("child_pages"), list) else []
-        )
-        attachments = (
-            manifest_payload.get("attachments") if isinstance(manifest_payload.get("attachments"), list) else []
-        )
-        root_page = manifest_payload.get("page") if isinstance(manifest_payload.get("page"), dict) else {}
-        root_page_id = (
-            str(
-                root_page.get("page_id")
-                or manifest_payload.get("page_id")
-                or manifest_payload.get("root_page_id")
-                or ""
-            ).strip()
-            or None
-        )
-        generated_at = manifest_payload.get("generated_at")
-    else:
-        resume_state = (
-            manifest_payload.get("resume_state") if isinstance(manifest_payload.get("resume_state"), dict) else {}
-        )
-        crawl_mode = manifest_payload.get("crawl_mode") if isinstance(manifest_payload.get("crawl_mode"), dict) else {}
-        child_pages = (
-            manifest_payload.get("child_pages") if isinstance(manifest_payload.get("child_pages"), list) else []
-        )
-        attachments = (
-            manifest_payload.get("attachments") if isinstance(manifest_payload.get("attachments"), list) else []
-        )
-        root_page = manifest_payload.get("page") if isinstance(manifest_payload.get("page"), dict) else {}
-        root_page_id = str(manifest_payload.get("root_page_id") or root_page.get("page_id") or "").strip() or None
-        generated_at = manifest_payload.get("generated_at")
-
-    root_status = str(root_page.get("status") or "").strip().lower()
-    page_error_total = 1 if root_status in {"error", "failed"} else 0
-    child_error_total = _collect_entry_error_total(child_pages)
-    attachment_error_total = _collect_entry_error_total(attachments)
-    permission_denied_pages = _collect_permission_denied_pages(child_pages)
-    return {
-        "manifest_path": str(manifest_path),
-        "root_page_id": root_page_id,
-        "generated_at": generated_at,
-        "crawl_mode": {
-            "page_concurrency": crawl_mode.get("page_concurrency"),
-            "staged_mode": crawl_mode.get("staged_mode"),
-        },
-        "progress": {
-            "nodes_processed": _safe_int(resume_state.get("nodes_processed")),
-            "pending_queue_size": _safe_int(resume_state.get("pending_queue_size")),
-            "skipped_unchanged": _safe_int(resume_state.get("skipped_unchanged")),
-            "skipped_already_visited": _safe_int(resume_state.get("skipped_already_visited")),
-            "completed": bool(resume_state.get("completed")) if "completed" in resume_state else None,
-            "termination_reason": resume_state.get("termination_reason"),
-            "child_pages_total": len(child_pages),
-            "attachments_total": len(attachments),
-        },
-        "errors": {
-            "page_error_total": page_error_total,
-            "child_page_error_total": child_error_total,
-            "attachment_error_total": attachment_error_total,
-            "total": page_error_total + child_error_total + attachment_error_total,
-        },
-        "permission_denied_pages": permission_denied_pages,
-        "permission_denied_count": len(permission_denied_pages),
-    }
-
-
-_CORRELATION_SINCE_PATTERN = re.compile(r"^(?P<value>\d+)(?P<unit>[smhdw])$", re.IGNORECASE)
-
-
-def _format_shell_command(command: list[str]) -> str:
-    return " ".join(shlex.quote(part) for part in command)
-
-
-def _resolve_correlation_window(*, since: str) -> tuple[str, str]:
-    raw_since = since.strip()
-    match = _CORRELATION_SINCE_PATTERN.fullmatch(raw_since)
-    if not match:
-        raise ValueError("--since must use <number><unit> where unit is one of: s, m, h, d, w.")
-
-    value = int(match.group("value"))
-    unit = match.group("unit").lower()
-    multiplier = {
-        "s": 1,
-        "m": 60,
-        "h": 3600,
-        "d": 86400,
-        "w": 604800,
-    }[unit]
-    window_seconds = value * multiplier
-
-    end_ts = datetime.now(UTC).replace(microsecond=0)
-    start_ts = (end_ts - timedelta(seconds=window_seconds)).replace(microsecond=0)
-    return (
-        start_ts.isoformat().replace("+00:00", "Z"),
-        end_ts.isoformat().replace("+00:00", "Z"),
-    )
-
-
-def _quote_query_value(value: str) -> str:
-    escaped = value.replace("\\", "\\\\").replace('"', '\\"')
-    return f'"{escaped}"'
-
-
-def _build_grafana_correlation_query(*, service: str | None, audit_id: str | None) -> str:
-    clauses = ["(severity_text:ERROR OR severity_text:FATAL OR severity_text:CRITICAL)"]
-    service_token = (service or "").strip()
-    audit_token = (audit_id or "").strip()
-    if service_token:
-        quoted = _quote_query_value(service_token)
-        clauses.insert(0, f"(service_name:{quoted} OR service.name:{quoted})")
-    if audit_token:
-        quoted = _quote_query_value(audit_token)
-        clauses.append(f"(audit_id:{quoted} OR request_id:{quoted} OR trace_id:{quoted})")
-    return " AND ".join(clauses)
-
-
-def _build_elastic_correlation_query(*, service: str | None, audit_id: str | None) -> str:
-    clauses = ["(level:ERROR OR log.level:ERROR OR severity_text:ERROR)"]
-    service_token = (service or "").strip()
-    audit_token = (audit_id or "").strip()
-    if service_token:
-        quoted = _quote_query_value(service_token)
-        clauses.insert(0, f"(service_name:{quoted} OR service.name:{quoted})")
-    if audit_token:
-        quoted = _quote_query_value(audit_token)
-        clauses.append(f"(audit_id:{quoted} OR request_id:{quoted} OR trace_id:{quoted} OR trace.id:{quoted})")
-    return " AND ".join(clauses)
-
-
-def _collect_external_observability_status() -> dict[str, Any]:
-    load_shared_env()
-    has_grafana_url = bool((os.getenv("VDS_GRAFANA_URL") or "").strip())
-    has_grafana_user = bool((os.getenv("VDS_GRAFANA_USER") or "").strip())
-    has_grafana_password = bool((os.getenv("VDS_GRAFANA_PASSWORD") or "").strip())
-    has_grafana_token = bool((os.getenv("VDS_GRAFANA_TOKEN") or "").strip())
-    grafana_auth_ready = has_grafana_token or (has_grafana_user and has_grafana_password)
-    grafana_ready = has_grafana_url and grafana_auth_ready
-
-    has_elastic_kibana_url = bool((os.getenv("VDS_ELASTIC_KIBANA_URL") or "").strip())
-    has_elastic_kibana_ip = bool((os.getenv("VDS_ELASTIC_KIBANA_IP") or "").strip())
-    has_elastic_user = bool((os.getenv("VDS_ELASTIC_USER") or "").strip())
-    has_elastic_password = bool((os.getenv("VDS_ELASTIC_PASSWORD") or "").strip())
-    elastic_ready = has_elastic_kibana_url and has_elastic_kibana_ip and has_elastic_user and has_elastic_password
-
-    return {
-        "env_path": _PRIMARY_SHARED_ENV_PATH,
-        "grafana": {
-            "url_set": has_grafana_url,
-            "user_set": has_grafana_user,
-            "password_set": has_grafana_password,
-            "token_set": has_grafana_token,
-            "auth_ready": grafana_auth_ready,
-            "ready": grafana_ready,
-        },
-        "elastic": {
-            "kibana_url_set": has_elastic_kibana_url,
-            "kibana_ip_set": has_elastic_kibana_ip,
-            "user_set": has_elastic_user,
-            "password_set": has_elastic_password,
-            "ready": elastic_ready,
-        },
-    }
-
-
-def _build_correlation_command_templates(
-    *,
-    runtime_log_file: Path,
-    since: str,
-    service: str | None,
-    audit_id: str | None,
-    grafana_index: str | None,
-    elastic_index: str,
-    limit: int,
-    tail: int,
-    start_iso: str,
-    end_iso: str,
-) -> dict[str, str]:
-    runtime_command = [
-        "uv",
-        "run",
-        "--project",
-        str(_VDS_CLI_PROJECT_DIR),
-        "vds-cli",
-        "audit",
-        "--json-only",
-        "doctor",
-        "logs-follow",
-        "--log-file",
-        str(runtime_log_file),
-        "--no-follow",
-        "--tail",
-        str(tail),
-        "--json",
-    ]
-
-    grafana_query = _build_grafana_correlation_query(service=service, audit_id=audit_id)
-    grafana_command = [
-        "uv",
-        "run",
-        "--project",
-        str(_VDS_CLI_PROJECT_DIR),
-        "vds-cli",
-        "grafana",
-        "--json-only",
-        "search",
-        "--query",
-        grafana_query,
-        "--since",
-        since,
-        "--limit",
-        str(limit),
-    ]
-    if grafana_index:
-        grafana_command.extend(["--index", grafana_index])
-
-    elastic_query = _build_elastic_correlation_query(service=service, audit_id=audit_id)
-    elastic_command = [
-        "uv",
-        "run",
-        "--project",
-        str(_VDS_CLI_PROJECT_DIR),
-        "vds-cli",
-        "elastic",
-        "--json-only",
-        "search",
-        "--index",
-        elastic_index,
-        "--qs",
-        elastic_query,
-        "--start",
-        start_iso,
-        "--end",
-        end_iso,
-        "--size",
-        str(limit),
-        "--sort",
-        "@timestamp:desc",
-    ]
-
-    return {
-        "runtime_log_command": _format_shell_command(runtime_command),
-        "grafana_correlation_command": _format_shell_command(grafana_command),
-        "elastic_correlation_command": _format_shell_command(elastic_command),
-    }
-
-
-def _run_external_json_command(*, command: list[str], timeout_seconds: float) -> dict[str, Any]:
-    rendered_command = _format_shell_command(command)
-    try:
-        result = subprocess.run(
-            command,
-            capture_output=True,
-            text=True,
-            check=False,
-            timeout=timeout_seconds,
-        )
-    except Exception as exc:
-        return {
-            "command": rendered_command,
-            "exit_code": None,
-            "ok": False,
-            "error": str(exc),
-        }
-
-    payload: dict[str, Any] = {
-        "command": rendered_command,
-        "exit_code": result.returncode,
-        "ok": result.returncode == 0,
-    }
-    stdout_text = result.stdout.strip()
-    stderr_text = result.stderr.strip()
-    if stdout_text:
-        payload["stdout"] = stdout_text
-        try:
-            payload["json"] = json.loads(stdout_text)
-        except json.JSONDecodeError:
-            payload["json_parse_error"] = "stdout is not valid JSON"
-    if stderr_text:
-        payload["stderr"] = stderr_text
-    return payload
-
-
-@doctor_app.command(name="correlation")
-def doctor_correlation(
-    since: str = typer.Option(
-        "30m",
-        "--since",
-        help="Correlation lookback window (<number><unit>, units: s|m|h|d|w).",
-    ),
-    service: str | None = typer.Option(
-        None,
-        "--service",
-        help="Optional service selector for generated Grafana/Elastic queries.",
-    ),
-    audit_id: str | None = typer.Option(
-        None,
-        "--audit-id",
-        help="Optional audit/request correlation token for generated queries.",
-    ),
-    grafana_index: str | None = typer.Option(
-        None,
-        "--grafana-index",
-        help="Optional Quickwit index override for generated Grafana command.",
-    ),
-    elastic_index: str = typer.Option(
-        "*",
-        "--elastic-index",
-        help="Elasticsearch index pattern for generated Elastic command.",
-    ),
-    tail: int = typer.Option(
-        200,
-        "--tail",
-        min=1,
-        help="Tail size for runtime-log capture template.",
-    ),
-    limit: int = typer.Option(
-        200,
-        "--limit",
-        min=1,
-        max=1000,
-        help="Result size for generated Grafana/Elastic commands.",
-    ),
-    log_file: Path | None = typer.Option(
-        None,
-        "--log-file",
-        envvar="VDS_AUDIT_RUNTIME_LOG_FILE",
-        help="Runtime JSONL log file (default: effective VDS log root / vds-audit-runtime-YYYYMMDD.jsonl).",
-    ),
-    run_health: bool = typer.Option(
-        False,
-        "--run-health/--no-run-health",
-        help="Execute vds-grafana health and vds-elastic ping preflight checks.",
-    ),
-    timeout_seconds: float = typer.Option(
-        20.0,
-        "--timeout-seconds",
-        min=1.0,
-        help="Timeout for each external health command.",
-    ),
-) -> None:
-    """Build deterministic Grafana/Elastic correlation runbook commands for one audit run."""
-    try:
-        start_iso, end_iso = _resolve_correlation_window(since=since)
-    except ValueError as exc:
-        raise typer.BadParameter(str(exc), param_hint="--since") from exc
-
-    runtime_log_file = _resolve_runtime_log_file(realtime_logs=True, log_file=log_file)
-    assert runtime_log_file is not None
-
-    credentials_status = _collect_credentials_status()
-    external_status = _collect_external_observability_status()
-    commands = _build_correlation_command_templates(
-        runtime_log_file=runtime_log_file,
-        since=since,
-        service=service,
-        audit_id=audit_id,
-        grafana_index=grafana_index,
-        elastic_index=elastic_index,
-        limit=limit,
-        tail=tail,
-        start_iso=start_iso,
-        end_iso=end_iso,
-    )
-
-    errors: list[str] = []
-    shared_env_path = get_shared_env_path()
-    if not bool(external_status["grafana"]["ready"]):
-        errors.append(f"Grafana correlation env is not ready (check VDS_GRAFANA_* in {shared_env_path}).")
-    if not bool(external_status["elastic"]["ready"]):
-        errors.append(f"Elastic correlation env is not ready (check VDS_ELASTIC_* in {shared_env_path}).")
-
-    health_checks: dict[str, Any] = {}
-    if run_health:
-        grafana_health = _run_external_json_command(
-            command=[
-                "uv",
-                "run",
-                "--project",
-                str(_VDS_CLI_PROJECT_DIR),
-                "vds-cli",
-                "grafana",
-                "--json-only",
-                "health",
-            ],
-            timeout_seconds=timeout_seconds,
-        )
-        grafana_json = grafana_health.get("json")
-        grafana_ok = bool(grafana_health.get("ok"))
-        if isinstance(grafana_json, dict):
-            grafana_ok = grafana_ok and bool(grafana_json.get("grafana_ok")) and bool(grafana_json.get("datasource_ok"))
-        grafana_health["ok"] = grafana_ok
-        health_checks["grafana_health"] = grafana_health
-        if not grafana_ok:
-            errors.append("Grafana health check failed.")
-
-        elastic_ping = _run_external_json_command(
-            command=[
-                "uv",
-                "run",
-                "--project",
-                str(_VDS_CLI_PROJECT_DIR),
-                "vds-cli",
-                "elastic",
-                "--json-only",
-                "ping",
-            ],
-            timeout_seconds=timeout_seconds,
-        )
-        elastic_json = elastic_ping.get("json")
-        elastic_ok = bool(elastic_ping.get("ok"))
-        if isinstance(elastic_json, dict):
-            elastic_ok = elastic_ok and bool(elastic_json.get("success"))
-        elastic_ping["ok"] = elastic_ok
-        health_checks["elastic_ping"] = elastic_ping
-        if not elastic_ok:
-            errors.append("Elastic ping check failed.")
-
-    payload: dict[str, Any] = {
-        "status": "ok" if not errors else "error",
-        "operation": "doctor_correlation",
-        "env_path": credentials_status.get("env_path"),
-        "inputs": {
-            "since": since,
-            "service": service,
-            "audit_id": audit_id,
-            "grafana_index": grafana_index,
-            "elastic_index": elastic_index,
-            "tail": tail,
-            "limit": limit,
-            "runtime_log_file": str(runtime_log_file),
-            "run_health": run_health,
-        },
-        "time_window": {
-            "start": start_iso,
-            "end": end_iso,
-        },
-        "checks": {
-            "runtime_log_exists": runtime_log_file.exists(),
-            "grafana_env": external_status["grafana"],
-            "elastic_env": external_status["elastic"],
-        },
-        "commands": commands,
-        "errors": errors,
-    }
-    if run_health:
-        payload["health_checks"] = health_checks
-
-    if _cli_state.get("json_only"):
-        _emit_json(payload)
-        if errors:
-            raise typer.Exit(1)
-        return
-
-    table = Table(title="Correlation Doctor")
-    table.add_column("Check")
-    table.add_column("Value")
-    table.add_row("Env path", str(payload["env_path"]))
-    table.add_row("Runtime log file", str(runtime_log_file))
-    table.add_row("Runtime log exists", "yes" if payload["checks"]["runtime_log_exists"] else "no")
-    table.add_row("Grafana env ready", "yes" if payload["checks"]["grafana_env"]["ready"] else "no")
-    table.add_row("Elastic env ready", "yes" if payload["checks"]["elastic_env"]["ready"] else "no")
-    table.add_row("Window start", start_iso)
-    table.add_row("Window end", end_iso)
-    console.print(table)
-
-    console.print("\n[bold]Correlation Commands[/bold]")
-    console.print(f"1. Runtime logs: {commands['runtime_log_command']}")
-    console.print(f"2. Grafana:      {commands['grafana_correlation_command']}")
-    console.print(f"3. Elastic:      {commands['elastic_correlation_command']}")
-
-    if run_health:
-        console.print("\n[bold]Health Checks[/bold]")
-        for name, details in health_checks.items():
-            marker = "[green]ok[/green]" if details.get("ok") else "[red]failed[/red]"
-            console.print(f"- {name}: {marker} ({details.get('command')})")
-
-    if errors:
-        for err in errors:
-            console.print(f"[red]- {err}[/red]")
-        raise typer.Exit(1)
-
-
-@doctor_app.command(name="crawl-status")
-def doctor_crawl_status(
-    manifest_path: Path | None = typer.Option(
-        None,
-        "--manifest-path",
-        help="Path to crawl manifest JSON (crawl_manifest.json or extract-docs project manifest).",
-    ),
-    crawl_dir: Path | None = typer.Option(
-        None,
-        "--crawl-dir",
-        help="Directory to discover the newest crawl_manifest.json when --manifest-path is omitted.",
-    ),
-    log_file: Path | None = typer.Option(
-        None,
-        "--log-file",
-        envvar="VDS_AUDIT_RUNTIME_LOG_FILE",
-        help="Runtime JSONL log file (default: effective VDS log root / vds-audit-runtime-YYYYMMDD.jsonl).",
-    ),
-    tail: int = typer.Option(
-        300,
-        "--tail",
-        min=1,
-        help="Number of latest runtime log events to evaluate for crawl diagnostics.",
-    ),
-    json_output: bool = typer.Option(False, "--json", help="Emit crawl diagnostics as JSON."),
-) -> None:
-    """Summarize crawl manifest progress and error diagnostics."""
-    errors: list[str] = []
-    warnings_list: list[str] = []
-
-    resolved_manifest_path: Path | None = None
-    if manifest_path is not None:
-        resolved_manifest_path = manifest_path.expanduser().resolve()
-        if not resolved_manifest_path.exists():
-            errors.append(f"Crawl manifest not found: {resolved_manifest_path}")
-    elif crawl_dir is not None:
-        resolved_crawl_dir = crawl_dir.expanduser().resolve()
-        resolved_manifest_path = _discover_latest_crawl_manifest(resolved_crawl_dir)
-        if resolved_manifest_path is None:
-            errors.append(f"No crawl_manifest.json found under: {resolved_crawl_dir}")
-    else:
-        errors.append("Provide --manifest-path or --crawl-dir.")
-
-    crawl_status: dict[str, Any] | None = None
-    if not errors and resolved_manifest_path is not None:
-        try:
-            manifest_payload = _load_json_dict(resolved_manifest_path)
-            crawl_status = _collect_crawl_manifest_status(
-                manifest_payload=manifest_payload,
-                manifest_path=resolved_manifest_path,
-            )
-        except Exception as exc:
-            errors.append(f"Failed to parse crawl manifest '{resolved_manifest_path}': {exc}")
-
-    resolved_log_file = _resolve_runtime_log_file(realtime_logs=True, log_file=log_file)
-    assert resolved_log_file is not None
-    runtime_logs = _summarize_runtime_logs_for_crawl_status(log_file=resolved_log_file, tail=tail)
-    if not bool(runtime_logs.get("exists")):
-        warnings_list.append(f"Runtime log file not found: {resolved_log_file}")
-    if _safe_int(runtime_logs.get("parse_errors")) > 0:
-        warnings_list.append("Runtime log contains malformed JSON lines; diagnostics use parsed entries only.")
-
-    status = "ok"
-    if errors:
-        status = "error"
-    elif crawl_status is not None:
-        crawl_errors = _safe_int(crawl_status.get("errors", {}).get("total"))
-        pending_queue = _safe_int(crawl_status.get("progress", {}).get("pending_queue_size"))
-        crawl_completed = crawl_status.get("progress", {}).get("completed")
-        runtime_error_total = _safe_int(runtime_logs.get("error_total"))
-        if crawl_errors > 0 or pending_queue > 0 or crawl_completed is False or runtime_error_total > 0:
-            status = "warning"
-
-    payload: dict[str, Any] = {
-        "status": status,
-        "operation": "doctor_crawl_status",
-        "crawl": crawl_status,
-        "runtime_logs": runtime_logs,
-        "errors": errors,
-        "warnings": warnings_list,
-    }
-
-    if _cli_state.get("json_only") or json_output:
-        _emit_json(payload)
-        if status == "error":
-            raise typer.Exit(1)
-        return
-
-    table = Table(title="Crawl Status")
-    table.add_column("Check")
-    table.add_column("Value")
-    table.add_row("Status", status)
-    if crawl_status is not None:
-        table.add_row("Manifest", str(crawl_status.get("manifest_path") or "-"))
-        table.add_row("Root page", str(crawl_status.get("root_page_id") or "-"))
-        table.add_row("Nodes processed", str(crawl_status.get("progress", {}).get("nodes_processed", 0)))
-        table.add_row("Pending queue", str(crawl_status.get("progress", {}).get("pending_queue_size", 0)))
-        table.add_row("Errors", str(crawl_status.get("errors", {}).get("total", 0)))
-        table.add_row("Permission denied", str(crawl_status.get("permission_denied_count", 0)))
-    table.add_row("Runtime log", str(runtime_logs.get("log_file")))
-    table.add_row("Log entries considered", str(runtime_logs.get("entries_considered", 0)))
-    table.add_row("Log warnings", str(runtime_logs.get("warning_total", 0)))
-    table.add_row("Log errors", str(runtime_logs.get("error_total", 0)))
-    table.add_row("Log throttle signals", str(runtime_logs.get("throttle_total", 0)))
-    console.print(table)
-
-    for warning in warnings_list:
-        console.print(f"[yellow]- {warning}[/yellow]")
-    if errors:
-        for err in errors:
-            console.print(f"[red]- {err}[/red]")
-        raise typer.Exit(1)
-
-
-@doctor_app.command(name="logs-follow")
-def doctor_logs_follow(
-    log_file: Path | None = typer.Option(
-        None,
-        "--log-file",
-        envvar="VDS_AUDIT_RUNTIME_LOG_FILE",
-        help="Runtime JSONL log file (default: effective VDS log root / vds-audit-runtime-YYYYMMDD.jsonl).",
-    ),
-    tail: int = typer.Option(100, "--tail", min=0, help="Print last N matching events before follow."),
-    follow: bool = typer.Option(True, "--follow/--no-follow", help="Follow appended events in realtime."),
-    poll_interval: float = typer.Option(1.0, "--poll-interval", min=0.2, help="Polling interval in seconds."),
-    timeout_seconds: float | None = typer.Option(
-        None,
-        "--timeout-seconds",
-        min=1.0,
-        help="Optional timeout for follow mode.",
-    ),
-    level: str | None = typer.Option(None, "--level", help="Filter level (debug|info|warning|error|critical)."),
-    event: str | None = typer.Option(None, "--event", help="Filter by event name substring."),
-    audit_id: str | None = typer.Option(None, "--audit-id", help="Filter by exact audit_id."),
-    agent: str | None = typer.Option(None, "--agent", help="Filter by exact agent name."),
-    json_output: bool = typer.Option(False, "--json", help="Emit matched events as JSON lines."),
-) -> None:
-    """Tail and follow runtime structured logs for realtime monitoring."""
-    resolved = _resolve_runtime_log_file(realtime_logs=True, log_file=log_file)
-    if resolved is None:
-        raise typer.BadParameter("Unable to resolve runtime log path.")
-
-    start_at = perf_counter()
-    position = 0
-
-    if resolved.exists():
-        if tail > 0:
-            recent = deque(maxlen=tail)
-            with resolved.open("r", encoding="utf-8") as handle:
-                for raw in handle:
-                    raw_line = raw.strip()
-                    if not raw_line:
-                        continue
-                    try:
-                        entry = cast("dict[str, Any]", json.loads(raw_line))
-                    except json.JSONDecodeError:
-                        continue
-                    if _runtime_log_event_matches(
-                        entry,
-                        level=level,
-                        event=event,
-                        audit_id=audit_id,
-                        agent=agent,
-                    ):
-                        recent.append(entry)
-                position = handle.tell()
-            for entry in recent:
-                _emit_runtime_log_event(entry, json_output=json_output)
-        else:
-            position = resolved.stat().st_size
-    elif not follow:
-        message = f"Runtime log file not found: {resolved}"
-        if _cli_state.get("json_only") or json_output:
-            _emit_json({"error": message})
-        else:
-            console.print(f"[yellow]{message}[/yellow]")
-        raise typer.Exit(1)
-
-    if not follow:
-        return
-
-    while True:
-        if timeout_seconds is not None and (perf_counter() - start_at) >= timeout_seconds:
-            return
-
-        if not resolved.exists():
-            sleep(poll_interval)
-            continue
-
-        try:
-            current_size = resolved.stat().st_size
-            if current_size < position:
-                position = 0
-            if current_size == position:
-                sleep(poll_interval)
-                continue
-
-            with resolved.open("r", encoding="utf-8") as handle:
-                handle.seek(position)
-                new_data = handle.read()
-                position = handle.tell()
-        except OSError:
-            sleep(poll_interval)
-            continue
-
-        for raw_line in new_data.splitlines():
-            line = raw_line.strip()
-            if not line:
-                continue
-            try:
-                entry = cast("dict[str, Any]", json.loads(line))
-            except json.JSONDecodeError:
-                continue
-            if _runtime_log_event_matches(
-                entry,
-                level=level,
-                event=event,
-                audit_id=audit_id,
-                agent=agent,
-            ):
-                _emit_runtime_log_event(entry, json_output=json_output)
-
-
-@doctor_app.command(name="corpus-status")
-def doctor_corpus_status(
-    project: str = typer.Option(
-        ...,
-        "--project",
-        help="Project selector (numeric Confluence page_id or URL containing pageId=<ID>).",
-    ),
-) -> None:
-    """Report corpus health diagnostics for a project.
-
-    Shows snapshot metrics, chunk breakdowns by source_type and doc_class,
-    contamination ratio, and health status (clean/warning/contaminated).
-
-    Examples:
-        vds-audit doctor corpus-status --project 88718877
-        vds-audit --json-only doctor corpus-status --project 88718877
-    """
-    from .cli_impl import _resolve_state_dsn_from_env
-
-    dsn = _resolve_state_dsn_from_env()
-    if not dsn:
-        if _cli_state.get("json_only"):
-            _emit_json({"status": "error", "error": "VDS_AUDIT_STATE_DSN not set."})
-        else:
-            console.print("[red]VDS_AUDIT_STATE_DSN not set.[/red]")
-        raise typer.Exit(1)
-
-    # FR-268 (AC-268.3): resolve --project through select_project() with junction table
-    project = _resolve_project_key(project_identifier=project, state_dsn=dsn)
-
-    store = PostgresStateStore(dsn)
-    try:
-        # Strict project_id resolution — no key-only fallback (DD-151)
-        project_id = store.resolve_project_id(project)
-
-        result = store.corpus_status_diagnostics(project_key=project, project_id=project_id)
-        payload = {"status": "ok", **result}
-        if _cli_state.get("json_only"):
-            _emit_json(payload)
-            return
-
-        health = result.get("health_status", "unknown")
-        health_color = {"clean": "green", "warning": "yellow", "contaminated": "red"}.get(health, "white")
-        console.print(f"\n[bold]Corpus Status[/bold] — [{health_color}]{health.upper()}[/{health_color}]")
-        console.print(f"  Project: {project}")
-        console.print(f"  Snapshots:    {result.get('snapshot_count', 0)}")
-        console.print(f"  Documents:    {result.get('total_documents', 0)}")
-        console.print(f"  Chunks:       {result.get('total_chunks', 0)}")
-        console.print(f"  Artifact:     {result.get('artifact_chunks', 0)}")
-        console.print(f"  Contamination: {result.get('contamination_ratio', 0.0):.2%}")
-        console.print(
-            f"  Orphan rate:   {result.get('orphan_document_rate', 0.0):.2%}  ({result.get('orphan_code_docs', 0)}/{result.get('total_code_docs', 0)} code docs)"
-        )
-        duplicate_total = int(result.get("duplicate_uri_count", 0) or 0)
-        duplicate_latest = int(result.get("duplicate_uri_count_latest_snapshot", 0) or 0)
-        duplicate_cross_snapshot = int(result.get("duplicate_uri_count_cross_snapshot", 0) or 0)
-        console.print(
-            f"  Dup URIs:      {duplicate_total} (latest={duplicate_latest}, cross_snapshot={duplicate_cross_snapshot})"
-        )
-        console.print(f"  Truncated:     {result.get('truncated_chunk_count', 0)}")
-        console.print()
-
-        by_source = result.get("chunks_by_source_type") or {}
-        if by_source:
-            console.print("  [bold]By source_type:[/bold]")
-            for st, count in sorted(by_source.items(), key=lambda x: -x[1]):
-                console.print(f"    {st}: {count}")
-
-        by_class = result.get("chunks_by_doc_class") or {}
-        if by_class:
-            console.print("  [bold]By doc_class:[/bold]")
-            for dc, count in sorted(by_class.items(), key=lambda x: -x[1]):
-                console.print(f"    {dc}: {count}")
-
-        snapshots = result.get("snapshots") or []
-        if snapshots:
-            console.print()
-            table = Table(title="Snapshots")
-            table.add_column("Key")
-            table.add_column("Created")
-            table.add_column("Chunks", justify="right")
-            table.add_column("Priority", justify="right")
-            for snap in snapshots:
-                table.add_row(
-                    str(snap.get("snapshot_key", "")),
-                    str(snap.get("created_at", ""))[:19],
-                    str(snap.get("chunk_count", 0)),
-                    str(snap.get("priority", 0)),
-                )
-            console.print(table)
-    except Exception as exc:
-        if _cli_state.get("json_only"):
-            _emit_json({"status": "error", "error": str(exc)})
-        else:
-            console.print(f"[red]{exc}[/red]")
-        raise typer.Exit(1) from exc
-    finally:
-        store.close()
-
-
-@doctor_app.command(name="permissions")
-def doctor_permissions(
-    page_id: str = typer.Option(
-        ...,
-        "--page-id",
-        help="Confluence page ID to test permissions on (required).",
-    ),
-) -> None:
-    """Validate Confluence permissions and report which operations are available.
-
-    Tests read, edit, and attachment permissions on the specified page.
-    Provides guidance on which mode to use (full or --page-only) based on available permissions.
-    """
-    import tempfile
-    from pathlib import Path
-
-    from vds_audit_orchestrator.clients.confluence_cli_client import ConfluenceCliClient
-
-    logger.info("doctor_permissions_start", page_id=page_id)
-
-    permissions = {
-        "read": {"available": False, "tested": False, "error": None},
-        "edit": {"available": False, "tested": False, "error": None},
-        "attachment": {"available": False, "tested": False, "error": None},
-    }
-
-    client = ConfluenceCliClient()
-    errors: list[str] = []
-    warnings: list[str] = []
-
-    # Test read permission
-    try:
-        logger.info("testing_read_permission", page_id=page_id)
-        page = asyncio.run(client.get_page(page_id, expand="version"))
-        if page and isinstance(page, dict):
-            permissions["read"]["available"] = True
-            permissions["read"]["tested"] = True
-            logger.info("read_permission_confirmed", page_id=page_id)
-        else:
-            permissions["read"]["tested"] = True
-            permissions["read"]["error"] = "Page not found or no access"
-            errors.append("Read permission: Page not found or no access")
-            logger.warning("read_permission_failed", page_id=page_id, reason="page_not_found")
-    except Exception as exc:
-        permissions["read"]["tested"] = True
-        permissions["read"]["error"] = str(exc)
-        errors.append(f"Read permission test failed: {exc}")
-        logger.warning("read_permission_test_failed", page_id=page_id, error=str(exc))
-
-    # Test edit permission (only if read succeeded)
-    if permissions["read"]["available"]:
-        test_page_id = None
-        try:
-            logger.info("testing_edit_permission", parent_page_id=page_id)
-            # Create a temporary test page
-            with tempfile.NamedTemporaryFile(mode="w", suffix=".html", delete=False) as f:
-                f.write("<p>Permission test - safe to delete</p>")
-                test_body_path = Path(f.name)
-
-            # Extract space key from the parent page
-            space_key = page.get("space", {}).get("key") if isinstance(page, dict) else None
-            if not space_key:
-                # Fallback: try to get space from the page structure
-                space_key = page.get("spaceKey") if isinstance(page, dict) else None
-
-            if not space_key:
-                warnings.append("Edit permission: Could not determine space key for test page creation")
-                permissions["edit"]["tested"] = True
-                permissions["edit"]["error"] = "Could not determine space key"
-                logger.warning("edit_permission_test_skipped", reason="no_space_key")
-            else:
-                # Try to create a test page
-                import uuid
-
-                test_title = f"VDS Permission Test {uuid.uuid4().hex[:8]}"
-                logger.info("creating_test_page", space_key=space_key, title=test_title)
-
-                test_page = asyncio.run(
-                    client.create_page(
-                        space_key=space_key,
-                        title=test_title,
-                        body_file=test_body_path,
-                        parent_id=page_id,
-                    )
-                )
-
-                if test_page and isinstance(test_page, dict):
-                    test_page_id = test_page.get("id")
-                    permissions["edit"]["available"] = True
-                    permissions["edit"]["tested"] = True
-                    logger.info("edit_permission_confirmed", test_page_id=test_page_id)
-
-                    # Clean up: delete the test page
-                    if test_page_id:
-                        try:
-                            logger.info("deleting_test_page", test_page_id=test_page_id)
-                            asyncio.run(client.delete_page(test_page_id))
-                            logger.info("test_page_deleted", test_page_id=test_page_id)
-                        except Exception as cleanup_exc:
-                            warnings.append(f"Failed to delete test page {test_page_id}: {cleanup_exc}")
-                            logger.warning(
-                                "test_page_cleanup_failed", test_page_id=test_page_id, error=str(cleanup_exc)
-                            )
-                else:
-                    permissions["edit"]["tested"] = True
-                    permissions["edit"]["error"] = "Failed to create test page"
-                    errors.append("Edit permission: Failed to create test page")
-                    logger.warning("edit_permission_failed", reason="test_page_creation_failed")
-
-                # Clean up temp file
-                with contextlib.suppress(Exception):
-                    test_body_path.unlink()
-
-        except Exception as exc:
-            permissions["edit"]["tested"] = True
-            permissions["edit"]["error"] = str(exc)
-            errors.append(f"Edit permission test failed: {exc}")
-            logger.warning("edit_permission_test_failed", page_id=page_id, error=str(exc))
-
-            # Clean up temp file if it exists
-            if "test_body_path" in locals():
-                with contextlib.suppress(Exception):
-                    test_body_path.unlink()
-
-            # Try to clean up test page if it was created
-            if test_page_id:
-                with contextlib.suppress(Exception):
-                    asyncio.run(client.delete_page(test_page_id))
-
-    # Test attachment permission (only if read and edit succeeded)
-    if permissions["read"]["available"] and permissions["edit"]["available"]:
-        try:
-            logger.info("testing_attachment_permission", page_id=page_id)
-            # Create a small test attachment
-            with tempfile.NamedTemporaryFile(mode="w", suffix=".txt", delete=False) as f:
-                f.write("VDS permission test attachment")
-                test_attachment_path = Path(f.name)
-
-            # Try to upload the attachment
-            logger.info("uploading_test_attachment", page_id=page_id)
-            upload_result = asyncio.run(
-                client.upload_attachment(
-                    page_id=page_id,
-                    file_path=test_attachment_path,
-                )
-            )
-
-            if upload_result and isinstance(upload_result, dict):
-                # Attachment upload succeeded
-                attachment_id = upload_result.get("id") or upload_result.get("results", {}).get("id")
-                permissions["attachment"]["available"] = True
-                permissions["attachment"]["tested"] = True
-                logger.info("attachment_permission_confirmed", attachment_id=attachment_id)
-
-                # Try to delete the test attachment
-                if attachment_id:
-                    try:
-                        # Note: The ConfluenceCliClient doesn't have a delete_attachment method,
-                        # but we can try to use the underlying client
-                        logger.info("deleting_test_attachment", attachment_id=attachment_id)
-                        # For now, we'll just leave the attachment (it's small and harmless)
-                        # In a production implementation, we'd want to delete it
-                        logger.info(
-                            "test_attachment_cleanup_skipped",
-                            attachment_id=attachment_id,
-                            reason="no_delete_method",
-                        )
-                    except Exception as cleanup_exc:
-                        warnings.append(f"Could not clean up test attachment {attachment_id}: {cleanup_exc}")
-                        logger.warning(
-                            "test_attachment_cleanup_failed", attachment_id=attachment_id, error=str(cleanup_exc)
-                        )
-            else:
-                permissions["attachment"]["tested"] = True
-                permissions["attachment"]["error"] = "Failed to upload test attachment"
-                errors.append("Attachment permission: Failed to upload test attachment")
-                logger.warning("attachment_permission_failed", reason="upload_failed")
-
-            # Clean up temp file
-            with contextlib.suppress(Exception):
-                test_attachment_path.unlink()
-
-        except Exception as exc:
-            permissions["attachment"]["tested"] = True
-            permissions["attachment"]["error"] = str(exc)
-            errors.append(f"Attachment permission test failed: {exc}")
-            logger.warning("attachment_permission_test_failed", page_id=page_id, error=str(exc))
-
-            # Clean up temp file if it exists
-            if "test_attachment_path" in locals():
-                with contextlib.suppress(Exception):
-                    test_attachment_path.unlink()
-
-    # Determine overall status and recommended mode
-    overall_status = "ok" if not errors else ("warning" if warnings else "error")
-
-    can_use_full_mode = all(permissions[p]["available"] for p in ["read", "edit", "attachment"])
-    can_use_page_only_mode = all(permissions[p]["available"] for p in ["read", "edit"])
-
-    recommended_mode = None
-    if can_use_full_mode:
-        recommended_mode = "full"
-    elif can_use_page_only_mode:
-        recommended_mode = "--page-only"
-    else:
-        recommended_mode = "none (insufficient permissions)"
-
-    # Build payload for JSON output
-    payload = {
-        "status": overall_status,
-        "page_id": page_id,
-        "permissions": permissions,
-        "recommended_mode": recommended_mode,
-        "can_use_full_mode": can_use_full_mode,
-        "can_use_page_only_mode": can_use_page_only_mode,
-        "errors": errors,
-        "warnings": warnings,
-    }
-
-    if _cli_state.get("json_only"):
-        _emit_json(payload)
-        return
-
-    # Human-readable output
-    console.print()
-    console.print("[bold]Confluence Permissions Check[/bold]")
-    console.print(f"  Page ID: {page_id}")
-    console.print()
-
-    # Permissions table
-    table = Table(title="Permission Status")
-    table.add_column("Permission", style="cyan")
-    table.add_column("Status", style="magenta")
-    table.add_column("Details")
-
-    for perm_name, perm_data in permissions.items():
-        status_str = "✓ Available" if perm_data["available"] else "✗ Unavailable"
-        details = perm_data.get("error") or "Tested successfully"
-        table.add_row(perm_name.capitalize(), status_str, details)
-
-    console.print(table)
-    console.print()
-
-    # Recommended mode
-    console.print("[bold]Recommended Mode:[/bold]")
-    if can_use_full_mode:
-        console.print("  ✓ Full mode (all permissions available)")
-        console.print("    You can use the default workflow with attachments.")
-    elif can_use_page_only_mode:
-        console.print("  ⚠ Use --page-only mode (attachment permission missing)")
-        console.print("    Run workflows with --page-only to skip attachment operations.")
-        console.print("    Example: vds-audit workflow <repo> --thread-id <id> --page-only")
-    else:
-        console.print("  ✗ Insufficient permissions for any mode")
-        console.print("    Check that you have read and edit permissions on the target page.")
-    console.print()
-
-    # Errors and warnings
-    if errors:
-        console.print("[bold red]Errors:[/bold red]")
-        for error in errors:
-            console.print(f"  • {error}")
-        console.print()
-
-    if warnings:
-        console.print("[bold yellow]Warnings:[/bold yellow]")
-        for warning in warnings:
-            console.print(f"  • {warning}")
-        console.print()
-
-    logger.info(
-        "doctor_permissions_complete",
-        page_id=page_id,
-        overall_status=overall_status,
-        recommended_mode=recommended_mode,
-        error_count=len(errors),
-        warning_count=len(warnings),
-    )
-
-    if errors and not warnings:
-        raise typer.Exit(1)
-
-
-# ---------------------------------------------------------------------------
-# P153-B: Confluence connectivity verification
-# ---------------------------------------------------------------------------
-
-
-def _collect_confluence_connectivity_payload() -> dict[str, Any]:
-    """Probe all configured Confluence endpoints and return a status dict."""
-    return collect_confluence_connectivity_payload(timeout_seconds=30)
-
-
-@doctor_app.command(name="check-confluence")
-def doctor_check_confluence(
-    json_output: bool = typer.Option(False, "--json", help="Emit connectivity diagnostics as JSON."),
-) -> None:
-    """Probe all configured Confluence endpoints and report reachability status.
-
-    Tests each configured endpoint (internal, external, and any configured
-    alternate URLs) with a lightweight probe. When multiple endpoint labels
-    share the same exact base URL, the command reuses one exact-URL probe
-    result for those labels. Reports per-endpoint status including auth
-    mechanism, reachability, latency, and error details without emitting
-    warning-level Confluence transport logs for probe-only failures.
-
-    Exit code 0 when at least the internal server is reachable.
-    Exit code 1 when ALL endpoints are unreachable.
-    """
-    payload = _collect_confluence_connectivity_payload()
-
-    settings_error = payload.get("settings_error")
-    if settings_error:
-        if _cli_state.get("json_only") or json_output:
-            _emit_json(payload)
-        else:
-            console.print(f"[red]✗ Settings error: {settings_error}[/red]")
-        raise typer.Exit(1)
-
-    endpoints = payload.get("endpoints", [])
-
-    if _cli_state.get("json_only") or json_output:
-        _emit_json(payload)
-    else:
-        table = Table(title="Confluence Connectivity")
-        table.add_column("Endpoint", style="cyan")
-        table.add_column("URL", style="dim")
-        table.add_column("Reachable", style="bold")
-        table.add_column("Latency", style="magenta")
-        table.add_column("Auth", style="green")
-        table.add_column("Detail", style="dim")
-
-        for ep in endpoints:
-            status_str = "[green]✓ YES[/green]" if ep.get("reachable") else "[red]✗ NO[/red]"
-            latency_str = f"{ep.get('latency_ms', '?')}ms"
-            table.add_row(
-                ep.get("server", "?"),
-                ep.get("url", "?"),
-                status_str,
-                latency_str,
-                ep.get("auth", "?"),
-                ep.get("detail", "")[:80],
-            )
-
-        console.print(table)
-
-        if payload.get("any_reachable"):
-            console.print("[green]At least one endpoint is reachable.[/green]")
-        else:
-            console.print("[red]No endpoints are reachable.[/red]")
-
-    logger.info(
-        "doctor_check_confluence_complete",
-        any_reachable=payload.get("any_reachable"),
-        internal_reachable=payload.get("internal_reachable"),
-        endpoint_count=len(endpoints),
-    )
-
-    if not payload.get("any_reachable"):
-        raise typer.Exit(1)
-
-
-# ---------------------------------------------------------------------------
-# check-duplicate-pages (Phase 154, FR-154.6, TSK-154.23)
-# ---------------------------------------------------------------------------
-
-
-@doctor_app.command(name="check-duplicate-pages")
-def check_duplicate_pages(
-    project_storage_key: str = typer.Option(
-        ...,
-        "--project-storage-key",
-        help="Canonical project storage key to scan for duplicate pages.",
-    ),
-    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}).",
-    ),
-) -> None:
-    """Detect duplicate Confluence pages under a project hierarchy.
-
-    Phase 154 (FR-154.6): Scans registry entries and Confluence hierarchy,
-    classifying pages as 'canonical' (in registry), 'stale' (registry entry
-    but page deleted), or 'duplicate' (found by CQL, not in registry).
-
-    Report-only — does NOT delete or modify pages.
-    """
-    resolved_state_dsn = _resolve_state_dsn(state_dsn, required=True)
-    assert resolved_state_dsn is not None
-
-    store = PostgresStateStore(resolved_state_dsn)
-
-    from vds_audit_orchestrator.clients.confluence_cli_client import ConfluenceCliClient
-
-    try:
-        registry_entries = store.list_published_pages(project_key=project_storage_key)
-        pages: list[dict[str, Any]] = []
-        registry_page_ids: set[str] = set()
-
-        async def _verify_pages() -> None:
-            client = ConfluenceCliClient()
-            # Step 1: Check each registry entry against Confluence.
-            for entry in registry_entries:
-                page_id = str(entry.get("confluence_page_id") or "")
-                if not page_id:
-                    continue
-                registry_page_ids.add(page_id)
-                page = await client.get_content_page(page_id)
-                if page and page.get("id"):
-                    pages.append(
-                        {
-                            "page_id": page_id,
-                            "title": str(page.get("title") or entry.get("confluence_page_title") or ""),
-                            "parent_id": str(entry.get("parent_page_id") or ""),
-                            "hierarchy_role": str(entry.get("hierarchy_role") or ""),
-                            "status": "canonical",
-                        }
-                    )
-                else:
-                    pages.append(
-                        {
-                            "page_id": page_id,
-                            "title": str(entry.get("confluence_page_title") or ""),
-                            "parent_id": str(entry.get("parent_page_id") or ""),
-                            "hierarchy_role": str(entry.get("hierarchy_role") or ""),
-                            "status": "stale",
-                        }
-                    )
-
-            # Step 2: Search Confluence for pages matching known title patterns.
-            title_patterns = [
-                "Audit Results - ",
-                "Project Audit - ",
-                "Project Analysis - ",
-            ]
-            for pattern in title_patterns:
-                try:
-                    cql = f'ancestor = "{project_storage_key}" AND title ~ "{pattern}" AND type = "page"'
-                    results = await client.search_cql(cql, limit=100)
-                    for result_page in results:
-                        cql_page_id = str(result_page.get("id") or "")
-                        if cql_page_id and cql_page_id not in registry_page_ids:
-                            registry_page_ids.add(cql_page_id)
-                            pages.append(
-                                {
-                                    "page_id": cql_page_id,
-                                    "title": str(result_page.get("title") or ""),
-                                    "parent_id": "",
-                                    "hierarchy_role": "",
-                                    "status": "duplicate",
-                                }
-                            )
-                except Exception as exc:
-                    logger.warning(
-                        "check_duplicate_pages_cql_search_failed",
-                        project_storage_key=project_storage_key,
-                        pattern=pattern,
-                        error=str(exc),
-                    )
-
-        asyncio.run(_verify_pages())
-
-        report = {
-            "project_key": project_storage_key,
-            "pages": pages,
-            "summary": {
-                "canonical": sum(1 for p in pages if p["status"] == "canonical"),
-                "stale": sum(1 for p in pages if p["status"] == "stale"),
-                "duplicate": sum(1 for p in pages if p["status"] == "duplicate"),
-                "total": len(pages),
-            },
-        }
-
-        _emit_json(report)
-
-        canonical_count = report["summary"]["canonical"]
-        stale_count = report["summary"]["stale"]
-        duplicate_count = report["summary"]["duplicate"]
-
-        if duplicate_count > 0 or stale_count > 0:
-            console.print(
-                f"[yellow]Found {duplicate_count} duplicate(s), {stale_count} stale, "
-                f"{canonical_count} canonical.[/yellow]"
-            )
-        else:
-            console.print(f"[green]No duplicates found. {canonical_count} canonical page(s).[/green]")
-
-        logger.info(
-            "doctor_check_duplicate_pages_complete",
-            project_storage_key=project_storage_key,
-            canonical=canonical_count,
-            stale=stale_count,
-            duplicate=duplicate_count,
-        )
-    finally:
-        store.close()
-
-
-@doctor_app.command(name="dispatch-status")
-def doctor_dispatch_status(
-    state_dsn: str | None = typer.Option(
-        None,
-        "--state-dsn",
-        envvar=_STATE_DSN_ENV_VAR,
-        help=f"State backend DSN (fallback: {_STATE_DSN_ENV_VAR}).",
-    ),
-    run_id: str | None = typer.Option(
-        None,
-        "--run-id",
-        help="Show status for a specific dispatch run ID.",
-    ),
-    dead_threshold_seconds: int = typer.Option(
-        300,
-        "--dead-threshold-seconds",
-        help=(
-            "Phase 169: Flag running runs with no heartbeat update for longer than "
-            "this many seconds as potentially_dead (default: 300)."
-        ),
-    ),
-    json_output: bool = typer.Option(False, "--json", help="Emit dispatch status as JSON."),
-) -> None:
-    """Show dispatch run status from the dispatch_run_status VIEW."""
-    try:
-        resolved_state_dsn = _resolve_state_dsn(state_dsn, required=True)
-        assert resolved_state_dsn is not None
-        store = PostgresStateStore(resolved_state_dsn)
-        try:
-            if run_id:
-                row = store.get_dispatch_run_status(run_id)
-                runs = [row] if row is not None else []
-            else:
-                runs = store.list_active_dispatch_runs()
-        finally:
-            store.close()
-    except Exception as exc:
-        payload = {
-            "status": "fail",
-            "operation": "doctor_dispatch_status",
-            "run_id": run_id,
-            "runs": [],
-            "errors": [str(exc)],
-        }
-        if _cli_state.get("json_only") or json_output:
-            _emit_json(payload)
-        else:
-            console.print(f"[red]Dispatch status check failed: {exc}[/red]")
-        raise typer.Exit(1) from exc
-
-    # Phase 169 (P169-E, TSK-169.8): Compute heartbeat age and dead-run flag per run.
-    now = datetime.now(UTC)
-    for r in runs:
-        hb = r.get("heartbeat_at")
-        age: float | None = (now - hb).total_seconds() if hb is not None else None
-        r["heartbeat_age_seconds"] = round(age, 1) if age is not None else None
-        r["potentially_dead"] = bool(
-            r.get("run_status") == "running" and (hb is None or (age is not None and age > dead_threshold_seconds))
-        )
-
-    payload = {
-        "status": "pass" if runs else "warn",
-        "operation": "doctor_dispatch_status",
-        "run_id": run_id,
-        "run_count": len(runs),
-        "runs": runs,
-        "errors": [],
-    }
-
-    if _cli_state.get("json_only") or json_output:
-        _emit_json(payload)
-        return
-
-    if not runs:
-        console.print(
-            "[yellow]No active dispatch runs found.[/yellow]"
-            if not run_id
-            else f"[yellow]No dispatch run found for run_id={run_id}.[/yellow]"
-        )
-        return
-
-    table = Table(title="Dispatch Run Status")
-    table.add_column("Run ID")
-    table.add_column("Project")
-    table.add_column("Status")
-    table.add_column("Heartbeat")
-    table.add_column("Lanes")
-    table.add_column("Completed")
-    table.add_column("Failed")
-    table.add_column("Active")
-    table.add_column("Repos Done")
-    table.add_column("Repos Failed")
-
-    for r in runs:
-        hb_age = r.get("heartbeat_age_seconds")
-        if hb_age is None:
-            hb_display = "none"
-        elif hb_age < 60:
-            hb_display = f"{int(hb_age)}s ago"
-        else:
-            hb_display = f"{int(hb_age // 60)}m ago"
-        status_display = str(r.get("run_status", ""))
-        if r.get("potentially_dead"):
-            status_display += " [DEAD?]"
-        table.add_row(
-            str(r.get("run_id", "")),
-            str(r.get("project_key", "")),
-            status_display,
-            hb_display,
-            str(r.get("total_lanes", 0)),
-            str(r.get("completed_lanes", 0)),
-            str(r.get("failed_lanes", 0)),
-            str(r.get("active_lanes", 0)),
-            str(r.get("total_repos_completed", 0)),
-            str(r.get("total_repos_failed", 0)),
-        )
-
-    console.print(table)
-
-
-# P168-D (TSK-168.9): Doctor repair-dispatch command — force-close stuck dispatch runs.
-@doctor_app.command(name="repair-dispatch")
-def doctor_repair_dispatch(
-    state_dsn: str | None = typer.Option(
-        None,
-        "--state-dsn",
-        envvar=_STATE_DSN_ENV_VAR,
-        help=f"State backend DSN (fallback: {_STATE_DSN_ENV_VAR}).",
-    ),
-    stale_hours: int = typer.Option(
-        2,
-        "--stale-hours",
-        help="Treat runs with started_at older than this many hours as stuck (default: 2).",
-    ),
-    force: bool = typer.Option(
-        False,
-        "--force",
-        help="Auto-close all stuck runs without interactive confirmation.",
-    ),
-    json_output: bool = typer.Option(False, "--json", help="Emit repair summary as JSON."),
-) -> None:
-    """Force-close dispatch runs stuck in 'running' status past the staleness threshold.
-
-    NOTE: dispatch_runs has no updated_at column — staleness is measured from started_at.
-    """
-    try:
-        resolved_state_dsn = _resolve_state_dsn(state_dsn, required=True)
-        assert resolved_state_dsn is not None
-        store = PostgresStateStore(resolved_state_dsn)
-        # TSK-170.13: Detect incompatible schema before attempting any repair operations.
-        # A reachable but schema-incompatible DB must surface a clear diagnostic, not a
-        # confusing downstream SQL failure (e.g. "column claimed_at does not exist").
-        _compat = store._schema_compat_result
-        if _compat.status in ("incompatible_blocking", "unreachable"):
-            _blocking_reasons = [
-                f"{v.table_name}{f'.{v.column_name}' if v.column_name else ''} [{v.kind.value}]"
-                for v in _compat.violations
-                if v.is_blocking and v.repair_succeeded is not True
-            ]
-            _schema_payload: dict[str, Any] = {
-                "status": "fail",
-                "operation": "doctor_repair_dispatch",
-                "schema_compatibility": {
-                    "status": _compat.status,
-                    "blocking_reasons": _blocking_reasons,
-                },
-                "errors": [
-                    f"Schema incompatible ({_compat.status}): cannot repair dispatch runs. "
-                    f"Run 'vds-audit doctor schema' for details and remediation guidance."
-                ],
-            }
-            store.close()
-            if _cli_state.get("json_only") or json_output:
-                _emit_json(_schema_payload)
-            else:
-                console.print(f"[red]Schema incompatible ({_compat.status}) — repair-dispatch aborted.[/red]")
-                for reason in _blocking_reasons:
-                    console.print(f"  ✗ {reason}")
-                console.print("[yellow]Run: vds-audit doctor schema — for details and remediation guidance.[/yellow]")
-            raise typer.Exit(2)
-        try:
-            # Query stuck runs directly from the dispatch_runs table via the status VIEW.
-            # We use list_active_dispatch_runs() then filter by started_at staleness, since
-            # the VIEW already surfaces started_at and there is no updated_at column.
-            active_runs = store.list_active_dispatch_runs()
-            cutoff = datetime.now(UTC) - timedelta(hours=stale_hours)
-            stuck_runs = [
-                r
-                for r in active_runs
-                if r.get("run_status") == "running" and r.get("started_at") is not None and r["started_at"] < cutoff
-            ]
-        finally:
-            store.close()
-    except typer.Exit:
-        # TSK-170.13: Schema incompatibility raises typer.Exit(2) — do not swallow.
-        raise
-    except Exception as exc:
-        payload = {
-            "status": "fail",
-            "operation": "doctor_repair_dispatch",
-            "errors": [str(exc)],
-        }
-        if _cli_state.get("json_only") or json_output:
-            _emit_json(payload)
-        else:
-            console.print(f"[red]Repair-dispatch failed: {exc}[/red]")
-        raise typer.Exit(1) from exc
-
-    if not stuck_runs:
-        payload = {
-            "status": "ok",
-            "operation": "doctor_repair_dispatch",
-            "message": f"No stuck runs found (threshold: {stale_hours}h).",
-            "repaired_runs": 0,
-            "lanes_closed": 0,
-            "errors": [],
-        }
-        if _cli_state.get("json_only") or json_output:
-            _emit_json(payload)
-        else:
-            console.print(f"[green]No stuck dispatch runs found (threshold: {stale_hours}h).[/green]")
-        return
-
-    repaired: list[str] = []
-    lanes_closed_total = 0
-    repair_errors: list[str] = []
-
-    # Re-open store for repair operations
-    resolved_state_dsn_repair = _resolve_state_dsn(state_dsn, required=True)
-    assert resolved_state_dsn_repair is not None
-    repair_store = PostgresStateStore(resolved_state_dsn_repair)
-    try:
-        for run in stuck_runs:
-            run_id_str = str(run.get("run_id", ""))
-            started_at = run.get("started_at")
-
-            if not force:
-                answer = typer.confirm(
-                    f"Force-close stuck run '{run_id_str}' (started: {started_at}, status: {run.get('run_status')})?"
-                )
-                if not answer:
-                    continue
-
-            try:
-                # Resolve the external run_id → integer PK (dispatch_runs.id)
-                run_row = repair_store.get_dispatch_run(run_id=run_id_str)
-                if run_row is None:
-                    repair_errors.append(f"run_id={run_id_str}: not found via get_dispatch_run()")
-                    continue
-                run_db_id = int(run_row["id"])
-
-                # Fetch all lanes for this run
-                lanes = repair_store.get_dispatch_lanes(dispatch_run_id=run_db_id)
-                lane_finals: list[dict[str, Any]] = [
-                    {
-                        "lane_db_id": int(lane["id"]),
-                        "status": "failed",
-                        "repos_completed": int(lane.get("repos_completed") or 0),
-                        "repos_failed": int(lane.get("repos_failed") or 0),
-                    }
-                    for lane in lanes
-                ]
-                events: list[dict[str, Any]] = [
-                    {
-                        "event_type": "lane_closed_by_doctor",
-                        "dispatch_lane_id": int(lane["id"]),
-                        "payload": {"profile": str(lane.get("profile", "")), "status": "failed"},
-                    }
-                    for lane in lanes
-                ]
-                events.append(
-                    {
-                        "event_type": "run_failed",
-                        "dispatch_lane_id": None,
-                        "payload": {
-                            "termination_reason": "force_closed_by_doctor",
-                            "stale_hours": stale_hours,
-                        },
-                    }
-                )
-                repair_store.finalize_dispatch_run(
-                    run_db_id=run_db_id,
-                    run_status="failed",
-                    lane_finals=lane_finals,
-                    events=events,
-                    run_summary={
-                        "termination_reason": "force_closed_by_doctor",
-                        "stale_hours": stale_hours,
-                        "lanes_closed": len(lanes),
-                    },
-                )
-                logger.info(
-                    "dispatch_doctor_repair",
-                    run_id=run_id_str,
-                    run_db_id=run_db_id,
-                    lanes_closed=len(lanes),
-                    stale_hours=stale_hours,
-                )
-                repaired.append(run_id_str)
-                lanes_closed_total += len(lanes)
-            except Exception as exc:
-                repair_errors.append(f"run_id={run_id_str}: {exc}")
-    finally:
-        repair_store.close()
-
-    payload = {
-        "status": "ok" if not repair_errors else "partial",
-        "operation": "doctor_repair_dispatch",
-        "message": f"Repaired {len(repaired)} runs, {lanes_closed_total} lanes force-closed.",
-        "repaired_runs": len(repaired),
-        "lanes_closed": lanes_closed_total,
-        "repaired_run_ids": repaired,
-        "errors": repair_errors,
-    }
-
-    if _cli_state.get("json_only") or json_output:
-        _emit_json(payload)
-        return
-
-    if repair_errors:
-        for err in repair_errors:
-            console.print(f"[red]Error: {err}[/red]")
-    console.print(f"[green]Repaired {len(repaired)} runs, {lanes_closed_total} lanes force-closed.[/green]")
-
-
-# P170-D (TSK-170.11, TSK-170.12): Operator-facing schema inspection surface.
-@doctor_app.command(name="schema")
-def doctor_schema(
-    state_dsn: str | None = typer.Option(
-        None,
-        "--state-dsn",
-        envvar=_STATE_DSN_ENV_VAR,
-        help=f"State backend DSN (fallback: {_STATE_DSN_ENV_VAR}).",
-    ),
-    json_output: bool = typer.Option(False, "--json", help="Emit schema compatibility report as JSON."),
-) -> None:
-    """Inspect dispatch-critical schema compatibility against the Phase 170 contract.
-
-    TSK-170.11: Reports reachability, compliance classification, missing tables/columns,
-    repair outcomes, and blocking items.
-
-    TSK-170.12: Provides explicit operator remediation guidance for each non-compliant state.
-
-    Exit codes:
-      0 — compliant or repaired_now (dispatch safe to start)
-      1 — unreachable (DB not reachable)
-      2 — incompatible_blocking (schema issues prevent safe dispatch)
-    """
-    try:
-        resolved_state_dsn = _resolve_state_dsn(state_dsn, required=True)
-        assert resolved_state_dsn is not None
-        store = PostgresStateStore(resolved_state_dsn)
-    except Exception as exc:
-        payload: dict[str, Any] = {
-            "operation": "doctor_schema",
-            "status": "unreachable",
-            "db_reachable": False,
-            "dispatch_safe": False,
-            "violations": [],
-            "missing_tables": [],
-            "missing_columns": [],
-            "repaired_items": [],
-            "blocking_items": [],
-            "remediation": "Database is unreachable. Verify VDS_AUDIT_STATE_DSN and network access.",
-            "errors": [str(exc)],
-        }
-        if _cli_state.get("json_only") or json_output:
-            _emit_json(payload)
-        else:
-            console.print(f"[red]Schema check failed — DB unreachable: {exc}[/red]")
-            console.print("[yellow]Remediation: Verify VDS_AUDIT_STATE_DSN and network access.[/yellow]")
-        raise typer.Exit(1) from exc
-
-    try:
-        result = store._schema_compat_result
-        violations = result.violations
-
-        missing_tables = [
-            v.table_name
-            for v in violations
-            if v.column_name is None and not v.repair_attempted and "missing_table" in v.kind.value
-        ]
-        missing_columns = [
-            f"{v.table_name}.{v.column_name}"
-            for v in violations
-            if v.column_name is not None and not v.repair_succeeded
-        ]
-        repaired_items = [
-            f"{v.table_name}.{v.column_name or '(table)'}" for v in violations if v.repair_succeeded is True
-        ]
-        blocking_items = [
-            {"table": v.table_name, "column": v.column_name, "kind": v.kind.value, "detail": v.detail}
-            for v in violations
-            if v.is_blocking and v.repair_succeeded is not True
-        ]
-
-        db_reachable = result.status != "unreachable"
-        dispatch_safe = result.status in ("compliant", "repaired_now")
-
-        # TSK-170.12: Remediation guidance per status
-        if result.status == "compliant":
-            remediation = "Schema is fully compliant. Dispatch is safe to start."
-        elif result.status == "repaired_now":
-            remediation = (
-                "Schema was repaired automatically (additive drift). "
-                "Dispatch is safe to start. Verify repair with: vds-audit doctor schema."
-            )
-        elif result.status == "incompatible_blocking":
-            if any(v.repair_succeeded is False for v in violations):
-                remediation = (
-                    "Schema has blocking incompatibilities and auto-repair failed. "
-                    "Run: vds-audit state init (or apply DB migrations manually), "
-                    "then re-verify with: vds-audit doctor schema."
-                )
-            else:
-                remediation = (
-                    "Schema has blocking incompatibilities (missing tables/columns). "
-                    "Run: vds-audit state init to initialize the audit-state schema, "
-                    "then re-verify with: vds-audit doctor schema. "
-                    "Do NOT start DB-native dispatch until schema is compliant."
-                )
-        else:  # unreachable
-            remediation = "Database is unreachable. Verify VDS_AUDIT_STATE_DSN and network access."
-
-        violations_serialized = [
-            {
-                "kind": v.kind.value,
-                "table_name": v.table_name,
-                "column_name": v.column_name,
-                "is_blocking": v.is_blocking,
-                "repair_eligible": v.repair_eligible,
-                "repair_attempted": v.repair_attempted,
-                "repair_succeeded": v.repair_succeeded,
-                "detail": v.detail,
-            }
-            for v in violations
-        ]
-
-        payload = {
-            "operation": "doctor_schema",
-            "status": result.status,
-            "db_reachable": db_reachable,
-            "dispatch_safe": dispatch_safe,
-            "violations": violations_serialized,
-            "missing_tables": missing_tables,
-            "missing_columns": missing_columns,
-            "repaired_items": repaired_items,
-            "blocking_items": blocking_items,
-            "remediation": remediation,
-            "errors": [],
-        }
-    finally:
-        store.close()
-
-    if _cli_state.get("json_only") or json_output:
-        _emit_json(payload)
-    else:
-        # Human-readable output
-        status_color = {"compliant": "green", "repaired_now": "yellow", "incompatible_blocking": "red"}.get(
-            result.status, "red"
-        )
-        console.print(f"[{status_color}]Schema status: {result.status}[/{status_color}]")
-        console.print(f"  DB reachable:   {db_reachable}")
-        console.print(f"  Dispatch safe:  {dispatch_safe}")
-
-        if missing_tables:
-            console.print(f"\n[red]Missing tables ({len(missing_tables)}):[/red]")
-            for t in missing_tables:
-                console.print(f"  • {t}")
-
-        if missing_columns:
-            console.print(f"\n[red]Missing columns ({len(missing_columns)}):[/red]")
-            for c in missing_columns:
-                console.print(f"  • {c}")
-
-        if repaired_items:
-            console.print(f"\n[yellow]Repaired (additive, now present) ({len(repaired_items)}):[/yellow]")
-            for r in repaired_items:
-                console.print(f"  ✓ {r}")
-
-        if blocking_items:
-            console.print(f"\n[red]Blocking schema issues ({len(blocking_items)}):[/red]")
-            for b in blocking_items:
-                col_part = f".{b['column']}" if b["column"] else ""
-                console.print(f"  ✗ {b['table']}{col_part} [{b['kind']}]")
-                if b.get("detail"):
-                    console.print(f"    {b['detail']}")
-
-        console.print(f"\n[bold]Remediation:[/bold] {remediation}")
-
-    if result.status == "incompatible_blocking":
-        raise typer.Exit(2)
-    if result.status == "unreachable":
-        raise typer.Exit(1)