# Pre-UAT Readiness Gate Runbook

Status: active

This runbook defines the gate sequence that must pass before a broad post-PSSM
UAT run is marked ready. Full UAT should not be the first defect detector.

## Command

Plan/report mode for PR CI and local dry runs:

```bash
scripts/ci/pre_uat_readiness_gate.sh --mode plan --env kind
```

Strict mode for UAT entry or release promotion:

```bash
PRE_UAT_RUN_SERVICE_FRESHNESS=1 \
PRE_UAT_RUN_INTEGRATION_SMOKE=1 \
PRE_UAT_RUN_LIVE_PREREQ=1 \
PRE_UAT_RUN_APP_SDK_LIVE=1 \
PRE_UAT_RUN_CLEAN_LOG=1 \
PRE_UAT_RUN_USER_SAFE_ERROR=1 \
PRE_UAT_RUN_HARNESS_FAILURE=1 \
scripts/ci/pre_uat_readiness_gate.sh --mode strict --env kind
```

Use `--env dev` for the dev-control run after kind passes. Demo is not part of
the current stabilization entry gate unless explicitly scheduled.

## Required Sequence

1. Service freshness: touched services must be deployed at the expected commit.
2. Blocking integration smoke: focused post-PSSM integration and trace smokes.
3. Live prerequisite baseline: profile, region, provider capacity, and UAT
   baseline resources.
4. Dev provider-node reconciliation: for dev Proxmox-backed UAT, run
   `scripts/ops/dev_provider_node_reconciliation_preflight.sh
   --require-provider-inventory` before app, terminal, or browser workload
   tests. The gate must prove current GPUaaS node/read-model state matches
   provider lifecycle/inventory, excludes stale/no-heartbeat nodes from
   launchable targets, fails provider/runtime/region/network-zone
   classification drift, and rejects manual node hosts that do not match the
   selected GPUaaS node.
5. App SDK live contract: launch/connect/decommission through public APIs for at
   least one launchable OCI app.
6. Clean log observability: observability stack, correlation, and clean scoped
   Loki window.
7. User-safe error presentation: raw Cloudflare, Pomerium, upstream, or Next.js
   pages must not be visible to users.
8. Harness failure injection: forced failures must produce accurate exit status,
   summary, results, captured evidence, and cleanup continuation.
9. Coverage matrix reference: UAT evidence must map to the platform UAT
   completeness matrix.

## Promotion Rule

Strict mode exits nonzero when any required gate is missing, failed, blocked, or
stale. An exception must be explicit, expiring, owned, and attached to the
Fairway task or release evidence packet. A skipped required gate is acceptable
only in plan/report mode.

## Evidence

The gate writes:

- `summary.md`: human-readable gate summary.
- `results.jsonl`: one row per gate with status, required flag, and artifact.
- `readiness.json`: machine-readable final state.

Fairway task `PSSM-UAT-CI-PROMOTION-WIRING-001` tracks this wiring. The UAT
readiness epic should reference the latest `readiness.json` before full UAT
starts.