wp-abilities-audit

WP Abilities Audit

WordPress プラグインの REST サーフェスを標準化された監査ドキュメントとしてまとめ、意味的な目的ごとにグループ化した Abilities API 登録案を提示します。監査ドキュメントは実装者（人間、エージェント、またはその両方）向けの計画資料です。コントローラーの一覧、権限ゲート、提案するアビリティの形状を構造化された形式で記録します。このドキュメントを読むレビュアーは、調査をやり直すことなく作業範囲を定められます。

このスキルは、REST サーフェスを公開するあらゆるプラグインで利用できます。プラグインの分類（任意の plugin_family アノテーションのための分類）はユーザーが決定します。このワークフロー自体はプラグインに依存しません。

使用する場面

• 「WP プラグインに Abilities API アビリティを登録する」タスクで、監査ドキュメントがまだ存在しない場合。
• 複数のプラグインを対象とするアビリティ導入計画に参加するため、共有可能な標準化された監査資料が必要な場合。
• アビリティを実装する前に、プラグインがエージェントに対応できる状態かどうかを事前確認する場合。
• PM または実装担当者以外の人が、エンジニアリングチームに作業を依頼する前に作業範囲を定めたい場合。

必要な入力

1. プラグインのチェックアウトパス — 監査対象プラグインの作業ツリーです。
2. トリアージ出力 — まだ実行していない場合は、まず wp-project-triage を実行してください。監査では、レポートから signals.usesAbilitiesApi、versions.wordpress、project.kind を使用します。
3. 監査担当者の情報 — 監査の auditor フィールドに記録する名前とチームまたはコンテキストです。
4. 出力パス — 監査ドキュメントの保存先です。明示的な指定を優先してください。指定がない場合、プラグインの作業ツリーに書き込むのではなく、確認してください。

前提条件

• wp-project-triage が正常に実行され、プラグインが分類されていること。
• プラグインに REST コントローラーが 1 つ以上あること。列挙してコントローラーが 0 件だった場合、監査は適用されません。以下の「失敗モード」を参照してください。

手順

1. REST コントローラーを列挙する

今すぐ references/controller-enumeration.md を読んでください。標準的なレイアウトでの glob と、汎用的な代替手段である grep という、確認済みの 2 つの列挙方法と、それぞれを使用する場面について説明しています。

すべてのコントローラークラス、ファイル、REST ベース、ルートを「コントローラー一覧」表に記録します。提案するアビリティになるのが一部だけであっても、一覧にはすべてを網羅して記載してください。

2. 各コントローラーの基盤となるフィールドを抽出する

見つかった各コントローラーについて、監査スキーマで必要なフィールドを抽出します。クラス、ファイル、HTTP メソッド、ルート、ルート登録行番号、コールバック名、コールバック行番号、権限コールバック、コールバックが WP_REST_Request 引数を取るか、または引数なしであるか、戻り値の型です。

正確なフィールド一覧と proposed_abilities エントリーの形状について、今すぐ references/audit-schema.md を読んでください。継承されたコールバックでは行番号フィールドを null にできます。スキーマはこれを許可しており、任意の inherited_from フィールドと組み合わせられます。

3. 権限ゲートを確認する

各コントローラーの permission_callback を、current_user_can() の呼び出しまで（または、コントローラーが投稿タイプを基盤とする親クラスを拡張している場合は、投稿タイプの権限機構まで）たどります。

今すぐ references/capability-gate-tracing.md を読んでください。一般的な 2 つの仕組み（直接の check_permission() と、投稿タイプを基盤とする wc_rest_check_post_permissions()）と、それぞれをスキーマで表す方法について説明しています。読み取り用と書き込み用の権限ゲートが異なるかどうかを明記してください。複合ゲートは単一の文字列ではなく、{read, write} オブジェクトで表します。

4. セマンティックな意図でグループ化して能力を提案する

HTTP メソッドごとに能力を細分化しないでください。このスキルで使用するグループ化ルールは、セマンティックな意図でグループ化するヒューリスティックだけです。

今すぐ ../wp-abilities-api/references/grouping-heuristic.md を読み込んでください。ここでルールを再導出してはいけません。要約すると、現実世界の質問または状態遷移ごとに能力を 1 つ定義し、input_schema のフィルターパラメーターによって N 個のバリエーションを 1 つにまとめます。

候補を入力する前に、ユースケースの妥当性チェックを適用してください。 ../wp-abilities-api/references/domain-vs-projection.md のユースケース契約テストに従い、人またはエージェントが、サポートされているプラグインのワークフローを通じてこの動作を意図的に実行するでしょうか。はいの場合、その候補は実際の能力です。フィールドの入力に進んでください。いいえの場合、そのルートは内部の通信処理（キャッシュの無効化、スケジューラーのティック、記帳用エンドポイント、デバッグ用のイントロスペクション）です。完全性のために「Controller Inventory」セクションには残しますが、proposed_abilities には追加しないでください。ルートは一覧にする価値があっても、提案する能力は実際のユーザーまたはオペレーターの質問やアクションを表す必要があります。

妥当性チェックを通過した提案能力ごとに、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。

最後の 3 つは、実装担当者と verify-mode のツールの両方に必要な、実装準備状況に関する情報です。この能力が対応する人間またはエージェントのワークフロー（use_case_fit）、呼び出しのたびにバックエンドのパスが出力する内容（side_effects。空の配列も未入力ではなく、事実を示します）、そして公開境界を通じて能力を実行するためにテスト環境に必要な代表的なデータ（seed_data_needs）です。

5. ギャップと先送り項目を明示する

分類は 3 つです。

• excluded_from_mvp — リスク上の理由（実際の金銭を伴う書き込み、不可逆な状態変更、または前提となる設計作業）から意図的に先送りした候補です。各項目に理由を 1 文で記載します。
• surfaced_gaps — バックエンドのエンドポイントがない MVP 候補（backing: null の能力）に加え、列挙中に見つかった、MVP リストにはないものの将来の対応が容易な価値の高いエンドポイントです。
• 能力ごとのリスク — 実装担当者が対処しなければならないバックエンドエンドポイントに関する事項です（冪等性キーがない、2 フェーズの動作、状態遷移に関する注意点、permission_callback => '__return_true' で登録された引数なしのエンドポイント。この設定を能力登録にコピーしてはいけません）。

6. 監査ドキュメントを作成する

「Inputs required」で収集した明示的な出力パスに書き込みます。ドキュメントの構成は references/audit-schema.md に厳密に合わせてください。

1. Last updated: YYYY-MM-DD HH:MM ヘッダー。
2. 必須のトップレベルメタデータと proposed_abilities、excluded_from_mvp、surfaced_gaps を含む YAML ブロック。
3. 「Controller Inventory」テーブル。
4. 「Notes and Surprises」の説明セクション。

すべての項目を含む、コピーして使える最小限の例は references/audit-schema.md の「Minimal valid example」にあります。新しい監査を作成する場合は、そこから始めてください。

7. （任意）リファレンス実装能力を指定する

実装担当者が最初に実装する能力（通常は、最も小さく、安全で、効果の大きい読み取り能力）に reference_ability: true を設定します。これにより、後続のワークフローで開始地点を確定できます。

検証

• 監査ドキュメントが references/audit-schema.md に準拠していること（必須のトップレベルフィールドがすべて存在し、proposed_abilities に 1 つ以上の項目があり、すべての能力で annotations が完全に設定されていること）。
• capability_gate は、単一機能のプラグインでは文字列、投稿タイプを使用するプラグインでは {read, write} オブジェクトであること。
• backing: null の能力がすべて surfaced_gaps にも含まれていること。
• ドキュメントを audit-schema.md の「Known limitations」に記載されたバリデーターで往復処理しても、エラーが発生しないこと。

失敗パターン／デバッグ

• プラグインに REST コントローラーがない — 監査の対象外です。フック／フィルターベースの機能（このスキルの現行バージョンでは対象外）を検討するか、このプラグインでの Abilities の採用を見送ってください。
• プラグインが別のリポジトリのコントローラーを継承している（WP_REST_Posts_Controller のような、コアの投稿タイプに対応するコントローラーを拡張するプラグインや、親プラグインの REST クラスを基盤とする拡張プラグインでよく見られます） — backing.inherited_from: "<parent FQCN>" に記録してください。スキーマに従い、行番号のフィールドは null にしてかまいません。
• 複合的な権限ゲート（読み取り／書き込みで異なる権限） — references/capability-gate-tracing.md に記載されている構造化された {read, write} 形式を使ってください。単一の権限として型指定されたフィールドに、/ 区切りの文字列を入れないでください。
• グループ分けが曖昧 — ../wp-abilities-api/references/grouping-heuristic.md を参照してください。監査ドキュメントで別のグループ分けルールを作らないでください。
• permission_callback => '__return_true' を指定した引数なしのエンドポイント — REST レイヤーでは有効ですが、Ability 自体の permission_callback はプラグインのマーチャント向けゲートと一致させる必要があります。'__return_true' を Ability の登録に決して引き継がないでください。この点を Ability の risks に記載してください。
• 出力先のデフォルトがプラグインの作業ツリー — 必ずユーザーに明示的な出力先ディレクトリ（例：ユーザーの vault plans/）を尋ねてください。プラグイン自体の Git 履歴に監査結果を書き込むと、作業ツリーが汚れ、成果物が埋もれてしまいます。

エスカレーション

• プラグインで references/controller-enumeration.md に記載されていない列挙規約が使われている場合（標準の glob と grep のフォールバックのどちらでも完全な一覧を取得できない場合）は、その新しい規約をリファレンスに追加し、今後の監査で確実に検出できるよう PR を作成してください。
• 権限のトレースで references/capability-gate-tracing.md に記載されていない仕組みに遭遇した場合は、そのケースを監査の「Notes and Surprises」だけに記録するのではなく、そのファイルを拡張してください。