Audit des capacités WP

Produire un document d'audit standardisé pour la surface REST d'un plugin WordPress, proposant un ensemble d'enregistrements Abilities API regroupés par intention sémantique. Le document d'audit est un artéfact de planification pour les implémenteurs — humains, agents ou les deux — qui capture l'inventaire des contrôleurs, les portes de capacité et les formes d'ability proposées sous forme structurée. Un relecteur consultant le document peut délimiter le travail sans redériver l'enquête.

Cette skill fonctionne sur tout plugin qui expose une surface REST. La classification du plugin (aux fins de l'annotation optionnelle plugin_family) est à l'appréciation de l'utilisateur ; le flux de travail lui-même est indépendant du plugin.

Quand utiliser

La tâche est « enregistrer les abilities de l'Abilities API pour un plugin WP » et aucun document d'audit n'existe encore.
Planifier une participation à un déploiement d'abilities multi-plugin et avoir besoin d'un artéfact d'audit standardisé et partageable.
Vérifier en amont qu'un plugin est prêt pour les agents avant d'implémenter les abilities.
Un PM ou un non-implémenteur veut délimiter le travail avant que l'engineering s'en charge.

Entrées requises

Chemin de checkout du plugin — arborescence de travail du plugin à auditer.
Sortie de triage — exécuter d'abord wp-project-triage si ce n'est pas déjà fait. L'audit consomme signals.usesAbilitiesApi, versions.wordpress et project.kind du rapport.
Identité de l'auditeur — nom et équipe ou contexte, enregistrés dans le champ auditor de l'audit.
Chemin de sortie — où le document d'audit doit être placé. Préférer l'explicite à l'implicite ; demander s'il n'est pas fourni plutôt que d'écrire dans l'arborescence du plugin.

Conditions préalables

wp-project-triage a s'exécuté avec succès et a classé le plugin.
Le plugin a au moins un contrôleur REST. Si l'énumération trouve zéro contrôleur, l'audit ne s'applique pas — voir « Modes d'échec » ci-dessous.

Procédure

1. Énumérer les contrôleurs REST

Lire references/controller-enumeration.md maintenant — il couvre les deux chemins d'énumération observés (glob pour les dispositions standard, grep comme solution universelle) et quand utiliser chacun.

Enregistrer chaque classe de contrôleur + fichier + base REST + routes dans un tableau « Inventaire des contrôleurs ». L'inventaire est exhaustif même si seul un sous-ensemble devient des abilities proposées.

2. Pour chaque contrôleur, extraire les champs de support

Pour chaque contrôleur trouvé, extraire les champs que le schéma d'audit requiert : classe, fichier, méthode HTTP, route, numéro de ligne d'enregistrement de route, nom du callback, numéro de ligne du callback, permission callback, si le callback prend un argument WP_REST_Request ou est sans argument, et le type de retour.

Lire references/audit-schema.md maintenant pour la liste exacte des champs et la forme des entrées proposed_abilities. Les champs numéro de ligne peuvent être null pour les callbacks hérités — le schéma le permet et l'associe à un champ optionnel inherited_from.

3. Confirmer la/les porte(s) de capacité

Tracer le permission_callback de chaque contrôleur jusqu'à son appel current_user_can() (ou jusqu'à la machinerie de capacité du type de post si le contrôleur étend une base soutenue par un type de post).

Lire references/capability-gate-tracing.md maintenant — il documente les deux mécanismes courants (check_permission() direct vs wc_rest_check_post_permissions() soutenu par type de post) et comment représenter chacun dans le schéma. Noter explicitement si les portes de lecture et d'écriture diffèrent : les portes composées sont représentées comme un objet {read, write}, pas une seule chaîne.

4. Proposer les abilities avec regroupement par intention sémantique

NE PAS atomiser une ability par méthode HTTP. Appliquer l'heuristique de regroupement par intention sémantique — c'est la seule règle de regroupement que cette skill utilise.

Lire ../wp-abilities-api/references/grouping-heuristic.md maintenant — NE PAS redériver les règles ici. Version courte : une ability par question réelle ou transition d'état, avec des paramètres de filtre dans input_schema réduisant N variantes à 1.

Appliquer le test de sanité du cas d'usage avant de remplir tout candidat. Selon le test du contrat de cas d'usage de ../wp-abilities-api/references/domain-vs-projection.md : un humain ou un agent effectuerait-il intentionnellement ce comportement via un flux de travail de plugin pris en charge ? Si oui, le candidat est une ability réelle — procéder au remplissage des champs. Si non, la route est de la plomberie de transport interne (invalidation du cache, ticks du planificateur, endpoints de comptabilité, introspection de débogage) — la conserver dans la section Inventaire des contrôleurs pour l'exhaustivité, mais NE PAS la promouvoir en proposed_abilities. La route peut être utile à l'inventaire ; la ability proposée doit représenter une question ou une action réelle de l'utilisateur/opérateur.

Pour chaque ability proposée qui passe le test de sanité, remplir chaque champ du schéma proposed_abilities : name, intent, backing, permission, return_type, effort (S/M/L), annotations (readonly/destructive/idempotent), notes, risks, use_case_fit, side_effects, seed_data_needs.

Les trois derniers sont les faits de préparation à l'implémentation que l'implémenteur et l'outillage en mode vérification ont besoin : quel flux de travail humain/agent cette ability sert (use_case_fit), ce que le chemin de support émet à chaque appel (side_effects — un tableau vide est un fait, pas une valeur manquante), et quelles données représentatives doivent exister dans l'environnement de test pour que l'ability s'exécute via la limite publique (seed_data_needs).

5. Surfaces les lacunes et les éléments reportés

Trois catégories :

excluded_from_mvp — candidats intentionnellement reportés pour des raisons de risque (écritures en vrai argent, changements d'état irréversibles ou travail de conception préalable). Chaque entrée reçoit une raison d'une phrase.
surfaced_gaps — candidats MVP sans endpoint de support (ability avec backing: null), plus les endpoints de haute valeur découverts lors de l'énumération qui ne sont pas dans la liste MVP mais seraient des victoires futures faciles.
Risques par ability — tout ce qui concerne un endpoint de support que l'implémenteur doit gérer (pas de clé d'idempotence, comportement en deux phases, avertissements de transition d'état, endpoints sans argument enregistrés avec permission_callback => '__return_true' qui ne doivent PAS copier cela dans l'enregistrement d'ability).

6. Rédiger le document d'audit

Écrire au chemin de sortie explicite collecté dans « Entrées requises ». La structure du document doit correspondre exactement à references/audit-schema.md :

En-tête Last updated: YYYY-MM-DD HH:MM.
Bloc YAML avec tous les métadonnées de haut niveau requises + proposed_abilities, excluded_from_mvp, surfaced_gaps.
Tableau « Inventaire des contrôleurs ».
Section de prose « Notes et Surprises ».

Un exemple minimal copiable-collable montrant la forme complète se trouve dans references/audit-schema.md sous « Minimal valid example » — commencer là lors de la création d'un nouvel audit.

7. (Optionnel) Désigner une ability d'implémentation de référence

Définir reference_ability: true sur la première ability qu'un implémenteur doit intégrer — généralement la plus petite, la plus sûre, la plus rentable en lecture. Cela donne aux flux de travail en aval un point de départ déterministe.

Vérification

L'audit se conforme à references/audit-schema.md (tous les champs de haut niveau requis présents, au moins une entrée dans proposed_abilities, annotations complètes sur chaque ability).
capability_gate est une chaîne pour les plugins à capacité unique ou un objet {read, write} pour les plugins soutenus par type de post.
Chaque ability avec backing: null apparaît aussi dans surfaced_gaps.
Le document s'arrondit à travers le validateur dans audit-schema.md « Known limitations » sans erreurs.

Modes d'échec / débogage

Plugin n'a pas de contrôleurs REST — audit ne s'applique pas. Considérer les abilities basées sur les hooks/filtres (hors de portée de la version actuelle de cette skill) ou ignorer l'adoption d'abilities pour ce plugin.
Plugin hérite de contrôleurs d'un autre repo (courant pour les plugins étendant les contrôleurs REST soutenus par type de post comme WP_REST_Posts_Controller, ou les plugins d'extension construits sur les classes REST d'un parent) — capturer avec backing.inherited_from: "<parent FQCN>". Les champs numéro de ligne peuvent être null selon le schéma.
Porte de capacité composée (capacités de lecture/écriture distinctes) — utiliser la forme structurée {read, write} documentée dans references/capability-gate-tracing.md. Ne pas glisser une chaîne séparée par / dans un champ typé comme une seule capacité.
Regroupement ambigu — router vers ../wp-abilities-api/references/grouping-heuristic.md. Ne pas inventer de règles de regroupement alternatives dans le document d'audit.
Endpoints sans argument avec permission_callback => '__return_true' — légal au niveau REST, mais le permission_callback de l'ability lui-même doit correspondre à la porte du merchant du plugin. Ne jamais promouvoir '__return_true' en un enregistrement d'ability. Noter cela dans les risks de l'ability.
Le chemin de sortie par défaut vers l'arborescence du plugin — toujours demander à l'utilisateur un répertoire de sortie explicite (par exemple leur vault plans/). Écrire l'audit dans l'historique git du plugin lui-même pollue l'arborescence et enterre l'artéfact.

Escalade

Si le plugin utilise une convention d'énumération non couverte par references/controller-enumeration.md (ni le glob standard ni le fallback grep ne produisent un inventaire complet), mettre à jour cette référence avec la nouvelle convention et ouvrir une PR pour que les audits futurs la couvrent de manière déterministe.
Si le traçage de capacité rencontre un mécanisme non couvert par references/capability-gate-tracing.md, étendre ce fichier plutôt que d'encoder le nouveau cas dans la « Notes et Surprises » de l'audit uniquement.

wp-abilities-audit