wp-abilities-verify

WP Abilities Verify

WordPress プラグインの Abilities API 登録を検証します。中心となるのは、敵対的アノテーション整合性チェックです。実際には書き込みを行う（$wpdb->update、update_option、GET 以外のデリゲートなど）readonly: true のアビリティは、エージェントがイントロスペクトしたアノテーションをもとにアクションを計画するため、セキュリティと UX に深刻な問題をもたらします。このスキルは、コールバック本体を読み、その動作とアノテーションの申告内容を照合することで、こうした虚偽を検出します。

このスキルは、wp-abilities-audit が作成した監査ドキュメントの検証、権限ゲートとスキーマの衛生状態のチェックも行い、必要に応じて各アビリティをライブ環境で実行します。

使用するタイミング

• プラグインにアビリティを登録した後、PR をマージする前。
• リリース済みプラグインのヘルスチェック（リファクタリングによって読み取り専用アビリティが書き込みを行うようになった場合など、リグレッションを検出します）。
• 実装者に渡す前の監査ドキュメントの検証。

2 つのモード

• 静的モード — プラグインのチェックアウトから実行します。環境は不要です。ソースコードを検査して列挙し、敵対的整合性チェック、スキーマと権限のリント、監査ドキュメントの検証を実行します。
• ランタイムモード — 起動中の環境が必要です。静的モードのすべてに加え、wp_get_abilities() による正式な列挙、厳選した入力を使った各アビリティの実行、実際のユーザーによる権限の往復確認を行います。また、idempotent: true のアビリティに対して同一アビリティの 2 回呼び出しによるヒューリスティックを実行し、レビュー候補を検出します（戻り値の一致はシグナルであり、判定ではありません。コアでは idempotent を「環境に追加の影響を与えないこと」と定義しています）。

どちらのモードでも、同じ形式の構造化レポートが生成されます。

静的モードの PASS は、「明らかに形状上の違反がない」ことを意味するだけであり、「書き込みがないことを検証済み」という意味ではありません。重要度の高いプラグインでは、マージ前にランタイムモードを実行してください。静的モードでは検出できないブートストラップ順序、権限の往復確認、冪等性に関する問題を検出できます。静的モードの盲点については、references/annotation-correctness.md を参照してください。

必要な入力

1. プラグインのチェックアウトパス — 検証する作業ツリー。
2. モード — static または runtime。指定がない場合は static を既定とします。
3. （ランタイムのみ）環境起動コマンド — プラグインの AGENTS.md を読みます。一般的なパターンは npm run wp-env start、npx wp-env start、Composer ベースの起動方法です。独自の開発ツールを使用するプラグイン群では、それぞれのコマンドが記載されています。npm run wp-env が使えると決めつけないでください。
4. （任意）監査ドキュメントのパス — 監査と登録済みアビリティの相互チェック、および監査自体の検証が有効になります。
5. レポートの出力パス — 明示的なパス。通常はユーザーのボルトを指定します。

前提条件

• プラグインに対して wp-project-triage が実行済みであること。
• プラグインのソースに登録済みアビリティが少なくとも 1 つあること。wp_register_ability( が 0 件の場合は、空の PASS ではなく、「登録済みアビリティなし」という明確なレポートを返します。

手順

1. （監査ドキュメントが指定されている場合）監査ドキュメントを検証する

references/audit-schema-validation.md を読みます。wp-abilities-audit が管理する正規スキーマに照らして監査を検証します。必須フィールドの欠落、reference_ability: true の複数指定、surfaced_gaps エントリーと対になっていない backing: null エントリーを報告します。backing: null 単独は WARN（意図的なギャップ出力）であり、FAIL ではありません。

2. アビリティを静的に列挙する

references/static-enumeration.md を読みます。各 wp_register_ability( 呼び出しを見つけ、名前、アノテーションブロック、実行コールバックの位置を抽出します。複数行対応のツール（rg --multiline --pcre2）を使用します。標準的な書式では、呼び出しが複数行に分割されています。各アビリティについて、ソースファイル、行番号、アノテーション、コールバックのバイト範囲を記録します。

3. （ランタイムのみ）REST + wp-cli で列挙する

references/runtime-harness.md を読みます。AGENTS.md に記載されたコマンドを使って環境を起動し、wp-cli 経由で wp_get_abilities() を使って列挙してから、静的インベントリと照合します。ソース側にのみ存在する場合 → FAIL（登録処理が実行されていません）。ランタイム側にのみ存在する場合 → WARN（動的な登録経路です）。

4. アノテーションの正確性（敵対的チェックの中核）

references/annotation-correctness.md を読みます。各コールバック本体を読み、アノテーションの主張と一致しているか確認します。

• readonly: true → コールバックは、データベース、options テーブル、投稿／ユーザー／ターム／コメントデータ、ファイルシステム、cron に書き込んだり、GET 以外の HTTP／REST デリゲートを介して書き込んだりしてはなりません。
• destructive: false → コールバックは削除、返金、無効化、キャンセル、ゴミ箱への移動をしてはなりません。
• idempotent: true → 同じ入力で繰り返し呼び出しても、環境に追加の影響を与えてはなりません（class-wp-ability.php 内の idempotent アノテーションの docblock に従います）。静的チェックではカウンターへの書き込みと呼び出しごとの cron スケジュールを検出します。ランタイムチェックでは、可視状態の変化に対する同一入力での2回実行ヒューリスティックを追加します。

リファレンスに記載されている一般的な書き込みパターンは出発点であり、チェックリストではありません。プラグインごとに用語が異なるため、エージェントは検証対象のプラグインに固有の動詞を追加します。

誤検出は、インラインの // verify-ignore: <annotation> -- <reason> コメントで抑制します。

5. 権限のラウンドトリップ

references/permission-roundtrip.md を読みます。静的チェックでは、各 permission_callback を6つの形式に分類します（推奨は Shape A の current_user_can(...)。Shape B-bad の WP_REST_Request パターンまたは Shape E のリテラル true は FAIL）。ランタイムチェックでは、匿名ユーザーとサブスクライバーは拒否され、管理者は許可されます（意図的に公開されている場合を除く）。監査情報が提供されている場合は、登録された権限を監査で宣言されたゲートと照合します。

6. スキーマのリント

references/schema-lints.md を読みます。各アビリティの input_schema に、6つの基本原則を適用します。オブジェクトスキーマでは additionalProperties を宣言すること、必須フィールドには説明があること、enum は空でないこと、$ref を使用しないこと、デフォルト値は静的に定数であること（(object) array() を含む）、参照アビリティには必須入力がないことです。

ランタイムでの4つの落とし穴（プロパティレベルのパスではデフォルト値が注入されない、ページネーションキーのずれ、文字列 ID に対する empty()、直接呼び出しと間接呼び出しの厳格さ）については、../wp-abilities-api/references/input-schema-gotchas.md と照合します。

7. エラーコードの語彙

../wp-abilities-api/references/error-code-vocabulary.md と照合します。各コールバックの WP_Error の戻り値を調べ、語彙に含まれないコードは WARN とします。

検証

実行すると、ユーザーが指定したパスに構造化された Markdown レポートが生成されます。

---
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

各アビリティは OK、WARN、FAIL のいずれかです。FAIL が1つでもあれば全体のステータスは FAIL、FAIL がなく WARN があれば WARN、それ以外は PASS です。

失敗の種類／デバッグ

• 環境に到達できない（ランタイム） — env-up が失敗したか、Docker が実行されていません。wp-project-triage を再実行してから、環境を修正します。レポートにその旨を記載せず、静的チェックに暗黙に切り替えてはなりません。
• ソースにアビリティがない —「検証対象なし」と明確に示すレポートを返します。
• 監査スキーマの不一致 — references/audit-schema-validation.md を参照し、監査データを自動修正してはなりません。
• readonly-writes の誤検出 — references/annotation-correctness.md の // verify-ignore の仕組みを参照します。各抑制が妥当な理由を記録します。
• ランタイムで列挙された数が静的チェックより少ない — 登録フックが実行されていません。init フックのタイミング、有効化状態、オートローダーの順序を確認します。

エスカレーション

• 複数のプラグインで敵対的チェックに抵触する、繰り返し現れる正当なパターン → annotation-correctness.md の抑制ガイダンスへの追加を提案します。推測に基づいて候補パターンの一覧を広げてはなりません。
• 監査スキーマバリデーターが正当な監査を拒否する → 正式なスキーマである ../wp-abilities-audit/references/audit-schema.md が更新されています。references/audit-schema-validation.md をそれに合わせて更新します。

対象外

トークンバジェットの測定は別の検証軸です。アノテーションとスキーマがクリーンで、ランタイムチェックに合格するアビリティセットでも、tools/list 形式がエージェントのコンテキストバジェットを使い切る場合は、リリースできないことがあります。この検証軸は別途追跡します。手動または外部の測定結果を、このスキルの PASS／FAIL 判定に集約してはなりません。