Commit c198cd03351 for woocommerce

commit c198cd03351ac1afbccec78d45b10a66342c7f58
Author: Wesley Rosa <wesleyjrosa@gmail.com>
Date:   Mon Aug 24 14:12:38 2026 -0300

    Add enum-style constants guidance to AGENTS.md (#67981)

diff --git a/.ai/skills/woocommerce-backend-dev/coding-conventions.md b/.ai/skills/woocommerce-backend-dev/coding-conventions.md
index a769e19932d..a82a8422c8d 100644
--- a/.ai/skills/woocommerce-backend-dev/coding-conventions.md
+++ b/.ai/skills/woocommerce-backend-dev/coding-conventions.md
@@ -4,6 +4,7 @@

 - [Code Clarity and Comments](#code-clarity-and-comments)
 - [WordPress Coding Standards](#wordpress-coding-standards)
+- [Enum Constants Instead of Magic Strings](#enum-constants-instead-of-magic-strings)
 - [Null Coalescing Operator](#null-coalescing-operator)
 - [Ternary Operator](#ternary-operator)
 - [call_user_func_array() Usage](#call_user_func_array-usage)
@@ -53,6 +54,33 @@ Follow [WordPress Coding Standards](https://developer.wordpress.org/coding-stand
 - **Braces**: Opening on same line, closing on new line
 - **Naming**: snake_case for functions and variables

+## Enum Constants Instead of Magic Strings
+
+Enumerated string vocabularies (order statuses, product types, stock statuses, settings option values...) have constants in `final` classes under `Automattic\WooCommerce\Enums` (`plugins/woocommerce/src/Enums/`, see its `README.md`). Reference the constant, not the raw string literal.
+
+**Good:**
+
+```php
+use Automattic\WooCommerce\Enums\OrderStatus;
+
+if ( OrderStatus::COMPLETED === $order->get_status() ) {
+```
+
+**Avoid:**
+
+```php
+if ( 'completed' === $order->get_status() ) {
+```
+
+Rules:
+
+- When a constant exists for a value, use it. Mind near-duplicate vocabularies: `OrderStatus` holds unprefixed values (`completed`), `OrderInternalStatus` the `wc-`-prefixed database variants (`wc-completed`).
+- New fixed sets of string values get a new class in `src/Enums/` (one `final` class per concept, `public const` with docblocks, no behavior), listed in `src/Enums/README.md`.
+- Never change, rename, or remove a constant or its value — the strings are a persisted, externally consumed contract and the constants are public API.
+- Exception: code that can run during install or upgrade (some REST controllers, report queries) may execute before the autoloader resolves `src/` classes; it keeps string literals to avoid fatals.
+
+See the "Enum-Style Constants" section in the repository root `AGENTS.md` for full context.
+
 ## Null Coalescing Operator

 Use `??` instead of `isset` checks for array access.
diff --git a/.ai/skills/woocommerce-code-review/SKILL.md b/.ai/skills/woocommerce-code-review/SKILL.md
index 65e29851a84..68fbdbec3d4 100644
--- a/.ai/skills/woocommerce-code-review/SKILL.md
+++ b/.ai/skills/woocommerce-code-review/SKILL.md
@@ -23,6 +23,7 @@ Consult the `woocommerce-backend-dev` skill for detailed standards. Using these

 - ❌ **camelCase naming** - Must use snake_case for methods/variables/hooks ([code-entities.md](../woocommerce-backend-dev/code-entities.md))
 - ❌ **Yoda condition violations** - Must follow WordPress Coding Standards ([coding-conventions.md](../woocommerce-backend-dev/coding-conventions.md))
+- ❌ **Magic strings with an existing enum constant** - New code comparing or assigning enumerated values (order statuses, product types, ...) must use the `Automattic\WooCommerce\Enums` constants, not raw literals — except in code that can run during install/upgrade ([coding-conventions.md](../woocommerce-backend-dev/coding-conventions.md))

 **Documentation:**

diff --git a/AGENTS.md b/AGENTS.md
index d5ad57b4352..a76cc94c221 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -204,6 +204,16 @@ Database migrations live in `WC_Install::$db_updates`; read that class for the c
 - Migration keys are one-shot: sites that updated past a key never re-run it. A migration added after a prerelease of the same version has shipped needs a new suffixed key (see existing examples in `$db_updates`), and a key must never be ahead of the version it ships in.
 - Feature flag defaults are persisted, so changing `enabled_by_default` alone doesn't change behavior on existing sites; ship a migration or remove the flag.

+## Enum-Style Constants (`src/Enums/`)
+
+WooCommerce names its enumerated string vocabularies — order statuses, product types, stock statuses, settings option values, and more — as `final` classes of `public const` strings under `Automattic\WooCommerce\Enums` (`plugins/woocommerce/src/Enums/`, see its `README.md` for the full list). Native PHP enums are not an option: the minimum supported PHP version is 7.4, and the raw string values are the contract persisted in databases and consumed by extensions.
+
+- **Use the existing constants.** When writing code that compares or assigns one of these values, reference the constant (e.g. `OrderStatus::COMPLETED`, `ProductType::SIMPLE`), not the raw string literal. During review, flag new raw literals for which a constant already exists.
+- **New vocabularies get a class by default.** When introducing a new fixed set of string values (including new settings option values), add a class in `src/Enums/`: one `final` class per concept, explicit `public` visibility on every constant, a docblock on every value, no behavior. List it in `src/Enums/README.md`. For large adoptions, introduce the class and adopt it in separate PRs to keep diffs reviewable.
+- **Constants name values; they never change them.** The string is the contract and the constant is a permanent alias for it. Never change a constant's value, and never rename or remove one — deprecate instead (see Backward Compatibility). These constants are public API that extensions may rely on.
+- **Respect the plugin lifecycle.** Some code paths (REST controllers, report queries) can run during install or upgrade, before the autoloader resolves classes under `src/`; referencing an enum class there is a fatal (`Class ... not found`). Code that can execute mid-install or mid-upgrade keeps its string literals.
+- **Near-duplicate vocabularies are distinct classes on purpose.** `OrderStatus` holds the unprefixed values (`completed`) most WooCommerce APIs expect; `OrderInternalStatus` holds the `wc-`-prefixed variants (`wc-completed`) WordPress stores. Reach for the class that matches what the consuming API expects.
+
 ## Block Development

 ### `block.json` Attribute Defaults