wordpress-agent-kit 0.3.2 → 0.5.1

package/.agents/skills/wp-abilities-audit/references/audit-schema.md

@@ -0,0 +1,300 @@
+# Audit Document Schema
+
+The canonical schema for an abilities audit doc. Every audit produced by
+`wp-abilities-audit` must conform to this schema so downstream tooling
+(humans reviewing, agents implementing, or validators like
+`wp-abilities-verify`) can consume it without parsing surprises.
+
+A copy-pasteable minimal example with both a read ability and a write
+ability lives under "Minimal valid example" below.
+
+## File layout
+
+```
+<output-dir>/<YYYY-MM-DD>-abilities-audit-<plugin-slug>.md
+```
+
+`<output-dir>` is explicit — collected from the user, not inferred. Typical
+values are the user's vault `plans/` directory or a dedicated audit repo.
+Writing into the plugin worktree is discouraged (pollutes git history).
+
+The body has two parts:
+
+1. A fenced ` ```yaml ` block holding structured fields (top-level metadata
+   + `proposed_abilities`, `excluded_from_mvp`, `surfaced_gaps`).
+2. Prose sections below: "Controller Inventory" table + "Notes and Surprises".
+
+A `Last updated: YYYY-MM-DD HH:MM` header sits above everything.
+
+## Top-level fields (all required)
+
+| Field | Type | Description |
+|---|---|---|
+| `plugin` | string | Plugin slug (e.g. `my-plugin`, `tasks-plugin`, `notifications`). |
+| `repo` | string | `Owner/Repository`. |
+| `branch_audited` | string | Git branch the audit was run against. |
+| `audited_at` | string | ISO date (YYYY-MM-DD). |
+| `auditor` | string | Human auditor name + team or context (e.g. `Your Name (Your Team)`). |
+| `baseline_abilities` | integer | Count of abilities already registered by the plugin at audit time. Usually 0. |
+| `capability_gate` | string OR object | The capability gate the base controller resolves to. Accept either a single string (single-cap plugins) OR a `{read, write}` object (post-type-backed or otherwise compound gates). See `capability-gate-tracing.md` for the mechanisms. |
+| `plugin_family` | string (optional) | Free-form classification when useful to downstream readers (e.g. `core-post-type`, `forms-engine`, or a project-specific family name). Optional and user-supplied — no canonical enum. Downstream consumers treat unknown values as opaque rather than erroring. |
+
+### `capability_gate` representations
+
+Two legal shapes, both consumed by downstream tooling:
+
+```yaml
+# Single-cap plugin (one capability across every controller)
+capability_gate: manage_options  # confirmed at includes/admin/class-my-plugin-rest-controller.php line 64
+```
+
+```yaml
+# Compound read/write (post-type-backed plugins typically need this shape;
+# read and write resolve to different capabilities)
+capability_gate:
+  read: read_private_pages
+  write: edit_others_pages
+  confirmed: true
+  verified_at: "custom_post_type capability_type='page' → core post-type cap map (wp-includes/post.php map_meta_cap)"
+```
+
+Plugin-specific capabilities (e.g. WooCommerce's `manage_woocommerce`,
+`edit_shop_orders`) are equally valid — substitute your plugin's caps. The
+shape is the contract; the literal cap names are project-specific.
+
+A legacy compound-string form exists in the wild (`"<read_cap> / <write_cap>"`)
+and is accepted for backwards compatibility, but the structured form above is
+the preferred representation for new audits.
+
+## `proposed_abilities` — array
+
+Each entry:
+
+| Field | Type | Description |
+|---|---|---|
+| `name` | string | Kebab-case `<plugin-slug>/<ability>`. |
+| `intent` | string | One sentence, user-question framed. |
+| `backing` | object or `null` | See below. `null` marks an ability with no backing endpoint (a known gap). |
+| `permission` | object or `null` | See below. `null` when `backing` is null. |
+| `return_type` | string | Short description (e.g. `WP_REST_Response (wrapping array)`). Hint-only; not machine-parsed. |
+| `effort` | enum | `S`, `M`, or `L`. |
+| `annotations` | object | `{ readonly: bool, destructive: bool, idempotent: bool }`. All three required. |
+| `notes` | array of strings | Implementer-facing detail (filter params, edge cases, alternative backings). |
+| `risks` | array of strings | Anything the implementer must handle (missing idempotency key, two-phase behavior, `permission_callback => '__return_true'` at the REST layer that must not copy into the ability, etc.). |
+| `use_case_fit` | string | One sentence naming the human or agent workflow this ability serves. The use-case-contract check (see `wp-abilities-api/references/domain-vs-projection.md`): if no human would intentionally do this through a supported UI or workflow, the entry probably belongs in `excluded_from_mvp` instead. |
+| `side_effects` | array of strings | Side effects the backing path emits on every call: telemetry hooks, audit-log rows, notifications, cache writes. One short line per effect. Empty array (`[]`) when the backing is a pure data-fetch — that is *itself* a load-bearing fact: it is what unlocks the conditional delegation shortcut in `wp-abilities-api/references/shared-core-service.md`. A non-empty array tells the implementer (and downstream verify-mode tooling) that this ability needs the shared-service shape, not the delegate-through-REST shortcut. |
+| `seed_data_needs` | string OR `null` | One line describing what representative data must exist in the test environment for the ability to execute through the public boundary and return something meaningful (e.g. `"at least one entity in the plugin's primary table"`, `"no seed required"`). `null` when the auditor has not yet identified the seed shape; downstream verify-mode tooling treats `null` as "ask the implementer" rather than guessing. |
+| `reference_ability` | bool (optional) | If `true`, marks this ability as the reference implementation — the first one an implementer should land (smallest, safest, highest-leverage read). Exactly zero or one ability per audit may set this. |
+
+### `backing: null` semantics
+
+An ability with `backing: null` is a known gap (the auditor identified a
+valuable ability that has no backing endpoint yet). The schema permits this
+as a warning, not an error:
+
+- The ability MUST also appear in `surfaced_gaps` with a one-line rationale.
+- Implementers pause for resolution rather than guessing a backing.
+- The audit is still valid; `backing: null` is intentional output, not
+  missing data.
+
+### `backing` object
+
+| Field | Type | Description |
+|---|---|---|
+| `kind` | enum (optional, default `rest_controller`) | The implementation path the ability should use or inspect. One of `rest_controller`, `service`, `helper`, `data_store`. When omitted, defaults to `rest_controller` for backwards compatibility with audits authored before this field landed. The kind tells downstream tooling whether the delegation pattern from `wp-abilities-api/references/shared-core-service.md` applies (only `rest_controller` is a candidate; the others select the shared-service shape from the start). |
+| `class` | string | Fully-qualified PHP class name (controller class for `rest_controller`; service / helper / data-store class for the other kinds). May be omitted when `kind: data_store` and the backing is a bare option key, post-meta key, or table without an owning class. |
+| `file` | string | Path relative to plugin root. |
+| `method` | enum (required when `kind: rest_controller`) | HTTP method: `GET`, `POST`, `PUT`, `DELETE`, `PATCH`. Not applicable when `kind` is `service`, `helper`, or `data_store`. |
+| `route` | string (required when `kind: rest_controller`) | Full REST route path. Not applicable to non-REST kinds. |
+| `route_registration_line` | integer OR `null` | For `kind: rest_controller`: line number of the `register_rest_route(` call, or `null` when inherited. Omit for other kinds. |
+| `callback` | string | For `kind: rest_controller`: controller method name that handles the route. For `kind: service` / `helper`: method name on the service / helper class. For `kind: data_store`: the operation name (`get_option`, `get_post_meta`) or the table-read pattern; may be omitted. |
+| `callback_line` | integer OR `null` | Line number of the callback or method definition, or `null` when inherited or not applicable. |
+| `inherited_from` | string (optional) | Fully-qualified parent class name when the route and/or callback is inherited from a class outside this plugin's repo (e.g. `WP_REST_Posts_Controller` from WordPress core, or another plugin's REST base class for extension plugins). Pair with `null` line numbers. Lets downstream tooling skip the re-grep step cleanly. Primarily relevant for `kind: rest_controller`. |
+
+### `permission` object
+
+| Field | Type | Description |
+|---|---|---|
+| `source` | enum (optional, default `rest_controller`) | Where the canonical permission for this behavior lives — not always the REST controller's `permission_callback`. One of `rest_controller`, `admin_action`, `service`, `domain_policy`, `post_type_map`, `none`. When omitted, defaults to `rest_controller` for backwards compatibility. `admin_action` for behaviors gated by `check_admin_referer` / `current_user_can` on an admin handler; `service` when a shared method enforces the cap; `domain_policy` for plugins with a policy / authorization layer; `post_type_map` for capabilities resolved through `map_meta_cap` on a post-type cap shadow; `none` for genuinely public behavior. Tells the implementer whether the ability's `permission_callback` can mirror the REST callback or must consult a different source of truth. |
+| `callback` | string | The method or function name that enforces the cap at the recorded `source`. For `source: rest_controller`, this is the `permission_callback` value. For `source: admin_action`, the admin handler function or method. For `source: service`, the service method that performs the cap check. |
+| `resolves_to` | string | The `current_user_can()` call(s) it ultimately resolves to. For compound gates, include both (e.g. `"current_user_can('read_private_pages')` for read; `current_user_can('edit_others_pages')` for write"). |
+| `confirmed` | bool | `true` if verified against source; `false` if inferred. |
+
+## `excluded_from_mvp` — array
+
+Abilities intentionally deferred for risk reasons. Each entry:
+
+| Field | Type | Description |
+|---|---|---|
+| `name` | string | Proposed ability name (kebab-case). |
+| `reason` | string | One sentence why it's deferred. |
+
+## `surfaced_gaps` — array
+
+MVP candidates with no backing endpoint (paired with `backing: null` above),
+plus high-value endpoints discovered during enumeration that aren't in MVP
+but would make future follow-up work. Each entry:
+
+| Field | Type | Description |
+|---|---|---|
+| `name` | string | Proposed ability name. |
+| `one_line_rationale` | string | Why it would be high-leverage. |
+
+## Prose sections (required)
+
+### Controller Inventory
+
+A Markdown table with columns `Class | File | REST Base | Routes`. Must list
+every controller enumeration found, even ones that aren't backing any MVP
+ability. This gives reviewers a full picture and catches "why isn't X in the
+MVP?" questions.
+
+### Notes and Surprises
+
+Free-form prose capturing anything that didn't fit the structured schema:
+capability-gate mismatches between controllers, hardcoded route paths, dual
+controllers with different output shapes, two-phase endpoint semantics, and
+any judgment calls the auditor made.
+
+## Minimal valid example
+
+Copy-pasteable starting point for a new audit:
+
+````markdown
+---
+Last updated: 2026-04-20 14:30
+---
+
+# Example Plugin Abilities — Phase 1 Audit
+
+```yaml
+plugin: example-plugin
+repo: Owner/example-plugin
+branch_audited: feat/abilities-example-plugin
+audited_at: 2026-04-20
+auditor: Your Name (Your Team)
+baseline_abilities: 0
+capability_gate: manage_options  # confirmed at includes/rest-api/class-example-rest-controller.php line 32
+
+proposed_abilities:
+
+  - name: example-plugin/get-items
+    intent: "List items with filters (status, owner, date range) so an agent can answer 'which items need attention?' in one call."
+    backing:
+      kind: rest_controller
+      class: Example_REST_Items_Controller
+      file: includes/rest-api/class-example-rest-items-controller.php
+      method: GET
+      route: /example/v1/items
+      route_registration_line: 26
+      callback: get_items
+      callback_line: 52
+    permission:
+      source: rest_controller
+      callback: check_permission
+      resolves_to: "current_user_can('manage_options')"
+      confirmed: true
+    return_type: "WP_REST_Response (wrapping array)"
+    effort: S
+    annotations: { readonly: true, destructive: false, idempotent: true }
+    notes:
+      - "get_items(WP_REST_Request $request) requires a WP_REST_Request; construct one in the ability execute_callback."
+    risks: []
+    use_case_fit: "Agent answers 'which items need attention right now?' in a single call without paging through a UI."
+    side_effects: []
+    seed_data_needs: "at least one item exists in any non-trashed status"
+    reference_ability: true
+
+  - name: example-plugin/close-item
+    intent: "Close a single item — terminal state transition, non-reversible."
+    backing:
+      kind: service
+      class: Example_Items_Service
+      file: src/Service/class-items-service.php
+      callback: close
+      callback_line: 88
+    permission:
+      source: service
+      callback: Example_Items_Service::assert_can_close
+      resolves_to: "current_user_can('manage_options')"
+      confirmed: true
+    return_type: "WP_REST_Response (updated item object)"
+    effort: M
+    annotations: { readonly: false, destructive: true, idempotent: false }
+    notes:
+      - "Close is terminal — no reopen endpoint exists."
+    risks:
+      - "No idempotency key on the backing endpoint; duplicate POSTs may produce inconsistent audit trails."
+    use_case_fit: "User or agent closes a stale item from a workflow that surfaces stale items (admin list view, daily-digest agent)."
+    side_effects:
+      - "fires action `example_plugin/item_closed` (downstream listeners may dispatch email)"
+      - "writes audit-log row to `example_plugin_audit_log`"
+    seed_data_needs: "one open item to close; the test must capture the item id before invocation"
+
+excluded_from_mvp:
+  - name: example-plugin/delete-item
+    reason: "Hard delete is irreversible and lacks an undo endpoint; defer until soft-delete is designed."
+
+surfaced_gaps:
+  - name: example-plugin/get-overview
+    one_line_rationale: "A zero-arg overview endpoint answering 'what's the current state of all items?' would be the highest-leverage ability but no backing endpoint exists yet."
+```
+
+## Controller Inventory
+
+| Class | File | REST Base | Routes |
+|---|---|---|---|
+| Example_REST_Items_Controller | includes/rest-api/class-example-rest-items-controller.php | example/v1/items | GET /example/v1/items, POST /example/v1/items/{id}/close |
+
+## Notes and Surprises
+
+### Capability gate is uniform
+Every controller inherits `Example_Base_REST_Controller` and uses
+`check_permission` verbatim as the `permission_callback`. No per-route
+overrides. Safe to treat `manage_options` as the single gate.
+````
+
+## Known limitations
+
+Documented so downstream skills have an explicit contract:
+
+- **`capability_gate` string-with-inline-comment form** loses data when parsed
+  by strict YAML parsers (comments are dropped). The structured object form is
+  preferred; string form is accepted for backwards compatibility.
+- **Legacy compound-string `capability_gate`** — the `"<read_cap> / <write_cap>"`
+  form predates the structured `{read, write}` object and is still accepted
+  for backwards compatibility. Validators (e.g. `wp-abilities-verify`)
+  emit WARN on this form to nudge migration to the structured shape;
+  they do NOT FAIL. New audits should use the object form.
+- **`return_type` is hint-only.** Prose for the human auditor; not
+  machine-parseable. Downstream skills use runtime `is_wp_error(...)` and
+  `instanceof WP_REST_Response` checks regardless of what this field says.
+- **Line numbers drift.** `route_registration_line` and `callback_line` are
+  captured at audit time and may bit-rot. Downstream skills re-locate routes
+  by `(class, callback)` and do not rely on exact line numbers.
+- **`inherited_from` + `null` line numbers** are the canonical way to
+  represent routes/callbacks defined in a parent class that lives outside
+  the plugin repo.
+- **`backing: null` invariant.** Abilities with `backing: null` are intentional
+  gaps and MUST also appear in `surfaced_gaps` by `name`. Validators FAIL
+  audits where this invariant is violated (a `null` backing without a
+  matching `surfaced_gaps` entry indicates inconsistent audit output).
+- **Implementation-readiness fields added 2026-05-21.** `use_case_fit`,
+  `side_effects`, and `seed_data_needs` are required in the per-ability
+  schema as of this date. Audits authored against an earlier revision of
+  this schema will be missing the three fields. Validators (e.g.
+  `wp-abilities-verify`) emit WARN on missing implementation-readiness
+  fields to nudge backfill the next time the audit is touched; they do
+  NOT FAIL, mirroring the legacy `capability_gate` posture above. New
+  audits MUST populate all three.
+- **`backing.kind` and `permission.source` added 2026-05-21.** Both
+  are optional with default `rest_controller` so older audits validate
+  as-is. New audits SHOULD populate both explicitly — `backing.kind`
+  to record whether the ability backs a REST controller, a shared
+  service, a helper, or a data store (because the answer drives the
+  delegate-vs-extract-service decision in `wp-abilities-api/references/
+  shared-core-service.md`); `permission.source` to record where the
+  canonical permission lives (REST callback is the common case, but
+  admin actions, service methods, domain policies, and post-type cap
+  maps each happen). Validators treat a missing field as the default,
+  not as an error.

package/.agents/skills/wp-abilities-audit/references/capability-gate-tracing.md

@@ -0,0 +1,197 @@
+# Capability-Gate Tracing
+
+How to resolve the actual capability (or capabilities) a plugin's REST
+controllers gate on. The audit's `capability_gate` field and each ability's
+`permission.resolves_to` field need to reflect reality, not what the
+controller docblock says.
+
+Two common mechanisms cover most plugins. Document both explicitly so the
+auditor doesn't hard-code one plugin family's assumptions.
+
+## Mechanism A — Direct (`check_permission()` returning a single cap)
+
+The base REST controller declares a `check_permission()` (or
+`permissions_check()`) method that calls `current_user_can('<some_cap>')`
+once. Every route in the controller uses that method as
+`permission_callback`.
+
+### Identifying signs
+
+- The base controller has a method like:
+  ```php
+  public function check_permission() {
+      return current_user_can( 'manage_options' );
+  }
+  ```
+- Controllers extend the plugin's own base, not a WordPress core
+  post-type-backed class.
+- The grep `grep -n 'current_user_can' <base-controller>.php` yields one hit.
+
+### How to trace
+
+```bash
+# Locate the base controller (usually the parent of every REST controller).
+grep -rn 'extends .*REST_Controller' includes/ | head
+
+# Read its permission_callback implementation.
+grep -n 'check_permission\|permissions_check' <base-controller>.php
+```
+
+Trace once: the single `current_user_can()` call is the plugin's gate.
+
+### How to represent in the audit
+
+```yaml
+capability_gate: manage_options  # confirmed at includes/admin/class-<plugin>-rest-controller.php line 64
+```
+
+Plugin-specific capabilities (e.g. WooCommerce's `manage_woocommerce` for
+shop-aware contexts, Jetpack Forms' `edit_pages`) substitute for
+`manage_options` cleanly — the shape stays the same.
+
+## Mechanism B — Post-type-backed (core CPT capability machinery)
+
+The controller extends a WordPress core post-type-backed class that
+dispatches to the post-type capability map. There is no local
+`check_permission()` — the permission callback resolves dynamically at
+request time based on the request context (read vs write) and the post
+type's `cap` object.
+
+### Identifying signs
+
+- The controller's base class is one of:
+  - `WP_REST_Posts_Controller` — the core post-type REST base.
+  - A subclass of it, in or out of this plugin's repo.
+- No local `check_permission()` — permission callbacks are inherited.
+- The post type is registered with `capability_type => '<cpt_or_shadow>'`,
+  and the cap map is resolved by core's `map_meta_cap()`.
+
+### How to trace
+
+```bash
+# Find the post-type registration.
+grep -rn "register_post_type\s*(\s*['\"]<cpt_name>['\"]" .
+
+# Read the registration block. The relevant fields are:
+#   - capability_type: the type whose cap map this post type uses.
+#     A custom post type can either declare its own caps or shadow another
+#     type's (e.g. capability_type => 'page' to reuse Pages' caps).
+#   - capabilities: optional explicit cap-string overrides.
+#   - map_meta_cap: whether meta caps (read_post, edit_post) get mapped to
+#     primitive caps (read_private_<type>s, edit_others_<type>s).
+```
+
+Dynamic resolution typically lands at:
+
+- **Read context** (GET list / GET item): `current_user_can('read_private_<type>s')` or `current_user_can('read_<type>', $id)`.
+- **Write context** (POST / PUT / DELETE): `current_user_can('edit_<type>s')`, `current_user_can('edit_others_<type>s')`, or `current_user_can('delete_<type>s', $id)`.
+
+The two often differ — post-type-backed plugins routinely have distinct read
+and write caps.
+
+### How to represent in the audit
+
+Use the structured `{read, write}` form from `audit-schema.md`:
+
+```yaml
+capability_gate:
+  read: read_private_pages
+  write: edit_others_pages
+  confirmed: true
+  verified_at: "custom_post_type capability_type='page' → core map_meta_cap (wp-includes/post.php) → primitive page caps"
+```
+
+In each ability's `permission` block, spell out both calls:
+
+```yaml
+permission:
+  callback: get_items_permissions_check
+  resolves_to: "WP_REST_Posts_Controller::get_items_permissions_check (inherited) → current_user_can('read_private_pages')"
+  confirmed: true
+```
+
+Example A — generic plugin shadowing core Pages caps. A custom post type
+registered with `capability_type='page'` inherits the Pages cap map, so
+reads gate on `read_private_pages` and writes gate on `edit_others_pages`.
+
+Example B — WooCommerce-style sidebar. WooCommerce's `shop_subscription` is
+registered with `capability_type='shop_order'`, so reads gate on
+`read_private_shop_orders` and writes gate on `edit_shop_orders`.
+Mechanically identical to Example A; the cap names are project-specific.
+WooCommerce also exposes a helper `wc_rest_check_post_permissions()` that
+wraps the same core machinery — the helper is convenience; the underlying
+mechanism is core's `map_meta_cap()`.
+
+## Compound-string form (accepted, not preferred)
+
+Some earlier audits encoded compound gates as a single string with a `/`
+separator:
+
+```yaml
+capability_gate: read_private_pages / edit_others_pages
+```
+
+This is accepted for backwards compatibility, but:
+
+- Downstream consumers have to heuristically split on `/`.
+- YAML comments after the string are silently dropped by strict parsers, so
+  provenance gets lost.
+- The `{read, write}` object form is machine-parseable and carries
+  `confirmed` and `verified_at` in-band.
+
+Prefer the structured form for any new audit.
+
+## Procedure — trace the permission source for each proposed behavior
+
+The ability's permission should match the plugin's intended gate for the
+proposed *behavior*, not necessarily the REST route. Often the REST
+controller's `permission_callback` is the right source of truth, but in
+some plugins the canonical permission lives elsewhere — an admin-action
+handler with its own `check_admin_referer` + `current_user_can` block, a
+service / helper method that performs the check before doing the work, a
+domain-policy / authorization layer, or a post-type cap shadow resolved
+through core's `map_meta_cap`. The audit should preserve where the
+permission canonically lives so the implementer doesn't silently drift
+to whichever source the REST layer happens to expose.
+
+For each proposed ability, walk the chain once:
+
+1. Identify the *behavior* the ability surfaces, then locate where the
+   plugin enforces the cap for that behavior. Check the REST controller's
+   `permission_callback` first; if the REST callback is `'__return_true'`,
+   delegates entirely, or doesn't match the behavior's intended gate,
+   look for the canonical source in an admin handler, a shared service
+   method, a domain-policy class, or a post-type cap map.
+2. Record where the gate lives in the ability's `permission.source` field
+   per `audit-schema.md`: one of `rest_controller`, `admin_action`,
+   `service`, `domain_policy`, `post_type_map`, `none`. Default
+   `rest_controller`; pick another value when the canonical source is
+   elsewhere.
+3. Determine whether the gate is Mechanism A (local method, single cap)
+   or Mechanism B (inherited, post-type-backed, dynamic).
+4. Resolve to the actual `current_user_can()` call(s). For Mechanism B,
+   resolve BOTH read and write if the ability crosses contexts.
+5. Record in the ability's `permission.resolves_to` field verbatim — the
+   string should read as an actual trace, not a best-guess summary.
+6. Add a risk note when the canonical permission source diverges from
+   the REST controller's callback: the ability's `permission_callback`
+   must consult the canonical source (or replicate its check), not
+   copy the REST callback by reflex.
+7. If every behavior in the plugin resolves to the same cap (or same
+   `{read, write}` pair) at the same source, hoist it into the top-level
+   `capability_gate`. If any behavior diverges in cap OR in source,
+   record the divergence in "Notes and Surprises".
+
+## Common pitfall — `permission_callback => '__return_true'`
+
+Zero-arg public endpoints sometimes declare `permission_callback =>
+'__return_true'` at the REST layer (e.g. status lookups, enumerated lists
+that are safe to expose). The audit still needs a gate:
+
+- Record the REST-layer value as-is (`resolves_to:
+  "__return_true (public)"`) so the auditor isn't hiding reality.
+- Add a risk note: the **ability** registration must NOT copy
+  `'__return_true'` — the ability's own `permission_callback` must match
+  the plugin's intended user gate (e.g. `manage_options`, `edit_pages`, or
+  whatever your plugin uses). The ability layer is the agent-facing surface
+  and needs that gate even when the underlying REST route is public.

package/.agents/skills/wp-abilities-audit/references/controller-enumeration.md

@@ -0,0 +1,116 @@
+# Controller Enumeration
+
+How to produce an exhaustive list of a plugin's REST controllers — the first
+step of every audit. Plugin family classification is handled separately by
+`wp-project-triage`; this reference covers the mechanics of finding controller
+classes inside whatever layout the plugin happens to use.
+
+## Two enumeration paths
+
+Observed across the plugins audited to date, there are exactly two paths that
+together cover every layout seen in the wild:
+
+| Path | When it works | How it works |
+|---|---|---|
+| **Glob** | Plugins that follow the standard `includes/admin/class-*-rest-*-controller.php` layout (WooCommerce core extensions, classic WooPayments). | Fast, deterministic, easy to script. Returns a complete list in one shell call. |
+| **Grep** | Any non-standard layout — `includes/api/`, `includes/rest-api/`, `src/rest/`, monorepo package directories, or anything else. | Universal fallback: grep every PHP file under the plugin root for `register_rest_route(` call sites, then collect the enclosing class for each hit. |
+
+### Default order
+
+1. **Try glob first** — it's faster and produces a cleaner inventory.
+2. **Fall back to grep** if glob returns zero hits (or clearly undercounts
+   against what you see in the plugin's public documentation / admin UI).
+
+Running both and de-duplicating is legal; it catches monorepos that have
+*some* controllers under the standard layout and *others* under a package
+directory.
+
+## Glob — standard layout
+
+```bash
+# From the plugin root:
+ls includes/admin/class-*-rest-*-controller.php 2>/dev/null
+ls includes/reports/class-*-rest-*-controller.php 2>/dev/null
+```
+
+What you'll see in repos that match this convention:
+
+- WooPayments (`Automattic/woocommerce-payments`) — every controller under
+  `includes/admin/class-wc-rest-payments-*-controller.php` plus some under
+  `includes/reports/`.
+- WooCommerce core's internal REST controllers use the same pattern.
+
+If glob returns 5+ hits, it's almost always the complete inventory. If it
+returns 0-2, fall through to grep.
+
+## Grep — universal fallback
+
+```bash
+# From the plugin root:
+grep -rn --include='*.php' 'register_rest_route(' .
+```
+
+For each hit:
+
+1. Open the file.
+2. Walk up to the enclosing class declaration.
+3. Record `(class, file, route, callback, permission_callback)`.
+
+This path matters because it's the only one that finds controllers in
+non-standard locations:
+
+- **WooCommerce Subscriptions** — controllers live under `includes/api/` and
+  `includes/api/legacy/`. The standard WooPayments glob returns zero; grep is
+  mandatory.
+- **Jetpack Forms** (and most Jetpack packages) — controllers live under
+  `projects/packages/<name>/src/` with no conventional filename. Grep is
+  again mandatory.
+- **Custom plugin layouts** — anything with `src/Rest/`, `lib/rest/`,
+  `api/v1/`, etc. Grep catches them all.
+
+## Inherited routes
+
+A controller can extend a base class in a different repo — typically the
+parent plugin (for extensions built on top of another plugin) or WordPress
+core itself (for plugins extending `WP_REST_Posts_Controller` or other core
+REST bases). The `parent::register_routes()` dispatch appears in the
+extending plugin's source, but the literal `register_rest_route(` call lives
+in the parent. WooCommerce extensions extending
+`WC_REST_Orders_Controller`, plugins built on Jetpack package REST classes,
+and CPT plugins inheriting from `WP_REST_Posts_Controller` all hit this
+pattern.
+
+Handling:
+
+- Record the route on the child class (that's where the plugin's REST surface
+  actually exposes it).
+- Set `backing.route_registration_line: null` and
+  `backing.callback_line: null` in the audit schema.
+- Add `backing.inherited_from: "<parent FQCN>"` so downstream skills can tell
+  the inheritance case from a plain missing line number.
+- Consider running grep against the parent repo too when you need to confirm
+  the callback's request handling — inherited callbacks behave as whatever
+  the parent defines, not what the plugin repo documents.
+
+See `audit-schema.md` for the exact field shapes.
+
+## Exhaustiveness is the goal
+
+The "Controller Inventory" table in the audit doc must list every controller
+the enumeration found — not just ones backing proposed abilities. A reviewer
+asking "why isn't controller X in the MVP?" should be able to point at the
+inventory and see the explicit answer (usually: "excluded from MVP because…"
+or "surfaced as a gap because…").
+
+If your inventory has 3 entries and the plugin clearly exposes more, either
+the enumeration is incomplete (re-run grep with broader patterns) or you're
+filtering the inventory instead of the proposal list. Fix the inventory
+first; filter after.
+
+## Escalation
+
+If neither glob nor grep produces a complete inventory — for example a
+plugin that registers routes dynamically from config or via a factory that
+does not contain a literal `register_rest_route(` string — document the
+enumeration gap in "Notes and Surprises", and extend this reference with the
+new pattern once understood.