gradle-run

Gradle の実行

基本原則

Gradle の出力全体は、一時的かつ機密性の高い成果物として扱います。エージェントが開始するすべての Gradle コマンドは、コンパクト出力ラッパーを経由して実行します。ビルドログ全体をストリーミングしたり、tee で出力したり、貼り付けたり、再度開いたりしてはいけません。

create、run、status、finish の各呼び出しは、そのツール呼び出しにおけるシェルコマンド全体でなければなりません。Gradle が正常終了した場合でも、プレフィックス、代入、条件分岐、パイプ、コマンドの連結、後続の調査を含めると、ライフサイクルの証拠は無効になります。

手順

1. リクエストを分類します。変更されていないソースと入力で質問に回答できる場合は、現在の成功結果を再利用します。別の変更を検証することが主目的ではない限定的なタスクは付随的な作業です。ビルド、チェック、警告、失敗への対応は、Gradle 中心のワークフローです。

2. このスキルのディレクトリを特定します。python3 または scripts/gradle_run.py が利用できない場合（単独の create が失敗すれば判明します）は、そこで停止して前提条件を報告します。代替手段として Gradle を直接実行してはいけません。プロジェクトで指定されたエントリーポイント（通常は ./gradlew）をそのまま呼び出します。内容を読んで独自に判断したり、別のランチャースクリプトに置き換えたりしてはいけません。

3. 最初のコマンドを実行する前にワークフローを 1 つ作成し、その不透明な ID を保持します。

   python3 <skill-dir>/scripts/gradle_run.py create
   

   create、各 run、finish は、それぞれ単独のシェルコマンドとして実行します。ls、test、変数設定、git、rg、&&、;、パイプ、または別のコマンドを含む改行と結合してはいけません。create が失敗した場合は、run を実行する前に、新しい単独の create を再試行します。ラッパーのみを使用します。コンソールの動作が選択されている場合、またはユーザーが --scan を許可している場合を除き、ラッパーは --console=plain と --no-scan を指定します。警告の調査または明示的な要求がある場合に限り、--warning-mode all を追加します。run または finish が workflow is busy を報告した場合は、ステータスを確認し、所有者の処理が終わるまで待ちます。実行の所有者は 1 つに保ち、重複ビルドを避けてください。

   ツールセッションが失われた場合、または実行結果が不明な場合は、同じワークフロー ID を使用します（グローバルな --root が指定されている場合は、それも同じものを使用します）。

   python3 <skill-dir>/scripts/gradle_run.py status --workflow <id>
   

   ステータスの確認は読み取り専用で、最大 16 KiB の JSON を即座に返します。run は、シーケンス番号、ラッパー／子プロセスの PID、開始時刻、作業ディレクトリ、コマンド、質問によって、実行中または最新の実行を特定します。result は、result_sequence によって特定される、保存済みの最新の上限付き実行結果の要約です。新しい実行中は、前回の実行を示す場合があります。ステータス確認でログが開かれることはありません。状態が running の間はステータスを繰り返し確認します。その実行に固有のロックが保持されていることは、処理中である証拠になります。一方、PID は識別情報にすぎません。無関係なワークフローのロック競合がある場合、放棄された実行は uncertain のままです。completed にはビルド失敗や起動エラーも含まれるため、result.exit_status を確認してください。interrupted には、記録されたシグナルが必要です。uncertain は、放棄された実行記録、ロックの欠落、不完全または旧形式の台帳、十分な証拠のない遷移を示します。その不確実性を報告してください。次の対応は所有権の調査です。PID から完了を推測すること、再実行すること（条件付きまたは後続の実行も含む）、クリーンアップ、finish、プロセスの終了を行ってはいけません。新しいワークフローは idle です。finish の後は finished となり、その結果は削除されます。不明な ID はすべて拒否されます。必要な結果を取得した後にのみ finish を実行してください。

4. 付随的な検証では現在のエージェントにとどまり、空でない検証上の質問に答えられる範囲で、最も限定的なタスクを実行します。

   python3 <skill-dir>/scripts/gradle_run.py run \
     --workflow <id> --scope targeted \
     --question "Does :module:test pass after this change?" -- \
     ./gradlew :module:test
   

   要求されたフィクスチャテストの代わりにコンパイルを実行したり、テストが見つからない可能性があるという理由で要求された実行を省略したりしないでください。実行し、その注意点を報告してください。 範囲が限定された JSON サマリーのみを読み取り、管理対象のラッパーとネストされた Gradle タスク、質問、および範囲が限定された回答の両方を報告してください。

5. Gradle を中心とする作業では、診断、リポジトリの編集、ラッパーの実行は、原則として現在の実装担当者が行います。有用な独立分析が得られる場合に限り、範囲を限定した読み取り専用の調査を委任してください。共有の選定と引き継ぎのリファレンスを使用して、任意のヘルパーを選定し、作業内容を伝えてください。 ラッパーの実行担当者は常に1人にしてください。ヘルパーは証拠と推奨事項をその担当者に報告します。ヘルパーを利用できない場合は、そのまま作業を続けてください。

6. 実行可能なサマリーを再利用し、警告や失敗はフィンガープリントごとにまとめてください。証拠にはソースと行を示し、次のコマンドは必要最小限のものを返してください。対象を絞った証拠では答えられない集約的な質問に限り、広範な実行を行ってください。主要なソース／コンパイラのフィンガープリントが繰り返された場合は、再ビルドを停止してください。診断を改める前に、示されたソース行と、その近くにある宣言、インポート、またはレシーバーのコンテキストを調べてください。ソースを変更したら、同じラッパーと適用可能な最小範囲のタスクで検証してください。最終診断では、次のアクションとして対象を絞った調査を明記してください。それより前にソースを修正したと主張してはいけません。新しい質問であっても、根拠のない再実行は認められません。質問の文言を変えても、変更のないタスクを再実行するのは依然として繰り返しです。

7. サマリーや台帳で一般的な認証情報が伏せられていても、完全なログは機微情報を含む生データとして扱ってください。モデルが参照できるコンテキストに表示してはいけません。中断時は、ラッパーが記録したシグナルと、範囲が限定された部分診断を使用してください。プロセスグループ／プロセスツリーのクリーンアップと永続的な台帳の更新はラッパーが担当します。範囲が限定された直近の実行台帳に残っているログだけが利用できます。範囲が限定された結果で、Gradle の起動前にキャッシュへのアクセスが拒否されたと報告された場合は、正確なパスを示し、その既存のキャッシュディレクトリに対する明示的な書き込み可能ルートのエントリーのみを、ユーザーが許可できるよう推奨してください。そこで停止してください。適用したり、その後の再実行を計画したり、finish や新しいワークフローを実行したり、サンドボックスを無効にしたり、キャッシュを移動したりしてはいけません。

8. 最後に要求された検証（対象を絞ったもの、または広範なもの）が成功したら終了してください。成功しない場合は、未解決のフィンガープリントと、検証を続行できない理由を報告してください。最終回答では、空でない --question をそれぞれ引用し、その範囲が限定された回答を示してください。コマンド履歴は証拠の報告の代わりにはなりません。その後、次を実行してください。

   python3 <skill-dir>/scripts/gradle_run.py finish --workflow <id>
   

   finish がラッパー所有のログのみを削除したことを報告してください。既知のIDに対する finish は冪等です。不明なIDまたはアクティブなワークフローの場合は、安全側に失敗し、ファイルをそのまま残します。このスキルは、無関係なレビュー、実装、またはサブエージェントを制約しません。