Commerce Gold Standard Rubric

---
name: commerce-gold-standard-rubric
description: "Score a scaffolded commerce integration against the seven-dimension gold-standard rubric and run the BUILD-measure-fix iteration loop until it passes. Use after scaffolding a provider track, before calling it done. Each dimension is a falsifiable test; a live provider-sandbox test is required beyond the static checks."
---

# Commerce Gold-Standard Rubric

"Gold standard" here means **passed an executable rubric**, not "someone eyeballed it." Run this after scaffolding a provider track and before shipping it. Do not gate a whole release on all tracks at once — score and ship provider by provider (CLAUDE.md §6).

## The seven dimensions (each a falsifiable test)

| # | Dimension | Passing test |
|---|---|---|
| 1 | **PCI card-isolation** | No card field reaches a merchant-origin handler; only the provider iframe/hosted page collects the PAN. (`git grep` for card-field bindings to app routes = none.) |
| 2 | **Webhook signature verification** | A tampered-payload fixture is rejected; the compare is constant-time (`safeSignatureEqual`). |
| 3 | **Idempotency / exactly-once** | A replayed event id is a no-op; every mutating call carries an idempotency key. |
| 4 | **Secret / env hygiene** | `git grep` for secret-shaped strings returns nothing outside `.env.example`; publishable vs secret split correct. |
| 5 | **Decline / test-mode UX** | A declined-test-card fixture renders a user-facing error, not a stack trace; test mode + a local listener are wired. |
| 6 | **DX / abstraction** | The track imports `templates/shared/*` and declares `capabilities`; scaffold-to-green time recorded. |
| 7 | **Checkout a11y / i18n** | axe on the checkout surface = 0 critical; user-facing strings externalized. |

## Beyond static checks — the live-sandbox requirement

Dimensions 1, 2, 3, and 5 cannot be **fully** proven by static analysis. Each track ALSO requires a **live provider-sandbox integration test** covering the happy path **and the decline / 3DS path** (where a careless redirect can leak card data into a server log):

- **Stripe** — test mode + `stripe listen` / `stripe trigger`.
- **Square** — sandbox environment.
- **Shopify** — a development store.

The scaffolded consumer repo ships `scripts/verify-template.sh` so these checks are CI-runnable in the consumer's account, not eyeballed once.

## The iteration loop (what "loop until gold standard" means)

```
BUILD → MEASURE (score all 7 + run the sandbox test)
      → for each FAILING dimension, emit a concrete fix spec
      → APPLY the fix → re-MEASURE
      → repeat until 7/7 → freeze the track
```

Bound each track at **3 cycles**. A dimension still failing after 3 cycles escalates to the Team Lead as a design question: is the shared contract insufficient, or is this a genuine provider limitation to record as an accepted `N/A` (e.g. Shopify has no server-side authorize/capture)?