interface:
  display_name: "Woo Guard"
  short_description: "WooCommerce code guardrails for AI agents"
  default_prompt: "Use $woo-guard after WooCommerce code is written or changed to review it for HPOS, CRUD, checkout, and money-handling issues."

# Woo Guard — Checkout and Money Reference

## Contents

- Two checkouts, two hook surfaces
- Server-side validation
- Cart and session context guards
- Money handling
- Gateway and webhook callbacks

## Two checkouts, two hook surfaces

Modern stores run the Blocks checkout (Store API); legacy stores run the shortcode checkout (`woocommerce_checkout_*` hooks, `wp_ajax` fragments). The hook surfaces do not overlap:

- Legacy-only: `woocommerce_checkout_fields`, `woocommerce_checkout_process`, `woocommerce_after_order_notes`.
- Blocks: Store API extensions (`ExtendSchema`), additional-fields API, server-side endpoint validation.

An extension claiming general compatibility wires both or declares which one it supports (see compatibility declaration in [hpos-and-crud.md](hpos-and-crud.md)). AI-generated checkout code overwhelmingly targets the legacy surface only — on a Blocks store it simply never runs: a hook on the wrong surface fails silently, no error, no behavior.

## Server-side validation

```php
/**
 * Reject checkout when the VAT number is malformed.
 *
 * JS validation on the field is UX; this hook is the actual gate.
 */
add_action( 'woocommerce_checkout_process', function () {
	$vat = isset( $_POST['ncs_vat'] ) ? sanitize_text_field( wp_unslash( $_POST['ncs_vat'] ) ) : '';

	if ( '' !== $vat && ! ncs_vat_is_valid( $vat ) ) {
		wc_add_notice( __( 'Please enter a valid VAT number.', 'ncs-checkout' ), 'error' );
	}
} );
```

For Blocks, the equivalent lives in the Store API additional-fields/extension schema callbacks. Either way: the server decides, every field is unslashed then sanitized with the type-correct function, and error messages go through `wc_add_notice()`/schema errors — never `die()`.

## Cart and session context guards

`WC()->cart`, `WC()->session`, and `WC()->customer` are initialized for front-end requests — they are null in REST, cron, CLI, webhooks, and most admin requests:

```php
if ( function_exists( 'WC' ) && WC()->cart instanceof WC_Cart ) {
	$count = WC()->cart->get_cart_contents_count();
}
```

Code that touches the cart inside an API callback or scheduled job is a fatal error wearing a demo-store disguise. Flag it in review even when "it worked locally."

## Money handling

- Storage and arithmetic inputs: `wc_format_decimal( $value )` — normalizes locale decimals and precision.
- Display: `wc_price( $amount )` — currency symbol, position, separators, all from store settings. Hardcoded `'$' . $amount` fails on the other 150 currencies.
- Totals and tax: use order/cart getters (`get_total()`, `get_subtotal()`, `WC_Tax` methods) — they apply the store's rounding mode. Re-deriving totals with raw float math produces penny drift that accountants will find.
- Comparisons: compare formatted decimals or integer minor units; never `==` on floats.
- Refund/discount logic: negative amounts have meaning — test the zero and partial cases explicitly (test-guard says hi).

## Gateway and webhook callbacks

- Verify webhook signatures/secrets before touching any order; fail closed with the provider's expected status code.
- Look up orders from gateway references via `wc_get_orders( array( 'transaction_id' => … ) )` or stored CRUD meta — not custom SQL.
- Callbacks run unauthenticated by design: capability checks don't apply, signature verification is the authentication, and every input is still unslashed and sanitized before use.
- Idempotency: providers retry. Processing the same payment event twice must not complete an order twice.

# Woo Guard — HPOS and CRUD Reference

## Contents

- Why HPOS breaks legacy code
- Order access patterns
- Order meta done right
- Products, stock, and lookup tables
- Status transitions
- Declaring compatibility
- Violation table for review

## Why HPOS breaks legacy code

High-Performance Order Storage moved orders out of `wp_posts`/`wp_postmeta` into dedicated tables, and it is the default on new stores. Code that treats orders as posts returns empty results or stale data on HPOS stores — silently, with no error. Code written "from memory" almost always targets the legacy storage, because that is what most training-era tutorials show.

## Order access patterns

```php
// Wrong — assumes orders are posts. Fails on HPOS.
$total  = get_post_meta( $order_id, '_order_total', true );
$orders = get_posts( array( 'post_type' => 'shop_order', 'numberposts' => 20 ) );

// Right — storage-agnostic CRUD API.
$order  = wc_get_order( $order_id );
$total  = $order ? $order->get_total() : 0;
$orders = wc_get_orders( array( 'status' => 'wc-processing', 'limit' => 20 ) );
```

`wc_get_orders()` takes its own argument schema (not `WP_Query` args): `limit`, `status`, `customer_id`, `date_created`, `meta_query` equivalents via `field_query`. Never run an unbounded order query — always set a `limit` (wp-guard covers query discipline in depth when installed).

## Order meta done right

```php
$order = wc_get_order( $order_id );
$order->update_meta_data( '_ncs_sync_status', 'queued' );
$order->save(); // persists to whichever storage backend is active

$value = $order->get_meta( '_ncs_sync_status' ); // single value, unserialized
```

`save()` is not optional — without it, meta changes exist only in memory. Batched changes: set everything, save once.

## Products, stock, and lookup tables

Product meta writes through `update_post_meta()` skip `wc_product_meta_lookup` sync, skip `woocommerce_update_product`-family hooks, and skip cache invalidation — three classes of bugs other plugins will blame on you.

```php
$product = wc_get_product( $product_id );
$product->set_stock_quantity( $new_qty );
$product->set_regular_price( wc_format_decimal( $price ) );
$product->save();
```

Stock specifically: `wc_update_product_stock()` and the CRUD setters handle backorders, stock status flips, and concurrency better than any hand-rolled meta math. Direct increments via meta are race-prone on busy stores.

## Status transitions

```php
$order->update_status( 'completed', 'Synced to fulfillment.' ); // fires emails + hooks
```

Never set status by writing meta or post fields — `update_status()` triggers the `woocommerce_order_status_*` hooks and customer emails the rest of the store depends on. If suppressing side effects is the goal, that is a design discussion to surface, not a meta write to sneak in.

## Declaring compatibility

```php
add_action( 'before_woocommerce_init', function () {
	if ( class_exists( \Automattic\WooCommerce\Utilities\FeaturesUtil::class ) ) {
		\Automattic\WooCommerce\Utilities\FeaturesUtil::declare_compatibility( 'custom_order_tables', __FILE__, true );
		\Automattic\WooCommerce\Utilities\FeaturesUtil::declare_compatibility( 'cart_checkout_blocks', __FILE__, true );
	}
} );
```

Declare only what is true — a false `custom_order_tables` declaration on postmeta-reading code converts a visible warning into an invisible data bug.

## Violation table for review

| Grep hit | Why it fails |
|---|---|
| `get_post_meta( $order_id` | HPOS: order meta is not postmeta |
| `post_type => 'shop_order'` (or `shop_order_refund`) | HPOS: orders are not posts |
| `update_post_meta( $product_id` | Skips lookup tables, hooks, caches |
| `wp_update_post` on order/product IDs | Same class of bypass |
| `$wpdb` joins on `postmeta` for order data | HPOS + fragile schema coupling |
| `posts_per_page => -1` over products/orders | Unbounded query, store-sized blast radius |

# Woo Guard — Review Checklist

Structured walk for review mode. First sweep the security floor on the same files — output escaping, unslash-then-sanitize on request data, capability plus nonce on state changes, prepared queries — money code gets zero security slack (wp-guard covers the full WordPress layer when installed). Cite file:line.

## Contents

- Pass 1: HPOS and CRUD greps
- Pass 2: Checkout and money
- Pass 3: Runtime context
- Pass 4: Compatibility and packaging
- Reporting

## Pass 1: HPOS and CRUD greps (must fix)

Run the violation table in [hpos-and-crud.md](hpos-and-crud.md):

- `get_post_meta` / `update_post_meta` / `wp_update_post` touching order or product IDs
- `post_type => 'shop_order'` in any query; `$wpdb` joins on postmeta for order data
- Meta changes without a following `save()`
- Stock or order status set by meta/post-field writes instead of `wc_update_product_stock()` / `$order->update_status()`
- Unbounded `wc_get_orders()` / product queries (no `limit`)

## Pass 2: Checkout and money (must fix)

- Checkout rules enforced server-side (`woocommerce_checkout_process` or Store API schema)? JS-only validation is a finding.
- Which checkout does the code target — and does that match what it claims to support?
- Money: `wc_format_decimal()` on inputs, `wc_price()` on display, store rounding on totals; flag float arithmetic, `number_format()`, hardcoded symbols, float `==`.
- Webhook/gateway callbacks: signature verified before order access? Idempotent on retries?

## Pass 3: Runtime context (should fix)

- `WC()->cart` / `WC()->session` / `WC()->customer` reachable from REST, cron, CLI, or webhooks without guards?
- `woocommerce_*` hooks and `wc_*` functions verified to exist in the supported version range?
- WooCommerce-active checks before hooking (`class_exists` / feature checks)?

## Pass 4: Compatibility and packaging (should fix)

- `FeaturesUtil` declarations present and truthful (`custom_order_tables`, `cart_checkout_blocks`)?
- Template overrides shipped inside the plugin? (Always a finding — hooks or `woocommerce_locate_template`.)
- Background/batch work on Action Scheduler, idempotent handlers?

## Reporting

Use the SKILL.md format (What / Risk / Fix). Lead with Pass 1–2 findings and an overall verdict (merge / fix first / do not merge). Note explicitly when security-floor findings exist on the same files so the user sees the full bill at once.

# Woo Guard — Sources

Central bibliography. Operational guidance lives in the other references; read this file only when a source URL is needed.

## Contents

- WooCommerce developer documentation

## WooCommerce developer documentation

- HPOS (High-Performance Order Storage): https://developer.woocommerce.com/docs/features/high-performance-order-storage/
- HPOS recipe book (compatibility patterns): https://developer.woocommerce.com/docs/features/high-performance-order-storage/recipe-book/
- CRUD objects: https://developer.woocommerce.com/docs/category/data-management/crud-objects/
- Store API: https://developer.woocommerce.com/docs/apis/store-api/
- Cart and Checkout Blocks — extensibility: https://developer.woocommerce.com/docs/category/cart-and-checkout-blocks/
- Action Scheduler: https://actionscheduler.org/
- Payment gateway API: https://developer.woocommerce.com/docs/woocommerce-payment-gateway-api/