claude-code-arcane 1.3.0 → 1.4.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [1.4.0](https://github.com/SebastianLuser/claude-code-arcane/compare/v1.3.0...v1.4.0) (2026-06-22)
+
+
+### Features
+
+* **ecommerce:** add language-agnostic +ecommerce addon profile ([4ccfc38](https://github.com/SebastianLuser/claude-code-arcane/commit/4ccfc387e7ae48672a3ce5ddbc18bf778f68c883))
+
 # [1.3.0](https://github.com/SebastianLuser/claude-code-arcane/compare/v1.2.0...v1.3.0) (2026-06-21)
 
 

package/README.md

@@ -1,6 +1,6 @@
 # Claude Code Arcane
 
-> **321 skills, 86 agents, 15 hooks and 19 rules for Claude Code — selective deploy by profile.**
+> **333 skills, 87 agents, 15 hooks and 19 rules for Claude Code — selective deploy by profile.**
 
 A configuration harness installable via `npx`. Pick a **profile** that matches your stack and only the relevant tools get installed into your project's `.claude/` directory.
 
@@ -193,6 +193,7 @@ Once installed, manage the installation from within a Claude Code session:
 | `+marketing` | Content, growth, SEO/CRO, strategy, analytics | 44 | marketing |
 | `+regulatory` | ISO 13485, GDPR, FDA, SOC 2, ISMS, QMS, MDR | 13 | regulatory |
 | `+job-hunt` | Job search end-to-end — master profile, ATS CV, LinkedIn, portfolio, cover letters, outreach, interview prep | 12 | — |
+| `+ecommerce` | Commerce end-to-end agnóstico de lenguaje — data model, checkout, inventario, órdenes, pagos, promociones, shipping/tax, listings, analytics, feeds, storefront, suscripciones | 12 | ecommerce |
 | `+self-improving` | Agent self-improvement and skill extraction | 2 | — |
 | `+statusline` | Claude Code status bar (branch, division, session info) | 0 | — |
 
@@ -347,7 +348,7 @@ claude-code-arcane/
 │   ├── manifest.ts            # Read/write arcane-manifest.json
 │   ├── types.ts               # TypeScript interfaces
 │   └── utils.ts               # Cross-platform helpers
-├── skills/                    # 321 skills (flat, one dir per skill)
+├── skills/                    # 333 skills (flat, one dir per skill)
 ├── profiles/                  # 29 profiles (YAML)
 ├── agents/                    # 13 dirs, 86+ agents (Markdown)
 ├── hooks/                     # 15 lifecycle hooks (Bash)

package/agents/ecommerce/ecommerce-architect.md

@@ -0,0 +1,60 @@
+---
+name: ecommerce-architect
+description: "E-Commerce Architect. Owner del dominio commerce: modelado de catálogo, selección de plataforma (headless vs monolito vs SaaS), y review de diseño de checkout, pagos, inventario y órdenes. Agnóstico de lenguaje/framework. Usar como punto de entrada para arquitectura de un storefront o marketplace."
+tools: Read, Glob, Grep, Write, Edit, WebSearch
+model: opus
+maxTurns: 30
+memory: project
+disallowedTools: Bash
+skills: [commerce-data-model, payments-architecture, order-lifecycle, inventory-stock, storefront-architecture]
+---
+
+Sos el **E-Commerce Architect**. Tu rol: diseñar y revisar la arquitectura de dominio de un negocio de commerce — agnóstico de lenguaje, framework y plataforma. Decisiones de modelado y arquitectura, no código atado a un stack.
+
+## Responsabilidades
+
+1. **Domain modeling** — catálogo (product/variant/SKU), órdenes, inventario, pagos
+2. **Platform selection** — headless vs monolito vs SaaS vs composable, con trade-offs
+3. **Flow review** — checkout, pagos (idempotencia), inventario (overselling), órdenes (state machine)
+4. **Data integrity** — concurrencia, reservas, reconciliación de pagos
+5. **Routing** — derivar a la skill correcta según la necesidad
+
+## Routing Map
+
+| Necesidad | Skill |
+|-----------|-------|
+| Modelar catálogo / variantes / taxonomía / facets | `commerce-data-model` |
+| Carrito, checkout, abandoned-cart | `cart-checkout` |
+| Stock, overselling, restock forecast | `inventory-stock` |
+| Estados de orden, returns, refunds | `order-lifecycle` |
+| Arquitectura de pagos, webhooks, PCI | `payments-architecture` |
+| Implementación Stripe específica | `stripe-integration-expert` |
+| Promos, cupones, gift cards | `promotions-discounts` |
+| Envíos, impuestos, duties | `shipping-tax` |
+| Listings / PDP / marketplace copy | `product-listing` |
+| KPIs y eventos GA4 ecommerce | `commerce-analytics` |
+| Feeds Google/Meta | `merchant-feed` |
+| IA del storefront, páginas, headless | `storefront-architecture` |
+| Suscripciones, dunning | `subscription-billing` |
+
+## Protocolo (non-negotiables)
+
+1. **Data model primero** — sin un modelo de catálogo sólido, no se diseña checkout ni feeds.
+2. **Idempotencia en pagos** — toda creación de cargo lleva idempotency key. No se discute.
+3. **Server-authoritative** — precios, stock, impuestos y promos se recalculan en el server antes de cobrar.
+4. **Money en minor units enteros** — nunca floats para dinero.
+5. **Estados separados** — order / payment / fulfillment son dimensiones independientes.
+6. **Agnóstico** — si el pedido empuja a un framework concreto, lo aclarás y derivás a la skill/implementador correspondiente; no atás el diseño a un stack salvo que el usuario lo decida.
+
+## Platform Decision Matrix
+
+| Opción | Para | Costo |
+|--------|------|-------|
+| Monolito (SaaS/themed) | Time-to-market, catálogo estándar | Menos flexibilidad |
+| Headless | UX custom, omnichannel, escala | Mayor build/ops |
+| Composable | Enterprise, best-of-breed | Complejidad de integración |
+
+## Delegation
+
+**Delegate to:** las skills del routing map según el área.
+**Escala a humano:** decisiones de compliance fiscal (nexus, VAT) y selección final de PSP/plataforma — presentás opciones con trade-offs, decide el negocio.

package/docs/SKILLS-CATALOG.md

@@ -1,6 +1,6 @@
 # Skills Catalog — Claude Code Arcane
 
-Catalogo completo de los 321 skills disponibles para proyectos consumidores. Organizados por division.
+Catalogo completo de los 333 skills disponibles para proyectos consumidores. Organizados por division.
 
 ## Como ejecutar un skill
 
@@ -451,6 +451,25 @@ Desde cualquier proyecto que tenga Arcane configurado, escribi `/` seguido del n
 
 ---
 
+## E-Commerce (12 skills)
+
+| Skill | Descripcion | Uso |
+|-------|-------------|-----|
+| `/commerce-data-model` | Modela y audita el dominio de catalogo: product/variant/SKU/option, collections, atributos, taxonomia, faceted search y paginacion | `[model\|audit\|taxonomy]` |
+| `/cart-checkout` | Disena/audita carrito y checkout: estado del cart, multi-step vs one-page, guest checkout, abandoned-cart recovery | `[design\|audit\|abandoned]` |
+| `/inventory-stock` | Inventario y stock: tracking, optimistic locking anti-overselling, reservas, multi-location, restock forecast (script) | `[design\|forecast\|audit]` |
+| `/order-lifecycle` | State machine de ordenes: order/payment/fulfillment, returns/RMA, refunds, eventos/webhooks | `[design\|states\|returns]` |
+| `/payments-architecture` | Arquitectura de pagos PSP-agnostica: payment intents, idempotencia, webhooks fiables, reconciliacion, PCI, fraude | `[design\|webhooks\|audit]` |
+| `/promotions-discounts` | Motor de promociones: cupones, automaticos, BOGO, tiered, reglas de stacking/exclusividad, gift cards | `[design\|rules\|audit]` |
+| `/shipping-tax` | Envios (zonas/rates/metodos) e impuestos (VAT/GST/nexus, duties, landed cost) calculados server-side | `[shipping\|tax\|audit]` |
+| `/product-listing` | Optimiza PDP y listings de marketplace (Amazon A10/COSMO/Rufus), titulos, bullets, A+, copy en bulk | `[pdp\|marketplace\|bulk]` |
+| `/commerce-analytics` | KPIs de commerce (CR, AOV, CLV, cohort) + spec de eventos GA4 ecommerce + validador de dataLayer (script) | `[kpis\|events\|audit]` |
+| `/merchant-feed` | Feeds de producto Google Merchant / Meta Catalog: atributos requeridos, mapping y validacion (script) | `[validate\|generate\|map]` |
+| `/storefront-architecture` | IA del storefront (home/PLP/PDP/cart/checkout/search/megamenu) + decision headless-vs-monolito + performance | `[design\|pages\|headless]` |
+| `/subscription-billing` | Billing recurrente: modelos, ciclos, proration, trials, plan changes y dunning anti-churn involuntario | `[design\|dunning\|audit]` |
+
+---
+
 ## Skills internos de Arcane
 
 Estos skills son para mantener y desarrollar el propio repo Arcane:

package/docs/USER-GUIDE.md

@@ -2,7 +2,7 @@
 
 ## What is Arcane?
 
-Arcane is a configuration harness for [Claude Code](https://docs.anthropic.com/en/docs/claude-code). It provides a curated library of **321 skills**, **86 agents**, **15 hooks**, and **19 rules** that you selectively deploy into any project. Instead of shipping everything to every project (wasting tokens and degrading performance), you pick a **profile** that matches your stack and only the relevant tools get installed.
+Arcane is a configuration harness for [Claude Code](https://docs.anthropic.com/en/docs/claude-code). It provides a curated library of **333 skills**, **87 agents**, **15 hooks**, and **19 rules** that you selectively deploy into any project. Instead of shipping everything to every project (wasting tokens and degrading performance), you pick a **profile** that matches your stack and only the relevant tools get installed.
 
 ## Table of Contents
 
@@ -536,7 +536,7 @@ Yes, and it's recommended. This way everyone on the team gets the same Claude Co
 
 ### How many tokens does a profile consume?
 
-Each skill adds ~30-100 tokens to the system prompt. A typical base profile (20-30 skills) adds ~1-2k tokens. The core profile adds ~500 tokens. Compare that to loading all 321 skills, which is why selective deploy matters.
+Each skill adds ~30-100 tokens to the system prompt. A typical base profile (20-30 skills) adds ~1-2k tokens. The core profile adds ~500 tokens. Compare that to loading all 333 skills, which is why selective deploy matters.
 
 ### Why replace instead of merge on install?
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-arcane",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Skills, agents, hooks and rules for Claude Code — installable via npx arcane",
   "type": "module",
   "bin": {

package/profiles/ecommerce.yaml

@@ -0,0 +1,48 @@
+name: ecommerce
+description: "E-Commerce — dominio commerce end-to-end agnostico de lenguaje: data model, carrito/checkout, inventario, ordenes, pagos, promociones, shipping/tax, listings, analytics, feeds, storefront y suscripciones"
+type: addon
+
+skills:
+  # net-new (12)
+  - commerce-data-model
+  - cart-checkout
+  - inventory-stock
+  - order-lifecycle
+  - payments-architecture
+  - promotions-discounts
+  - shipping-tax
+  - product-listing
+  - commerce-analytics
+  - merchant-feed
+  - storefront-architecture
+  - subscription-billing
+  # reutilizadas (existentes, relevantes a e-commerce)
+  - stripe-integration-expert
+  - page-cro
+  - form-cro
+  - schema-markup
+  - seo-audit
+  - analytics-tracking
+  - pricing-strategy
+  - ab-test-setup
+  - referral-program
+
+rules:
+  universal:
+    []
+  gamedev:
+    []
+
+agents:
+  - ecommerce
+
+permissions:
+  allow:
+    - "Bash(python *restock_forecast.py*)"
+    - "Bash(python3 *restock_forecast.py*)"
+    - "Bash(python *ga4_ecommerce_validate.py*)"
+    - "Bash(python3 *ga4_ecommerce_validate.py*)"
+    - "Bash(python *feed_validate.py*)"
+    - "Bash(python3 *feed_validate.py*)"
+  deny:
+    []

package/skills/cart-checkout/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: cart-checkout
+description: "Design and audit cart and checkout flows — cart state, multi-step vs one-page checkout, guest checkout, address/shipping/tax/payment steps, and abandoned-cart recovery. Platform-agnostic conversion and correctness patterns. Triggers: designing a checkout, auditing drop-off, planning abandoned-cart flows."
+argument-hint: "[design | audit | abandoned]"
+category: "ecommerce"
+user-invocable: true
+allowed-tools: Read, Glob, Grep
+---
+
+# Cart & Checkout
+
+The highest-leverage surface in commerce: where intent becomes revenue. Design carts and checkouts that are correct under concurrency and optimized for completion — without prescribing a framework.
+
+## Before Starting
+
+Gather: cart model (server-persisted vs client, guest vs account), checkout type (single vs multi-step), payment/shipping/tax requirements, and goal (design new flow, audit drop-off, or build abandoned-cart recovery).
+
+## How This Skill Works
+
+| Mode | Trigger | Output |
+|------|---------|--------|
+| **Design** | `design` | Cart state model + checkout step flow + edge cases |
+| **Audit** | `audit` | Friction/drop-off analysis with prioritized fixes |
+| **Abandoned** | `abandoned` | Recovery sequence (triggers, timing, channels) |
+
+---
+
+## Phase 1 — Cart State
+
+| Decision | Recommendation |
+|----------|----------------|
+| Persistence | Server-side cart keyed by session + user; merge on login |
+| Pricing | **Re-price at checkout** — never trust cart-stored prices |
+| Inventory | Soft-reserve at checkout start, not on add-to-cart |
+| Identity | Allow guest carts; merge guest → account without losing items |
+
+**Rule:** The cart is a draft, not a contract. Totals, stock, and promotions are recomputed server-side before payment.
+
+---
+
+## Phase 2 — Checkout Flow
+
+Canonical steps: **Cart → Identity → Shipping address → Shipping method → Payment → Review → Confirmation.**
+
+- **Guest checkout** is non-negotiable for B2C — forced account creation is the #1 avoidable drop-off.
+- Collect email first (enables abandoned-cart + receipts).
+- One-page vs multi-step: multi-step for complex shipping/tax; one-page for low-SKU/digital. Either way, show progress and never lose entered data on validation error.
+- Recompute tax/shipping when the address changes; show the final total before the pay button.
+- Make payment **idempotent** — a double-click must not double-charge (hand off to `payments-architecture`).
+
+For the full step-by-step field list, error handling, and address validation patterns, see [references/checkout-flow-spec.md](references/checkout-flow-spec.md).
+
+---
+
+## Phase 3 — Abandoned-Cart Recovery
+
+| Touch | Timing | Angle |
+|-------|--------|-------|
+| 1 | ~1h | Reminder ("you left these") |
+| 2 | ~24h | Help/objection handling + reviews |
+| 3 | ~72h | Incentive (discount) — only if margin allows |
+
+Capture email as early as possible; suppress recovery once the order completes; respect consent and frequency caps.
+
+---
+
+## Output Artifacts
+
+| Request | Output |
+|---------|--------|
+| Design flow | Cart model + annotated step diagram + edge-case list |
+| Audit | Drop-off table with severity and READY-to-ship fixes |
+| Abandoned | Trigger/timing/channel sequence + suppression rules |
+
+A checkout is **READY** when guest checkout works, prices/stock are re-validated server-side, payment is idempotent, and data survives validation errors.
+
+---
+
+## Related Skills
+
+- **payments-architecture**: owns the payment step (intents, idempotency, webhooks).
+- **shipping-tax**: computes the shipping and tax shown at checkout.
+- **promotions-discounts**: applies coupons/discounts at the cart.
+- **page-cro** / **form-cro**: deeper conversion optimization of the checkout UI.
+- **order-lifecycle**: takes over once the order is placed.

package/skills/cart-checkout/references/checkout-flow-spec.md

@@ -0,0 +1,50 @@
+# Checkout Flow — Step-by-Step Spec
+
+A platform-agnostic reference for a correct, conversion-optimized checkout. Adapt step granularity to your catalog (digital/low-SKU can collapse steps).
+
+## Steps, Fields & Validation
+
+| Step | Fields | Validation / behavior |
+|------|--------|-----------------------|
+| **Cart** | line items, qty, totals | Editable qty; re-price + re-check stock server-side on load |
+| **Identity** | email (required), login/guest | Collect email first; offer guest checkout prominently |
+| **Shipping address** | name, address, country, postal | Inline validation; address autocomplete if available |
+| **Shipping method** | method options + rates | Recompute on address change; show ETA + cost |
+| **Payment** | payment method | Tokenized/hosted fields; idempotency key generated here |
+| **Review** | full summary | Final total incl. tax/shipping/discounts before pay button |
+| **Confirmation** | order number | Show + email receipt; clear cart; fire `purchase` event |
+
+## Server-Side Re-Validation (before charge)
+Always recompute, never trust the client:
+1. Item availability (reserve with TTL)
+2. Prices (current catalog prices, not cart-stored)
+3. Promotions (re-evaluate eligibility + caps)
+4. Shipping + tax (against final address)
+5. Final total → only then create the payment intent
+
+## Error Handling
+- Never clear entered fields on a validation error.
+- Show errors inline next to the field, plus a summary.
+- Payment decline → keep the order in a recoverable state; let the shopper retry without re-entering everything.
+- Stock lost during checkout → tell the shopper exactly which line and offer alternatives.
+
+## Address Validation
+- Normalize country to ISO code; postal format per country.
+- Soft-validate (suggest correction) rather than hard-block where possible.
+
+## Abandoned-Cart Triggers
+| Touch | Timing | Content |
+|-------|--------|---------|
+| 1 | ~1h | "You left these" + cart contents |
+| 2 | ~24h | Objection handling, reviews, support offer |
+| 3 | ~72h | Incentive (only if margin allows) |
+
+Suppress all touches once `purchase` fires. Respect consent + frequency caps.
+
+## Verdict: READY when
+- [ ] Guest checkout works end-to-end
+- [ ] Email captured before payment
+- [ ] All totals recomputed server-side pre-charge
+- [ ] Payment is idempotent (no double-charge on retry/double-click)
+- [ ] Entered data survives validation errors
+- [ ] `purchase` event fires once with transaction id

package/skills/commerce-analytics/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: commerce-analytics
+description: "Define and audit e-commerce analytics — conversion rate, AOV, CLV, cohort/funnel metrics, and the standard GA4 ecommerce event spec (view_item, add_to_cart, begin_checkout, purchase). Includes a dataLayer event validator. Triggers: defining commerce KPIs, instrumenting GA4 ecommerce events, auditing tracking."
+argument-hint: "[kpis | events | audit]"
+category: "ecommerce"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash
+---
+
+# Commerce Analytics
+
+You cannot optimize what you mis-measure. Define the KPIs that actually move a store and instrument the standard ecommerce event spec correctly — platform-agnostic, with a validator for GA4 dataLayer events.
+
+## Before Starting
+
+Gather: current tracking (GA4/GTM/other), business model (one-time vs subscription), key conversion actions, and goal (define KPIs, design/instrument events, or audit existing tracking).
+
+## How This Skill Works
+
+| Mode | Trigger | Output |
+|------|---------|--------|
+| **KPIs** | `kpis` | KPI framework + dashboard spec |
+| **Events** | `events` | Ecommerce event taxonomy + dataLayer spec |
+| **Audit** | `audit` | Tracking gap + data-quality review |
+
+---
+
+## Phase 1 — Core KPIs
+
+| Metric | Formula | Watch for |
+|--------|---------|-----------|
+| **Conversion rate** | orders / sessions | Segment by device/channel |
+| **AOV** | revenue / orders | Moves with promos/bundles |
+| **CLV** | avg order value × frequency × lifespan | The number that justifies CAC |
+| **Cart abandonment** | 1 − (checkouts / carts) | Diagnoses checkout friction |
+| **Repeat rate** | repeat customers / total | Retention health |
+| **Sell-through** | units sold / units received | Feeds `inventory-stock` forecasts |
+
+**Rule:** Pair every acquisition metric with a margin metric — revenue growth on negative contribution margin is a trap.
+
+---
+
+## Phase 2 — The Ecommerce Event Spec
+
+The standard GA4 ecommerce funnel events, each carrying `currency` + an `items[]` array:
+
+`view_item_list → view_item → add_to_cart → begin_checkout → add_shipping_info → add_payment_info → purchase` (plus `remove_from_cart`, `refund`).
+
+Each `items[]` entry: `item_id`, `item_name`, `price`, `quantity` (+ optional `item_brand`, `item_category`, `item_variant`). `purchase` also needs `transaction_id` and `value`.
+
+Validate a captured dataLayer against this spec:
+
+```bash
+python skills/commerce-analytics/scripts/ga4_ecommerce_validate.py            # demo events
+python skills/commerce-analytics/scripts/ga4_ecommerce_validate.py events.json
+```
+
+It reports PASS/FAIL per event with the missing required fields. For the full taxonomy and parameter reference, see [references/ga4-ecommerce-events.md](references/ga4-ecommerce-events.md).
+
+---
+
+## Phase 3 — Audit & Data Quality
+
+Common faults: missing `transaction_id` (duplicate purchases), `value` excluding/including tax inconsistently, `items[]` absent on purchase, double-firing (GTM + hardcoded). Cross-check store revenue vs GA4 revenue — variance > 5% means a tracking bug.
+
+---
+
+## Output Artifacts
+
+| Request | Output |
+|---------|--------|
+| KPIs | KPI framework + dashboard layout |
+| Events | Event taxonomy + dataLayer spec |
+| Audit | Gap analysis + data-quality scorecard |
+
+Commerce tracking is **COMPLIANT** when the full funnel fires with valid `items[]` and `currency`, `purchase` carries a unique `transaction_id`, revenue reconciles within 5%, and KPIs pair growth with margin.
+
+---
+
+## Related Skills
+
+- **analytics-tracking**: general GA4/GTM setup this builds on for SaaS-style funnels.
+- **inventory-stock**: sell-through metrics feed restock forecasting.
+- **commerce-data-model**: item taxonomy maps to `items[]` parameters.
+- **ab-test-setup** / **campaign-analytics**: experimentation and campaign measurement.

package/skills/commerce-analytics/references/ga4-ecommerce-events.md

@@ -0,0 +1,63 @@
+# GA4 Ecommerce Event Taxonomy & Parameter Reference
+
+The standard funnel. Fire these with a consistent `items[]` shape so reports, funnels, and audiences work. The `ga4_ecommerce_validate.py` script checks a captured dataLayer against this spec.
+
+## The funnel
+```
+view_item_list → view_item → add_to_cart → view_cart → begin_checkout
+  → add_shipping_info → add_payment_info → purchase
+```
+Plus: `select_item`, `remove_from_cart`, `refund`.
+
+## Required parameters per event
+| Event | Required (beyond items[]) |
+|-------|---------------------------|
+| view_item | currency |
+| add_to_cart / remove_from_cart / view_cart | currency |
+| begin_checkout | currency |
+| add_shipping_info | currency |
+| add_payment_info | currency |
+| purchase | currency, value, transaction_id |
+| refund | currency, transaction_id |
+| view_item_list / select_item | (item_list_id / item_list_name recommended) |
+
+## items[] object
+| Field | Req? | Notes |
+|-------|------|-------|
+| item_id | yes | Map to SKU |
+| item_name | yes | Product/variant name |
+| price | recommended | Unit price (number) |
+| quantity | recommended | Defaults to 1 |
+| item_brand | optional | |
+| item_category | optional | Up to item_category5 |
+| item_variant | optional | e.g. "Red / M" |
+| discount | optional | Per-unit discount |
+| index | optional | Position in list |
+
+## Worked example — purchase
+```json
+{
+  "event": "purchase",
+  "ecommerce": {
+    "currency": "USD",
+    "value": 42.00,
+    "transaction_id": "T-1001",
+    "tax": 3.50,
+    "shipping": 5.00,
+    "items": [
+      { "item_id": "ACME-TEE-RED-M", "item_name": "Acme Cotton Tee",
+        "item_variant": "Red / M", "price": 21.00, "quantity": 2 }
+    ]
+  }
+}
+```
+
+## Common faults (audit checklist)
+- [ ] `purchase` missing `transaction_id` → duplicate purchases on refresh
+- [ ] `value` inconsistent about tax/shipping inclusion (pick one, document it)
+- [ ] `items[]` absent or empty on funnel events
+- [ ] Double-firing (GTM tag + hardcoded gtag)
+- [ ] Currency missing → revenue not attributed
+- [ ] Store revenue vs GA4 revenue variance > 5% → tracking bug
+
+Verdict: **COMPLIANT** when the full funnel fires with valid `items[]` + `currency`, `purchase` has a unique `transaction_id`, and revenue reconciles within 5%.

package/skills/commerce-analytics/scripts/ga4_ecommerce_validate.py

@@ -0,0 +1,134 @@
+"""
+ga4_ecommerce_validate.py — Validate a captured dataLayer against the GA4
+standard ecommerce event spec.
+
+Checks each event for: a known ecommerce event name, required top-level
+parameters (currency/value/transaction_id where applicable), a non-empty
+items[] array, and required per-item fields. No external dependencies.
+
+Usage:
+    python ga4_ecommerce_validate.py                 # built-in demo events
+    python ga4_ecommerce_validate.py events.json     # your captured dataLayer
+
+Input JSON: either a single event object or an array of event objects, each:
+    {"event": "purchase", "ecommerce": {"currency": "USD", "value": 42.0,
+        "transaction_id": "T123", "items": [{"item_id": "SKU1",
+        "item_name": "Tee", "price": 21.0, "quantity": 2}, ...]}}
+
+Some setups put params at the top level instead of under "ecommerce"; both
+shapes are accepted.
+"""
+
+import json
+import sys
+
+
+# event name -> required top-level (ecommerce) params beyond items[]
+EVENT_REQS = {
+    "view_item_list": [],
+    "view_item": ["currency"],
+    "select_item": [],
+    "add_to_cart": ["currency"],
+    "remove_from_cart": ["currency"],
+    "view_cart": ["currency"],
+    "begin_checkout": ["currency"],
+    "add_shipping_info": ["currency"],
+    "add_payment_info": ["currency"],
+    "purchase": ["currency", "value", "transaction_id"],
+    "refund": ["currency", "transaction_id"],
+}
+EVENTS_REQUIRING_ITEMS = set(EVENT_REQS) - {"refund"}
+ITEM_REQUIRED = ["item_id", "item_name"]  # GA4 needs id or name; we require both for quality
+ITEM_RECOMMENDED = ["price", "quantity"]
+
+
+DEMO_EVENTS = [
+    {"event": "view_item", "ecommerce": {"currency": "USD",
+        "items": [{"item_id": "ACME-TEE", "item_name": "Acme Tee", "price": 21.0}]}},
+    {"event": "add_to_cart", "ecommerce": {"currency": "USD",
+        "items": [{"item_id": "ACME-TEE", "item_name": "Acme Tee", "price": 21.0, "quantity": 2}]}},
+    {"event": "purchase", "ecommerce": {"currency": "USD", "value": 42.0, "transaction_id": "T-1001",
+        "items": [{"item_id": "ACME-TEE", "item_name": "Acme Tee", "price": 21.0, "quantity": 2}]}},
+    # intentionally broken: missing transaction_id + value, item missing name
+    {"event": "purchase", "ecommerce": {"currency": "USD",
+        "items": [{"item_id": "ACME-MUG", "price": 9.0}]}},
+    {"event": "add_to_cart", "ecommerce": {  # missing currency + empty items
+        "items": []}},
+]
+
+
+def get_ecom(event):
+    """Return the param dict — under 'ecommerce' or at the top level."""
+    if isinstance(event.get("ecommerce"), dict):
+        return event["ecommerce"]
+    return {k: v for k, v in event.items() if k != "event"}
+
+
+def validate_event(event, idx):
+    errors = []
+    name = event.get("event")
+    if not name:
+        return [f"event[{idx}]: missing 'event' name"], None
+    if name not in EVENT_REQS:
+        return [f"event[{idx}] '{name}': not a recognized GA4 ecommerce event"], name
+
+    ecom = get_ecom(event)
+
+    for param in EVENT_REQS[name]:
+        if param not in ecom or ecom[param] in (None, ""):
+            errors.append(f"missing required param '{param}'")
+
+    if name in EVENTS_REQUIRING_ITEMS:
+        items = ecom.get("items")
+        if not isinstance(items, list) or not items:
+            errors.append("missing or empty 'items[]'")
+        else:
+            for i, it in enumerate(items):
+                missing = [f for f in ITEM_REQUIRED if not it.get(f)]
+                if missing:
+                    errors.append(f"items[{i}]: missing {', '.join(missing)}")
+                rec_missing = [f for f in ITEM_RECOMMENDED if it.get(f) in (None, "")]
+                if rec_missing:
+                    errors.append(f"items[{i}]: (recommended) missing {', '.join(rec_missing)}")
+    return errors, name
+
+
+def main():
+    if len(sys.argv) > 1:
+        path = sys.argv[1]
+        try:
+            with open(path, encoding="utf-8") as f:
+                data = json.load(f)
+        except (OSError, json.JSONDecodeError) as e:
+            print(f"[ERROR] cannot read {path}: {e}")
+            sys.exit(1)
+    else:
+        print("[INFO] No JSON given - using built-in demo events.\n")
+        data = DEMO_EVENTS
+
+    events = data if isinstance(data, list) else [data]
+
+    total_fail = 0
+    for idx, event in enumerate(events):
+        errors, name = validate_event(event, idx)
+        hard = [e for e in errors if "(recommended)" not in e]
+        if hard:
+            total_fail += 1
+            print(f"FAIL  [{idx}] {name or '?'}")
+            for e in errors:
+                print(f"        - {e}")
+        else:
+            warn = [e for e in errors if "(recommended)" in e]
+            print(f"PASS  [{idx}] {name}")
+            for w in warn:
+                print(f"        ~ {w}")
+
+    print()
+    passed = len(events) - total_fail
+    verdict = "COMPLIANT" if total_fail == 0 else "NON-COMPLIANT"
+    print(f"{verdict}: {passed}/{len(events)} events passed.")
+    sys.exit(0 if total_fail == 0 else 1)
+
+
+if __name__ == "__main__":
+    main()