docs(phase-18): add validation strategy

.planning/phases/18-payment-gateway/18-VALIDATION.md

@@ -0,0 +1,95 @@
+---
+phase: "18"
+slug: "payment-gateway"
+# status lifecycle: draft (seeded by plan-phase) → validated (set by validate-phase §6)
+# audit-milestone §5.5 distinguishes NOT-VALIDATED (draft) from PARTIAL (validated + nyquist_compliant: false) (#2117)
+status: draft
+nyquist_compliant: false
+wave_0_complete: false
+created: "2026-10-12"
+---
+
+# Phase 18 — Validation Strategy
+
+> Per-phase validation contract for feedback sampling during execution.
+
+---
+
+## Test Infrastructure
+
+| Property | Value |
+|----------|-------|
+| **Framework** | Go `testing` (+ testcontainers-go Postgres), vitest (admin SPA), `node --test` (vue-paymentgateway-layer) |
+| **Config file** | none for Go; `admin/` vitest config exists; layer `package.json` test script (Wave 0) |
+| **Quick run command** | `go vet ./... && go test -short ./...` in the touched repo (summercms.go, sm-paymentgateway-plugin, sm-pgstripe-plugin) |
+| **Full suite command** | `bash scripts/check-phase18.sh --all` (written in the last plan, modelled on `scripts/check-phase17.sh`) |
+| **Estimated runtime** | ~60 seconds quick; several minutes full (Docker) |
+
+---
+
+## Sampling Rate
+
+- **After every task commit:** Run the quick command in the touched repo
+- **After every plan wave:** Run `go test ./...` (Docker) in the touched repos, plus `npm --prefix admin run test` when admin changed
+- **Before `/msd-verify-work`:** `bash scripts/check-phase18.sh --all` must be green
+- **Max feedback latency:** 120 seconds
+
+---
+
+## Per-Task Verification Map
+
+Filled by the planner/executor from the PLAN.md tasks. Seed map from 18-RESEARCH.md § Validation Architecture:
+
+| Area | Behavior | Test Type | Automated Command | File Exists | Status |
+|------|----------|-----------|-------------------|-------------|--------|
+| SC-1 | Payment FSM 6×5, Order FSM 12×19, refund bridge | unit | `go test -short ./fsm/... ./orders/... ./payments/... -run 'TestPaymentMatrix\|TestOrderMatrix\|TestRefundBridge'` | ❌ W0 | ⬜ pending |
+| SC-1 | MoneyRight vectors, Scan/Value, (10,4)/(12,4) ceilings | unit | `go test -short ./money/...` | ❌ W0 | ⬜ pending |
+| SC-2 | Operator registry discovery; duplicate code fails boot | unit | `go test -short ./operators/... -run TestRegistry` | ❌ W0 | ⬜ pending |
+| SC-2 | Notification route paths × methods, mode merge, de-urlize, unregistered → 404 | integration (httptest) | `go test -short . -run TestNotificationRoute` | ❌ W0 | ⬜ pending |
+| SC-2 | Stripe webhook signature cases, replay no-op | integration | `go test -short ./... -run TestStripeWebhook` (pgstripe) | ❌ W0 | ⬜ pending |
+| SC-3 | Events once per transition; MailerSettings gating; EN/PL templates | unit | `go test -short ./events/... -run 'TestEvents\|TestMailers'` | ❌ W0 | ⬜ pending |
+| SC-3 | Migrations up/down; schema equals PHP v2.6.0 | integration (Docker) | `go test ./updates/... -run TestMigrations` | ❌ W0 | ⬜ pending |
+| SC-3 | Scheduled commands select rows by timeout | integration (Docker) | `go test ./console/... -run TestPG` | ❌ W0 | ⬜ pending |
+| SC-3 | Settings import-winter | integration (Docker) | `go test ./console/... -run TestImportWinter` | ❌ W0 | ⬜ pending |
+| SC-4 | Host flow: Make → Stripe → signed event → Paid → OrderPaid + mail; path (b) | integration (Docker + httptest) | `go test ./... -run TestHostStripeFlow` (pgstripe) | ❌ W0 | ⬜ pending |
+| D-07 | cabana `money` field schema/fill/projection | unit | `go test -short ./modules/cabana -run TestMoneyField` | ❌ W0 | ⬜ pending |
+| D-07 | `MoneyField.vue` | unit (vitest) | `npm --prefix admin run test -- MoneyField` | ❌ W0 | ⬜ pending |
+| D-11 | Legacy reader goldens, v2 round trip | unit | `go test -short ./cart/... -run 'TestLegacy\|TestV2'` | ❌ W0 | ⬜ pending |
+| D-06 | Customer API authz and state guards | integration (Docker) | `go test ./api/... -run TestCustomerAPI` | ❌ W0 | ⬜ pending |
+| D-06 | Layer client and components | unit | `pnpm --dir ../vue-paymentgateway-layer test` | ❌ W0 | ⬜ pending |
+| Docs | docs checker, OpenAPI, dist | gate | `go test ./cmd/summer -run TestDocsTree && summer docs:build --check && scripts/check-admin-openapi.sh --check && scripts/check-admin-dist.sh` | ✅ | ⬜ pending |
+
+*Status: ⬜ pending · ✅ green · ❌ red · ⚠️ flaky*
+
+---
+
+## Wave 0 Requirements
+
+- [ ] New repos `sm-paymentgateway-plugin`, `sm-pgstripe-plugin` with `go.mod`/`go.work` and an `integration_test.go` harness copied from `sm-journal-plugin` (`TestMain` with `flag.Parse()` + `testing.Short()`)
+- [ ] `testdata/legacy/` golden fixtures (anonymized Horoskopia row + PHP-generated synthetic rows)
+- [ ] `money/vectors_test.go` seeded from the PHP vectors in 18-RESEARCH.md
+- [ ] Shared Stripe `httptest` fake helper for pgstripe tests
+- [ ] `vue-paymentgateway-layer` scaffold copied from `vue-journal-layer`
+- [ ] `scripts/check-phase18.sh`
+
+---
+
+## Manual-Only Verifications
+
+| Behavior | Requirement | Why Manual | Test Instructions |
+|----------|-------------|------------|-------------------|
+| Real shop-type golden fixtures | D-11 | Needs anonymized production rows from other apps | Checkpoint: user supplies rows; executor adds them to `testdata/legacy/` |
+| Layer visual check in a playground | D-06 | Visual layout | Run the layer `.playground`, walk order → checkout redirect |
+
+---
+
+## Validation Sign-Off
+
+- [ ] All tasks have `<automated>` verify or Wave 0 dependencies
+- [ ] Sampling continuity: no 3 consecutive tasks without automated verify
+- [ ] Wave 0 covers all MISSING references
+- [ ] No watch-mode flags
+- [ ] Feedback latency < 120s
+- [ ] `nyquist_compliant: true` set in frontmatter
+
+**Approval:** pending