abilities-api-implement

Abilities API の実装 — WooCommerce 拡張機能のプレイブック

このスキルは、WooCommerce 拡張機能を「Abilities が未登録」の状態から「ドラフト PR を作成し、Ability の公開範囲を検証済み」の状態まで、一度の実行で進めます。上流の wp-abilities-audit が作成した監査ドキュメントを使用し、登録処理の骨組みの作成、Ability ごとに 1 つのコミットの作成、統合ハーネスの実行、PR の作成という各フェーズを進めます。

引き継ぎは厳格です。有効な監査ドキュメントが必要で、見つからない場合や解析できない場合はエラーで終了します。

上流スキルとの関係

このプレイブックの汎用的な部分は、WordPress/agent-skills にあります。

上流スキル	担当内容
wp-abilities-audit	このスキルが使用する監査ドキュメントを作成します。プラグインファミリーの検出、グループ化のヒューリスティック、監査スキーマを担当します。
wp-abilities-api	汎用的なパターンを提供します。委譲ヘルパーパターン、エラーコードの用語体系、入力スキーマに関する注意点（ページネーションキーの不一致、スキーマのデフォルト値）、プラグインファミリーのパターンを含みます。
wp-abilities-verify	統合ハーネスを提供します。wp-env の列挙、アノテーション、実行、権限ゲートのチェック、監査スキーマの検証を担当します。

このスキルは、その上に重ねる WooCommerce 拡張機能レイヤーを担当します。

• WooCommerce 拡張機能の名前空間、自動読み込みの構成、テスト用の基底クラス、ブートストラップのエントリーポイントに合わせて、登録処理の骨組みを作成します。WooCommerce 以外のプラグインファミリー（Jetpack ファミリー、一般的な WordPress プラグイン）は、このプレイブックの対象外です。ホストプロジェクト独自の規約に従い、上流の wp-abilities-api スキル（WordPress/agent-skills）を直接使用してください。
• WooCommerce 拡張機能のプリミティブを扱います。名前空間のルール、MCP への公開方法の選択、共通の woocommerce カテゴリーの規約、woocommerce_ability_definition_classes ローダーの経路、必須の meta.mcp.public / meta.mcp.type のデフォルト値を含みます。
• レビューを容易にするため、Ability ごとにアトミックなコミットを 1 つ作成する規約です。
• 対象リポジトリ独自の .github/pull_request_template.md を尊重し、記入する Ability 固有のセクションを用意する PR テンプレートです。
• 骨組みの作成時に繰り返し発生している問題（権限ゲートの不一致、プラグインファミリーの不一致、バックエンドのコントローラーの欠落）を検出する監査の前提条件チェックを行います。

概要

監査ドキュメントを基に、このスキルは次のものを作成します。

1. 拡張機能のソースツリーに、新しい Abilities_Registrar クラスを作成します。
2. 登録する Ability ごとにアトミックなコミットを 1 つ作成します（まず参照用 Ability、次に読み取り、最後に書き込み）。
3. 構造、権限、実行パスのアサーションを網羅する単体テストを作成します。
4. 統合ハーネスの実行結果を Markdown アーティファクトとして記録します。
5. 拡張機能のリポジトリに対する PR をオープンします。

このスキルはプッシュと PR の作成までで終了します。課題トラッカーやチャットへの投稿は行いません。部分的な実行からの再開も試みません。実行途中で問題が発生した場合は、問題の起きたフェーズを手動で修正して再実行してください。

ローダーのみ — 前提としてよいこと

このスキルは、WC 10.9 の AbilityDefinition と woocommerce_ability_definition_classes ローダーの構成を作成します。WC < 10.9 を実行しているストアでは、登録処理は何もせずに終了します。ポリフィルも、代替の登録経路もありません。構造上のゲートは \Automattic\WooCommerce\Internal\Abilities\AbilitiesLoader に対する class_exists() チェックです。段階的な導入時のセーフティネットとして、プラグインごとの <plugin_slug>_abilities_enabled フィーチャーフラグを使用します。

骨組みを作成する前に references/wc-1009-dependency.md を読んでください。ポリフィルを提供しない理由、Domain クラスを WC < 10.9 のストアに含めても安全である理由となる遅延オートロードの特性、テスト環境への影響（WC < 10.9 の CI マトリックスでは markTestSkipped により問題なくスキップされる）を説明しています。

使用方法

拡張機能の作業ツリー内から実行します。

/woocommerce:abilities-api-implement <path-to-audit-doc>

引数を渡さない場合、このスキルは plans/（vault または拡張機能のローカル）内で、最新の *abilities-audit*.md を自動検出します。

前提条件 — 監査ドキュメントが有効であること

スキャフォールディングを始める前に、wp-abilities-audit が作成した監査ドキュメントを検証してください。

前提条件チェックリストについて、今すぐ references/audit-precondition.md を読んでください。この検証は、wp-abilities-verify の標準監査スキーマバリデーターを置き換えるものではなく、それに加えて実施するものです。WordPress/agent-skills の wp-abilities-verify スキルがインストールされている場合は、標準スキーマチェックについて wp-abilities-verify/references/audit-schema-validation.md も読んでください。まず標準スキーマチェックを実行し、その後 audit-precondition.md に記載された Woo 拡張機能固有のチェックを実行してください。

前提条件チェックに失敗した場合は、そこで中止してください。部分的なスキャフォールディングも行わないでください。

実行計画

実装は6つのフェーズで進めます。各フェーズの最後に、1つ以上のアトミックコミットを作成します。

フェーズ I — コーディネーターと Domain フォルダーのスキャフォールディング

以下を作成します。

• Abilities_Registrar コーディネーター — 機能フラグゲートと WC 10.9 ローダーゲートを備えた init()、空の ABILITY_CLASSES 定数、append_classes() フィルターコールバック、CATEGORY_SLUG = 'woocommerce' 定数、および <CanCapHelper>() 権限ヘルパーを実装します。コーディネーターはカテゴリを登録しません。woocommerce スラッグは Woo Core が所有します（woo-extension-primitives.md §5 を参照）。
• Domain/Abstract<Plugin>Ability — CATEGORY_SLUG 定数（レジストラーのものと同じ値）と delegate_to_rest_controller()（フェーズ III の Shape-2 読み取りで使用）を実装します。サーフェスにリスト形式のアビリティがあるとすでに分かっている場合は、paginated-output-envelope.md のページネーションヘルパーも今追加してください。そうでなければ、最初のリスト形式の Domain クラスを追加するときまで保留できます。
• フェーズ I のテスト — 6つのケース：機能フラグがオフの場合の早期終了、ローダーがない場合の早期終了、ローダーがある場合のフィルター接続、append_classes() の往復、権限ヘルパー、そして $initialized 静的ガード下での init() の冪等性。

拡張機能のブートストラップで Abilities_Registrar::init() を呼び出すようにします。

機能フラグゲート。 レジストラーの init() は、<plugin_slug>_abilities_enabled フィルターが false を返す場合（ロールアウト中のデフォルト）に、処理を早期終了しなければなりません。これにより、最終的なアビリティの形を確定する前に、登録用のスキャフォールディングをリリースできます。このフィルターはサイトごとのオプトインです。サーフェスが安定したら、デフォルトを true に変更してください。

今すぐ references/registrar-template.md を読んでください。WooCommerce 拡張機能向けのクラステンプレート、テスト基底クラスのルール、機能フラグのパターン、ブートストラップの接続箇所が記載されています。このファイルが応用する汎用的な仕組み（呼び出し形式のパターン、委譲ヘルパーのシグネチャ、エラーコードの語彙）については、（そのスキルがインストールされている場合）まず wp-abilities-api の references/plugin-family-patterns.md、references/delegate-helper-pattern.md、references/error-code-vocabulary.md を読んでください。

ローダーゲートの理由について、今すぐ references/wc-1009-dependency.md を読んでください。コーディネーターの woo_abilities_loader_available() チェックが構造上のゲートである理由（機能フラグはロールアウト時の安全策にすぎません）、ABILITY_CLASSES 内の ::class 定数が WC < 10.9 で Domain クラスをオートロードしない理由、後続フェーズのアビリティごとのテストで markTestSkipped パターンを使用する理由が記載されています。

今すぐ references/woo-extension-primitives.md を読んでください。このドキュメントには、監査ドキュメントだけでは定義できない WooCommerce 拡張機能向けのルールがまとめられています。アビリティの名前空間、woocommerce_ability_definition_classes ローダー、非推奨の MCP エンドポイントを公開するかどうかの選択、必須メタデータのデフォルト、共有の woocommerce カテゴリ規約（§5。プラグインスラッグをカテゴリにするアンチパターンと、再登録しないルールを含む）です。これらのルールは、フェーズ II～IV で登録するすべてのアビリティに適用されます。

コミット形式： feat(abilities): scaffold Abilities_Registrar coordinator + Domain base

フェーズ II — 最初のアビリティを登録する（参照パターン）

最もシンプルで安全な読み取りを選びます。通常は、WP_REST_Request の構築が不要な、引数なしの「get -summary」または「get -statuses」形式のアビリティです。このコミットでは、残りのアビリティが踏襲する Domain クラスの参照パターンを確立します。各アビリティにつき Domain/<Name>.php ファイルを 1 つ用意し、get_name()／get_registration_args()／execute() の静的メソッドを備えた AbilityDefinition を実装して、Abilities_Registrar::ABILITY_CLASSES に登録します。

今すぐ references/first-ability-template.md を読んでください — 登録ヘルパー、防御的ガードを備えた execute コールバック、二重状態の戻り値の処理、そして必須の 2 つのテスト（構造 + 権限）について説明しています。

代替のバックエンドコントローラー： このアビリティに関する監査の Notes に、代替のバックエンドコントローラー（例：管理者名前空間のコントローラーと、出力形式が異なるレポート名前空間のコントローラー）が記載されている場合は、スキャフォールディングを行う前に一時停止し、ユーザーに確認してください。

コミット形式： feat(abilities): add <plugin-slug>/<ability-name> ability。

フェーズ III — 残りの読み取りを登録する

アビリティ #2 が追加されたら、ヘルパーを抽出する前に、残りの読み取りそれぞれに適切なパスを選びます。

Woo 拡張オーバーレイでの形式の優先順位：

形式	パターン	使用する場面
3 — 共有サービス	アビリティ + REST + UI がすべて共有サービスクラス（<PluginNamespace>\Internal\Service\<Thing>_Service — \Internal\Abilities 名前空間の兄弟であり、子ではありません）を呼び出す	デフォルトです。 書き込みでは必須です（フェーズ IV）。読み取りでもデフォルトです。共有ドメイン／サービスヘルパーは、UI と REST コントローラーがすでに使用しているものと同じコードパスを利用し、アビリティ層がエージェント向けに出力を整えます。
2 — REST に委譲	アビリティが WP_REST_Request を構築し、delegate_to_rest_controller ヘルパーを介して rest_do_request() を呼び出す	明示的にレビューされた場合に限る例外手段として、低リスクの読み取りに使用できます。バックエンドコントローラーが副作用を一切持たず、REST ハンドラーがアビリティにそのまま引き継がれるトランスポート由来の要素（エンベロープ形式、_links、埋め込みハイパーメディア、ヘッダー由来のフィールド）を追加せず、さらに、コントローラーが依存するリクエストコンテキストヘルパー（current_user_can の経路、is_admin()、did_action、ヘッダーに基づく動作）が REST リクエストのライフサイクル外でも同じように動作すると確認できた場合に限り、許容されます。
1 — 再実装	アビリティが独自の SQL／検証を持つ	避けてください。 ドリフトは避けられません。

Woo 拡張で形式 3 をデフォルトにする理由（「推奨」ではありません）：

• REST 出力にはトランスポート由来の要素が含まれます。 コントローラーは HTTP 向けに出力を整えます。エンベロープキー、_links、埋め込みハイパーメディア、次／前ページへのリンクなどです。アビリティ層が必要とするのは、トランスポート形式ではなく、整理されたペイロードです。形式 3 なら、アビリティはドメインヘルパーを呼び出し、エージェント向けの形式を自ら組み立てられます。
• リクエストコンテキストヘルパーは REST の外では動作が異なります。 nonce 検証の背後にある current_user_can チェック、is_admin() の分岐、did_action('rest_api_init') ガード、ヘッダーに基づく権限解決は、REST では通常通りますが、CLI／cron／エージェント呼び出しでは失敗します。形式 2 では、これらすべてを気づかないまま引き継ぎます。
• メトリクスの落とし穴。 バックエンドコントローラーは、分析イベントを出力したり、WP フックを実行したり、通知を配信したりすることがよくあります。エージェントによる形式 2 の呼び出しはすべてカウンターを汚染し、ダッシュボード上で「人間がこのエンドポイントにアクセスした」ように見えてしまいます。形式 3 なら、アビリティはドメインヘルパーを直接呼び出し、独自のアビリティタグ付き副作用を出力する（または出力しない）ことができます。
• REST の初回ブートストラップコスト。 rest_do_request() は rest_get_server() を呼び出し、WP_REST_Server を遅延インスタンス化して、リクエストごとに一度 rest_api_init を実行します。REST リクエストのライフサイクル内ではコストが償却されますが、その外（CLI、cron、非 REST MCP トランスポート、エージェントのワークフロー）では、最初の委譲アビリティ呼び出しがブートストラップの全コストを負担します。

スキャフォールディング時の判断順序：

1. この操作を行うドメイン／サービス用ヘルパーはすでにありますか？ → 形状 3 を選び、呼び出します。
2. 監査の side_effects フィールドに、空でない項目（テレメトリーフック、監査ログ、通知、キャッシュへの書き込み、ロックの取得）が記載されていますか？ → 形状 3 を選び、既存のサービスがなければサービスを抽出します。
3. その機能は主に REST 以外から呼び出されますか？ → 形状 3 を選びます。
4. REST ハンドラーがトランスポート関連の成果物を出力する、またはリクエストコンテキスト用ヘルパーに依存していますか（上記の「形状 3 がデフォルトである理由」を参照）？ → 形状 3 を選びます。
5. 上記のいずれにも該当せず、読み取りが本当に低リスクの場合 → 形状 2 を、明示的にレビューされた例外として使用してもかまいません。トレードオフと、確認済みの前提条件を PR の「レビュー担当者へのメモ」に記載してください。

ローダーのみのパターンで形状 2 を使う場合、delegate_to_rest_controller() は Abstract<Plugin>Ability（ローカルの抽象基底クラス。registrar-template.md を参照）の protected static メソッドです。ドメインクラスからは self::delegate_to_rest_controller(...) として呼び出します。

形状 2 の正規のヘルパー実装、シグネチャ、2 種類のレスポンス形式の展開、および引数なしの能力に関する 2 つの例外ルールは、上流にあります。

WordPress/agent-skills の wp-abilities-api スキルがインストールされている場合は、今すぐその references/delegate-helper-pattern.md を読んでください。 それ以外の場合は、references/registrar-template.md のテンプレートに、WP_REST_Request を構築して rest_do_request() を呼び出し、WP_REST_Response と生の配列の両方の戻り値形式を展開する、自己完結型のヘルパーが含まれています。

ページネーションパラメーターについては、バックエンドのコントローラーによって異なるキー（per_page ではなく pagesize など）が使われることがあります。

wp-abilities-api スキルがインストールされている場合は、今すぐその references/input-schema-gotchas.md を読んでください（セクション：ページネーションキーの不一致）。 それ以外の場合の検出方法は、バックエンドコントローラーの get_collection_params()（または同等のメソッド）を検索し、pagesize、page_size、または per_page 以外のページネーションキーを確認することです。標準外のキーを能力の入力スキーマに持ち込むのではなく、能力の境界で変換してください。

コミットの形式：

• サービスの抽出（形状 3）：refactor(<plugin>): extract <Thing>_Service for shared business logic。
• ヘルパーの抽出（形状 2）：refactor(abilities): extract delegate_to_rest_controller helper。
• 各能力：feat(abilities): add <plugin-slug>/<ability-name> ability。

フェーズ IV — 書き込みの登録

監査で書き込み機能が見つかった場合は、すべての読み取り機能を追加してから実装します。**最初のバッチはデフォルトで読み取り専用です。**書き込み機能を追加すると、エージェントが利用できる操作の範囲が広がります。以下の手順を守れば、バッチの足場作りによって意図せず範囲が広がるのを防げます。

明示的な書き込みゲート — 書き込み機能を追加する前に、以下の4項目すべてを確認してください。

1. **動作。**その操作が実際の状態遷移であること（ターミナルのクローズ、返金、無効化、下流への影響を伴うステータス変更など）。POSTに見せかけた状態変更を伴うGETや、読み取りを装ったセッターではありません。監査ドキュメントの intent フィールドと use_case_fit フィールドに照らし合わせて確認します。
2. **権限ゲート。**監査の permission.source に記録された正規のソース（RESTコントローラーの permission_callback だけではなく、ドメイン／サービス／管理操作のレイヤー）で権限が適用されていること。その機能の permission_callback は、RESTコールバックを反射的に使うのではなく、この正規のソースを参照します。上流の情報は wp-abilities-audit/references/capability-gate-tracing.md と相互参照してください。
3. **サービスパス。**フェーズ III の表にあるシェイプ3が必須です。その操作を担う共通サービスクラスが存在するか、またはこの書き込み機能のコミットより前に適用される refactor() コミットで抽出されている必要があります。
4. **アノテーション。**各値は、読み取り機能からコピーしたものではなく、実際の動作を反映していること。readonly: false、destructive: <true|false> を明示し、idempotent: <true|false> も明示します。検証スキルの敵対的チェックで虚偽は見つかります。最初から正直に設定するほうが適切です。

確認の過程で4項目のいずれかに不明点が生じた場合は、推測せずに書き込みを保留してください。書き込みは、雑な実装が最も大きな損害をもたらす領域です。

今すぐ references/write-ability-template.md を読んでください。書き込み機能のドメインクラスの構造（シェイプ3が必須です。共通サービスを使い、引数にHTTPメソッドを渡しません。書き込みには抽象基底クラスの delegate_to_rest_controller() を決して使わないでください）、必須入力のバリデーションパターン、スキーマのデフォルト値に関する落とし穴について説明しています。移植可能な入力スキーマとスキーマのデフォルト値に関する落とし穴については、インストール済みの場合、wp-abilities-api の references/input-schema-gotchas.md も相互参照してください。

コミット形式： feat(abilities): add <plugin-slug>/<ability-name> ability。

フェーズ V — 統合ハーネス

wp-env を起動し、機能を列挙して、アノテーションを検証し、読み取りを実行し、書き込みの入力バリデーションを確認して、権限ゲートを確認します。出力をPR用のMarkdown成果物として保存します。

**検証レベルは2段階です。**スモークレベルでは、ブートストラップの問題や重大なエラーの回帰を検出します。高信頼度レベルでは、本番環境で各機能が扱うデータ形状を使って検証します。どちらもレジストラーの静的メソッドではなく、公開されている機能境界（wp_get_ability( $name )->execute( $input )）を経由します。

• **レベル1 — スモーク実行（合成入力）。**各読み取り機能が OK またはボキャブラリーの WP_Error を返すことを確認します。各書き込み機能が、入力不足に対して ability_invalid_input またはプラグイン固有の <plugin_slug>_missing_<field> コードを返すことを確認します。PHPの致命的エラー、サービスのブートストラップ漏れ、登録の失敗、書き込みの入力バリデーション漏れを検出します。
• **レベル2 — 高信頼度検証（代表的なシードデータ）。**監査ドキュメントで seed_data_needs がnull以外とされている各機能で、実施を推奨します。そのフィールドに合わせて現実的なプラグインデータをシードし、代表的な入力（合成プレースホルダーではなく、実際のIDやスラッグ）で機能を呼び出して、（a）ドキュメントに記載された出力形状、（b）プライバシー契約（機能が提供を約束していない機密フィールドが含まれないこと）、（c）実際のレコードに対する権限の動作（匿名ユーザーは拒否、購読者は拒否、想定されたロールは許可）を検証します。レベル2では、誤ったIDで別のレコードが返される問題、キャッシュされたセンチネルが返される問題、合成IDでは通過するが実IDでは通過しない権限ゲート、フィルター適用済みと未適用のラベルのずれ、機能が継承したコントローラーのフィールドに起因するキュレーション済み出力のずれを検出できます。 ある機能の seed_data_needs: null の場合、レベル 2 は pending (ask the implementer) と報告して先に進みます。これは、監査スキーマの実装準備状況フィールドを WARN とし、FAIL にしない方針と合致します。

WordPress/agent-skills の wp-abilities-verify スキルを使用してください。これは、移植可能で信頼できる統合ハーネスです。references/runtime-harness.md の Check 3 が、レベル 1 とレベル 2 の正式な区分を定めています。その他のチェックでは、アノテーションの正確性、権限のラウンドトリップ、スキーマのリント、読み取り専用なのに書き込みを行う処理の検出を確認します。このスキルは、この PR テンプレートに表示される形式の成果物を生成します。

重要なゲート — 読み取り専用なのに書き込みを行う処理の検出。 監査対象の readonly: true の機能はすべて、検証スキルの敵対的な annotation-correctness チェックで問題なしと判定される必要があります（wp-abilities-verify/references/annotation-correctness.md を参照）。readonly: true を宣言しながら $wpdb->update、update_option、wp_insert_* を呼び出す、または GET 以外の HTTP メソッドを使って処理を委譲する機能は、ユニットテストでは検出できない種類のバグです。モックは実際の書き込み処理とまったく同じように見えるためです。この検出で問題なしとならなければ、PASS は認められません。 検出で機能に問題が見つかった場合は、アノテーションを修正する（readonly: false に設定する）か、コールバックを真に読み取り専用になるよう修正してください。

wp-abilities-verify がインストールされていない場合は、手動ハーネスを実行してください。wp eval 'print_r( array_keys( wp_get_abilities() ) );' で機能を列挙し、アノテーションをスポットチェックして、WP-CLI で動作を実行し、コマンドと出力の両方を成果物ファイルに記録します。

統合ハーネスは、一度限りの PR 成果物としてだけでなく、プラグイン自体のテストスイートにも含めてください。 wp-abilities-verify の実行結果は PR に添付する成果物を生成します。一方、プラグイン内の PHPUnit テストは、その後のすべての CI 実行で公開コントラクトを検証します。今すぐ references/test-the-public-contract.md を読んでください。プラグイン内のテストで、wp_get_ability() を通じて必ずアサートすべき 6 つのコントラクトの観点（権限、入力、アノテーション、厳選された出力、プライバシー、実行動作）について説明されています。レジストラーの静的メソッドを直接呼び出してテストしてはいけません。

成果物： plans/<YYYY-MM-DD>-<plugin-slug>-abilities-harness-output.md。

コミットの構成： ハーネスでバグが見つかった場合は、小さな単独コミットで修正してください（例：fix(abilities): ...）。ハーネス出力ファイル自体は拡張機能のリポジトリにコミットしません。ユーザーの plans ディレクトリに置き、PR の本文から参照します。

フェーズ V.5 — トークンコストを測定する

すべての機能セットには、トークンコストの数値を含める必要があります。暫定予算は、MCP の tools/list でプラグインあたり約 2,000 トークンです。

wp-abilities-measure スキルがインストールされている場合は、 登録直後の機能セットに対して実行し、次の 2 つの数値を記録してください。

• プラグインの <plugin-slug>/* 名前空間における tools/list のトークンコスト（拡張機能の ability-ID プレフィックスを共有するすべての機能。woo-extension-primitives.md §1 を参照）。
• 機能あたりの平均値。

予算のゲート。 プラグインの tools/list が約 2,000 トークンを超える場合：

1. PR を作成する前に一時停止してください。プラグインの機能が多すぎます。
2. 適切な再設計の軸は投影レイヤーです（例：機能を MCP に公開する方法を STRAP／ファサード／ネスト型ディスカバリーの構成に切り替える）。登録レイヤーではありません。測定によってどの構成が適切かわかる前に登録を先に組み替えると、粒度の決定が固定されてしまいます。
3. 投影レイヤーの再設計後に再測定してください。それでも予算を超える場合は、より小さな MVP をリリースし、機能を後回しにするべきだという兆候です。

wp-abilities-measure がインストールされていない場合の代替手順。 手動で概算してください。wp eval を使ってプラグインの tools/list ペイロードを JSON として出力し、任意のトークナイザーでトークン数を数えます。測定の下限についてレビュー担当者が把握できるよう、PR の本文ではこの数値を暫定値として記載してください。

トークンコストの数値は、PR 本文の「Coverage numbers」セクションに必ず記載してください。

フェーズ VI — プッシュして PR を作成する

拡張機能のデフォルトブランチを対象に PR を作成します。

今すぐ references/pr-template.md を読んでください。ここには、パラメーター化された PR 本文テンプレートに加え、拡張機能リポジトリ独自の .github/pull_request_template.md を先に読み、上書きせずに必須セクションを記入するルールが記載されています。

フェーズ VI.1 — AGENTS.md のドリフト防止ガードを追加する

拡張機能の AGENTS.md に、次の一文を追加します（既存の「この領域での作業」または「X を変更する場合」セクションの下に追加します。そのようなセクションがない場合は作成します）。

登録済みの能力の背後にあるコードパスを変更するときは、登録内容に更新が必要か（アノテーション、スキーマ、説明）を確認してください。

これは、能力とそのバックエンドサービス／REST コントローラー間で気づかないうちにずれが生じるのを防ぐ、低コストの人手によるループ防止策です。次の内容を独立したコミットとして取り込みます。

chore(agents): note ability-registration audit when changing controller code

曖昧さへの対処 — 作業を一時停止する条件

次の場合は、続行する前に一時停止してユーザーに確認してください。

• 監査結果の proposed_abilities に backing: null のエントリーがある。
• 提案された能力の Notes に、代替バックエンドコントローラーへの言及がある。
• 監査結果の plugin_family が、CWD から自動検出されたファミリーと異なる。
• 監査結果に記載された capability gate が、スキャフォールド時に再読み込みしたベース REST コントローラーの解決結果と異なる。
• 監査結果の route_registration_line／callback_line のヒントから、現在のブランチで一致する (class, callback_name) の組み合わせを特定できない（ヒントは古くなっている可能性があります。再 grep の結果を正とします）。

このリストの各項目では、オペレーターの判断を仰ぐために作業を一時停止します。安全に自動解決する方法はありません。

エラーコードの用語集

実行コールバックが返すすべての WP_Error では、エージェントが文字列照合に依存せず再試行ロジックを構築できるよう、標準化された用語集に沿ったコードを使用する必要があります。用語集は上流で定義されています。

WordPress/agent-skills の wp-abilities-api スキルがインストールされている場合は、今すぐその references/error-code-vocabulary.md を読んでください。 それ以外の場合、このスキルのテンプレートで使用される最小限のエラーコードは次のとおりです。

• <plugin_slug>_invalid_input — 入力が検証に失敗しました（Abilities API 独自の ability_invalid_input に対応します）。
• <plugin_slug>_missing_<field> — スキーマ検証なしでコールバックが実行された際に、特定の必須フィールドが不足していました（例：直接呼び出された場合）。
• <plugin_slug>_not_found — 参照先のリソース（注文、商品など）が存在しませんでした。
• <plugin_slug>_permission_denied — permission_callback を通過した後に capability チェックに失敗しました（まれなケースです。通常は、コールバックが再確認するデータ依存の権限ゲートがあることを示します）。

拡張機能で既に使用されている WP_Error コードの規約とテキストドメインに合わせてください。拡張機能の別の箇所ですでに <plugin_slug>_rest_* または woocommerce_<ext>_rest_* コードを使用している場合は、新しい名前空間を作らず、そのプレフィックスに合わせてください。

完了条件

完了を宣言する前に、次のチェックリストを確認してください。

• すべてのコミットがアトミックである（1 ファイルにつき 1 コミットにする必要はありませんが、1 コミットにつき論理的な変更は 1 つです）。
• 登録された各能力に、それぞれ独自の機能コミットがある。
• 拡張機能独自のテストコマンド（拡張機能の AGENTS.md または composer.json／package.json のスクリプトを参照）で、ローカルのユニットテストがすべて成功する。
• 新規ファイルに対する PHPCS（または拡張機能の lint コマンド）に合格する。
• 統合ハーネスの出力が plans/<YYYY-MM-DD>-<plugin-slug>-abilities-harness-output.md に保存されている（インストールされている場合は wp-abilities-verify を使用し、そうでない場合は手動の代替手順を使用）。
• PR 本文に、拡張機能独自の .github/pull_request_template.md が必須とするセクションが記入されている。
• PR が作成され、ターミナルの出力にリンクが表示されている。

チェックリストに問題がなければ、PR の URL をユーザーに報告してください。