@rune-kit/rune 2.1.1 → 2.2.1

package/extensions/ecommerce/PACK.md

@@ -1,242 +1,58 @@
 ---
 name: "@rune/ecommerce"
-description: E-commerce patterns — Shopify development, payment integration, shopping cart, and inventory management.
+description: E-commerce patterns — Shopify development, payment integration, subscription billing, shopping cart, inventory management, order lifecycle, and tax compliance.
 metadata:
   author: runedev
-  version: "0.1.0"
+  version: "0.3.0"
   layer: L4
   price: "$12"
   target: E-commerce developers
+  format: split
 ---
 
 # @rune/ecommerce
 
 ## Purpose
 
-E-commerce codebases fail at the seams between systems: payment intents that succeed but order records that don't get created, inventory counts that go negative during flash sales, carts that lose items when users sign in, and Shopify themes that break on metafield updates. This pack addresses the full order lifecycle — storefront to payment to fulfillment — with patterns that handle the race conditions, state machines, and distributed system problems that every commerce platform eventually hits.
+E-commerce codebases fail at the seams between systems: payment intents that succeed but order records that don't get created, inventory counts that go negative during flash sales, subscription proration that charges the wrong amount mid-cycle, tax calculations that use cart-time rates instead of checkout-time rates, carts that lose items when users sign in, and webhook handlers that process the same event twice. This pack addresses the full order lifecycle — storefront to payment to fulfillment — with patterns that handle the race conditions, state machines, and distributed system problems that every commerce platform eventually hits.
 
 ## Triggers
 
 - Auto-trigger: when `shopify.app.toml`, `*.liquid`, `cart`, `checkout`, `stripe` in payment context, `inventory` schema detected
 - `/rune shopify-dev` — audit Shopify theme or app architecture
 - `/rune payment-integration` — set up or audit payment flows
+- `/rune subscription-billing` — set up or audit recurring billing
 - `/rune cart-system` — build or audit cart architecture
 - `/rune inventory-mgmt` — audit inventory tracking and stock management
+- `/rune order-management` — audit order lifecycle and fulfillment
+- `/rune tax-compliance` — set up or audit tax calculation
 - Called by `cook` (L1) when e-commerce project detected
 - Called by `launch` (L1) when preparing storefront for production
 
 ## Skills Included
 
-### shopify-dev
-
-Shopify development patterns — Liquid templates, Shopify API, Hydrogen/Remix storefronts, metafields, theme architecture.
-
-#### Workflow
-
-**Step 1 — Detect Shopify architecture**
-Use Glob to find `shopify.app.toml`, `*.liquid`, `remix.config.*`, `hydrogen.config.*`. Use Grep to find Storefront API queries (`#graphql`), Admin API calls, and metafield references. Classify: theme app extension, custom app, or Hydrogen storefront.
-
-**Step 2 — Audit theme and API usage**
-Check for: Liquid templates without `| escape` filter (XSS), Storefront API queries without pagination, hardcoded product IDs, missing metafield type validation, theme sections without `schema` blocks, and deprecated API version usage.
-
-**Step 3 — Emit optimized patterns**
-For Hydrogen: emit typed Storefront API loader with proper caching. For theme: emit section schema with metafield integration. For apps: emit webhook handler with HMAC verification.
-
-#### Example
-
-```typescript
-// Hydrogen — typed Storefront API loader with caching
-import { json, type LoaderFunctionArgs } from '@shopify/remix-oxygen';
-
-const PRODUCT_QUERY = `#graphql
-  query Product($handle: String!) {
-    product(handle: $handle) {
-      id title description
-      variants(first: 10) {
-        nodes { id title price { amount currencyCode } availableForSale }
-      }
-      metafield(namespace: "custom", key: "care_instructions") { value type }
-    }
-  }
-` as const;
-
-export async function loader({ params, context }: LoaderFunctionArgs) {
-  const { product } = await context.storefront.query(PRODUCT_QUERY, {
-    variables: { handle: params.handle! },
-    cache: context.storefront.CacheLong(),
-  });
-  if (!product) throw new Response('Not Found', { status: 404 });
-  return json({ product });
-}
-```
-
----
-
-### payment-integration
-
-Payment integration — Stripe Payment Intents, 3D Secure, webhook handling, refunds, PCI compliance.
-
-#### Workflow
-
-**Step 1 — Detect payment setup**
-Use Grep to find `stripe`, `paypal`, `@stripe/stripe-js`, payment-related endpoints. Read checkout handlers and webhook processors to understand: payment flow type, webhook events handled, and error recovery.
-
-**Step 2 — Audit payment security**
-Check for: missing idempotency keys on payment creation, webhook signature not verified, payment amount calculated client-side (manipulation risk), no 3D Secure handling, secret keys in client bundle, and missing failed payment recovery flow.
-
-**Step 3 — Emit robust payment flow**
-Emit: server-side Payment Intent creation with idempotency, 3D Secure handling, comprehensive webhook handler, and refund flow with audit trail.
-
-#### Example
-
-```typescript
-// Stripe Payment Intent — server-side, idempotent, 3DS-ready
-import Stripe from 'stripe';
-const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
-
-app.post('/api/checkout', async (req, res) => {
-  const { cartId, paymentMethodId } = req.body;
-  const cart = await cartService.getVerified(cartId); // server-side price calculation
-
-  const intent = await stripe.paymentIntents.create({
-    amount: cart.totalInCents, // ALWAYS server-calculated
-    currency: cart.currency,
-    payment_method: paymentMethodId,
-    confirm: true,
-    return_url: `${process.env.APP_URL}/checkout/complete`,
-    metadata: { cartId, userId: req.user.id },
-    idempotencyKey: `checkout-${cartId}-${Date.now()}`,
-  });
-
-  if (intent.status === 'requires_action') {
-    return res.json({ requiresAction: true, clientSecret: intent.client_secret });
-  }
-  if (intent.status === 'succeeded') {
-    await orderService.create(cart, intent.id);
-    return res.json({ success: true, orderId: intent.metadata.orderId });
-  }
-  res.status(400).json({ error: { code: 'PAYMENT_FAILED', message: 'Payment could not be processed' } });
-});
-```
-
----
-
-### cart-system
-
-Shopping cart architecture — state management, persistent carts, guest checkout, coupon/discount engine, tax calculation.
-
-#### Workflow
-
-**Step 1 — Detect cart architecture**
-Use Grep to find cart state: `cartStore`, `useCart`, `addToCart`, `localStorage.*cart`, `session.*cart`. Read cart-related components and API routes to understand: client vs server cart, persistence strategy, and discount handling.
-
-**Step 2 — Audit cart integrity**
-Check for: cart total calculated client-side only (price manipulation), no cart TTL (stale carts), missing guest-to-authenticated cart merge, race conditions on concurrent cart updates, coupons validated client-side, and no stock check at add-to-cart time.
-
-**Step 3 — Emit cart patterns**
-Emit: server-authoritative cart with client cache, guest-to-auth merge flow, coupon validation middleware, and optimistic UI with server reconciliation.
-
-#### Example
-
-```typescript
-// Server-authoritative cart with Zustand client cache
-import { create } from 'zustand';
-import { persist } from 'zustand/middleware';
-
-interface CartStore {
-  items: CartItem[];
-  cartId: string | null;
-  addItem: (productId: string, variantId: string, qty: number) => Promise<void>;
-  mergeGuestCart: (userId: string) => Promise<void>;
-}
-
-const useCart = create<CartStore>()(persist((set, get) => ({
-  items: [], cartId: null,
-
-  addItem: async (productId, variantId, qty) => {
-    // Optimistic update
-    set(state => ({ items: [...state.items, { productId, variantId, qty, pending: true }] }));
-    // Server reconciliation (validates stock, calculates price)
-    const cart = await fetch('/api/cart/add', {
-      method: 'POST',
-      body: JSON.stringify({ cartId: get().cartId, productId, variantId, qty }),
-    }).then(r => r.json());
-    set({ items: cart.items, cartId: cart.id }); // server is source of truth
-  },
-
-  mergeGuestCart: async (userId) => {
-    const { cartId } = get();
-    if (!cartId) return;
-    const merged = await fetch('/api/cart/merge', {
-      method: 'POST', body: JSON.stringify({ guestCartId: cartId, userId }),
-    }).then(r => r.json());
-    set({ items: merged.items, cartId: merged.id });
-  },
-}), { name: 'cart-storage' }));
-```
-
----
-
-### inventory-mgmt
-
-Inventory management — stock tracking with optimistic locking, variant management, low stock alerts, backorder handling.
-
-#### Workflow
-
-**Step 1 — Detect inventory model**
-Use Grep to find stock-related code: `stock`, `inventory`, `quantity`, `variant`, `warehouse`, `sku`. Read schema files to understand: single vs multi-warehouse, variant structure, and reservation model.
-
-**Step 2 — Audit stock integrity**
-Check for: stock decremented without transaction (oversell risk), no optimistic locking on concurrent updates, inventory checked at cart-add but not at checkout (stale check), missing low-stock alerts, and no backorder handling for out-of-stock items.
-
-**Step 3 — Emit inventory patterns**
-Emit: atomic stock reservation with optimistic locking (version field), reservation expiry for abandoned checkouts, low-stock alert trigger, and backorder queue.
-
-#### Example
-
-```typescript
-// Atomic stock reservation with optimistic locking (Prisma)
-async function reserveStock(variantId: string, qty: number, orderId: string) {
-  const MAX_RETRIES = 3;
-  for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
-    const variant = await prisma.variant.findUniqueOrThrow({ where: { id: variantId } });
-
-    if (variant.stock < qty && !variant.allowBackorder) {
-      throw new Error(`Insufficient stock: ${variant.stock} available, ${qty} requested`);
-    }
-
-    try {
-      const updated = await prisma.variant.update({
-        where: { id: variantId, version: variant.version }, // optimistic lock
-        data: {
-          stock: { decrement: qty },
-          version: { increment: 1 },
-          reservations: { create: { orderId, qty, expiresAt: addMinutes(new Date(), 15) } },
-        },
-      });
-
-      if (updated.stock <= updated.lowStockThreshold) {
-        await alertService.trigger('LOW_STOCK', { variantId, currentStock: updated.stock });
-      }
-      return updated;
-    } catch (e) {
-      if (attempt === MAX_RETRIES - 1) throw new Error('Stock reservation failed: concurrent modification');
-    }
-  }
-}
-```
-
----
-
-## Connections
-
-```
-Calls → sentinel (L2): PCI compliance audit on payment code
-Calls → db (L2): schema design for orders, inventory, carts
-Called By ← cook (L1): when e-commerce project detected
-Called By ← launch (L1): pre-launch checkout verification
-Called By ← review (L2): when payment or cart code under review
-```
+| Skill | Model | Description |
+|-------|-------|-------------|
+| [shopify-dev](skills/shopify-dev.md) | sonnet | Shopify theme, Hydrogen, app architecture — Liquid templates, Storefront API, metafields, webhook HMAC verification. |
+| [payment-integration](skills/payment-integration.md) | sonnet | Stripe, 3DS, webhooks, fraud detection, multi-currency, Vietnamese gateways (SePay, VNPay, MoMo). |
+| [subscription-billing](skills/subscription-billing.md) | sonnet | Trials, proration, dunning, plan changes mid-cycle, usage-based billing, cancellation flows. |
+| [cart-system](skills/cart-system.md) | sonnet | Persistent carts, guest-to-auth merge, server-authoritative totals, coupon engine. |
+| [inventory-mgmt](skills/inventory-mgmt.md) | sonnet | Atomic stock with optimistic locking, reservations, low-stock alerts, backorder handling. |
+| [order-management](skills/order-management.md) | sonnet | State machine, fulfillment, refund/return flows, reconciliation, webhook fan-out. |
+| [tax-compliance](skills/tax-compliance.md) | sonnet | Tax APIs, EU VAT reverse charge, digital goods tax, audit trail per order line item. |
+
+## Common Workflows
+
+| Workflow | Skills Involved | Description |
+|----------|----------------|-------------|
+| Full checkout | cart-system → tax-compliance → payment-integration → order-management | Complete purchase from cart to confirmation |
+| Flash sale | inventory-mgmt → cart-system → payment-integration | High-concurrency stock control |
+| Subscription signup | cart-system → payment-integration → subscription-billing | Free trial with payment method upfront |
+| Plan upgrade | subscription-billing → payment-integration → tax-compliance | Mid-cycle upgrade with proration invoice |
+| Order cancellation | order-management → inventory-mgmt → payment-integration | Cancel + release stock + issue refund |
+| New market launch | tax-compliance → payment-integration (multi-currency) → shopify-dev | Localization, VAT, FX pricing |
+| Fraud review | payment-integration (fraud patterns) → order-management | Risk scoring before order fulfilment |
+| Product catalog | shopify-dev → inventory-mgmt | Variant structure + stock sync |
 
 ## Tech Stack Support
 
@@ -246,35 +62,55 @@ Called By ← review (L2): when payment or cart code under review
 | Custom | Next.js 16 / SvelteKit | Stripe | Most flexible |
 | Headless | Any frontend | Stripe / PayPal | API-first commerce |
 | Medusa.js | Next.js | Stripe / PayPal | Open-source alternative |
+| Saleor | React / Next.js | Stripe / Braintree | GraphQL-first |
 
-## Constraints
+## Connections
 
-1. MUST calculate all prices server-side — never trust client-submitted amounts for payment.
-2. MUST use idempotency keys on all payment creation API calls — prevent double charges.
-3. MUST use optimistic locking or database transactions for inventory updates — prevent overselling.
-4. MUST verify webhook signatures before processing any payment events.
-5. MUST validate coupons and discounts server-side — client-side validation is bypassable.
+```
+Calls → sentinel (L2): PCI compliance audit on payment code, webhook security
+Calls → db (L2): schema design for orders, inventory, carts, subscriptions
+Calls → perf (L2): audit checkout page load, cart update latency
+Calls → verification (L3): run payment flow integration tests
+Called By ← cook (L1): when e-commerce project detected
+Called By ← launch (L1): pre-launch checkout verification
+Called By ← review (L2): when payment or cart code under review
+Called By ← ba (L2): requirements elicitation for e-commerce features
+```
 
 ## Sharp Edges
 
 | Failure Mode | Severity | Mitigation |
 |---|---|---|
-| Double charge from retried Payment Intent without idempotency key | CRITICAL | Always pass idempotencyKey derived from cartId; check for existing successful intent before creating new one |
+| Double charge from retried Payment Intent without idempotency key | CRITICAL | Derive idempotencyKey from `cartId-v${version}`, not timestamp; check for existing succeeded intent |
+| Webhook signature fails because `req.body` is parsed JSON instead of raw bytes | CRITICAL | Use `express.raw({ type: 'application/json' })` for webhook route; verify with `req.body` as Buffer |
 | Overselling during flash sale (stock goes negative) | CRITICAL | Use optimistic locking with version field; serializable isolation for high-contention items |
-| Webhook processes `payment_intent.succeeded` but order creation fails (payment taken, no order) | HIGH | Wrap order creation in transaction; implement reconciliation job that matches intents to orders |
+| Payment succeeded but order creation fails (money taken, no order record) | HIGH | Wrap in transaction; run reconciliation job matching payment intents to orders every hour |
+| Same webhook processed twice creates duplicate orders | HIGH | Store `event.id` in database; check before processing; wrap in transaction |
 | Guest cart items lost on login (separate cart created for auth user) | HIGH | Implement cart merge in auth callback; prefer server cart state over local |
-| Tax calculated at cart time but rate changed by checkout (wrong amount charged) | MEDIUM | Recalculate tax at payment creation time, not at cart add time |
+| Subscription proration charges wrong amount on mid-cycle plan change | HIGH | Explicitly set `proration_behavior`; preview proration with `stripe.invoices.retrieveUpcoming` |
+| Trial-to-paid conversion fails silently (no payment method on file) | HIGH | Require payment method at trial signup; set `missing_payment_method: 'cancel'` in trial settings |
+| Tax calculated at cart time but rate changed by checkout (wrong amount charged) | MEDIUM | Recalculate tax at payment creation time using shipping address, not cart-add time |
 | Liquid template outputs unescaped metafield content (XSS in Shopify theme) | HIGH | Always use `| escape` filter on user-generated metafield values |
+| Cancelled order stock not returned to inventory | MEDIUM | Use order state machine with side effects — cancellation always triggers `releaseOrderReservations` |
+| Reservation never expires for abandoned checkout (stock locked forever) | MEDIUM | Run reservation expiry job every 5 minutes; default reservation TTL = 15 minutes |
+| Stolen card fraud passes payment but triggers chargeback later | HIGH | Apply fraud scoring before confirmation; hold high-risk orders for manual review |
+| FX rate stale on multi-currency display — user sees wrong price | MEDIUM | Cache FX rates max 15 minutes; show rate timestamp to user; always charge in store base currency |
 
 ## Done When
 
-- Checkout flow completes end-to-end: cart → payment → order confirmation
+- Checkout flow completes end-to-end: cart → tax → payment → order confirmation
+- Subscription lifecycle handles trial → active → past_due → cancelled with proper dunning
 - Inventory accurately tracks stock with no overselling under concurrent load
-- Webhooks are idempotent and handle all payment lifecycle events
+- Order state machine enforces valid transitions with side effects (stock release, refunds, notifications)
+- Webhooks are idempotent, signature-verified, and handle all payment/subscription lifecycle events
+- Tax calculated at checkout with audit trail stored per order line item
 - Guest-to-authenticated cart merge works without data loss
-- All prices and discounts validated server-side
+- All prices, discounts, and coupons validated server-side
+- Reconciliation job catches payment/order mismatches
+- Fraud scoring applied to all orders; high-risk orders flagged for review
+- Multi-currency display works with cached FX rates; charges always in base currency
 - Structured report emitted for each skill invoked
 
 ## Cost Profile
 
-~8,000–14,000 tokens per full pack run (all 4 skills). Individual skill: ~2,000–4,000 tokens. Sonnet default. Use haiku for detection scans; escalate to sonnet for payment flow and inventory pattern generation.
+~14,000–26,000 tokens per full pack run (all 7 skills). Individual skill: ~2,000–4,000 tokens. Sonnet default. Use haiku for detection scans; escalate to sonnet for payment flow, subscription lifecycle, and order state machine generation.

package/extensions/ecommerce/skills/cart-system.md

@@ -0,0 +1,79 @@
+---
+name: "cart-system"
+pack: "@rune/ecommerce"
+description: "Shopping cart architecture — state management, persistent carts, guest checkout, coupon/discount engine, guest-to-auth cart merge."
+model: sonnet
+tools: [Read, Edit, Write, Grep, Glob, Bash]
+---
+
+# cart-system
+
+Shopping cart architecture — state management, persistent carts, guest checkout, coupon/discount engine, guest-to-auth cart merge.
+
+#### Workflow
+
+**Step 1 — Detect cart architecture**
+Use Grep to find cart state: `cartStore`, `useCart`, `addToCart`, `localStorage.*cart`, `session.*cart`. Read cart-related components and API routes to understand: client vs server cart, persistence strategy, and discount handling.
+
+**Step 2 — Audit cart integrity**
+Check for:
+- Cart total calculated client-side only (price manipulation — attacker changes localStorage price)
+- No cart TTL (stale carts hold inventory reservations indefinitely)
+- Missing guest-to-authenticated cart merge (items lost on login)
+- Race conditions on concurrent cart updates (two tabs adding items, last write wins)
+- Coupons validated client-side (attacker applies any discount code)
+- No stock check at add-to-cart time (user adds 100 items, stock is 3)
+- Cart stored in localStorage only (lost on device switch, no cross-device)
+
+**Step 3 — Emit cart patterns**
+Emit: server-authoritative cart with client cache, guest-to-auth merge flow, coupon validation middleware, and optimistic UI with server reconciliation.
+
+#### Example
+
+```typescript
+// Server-authoritative cart with Zustand client cache
+import { create } from 'zustand';
+import { persist } from 'zustand/middleware';
+
+interface CartStore {
+  items: CartItem[];
+  cartId: string | null;
+  addItem: (productId: string, variantId: string, qty: number) => Promise<void>;
+  mergeGuestCart: (userId: string) => Promise<void>;
+}
+
+const useCart = create<CartStore>()(persist((set, get) => ({
+  items: [], cartId: null,
+
+  addItem: async (productId, variantId, qty) => {
+    // Optimistic update (show item immediately)
+    set(state => ({ items: [...state.items, { productId, variantId, qty, pending: true }] }));
+    // Server reconciliation (validates stock, calculates price, applies discounts)
+    const cart = await fetch('/api/cart/add', {
+      method: 'POST',
+      body: JSON.stringify({ cartId: get().cartId, productId, variantId, qty }),
+    }).then(r => r.json());
+    set({ items: cart.items, cartId: cart.id }); // server is source of truth
+  },
+
+  mergeGuestCart: async (userId) => {
+    const { cartId } = get();
+    if (!cartId) return;
+    const merged = await fetch('/api/cart/merge', {
+      method: 'POST', body: JSON.stringify({ guestCartId: cartId, userId }),
+    }).then(r => r.json());
+    set({ items: merged.items, cartId: merged.id });
+  },
+}), { name: 'cart-storage' }));
+
+// Server — coupon validation (NEVER trust client)
+app.post('/api/cart/apply-coupon', async (req, res) => {
+  const { cartId, code } = req.body;
+  const coupon = await couponService.validate(code); // checks: exists, not expired, usage limit
+  if (!coupon) return res.status(400).json({ error: 'INVALID_COUPON' });
+
+  const cart = await cartService.applyCoupon(cartId, coupon);
+  // Recalculate totals server-side after discount
+  res.json({ cart: cartService.calculateTotals(cart) });
+});
+```

package/extensions/ecommerce/skills/inventory-mgmt.md

@@ -0,0 +1,102 @@
+---
+name: "inventory-mgmt"
+pack: "@rune/ecommerce"
+description: "Inventory management — stock tracking with optimistic locking, variant management, low stock alerts, backorder handling, reservation expiry."
+model: sonnet
+tools: [Read, Edit, Write, Grep, Glob, Bash]
+---
+
+# inventory-mgmt
+
+Inventory management — stock tracking with optimistic locking, variant management, low stock alerts, backorder handling, reservation expiry.
+
+#### Workflow
+
+**Step 1 — Detect inventory model**
+Use Grep to find stock-related code: `stock`, `inventory`, `quantity`, `variant`, `warehouse`, `sku`. Read schema files to understand: single vs multi-warehouse, variant structure, and reservation model.
+
+**Step 2 — Audit stock integrity**
+Check for:
+- Stock decremented without transaction (oversell risk under concurrent load)
+- No optimistic locking on concurrent updates (version field or `FOR UPDATE` lock)
+- Inventory checked at cart-add but not at checkout (stale check — stock sold out between add and pay)
+- Missing low-stock alerts (ops team discovers stockout from customer complaints)
+- No reservation expiry for abandoned checkouts (stock locked forever)
+- No backorder handling for out-of-stock items (zero stock = hard error vs queue)
+- Flash sale race condition: 10 users checkout simultaneously with 3 items left = 7 oversold orders
+
+**Step 3 — Emit inventory patterns**
+Emit: atomic stock reservation with optimistic locking (version field), reservation expiry job for abandoned checkouts, low-stock alert trigger, and backorder queue.
+
+#### Example
+
+```typescript
+// Atomic stock reservation with optimistic locking (Prisma)
+async function reserveStock(variantId: string, qty: number, orderId: string) {
+  const MAX_RETRIES = 3;
+  for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+    const variant = await prisma.variant.findUniqueOrThrow({ where: { id: variantId } });
+
+    if (variant.stock < qty && !variant.allowBackorder) {
+      throw new Error(`Insufficient stock: ${variant.stock} available, ${qty} requested`);
+    }
+
+    try {
+      const updated = await prisma.variant.update({
+        where: { id: variantId, version: variant.version }, // optimistic lock
+        data: {
+          stock: { decrement: qty },
+          version: { increment: 1 },
+          reservations: { create: { orderId, qty, expiresAt: addMinutes(new Date(), 15) } },
+        },
+      });
+
+      if (updated.stock <= updated.lowStockThreshold) {
+        await alertService.trigger('LOW_STOCK', { variantId, currentStock: updated.stock });
+      }
+      return updated;
+    } catch (e) {
+      if (attempt === MAX_RETRIES - 1) throw new Error('Stock reservation failed: concurrent modification');
+    }
+  }
+}
+
+// Reservation expiry job — release stock from abandoned checkouts
+async function releaseExpiredReservations() {
+  const expired = await prisma.reservation.findMany({
+    where: { expiresAt: { lt: new Date() }, status: 'PENDING' },
+  });
+
+  for (const reservation of expired) {
+    await prisma.$transaction([
+      prisma.variant.update({
+        where: { id: reservation.variantId },
+        data: { stock: { increment: reservation.qty } },
+      }),
+      prisma.reservation.update({
+        where: { id: reservation.id },
+        data: { status: 'EXPIRED' },
+      }),
+    ]);
+  }
+}
+
+// Inventory webhook — push stock changes to external systems (3PL, ERP)
+async function emitInventoryWebhook(variantId: string, newStock: number, event: string) {
+  const variant = await prisma.variant.findUniqueOrThrow({
+    where: { id: variantId },
+    include: { product: true },
+  });
+  const payload = {
+    event,                          // 'STOCK_UPDATED' | 'LOW_STOCK' | 'OUT_OF_STOCK'
+    sku: variant.sku,
+    variantId,
+    productId: variant.productId,
+    stock: newStock,
+    threshold: variant.lowStockThreshold,
+    timestamp: new Date().toISOString(),
+  };
+  // Fan-out to all registered webhook endpoints
+  await webhookFanOut(payload, 'inventory.*');
+}
+```

package/extensions/ecommerce/skills/order-management.md

@@ -0,0 +1,126 @@
+---
+name: "order-management"
+pack: "@rune/ecommerce"
+description: "Order lifecycle — state machine, fulfillment workflows, refund/return flows, email notifications, reconciliation, webhook fan-out."
+model: sonnet
+tools: [Read, Edit, Write, Grep, Glob, Bash]
+---
+
+# order-management
+
+Order lifecycle — state machine, fulfillment workflows, refund/return flows, email notifications, reconciliation, webhook fan-out.
+
+#### Workflow
+
+**Step 1 — Detect order model**
+Use Grep to find: `order`, `fulfillment`, `shipment`, `refund`, `return`, `order_status`, `OrderStatus`. Read schema to understand: order states, fulfillment model (self-ship, 3PL, dropship), and refund handling.
+
+**Step 2 — Audit order lifecycle**
+Check for:
+- No explicit state machine: order status updated with raw string assignment (typos, invalid transitions)
+- Missing reconciliation: payment succeeded but order creation failed (payment taken, no order)
+- Partial fulfillment not handled: multi-item order with one item backordered
+- Refund without inventory return: money refunded but stock not incremented back
+- No email notifications on state transitions (customer has no visibility)
+- Cancellation after partial fulfillment: must refund only unfulfilled items
+
+**Step 3 — Emit order patterns**
+Emit: typed state machine with valid transitions, reconciliation job, partial fulfillment handler, and refund flow with inventory return.
+
+#### Example
+
+```typescript
+// Order state machine with valid transitions
+type OrderStatus = 'pending' | 'confirmed' | 'processing' | 'partially_shipped' |
+                   'shipped' | 'delivered' | 'cancelled' | 'refunded';
+
+const VALID_TRANSITIONS: Record<OrderStatus, OrderStatus[]> = {
+  pending: ['confirmed', 'cancelled'],
+  confirmed: ['processing', 'cancelled'],
+  processing: ['partially_shipped', 'shipped', 'cancelled'],
+  partially_shipped: ['shipped', 'cancelled'],
+  shipped: ['delivered', 'refunded'],
+  delivered: ['refunded'],
+  cancelled: [],
+  refunded: [],
+};
+
+async function transitionOrder(orderId: string, newStatus: OrderStatus) {
+  const order = await prisma.order.findUniqueOrThrow({ where: { id: orderId } });
+  const currentStatus = order.status as OrderStatus;
+
+  if (!VALID_TRANSITIONS[currentStatus]?.includes(newStatus)) {
+    throw new Error(`Invalid transition: ${currentStatus} → ${newStatus}`);
+  }
+
+  const updated = await prisma.$transaction(async (tx) => {
+    const result = await tx.order.update({
+      where: { id: orderId },
+      data: {
+        status: newStatus,
+        statusHistory: { push: { from: currentStatus, to: newStatus, at: new Date() } },
+      },
+    });
+
+    // Side effects per transition
+    if (newStatus === 'cancelled') {
+      await releaseOrderReservations(tx, orderId);
+    }
+    if (newStatus === 'refunded') {
+      await processRefund(tx, orderId);
+      await returnInventory(tx, orderId);
+    }
+
+    return result;
+  });
+
+  // Notifications (outside transaction — don't block on email)
+  await notificationService.orderStatusChanged(updated);
+  return updated;
+}
+
+// Reconciliation job — find payments without orders
+async function reconcilePayments() {
+  const recentIntents = await stripe.paymentIntents.list({
+    created: { gte: Math.floor(Date.now() / 1000) - 3600 }, // last hour
+    limit: 100,
+  });
+
+  for (const intent of recentIntents.data) {
+    if (intent.status !== 'succeeded') continue;
+    const cartId = intent.metadata.cartId;
+    const order = await prisma.order.findFirst({ where: { paymentIntentId: intent.id } });
+
+    if (!order) {
+      // Payment succeeded but order not created — create it now
+      await orderService.createFromIntent(intent);
+      await alertService.trigger('RECONCILED_ORDER', { intentId: intent.id, cartId });
+    }
+  }
+}
+
+// Webhook fan-out for order status changes — notify 3PLs, ERPs, analytics
+async function webhookFanOut(payload: Record<string, unknown>, topic: string) {
+  const endpoints = await db.webhookEndpoint.findMany({
+    where: { topics: { has: topic }, active: true },
+  });
+  await Promise.allSettled(
+    endpoints.map(ep =>
+      fetch(ep.url, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'X-Rune-Signature': signPayload(payload, ep.secret),
+          'X-Rune-Topic': topic,
+          'X-Rune-Timestamp': String(Date.now()),
+        },
+        body: JSON.stringify(payload),
+        signal: AbortSignal.timeout(5000),
+      }).catch(err => {
+        // Log failure but don't throw — one bad endpoint shouldn't block others
+        console.error(`Webhook delivery failed for ${ep.url}:`, err.message);
+      })
+    )
+  );
+}
+```