---
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

| Task ID | Wave | Requirement | Threat Ref | Test type | Automated evidence | Status |
|---|---:|---|---|---|---|---|
| 02-01-01 | 1 | QA-01, QA-02, QA-03 | T-02-01, T-02-SC | CLI integration | Root vet/test and `TestParityRoundTrip`/`TestParityCommands`; red state observed only before green commit | Pending |
| 02-01-02 | 1 | QA-01, QA-02, QA-03 | T-02-01 | unit + CLI | Root vet/test; malformed YAML, bounded bodies and byte/JSON diffs | Pending |
| 02-02-01 | 2 | QA-01, QA-03 | T-02-01, T-02-02 | proxy integration | `TestProxy`, `TestParityCommands`; named session, fixed upstream, safe flush | Pending |
| 02-02-02 | 2 | QA-01, QA-02, QA-03 | T-02-02, T-02-03 | unit + proxy | `TestCapture`, `TestScrub`, `TestNormalize`, `TestDiff`, `TestHeaders`, `TestFlow` | Pending |
| 02-02-03 | 2 | QA-01, QA-02, QA-03 | T-02-03, T-02-04 | CLI + manifest | `TestManifest`, `TestCoverage`; 16-route resume across two batches | Pending |
| 02-03-01 | 3 | QA-01, QA-03 | T-02-02, T-02-04, T-02-05 | PHP capture + audit | `check_corpus.go --allow-incomplete` against source; first PHP fixture and seed self-replay; both modules vet/test | Pending |
| 02-03-02 | 3 | QA-01, QA-03 | T-02-02, T-02-04, T-02-05 | batched PHP capture | Per-batch incomplete audit and PHP replay, then strict `--require-recorded` reports 154/154; both modules vet/test | Pending |
| 02-03-03 | 3 | QA-01, QA-03 | T-02-02, T-02-05 | real client capture | `capture_clients.mjs --check-deps` and `--capture`; corpus requires client flows and secret scan | Pending |
| 02-04-01 | 4 | QA-02, QA-03 | T-02-06, T-02-SC | Postgres integration | `TestParitySynthetic` starts testcontainers Postgres; both modules vet/test | Pending |
| 02-04-02 | 4 | QA-02, QA-03 | T-02-04, T-02-06 | app integration | `TestParityCorpus` shows 154 recorded/pending and zero false Go passes | Pending |
| 02-05-01 | 5 | QA-02, QA-03 | T-02-03 | contract unit | `TestFlowContract`, `TestDiffContract`, `TestManifestContract` | Pending |
| 02-05-02 | 5 | QA-01, QA-02, QA-03 | T-02-01, T-02-02, T-02-04, T-02-06 | security + app integration | `TestProxySecurity`, `TestParityCommandContract`, `TestParityContract` | Pending |
| 02-05-03 | 5 | QA-01, QA-02, QA-03 | T-02-01 to T-02-06 | phase gate | `bash scripts/check-phase2.sh --fresh-php` runs both modules' vet/test/race, Postgres, corpus audit and disposable PHP self-replay | 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 | The local PHP checkout, disposable DB and real credentials are required | Run `bash scripts/check-phase2.sh --fresh-php`; it must prove a unique empty `fonoteka_parity_*` DB, run documented artisan bootstrap, and replay all fixtures against its own `127.0.0.1:8423` child. Save output and confirm zero failures. |
| Nuxt and MCP real sessions | QA-01 | Actual browser and MCP clients are required | Run `capture_clients.mjs --capture` with the isolated PHP/proxy setup; inspect committed `nuxt/` and `mcp/` flows and the secret scan. |

## 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.