@ngocsangairvds/vsaf 3.2.14 → 3.2.16

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

@@ -1,1868 +0,0 @@
-"""State commands for vds-audit CLI."""
-
-# pyright: reportUnusedVariable=false
-
-from __future__ import annotations
-
-import importlib
-import json
-import re
-from collections.abc import Callable
-from datetime import UTC, datetime
-from pathlib import Path
-from typing import Any, NoReturn
-
-import typer
-from psycopg.errors import UniqueViolation
-from rich.panel import Panel
-from rich.table import Table
-
-from vds_audit_orchestrator.config import get_config, get_vds_cache_root
-from vds_audit_orchestrator.engine.confluence_checklist_contract import (
-    CANONICAL_CHECKLIST_PAGE_ID,
-    compute_stable_row_key,
-)
-from vds_audit_orchestrator.phase151_projection import project_profile_metadata, project_status_summary
-from vds_audit_orchestrator.state.store import PostgresStateStore
-
-from .cli_common import _STATE_DSN_ENV_VAR, _cli_state, console, logger, state_app
-from .cli_impl import (
-    _emit_json,
-    _require_consumer_state_dsn,
-    _run_state_command,
-)
-
-
-def _state_api_module() -> Any:
-    """Resolve the state module lazily so tests can monkeypatch sys.modules."""
-    return importlib.import_module("vds_audit_orchestrator.state")
-
-
-_RECOVERABLE_STATE_COMMAND_ERRORS: tuple[type[Exception], ...] = (
-    RuntimeError,
-    ValueError,
-    LookupError,
-    OSError,
-    TypeError,
-    AttributeError,
-    ImportError,
-)
-_LEGACY_ROW_KEY_PATTERN = re.compile(r"^CL-(\d{1,4}):row[_-](\d+)$", re.IGNORECASE)
-
-
-def _average_metric(rows: list[dict[str, Any]], key: str) -> float | None:
-    values: list[float] = []
-    for row in rows:
-        value = row.get(key)
-        if value is None or isinstance(value, bool):
-            continue
-        try:
-            values.append(float(value))
-        except (TypeError, ValueError):
-            continue
-    if not values:
-        return None
-    return sum(values) / len(values)
-
-
-def _extract_resilience_metrics(payload: dict[str, Any] | None) -> dict[str, Any]:
-    """Extract resilience metrics from a checklist_run payload (TSK-145.17).
-
-    Returns a dict with retry_count, retry_successes, failover_hops, and
-    error_recovery_rate fields.  When resilience_summary is absent (older runs
-    or runs without retry activity), all fields are None / null.
-    """
-    if not isinstance(payload, dict):
-        return {
-            "retry_count": None,
-            "retry_successes": None,
-            "failover_hops": None,
-            "error_recovery_rate": None,
-        }
-    summary = payload.get("resilience_summary")
-    if not isinstance(summary, dict):
-        return {
-            "retry_count": None,
-            "retry_successes": None,
-            "failover_hops": None,
-            "error_recovery_rate": None,
-        }
-    retry_attempts_raw = summary.get("retry_attempts")
-    retry_successes_raw = summary.get("retry_successes")
-    failover_hops_raw = summary.get("failover_hops_total")
-
-    retry_attempts = int(retry_attempts_raw) if isinstance(retry_attempts_raw, (int, float)) else None
-    retry_successes = int(retry_successes_raw) if isinstance(retry_successes_raw, (int, float)) else None
-    failover_hops = int(failover_hops_raw) if isinstance(failover_hops_raw, (int, float)) else None
-
-    if retry_attempts is not None and retry_successes is not None:
-        error_recovery_rate = round(retry_successes / max(retry_attempts, 1), 4)
-    else:
-        error_recovery_rate = None
-
-    return {
-        "retry_count": retry_attempts,
-        "retry_successes": retry_successes,
-        "failover_hops": failover_hops,
-        "error_recovery_rate": error_recovery_rate,
-    }
-
-
-def _enrich_run_with_resilience_metrics(run: dict[str, Any]) -> dict[str, Any]:
-    """Return a new run dict with resilience metrics merged in (TSK-145.17).
-
-    Reads resilience_summary from run["payload"] and merges the computed
-    metrics into a flat resilience_metrics key on the run row.
-    """
-    payload = run.get("payload")
-    metrics = _extract_resilience_metrics(payload if isinstance(payload, dict) else None)
-    return {**run, "resilience_metrics": metrics}
-
-
-def _project_run_row_phase151(run: dict[str, Any]) -> dict[str, Any]:
-    payload = run.get("payload") if isinstance(run.get("payload"), dict) else {}
-    projected = dict(run)
-    projected["status_projection"] = project_status_summary(payload)
-    projected["profile_projection"] = project_profile_metadata(payload)
-    return projected
-
-
-def _summarize_profile_performance_rows(rows: list[dict[str, Any]]) -> dict[str, Any]:
-    grouped: dict[str, list[dict[str, Any]]] = {}
-    for row in rows:
-        profile_name = str(row.get("profile_name") or "").strip() or "unknown"
-        grouped.setdefault(profile_name, []).append(row)
-
-    by_profile: list[dict[str, Any]] = []
-    for profile_name, profile_rows in sorted(grouped.items(), key=lambda item: item[0]):
-        by_profile.append(
-            {
-                "profile_name": profile_name,
-                "run_count": len(profile_rows),
-                "avg_overall_score": _average_metric(profile_rows, "overall_score"),
-                "avg_pass_rate": _average_metric(profile_rows, "pass_rate"),
-                "avg_error_rate": _average_metric(profile_rows, "error_rate"),
-                "avg_timeout_rate": _average_metric(profile_rows, "timeout_rate"),
-                "latest_created_at": max(
-                    (str(row.get("created_at") or "") for row in profile_rows),
-                    default=None,
-                )
-                or None,
-            }
-        )
-
-    return {
-        "row_count": len(rows),
-        "profile_count": len(grouped),
-        "project_count": len({str(row.get("project_key") or "").strip() for row in rows if row.get("project_key")}),
-        "repo_count": len({str(row.get("repo_key") or "").strip() for row in rows if row.get("repo_key")}),
-        "by_profile": by_profile,
-    }
-
-
-def _handle_state_command_failure(
-    *,
-    failure_label: str,
-    exc: Exception,
-    context: dict[str, Any] | None = None,
-    recovery_action: str = "emit_cli_error_and_exit_1",
-) -> NoReturn:
-    message = f"State {failure_label} failed: {exc}"
-    logger.error(
-        "state_command_failed",
-        error_type=type(exc).__name__,
-        source_module=__name__,
-        context=context or {"cli_command": failure_label},
-        recovery_action=recovery_action,
-    )
-    if _cli_state.get("json_only"):
-        _emit_json({"error": message})
-    else:
-        console.print(f"[red]{message}[/red]")
-    raise typer.Exit(1) from exc
-
-
-def _execute_state_operation(
-    *,
-    operation: Callable[[], None],
-    failure_label: str,
-    context: dict[str, Any] | None = None,
-) -> None:
-    try:
-        operation()
-    except typer.Exit:
-        raise
-    except _RECOVERABLE_STATE_COMMAND_ERRORS as exc:
-        _handle_state_command_failure(
-            failure_label=failure_label,
-            exc=exc,
-            context=context,
-            recovery_action="emit_cli_error_and_exit_1",
-        )
-    except Exception as exc:  # Defensive fallback to preserve existing CLI UX.
-        _handle_state_command_failure(
-            failure_label=failure_label,
-            exc=exc,
-            context=context,
-            recovery_action="emit_cli_error_and_exit_1_unexpected",
-        )
-
-
-def _execute_state_command(
-    *,
-    command: str,
-    failure_label: str,
-    state_dsn: str | None,
-    extra: dict[str, Any] | None = None,
-    context: dict[str, Any] | None = None,
-) -> None:
-    command_context = {"command": command, "cli_command": failure_label}
-    if context:
-        command_context.update(context)
-
-    if command == "query_departments":
-
-        def _operation() -> None:
-            resolved_dsn = _require_consumer_state_dsn(state_dsn, command="state query-departments")
-            result = _state_api_module().query_departments(
-                state_dsn=resolved_dsn,
-                department=(extra or {}).get("department"),
-                limit=(extra or {}).get("limit"),
-            )
-            payload = {
-                "status": "ok",
-                "operation": "query_departments",
-                "selectors": {"department": (extra or {}).get("department")},
-                "result": result,
-            }
-            if _cli_state.get("json_only"):
-                _emit_json(payload)
-            else:
-                table = Table(show_lines=False)
-                table.add_column("Department", style="cyan")
-                table.add_column("Page ID", style="dim")
-                table.add_column("Projects", justify="right")
-                table.add_column("Repos", justify="right")
-                for row in result:
-                    table.add_row(
-                        str(row.get("department") or "—"),
-                        str(row.get("department_page_id") or "—"),
-                        str(row.get("project_count") or 0),
-                        str(row.get("repo_count") or 0),
-                    )
-                console.print(table)
-                console.print(f"[green]Departments: {len(result)}[/green]")
-
-        _execute_state_operation(operation=_operation, failure_label=failure_label, context=command_context)
-        return
-
-    if command == "query_projects":
-
-        def _operation() -> None:
-            resolved_dsn = _require_consumer_state_dsn(state_dsn, command="state query-projects")
-            result = _state_api_module().query_projects(
-                state_dsn=resolved_dsn,
-                project=(extra or {}).get("project"),
-                department=(extra or {}).get("department"),
-                limit=(extra or {}).get("limit"),
-            )
-            payload = {
-                "status": "ok",
-                "operation": "query_projects",
-                "selectors": {"project": (extra or {}).get("project"), "department": (extra or {}).get("department")},
-                "result": result,
-            }
-            if _cli_state.get("json_only"):
-                _emit_json(payload)
-            else:
-                table = Table(show_lines=False)
-                table.add_column("Key", style="cyan")
-                table.add_column("Name", style="green")
-                table.add_column("Department", style="dim")
-                table.add_column("Repos", justify="right")
-                for row in result:
-                    table.add_row(
-                        str(row.get("project_storage_key") or "—"),
-                        str(row.get("project_name") or row.get("project_name_en") or "—"),
-                        str(row.get("department") or "—"),
-                        str(row.get("repo_count") or 0),
-                    )
-                console.print(table)
-                console.print(f"[green]Projects: {len(result)}[/green]")
-
-        _execute_state_operation(operation=_operation, failure_label=failure_label, context=command_context)
-        return
-
-    if command == "query_repos":
-
-        def _operation() -> None:
-            resolved_dsn = _require_consumer_state_dsn(state_dsn, command="state query-repos")
-            result = _state_api_module().query_repos(
-                state_dsn=resolved_dsn,
-                project=str((extra or {}).get("project") or ""),
-                repo=(extra or {}).get("repo"),
-                limit=(extra or {}).get("limit"),
-            )
-            payload = {
-                "status": "ok",
-                "operation": "query_repos",
-                "selectors": {"project": (extra or {}).get("project"), "repo": (extra or {}).get("repo")},
-                "result": result,
-            }
-            if _cli_state.get("json_only"):
-                _emit_json(payload)
-            else:
-                table = Table(show_lines=False)
-                table.add_column("Key", style="cyan")
-                table.add_column("Slug", style="green")
-                table.add_column("Project", style="dim")
-                table.add_column("Role", style="dim")
-                for row in result:
-                    table.add_row(
-                        str(row.get("repo_storage_key") or "—"),
-                        str(row.get("repo_slug") or row.get("repo_name") or "—"),
-                        str(row.get("project_storage_key") or "—"),
-                        str(row.get("role") or "—"),
-                    )
-                console.print(table)
-                console.print(f"[green]Repositories: {len(result)}[/green]")
-
-        _execute_state_operation(operation=_operation, failure_label=failure_label, context=command_context)
-        return
-
-    if command == "query_summary":
-
-        def _operation() -> None:
-            resolved_dsn = _require_consumer_state_dsn(state_dsn, command="state query-summary")
-            result = _state_api_module().query_summary(
-                state_dsn=resolved_dsn,
-                project=str((extra or {}).get("project") or ""),
-                repo=(extra or {}).get("repo"),
-                include_completeness=bool((extra or {}).get("include_completeness", True)),
-            )
-            payload = {
-                "status": "ok",
-                "operation": "query_summary",
-                "selectors": {"project": (extra or {}).get("project"), "repo": (extra or {}).get("repo")},
-                "result": result,
-            }
-            if _cli_state.get("json_only"):
-                _emit_json(payload)
-            else:
-                console.print("[green]State query_summary completed.[/green]")
-
-        _execute_state_operation(operation=_operation, failure_label=failure_label, context=command_context)
-        return
-
-    _execute_state_operation(
-        operation=lambda: _run_state_command(command, state_dsn=state_dsn, extra=extra),
-        failure_label=failure_label,
-        context=command_context,
-    )
-
-
-@state_app.command(name="init")
-def state_init(
-    state_dsn: str | None = typer.Option(
-        None,
-        "--state-dsn",
-        envvar=_STATE_DSN_ENV_VAR,
-        help=f"State backend DSN (fallback: {_STATE_DSN_ENV_VAR}).",
-    ),
-) -> None:
-    """Initialize state backend schema/storage."""
-    _execute_state_command(
-        command="init",
-        failure_label="init",
-        state_dsn=state_dsn,
-    )
-
-
-@state_app.command(name="validate")
-def state_validate(
-    state_dsn: str | None = typer.Option(
-        None,
-        "--state-dsn",
-        envvar=_STATE_DSN_ENV_VAR,
-        help=f"State backend DSN (fallback: {_STATE_DSN_ENV_VAR}).",
-    ),
-) -> None:
-    """Validate state backend connectivity/invariants."""
-    _execute_state_command(
-        command="validate",
-        failure_label="validate",
-        state_dsn=state_dsn,
-    )
-
-
-@state_app.command(name="export")
-def state_export(
-    state_dsn: str | None = typer.Option(
-        None,
-        "--state-dsn",
-        envvar=_STATE_DSN_ENV_VAR,
-        help=f"State backend DSN (fallback: {_STATE_DSN_ENV_VAR}).",
-    ),
-    output: Path | None = typer.Option(
-        None,
-        "--output",
-        "-o",
-        help="Output path for exported state snapshot.",
-    ),
-) -> None:
-    """Export state backend data."""
-    _execute_state_command(
-        command="export",
-        failure_label="export",
-        state_dsn=state_dsn,
-        extra={"output": output, "output_path": output},
-    )
-
-
-@state_app.command(name="doctor")
-def state_doctor(
-    state_dsn: str | None = typer.Option(
-        None,
-        "--state-dsn",
-        envvar=_STATE_DSN_ENV_VAR,
-        help=f"State backend DSN (fallback: {_STATE_DSN_ENV_VAR}).",
-    ),
-) -> None:
-    """Run state backend diagnostics."""
-    _execute_state_command(
-        command="doctor",
-        failure_label="doctor",
-        state_dsn=state_dsn,
-    )
-
-
-@state_app.command(name="repair")
-def state_repair(
-    state_dsn: str | None = typer.Option(
-        None,
-        "--state-dsn",
-        envvar=_STATE_DSN_ENV_VAR,
-        help=f"State backend DSN (fallback: {_STATE_DSN_ENV_VAR}).",
-    ),
-) -> None:
-    """Repair state backend inconsistencies."""
-    _execute_state_command(
-        command="repair",
-        failure_label="repair",
-        state_dsn=state_dsn,
-    )
-
-
-@state_app.command(name="list-runs")
-def state_list_runs(
-    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_storage_key: str | None = typer.Option(
-        None,
-        "--project-storage-key",
-        help="Optional project storage key filter.",
-    ),
-    run_type: str | None = typer.Option(
-        None,
-        "--run-type",
-        help="Optional run type filter (workflow|workflow_defaults|workflow_project|upload_results).",
-    ),
-    thread_id: str | None = typer.Option(
-        None,
-        "--thread-id",
-        help="Optional thread ID filter.",
-    ),
-    limit: int = typer.Option(
-        100,
-        "--limit",
-        min=1,
-        help="Maximum runs to return.",
-    ),
-) -> None:
-    """List typed run rows from centralized state with resilience metrics (TSK-145.17)."""
-
-    def _operation() -> None:
-        resolved_dsn = _require_consumer_state_dsn(state_dsn, command="state list-runs")
-        store = PostgresStateStore(resolved_dsn)
-        raw_rows = store.list_runs(
-            project_key=project_storage_key,
-            run_type=run_type,
-            thread_id=thread_id,
-            limit=limit,
-        )
-        rows = [dict(row) for row in (raw_rows or [])]
-        enriched = [_project_run_row_phase151(_enrich_run_with_resilience_metrics(row)) for row in rows]
-        if _cli_state.get("json_only"):
-            _emit_json({"status": "ok", "operation": "list_runs", "result": enriched})
-        else:
-            console.print("[green]State list_runs completed.[/green]")
-            console.print(f"Runs: {len(enriched)}")
-
-    _execute_state_operation(
-        operation=_operation,
-        failure_label="list-runs",
-        context={"command": "list_runs", "cli_command": "list-runs"},
-    )
-
-
-@state_app.command(name="list-run-roots")
-def state_list_run_roots(
-    project_storage_key: str = typer.Option(
-        ...,
-        "--project-storage-key",
-        help="Project storage key to list run roots for.",
-    ),
-    state_dsn: str | None = typer.Option(
-        None,
-        "--state-dsn",
-        envvar=_STATE_DSN_ENV_VAR,
-        help=f"State backend DSN (fallback: {_STATE_DSN_ENV_VAR}).",
-    ),
-    limit: int = typer.Option(
-        100,
-        "--limit",
-        min=1,
-        help="Maximum run roots to return.",
-    ),
-) -> None:
-    """List available run roots for a project, showing thread_id and run_root path."""
-    _execute_state_command(
-        command="list_run_roots",
-        failure_label="list-run-roots",
-        state_dsn=state_dsn,
-        extra={
-            "project_key": project_storage_key,
-            "limit": limit,
-        },
-    )
-
-
-@state_app.command(name="show-run")
-def state_show_run(
-    run_id: str = typer.Option(..., "--run-id", help="Run ID to inspect."),
-    include_events: bool = typer.Option(
-        False,
-        "--include-events/--no-include-events",
-        help="Include run_events in the response payload.",
-    ),
-    state_dsn: str | None = typer.Option(
-        None,
-        "--state-dsn",
-        envvar=_STATE_DSN_ENV_VAR,
-        help=f"State backend DSN (fallback: {_STATE_DSN_ENV_VAR}).",
-    ),
-) -> None:
-    """Show one typed run row by run ID."""
-
-    def _operation() -> None:
-        resolved_dsn = _require_consumer_state_dsn(state_dsn, command="state show-run")
-        store = PostgresStateStore(resolved_dsn)
-        try:
-            result = store.show_run(run_id=run_id)
-            payload: dict[str, Any] = {"status": "ok", "operation": "show_run", "result": None}
-            if result is not None:
-                run_row = _project_run_row_phase151(_enrich_run_with_resilience_metrics(dict(result)))
-                result_payload: dict[str, Any] = {"run": run_row}
-                if include_events:
-                    result_payload["events"] = store.list_run_events(run_id=run_id, limit=None)
-                payload["result"] = result_payload
-            if _cli_state.get("json_only"):
-                _emit_json(payload)
-            else:
-                console.print("[green]State show_run completed.[/green]")
-        finally:
-            store.close()
-
-    _execute_state_operation(
-        operation=_operation,
-        failure_label="show-run",
-        context={"command": "show_run", "cli_command": "show-run"},
-    )
-
-
-@state_app.command(name="profile-stats")
-def state_profile_stats(
-    profile: str | None = typer.Option(
-        None,
-        "--profile",
-        help="Optional profile name filter (for example codex-chatgpt).",
-    ),
-    project_storage_key: str | None = typer.Option(
-        None,
-        "--project-storage-key",
-        help="Optional project storage key filter.",
-    ),
-    repo_storage_key: str | None = typer.Option(
-        None,
-        "--repo-storage-key",
-        help="Optional repo storage key filter (applied after query).",
-    ),
-    last_n: int = typer.Option(
-        50,
-        "--last-n",
-        min=1,
-        max=1000,
-        help="Maximum number of profile-performance rows to query.",
-    ),
-    state_dsn: str | None = typer.Option(
-        None,
-        "--state-dsn",
-        envvar=_STATE_DSN_ENV_VAR,
-        help=f"State backend DSN (fallback: {_STATE_DSN_ENV_VAR}).",
-    ),
-) -> None:
-    """Query profile performance registry rows and summary metrics."""
-    resolved_dsn = _require_consumer_state_dsn(state_dsn, command="state profile-stats")
-    store = PostgresStateStore(resolved_dsn)
-    try:
-        rows_raw = store.query_profile_performance(
-            profile_name=profile,
-            project_key=project_storage_key,
-            last_n=last_n,
-        )
-        rows = [dict(row) for row in rows_raw]
-        if repo_storage_key:
-            rows = [row for row in rows if str(row.get("repo_key") or "").strip() == repo_storage_key]
-        summary = _summarize_profile_performance_rows(rows)
-        payload = {
-            "status": "ok",
-            "operation": "state_profile_stats",
-            "filters": {
-                "profile": profile,
-                "project_storage_key": project_storage_key,
-                "repo_storage_key": repo_storage_key,
-                "last_n": last_n,
-            },
-            "summary": summary,
-            "rows": rows,
-        }
-        if _cli_state.get("json_only"):
-            _emit_json(payload)
-            return
-
-        console.print(
-            Panel.fit(
-                f"[bold]Rows:[/bold] {summary['row_count']}  "
-                f"[bold]Profiles:[/bold] {summary['profile_count']}  "
-                f"[bold]Projects:[/bold] {summary['project_count']}  "
-                f"[bold]Repos:[/bold] {summary['repo_count']}",
-                title="Profile Performance Stats",
-            )
-        )
-        if not rows:
-            console.print("[yellow]No profile performance rows matched the supplied filters.[/yellow]")
-            return
-
-        table = Table(show_lines=False)
-        table.add_column("Profile", style="cyan")
-        table.add_column("Project", style="green")
-        table.add_column("Repo", style="green")
-        table.add_column("Run ID", style="dim")
-        table.add_column("Score", justify="right")
-        table.add_column("Pass", justify="right")
-        table.add_column("Error", justify="right")
-        table.add_column("Timeout", justify="right")
-        table.add_column("Created", style="dim")
-
-        for row in rows:
-            score = row.get("overall_score")
-            pass_rate = row.get("pass_rate")
-            error_rate = row.get("error_rate")
-            timeout_rate = row.get("timeout_rate")
-            table.add_row(
-                str(row.get("profile_name") or "—"),
-                str(row.get("project_key") or "—"),
-                str(row.get("repo_key") or "—"),
-                str(row.get("run_id") or "—"),
-                f"{float(score):.2f}" if score is not None else "—",
-                f"{float(pass_rate):.3f}" if pass_rate is not None else "—",
-                f"{float(error_rate):.3f}" if error_rate is not None else "—",
-                f"{float(timeout_rate):.3f}" if timeout_rate is not None else "—",
-                str(row.get("created_at") or "—"),
-            )
-        console.print(table)
-    finally:
-        store.close()
-
-
-@state_app.command(name="list-snapshots")
-def state_list_snapshots(
-    project_storage_key: str = typer.Option(
-        ...,
-        "--project-storage-key",
-        help="Project storage key to list snapshot artifacts for.",
-    ),
-    state_dsn: str | None = typer.Option(
-        None,
-        "--state-dsn",
-        envvar=_STATE_DSN_ENV_VAR,
-        help=f"State backend DSN (fallback: {_STATE_DSN_ENV_VAR}).",
-    ),
-    limit: int = typer.Option(
-        200,
-        "--limit",
-        min=1,
-        help="Maximum snapshot rows to return.",
-    ),
-) -> None:
-    """List project-scoped artifact snapshots from centralized state."""
-    _execute_state_command(
-        command="list_snapshots",
-        failure_label="list-snapshots",
-        state_dsn=state_dsn,
-        extra={
-            "project_storage_key": project_storage_key,
-            "limit": limit,
-        },
-    )
-
-
-@state_app.command(name="resolve-run-input")
-def state_resolve_run_input(
-    project: str = typer.Option(
-        ...,
-        "--project",
-        help="Project identifier to resolve (storage key, page ID, or project name).",
-    ),
-    repo: str | None = typer.Option(
-        None,
-        "--repo",
-        help="Optional repository selector (repo key, slug, storage key, or URL).",
-    ),
-    state_dsn: str | None = typer.Option(
-        None,
-        "--state-dsn",
-        envvar=_STATE_DSN_ENV_VAR,
-        help=f"State backend DSN (fallback: {_STATE_DSN_ENV_VAR}).",
-    ),
-) -> None:
-    """Resolve canonical project/repo run input from centralized state."""
-    _execute_state_command(
-        command="resolve_run_input",
-        failure_label="resolve-run-input",
-        state_dsn=state_dsn,
-        extra={
-            "project": project,
-            "project_identifier": project,
-            "repo": repo,
-            "repo_identifier": repo,
-        },
-    )
-
-
-@state_app.command(name="workflow-params")
-def state_resolve_workflow_run_parameters(
-    project: str = typer.Option(
-        ...,
-        "--project",
-        help="Project identifier to resolve (storage key, page ID, or project name).",
-    ),
-    repo: str | None = typer.Option(
-        None,
-        "--repo",
-        help="Optional repository selector (repo key, slug, storage key, or URL).",
-    ),
-    state_dsn: str | None = typer.Option(
-        None,
-        "--state-dsn",
-        envvar=_STATE_DSN_ENV_VAR,
-        help=f"State backend DSN (fallback: {_STATE_DSN_ENV_VAR}).",
-    ),
-) -> None:
-    """Resolve reusable workflow parameters from Postgres run ledger."""
-    _execute_state_command(
-        command="resolve_workflow_run_parameters",
-        failure_label="workflow-params",
-        state_dsn=state_dsn,
-        extra={
-            "project": project,
-            "project_identifier": project,
-            "repo": repo,
-            "repo_identifier": repo,
-        },
-    )
-
-
-@state_app.command(name="readiness")
-def state_readiness(
-    project: str = typer.Option(
-        ...,
-        "--project",
-        help="Project identifier to resolve (storage key, page ID, or project name).",
-    ),
-    repo: str | None = typer.Option(
-        None,
-        "--repo",
-        help="Optional repository selector (repo key, slug, storage key, or URL).",
-    ),
-    skip_completeness_check: bool = typer.Option(
-        False,
-        "--skip-completeness-check",
-        help="Skip completeness assessment in readiness check (TSK-126.11).",
-    ),
-    state_dsn: str | None = typer.Option(
-        None,
-        "--state-dsn",
-        envvar=_STATE_DSN_ENV_VAR,
-        help=f"State backend DSN (fallback: {_STATE_DSN_ENV_VAR}).",
-    ),
-) -> None:
-    """Return project/repo readiness status from centralized state metadata."""
-    _execute_state_command(
-        command="readiness",
-        failure_label="readiness",
-        state_dsn=state_dsn,
-        extra={
-            "project": project,
-            "project_identifier": project,
-            "repo": repo,
-            "repo_identifier": repo,
-            "skip_completeness_check": skip_completeness_check,
-        },
-    )
-
-
-@state_app.command(name="completeness")
-def state_completeness(
-    project: str = typer.Option(
-        ...,
-        "--project",
-        help="Project identifier to resolve (storage key, page ID, or project name).",
-    ),
-    deep_check: bool = typer.Option(
-        False,
-        "--deep-check",
-        help="Enable remote signal validation (slower but more accurate).",
-    ),
-    skip_stale: bool = typer.Option(
-        False,
-        "--skip-stale",
-        help="Skip materials that are cached but stale (faster).",
-    ),
-    min_threshold: float = typer.Option(
-        80.0,
-        "--min-threshold",
-        min=0.0,
-        max=100.0,
-        help="Minimum completeness threshold percentage (default: 80).",
-    ),
-    state_dsn: str | None = typer.Option(
-        None,
-        "--state-dsn",
-        envvar=_STATE_DSN_ENV_VAR,
-        help=f"State backend DSN (fallback: {_STATE_DSN_ENV_VAR}).",
-    ),
-) -> None:
-    """Return material completeness assessment from project_preparation.sync_metadata (TSK-126.10).
-
-    Reads the stored completeness report from the last completeness check run,
-    showing metrics like:
-    - completeness_pct: Percentage of required materials that are prepared
-    - freshness_pct: Percentage of prepared materials that are fresh
-    - readiness_status: ready/needs_attention/critical based on thresholds
-
-    Note: This command reads stored completeness data. To run a fresh completeness
-    check with remote signal validation, use the MaterialCompletenessService directly.
-
-    Example:
-        vds-audit state completeness --project 88718940
-        vds-audit state completeness --project 88718940 --min-threshold 90
-    """
-    _execute_state_command(
-        command="completeness",
-        failure_label="completeness",
-        state_dsn=state_dsn,
-        extra={
-            "project": project,
-            "project_identifier": project,
-            "deep_check": deep_check,
-            "skip_stale": skip_stale,
-            "min_threshold": min_threshold,
-        },
-    )
-
-
-@state_app.command(name="list-links")
-def state_list_links(
-    project: str = typer.Option(
-        ...,
-        "--project",
-        help="Project identifier to resolve (storage key, page ID, or project name).",
-    ),
-    repo: str | None = typer.Option(
-        None,
-        "--repo",
-        help="Optional repository selector (repo key, slug, storage key, or URL).",
-    ),
-    state_dsn: str | None = typer.Option(
-        None,
-        "--state-dsn",
-        envvar=_STATE_DSN_ENV_VAR,
-        help=f"State backend DSN (fallback: {_STATE_DSN_ENV_VAR}).",
-    ),
-) -> None:
-    """List normalized project/repo links from centralized state snapshots."""
-    _execute_state_command(
-        command="list_links",
-        failure_label="list-links",
-        state_dsn=state_dsn,
-        extra={
-            "project": project,
-            "project_identifier": project,
-            "repo": repo,
-            "repo_identifier": repo,
-        },
-    )
-
-
-@state_app.command(name="query-departments")
-def state_query_departments(
-    department: str | None = typer.Option(None, "--department", help="Optional department selector filter."),
-    state_dsn: str | None = typer.Option(
-        None,
-        "--state-dsn",
-        envvar=_STATE_DSN_ENV_VAR,
-        help=f"State backend DSN (fallback: {_STATE_DSN_ENV_VAR}).",
-    ),
-    limit: int = typer.Option(100, "--limit", min=1, help="Maximum departments to return."),
-) -> None:
-    """Query department-level summaries from centralized state."""
-    _execute_state_command(
-        command="query_departments",
-        failure_label="query-departments",
-        state_dsn=state_dsn,
-        extra={"department": department, "limit": limit},
-    )
-
-
-@state_app.command(name="query-projects")
-def state_query_projects(
-    project: str | None = typer.Option(
-        None, "--project", help="Optional project selector (storage key, page ID, or project name)."
-    ),
-    department: str | None = typer.Option(None, "--department", help="Optional department selector filter."),
-    state_dsn: str | None = typer.Option(
-        None,
-        "--state-dsn",
-        envvar=_STATE_DSN_ENV_VAR,
-        help=f"State backend DSN (fallback: {_STATE_DSN_ENV_VAR}).",
-    ),
-    limit: int = typer.Option(100, "--limit", min=1, help="Maximum projects to return."),
-) -> None:
-    """Query project-level summaries from centralized state."""
-    _execute_state_command(
-        command="query_projects",
-        failure_label="query-projects",
-        state_dsn=state_dsn,
-        extra={"project": project, "department": department, "limit": limit},
-    )
-
-
-@state_app.command(name="query-repos")
-def state_query_repos(
-    project: str = typer.Option(..., "--project", help="Project selector (storage key, page ID, or project name)."),
-    repo: str | None = typer.Option(None, "--repo", help="Optional repository selector."),
-    state_dsn: str | None = typer.Option(
-        None,
-        "--state-dsn",
-        envvar=_STATE_DSN_ENV_VAR,
-        help=f"State backend DSN (fallback: {_STATE_DSN_ENV_VAR}).",
-    ),
-    limit: int = typer.Option(200, "--limit", min=1, help="Maximum repositories to return."),
-) -> None:
-    """Query repository-level summaries from centralized state."""
-    _execute_state_command(
-        command="query_repos",
-        failure_label="query-repos",
-        state_dsn=state_dsn,
-        extra={"project": project, "repo": repo, "limit": limit},
-    )
-
-
-@state_app.command(name="query-runs")
-def state_query_runs(
-    project: str = typer.Option(..., "--project", help="Project selector (storage key, page ID, or project name)."),
-    repo: str | None = typer.Option(None, "--repo", help="Optional repository selector."),
-    run_type: str | None = typer.Option(None, "--run-type", help="Optional run type filter."),
-    status: str | None = typer.Option(None, "--status", help="Optional lifecycle status filter."),
-    state_dsn: str | None = typer.Option(
-        None,
-        "--state-dsn",
-        envvar=_STATE_DSN_ENV_VAR,
-        help=f"State backend DSN (fallback: {_STATE_DSN_ENV_VAR}).",
-    ),
-    limit: int = typer.Option(100, "--limit", min=1, help="Maximum runs to return."),
-) -> None:
-    """Query run rows by project/repository hierarchy selectors."""
-
-    def _operation() -> None:
-        resolved_dsn = _require_consumer_state_dsn(state_dsn, command="state query-runs")
-        rows = _state_api_module().query_runs(
-            state_dsn=resolved_dsn,
-            project=project,
-            repo=repo,
-            run_type=run_type,
-            status=status,
-            limit=limit,
-        )
-        enriched = [_project_run_row_phase151(_enrich_run_with_resilience_metrics(dict(row))) for row in rows]
-        payload = {
-            "status": "ok",
-            "operation": "query_runs",
-            "selectors": {"project": project, "repo": repo},
-            "result": enriched,
-        }
-        if _cli_state.get("json_only"):
-            _emit_json(payload)
-        else:
-            console.print("[green]State query_runs completed.[/green]")
-            console.print(f"Runs: {len(enriched)}")
-
-    _execute_state_operation(
-        operation=_operation,
-        failure_label="query-runs",
-        context={"command": "query_runs", "cli_command": "query-runs"},
-    )
-
-
-@state_app.command(name="query-summary")
-def state_query_summary(
-    project: str = typer.Option(..., "--project", help="Project selector (storage key, page ID, or project name)."),
-    repo: str | None = typer.Option(None, "--repo", help="Optional repository selector."),
-    state_dsn: str | None = typer.Option(
-        None,
-        "--state-dsn",
-        envvar=_STATE_DSN_ENV_VAR,
-        help=f"State backend DSN (fallback: {_STATE_DSN_ENV_VAR}).",
-    ),
-    no_completeness: bool = typer.Option(
-        False, "--no-completeness", help="Skip completeness calculation in summary output."
-    ),
-) -> None:
-    """Query a read-only project/repository summary for downstream workflow bootstrap."""
-    _execute_state_command(
-        command="query_summary",
-        failure_label="query-summary",
-        state_dsn=state_dsn,
-        extra={"project": project, "repo": repo, "include_completeness": not no_completeness},
-    )
-
-
-@state_app.command(name="set-repo-analysis")
-def state_set_repo_analysis(
-    project: str = typer.Option(
-        ...,
-        "--project",
-        help="Project identifier to resolve (storage key, page ID, or project name).",
-    ),
-    repo: str = typer.Option(
-        ...,
-        "--repo",
-        help="Repository selector (canonical repo key preferred; slug/URL supported).",
-    ),
-    exclude: bool = typer.Option(
-        True,
-        "--exclude/--include",
-        help="Set repo analysis exclusion (default: exclude). Use --include to clear exclusion.",
-    ),
-    reason: str | None = typer.Option(
-        None,
-        "--reason",
-        help="Required when --exclude; ignored when --include.",
-    ),
-    state_dsn: str | None = typer.Option(
-        None,
-        "--state-dsn",
-        envvar=_STATE_DSN_ENV_VAR,
-        help=f"State backend DSN (fallback: {_STATE_DSN_ENV_VAR}).",
-    ),
-) -> None:
-    """Set/clear canonical repo analysis exclusion used by readiness/workflow filtering."""
-    _execute_state_command(
-        command="set_repo_analysis_exclusion",
-        failure_label="set-repo-analysis",
-        state_dsn=state_dsn,
-        extra={
-            "project": project,
-            "project_identifier": project,
-            "repo": repo,
-            "repo_identifier": repo,
-            "analysis_excluded": bool(exclude),
-            "analysis_exclusion_reason": reason,
-        },
-    )
-
-
-@state_app.command(name="compact")
-def state_compact(
-    retention_days: int = typer.Option(
-        30,
-        "--retention-days",
-        min=1,
-        help="Retain run-events newer than this number of days.",
-    ),
-    dry_run: bool = typer.Option(
-        True,
-        "--dry-run/--execute",
-        help="Preview deletion counts only; pass --execute to apply deletion.",
-    ),
-    state_dsn: str | None = typer.Option(
-        None,
-        "--state-dsn",
-        envvar=_STATE_DSN_ENV_VAR,
-        help=f"State backend DSN (fallback: {_STATE_DSN_ENV_VAR}).",
-    ),
-) -> None:
-    """Compact old run-event rows while preserving live-run events."""
-    _execute_state_command(
-        command="compact",
-        failure_label="compact",
-        state_dsn=state_dsn,
-        extra={"retention_days": retention_days, "dry_run": dry_run},
-    )
-
-
-@state_app.command(name="reconcile-runs")
-def state_reconcile_runs(
-    stale_after_minutes: int = typer.Option(
-        60,
-        "--stale-after-minutes",
-        min=1,
-        help="Mark running/pending runs older than this threshold as failed.",
-    ),
-    target_statuses: list[str] = typer.Option(
-        ["running", "pending"],
-        "--status",
-        help="Target run statuses to reconcile (repeatable).",
-    ),
-    dry_run: bool = typer.Option(
-        True,
-        "--dry-run/--execute",
-        help="Preview stale run candidates only; pass --execute to persist updates.",
-    ),
-    state_dsn: str | None = typer.Option(
-        None,
-        "--state-dsn",
-        envvar=_STATE_DSN_ENV_VAR,
-        help=f"State backend DSN (fallback: {_STATE_DSN_ENV_VAR}).",
-    ),
-) -> None:
-    """Reconcile stale run rows by finalizing abandoned running/pending executions."""
-    _execute_state_command(
-        command="reconcile_runs",
-        failure_label="reconcile-runs",
-        state_dsn=state_dsn,
-        extra={
-            "stale_after_minutes": stale_after_minutes,
-            "target_statuses": target_statuses,
-            "dry_run": dry_run,
-        },
-    )
-
-
-@state_app.command(name="index-health")
-def state_index_health(
-    state_dsn: str | None = typer.Option(
-        None,
-        "--state-dsn",
-        envvar=_STATE_DSN_ENV_VAR,
-        help=f"State backend DSN (fallback: {_STATE_DSN_ENV_VAR}).",
-    ),
-    bootstrap: bool = typer.Option(
-        False,
-        "--bootstrap/--no-bootstrap",
-        help="Attempt pgvector extension/index bootstrap before returning diagnostics.",
-    ),
-    index_type: str = typer.Option(
-        "hnsw",
-        "--index-type",
-        help="Vector index strategy when bootstrapping: hnsw|ivfflat.",
-    ),
-    dimensions: int | None = typer.Option(
-        None,
-        "--dimensions",
-        min=1,
-        help=(
-            "Embedding vector dimensions for bootstrap (for example 1024 for bge-m3). "
-            "When omitted with --bootstrap, defaults to configured embedding dimensions."
-        ),
-    ),
-) -> None:
-    """Show pgvector readiness diagnostics with lexical fallback status."""
-
-    def _operation() -> None:
-        resolved_dimensions = dimensions
-        if bootstrap and resolved_dimensions is None:
-            resolved_dimensions = int(get_config().embedding.dimensions)
-        _run_state_command(
-            "vector_index_health",
-            state_dsn=state_dsn,
-            extra={
-                "bootstrap": bootstrap,
-                "index_type": index_type,
-                "dimensions": resolved_dimensions,
-            },
-        )
-
-    _execute_state_operation(
-        operation=_operation,
-        failure_label="index-health",
-        context={"command": "vector_index_health", "cli_command": "index-health"},
-    )
-
-
-@state_app.command(name="list-retrieval-snapshots")
-def state_list_retrieval_snapshots(
-    project_storage_key: str = typer.Option(
-        ...,
-        "--project-storage-key",
-        help="Project storage key to list retrieval snapshots for.",
-    ),
-    repo_storage_key: str | None = typer.Option(
-        None,
-        "--repo-storage-key",
-        help="Optional repo storage key filter.",
-    ),
-    state_dsn: str | None = typer.Option(
-        None,
-        "--state-dsn",
-        envvar=_STATE_DSN_ENV_VAR,
-        help=f"State backend DSN (fallback: {_STATE_DSN_ENV_VAR}).",
-    ),
-    limit: int = typer.Option(
-        200,
-        "--limit",
-        min=1,
-        help="Maximum retrieval snapshot rows to return.",
-    ),
-) -> None:
-    """List retrieval snapshots with embedding lineage metadata."""
-    _execute_state_command(
-        command="list_retrieval_snapshots",
-        failure_label="list-retrieval-snapshots",
-        state_dsn=state_dsn,
-        extra={
-            "project_key": project_storage_key,
-            "repo_key": repo_storage_key,
-            "limit": limit,
-        },
-    )
-
-
-@state_app.command(name="refresh-retrieval-snapshot")
-def state_refresh_retrieval_snapshot(
-    project_storage_key: str = typer.Option(
-        ...,
-        "--project-storage-key",
-        help="Project storage key for the retrieval snapshot refresh.",
-    ),
-    snapshot_key: str = typer.Option(
-        ...,
-        "--snapshot-key",
-        help="Deterministic retrieval snapshot key to write.",
-    ),
-    chunks_path: Path = typer.Option(
-        ...,
-        "--chunks-path",
-        exists=True,
-        file_okay=True,
-        dir_okay=False,
-        help="Path to JSON/JSONL chunk manifest with chunk_id/content_hash/content_text fields.",
-    ),
-    repo_storage_key: str | None = typer.Option(
-        None,
-        "--repo-storage-key",
-        help="Optional repo storage key scope.",
-    ),
-    model: str = typer.Option(
-        "bge-m3",
-        "--model",
-        help="Embedding model override (default: bge-m3).",
-    ),
-    batch_size: int = typer.Option(
-        25,
-        "--batch-size",
-        min=1,
-        max=25,
-        help="Embedding batch size (hard cap: 25 per Ollama call).",
-    ),
-    timeout_seconds: float = typer.Option(
-        30.0,
-        "--timeout-seconds",
-        min=1.0,
-        help="Embedding request timeout in seconds.",
-    ),
-    embedding_base_url: str = typer.Option(
-        "http://127.0.0.1:11434",
-        "--embedding-base-url",
-        help="Base URL for embedding service endpoint.",
-    ),
-    index_type: str = typer.Option(
-        "hnsw",
-        "--index-type",
-        help="Vector index strategy for snapshot diagnostics: hnsw|ivfflat.",
-    ),
-    state_dsn: str | None = typer.Option(
-        None,
-        "--state-dsn",
-        envvar=_STATE_DSN_ENV_VAR,
-        help=f"State backend DSN (fallback: {_STATE_DSN_ENV_VAR}).",
-    ),
-) -> None:
-    """Refresh retrieval snapshot with default intelligent changed-only chunk persistence + embedding updates."""
-    _execute_state_command(
-        command="refresh_retrieval_snapshot",
-        failure_label="refresh-retrieval-snapshot",
-        state_dsn=state_dsn,
-        extra={
-            "project_key": project_storage_key,
-            "repo_key": repo_storage_key,
-            "snapshot_key": snapshot_key,
-            "chunks_path": chunks_path,
-            "model": model,
-            "batch_size": batch_size,
-            "timeout_seconds": timeout_seconds,
-            "embedding_base_url": embedding_base_url,
-            "index_type": index_type,
-        },
-    )
-
-
-def _extract_criterion_path(payload: dict[str, Any]) -> list[str]:
-    criterion_path = payload.get("criterion_path")
-    if isinstance(criterion_path, list):
-        return [str(item).strip() for item in criterion_path if str(item).strip()]
-    if isinstance(criterion_path, str):
-        normalized = criterion_path.strip()
-        if not normalized:
-            return []
-        return [part for part in normalized.split("/") if part.strip()]
-    return []
-
-
-def _resolve_row_index(candidate: dict[str, Any]) -> int:
-    row_index = candidate.get("row_index")
-    if isinstance(row_index, int) and row_index >= 0:
-        return row_index
-    legacy_key = str(candidate.get("row_key") or "").strip()
-    if match := _LEGACY_ROW_KEY_PATTERN.match(legacy_key):
-        return int(match.group(2))
-    return 0
-
-
-def _emit_state_migration_payload(payload: dict[str, Any]) -> None:
-    if _cli_state.get("json_only"):
-        _emit_json(payload)
-        return
-    status = str(payload.get("status") or "unknown").upper()
-    operation = str(payload.get("operation") or "state_migrate_row_keys")
-    mode = str(payload.get("mode") or "dry_run")
-    project_scope = str(payload.get("project_selector_used") or "all-projects")
-    console.print(
-        Panel.fit(
-            f"[bold]Operation:[/bold] {operation}\n"
-            f"[bold]Mode:[/bold] {mode}\n"
-            f"[bold]Status:[/bold] {status}\n"
-            f"[bold]Project scope:[/bold] {project_scope}\n"
-            f"[bold]Legacy candidates:[/bold] {payload.get('legacy_candidate_count', 0)}\n"
-            f"[bold]Updated:[/bold] {payload.get('updated_count', 0)}\n"
-            f"[bold]Skipped duplicates:[/bold] {payload.get('skipped_duplicate_count', 0)}\n"
-            f"[bold]Missing criterion_path:[/bold] {payload.get('missing_criterion_path_count', 0)}",
-            title="State Row-Key Migration",
-        )
-    )
-    if payload.get("snapshot_file"):
-        console.print(f"[cyan]Snapshot file:[/cyan] {payload['snapshot_file']}")
-    advisory = str(payload.get("advisory") or "").strip()
-    if advisory:
-        console.print(advisory)
-
-
-@state_app.command(name="migrate-row-keys")
-def state_migrate_row_keys(
-    project: str | None = typer.Option(
-        None,
-        "--project",
-        help="Optional project storage key scope for migration.",
-    ),
-    execute: bool = typer.Option(
-        False,
-        "--execute",
-        help="Apply row-key migration updates (default: dry-run only).",
-    ),
-    batch_size: int = typer.Option(
-        500,
-        "--batch-size",
-        min=1,
-        max=5000,
-        help="Batch size for scanning/updating legacy row-key rows.",
-    ),
-    verify: bool = typer.Option(
-        False,
-        "--verify",
-        help="Read-only verification of row-key migration status.",
-    ),
-    rollback: bool = typer.Option(
-        False,
-        "--rollback",
-        help="Rollback migrated row keys using snapshot JSONL.",
-    ),
-    rollback_file: Path | None = typer.Option(
-        None,
-        "--rollback-file",
-        file_okay=True,
-        dir_okay=False,
-        readable=True,
-        help="Snapshot JSONL path generated by migrate-row-keys --execute.",
-    ),
-    state_dsn: str | None = typer.Option(
-        None,
-        "--state-dsn",
-        envvar=_STATE_DSN_ENV_VAR,
-        help=f"State backend DSN (fallback: {_STATE_DSN_ENV_VAR}).",
-    ),
-) -> None:
-    """Migrate legacy CL-NNN:row_N checklist row keys to canonical stable keys."""
-    if verify and rollback:
-        raise typer.BadParameter("--verify and --rollback are mutually exclusive.")
-    if rollback and rollback_file is None:
-        raise typer.BadParameter("--rollback-file is required when --rollback is set.")
-    if rollback and not execute:
-        raise typer.BadParameter("--rollback requires --execute.")
-    resolved_dsn = _require_consumer_state_dsn(state_dsn, command="state migrate-row-keys")
-    store = PostgresStateStore(resolved_dsn)
-    try:
-        if verify:
-            summary = store.verify_row_key_migration(project_key=project)
-            payload = {
-                "status": "pass" if summary["migration_complete"] else "warn",
-                "operation": "state_migrate_row_keys",
-                "mode": "verify",
-                "project_selector_used": project,
-                **summary,
-                "safe_to_proceed": bool(summary["migration_complete"]),
-                "advisory": (
-                    "Safe to proceed: no legacy CL-NNN:row_N keys detected."
-                    if summary["migration_complete"]
-                    else "Legacy row keys still present. Run `vds-audit state migrate-row-keys --execute`."
-                ),
-                "warnings": [],
-                "errors": [],
-            }
-            _emit_state_migration_payload(payload)
-            return
-
-        if rollback:
-            assert rollback_file is not None  # Narrowing for type-checkers
-            restored_count = 0
-            skipped_duplicate_count = 0
-            skipped_scope_count = 0
-            parse_error_count = 0
-            warnings: list[str] = []
-            errors: list[str] = []
-            with rollback_file.open("r", encoding="utf-8") as handle:
-                for line_number, raw_line in enumerate(handle, start=1):
-                    line = raw_line.strip()
-                    if not line:
-                        continue
-                    try:
-                        entry = json.loads(line)
-                    except json.JSONDecodeError:
-                        parse_error_count += 1
-                        warnings.append(f"Line {line_number}: invalid JSON skipped.")
-                        continue
-                    entry_project = str(entry.get("project_key") or "").strip()
-                    if project and entry_project and entry_project != project:
-                        skipped_scope_count += 1
-                        continue
-                    row_result_id = entry.get("row_result_id")
-                    old_row_key = str(entry.get("old_row_key") or "").strip()
-                    if not isinstance(row_result_id, int) or not old_row_key:
-                        parse_error_count += 1
-                        warnings.append(f"Line {line_number}: missing row_result_id/int or old_row_key; skipped.")
-                        continue
-                    try:
-                        updated = store.update_checklist_row_key_by_id(
-                            row_result_id=row_result_id,
-                            new_row_key=old_row_key,
-                        )
-                        if updated:
-                            restored_count += 1
-                    except UniqueViolation:
-                        skipped_duplicate_count += 1
-                        warnings.append(f"Row result id {row_result_id}: duplicate row_key '{old_row_key}' skipped.")
-                    except Exception as exc:
-                        errors.append(f"Row result id {row_result_id}: rollback failed: {exc}")
-            payload = {
-                "status": "fail" if errors else ("warn" if warnings else "pass"),
-                "operation": "state_migrate_row_keys",
-                "mode": "rollback",
-                "project_selector_used": project,
-                "rollback_file": str(rollback_file),
-                "restored_count": restored_count,
-                "skipped_duplicate_count": skipped_duplicate_count,
-                "skipped_scope_count": skipped_scope_count,
-                "parse_error_count": parse_error_count,
-                "warnings": warnings[:100],
-                "errors": errors[:100],
-                "advisory": "Rollback complete." if not errors else "Rollback completed with errors.",
-            }
-            _emit_state_migration_payload(payload)
-            if errors:
-                raise typer.Exit(1)
-            return
-
-        legacy_candidate_count = store.count_legacy_row_key_candidates(project_key=project)
-        warnings: list[str] = []
-        errors: list[str] = []
-        missing_criterion_path_count = 0
-        skipped_duplicate_count = 0
-        updated_count = 0
-        sampled_rows: list[dict[str, Any]] = []
-        snapshot_file: Path | None = None
-        if execute and legacy_candidate_count > 0:
-            migration_dir = get_vds_cache_root().parent / "migrations"
-            migration_dir.mkdir(parents=True, exist_ok=True)
-            timestamp = datetime.now(UTC).strftime("%Y%m%d-%H%M%S")
-            snapshot_file = migration_dir / f"row-key-backfill-{timestamp}.jsonl"
-            with snapshot_file.open("w", encoding="utf-8") as snapshot:
-                after_id = 0
-                while True:
-                    rows = store.list_legacy_row_key_candidates(
-                        project_key=project,
-                        after_id=after_id,
-                        limit=batch_size,
-                    )
-                    if not rows:
-                        break
-                    for row in rows:
-                        after_id = max(after_id, int(row["id"]))
-                        payload = dict(row.get("payload") or {})
-                        criterion_path = _extract_criterion_path(payload)
-                        row_index = _resolve_row_index(row)
-                        if not criterion_path:
-                            missing_criterion_path_count += 1
-                            warnings.append(
-                                f"Row result id {row['id']} missing criterion_path; fallback row-{row_index} applied."
-                            )
-                        new_row_key = compute_stable_row_key(
-                            profile_id="default",
-                            page_id=CANONICAL_CHECKLIST_PAGE_ID,
-                            criterion_path=criterion_path,
-                            local_ordinal=row_index,
-                        )
-                        snapshot.write(
-                            json.dumps(
-                                {
-                                    "row_result_id": row["id"],
-                                    "checklist_run_id": row["checklist_run_id"],
-                                    "run_id": row["run_id"],
-                                    "project_key": row["project_key"],
-                                    "repo_key": row.get("repo_key"),
-                                    "row_index": row_index,
-                                    "old_row_key": row["row_key"],
-                                    "new_row_key": new_row_key,
-                                    "criterion_path": criterion_path,
-                                },
-                                ensure_ascii=True,
-                            )
-                            + "\n"
-                        )
-                        try:
-                            updated = store.update_checklist_row_key_by_id(
-                                row_result_id=int(row["id"]),
-                                new_row_key=new_row_key,
-                            )
-                            if updated:
-                                updated_count += 1
-                        except UniqueViolation:
-                            skipped_duplicate_count += 1
-                            warnings.append(
-                                f"Row result id {row['id']} duplicate canonical row_key '{new_row_key}' skipped."
-                            )
-                        except Exception as exc:
-                            errors.append(f"Row result id {row['id']} migration failed: {exc}")
-        else:
-            sample_rows = store.list_legacy_row_key_candidates(project_key=project, after_id=0, limit=20)
-            for row in sample_rows:
-                payload = dict(row.get("payload") or {})
-                criterion_path = _extract_criterion_path(payload)
-                row_index = _resolve_row_index(row)
-                if not criterion_path:
-                    missing_criterion_path_count += 1
-                sampled_rows.append(
-                    {
-                        "row_result_id": row["id"],
-                        "run_id": row["run_id"],
-                        "project_key": row["project_key"],
-                        "repo_key": row.get("repo_key"),
-                        "old_row_key": row["row_key"],
-                        "row_index": row_index,
-                        "new_row_key": compute_stable_row_key(
-                            profile_id="default",
-                            page_id=CANONICAL_CHECKLIST_PAGE_ID,
-                            criterion_path=criterion_path,
-                            local_ordinal=row_index,
-                        ),
-                        "criterion_path_present": bool(criterion_path),
-                    }
-                )
-
-        payload = {
-            "status": "fail" if errors else ("warn" if warnings else "pass"),
-            "operation": "state_migrate_row_keys",
-            "mode": "execute" if execute else "dry_run",
-            "project_selector_used": project,
-            "batch_size": batch_size,
-            "legacy_candidate_count": legacy_candidate_count,
-            "updated_count": updated_count,
-            "skipped_duplicate_count": skipped_duplicate_count,
-            "missing_criterion_path_count": missing_criterion_path_count,
-            "snapshot_file": str(snapshot_file) if snapshot_file is not None else None,
-            "samples": sampled_rows,
-            "warnings": warnings[:100],
-            "errors": errors[:100],
-            "advisory": (
-                "Dry-run complete. Re-run with --execute to apply updates."
-                if not execute
-                else (
-                    "Migration complete. Run `vds-audit state migrate-row-keys --verify` to confirm."
-                    if not errors
-                    else "Migration completed with errors. Review warnings/errors."
-                )
-            ),
-        }
-        _emit_state_migration_payload(payload)
-        if errors:
-            raise typer.Exit(1)
-    finally:
-        store.close()
-
-
-@state_app.command("estimate-resources")
-def state_estimate_resources(
-    chunk_count: int = typer.Option(
-        100000,
-        "--chunk-count",
-        "-c",
-        help="Estimated number of chunks in corpus",
-    ),
-    dimensions: int = typer.Option(
-        1024,
-        "--dimensions",
-        "-d",
-        help="Embedding vector dimensions (1024 for bge-m3)",
-    ),
-    m_value: int = typer.Option(
-        16,
-        "--m-value",
-        "-m",
-        help="HNSW M parameter (connections per node)",
-    ),
-    json_output: bool = typer.Option(False, "--json", help="Output as JSON"),
-) -> None:
-    """Estimate PostgreSQL resource requirements for vector corpus.
-
-    Uses formula from PGConf 2025:
-    Memory = (dimensions * 4 + M * 3 * 4) * chunk_count bytes
-    """
-    # Calculate HNSW index memory
-    bytes_per_vector = (dimensions * 4) + (m_value * 3 * 4)
-    total_memory_bytes = bytes_per_vector * chunk_count
-    total_memory_mb = total_memory_bytes / (1024 * 1024)
-    total_memory_gb = total_memory_bytes / (1024 * 1024 * 1024)
-
-    # Recommended shared_buffers (1.2x index size for headroom)
-    recommended_shared_buffers_mb = total_memory_mb * 1.2
-
-    # Estimate for different scales
-    estimates = {
-        "input": {
-            "chunk_count": chunk_count,
-            "dimensions": dimensions,
-            "m_value": m_value,
-        },
-        "hnsw_index": {
-            "bytes_per_vector": bytes_per_vector,
-            "total_memory_mb": round(total_memory_mb, 2),
-            "total_memory_gb": round(total_memory_gb, 2),
-        },
-        "postgresql": {
-            "recommended_shared_buffers_mb": round(recommended_shared_buffers_mb, 2),
-            "recommended_shared_buffers_gb": round(recommended_shared_buffers_mb / 1024, 2),
-        },
-        "scale_examples": {
-            "100k_chunks": {"memory_gb": round(100000 * bytes_per_vector / (1024**3), 2)},
-            "500k_chunks": {"memory_gb": round(500000 * bytes_per_vector / (1024**3), 2)},
-            "1m_chunks": {"memory_gb": round(1000000 * bytes_per_vector / (1024**3), 2)},
-        },
-    }
-
-    if json_output:
-        _emit_json(estimates)
-    else:
-        console.print(
-            Panel.fit(
-                f"[bold]Resource Estimation[/bold]\n\n"
-                f"Chunks: {chunk_count:,}\n"
-                f"Dimensions: {dimensions}\n"
-                f"HNSW M: {m_value}\n\n"
-                f"[cyan]HNSW Index Memory:[/cyan] {total_memory_gb:.2f} GB\n"
-                f"[cyan]Recommended shared_buffers:[/cyan] {recommended_shared_buffers_mb / 1024:.2f} GB\n\n"
-                f"[dim]Formula: (dims×4 + M×3×4) × chunks[/dim]",
-                title="PostgreSQL Vector Sizing",
-            )
-        )
-
-
-@state_app.command(name="skill-readiness")
-def state_skill_readiness(
-    project_storage_key: str | None = typer.Option(
-        None,
-        "--project-storage-key",
-        help="Optional project storage key for context.",
-    ),
-    repo_path: str | None = typer.Option(
-        None,
-        "--repo-path",
-        help="Optional repository path for graph-skill prerequisites.",
-    ),
-    json_output: bool = typer.Option(
-        False,
-        "--json-only",
-        help="Output diagnostics as JSON.",
-    ),
-) -> None:
-    """Display skill readiness diagnostics (Phase 125 / TSK-125.1).
-
-    Shows configured skill directories, policy-eligible counts, runtime-loaded
-    counts, blocked tools, and effective available-skill inventory.
-    """
-    from vds_audit_orchestrator.state.skill_readiness import build_skill_readiness_diagnostics
-
-    try:
-        diagnostics = build_skill_readiness_diagnostics(
-            project_storage_key=project_storage_key,
-            repo_path=repo_path,
-        )
-
-        if json_output:
-            _emit_json(diagnostics.to_dict())
-        else:
-            _render_skill_readiness_diagnostics(diagnostics)
-    except Exception as exc:
-        logger.exception("skill_readiness_failed", error=str(exc))
-        raise typer.Exit(1) from exc
-
-
-def _render_skill_readiness_diagnostics(diagnostics: Any) -> None:
-    """Render skill readiness diagnostics to console."""
-    # Header
-    console.print(
-        Panel.fit(
-            f"[bold]Skill Readiness Diagnostics[/bold]\n\n"
-            f"Policy Mode: {diagnostics.skill_policy_mode}\n"
-            f"Skills Toolset Enabled: {diagnostics.skills_toolset_enabled}\n"
-            f"Project Storage Key: {diagnostics.project_storage_key or 'N/A'}",
-            title="Phase 125 / TSK-125.1",
-        )
-    )
-
-    # Configured directories
-    dir_table = Table(title="Configured Skill Directories", show_header=True)
-    dir_table.add_column("Path", style="cyan")
-    dir_table.add_column("Exists", justify="center")
-    dir_table.add_column("Skill Count", justify="right")
-    dir_table.add_column("Error", style="red")
-
-    for dir_info in diagnostics.configured_directories:
-        exists_str = "✓" if dir_info.exists else "✗"
-        error_str = dir_info.error or ""
-        dir_table.add_row(
-            dir_info.path,
-            exists_str,
-            str(dir_info.skill_count) if dir_info.exists else "-",
-            error_str,
-        )
-
-    console.print(dir_table)
-
-    # Summary statistics
-    console.print(
-        Panel.fit(
-            f"[bold]Summary[/bold]\n\n"
-            f"Policy-Eligible Count: {diagnostics.policy_eligible_count}\n"
-            f"Runtime-Loaded Count: {diagnostics.runtime_loaded_count}\n"
-            f"Effective Available Count: {diagnostics.effective_count}\n"
-            f"Blocked Skills: {len(diagnostics.blocked_skills)}",
-        )
-    )
-
-    # Blocked skills
-    if diagnostics.blocked_skills:
-        blocked_table = Table(title="Blocked Skills", show_header=True)
-        blocked_table.add_column("Skill Name", style="cyan")
-        blocked_table.add_column("Tool Name")
-        blocked_table.add_column("Drop Reason", style="yellow")
-        blocked_table.add_column("Policy Mode")
-
-        for blocked in diagnostics.blocked_skills:
-            blocked_table.add_row(
-                blocked.skill_name,
-                blocked.tool_name,
-                blocked.drop_reason,
-                blocked.policy_mode,
-            )
-
-        console.print(blocked_table)
-
-    # Drop reasons
-    if diagnostics.drop_reasons:
-        drop_table = Table(title="Drop Reason Statistics", show_header=True)
-        drop_table.add_column("Reason", style="yellow")
-        drop_table.add_column("Count", justify="right")
-
-        for reason, count in sorted(diagnostics.drop_reasons.items(), key=lambda x: x[1], reverse=True):
-            drop_table.add_row(reason, str(count))
-
-        console.print(drop_table)
-
-    # Effective available skills
-    if diagnostics.effective_available_skills:
-        skills_panel = Panel.fit(
-            "\n".join(f"• {skill}" for skill in diagnostics.effective_available_skills),
-            title=f"Effective Available Skills ({diagnostics.effective_count})",
-        )
-        console.print(skills_panel)
-
-    # Graph-skill readiness
-    if diagnostics.graph_skills_readiness:
-        graph_table = Table(title="Graph-Review Skill Readiness", show_header=True)
-        graph_table.add_column("Skill Name", style="cyan")
-        graph_table.add_column("Available", justify="center")
-        graph_table.add_column("Policy-Eligible", justify="center")
-        graph_table.add_column("Runtime-Loadable", justify="center")
-        graph_table.add_column("Prerequisites Met", justify="center")
-        graph_table.add_column("Blocked Reason", style="yellow")
-
-        for graph in diagnostics.graph_skills_readiness:
-            available_str = "✓" if graph.available else "✗"
-            policy_str = "✓" if graph.policy_eligible else "✗"
-            runtime_str = "✓" if graph.runtime_loadable else "✗"
-            prereq_str = "✓" if graph.prerequisites_met else "✗"
-            blocked_str = graph.blocked_reason or "-"
-
-            graph_table.add_row(
-                graph.skill_name,
-                available_str,
-                policy_str,
-                runtime_str,
-                prereq_str,
-                blocked_str,
-            )
-
-        console.print(graph_table)