WP Abilities Verify

Vérifier les enregistrements Abilities API d'un plugin WordPress. Le cœur du système est la vérification adversarielle de la correction des annotations : une ability avec readonly: true qui écrit réellement (via $wpdb->update, update_option, un delegate non-GET, etc.) est un désastre de sécurité et d'UX car les agents planifient les actions en fonction des annotations qu'ils introspectent. Ce skill détecte ces mensonges en lisant le corps du callback et en comparant ce qu'il fait par rapport à ce que l'annotation prétend.

Le skill valide également les documents d'audit produits par wp-abilities-audit, vérifie les portes de permission et l'hygiène du schéma, et peut optionnellement exécuter chaque ability dans un environnement actif.

Quand utiliser

Après que les abilities ont été enregistrées dans un plugin mais avant qu'une PR ne débarque.
Comme contrôle de santé sur un plugin déjà livré (détecter les régressions où une refonte a transformé une ability readonly en ability écrivain).
Pour valider un document d'audit avant de le confier à un implémenteur.

Deux modes

Mode statique — s'exécute depuis le checkout du plugin. Aucun env. Énumère par inspection de source, lance la vérification de correction adversarielle, exécute les lints de schéma et de permission, et valide les documents d'audit.
Mode runtime — nécessite un env actif. Fait tout ce que le mode statique fait PLUS : wp_get_abilities() pour l'énumération faisant autorité, exécute chaque ability avec des entrées curées, confirme le roundtrip de permission contre des vrais utilisateurs, et exécute une heuristique d'invocation double sur les abilities idempotent: true pour signaler les candidates à réviser (l'égalité des valeurs de retour est un signal, pas un verdict — le core définit idempotent comme « aucun effet supplémentaire sur l'environnement »).

Les deux modes produisent le même format de rapport structuré.

Un PASS en mode statique signifie « aucune violation de forme évidente », pas « vérifié sans écriture ». Pour les plugins critiques, lancez le mode runtime avant de débarquer — il détecte les problèmes d'ordre de bootstrap, de roundtrip de permission et d'idempotence que le mode statique ne peut pas. Voir references/annotation-correctness.md pour les points aveugles du mode statique.

Entrées requises

Chemin du checkout du plugin — arborescence à vérifier.
Mode — static ou runtime. Par défaut statique si non spécifié.
(Runtime uniquement) Commande d'env-up — lisez le AGENTS.md du plugin. Patterns courants : npm run wp-env start, npx wp-env start, ou un bring-up basé sur composer. Les familles de plugins avec leurs propres outils de dev documenteront leur propre commande. N'ASSUREZ PAS que npm run wp-env fonctionne.
(Optionnel) Chemin du document d'audit — active les vérifications croisées entre l'audit et les abilities enregistrées, et valide l'audit lui-même.
Chemin de sortie du rapport — chemin explicite, généralement le vault de l'utilisateur.

Prérequis

wp-project-triage a été exécuté sur le plugin.
Le plugin a au moins une ability enregistrée en source. Zéro hit sur wp_register_ability( → retourner un rapport clair « aucune ability enregistrée », pas un PASS vide.

Procédure

1. (Si audit fourni) Valider le document d'audit

Lisez references/audit-schema-validation.md. Validez l'audit par rapport au schéma canonique détenu par wp-abilities-audit. Signalez les champs obligatoires manquants, les reference_ability: true multiples, et les entrées backing: null non appairées avec une entrée surfaced_gaps. backing: null seul est WARN (output de gap intentionnel), pas FAIL.

2. Énumérer les abilities de façon statique

Lisez references/static-enumeration.md. Trouvez chaque appel wp_register_ability(, extrayez le nom, le bloc d'annotation, et l'emplacement du callback d'exécution. Utilisez un outil multi-ligne (rg --multiline --pcre2) — le formatage canonique divise l'appel sur plusieurs lignes. Enregistrez pour chaque ability le fichier source + ligne + annotations + plage d'octets du callback.

3. (Runtime uniquement) Énumérer via REST + wp-cli

Lisez references/runtime-harness.md. Levez l'env en utilisant la commande depuis AGENTS.md, puis énumérez via wp_get_abilities() sur wp-cli et vérifiez par rapport à l'inventaire statique. Source uniquement → FAIL (enregistrement ne se déclenche pas). Runtime uniquement → WARN (chemin d'enregistrement dynamique).

4. Correction des annotations (le cœur adversariel)

Lisez references/annotation-correctness.md. Lisez chaque corps de callback et vérifiez qu'il correspond à la réclamation d'annotation :

readonly: true → le callback ne doit pas écrire dans la base de données, la table d'options, les données post / utilisateur / terme / commentaire, le système de fichiers, cron, ou via des delegates HTTP / REST non-GET.
destructive: false → le callback ne doit pas supprimer, rembourser, annuler, valider ou mettre à la corbeille.
idempotent: true → les appels répétés avec la même entrée n'ont aucun effet supplémentaire sur l'environnement (selon le docblock de l'annotation idempotent dans class-wp-ability.php). Le mode statique détecte les écritures de compteur et les schedules cron par appel ; le mode runtime ajoute une heuristique d'invocation double pour les changements d'état visibles.

La référence liste les patterns d'écriture courants comme point de départ, pas comme liste de vérification — les vocabulaires des plugins varient, et l'agent s'étend avec des verbes spécifiques au plugin en cours de vérification.

Les faux positifs sont supprimés via un commentaire inline // verify-ignore: <annotation> -- <reason>.

5. Roundtrip de permission

Lisez references/permission-roundtrip.md. Mode statique : classifiez chaque permission_callback par rapport aux six formes (la Shape A préférée current_user_can(...) ; FAIL sur les patterns Shape B-bad WP_REST_Request ou la Shape E littérale true). Mode runtime : anon et subscriber refusés ; admin autorisé (sauf délibérément public). Quand un audit a été fourni, vérifiez par rapport à la cap déclarée de l'audit.

6. Lints de schéma

Lisez references/schema-lints.md. Six petits principes appliqués à chaque input_schema d'ability : les schémas d'objet déclarent additionalProperties ; les champs requis ont des descriptions ; les énums non vides ; pas de $ref ; les valeurs par défaut sont statiquement constantes (y compris (object) array()) ; les abilities de référence n'ont pas d'entrées requises.

Référencez croisé ../wp-abilities-api/references/input-schema-gotchas.md pour les quatre gotchas runtime (defaults non injectés sur le chemin au niveau propriété, dérive de clé de pagination, empty() sur les IDs de chaîne, rigueur d'invocation directe vs indirecte).

7. Vocabulaire des codes d'erreur

Référencez croisé ../wp-abilities-api/references/error-code-vocabulary.md. Inspectez chaque retour WP_Error du callback ; les codes en dehors du vocabulaire → WARN.

Vérification

L'exécution produit un rapport markdown structuré au chemin spécifié par l'utilisateur :

---
Last updated: <YYYY-MM-DD HH:MM>
---

# <Plugin> Abilities Verification — <Static|Runtime> Mode

## Status: <PASS|WARN|FAIL>

## Audit doc validation (if provided)

## Static inventory

## Annotation correctness
| Ability | Claim | Result | Evidence |
|---|---|---|---|

## Permission gates

## Schema lints

## Error-code vocabulary

Chaque ability est OK, WARN, ou FAIL. Un seul FAIL → FAIL en première ligne ; des WARNs sans FAILs → WARN ; sinon PASS.

Modes de défaillance / débogage

Env non accessible (runtime) — env-up a échoué ou Docker ne tourne pas. Réexécutez wp-project-triage, puis corrigez l'env. Ne retombez pas silencieusement au statique sans le noter dans le rapport.
Aucune ability en source — retournez un rapport clair « rien à vérifier ».
Déséquilibre du schéma d'audit — pointez vers references/audit-schema-validation.md ; ne corrigez pas automatiquement l'audit.
Faux positif sur les écritures readonly — voir le mécanisme // verify-ignore dans references/annotation-correctness.md. Documentez pourquoi chaque suppression est légitime.
Énumération runtime plus petite que statique — le hook d'enregistrement ne se déclenche pas. Vérifiez le timing du hook init, l'état d'activation, l'ordre du chargeur automatique.

Escalade

Pattern légitime récurrent qui déclenche la vérification adversarielle sur plusieurs plugins → proposez de l'ajouter aux conseils de suppression dans annotation-correctness.md. N'élargissez pas la liste des patterns candidats de façon spéculative.
Le validateur de schéma d'audit rejette un audit légitime → le schéma canonique dans ../wp-abilities-audit/references/audit-schema.md a évolué. Mettez à jour references/audit-schema-validation.md pour correspondre.

Hors scope

La mesure du budget de token est un axe de vérification séparé — un ensemble d'abilities propre d'annotation, propre de schéma, passant en runtime peut quand même être non livrable si sa forme tools/list brûle le budget de contexte d'un agent. Cet axe est suivi séparément. N'agrégez pas les mesures manuelles ou externes au verdict PASS / FAIL de ce skill.

wp-abilities-verify