wordpress-agent-kit 0.5.1 → 0.6.0

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

@@ -1,300 +0,0 @@
-# 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/.github/skills/wp-abilities-audit/references/capability-gate-tracing.md

@@ -1,197 +0,0 @@
-# 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/.github/skills/wp-abilities-audit/references/controller-enumeration.md

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