@sadrmanesh/commerce-agent-skills 0.3.1 → 0.3.3

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## [Unreleased]
+
+## [0.3.3] - 2026-11-04
+
+### Fixed
+
+- `allocate-stock.mjs` could oversell when an order had two lines for the same SKU. The one-location check looked at each line alone, so two lines of 3 both fit a location with 4 free. It now sums quantities per SKU first.
+
+### Added
+
+- `reserve()` in `allocate-stock.mjs`, a check-and-set step that reserves stock only when enough is free. The allocator uses it.
+- Tests for two concurrent checkouts racing for the last unit, plus a test that runs the same race against a read-then-write reserve and expects it to oversell, so the race test shows it can fail. Removing the stock decrement, the availability check, or the per-SKU sum now fails the suite; before this change, removing the decrement still passed.
+
+### Changed
+
+- The package and every skill are now version 0.3.3.
+
+## [0.3.2] - 2026-10-31
+
+### Added
+
+- A `redelivery-after-timeout` eval task and worked example for `order-and-webhook-reliability`. The handler stored and applied the event, the sender timed out before the 2xx arrived and redelivered, and the answer must return 2xx without repeating a side effect such as a second fulfillment, email, or stock decrement. The skill explains this case, its verification list and gotchas cover it, and the rule has a matching line.
+- The skills, rules, and evaluation tasks as a Hugging Face dataset, <https://huggingface.co/datasets/sadrmanesh/commerce-agent-skills>, with a `skills` table, an `evals` table, and the installable folders. The README, the docs home page, and the installation guide link to it.
+- `.github/workflows/mirror.yml`, which mirrors `main` and tags to `gitlab.com/sadrmanesh/commerce-agent-skills` when the `GITLAB_TOKEN` secret is set, and skips cleanly otherwise.
+
+### Changed
+
+- The package and every skill are now version 0.3.2.
+
 ## [0.3.1] - 2026-10-30
 
 ### Added

package/README.md

@@ -2,7 +2,9 @@
 
 Skills and rules for AI coding agents that build e-commerce and marketplace products.
 
-**Documentation:** <https://sadrmanesh.github.io/commerce-agent-skills/>
+**Documentation:** <https://sadrmanesh.github.io/commerce-agent-skills/> · **Dataset:** [Hugging Face](https://huggingface.co/datasets/sadrmanesh/commerce-agent-skills)
+
+**Read more:** [Treat agent skills like code: evals, a strict validator, and an npx installer for commerce skills](https://dev.to/sadrmanesh/treat-agent-skills-like-code-evals-a-strict-validator-and-an-npx-installer-for-commerce-skills-13dk) on Dev.to · [The knowledge your senior engineers carry, packaged for coding agents](https://www.linkedin.com/pulse/knowledge-your-senior-engineers-carry-packaged-coding-sadrmanesh-xtenf/) on LinkedIn
 
 The skills follow the [Agent Skills](https://agentskills.io/specification) format: a folder, a `SKILL.md` file with `name` and `description`, and optional reference files and scripts. An agent that supports that format can load them. The format does not name an install path. [Installation](docs/installation.md) explains how to point your agent at these folders.
 
@@ -132,6 +134,24 @@ Later releases can add:
 
 See [CONTRIBUTING.md](CONTRIBUTING.md). Run the validator before opening a pull request. New skills need a matching rule, a row in `skills/catalog-order.txt`, and a place in `website/categories.json`.
 
+## Technical report
+
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.23883598.svg)](https://doi.org/10.5281/zenodo.23883598)
+
+commerce-agent-skills: Architectural Specification, Domain Constraints, and Evaluation Framework for E-Commerce AI Coding Agents. M. N. Sadrmanesh, Zenodo, 2026. <https://doi.org/10.5281/zenodo.23883598>
+
+```bibtex
+@techreport{sadrmanesh2026commerceagentskills,
+  author      = {Sadrmanesh, Mohammad Naser},
+  title       = {commerce-agent-skills: Architectural Specification, Domain Constraints, and Evaluation Framework for E-Commerce AI Coding Agents},
+  institution = {Zenodo},
+  year        = {2026},
+  version     = {1.0},
+  doi         = {10.5281/zenodo.23883598},
+  url         = {https://doi.org/10.5281/zenodo.23883598}
+}
+```
+
 ## License
 
 [MIT](LICENSE). Copyright (c) 2026 Naser Sadrmanesh.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sadrmanesh/commerce-agent-skills",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "Tool-agnostic skills and rules for AI coding agents that build e-commerce and marketplace products.",
   "keywords": [
     "agent-skills",

package/rules/order-and-webhook-reliability.md

@@ -6,6 +6,7 @@
 - Fetch the order or payment when the event is out of order or incomplete. Do not apply an older status over a newer one.
 - Compare paid amounts in integer minor units.
 - Make the paid transition idempotent so stock and receipt email run once.
+- Treat a redelivery after a timeout as a duplicate: if the inbox row is already `applied`, return 2xx and run no side effect again.
 - Write outbound webhooks from an outbox in the same transaction as the order change.
 - Acknowledge a WooCommerce activation ping with 2xx and do not create an order from it.
 - Return a retryable error only when the event was not stored. WooCommerce disables a webhook after more than five consecutive failures.

package/skills/b2b-pricing/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 compatibility: "The price resolver needs Node.js 20 or newer and no packages."
 metadata:
   author: Naser Sadrmanesh
-  version: "0.3.1"
+  version: "0.3.3"
 ---
 
 # B2B pricing

package/skills/catalog-import-and-migration/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 compatibility: "The row checker needs Node.js 20 or newer and no packages."
 metadata:
   author: Naser Sadrmanesh
-  version: "0.3.1"
+  version: "0.3.3"
 ---
 
 # Catalog import and migration

package/skills/checkout-ux-and-conversion/SKILL.md

@@ -4,7 +4,7 @@ description: "Design checkout so the full cost is visible before payment, guest
 license: MIT
 metadata:
   author: Naser Sadrmanesh
-  version: "0.3.1"
+  version: "0.3.3"
 ---
 
 # Checkout UX and conversion

package/skills/conversion-event-tracking/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 compatibility: "The event checker requires Node.js 20 or newer. No network access."
 metadata:
   author: Naser Sadrmanesh
-  version: "0.3.1"
+  version: "0.3.3"
 ---
 
 # Conversion event tracking

package/skills/ecommerce-seo-structured-data/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 compatibility: "The JSON-LD checker requires Node.js 20 or newer. No network access."
 metadata:
   author: Naser Sadrmanesh
-  version: "0.3.1"
+  version: "0.3.3"
 ---
 
 # Ecommerce SEO structured data

package/skills/fraud-and-risk-basics/SKILL.md

@@ -4,7 +4,7 @@ description: "Hold or review risky payments using provider signals, velocity, an
 license: MIT
 metadata:
   author: Naser Sadrmanesh
-  version: "0.3.1"
+  version: "0.3.3"
 ---
 
 # Fraud and risk basics

package/skills/google-merchant-product-feeds/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 compatibility: "The feed item checker requires Node.js 20 or newer. No network access."
 metadata:
   author: Naser Sadrmanesh
-  version: "0.3.1"
+  version: "0.3.3"
 ---
 
 # Google Merchant product feeds

package/skills/headless-nextjs-storefront/SKILL.md

@@ -4,7 +4,7 @@ description: "Build a Next.js storefront that loads catalog data on the server,
 license: MIT
 metadata:
   author: Naser Sadrmanesh
-  version: "0.3.1"
+  version: "0.3.3"
 ---
 
 # Headless Next.js storefront

package/skills/inventory-and-multi-warehouse/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 compatibility: "The allocation checker needs Node.js 20 or newer and no packages."
 metadata:
   author: Naser Sadrmanesh
-  version: "0.3.1"
+  version: "0.3.3"
 ---
 
 # Inventory and multi-warehouse

package/skills/inventory-and-multi-warehouse/scripts/allocate-stock.mjs

@@ -13,6 +13,17 @@ export function availableAt(location, sku) {
   return Math.max(0, (level.onHand ?? 0) - (level.reserved ?? 0) - (level.safetyStock ?? 0));
 }
 
+/**
+ * Reserves quantity units of sku in levels as one check-and-set step, so nothing can run
+ * between reading what is free and writing the new reserved count. Returns false and
+ * changes nothing when fewer units are free. A database version is one conditional UPDATE.
+ */
+export function reserve(levels, sku, quantity) {
+  if (availableAt({ levels }, sku) < quantity) return false;
+  levels[sku] = { ...levels[sku], reserved: (levels[sku].reserved ?? 0) + quantity };
+  return true;
+}
+
 /**
  * Returns { allocations: [{ sku, location, quantity }], shortfalls: [{ sku, quantity }], locations }.
  * Never allocates more than a location has available.
@@ -27,7 +38,10 @@ export function allocateOrder(order, stock) {
     if (!Number.isInteger(line.quantity) || line.quantity <= 0) throw new Error(`${line.sku}: quantity must be a positive whole number`);
   }
 
-  const single = eligible.find((location) => lines.every((line) => availableAt(location, line.sku) >= line.quantity));
+  // Sum repeated SKUs so two lines for the same item cannot each pass the check alone.
+  const totals = new Map();
+  for (const line of lines) totals.set(line.sku, (totals.get(line.sku) ?? 0) + line.quantity);
+  const single = eligible.find((location) => [...totals].every(([sku, quantity]) => availableAt(location, sku) >= quantity));
   if (single) {
     const allocations = lines.map((line) => ({ sku: line.sku, location: single.location, quantity: line.quantity }));
     return { allocations, shortfalls: [], locations: [single.location] };
@@ -48,7 +62,7 @@ export function allocateOrder(order, stock) {
       if (free === 0) continue;
       const take = Math.min(free, needed);
       allocations.push({ sku: line.sku, location: location.location, quantity: take });
-      levels[line.sku] = { ...levels[line.sku], reserved: (levels[line.sku].reserved ?? 0) + take };
+      reserve(levels, line.sku, take);
       used.add(location.location);
       needed -= take;
     }

package/skills/iranian-payment-gateways/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 compatibility: "The verify checker needs Node.js 20 or newer and no packages."
 metadata:
   author: Naser Sadrmanesh
-  version: "0.3.1"
+  version: "0.3.3"
 ---
 
 # Iranian payment gateways

package/skills/marketplace-search-and-ranking/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 compatibility: "The search-text normalizer requires Node.js 20 or newer. No network access."
 metadata:
   author: Naser Sadrmanesh
-  version: "0.3.1"
+  version: "0.3.3"
 ---
 
 # Marketplace search and ranking

package/skills/mcp-store-tooling/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 compatibility: "The tool definition checker needs Node.js 20 or newer and no packages."
 metadata:
   author: Naser Sadrmanesh
-  version: "0.3.1"
+  version: "0.3.3"
 ---
 
 # MCP store tooling

package/skills/multi-vendor-payouts/SKILL.md

@@ -4,7 +4,7 @@ description: "Split a marketplace order by vendor, record commission as ledger e
 license: MIT
 metadata:
   author: Naser Sadrmanesh
-  version: "0.3.1"
+  version: "0.3.3"
 ---
 
 # Multi-vendor payouts

package/skills/order-and-webhook-reliability/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 compatibility: "The signature checker requires Node.js 20 or newer. No network access."
 metadata:
   author: Naser Sadrmanesh
-  version: "0.3.1"
+  version: "0.3.3"
 ---
 
 # Order and webhook reliability
@@ -34,6 +34,8 @@ Do not dedupe only on a delivery attempt id. Those change when the sender times
 
 Store: event id, topic, resource id, raw body, signature verification time, and processing status (`stored`, `applied`, `ignored`). Ignore a duplicate by returning 2xx and the original result. A second apply is a bug.
 
+The most common duplicate is a redelivery after a timeout. The handler stored and applied the event, but the sender timed out before the 2xx arrived and posts the same event again, often with a new delivery id. The retry must find the inbox row already `applied`, return 2xx, and run no side effect: no second fulfillment, no second confirmation email, no second stock decrement. This only holds when each side effect is recorded in the same transaction that marks the row `applied`, or is keyed on the event id where it runs.
+
 ## Apply rules
 
 - Compare amounts in integer minor units before marking an order paid.
@@ -82,6 +84,7 @@ There is no separate backoff retry of one payload described here. Timeouts and r
 
 - Parsing JSON and signing `JSON.stringify(object)` will not match. The sender signed the original bytes, including key order and spacing.
 - Returning 200 before the inbox write loses the event if the process dies.
+- A slow handler that applies the event and sends the email before answering invites a timeout, and the redelivery sends the email again unless the email is tied to the `applied` row.
 - Applying events in arrival order without a version can reopen a canceled order.
 - Logging the raw body of a payment webhook can capture data you did not mean to keep. Store the body in the inbox with restricted access, and keep card data out of application logs.
 - A shared webhook secret across shops makes a signature from shop A valid on shop B. Use one secret per subscription.
@@ -90,6 +93,7 @@ There is no separate backoff retry of one payload described here. Timeouts and r
 
 - The checker accepts a known body and secret and rejects a one-byte change.
 - A duplicated delivery creates one inbox row and one state change.
+- A redelivery after a sender timeout, where the first attempt was stored and applied but the 2xx never arrived, returns 2xx and repeats no side effect: one fulfillment, one email, one stock decrement.
 - An older event received after a newer one does not downgrade a paid order.
 - A wrong amount does not mark the order paid.
 - Stopping the database makes the handler return a retryable status and, after recovery, the redelivered event still applies once.

package/skills/order-and-webhook-reliability/evals/examples/redelivery-after-timeout.md

@@ -0,0 +1,3 @@
+Treat the retry after a timeout as a duplicate of an event you already applied.
+
+Look up the inbox row by topic, order id, and `date_modified_gmt`. When its status is already `applied`, return 2xx with the original result and run no side effect: no second fulfillment, no second confirmation email, and no second stock decrement. Record the fulfillment, the email, and the stock change in the same transaction that marks the row `applied`, so the first attempt either did all of them once or none of them.

package/skills/order-and-webhook-reliability/evals/tasks.json

@@ -24,6 +24,21 @@
           "X-WC-Webhook-Delivery-ID"
         ]
       }
+    },
+    {
+      "id": "redelivery-after-timeout",
+      "task": "The order.paid handler stored and applied the event and created the fulfillment, but WooCommerce timed out before the 2xx arrived and posted the same event again. Make the retry safe.",
+      "expects": {
+        "must_include": [
+          "applied",
+          "2xx",
+          "side effect",
+          "timeout"
+        ],
+        "must_not_include": [
+          "X-WC-Webhook-Delivery-ID"
+        ]
+      }
     }
   ]
 }

package/skills/payment-gateway-integration/SKILL.md

@@ -4,7 +4,7 @@ description: "Integrate a payment provider with idempotent charges, signature-ch
 license: MIT
 metadata:
   author: Naser Sadrmanesh
-  version: "0.3.1"
+  version: "0.3.3"
 ---
 
 # Payment gateway integration

package/skills/product-catalog-modeling/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 compatibility: "The catalog checker requires Node.js 20 or newer. No network access."
 metadata:
   author: Naser Sadrmanesh
-  version: "0.3.1"
+  version: "0.3.3"
 ---
 
 # Product catalog modeling

package/skills/product-description-guardrails/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 compatibility: "The description checker requires Node.js 20 or newer. No network access."
 metadata:
   author: Naser Sadrmanesh
-  version: "0.3.1"
+  version: "0.3.3"
 ---
 
 # Product description guardrails

package/skills/returns-and-refunds/SKILL.md

@@ -4,7 +4,7 @@ description: "Run returns as a tracked RMA from request to inspection, refund on
 license: MIT
 metadata:
   author: Naser Sadrmanesh
-  version: "0.3.1"
+  version: "0.3.3"
 ---
 
 # Returns and refunds

package/skills/rtl-and-persian-localization/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 compatibility: "The Persian normalizer requires Node.js 20 or newer. No network access."
 metadata:
   author: Naser Sadrmanesh
-  version: "0.3.1"
+  version: "0.3.3"
 ---
 
 # RTL and Persian localization

package/skills/shopify-app-development/SKILL.md

@@ -4,7 +4,7 @@ description: "Build a Shopify app with the configured Admin API version, session
 license: MIT
 metadata:
   author: Naser Sadrmanesh
-  version: "0.3.1"
+  version: "0.3.3"
 ---
 
 # Shopify app development

package/skills/storefront-accessibility/SKILL.md

@@ -4,7 +4,7 @@ description: "Build product, cart, and checkout pages that meet WCAG 2.2 AA: key
 license: MIT
 metadata:
   author: Naser Sadrmanesh
-  version: "0.3.1"
+  version: "0.3.3"
 ---
 
 # Storefront accessibility

package/skills/storefront-performance/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 compatibility: "The Web Vitals checker needs Node.js 20 or newer and no packages."
 metadata:
   author: Naser Sadrmanesh
-  version: "0.3.1"
+  version: "0.3.3"
 ---
 
 # Storefront performance

package/skills/stripe-payments/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 compatibility: "The signature checker needs Node.js 20 or newer and no packages."
 metadata:
   author: Naser Sadrmanesh
-  version: "0.3.1"
+  version: "0.3.3"
 ---
 
 # Stripe payments

package/skills/subscription-billing/SKILL.md

@@ -4,7 +4,7 @@ description: "Model subscription state, renewal charges, proration, and dunning
 license: MIT
 metadata:
   author: Naser Sadrmanesh
-  version: "0.3.1"
+  version: "0.3.3"
 ---
 
 # Subscription billing

package/skills/tax-and-shipping/SKILL.md

@@ -4,7 +4,7 @@ description: "Calculate tax and shipping from the destination and the store's co
 license: MIT
 metadata:
   author: Naser Sadrmanesh
-  version: "0.3.1"
+  version: "0.3.3"
 ---
 
 # Tax and shipping

package/skills/vector-product-search/SKILL.md

@@ -4,7 +4,7 @@ description: "Add vector retrieval beside lexical product search, with one embed
 license: MIT
 metadata:
   author: Naser Sadrmanesh
-  version: "0.3.1"
+  version: "0.3.3"
 ---
 
 # Vector product search

package/skills/woocommerce-plugin-development/SKILL.md

@@ -4,7 +4,7 @@ description: "Build and change WooCommerce plugins with hooks, CRUD data stores,
 license: MIT
 metadata:
   author: Naser Sadrmanesh
-  version: "0.3.1"
+  version: "0.3.3"
 ---
 
 # WooCommerce plugin development

package/skills/woocommerce-rest-api/SKILL.md

@@ -4,7 +4,7 @@ description: "Call the WooCommerce REST API at wc/v3, including authentication,
 license: MIT
 metadata:
   author: Naser Sadrmanesh
-  version: "0.3.1"
+  version: "0.3.3"
 ---
 
 # WooCommerce REST API

package/skills/wordpress-plugin-security/SKILL.md

@@ -4,7 +4,7 @@ description: "Review and implement WordPress plugin security: capabilities, nonc
 license: MIT
 metadata:
   author: Naser Sadrmanesh
-  version: "0.3.1"
+  version: "0.3.3"
 ---
 
 # WordPress plugin security