[AZ-1133] Add perf gate preflight before PT-01

Probe API reachability after JWT mint; exit 7 with compose-up
instructions when the perf stack is down. Document in environment
and containerization guides.

Co-authored-by: Cursor <cursoragent@cursor.com>

_docs/02_document/deployment/containerization.md

@@ -45,6 +45,8 @@ services:
 
 Use this when Step 15 (`scripts/run-performance-tests.sh`) or manual perf probing against `https://localhost:18980` must run while another project owns host port 5433.
 
+`run-performance-tests.sh` probes API reachability after JWT mint and before PT-01. If the stack is down, the script exits **7** and prints the `docker compose -f docker-compose.yml -f docker-compose.perf.yml up -d --build` command. See [environment.md](../tests/environment.md) § Performance tests.
+
 Integration tests do **not** use this overlay — `scripts/run-tests.sh` starts `docker-compose.tests.yml` alone, which never publishes postgres to the host.
 
 

_docs/02_document/tests/environment.md

@@ -77,7 +77,7 @@ docker compose -f docker-compose.tests.yml up --build --abort-on-container-exit
 
 `docker-compose.tests.yml` is self-contained (postgres + api + integration-tests on an internal Docker network). Postgres is not published to the host — intentional when host port 5433 is occupied by a sibling stack.
 
-**Performance tests** (Step 15 / `scripts/run-performance-tests.sh`): start the API with the perf overlay when host port 5433 is occupied — `docker compose -f docker-compose.yml -f docker-compose.perf.yml up -d --build`. Details: [containerization.md](../deployment/containerization.md#compose-overlays-dev--test--perf). PT-10 (`DeliverRouteTiles` gRPC stream) runs via `dotnet SatelliteProvider.IntegrationTests --run-pt10` inside the script; host-side default `API_URL=https://localhost:18980` with TLS trust via `./certs/api.crt` (`PERF_CA_CERT` override). Harness knobs:
+**Performance tests** (Step 15 / `scripts/run-performance-tests.sh`): start the API with the perf overlay when host port 5433 is occupied — `docker compose -f docker-compose.yml -f docker-compose.perf.yml up -d --build`. Details: [containerization.md](../deployment/containerization.md#compose-overlays-dev--test--perf). The script runs a **preflight reachability probe** after JWT mint and before PT-01; if `$API_URL` is unreachable it exits with code **7** and prints the compose-up command. PT-10 (`DeliverRouteTiles` gRPC stream) runs via `dotnet SatelliteProvider.IntegrationTests --run-pt10` inside the script; host-side default `API_URL=https://localhost:18980` with TLS trust via `./certs/api.crt` (`PERF_CA_CERT` override). Harness knobs:
 
 | Variable | Default | Purpose |
 |----------|---------|---------|

_docs/02_tasks/_dependencies_table.md

@@ -272,7 +272,7 @@ Step 9 cycle 16: 1 task created (AZ-1133 = 1 pt) — perf gate preflight before
 
 | Task | Epic | SP | Status |
 |------|------|-----|--------|
-| AZ-1133 Perf gate preflight — health-check before PT-01 | — | 1 | Todo |
+| AZ-1133 Perf gate preflight — health-check before PT-01 | — | 1 | Done |
 
 ### Step 9 cycle 15 (FluentValidation bump — AZ-1132)
 

_docs/03_implementation/batch_01_cycle16_report.md

@@ -0,0 +1,32 @@
+# Batch Report
+
+**Batch**: 1
+**Tasks**: AZ-1133_perf_gate_preflight
+**Date**: 2026-06-26
+
+## Task Results
+
+| Task | Status | Files Modified | Tests | AC Coverage | Issues |
+|------|--------|---------------|-------|-------------|--------|
+| AZ-1133 | Done | 3 files | curl probe pass | 4/4 ACs covered | None |
+
+## AC Test Coverage: All covered
+
+| AC | Evidence |
+|----|----------|
+| AC-1 | `preflight_api_reachable` called after JWT mint, before PT-01 banner in `run-performance-tests.sh` |
+| AC-2 | Isolated curl probe to `localhost:19999` → `curl_exit=7`; script prints compose-up and `exit 7` |
+| AC-3 | HTTP response path proceeds (any non-zero curl exit only triggers preflight fail) |
+| AC-4 | `environment.md` + `containerization.md` updated |
+
+## Code Review Verdict: PASS
+
+- Preflight uses same `CURL_OPTS` / `AUTH_HEADER` as PT-01
+- `set +e` / `set -e` scoped around probe — does not weaken global `pipefail`
+- Exit code 7 reserved for unreachable API per task spec
+- Docs cross-link preflight + exit 7
+
+## Auto-Fix Attempts: 0
+## Stuck Agents: None
+
+## Next Batch: All tasks complete

_docs/03_implementation/implementation_completeness_cycle16_report.md

@@ -0,0 +1,15 @@
+# Implementation Completeness — Cycle 16
+
+## Per-task classification
+
+| Task | Verdict | Evidence |
+|------|---------|----------|
+| AZ-1133 | PASS | `preflight_api_reachable` in `scripts/run-performance-tests.sh`; docs in `environment.md`, `containerization.md` |
+
+No scaffold markers. No named runtime dependencies beyond curl/dotnet already in harness.
+
+## System Pipeline Audit
+
+N/A — tooling-only cycle; no production pipeline changes.
+
+**Gate**: PASS — proceed to test handoff.

_docs/03_implementation/implementation_report_perf_gate_preflight_cycle16.md

@@ -0,0 +1,19 @@
+# Implementation Report — perf_gate_preflight (cycle 16)
+
+**Cycle**: 16
+**Tasks**: AZ-1133 (1 SP, 1 batch)
+**Feature slug**: perf_gate_preflight
+
+## Summary
+
+Added `preflight_api_reachable` to `scripts/run-performance-tests.sh`. After JWT mint and before PT-01, the script probes `$API_URL` with the same TLS trust and Bearer token as the perf scenarios. Connection/TLS failures exit **7** with the perf overlay compose-up command. Documentation updated in `environment.md` and `containerization.md`.
+
+## Batches
+
+| Batch | Tasks | Verdict |
+|-------|-------|---------|
+| batch_01_cycle16 | AZ-1133 | PASS |
+
+## Test handoff
+
+Full suite gate deferred to autodev Step 11 (`test-run` skill) per implement Step 16 handoff rule.

scripts/run-performance-tests.sh

@@ -117,6 +117,26 @@ PERF_TMP_DIR="$(mktemp -d -t perf-XXXXXX)"
 
 # --- Helper functions ---
 
+preflight_api_reachable() {
+    local perf_compose_up="docker compose -f docker-compose.yml -f docker-compose.perf.yml up -d --build"
+    local http_code curl_exit
+    set +e
+    http_code=$(curl "${CURL_OPTS[@]}" --connect-timeout 5 -s -o /dev/null -w "%{http_code}" \
+        -H "$AUTH_HEADER" \
+        "$API_URL/api/satellite/tiles/latlon?lat=47.461347&lon=37.646663&zoom=18")
+    curl_exit=$?
+    set -e
+
+    if (( curl_exit != 0 )); then
+        echo "ERROR: API at $API_URL is unreachable (curl exit $curl_exit)."
+        echo "Start the perf overlay stack:"
+        echo "  $perf_compose_up"
+        exit 7
+    fi
+
+    echo "API reachable at $API_URL (HTTP $http_code)"
+}
+
 check_threshold() {
     local test_name="$1"
     local actual_ms="$2"
@@ -163,6 +183,9 @@ wait_region_completed() {
     return 1
 }
 
+preflight_api_reachable
+echo ""
+
 # --- PT-01..PT-06 (existing scenarios; now with Bearer token) ---
 
 # PT-01: Tile download latency for a fresh tile (cold path).