opencode-skills-collection 4.0.0 → 4.0.2

package/bundled-skills/woo-guard/references/checkout-and-money.md

@@ -0,0 +1,64 @@
+# 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.

package/bundled-skills/woo-guard/references/hpos-and-crud.md

@@ -0,0 +1,87 @@
+# 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 |

package/bundled-skills/woo-guard/references/review-checklist.md

@@ -0,0 +1,44 @@
+# 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.

package/bundled-skills/woo-guard/references/sources.md

@@ -0,0 +1,17 @@
+# 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/

package/bundled-skills/wp-guard/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: "wp-guard"
+description: "Review generated or changed WordPress plugins, themes, and blocks for security, internationalization, performance, and API correctness."
+risk: "offensive"
+source: "community"
+source_repo: "amElnagdy/guard-skills"
+source_type: "community"
+date_added: 2026-07-13
+author: "community"
+tags: []
+tools: []
+---
+
+
+# WP Guard
+
+> [!WARNING]
+> **Authorized Use Only.** Review only WordPress code and environments the user owns or is explicitly authorized to assess. Keep checks non-destructive and inside the approved scope.
+
+You are reviewing generated or changed WordPress code before it ships. Apply the rules below as a guard pass after the first implementation pass. Be a sharp reviewer, not a pedantic one: flag what creates vulnerabilities, breaks translations, or melts servers — ignore cosmetic preferences WPCS tooling already handles.
+
+These rules exist because AI agents produce WordPress code with systematic failures: raw `echo` of request data, AJAX handlers with neither nonce nor capability check, SQL built by string interpolation, English hardcoded into user-facing strings, `posts_per_page => -1` on sites with a million posts, and hand-rolled replacements for APIs core already ships. Each one looks fine in a demo and fails in production.
+
+## When to Use
+
+Use this skill when reviewing generated or changed WordPress code — plugins, themes, and blocks — before it ships. Activate it reactively after an agent writes, edits, or reviews code touching WordPress APIs: hooks, custom post types, REST endpoints, database queries, and block editor integrations.
+
+## How to use this skill
+
+**Guard-pass mode** (recommended): after WordPress code has been generated or edited, apply the rules to the diff or target files, then run the self-check before delivery. Fix violations before showing the user.
+
+**Live mode** (explicit): when the user invokes this skill before writing WordPress code, apply the same rules while writing, then run the self-check before delivery.
+
+**Review mode** (the user asks you to review, audit, or rate WordPress code): walk [references/review-checklist.md](references/review-checklist.md) against the target files and produce a structured findings report. Do not edit code in review mode unless asked.
+
+Pair this skill with clean-code-guard when both are installed: clean-code-guard owns generic code quality; wp-guard owns the WordPress layer.
+
+## Adapt to the project first
+
+1. Read the project's agent instructions (CLAUDE.md, AGENTS.md), `phpcs.xml`/WPCS config, and `composer.json`. Project conventions win on conflict.
+2. Identify the established prefix (functions, options, meta keys, handles) and the minimum supported WP/PHP versions. Match both.
+3. Detect context: WooCommerce APIs in play → apply woo-guard alongside this skill when it is installed; otherwise apply WooCommerce's HPOS, CRUD, and checkout rules from its developer documentation. Multilingual site (WPML/Polylang/multisite) → i18n rules are blocking, not advisory.
+4. Read one neighboring file before writing. Mirror its error handling, hook registration style, and escaping habits — unless they violate the security rules below, which are non-negotiable.
+
+## The Rules
+
+### Security — must fix, no exceptions
+
+1. **Escape late, escape everything.** Every variable crossing into HTML output goes through the context-correct function: `esc_html()`, `esc_attr()`, `esc_url()`, or `wp_kses()`/`wp_kses_post()` for rich content. Data passed to inline JS goes through `wp_json_encode()` + `wp_add_inline_script()` — `esc_js()` is legacy, for single-quoted strings in inline attributes only. Escaping happens at output, not at storage. `echo $anything;` without an `esc_*` wrapper fails review.
+
+2. **Sanitize early, and unslash first.** Request data (`$_POST`, `$_GET`, `$_REQUEST`, `$_SERVER`) never touches logic raw: `wp_unslash()` first, then the type-correct sanitizer (`sanitize_text_field()`, `sanitize_key()`, `absint()`, `sanitize_email()`, …). Sanitization is not escaping; doing one never excuses the other.
+
+3. **Every state change proves identity and intent.** Form handlers, AJAX endpoints, and REST routes that change anything require BOTH a capability check (`current_user_can()`) AND a nonce (`check_admin_referer()`, `check_ajax_referer()`, or REST nonce handling). A nonce is not authorization. A REST `permission_callback` of `__return_true` on a writing route fails review.
+
+4. **`$wpdb->prepare()` for every query containing a variable.** Placeholders (`%s`, `%d`, `%f`, and `%i` for identifiers on WP ≥ 6.2), never interpolation or concatenation. Prefer `WP_Query`, the meta and options APIs over raw SQL when they can express the query.
+
+### Core API discipline
+
+5. **Use the platform; don't reinvent it.** Outbound HTTP via `wp_remote_get()`/`wp_remote_post()`, never curl. Assets via `wp_enqueue_script()`/`wp_enqueue_style()`, never echoed `<script>`/`<style>` tags. Scheduling via WP-Cron or Action Scheduler. Redirects via `wp_safe_redirect()` followed by `exit`. File writes via `WP_Filesystem`. Simple persistent data via options/transients, not a custom table.
+
+6. **Verify every hook and function exists.** Before `add_action()`, `add_filter()`, or calling a core/plugin function, confirm it exists in the supported versions — read the source or the project's installed code. Hallucinated hooks fail silently in WordPress: no error, no behavior. Also match the hook to the moment — front-end code does not load on `admin_init`, queries do not run before `init` expects them.
+
+7. **Prefix or namespace everything public.** Functions, classes, options, transients, meta keys, script handles, AJAX actions, REST namespaces — all carry the project prefix. Generic names (`get_settings`, `data`, `api_key`) are collisions waiting for the next active plugin.
+
+8. **Guard direct access.** Every PHP file that does work starts with the `ABSPATH` check (or equivalent project convention).
+
+### Internationalization
+
+9. **Every user-facing string is translation-ready.** The correct wrapper for the context (`__()`, `_e()`, `_x()`, `_n()`, or the escaping combos `esc_html__()`, `esc_attr__()`), a literal text domain matching the plugin slug — never a variable or constant — translator comments on every placeholder, `_n()` for plurals (never `sprintf` with a hardcoded singular/plural choice), and no sentence assembly by concatenation. Dates and numbers through `date_i18n()`/`wp_date()` and `number_format_i18n()`. Details and JS i18n: [references/i18n.md](references/i18n.md).
+
+### Performance
+
+10. **Query discipline.** No `posts_per_page => -1` and no `query_posts()`, ever. Use `'fields' => 'ids'` when only IDs are needed, `'no_found_rows' => true` when not paginating, and never query inside a loop what could be primed once (meta/term caches). Details: [references/performance.md](references/performance.md).
+
+11. **Cache expensive work, load assets where used.** Remote calls and heavy computations go behind transients or the object cache with a deliberate TTL. Options that are large or rarely read register with `autoload => false`. Scripts and styles enqueue only on the screens that use them.
+
+## Self-check before delivery
+
+1. Grep your diff for `echo`, `print`, `<?=`: is every variable output escaped with the context-correct function?
+2. Grep for `$_POST`, `$_GET`, `$_REQUEST`: unslashed? sanitized? nonce-verified? capability-checked?
+3. Grep for `$wpdb->`: every variable behind a placeholder?
+4. Any user-facing string outside an i18n wrapper? Any non-literal text domain?
+5. Any hook or function you did not verify exists?
+6. Any unbounded query, uncached remote call, or unconditional enqueue?
+7. Does every new public name carry the project prefix?
+8. Would this survive WPCS (`WordPress-Extra` + `WordPress-Security`) without warnings you cannot justify?
+
+If any answer is wrong, fix it before showing the user.
+
+## Reporting format (review mode)
+
+```
+**Rule N violation** in `path/file.php:<line or function>`
+- What: <one sentence>
+- Risk: <XSS / SQLi / CSRF / broken i18n / scaling — one phrase>
+- Fix: <one sentence>
+```
+
+Group by file, lead with security findings. If a file is clean, don't mention it.
+
+## Severity guide
+
+- **Must fix:** Rules 1–4 — these are exploitable (XSS, SQLi, CSRF, privilege escalation)
+- **Should fix:** Rules 5–9 — conflicts, silent failures, untranslatable releases
+- **Worth noting:** Rules 10–11 — they decide whether the code survives traffic; block on them for code that runs on every request
+
+## References
+
+- [references/security.md](references/security.md) — escaping/sanitization function tables, nonce lifecycle, REST permissions, `$wpdb->prepare` details, file uploads
+- [references/i18n.md](references/i18n.md) — wrapper selection, text domain rules, plurals, translator comments, JS translations, RTL, multilingual-plugin gotchas
+- [references/performance.md](references/performance.md) — WP_Query flags, transients vs object cache, autoload hygiene, asset loading, cron, scaling traps
+- [references/review-checklist.md](references/review-checklist.md) — structured walk-through for review mode
+- [references/sources.md](references/sources.md) — handbook and research URLs; read only when citing a source
+
+## What this skill does not do
+
+- Run PHPCS, PHPStan, or Plugin Check — use the project's tooling for mechanical verification; this skill is the judgment layer above it.
+- Decide plugin architecture or business logic — it guards how WordPress code ships, not what it does.
+- Replace clean-code-guard or test-guard — generic code quality and test quality remain their jurisdiction.

package/bundled-skills/wp-guard/references/i18n.md

@@ -0,0 +1,88 @@
+# WP Guard — Internationalization Reference
+
+## Contents
+
+- Wrapper selection
+- Text domain rules
+- Placeholders and translator comments
+- Plurals
+- Sentence assembly
+- JavaScript i18n
+- Dates, numbers, RTL
+- Multilingual-plugin gotchas
+
+## Wrapper selection
+
+| Situation | Use |
+|---|---|
+| Return a translated string | `__( 'Text', 'my-plugin' )` |
+| Echo a translated string | `_e( 'Text', 'my-plugin' )` — or better, `esc_html_e()` |
+| Translate + escape for HTML | `esc_html__()` / `esc_html_e()` |
+| Translate + escape for attribute | `esc_attr__()` / `esc_attr_e()` |
+| Ambiguous word needing context | `_x( 'Post', 'verb', 'my-plugin' )` |
+| Plural | `_n( '%s item', '%s items', $count, 'my-plugin' )` |
+| Plural + context | `_nx()` |
+
+When a string is both translated and output, the combined wrappers (`esc_html__`) are required — translations are untrusted input like any other (a compromised translation file is an XSS vector).
+
+## Text domain rules
+
+- Literal string, always: `__( 'Text', 'my-plugin' )`. Never `__( 'Text', PLUGIN_DOMAIN )`, never a variable — static analysis tools and translate.wordpress.org both fail on non-literal domains.
+- Must match the plugin slug exactly (the WordPress.org directory enforces this).
+- One domain per plugin/theme. AI agents copying snippets from other projects routinely import foreign text domains — grep for domains that don't match the project's.
+
+## Placeholders and translator comments
+
+```php
+/* translators: 1: customer name, 2: order number. */
+$message = sprintf(
+	__( 'Hi %1$s, your order #%2$d is on its way.', 'my-plugin' ),
+	$customer_name,
+	$order_id
+);
+```
+
+- Numbered placeholders (`%1$s`) whenever there is more than one — translators reorder words.
+- A `/* translators: … */` comment on every string with placeholders, immediately above the line.
+- Never put variables or HTML soup inside the translatable string when it can sit outside.
+
+## Plurals
+
+`_n()` exists because languages have between one and six plural forms. Never:
+
+```php
+// Wrong — English-only logic.
+$label = $count === 1 ? __( 'item', 'my-plugin' ) : __( 'items', 'my-plugin' );
+```
+
+Always `_n( '%s item', '%s items', $count, 'my-plugin' )`, then `sprintf()` with `number_format_i18n( $count )`.
+
+## Sentence assembly
+
+Never build sentences by concatenation — word order differs across languages:
+
+```php
+// Wrong: translators get fragments they cannot reorder.
+echo __( 'Imported', 'my-plugin' ) . ' ' . $count . ' ' . __( 'products', 'my-plugin' );
+
+// Right: one string, one placeholder, full context.
+/* translators: %s: number of imported products. */
+printf( esc_html__( 'Imported %s products.', 'my-plugin' ), number_format_i18n( $count ) );
+```
+
+## JavaScript i18n
+
+- `wp_set_script_translations( 'my-handle', 'my-plugin' )` after enqueueing; use `__()` from `@wordpress/i18n` in the JS.
+- Legacy pattern (`wp_localize_script` with pre-translated strings) is acceptable in legacy codebases — match the project.
+
+## Dates, numbers, RTL
+
+- Dates: `wp_date()` / `date_i18n()` with the site's format options — never raw `date()` for display.
+- Numbers: `number_format_i18n()`.
+- CSS: logical properties (`margin-inline-start`, not `margin-left`) for new styles; don't hand-write directional CSS — build `-rtl.css` files with RTLCSS. Auto-loading them applies only to core styles and block.json-registered styles; classic plugin/theme handles must opt in with `wp_style_add_data( $handle, 'rtl', 'replace' )`.
+
+## Multilingual-plugin gotchas (WPML / Polylang)
+
+- Strings stored in options/meta are NOT translated by `__()` — they need string registration (WPML String Translation / `pll_register_string`). Flag stored user-facing strings during review.
+- IDs are language-specific: a hardcoded `page_id` points at one language's page. Resolve through the multilingual plugin's API or filters when the project uses one.
+- Queries on multilingual sites are language-filtered by default — explicitly note when a query intentionally crosses languages.

package/bundled-skills/wp-guard/references/performance.md

@@ -0,0 +1,70 @@
+# WP Guard — Performance Reference
+
+## Contents
+
+- WP_Query discipline
+- Meta and term cache priming
+- Transients vs object cache
+- Options autoload hygiene
+- Asset loading
+- Cron and background work
+- Scaling traps checklist
+
+## WP_Query discipline
+
+- `posts_per_page => -1` is forbidden. There is always a bound; if the caller "needs everything," page through with a loop or use a bounded cap the project agrees on.
+- `query_posts()` is forbidden — it clobbers the main query. Use `WP_Query` or `pre_get_posts`.
+- Only IDs needed → `'fields' => 'ids'` (skips row hydration and caches).
+- Not paginating → `'no_found_rows' => true` (skips `SQL_CALC_FOUND_ROWS`).
+- Not using meta/terms in the loop → `'update_post_meta_cache' => false`, `'update_post_term_cache' => false`.
+- Avoid `'meta_query'` on unindexed scans for high-traffic paths — meta queries do not scale on large `postmeta` tables; consider a lookup table or taxonomy when the access pattern is hot.
+- Never run queries inside `foreach` when one query (or cache priming) can fetch the set.
+
+## Meta and term cache priming
+
+The N+1 killer. When iterating IDs and reading meta per item:
+
+```php
+$ids = get_posts( array( 'fields' => 'ids', /* … */ ) );
+update_meta_cache( 'post', $ids ); // one query primes the cache
+foreach ( $ids as $id ) {
+	$sku = get_post_meta( $id, '_sku', true ); // served from cache
+}
+```
+
+`update_meta_cache()` and `update_object_term_cache()` exist for exactly this; on WP ≥ 6.1, `_prime_post_caches()` batches posts, meta, and terms in one call (public API since 6.1 despite the underscore). AI-generated loops skip them every time.
+
+## Transients vs object cache
+
+- `set_transient()` / `get_transient()` — persistent cache with TTL; backed by the object cache when a drop-in exists, by the options table otherwise.
+- `wp_cache_get()` / `wp_cache_set()` — request-scope by default, persistent only with an object-cache drop-in (Redis/Memcached). Use cache groups and deliberate TTLs.
+- Expensive remote calls (Rule 11) always go behind one of these. Choose TTL consciously; never cache user-specific data in a shared key — include the user/locale in the key when output varies by them.
+- On failure paths, decide explicitly whether to cache the failure (short TTL) or retry every request — and say which in a comment.
+
+## Options autoload hygiene
+
+Every `autoload => true` option loads on EVERY request into `alloptions`. Rules:
+
+- `add_option( 'ncs_big_report_cache', $data, '', false )` — large or rarely-read data never autoloads (pass `false` as the third arg of `update_option` too; the parameter exists since WP 4.2).
+- Keep individual autoloaded options small; an `alloptions` blob over ~1 MB is a known site-killer on high-traffic sites.
+- One serialized settings array per plugin beats twenty separate options.
+
+## Asset loading
+
+- Enqueue only where used: check `is_admin()`, screen IDs (`get_current_screen()`), shortcode presence, or block usage before enqueueing.
+- Front-end assets registered on `wp_enqueue_scripts`, admin on `admin_enqueue_scripts` with the `$hook_suffix` check.
+- Version assets with the plugin version (cache busting); load non-critical JS with `defer`/`async` strategies (`wp_register_script` args on WP ≥ 6.3).
+
+## Cron and background work
+
+- WP-Cron is traffic-driven and can stack: guard handlers against overlap (a lock transient), keep events idempotent.
+- Long or high-volume jobs → Action Scheduler when WooCommerce (or the library) is present.
+- Never `sleep()` in a request; never do batch work on `init` for every visitor.
+
+## Scaling traps checklist
+
+- Unbounded `get_users()` / `get_terms()` on large sites — same rules as posts.
+- `switch_to_blog()` in loops without batching (multisite).
+- Per-request remote HTTP without caching — one slow third party becomes your TTFB.
+- Writing to options on front-end requests (cache invalidation storm under traffic).
+- Counting rows with `found_posts` when an indexed count query or cached counter would do.

package/bundled-skills/wp-guard/references/review-checklist.md

@@ -0,0 +1,57 @@
+# WP Guard — Review Checklist
+
+Structured walk for review mode. Lead with findings, not summary. Cite file:line. Prioritize: security → silent breakage → i18n → performance.
+
+## Contents
+
+- Pass 1: Security sweep
+- Pass 2: API and hook correctness
+- Pass 3: i18n
+- Pass 4: Performance
+- Pass 5: Packaging hygiene
+- Reporting
+
+## Pass 1: Security sweep (must fix)
+
+Grep-driven; check every hit:
+
+- `echo`, `print`, `<?=`, `printf` — every variable escaped with the context-correct `esc_*`/`wp_kses`? (Rule 1)
+- `$_POST`, `$_GET`, `$_REQUEST`, `$_SERVER`, `$_COOKIE` — `wp_unslash()` then sanitized? (Rule 2)
+- `add_action( 'wp_ajax_`, `admin_post_`, `rest_api_init` — every state-changing handler has BOTH `current_user_can()` and a nonce check / real `permission_callback`? (Rule 3)
+- `$wpdb->` — every variable behind `prepare()` placeholders? `esc_like()` for LIKE? (Rule 4)
+- `$_FILES` — handled via `wp_handle_upload()` with type allowlist?
+- Secrets: API keys hardcoded? Logged? In autoloaded options when they belong in constants/env?
+
+## Pass 2: API and hook correctness (should fix)
+
+- Every hooked hook and called function exists in supported WP/plugin versions? (Rule 6 — hallucinated hooks fail silently)
+- Hook timing right? (No front-end work on admin hooks, no early queries, no `init`-heavy work per request)
+- Core API replacements: curl, raw `<script>` echoes, manual cron loops, direct file ops? (Rule 5)
+- Prefixes on every public name: functions, options, transients, meta keys, handles, AJAX actions? (Rule 7)
+- `ABSPATH` guard present in working files? (Rule 8)
+- `wp_safe_redirect()` + `exit` after state changes?
+
+## Pass 3: i18n (should fix; blocking on multilingual projects)
+
+- User-facing strings without wrappers? Wrong/non-literal text domain? (Rule 9)
+- Placeholders without translator comments? Plural logic without `_n()`?
+- Concatenated sentence fragments?
+- Stored user-facing strings (options/meta) that multilingual plugins can't see? (see [i18n.md](i18n.md))
+- Raw `date()`/`number_format()` for display?
+
+## Pass 4: Performance (worth noting; blocking on every-request paths)
+
+- `posts_per_page => -1`, `query_posts()`, unbounded `get_users()`/`get_terms()`? (Rule 10)
+- Queries or `get_post_meta()` inside loops without cache priming?
+- Remote calls without transient/object caching? (Rule 11)
+- Large options autoloading? Unconditional asset enqueues?
+
+## Pass 5: Packaging hygiene
+
+- WooCommerce code in scope → hand off to woo-guard when it is installed; otherwise apply WooCommerce's HPOS, CRUD, checkout, and money rules from its developer documentation.
+- Activation/deactivation/uninstall: scheduled events cleared, transients cleaned, uninstall removes its data?
+- Direct entry files, readme version mismatches, debug code (`error_log`, `var_dump`) left in?
+
+## Reporting
+
+Use the SKILL.md reporting format. Lead with the security findings and an overall verdict (merge / fix first / do not merge). End with at most three positives worth keeping — reviewers who only list faults get ignored.

package/bundled-skills/wp-guard/references/security.md

@@ -0,0 +1,100 @@
+# WP Guard — Security Reference
+
+## Contents
+
+- Escaping: context → function
+- Sanitization: input type → function
+- The unslash-then-sanitize order
+- Nonce + capability lifecycle
+- REST API permissions
+- $wpdb->prepare details
+- File uploads
+- Common AI-generated violations
+
+## Escaping: context → function
+
+Escape at the moment of output, with the function matching the destination context:
+
+| Output context | Function |
+|---|---|
+| HTML body text | `esc_html()` |
+| HTML attribute | `esc_attr()` |
+| URL (href/src/action) | `esc_url()` (display) / `esc_url_raw()` (storage/redirects) |
+| Data for inline JS | `wp_json_encode()` + `wp_add_inline_script()`; `esc_js()` is legacy — single-quoted strings in inline attributes only |
+| Textarea content | `esc_textarea()` |
+| Rich/user HTML | `wp_kses_post()` or `wp_kses()` with an explicit allowlist |
+| Translation + output | `esc_html__()`, `esc_html_e()`, `esc_attr__()` — escape and translate in one call |
+
+Trust nothing at output time — not even your own stored options; another plugin or a compromised import may have written them. "Escaped on save" is not a defense.
+
+## Sanitization: input type → function
+
+| Expected input | Function |
+|---|---|
+| Plain text line | `sanitize_text_field()` |
+| Multiline text | `sanitize_textarea_field()` |
+| Integer / ID | `absint()` or `intval()` |
+| Slug/key | `sanitize_key()` / `sanitize_title()` |
+| Email | `sanitize_email()` + `is_email()` check |
+| URL | `esc_url_raw()` |
+| HTML payload | `wp_kses_post()` / `wp_kses()` |
+| File name | `sanitize_file_name()` |
+| Anything enumerable | strict allowlist comparison (`in_array( $v, $allowed, true )`) |
+
+## The unslash-then-sanitize order
+
+WordPress adds slashes to superglobals. The correct pipeline is always:
+
+```php
+$status = sanitize_key( wp_unslash( $_POST['ncs_status'] ?? '' ) );
+```
+
+`wp_unslash()` first, sanitizer second. Sanitizing slashed data corrupts legitimate input and hides bugs.
+
+## Nonce + capability lifecycle
+
+Both checks, always, for any state change. They answer different questions:
+
+- `current_user_can( 'manage_options' )` — is this user *allowed* to do this? (authorization)
+- `check_admin_referer( 'ncs_save_settings' )` / `check_ajax_referer( 'ncs_action', 'nonce' )` — did this request *intend* this action? (CSRF protection)
+
+A nonce without a capability check lets any logged-in subscriber fire admin actions. A capability check without a nonce leaves CSRF open. AI-generated handlers routinely have one, the other, or neither — verify both exist on every `admin_post_*`, `wp_ajax_*`, and form handler.
+
+Generate nonces with `wp_nonce_field()` (forms) or `wp_create_nonce()` (AJAX/REST payloads). Nonces are per-user and time-limited; do not cache pages containing them.
+
+## REST API permissions
+
+- Every route registers a real `permission_callback`. `__return_true` is acceptable only for genuinely public read-only data — never for writes.
+- Validate and sanitize via the route's `args` schema (`validate_callback`, `sanitize_callback`) instead of manual checks inside the handler.
+- Cookie-authenticated REST requests require the `X-WP-Nonce` header (`wp_rest` nonce); custom auth schemes must fail closed.
+
+## $wpdb->prepare details
+
+```php
+$row = $wpdb->get_row(
+	$wpdb->prepare(
+		"SELECT * FROM {$wpdb->prefix}ncs_log WHERE user_id = %d AND event = %s",
+		$user_id,
+		$event
+	)
+);
+```
+
+- Placeholders: `%s`, `%d`, `%f`; `%i` for table/column identifiers (WP ≥ 6.2).
+- `IN ( … )` lists: build placeholders dynamically — `implode( ',', array_fill( 0, count( $ids ), '%d' ) )` — then prepare with the spread array.
+- LIKE queries: `$wpdb->esc_like()` the term *before* passing it as a `%s` parameter.
+- Never interpolate `$_REQUEST` data anywhere near SQL, even "validated" data.
+- Prefer `WP_Query`, `get_posts()`, meta/term/option APIs when they can express the query — they bring caching for free.
+
+## File uploads
+
+Use `wp_handle_upload()` / media APIs — never move `$_FILES` manually. Validate type with `wp_check_filetype_and_ext()` against an allowlist; never trust the client MIME. Store outside executable paths; WordPress handles this when you use its APIs.
+
+## Common AI-generated violations
+
+1. `echo '<div>' . $title . '</div>';` — unescaped output (Rule 1). Published research: XSS appears in 86% of AI generations tested on XSS-prone tasks (see [sources.md](sources.md)).
+2. `wp_ajax_` handler with neither `check_ajax_referer()` nor `current_user_can()` (Rule 3).
+3. `"SELECT * FROM {$wpdb->posts} WHERE post_title = '$title'"` — interpolated SQL (Rule 4).
+4. `permission_callback => '__return_true'` on a POST route (Rule 3).
+5. `curl_init()` inside a plugin (Rule 5) — breaks proxies, blocks, and filters that `wp_remote_*` honors.
+6. Echoed `<script>` blocks with interpolated PHP — combines Rules 1 and 5; use `wp_enqueue_script()` + `wp_add_inline_script()`/`wp_localize_script()`.