docs(02): research parity harness and validation

.planning/phases/02-api-parity-harness-bootstrap/02-VALIDATION.md

@@ -0,0 +1,64 @@
+---
+phase: 02
+slug: api-parity-harness-bootstrap
+status: draft
+nyquist_compliant: false
+wave_0_complete: false
+created: 2026-09-16
+---
+
+# Phase 2 — Validation Strategy
+
+## Test Infrastructure
+
+| Property | Value |
+|---|---|
+| Framework | Go 1.27 `testing`, `httptest`; Testcontainers Postgres for app integration |
+| Config file | Root `go.mod`; app `../fonoteka.go/go.mod`; no separate test config |
+| Quick run | `go vet ./... && go test ./...` in root, then the same from `../fonoteka.go` once code exists |
+| Full suite | Quick run plus `go test -race ./...` in both modules, CLI synthetic smoke, PHP self-replay on isolated local DB, route coverage audit |
+| Estimated runtime | Measure during execution; Testcontainers and PHP checks are slower than package tests |
+
+## Sampling Rate
+
+- After every implementation task commit: root `go vet ./... && go test ./...`; once app files exist, also run the app module checks.
+- After each plan wave: run the above and the slice's CLI smoke against a local `httptest.Server` or isolated PHP server as applicable.
+- Before `$gsd-verify-work`: run both modules' vet, test and race suites; run testcontainers Postgres integration; run PHP self-replay and inspect the 154-route coverage report.
+- Keep quick checks in seconds after build cache warmup. Measure actual runtime; no arbitrary latency promise is set.
+
+## Per-Task Verification Map
+
+Plan/task IDs are assigned after the required plan-count checkpoint. The planner must attach each row to an exact task and automated command.
+
+| Slice | Requirement | Threat Ref | Secure behavior | Test type | Automated command or assertion | Initial status |
+|---|---|---|---|---|---|---|
+| One-fixture record and replay through `summer` | QA-01, QA-02 | T-02-01 | Loopback target and bounded body handling | integration | `go test ./tide ./cmd/summer` with `httptest.Server`, fixture written then diffed | Pending |
+| Live PHP proxy and scripted route recording | QA-01 | T-02-01, T-02-02 | Fixed upstream, scrub before write, no credential log | integration + operator smoke | `go test ./tide ./cmd/summer`; CLI capture from isolated PHP server | Pending |
+| Structural JSON/byte diff and rule assertions | QA-02 | T-02-03 | Normalization rejects wrong token type or malformed date | unit | `go test ./tide -run 'Diff|Normalize|Capture|Scrub'` | Pending |
+| 154-route manifest and client flows | QA-01 | T-02-02 | Only deterministic test identities committed | manifest audit + PHP replay | manifest validator reports `154/154 recorded`; PHP self-replay zero failures | Pending |
+| Go replay seam and Postgres state | QA-02, QA-03 | T-02-04 | No false green for pending routes; seed hook allow-list | integration | `go test ./parity` in app module with testcontainers Postgres | Pending |
+| Phase-wide test plan | QA-03 | T-02-01 to T-02-04 | Regression tests for all listed secure behaviors | unit + race + CLI | `go vet ./... && go test ./... && go test -race ./...` in both modules | Pending |
+
+## Wave 0 Requirements
+
+- [ ] First implementation slice adds `tide` package tests and `cmd/summer` command smoke test so record/replay is executable from its first commit.
+- [ ] App integration slice creates `../fonoteka.go/parity/parity_test.go`, a Postgres-backed synthetic handler, and a pending-route fixture status check before any real Go API port exists.
+- [ ] Manifest validation rejects duplicate/missing route ids and reports exactly 154 PHP route definitions as the source snapshot.
+
+## Manual-Only Verifications
+
+| Behavior | Requirement | Why manual | Test instructions |
+|---|---|---|---|
+| Fresh PHP backend capture and self-replay | QA-01, QA-02 | Requires isolated PHP backend and database with local credentials | Start PHP on the agreed port with fresh parity DB, run seed/record, route manifest, Nuxt and MCP flows through proxy, then replay corpus against PHP; save command output and confirm zero failures. |
+| Nuxt and MCP real sessions | QA-01 | Browser consent and external MCP interaction cannot be fully represented by synthetic handler | Point `NUXT_DEV_BACKEND_ORIGIN` and `FONOTEKA_API_URL` at proxy, perform documented flows, confirm committed fixtures under `nuxt/` and `mcp/` contain placeholders and no credentials. |
+
+## Validation Sign-Off
+
+- [ ] Each finalized plan task has an automated verify or an explicit manual gate.
+- [ ] No three consecutive tasks lack automated feedback.
+- [ ] Testcontainers Postgres test executes; it is not silently skipped in the phase completion run.
+- [ ] Root and app module `go vet`, `go test`, and `go test -race` pass.
+- [ ] PHP self-replay and 154-route coverage evidence are recorded.
+- [ ] Set `nyquist_compliant: true` only after all mapped checks exist and pass.
+
+**Approval:** Pending execution evidence.