@sadrmanesh/commerce-agent-skills 0.0.0-stage → 0.3.0

package/skills/payment-gateway-integration/references/woocommerce-gateway.md

@@ -0,0 +1,67 @@
+# WooCommerce payment gateway
+
+Extend `WC_Payment_Gateway` and register it on `woocommerce_payment_gateways`.
+
+```php
+class Example_Gateway extends WC_Payment_Gateway {
+    public function __construct() {
+        $this->id                 = 'example';
+        $this->method_title       = __( 'Example', 'example-gateway' );
+        $this->method_description = __( 'Pay with Example.', 'example-gateway' );
+        $this->has_fields         = false;
+        $this->supports           = array( 'products' );
+        $this->init_form_fields();
+        $this->init_settings();
+        add_action( 'woocommerce_update_options_payment_gateways_' . $this->id, array( $this, 'process_admin_options' ) );
+    }
+
+    public function process_payment( $order_id ) {
+        $order = wc_get_order( $order_id );
+        if ( ! $order ) {
+            wc_add_notice( __( 'Order not found.', 'example-gateway' ), 'error' );
+            return array( 'result' => 'failure' );
+        }
+
+        // Create or reuse the provider payment with an idempotency key.
+        // Do not mark the order paid here unless the provider response is a confirmed capture.
+        // A hosted payment page uses the provider URL. An offline method uses get_return_url().
+        $redirect_url = $this->get_return_url( $order );
+
+        return array(
+            'result'   => 'success',
+            'redirect' => $redirect_url,
+        );
+    }
+
+    public function process_refund( $order_id, $amount = null, $reason = '' ) {
+        // Add 'refunds' to $supports only after this calls the provider and returns true on acceptance.
+        // On decline: return new WP_Error( 'example_refund_failed', __( 'The provider declined the refund.', 'example-gateway' ) );
+        return new WP_Error( 'example_refund_failed', __( 'Refunds are not implemented yet.', 'example-gateway' ) );
+    }
+}
+```
+
+## Paid, held, and failed
+
+- Confirmed capture: `$order->payment_complete( $transaction_id )`. That stores the transaction id, chooses `processing` or `completed` through `woocommerce_payment_complete_order_status`, and fires `woocommerce_payment_complete`.
+- Awaiting a bank transfer or webhook: `$order->update_status( 'on-hold', $note )`. Do not call `payment_complete()` for money you do not have.
+- Decline: `$order->update_status( 'failed', $note )` and `wc_add_notice()`.
+- Do not call `update_status( 'processing' )` for a successful capture. That skips the payment-complete path.
+
+`payment_complete()` is not a substitute for an idempotency check. Guard it with the stored transaction id or `$order->is_paid()` so a replay does not treat the order as newly paid. `is_paid()` is true for statuses in `woocommerce_order_is_paid_statuses`, which defaults to `processing` and `completed`.
+
+Empty the cart with `WC()->cart->empty_cart()` only after the shop accepts the attempt (redirect created, or payment confirmed), matching the policy in `SKILL.md`. Use `$this->get_return_url( $order )` when you return the shopper to the site. Do not call `wp_redirect()` inside `process_payment()`.
+
+## Blocks checkout
+
+A classic gateway is not automatically offered in the Checkout block. Register a payment method integration that extends `Automattic\WooCommerce\Blocks\Payments\Integrations\AbstractPaymentMethodType` on `woocommerce_blocks_payment_method_type_registration`, and declare `cart_checkout_blocks` compatibility from the main plugin file. Until that exists, say so in the plugin and test classic checkout separately.
+
+## Webhooks
+
+WooCommerce API callbacks under `/?wc-api=example` are not cookie-authenticated. Verify the provider signature there. The same rule applies to a custom REST route. Nonces do not apply.
+
+Store the transaction id with `payment_complete()`. Do not call `add_post_meta( $order_id, '_transaction_id', ... )`. That misses HPOS.
+
+## Refunds
+
+`process_refund()` must talk to the provider and return `true` only after the provider accepts the refund. Returning `true` without a provider call marks the WooCommerce refund as done while the money has not moved. Omit `refunds` from `$supports` until the method is real.

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

@@ -0,0 +1,91 @@
+---
+name: product-catalog-modeling
+description: "Model a sellable catalog of simple products, variants, attributes, SKUs, and stock, and check the model before importing it. Use when designing product data, variation matrices, inventory rules, or catalog imports."
+license: MIT
+compatibility: "The catalog checker requires Node.js 20 or newer. No network access."
+metadata:
+  author: Naser Sadrmanesh
+  version: "0.3.0"
+---
+
+# Product catalog modeling
+
+Use this skill before writing import code or a product schema. The document checked by [`scripts/validate-catalog.mjs`](scripts/validate-catalog.mjs) is a planning model. It is not a WooCommerce export. Map it to WooCommerce with [the variation notes](references/variation-model.md). An example that passes the checker is [`assets/example-catalog.json`](assets/example-catalog.json).
+
+## Procedure
+
+1. Decide the purchasable unit. A simple product is purchased as itself. A variable product is purchased as one variant. A grouped product is a collection of other products. An external product is sold somewhere else.
+2. Give every purchasable unit one SKU. SKUs are unique across the catalog, including variants.
+3. Model variation attributes as a fixed set of options. Every variant picks exactly one option for every variation attribute. Two variants cannot share a combination.
+4. Put the price and the stock record on the purchasable unit. A variable parent does not have its own price or SKU in this model.
+5. Run `node scripts/validate-catalog.mjs --file catalog.json` from this skill directory and fix every reported error before importing.
+
+## Document shape
+
+```json
+{
+  "products": [
+    {
+      "id": "shirt",
+      "type": "variable",
+      "sku": null,
+      "name": "Cotton shirt",
+      "attributes": [
+        { "code": "color", "name": "Color", "options": ["blue", "red"], "variation": true }
+      ],
+      "variants": [
+        {
+          "id": "shirt-blue",
+          "sku": "SHIRT-BLUE",
+          "attributes": { "color": "blue" },
+          "price": "19.00",
+          "currency": "USD",
+          "stock": { "managed": true, "quantity": 4, "backorders": "no", "status": "instock" }
+        }
+      ]
+    }
+  ]
+}
+```
+
+Rules the checker enforces:
+
+- `type` is `simple`, `variable`, `external`, or `grouped`.
+- `price` is a major-unit string with two decimal places, such as `"19.00"`. `currency` is an ISO 4217 code. Map to the store's decimal setting at the boundary. Do not send this string through a binary float.
+- Simple and external products require `sku`, `price`, and `currency`. External products also require `productUrl`.
+- Variable products require `sku: null`, no parent `price`, at least one attribute with `"variation": true`, and at least one variant. Each variant sets exactly those attributes.
+- Grouped products list `children` ids and do not carry a price.
+- `stock.managed: true` requires an integer `quantity` of zero or more. `stock.managed: false` requires `quantity: null`. `backorders` is `no`, `notify`, or `yes`.
+- Optional `stock.status` is `instock`, `outofstock`, or `onbackorder`. When quantity is managed, status should agree with quantity and backorders. The checker does not infer status for you.
+
+## Inventory rules
+
+- Managed stock is a quantity you decrement on paid orders and restore on cancel or refund, using the platform's stock API once.
+- Unmanaged stock is a status you set by hand (`instock` or `outofstock`). Do not also store a quantity.
+- Backorders mean you accept orders at zero. `notify` shows the shopper that the item is on backorder. `yes` allows it quietly. `no` stops the sale at zero.
+- A variable parent's availability is the rollup of its variants. Do not maintain a second parent quantity that can disagree with the variants.
+- Reservation during checkout, when the platform holds stock for unpaid orders, is part of available-to-sell. Do not subtract that hold a second time in your importer.
+
+## Attributes
+
+- A variation attribute changes the purchasable unit (size, color). It belongs in `attributes` with `variation: true` and on each variant.
+- A descriptive attribute (material, care) is not a variant axis. Store it with `variation: false` or as content. Do not create a variant per descriptive value.
+- Keep option values stable. Translate the display label, not the option code. The search skill depends on stable facet ids.
+
+## Gotchas
+
+- A parent price range is derived from variants. Writing a parent price and different variant prices hides which amount will be charged.
+- Duplicate SKUs across a simple product and a variant make stock and fulfillment ambiguous.
+- Cartesian explosions are real. Three attributes with ten options are a thousand variants. Split the product or drop an axis before generating them.
+- Currency is a property of the price, not of the shopper's browser. A multi-currency display converts from the stored currency. It does not create a second SKU.
+
+## Verification
+
+- The checker exits 0 on the catalog file.
+- Every SKU resolves to one purchasable unit.
+- A variant combination that is not for sale is absent, not stored with a blank price.
+- After import, the storefront price and stock for one variant match that variant's record, not the parent.
+
+## Evaluation
+
+Worked examples and the checks they must satisfy are in [evals/tasks.json](evals/tasks.json).

package/skills/product-catalog-modeling/assets/example-catalog.json

@@ -0,0 +1,45 @@
+{
+  "products": [
+    {
+      "id": "shirt",
+      "type": "variable",
+      "sku": null,
+      "name": "Cotton shirt",
+      "attributes": [
+        {
+          "code": "color",
+          "name": "Color",
+          "options": ["blue", "red"],
+          "variation": true
+        }
+      ],
+      "variants": [
+        {
+          "id": "shirt-blue",
+          "sku": "SHIRT-BLUE",
+          "attributes": { "color": "blue" },
+          "price": "19.00",
+          "currency": "USD",
+          "stock": { "managed": true, "quantity": 5, "backorders": "no", "status": "instock" }
+        },
+        {
+          "id": "shirt-red",
+          "sku": "SHIRT-RED",
+          "attributes": { "color": "red" },
+          "price": "21.00",
+          "currency": "USD",
+          "stock": { "managed": true, "quantity": 0, "backorders": "no", "status": "outofstock" }
+        }
+      ]
+    },
+    {
+      "id": "gift-card",
+      "type": "simple",
+      "sku": "GIFT-25",
+      "name": "Gift card",
+      "price": "25.00",
+      "currency": "USD",
+      "stock": { "managed": false, "quantity": null, "backorders": "no", "status": "instock" }
+    }
+  ]
+}

package/skills/product-catalog-modeling/evals/examples/create-variation.md

@@ -0,0 +1,10 @@
+Create the purchasable variation and give it the SKU.
+
+```php
+$variation = new WC_Product_Variation();
+$variation->set_parent_id( $product->get_id() );
+$variation->set_attributes( array( 'pa_color' => 'blue' ) );
+$variation->set_sku( 'SHIRT-BLUE' );
+$variation->set_regular_price( '19.00' );
+$variation->save();
+```

package/skills/product-catalog-modeling/evals/examples/sync-parent.md

@@ -0,0 +1,7 @@
+Sync the variable parent after the variations exist.
+
+```php
+WC_Product_Variable::sync( $product->get_id() );
+```
+
+The parent record does not carry the variation SKU or the charged price.

package/skills/product-catalog-modeling/evals/tasks.json

@@ -0,0 +1,29 @@
+{
+  "tasks": [
+    {
+      "id": "create-variation",
+      "task": "Create a WooCommerce variation with its own SKU and price under a variable parent that has no SKU.",
+      "expects": {
+        "must_include": [
+          "WC_Product_Variation",
+          "set_sku"
+        ],
+        "must_not_include": [
+          "update_post_meta"
+        ]
+      }
+    },
+    {
+      "id": "sync-parent",
+      "task": "After writing variations, refresh the parent price range and stock status from the children.",
+      "expects": {
+        "must_include": [
+          "WC_Product_Variable::sync"
+        ],
+        "must_not_include": [
+          "set_sku( 'PARENT' )"
+        ]
+      }
+    }
+  ]
+}

package/skills/product-catalog-modeling/references/variation-model.md

@@ -0,0 +1,71 @@
+# Mapping the catalog model to WooCommerce
+
+WooCommerce product types match this model: `simple`, `variable`, `external`, and `grouped`.
+
+## Global attributes
+
+Create a global attribute once, then attach terms. The taxonomy name is `pa_` plus the attribute slug. Variation attribute values stored on a `WC_Product_Variation` are term slugs, not translated labels.
+
+```php
+$product = new WC_Product_Variable();
+$product->set_name( 'Cotton shirt' );
+$product->set_status( 'publish' );
+
+$attribute = new WC_Product_Attribute();
+$attribute->set_id( wc_attribute_taxonomy_id_by_name( 'pa_color' ) );
+$attribute->set_name( 'pa_color' );
+$attribute->set_options( array( $blue_term_id, $red_term_id ) );
+$attribute->set_visible( true );
+$attribute->set_variation( true );
+$product->set_attributes( array( $attribute ) );
+$product->save();
+
+$variation = new WC_Product_Variation();
+$variation->set_parent_id( $product->get_id() );
+$variation->set_attributes( array( 'pa_color' => 'blue' ) );
+$variation->set_sku( 'SHIRT-BLUE' );
+$variation->set_regular_price( '19.00' );
+$variation->set_manage_stock( true );
+$variation->set_stock_quantity( 4 );
+$variation->set_backorders( 'no' );
+$variation->save();
+
+WC_Product_Variable::sync( $product->get_id() );
+```
+
+Call `WC_Product_Variable::sync()` after variant writes so the parent price range and stock status match the children. Skip it and the catalog can show the parent as out of stock while a variant has quantity.
+
+Local attributes (not a `pa_` taxonomy) are valid for a single product. Prefer global attributes when the same facet must be shared across products and search.
+
+## Simple products
+
+```php
+$product = new WC_Product_Simple();
+$product->set_name( 'Gift card' );
+$product->set_sku( 'GIFT-25' );
+$product->set_regular_price( '25.00' );
+$product->set_manage_stock( false );
+$product->set_stock_status( 'instock' );
+$product->save();
+```
+
+`set_regular_price()` takes a decimal string. Sale price is `set_sale_price()`. The active price follows WooCommerce sale schedule rules. Do not overwrite `_price` meta by hand.
+
+## SKU lookup
+
+`wc_get_product_id_by_sku()` resolves both parent products and variations. Uniqueness is enforced unless `wc_product_has_unique_sku` is filtered. Do not filter it to allow duplicates unless the shop has a separate identity for the sellable unit.
+
+## Stock
+
+- `set_manage_stock( true )` plus `set_stock_quantity()` is managed stock.
+- `set_stock_status()` is the manual status used when stock is not managed, and the cached status when it is.
+- Reducing stock for an order is `wc_reduce_stock_levels()` / `wc_maybe_reduce_stock_levels()`, which no-ops when `_order_stock_reduced` is already set. Call it from payment completion only if core has not already done so.
+- `woocommerce_hold_stock_minutes` (default 60) holds stock on unpaid pending orders. Importers and availability displays should use WooCommerce's availability helpers rather than subtracting `stock_quantity` a second time.
+
+## Grouped and external
+
+Grouped products store child ids. The price is the child's price. External products store a product URL and an optional button label. They are not stock-managed inside the shop.
+
+## Imports
+
+Resolve SKU to id before update. Create when absent. Wrap a large import in batches and call `WC_Product_Variable::sync()` per parent after its variants, not once for the whole catalog at the start. Delete a variant that left the model. Leaving it published sells a combination the model no longer allows.

package/skills/product-catalog-modeling/scripts/validate-catalog.mjs

@@ -0,0 +1,234 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+
+const TYPES = new Set(["simple", "variable", "external", "grouped"]);
+const BACKORDERS = new Set(["no", "notify", "yes"]);
+const STOCK_STATUS = new Set(["instock", "outofstock", "onbackorder"]);
+
+export function validateCatalog(document) {
+  const errors = [];
+  if (!document || !Array.isArray(document.products)) {
+    return ["Catalog root must be an object with a products array."];
+  }
+
+  const productIds = new Set();
+  const skus = new Set();
+
+  for (const [index, product] of document.products.entries()) {
+    const label = `products[${index}]`;
+    if (!product || typeof product !== "object") {
+      errors.push(`${label} must be an object`);
+      continue;
+    }
+    if (!isId(product.id)) {
+      errors.push(`${label}.id must be a non-empty string`);
+    } else if (productIds.has(product.id)) {
+      errors.push(`${label}.id duplicates ${product.id}`);
+    } else {
+      productIds.add(product.id);
+    }
+    if (!TYPES.has(product.type)) {
+      errors.push(`${label}.type must be simple, variable, external, or grouped`);
+      continue;
+    }
+    if (typeof product.name !== "string" || product.name.trim() === "") {
+      errors.push(`${label}.name is required`);
+    }
+
+    if (product.type === "simple") {
+      requireSku(product.sku, skus, `${label}.sku`, errors);
+      requirePrice(product, label, errors);
+      checkStock(product.stock, `${label}.stock`, errors, false);
+      reject(product.variants, `${label}.variants`, "simple products have no variants", errors);
+    } else if (product.type === "external") {
+      requireSku(product.sku, skus, `${label}.sku`, errors);
+      requirePrice(product, label, errors);
+      if (typeof product.productUrl !== "string" || product.productUrl.trim() === "") {
+        errors.push(`${label}.productUrl is required for external products`);
+      }
+      reject(product.variants, `${label}.variants`, "external products have no variants", errors);
+    } else if (product.type === "grouped") {
+      if (!Array.isArray(product.children) || product.children.length === 0) {
+        errors.push(`${label}.children must list at least one product id`);
+      }
+      if (product.price !== undefined) {
+        errors.push(`${label}.price belongs on the child products, not the grouped parent`);
+      }
+      reject(product.variants, `${label}.variants`, "grouped products have no variants", errors);
+    } else {
+      checkVariable(product, label, skus, errors);
+    }
+  }
+
+  const known = new Set(document.products.filter((product) => product && isId(product.id)).map((product) => product.id));
+  for (const [index, product] of document.products.entries()) {
+    if (!product || product.type !== "grouped" || !Array.isArray(product.children)) {
+      continue;
+    }
+    for (const child of product.children) {
+      if (!known.has(child) || child === product.id) {
+        errors.push(`products[${index}].children references unknown id ${child}`);
+      }
+    }
+  }
+
+  return errors;
+}
+
+function checkVariable(product, label, skus, errors) {
+  if (product.sku !== null) {
+    errors.push(`${label}.sku must be null; put SKUs on variants`);
+  }
+  if (product.price !== undefined) {
+    errors.push(`${label}.price must live on each variant so the purchasable price is explicit`);
+  }
+  const attributes = Array.isArray(product.attributes) ? product.attributes : [];
+  const variationAttributes = attributes.filter((attribute) => attribute && attribute.variation === true);
+  if (variationAttributes.length === 0) {
+    errors.push(`${label} needs at least one attribute with variation: true`);
+  }
+  const optionsByCode = new Map();
+  const codes = new Set();
+  for (const [index, attribute] of attributes.entries()) {
+    const attributeLabel = `${label}.attributes[${index}]`;
+    if (!attribute || !isId(attribute.code)) {
+      errors.push(`${attributeLabel}.code is required`);
+      continue;
+    }
+    if (codes.has(attribute.code)) {
+      errors.push(`${attributeLabel}.code duplicates ${attribute.code}`);
+    }
+    codes.add(attribute.code);
+    if (!Array.isArray(attribute.options) || attribute.options.length === 0 || attribute.options.some((option) => typeof option !== "string" || option === "")) {
+      errors.push(`${attributeLabel}.options must be a non-empty list of strings`);
+    } else if (new Set(attribute.options).size !== attribute.options.length) {
+      errors.push(`${attributeLabel}.options contains a duplicate`);
+    }
+    optionsByCode.set(attribute.code, new Set(attribute.options ?? []));
+  }
+
+  if (!Array.isArray(product.variants) || product.variants.length === 0) {
+    errors.push(`${label}.variants must contain at least one variant`);
+    return;
+  }
+
+  const combinations = new Set();
+  const variantIds = new Set();
+  for (const [index, variant] of product.variants.entries()) {
+    const variantLabel = `${label}.variants[${index}]`;
+    if (!variant || typeof variant !== "object") {
+      errors.push(`${variantLabel} must be an object`);
+      continue;
+    }
+    if (!isId(variant.id)) {
+      errors.push(`${variantLabel}.id is required`);
+    } else if (variantIds.has(variant.id)) {
+      errors.push(`${variantLabel}.id duplicates ${variant.id}`);
+    } else {
+      variantIds.add(variant.id);
+    }
+    requireSku(variant.sku, skus, `${variantLabel}.sku`, errors);
+    requirePrice(variant, variantLabel, errors);
+    checkStock(variant.stock, `${variantLabel}.stock`, errors, true);
+    const chosen = variant.attributes;
+    if (!chosen || typeof chosen !== "object" || Array.isArray(chosen)) {
+      errors.push(`${variantLabel}.attributes must map attribute codes to option values`);
+      continue;
+    }
+    const keys = Object.keys(chosen).sort();
+    const expected = variationAttributes.map((attribute) => attribute.code).filter(Boolean).sort();
+    if (keys.join("|") !== expected.join("|")) {
+      errors.push(`${variantLabel}.attributes must set exactly the variation attributes (${expected.join(", ")})`);
+    }
+    for (const key of keys) {
+      const allowed = optionsByCode.get(key);
+      if (!allowed || !allowed.has(chosen[key])) {
+        errors.push(`${variantLabel}.attributes.${key} value ${JSON.stringify(chosen[key])} is not an option`);
+      }
+    }
+    const signature = expected.map((key) => `${key}=${chosen[key]}`).join("&");
+    if (combinations.has(signature)) {
+      errors.push(`${variantLabel} repeats combination ${signature}`);
+    }
+    combinations.add(signature);
+  }
+}
+
+function requireSku(sku, skus, label, errors) {
+  if (typeof sku !== "string" || sku.trim() === "") {
+    errors.push(`${label} is required`);
+    return;
+  }
+  if (skus.has(sku)) {
+    errors.push(`${label} duplicates SKU ${sku}`);
+    return;
+  }
+  skus.add(sku);
+}
+
+function requirePrice(record, label, errors) {
+  if (typeof record.price !== "string" || !/^\d+\.\d{2}$/.test(record.price)) {
+    errors.push(`${label}.price must be a decimal string with two places, such as "19.00"`);
+  }
+  if (typeof record.currency !== "string" || !/^[A-Z]{3}$/.test(record.currency)) {
+    errors.push(`${label}.currency must be a 3-letter ISO 4217 code`);
+  }
+}
+
+function checkStock(stock, label, errors, required) {
+  if (stock === undefined) {
+    if (required) {
+      errors.push(`${label} is required`);
+    }
+    return;
+  }
+  if (!stock || typeof stock !== "object") {
+    errors.push(`${label} must be an object`);
+    return;
+  }
+  if (typeof stock.managed !== "boolean") {
+    errors.push(`${label}.managed must be true or false`);
+  }
+  if (stock.managed === true) {
+    if (!Number.isInteger(stock.quantity) || stock.quantity < 0) {
+      errors.push(`${label}.quantity must be an integer of zero or more when stock is managed`);
+    }
+  } else if (stock.quantity !== null && stock.quantity !== undefined) {
+    errors.push(`${label}.quantity must be null when stock is not managed`);
+  }
+  if (!BACKORDERS.has(stock.backorders)) {
+    errors.push(`${label}.backorders must be no, notify, or yes`);
+  }
+  if (stock.status !== undefined && !STOCK_STATUS.has(stock.status)) {
+    errors.push(`${label}.status must be instock, outofstock, or onbackorder`);
+  }
+}
+
+function reject(value, label, message, errors) {
+  if (value !== undefined && !(Array.isArray(value) && value.length === 0)) {
+    errors.push(`${label}: ${message}`);
+  }
+}
+
+function isId(value) {
+  return typeof value === "string" && value.trim() !== "";
+}
+
+const isCli = process.argv[1] && process.argv[1].endsWith("validate-catalog.mjs");
+if (isCli) {
+  const fileFlag = process.argv.indexOf("--file");
+  const file = fileFlag === -1 ? undefined : process.argv[fileFlag + 1];
+  if (!file) {
+    console.error("Usage: node validate-catalog.mjs --file catalog.json");
+    process.exit(2);
+  }
+  const document = JSON.parse(await readFile(file, "utf8"));
+  const errors = validateCatalog(document);
+  if (errors.length > 0) {
+    for (const error of errors) {
+      console.error(`ERROR ${error}`);
+    }
+    process.exit(1);
+  }
+  console.log("Catalog is valid.");
+}

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

@@ -0,0 +1,84 @@
+---
+name: product-description-guardrails
+description: "Generate product titles and descriptions only from catalog facts, and block prices, certifications, and medical claims that are not in the record. Use when writing or reviewing generated product copy, Merchant Center text, or locale-specific descriptions."
+license: MIT
+compatibility: "The description checker requires Node.js 20 or newer. No network access."
+metadata:
+  author: Naser Sadrmanesh
+  version: "0.3.0"
+---
+
+# Product description guardrails
+
+Use this skill when copy is generated from a catalog record. The feed skill decides which Merchant Center attribute receives that copy. Search text normalization is the search skill. This skill does not claim the copy is true. It keeps the copy inside the facts you passed in.
+
+## Procedure
+
+1. Pass a source record: name, price, currency, locale, and the facts that may be stated (materials, dimensions, color, care, certifications).
+2. Write the description from those facts only. If a fact is absent, omit it. Do not fill the gap with a typical value for that category.
+3. Either omit the price or state the source price and currency. Do not round it into a different amount.
+4. Refuse medical, safety, and guarantee claims that are not in the source. The checker encodes a short refuse-list, not a legal opinion.
+5. Match the locale. A `fa_IR` description is Persian. Do not mix a generated English paragraph into that field.
+6. Run `node scripts/check-description.mjs --description copy.txt --source source.json`.
+
+The refuse-list and the Merchant Center labeling rule are in [the claim notes](references/claims.md). Worked examples and checks are in [evals/tasks.json](evals/tasks.json).
+
+## Source record
+
+```json
+{
+  "name": "Cotton shirt",
+  "price": "19.00",
+  "currency": "USD",
+  "locale": "en",
+  "facts": ["short sleeve", "cotton", "blue"],
+  "allowedClaims": []
+}
+```
+
+`allowedClaims` is empty unless the merchant has supplied the exact claim that may be repeated, such as a certification number that is already in `facts`.
+
+## What may be written
+
+- The product name and the facts, in the locale's language.
+- Care or sizing text that appears in `facts`.
+- The price only as `{price} {currency}`.
+
+## What may not be written
+
+- A material, dimension, country of origin, or certification that is not in `facts`.
+- "Cures", "clinically proven", "guaranteed to", "100% effective", or "risk-free", unless that phrase is listed in `allowedClaims`.
+- Another product's name, a competitor, or "free shipping".
+- A sale price the source does not contain.
+- Stars or review counts that are not in the source.
+
+## Merchant Center
+
+Google's product data specification says generated titles and descriptions use `structured_title` and `structured_description` with `digital_source_type` set to `trained_algorithmic_media`. Text that was not generated uses `title` and `description`. The feed skill checks lengths: 150 characters for a title and 5000 for a description.
+
+## Checker limits
+
+`scripts/check-description.mjs` checks:
+
+- non-empty text at most 5000 characters
+- any `{amount} {CURRENCY}` in the text matches `price` and `currency`
+- the refuse-list phrases above, unless present in `allowedClaims`
+
+It does not detect a made-up material that lacks those phrases. Review the facts list. A passing check is not a statement that the description is accurate.
+
+## Gotchas
+
+- Translating a fact is allowed. Adding a fact during translation is not. "Cotton" may become the Persian word for cotton. It may not gain "organic".
+- A marketing model will add "perfect for" and a use the catalog never stated. Keep the sentence tied to a fact or delete it.
+- Putting the price in Persian digits in the description is a display choice. The checker looks for ASCII `{amount} {CURRENCY}`. Do not also embed a different ASCII amount.
+
+## Verification
+
+- The checker fails a description that says `15.00 USD` when the source price is `19.00`.
+- The checker fails "clinically proven" when `allowedClaims` is empty.
+- A `fa_IR` request does not return an English-only description.
+- Generated Merchant Center text is labeled `trained_algorithmic_media`.
+
+## Evaluation
+
+Worked examples and the checks they must satisfy are in [evals/tasks.json](evals/tasks.json).

package/skills/product-description-guardrails/evals/examples/facts-only.md

@@ -0,0 +1,3 @@
+Describe the shirt from the source record.
+
+The Cotton shirt is short sleeve, cotton, and blue. The price is 19.00 USD. No certification is mentioned because the source has none.

package/skills/product-description-guardrails/evals/examples/label-generated.md

@@ -0,0 +1,3 @@
+Send the generated paragraph as `structured_description`.
+
+Set `digital_source_type` to `trained_algorithmic_media`. Keep the words inside the supplied facts.