Files
summercms/.planning/phases/18.1-payment-gateway-subscriptions/18.1-VALIDATION.md

18 KiB

phase, slug, status, nyquist_compliant, wave_0_complete, created, validated, revalidated
phase slug status nyquist_compliant wave_0_complete created validated revalidated
18.1 payment-gateway-subscriptions validated true true 2026-10-14 2026-10-14 2026-10-16

Phase 18.1 — Validation Strategy

Per-phase validation contract for feedback sampling during execution. Source: 18.1-RESEARCH.md § Validation Architecture.


Test Infrastructure

Property Value
Framework Go testing + testcontainers Postgres 16 (Docker tests skip under -short); admin: vitest; layer: node --test via pnpm test
Config file per-repo testmain_test.go (flag.Parse() + testing.Short()): framework modules/cabana, sm-paymentgatewaysubscriptions-plugin (root), sm-pgstripe-plugin (root and subscriptions)
Quick run command go -C ../sm-paymentgatewaysubscriptions-plugin vet ./... && go -C ../sm-paymentgatewaysubscriptions-plugin test -short ./... ; go -C ../sm-pgstripe-plugin vet ./... && go -C ../sm-pgstripe-plugin test -short ./...
Full suite command go test ./... (Docker) in both plugin repos; pnpm -C ../vue-paymentgateway-layer test; go vet ./... && go test -short ./... in summercms.go
Phase gate scripts/check-phase18.1.sh --all in summercms.go (stages go, plugins, admin, layers, docs, postgres; --self-test; PHASE181_REQUIRE_POSTGRES=1 makes a missing Docker daemon fatal)
Estimated runtime quick ~30 s per repo; full gate ~10 min (containers, vitest, docs)

Sampling Rate

  • After every task commit: the -short quick run of the touched repo
  • After every plan wave: full suite of the touched repos (Docker)
  • Before /msd-verify-work: scripts/check-phase18.1.sh --all green
  • Max feedback latency: 60 seconds for the quick run

Per-Task Verification Map

Every task of plans 01 to 09, with the command that proves it (run from the summercms.go root; sibling repositories through go -C ../<repo> or pnpm --dir ../<repo>). Docker rows ran on a Docker host. "File exists" names the plan and task that created the test. Status is the result of the 18.1-06 gate run (PHASE181_REQUIRE_POSTGRES=1 bash scripts/check-phase18.1.sh --all) for plans 01 to 06 and of the 18.1-09 gate run (the same command, 2026-10-16, Docker host) for plans 07 to 09, unless noted.

Task Req Behaviour Type Automated command File exists Status
18.1-01 T1 D-17 taglist array mode: compile gates, save to a JSON column, record GET, OpenAPI, dist, docs unit + Docker go test -count=1 -short -run '^TestTaglistFieldCompile$' ./modules/cabana; Docker: go test -count=1 -run '^TestTaglistFieldSmoke$' ./modules/cabana ✅ (01 T1) ✅ green
18.1-01 T2 D-17 taglist string mode, customTags, relation and settings save sites, repeater refusal, preview unit + Docker + vitest go test -count=1 -short -run '^(TestTaglistFieldCompile|TestTaglistFieldValidate|TestTaglistFieldHydrate)$' ./modules/cabana && npm --prefix admin test -- tests/form/TaglistField.test.ts ✅ (01 T2, 06 T2) ✅ green
18.1-01 T3 D-17 flat reorder inference, flat save, flat on the list schema (localized too) and the reorder data unit + Docker go test -count=1 -short -run '^(TestReorderFlatCompile|TestReorderFlatNodes)$' ./modules/cabana; Docker: go test -count=1 -run '^(TestReorderFlatSmoke|TestReorderPostgres)$' ./modules/cabana ✅ (01 T3, 06 T2) ✅ green
18.1-01 T4 D-17 flat reorder in the SPA, dist rebuilt vitest + gate npm --prefix admin test -- tests/views/ReorderView.test.ts && bash scripts/check-admin-dist.sh ✅ (01 T4, 06 T2) ✅ green
18.1-01 T5 D-22 framework release decision (reply "hold") checkpoint n/a (decision; the final push is 18.1-06 T5) n/a ✅ recorded
18.1-02 T1 D-04, D-16 baseline shape confirmed (reply "baseline-jsonb") checkpoint n/a n/a ✅ recorded
18.1-02 T2 SC-1, SC-2 plugin boots, baseline migrates, Apply stores an active subscription and fires activated once Docker go -C ../sm-paymentgatewaysubscriptions-plugin test -count=1 -run '^TestSubscriptionsTracer$' . ✅ (02 T2) ✅ green
18.1-02 T3 SC-1, D-08, D-09 registries, Gateway contract, built-in user subscriber, checkout stores the customer id unit + Docker go -C ../sm-paymentgatewaysubscriptions-plugin test -count=1 -short -run '^TestRegistry$' ./contracts; Docker: go -C ../sm-paymentgatewaysubscriptions-plugin test -count=1 -run '^(TestSubscriptionsCheckout|TestUserSubscribable)$' . ✅ (02 T3, 06 T3) ✅ green
18.1-02 T4 SC-1, SC-2, SC-3, D-03, D-05, D-13 model checks, features, event diff, invoices, claim, service API, baseline names unit + Docker go -C ../sm-paymentgatewaysubscriptions-plugin test -count=1 -short -run '^(TestSubscriptionChecks|TestPlanPrices|TestFeatureList)$' ./models; Docker: go -C ../sm-paymentgatewaysubscriptions-plugin test -count=1 -run '^(TestSubscriptionsCoreSmoke|TestPlanJSONBColumns|TestApplyEvents|TestClaimEventConcurrent|TestBaselineSchema|TestServiceAPI)$' . ✅ (02 T4, 06 T3) ✅ green
18.1-02 T5 D-22 pgsub remote created and main pushed at aad4647 (reply "create-and-push") checkpoint git -C ../sm-paymentgatewaysubscriptions-plugin ls-remote origin main n/a ✅ recorded
18.1-03 T1 D-10, D-11, D-18 webhook contract confirmed (reply "php-plain-text") checkpoint n/a n/a ✅ recorded
18.1-03 T2 SC-2, SC-4 checkout through the Stripe fake, signed customer.subscription.created, claim-first job, activated Docker go -C ../sm-pgstripe-plugin test -count=1 -run '^TestHostSubscriptionFlow$' ./subscriptions ✅ (03 T2) ✅ green
18.1-03 T3 SC-2, SC-4, D-11, D-12, D-15, D-19 gateway, plan sync, five event types in both shapes, app tag, refusals, real worker unit + Docker go -C ../sm-pgstripe-plugin test -count=1 -short -run '^(TestDecodeSubscription|TestDecodeInvoice|TestJobArgsMinimal)$' ./subscriptions; Docker: go -C ../sm-pgstripe-plugin test -count=1 -run '^(TestHostSubscriptionFlow|TestSubscriptionWebhookSmoke|TestSubscriptionJob|TestSyncPlan|TestSubscriptionGateway)$' ./subscriptions ✅ (03 T3, 06 T4) ✅ green
18.1-03 T4 D-18 subscription secret fields, import target flag, READMEs, settings and import smokes unit + Docker go -C ../sm-pgstripe-plugin test -count=1 -short -run '^(TestStripeDataHandling|TestSDKPin)$' .; Docker: go -C ../sm-pgstripe-plugin test -count=1 -run '^(TestStripeSettingsSmoke|TestStripeImportWinterSmoke|TestStripeSubscriptionSecrets|TestHostStripeFlow)$' . ✅ (03 T4, 06 T4) ✅ green
18.1-04 T1 SC-3, D-17 plans admin with permissions, navigation and the taglist form Docker go -C ../sm-paymentgatewaysubscriptions-plugin test -count=1 -run '^TestAdminPlansSmoke$' . ✅ (04 T1) ✅ green
18.1-04 T2 SC-3, D-13, D-17 flat plan reorder, bulk and toolbar sync with per-plan failures Docker go -C ../sm-paymentgatewaysubscriptions-plugin test -count=1 -run '^(TestAdminPlansSmoke|TestAdminSyncActions)$' . ✅ (04 T2, 06 T3) ✅ green
18.1-04 T3 SC-3, D-02, D-08 subscriptions admin, label field types, EN/PL phrasebook unit + Docker go -C ../sm-paymentgatewaysubscriptions-plugin test -count=1 -short -run '^(TestAdminCatalog|TestAdminLangParity|TestLangParity)$' .; Docker: go -C ../sm-paymentgatewaysubscriptions-plugin test -count=1 -run '^TestAdminSubscriptionsSmoke$' . ✅ (04 T3, 06 T3) ✅ green
18.1-04 T4 D-13 customer API contract confirmed (reply "api-research") checkpoint n/a n/a ✅ recorded
18.1-04 T5 SC-3, D-13, D-21 customer API endpoints, redirects from config, authorization matrix unit + Docker go -C ../sm-paymentgatewaysubscriptions-plugin test -count=1 -short -run '^TestRedirectURLs$' .; Docker: go -C ../sm-paymentgatewaysubscriptions-plugin test -count=1 -run '^(TestCustomerAPISmoke|TestCustomerAPIAuthz)$' . ✅ (04 T5, 06 T3) ✅ green
18.1-05 T1 SC-3, D-14 typed client, PgPlans, PgSubscribeButton with a one-time checkout redirect node pnpm --dir ../vue-paymentgateway-layer test (files tests/subscriptions.test.ts, tests/subscribe.test.ts) ✅ (05 T1, 06 T2) ✅ green
18.1-05 T2 SC-3, D-14, D-21 PgMySubscription with cancel, PgManageSubscriptionButton, useSubscription, copy node pnpm --dir ../vue-paymentgateway-layer test (files tests/subscriptionComponents.test.ts, tests/i18n.test.ts) ✅ (05 T2, 06 T2) ✅ green
18.1-05 T3 D-22 layer release decision (reply "hold") checkpoint n/a (the final push is 18.1-06 T5) n/a ✅ recorded
18.1-06 T1 SC-5 fail-closed gate with detector self-test gate bash scripts/check-phase18.1.sh --self-test ✅ (06 T1) ✅ green
18.1-06 T2 SC-5, D-17, D-14 framework and layer coverage; the reorder.flat defect fixed gate bash scripts/check-phase18.1.sh go && bash scripts/check-phase18.1.sh admin && bash scripts/check-phase18.1.sh layers ✅ (06 T2) ✅ green
18.1-06 T3 SC-5, D-03 to D-16, D-21 pgsub coverage gate bash scripts/check-phase18.1.sh plugins && bash scripts/check-phase18.1.sh postgres ✅ (06 T3) ✅ green
18.1-06 T4 SC-5, D-11, D-12, D-15, D-18, D-19 pgstripe coverage and the PHP map gate PHASE181_REQUIRE_POSTGRES=1 bash scripts/check-phase18.1.sh --all ✅ (06 T4) ✅ green
18.1-06 T5 D-22 final push and tag decision checkpoint n/a (reply "push-all": framework v0.1.26, layer v0.2.0) n/a ✅ recorded
18.1-07 T1 CR-01, D-11 webhook job applies the subscription Stripe holds, under the per-subscription session lock, claim-first kept Docker go -C ../sm-pgstripe-plugin test -count=1 -run '^(TestEventOrdering|TestFreshStateSmoke|TestRetrieveSubscription)$' ./subscriptions ✅ (07 T1, 09 T1, 09 T3) ✅ green
18.1-07 T2 CR-01, WR-04 a deletion before its subscription is stored is retried; plan resolution by price, product, plan code unit + Docker go -C ../sm-paymentgatewaysubscriptions-plugin test -count=1 -run '^(TestPlanResolution|TestApplyDeletedNotStored)$' .; go -C ../sm-pgstripe-plugin test -count=1 -short -run '^TestDecodeSubscription$' ./subscriptions ✅ (09 T2, 09 T3) ✅ green
18.1-07 T3 WR-06 SyncSubscription writes only gateway-owned columns of a locked re-read row and refreshes the plan Docker go -C ../sm-paymentgatewaysubscriptions-plugin test -count=1 -run '^TestSyncSubscriptionFresh$' . ✅ (09 T2) ✅ green
18.1-08 T1 CR-02 strict checkout price: customer API 422, gateway ErrNoPriceForCurrency without a Stripe call, yen refused unit + Docker go -C ../sm-paymentgatewaysubscriptions-plugin test -count=1 -short -run '^TestCheckoutPriceID$' ./models; go -C ../sm-pgstripe-plugin test -count=1 -run '^TestGatewayStrictPrice$' ./subscriptions; go -C ../sm-paymentgatewaysubscriptions-plugin test -count=1 -run '^TestCustomerAPIGuards$' . ✅ (09 T2, 09 T3) ✅ green
18.1-08 T2 WR-02, WR-03 idempotency keys, first-write-wins customer id, guarded checkout under the subscriber lock, 409 for any open subscription unit + Docker go -C ../sm-paymentgatewaysubscriptions-plugin test -count=1 -short -run '^TestTerminalStatuses$' ./models; go -C ../sm-paymentgatewaysubscriptions-plugin test -count=1 -run '^(TestCheckoutGuarded|TestCustomerIDFirstWriteWins|TestCustomerAPIGuards)$' .; go -C ../sm-pgstripe-plugin test -count=1 -run '^TestGatewayIdempotencyKeys$' ./subscriptions ✅ (09 T2, 09 T3) ✅ green
18.1-08 T3 WR-01 pact.AdminBulkAction.Detached; plan sync holds no transaction or row lock across Stripe calls Docker go test -count=1 -run '^TestDetachedBulkAction$' ./modules/cabana; go -C ../sm-paymentgatewaysubscriptions-plugin test -count=1 -run '^TestAdminSyncDetached$' . ✅ (09 T2, 09 T3) ✅ green
18.1-08 T4 WR-07, WR-03 the layer's buttons recover after Back from Stripe; 409 copy fits any open subscription node pnpm --dir ../vue-paymentgateway-layer test (seven subscriptions: specs of 18.1-09 in tests/subscribe.test.ts, tests/subscriptionComponents.test.ts) ✅ (09 T4) ✅ green
18.1-09 T1 SC-5, CR-01 tracer: the CR-01 ordering suite required by name in the postgres stage gate bash scripts/check-phase18.1.sh --self-test && bash scripts/check-phase18.1.sh postgres ✅ (09 T1) ✅ green
18.1-09 T2 SC-5, CR-01, CR-02, WR-01 to WR-04, WR-06 pgsub gap-closure coverage gate bash scripts/check-phase18.1.sh plugins && bash scripts/check-phase18.1.sh postgres ✅ (09 T2) ✅ green
18.1-09 T3 SC-5, CR-01, CR-02, WR-01 to WR-04 pgstripe and framework coverage gate bash scripts/check-phase18.1.sh go && bash scripts/check-phase18.1.sh plugins && bash scripts/check-phase18.1.sh docs && bash scripts/check-phase18.1.sh postgres ✅ (09 T3) ✅ green
18.1-09 T4 SC-5, WR-07 layer coverage (43 subscriptions: passes, minimum 43), version 0.2.1, the full gate gate PHASE181_REQUIRE_POSTGRES=1 bash scripts/check-phase18.1.sh --all ✅ (09 T4) ✅ green
18.1-09 T5 D-22 final push and tag decision for the gap closure (framework v0.1.27, layer v0.2.1, optional plugin v0.1.0) checkpoint n/a (awaiting the human reply) n/a ⬜ pending

The success-criterion view (seeded by the planner) maps onto the rows above:

Req Behaviour Proven by
SC-1 baseline up/down, idempotent re-run, names equal the PHP v2.4.0 dump; users.stripe_customer_id only when missing; registries; user subscriber; status, grace, feature and renewal matrices TestBaselineSchema, TestSubscriptionsCoreSmoke, TestRegistry, TestUserSubscribable, TestSubscriptionChecks, TestPlanPrices, TestFeatureList
SC-2 webhook answers and URLs; claim-first job (STRIPE-006/007), duplicate and concurrent; event matrix; plan sync TestSubscriptionWebhookSmoke, TestSubscriptionJob, TestApplyEvents, TestClaimEventConcurrent, TestSyncPlan, TestSubscriptionGateway
SC-3 admin screens and actions; customer API; layer client and components TestAdminPlansSmoke, TestAdminSubscriptionsSmoke, TestAdminSyncActions, TestCustomerAPISmoke, TestCustomerAPIAuthz, the layer's subscriptions: specs
SC-4 the proof host flow incl. a real conga worker TestHostSubscriptionFlow
SC-5 the PHP test map and the gate TestStripeSubscriptionReliability, TestSubscriptionAuthentication, TestStripeSubscriptionSecrets, TestSDKPin; scripts/check-phase18.1.sh --all
CR-01 stale events cannot regress a row; deletion before creation retried TestEventOrdering, TestFreshStateSmoke, TestApplyDeletedNotStored, TestRetrieveSubscription
CR-02 no checkout billed at another currency's price TestCheckoutPriceID, TestGatewayStrictPrice, TestCustomerAPIGuards
WR-01 no transaction or row lock across Stripe calls in the admin sync TestDetachedBulkAction, TestAdminSyncDetached
WR-02, WR-03 one customer and one checkout per subscriber; any open subscription blocks checkout TestGatewayIdempotencyKeys, TestCustomerIDFirstWriteWins, TestCheckoutGuarded, TestTerminalStatuses, TestCustomerAPIGuards
WR-04 a re-priced or renamed plan still stores the subscription TestPlanResolution, TestDecodeSubscription
WR-06 no lost update in SyncSubscription TestSyncSubscriptionFresh
WR-07 the layer's buttons recover after Back the seven 18.1-09 subscriptions: specs

Status: ⬜ pending · ✅ green · ❌ red · ⚠️ flaky


Wave 0 Requirements

  • sm-paymentgatewaysubscriptions-plugin/testmain_test.go + harness (18.1-02)
  • Subscription-endpoint Stripe fake in sm-pgstripe-plugin/subscriptions (18.1-03; price failure switch added in 18.1-06)
  • Webhook event-body builders for both API shapes (subscriptions/eventbody_test.go, 18.1-03)
  • scripts/check-phase18.1.sh (18.1-06; gap-closure names and the layers minimum 43 added in 18.1-09)
  • Stripe fake retrieval failure switch setFailRetrieve and the Idempotency-Key capture (18.1-08, 18.1-09)

Manual-Only Verifications

Behavior Requirement Why Manual Test Instructions
Billing-portal cancellation arrives as cancel_at_period_end or cancel_at SC-2, D-21 Depends on live Stripe portal behaviour on the account's API version Stripe test mode + stripe listen forwarding to the subscriptions URL; cancel through the portal; inspect the delivered customer.subscription.updated
Real Stripe test-mode checkout end to end SC-4, CR-01 The fake cannot prove Stripe's hosted checkout or its real event order Test-mode keys in settings, run checkout from the layer playground, confirm activation and the activated event; watch that customer.subscription.created and .updated arrive in either order without the row regressing
Admin screens and layer components in a real browser SC-3, D-17, WR-07 vitest and SSR specs do not drive a browser or its back/forward cache Try the taglist chips, the flat drag reorder, the sync toasts, the plans page, Checkout and portal redirects and the cancel dialog once, and press Back from Checkout and from the portal: the buttons are enabled again

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 < 60s for the quick run
  • nyquist_compliant: true set in frontmatter

Approval: validated 2026-10-14 by the 18.1-06 gate run (PHASE181_REQUIRE_POSTGRES=1 bash scripts/check-phase18.1.sh --all, postgres run on a Docker host); revalidated 2026-10-16 for the gap closure (plans 07 to 09) by the 18.1-09 gate run, the same command on a Docker host, every stage PASS