docs(UAT_PLAYBOOK): document canonical source-of-truth for UAT seed passwords (GRO-2000)

The 'Source of truth for UAT passwords' subsection under Pre-conditions
records:

- The seed-uat-passwords Secret in groombook-uat is the live source.
- The Bitnami SealedSecret apps/overlays/uat/ss-seed-uat-passwords.yaml
  in groombook/infra is the single upstream source of truth.
- A kubectl recipe to pull the current values for SUPER / GROOMER /
  TESTER / CUSTOMER at the start of every UAT run.
- The 'captured env var from a previous rotation produces 401' failure
  mode that GRO-2000 hit, and the manual-reseed escape hatch if the
  login still 401s after pulling the live value.

Refs: GRO-2000, GRO-1977 (idempotent re-hash), GRO-1999 (enum fix that
allowed the seed Job to run cleanly again).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

UAT_PLAYBOOK.md

@@ -19,6 +19,27 @@ GroomBook API is a Hono-based REST service (TypeScript/Node.js) powering the pet
 - OIDC authentication provider configured
 - Seed data present (clients, pets, services, staff)
 
+### Source of truth for UAT passwords (GRO-2000)
+
+The `UAT_SUPER_PASSWORD` / `UAT_GROOMER_PASSWORD` / `UAT_TESTER_PASSWORD` / `UAT_CUSTOMER_PASSWORD` env vars the test orchestrator uses **must** be pulled from the live `seed-uat-passwords` Secret in the UAT cluster — never from a captured shell value, a previous run's `.env`, or a copy of the SealedSecret committed before the latest rotation.
+
+**Canonical recipe** (works from any host with `kubectl` + cluster credentials):
+
+```bash
+SUPER=$(kubectl get secret seed-uat-passwords -n groombook-uat \
+  -o jsonpath='{.data.super-password}' | base64 -d)
+GROOMER=$(kubectl get secret seed-uat-passwords -n groombook-uat \
+  -o jsonpath='{.data.groomer-password}' | base64 -d)
+TESTER=$(kubectl get secret seed-uat-passwords -n groombook-uat \
+  -o jsonpath='{.data.tester-password}' | base64 -d)
+CUSTOMER=$(kubectl get secret seed-uat-passwords -n groombook-uat \
+  -o jsonpath='{.data.customer-password}' | base64 -d)
+```
+
+**Why:** the Bitnami SealedSecret `apps/overlays/uat/ss-seed-uat-passwords.yaml` (in `groombook/infra`) is the single source of truth. The UAT `reset-demo-data` CronJob re-hashes these values into the `account` table on every run (idempotent — GRO-1977). A captured env var from a previous generation will not match the current hash, producing 401 `INVALID_EMAIL_OR_PASSWORD`. If the live login still 401s after pulling from the SealedSecret, the seed Job is stale — trigger `kubectl create job --from=cronjob/reset-demo-data -n groombook-uat manual-seed-$$` and retry.
+
+**How to apply:** at the start of every UAT run that touches TC-API-1.4 / 1.5 / 1.6 / 1.7 / 3.18 / 3.21 / 3.23, refresh these four env vars from the cluster before issuing the sign-in request.
+
 ## Test Cases
 
 ### 4.0 Health Check
@@ -119,6 +140,7 @@ GroomBook API is a Hono-based REST service (TypeScript/Node.js) powering the pet
 | TC-API-3.25 | Verify 30+ total pets in UAT DB | GET /api/pets then count total | 30+ pets returned (UAT seed creates 500 random-pool + 5 UAT test clients + 2 UAT customer = 507 total) |
 | TC-API-3.26 | Verify 25-35% medicalAlerts distribution | GET /api/pets (first 30 pets), count how many have non-empty medicalAlerts | Ratio is 25-35% (seed uses rand() < 0.3 for ~30% distribution) |
 | TC-API-3.27 | Verify coat_type enum has all seed values | After UAT seed completes, inspect the coat_type enum on the UAT DB — it must contain: short, medium, long, double, wire, silky, curly, hairless | UAT seed jobs (`reset-demo-data`, `seed-test-data`) complete 1/1 with no `enum_in` error; coat_type includes all 8 values used by seed.ts `coatTypePool` |
+| TC-API-3.28 | Verify pet_size_category enum has all seed values | After UAT seed completes, inspect the pet_size_category enum on the UAT DB — it must contain: small, medium, large, extra_large | UAT seed jobs (`reset-demo-data`, `seed-test-data`) complete 1/1 with no `enum_in` error; pet_size_category includes all 4 values used by seed.ts `petSizeCategoryPool` (regression for GRO-1999, mirrors TC-API-3.27) |
 
 ### 4.4 Appointment Scheduling
 

packages/db/migrations/0038_register_extra_large_pet_size_category.sql

@@ -0,0 +1,4 @@
+-- GRO-1999: 0037 was skipped on existing DBs due to a below-high-water-mark
+-- journal timestamp. Re-register extra_large with a monotonic timestamp so
+-- the existing UAT/persistent DBs apply it. Idempotent.
+ALTER TYPE "pet_size_category" ADD VALUE IF NOT EXISTS 'extra_large';

packages/db/migrations/meta/_journal.json

@@ -260,6 +260,13 @@
       "when": 1751500000000,
       "tag": "0037_add_extra_large_to_pet_size_category",
       "breakpoints": true
+    },
+    {
+      "idx": 38,
+      "version": "7",
+      "when": 1780000000000,
+      "tag": "0038_register_extra_large_pet_size_category",
+      "breakpoints": true
     }
   ]
 }