@rune-kit/rune 2.10.0 → 2.11.0

package/extensions/ecommerce/PACK.md

@@ -1,116 +1,116 @@
----
-name: "@rune/ecommerce"
-description: E-commerce patterns — Shopify development, payment integration, subscription billing, shopping cart, inventory management, order lifecycle, and tax compliance.
-metadata:
-  author: runedev
-  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, 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
-
-| 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
-
-| Platform | Framework | Payment | Notes |
-|----------|-----------|---------|-------|
-| Shopify | Hydrogen 2.x (Remix) | Shopify Payments | Storefront + Admin API |
-| 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 |
-
-## Connections
-
-```
-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 | 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 |
-| 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 |
-| 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 → 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
-- 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, 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
-
-~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.
+---
+name: "@rune/ecommerce"
+description: E-commerce patterns — Shopify development, payment integration, subscription billing, shopping cart, inventory management, order lifecycle, and tax compliance.
+metadata:
+  author: runedev
+  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, 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
+
+| 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
+
+| Platform | Framework | Payment | Notes |
+|----------|-----------|---------|-------|
+| Shopify | Hydrogen 2.x (Remix) | Shopify Payments | Storefront + Admin API |
+| 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 |
+
+## Connections
+
+```
+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 | 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 |
+| 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 |
+| 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 → 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
+- 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, 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
+
+~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

@@ -1,79 +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) });
-});
-```
+---
+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

@@ -1,102 +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.*');
-}
-```
+---
+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.*');
+}
+```