merge-ready

マージ可能な状態

PR をレビューまたはマージに出せる状態にする前に、最終チェックとしてこのスキルを使用します。

このスキルは既存のプロジェクトワークフローを連携させます。以下を置き換えるものではありません。

• 外部ユーザーの視点でのシナリオ作成と実行には qa-team
• 反復的な SEEK → VALIDATE → FIX レビューには quality-audit
• PR をマージ可能な状態にする作業中に見つかった本質的な修正には default-workflow

必須の証拠を含めて PR の説明を更新するには、pr-description-template.md を使用します。

必須条件

以下のすべてを満たした場合に限り、PR はマージ可能な状態です。

1. qa-team のシナリオを作成または更新し、gadugi-test validate で検証したうえで、実際に gadugi-test run を実行していること。
2. 変更が API、設定、デプロイ、CLI の動作、その他の外部向けインターフェースに影響する場合、ユーザー向けドキュメントを更新していること。
3. quality-audit を最低 3 回、SEEK → VALIDATE → FIX のサイクルで完了しており、重大または高レベルの指摘が残っている場合は 3 回を超えて継続し、最後のサイクルがクリーンな結果で終了していること。
4. すべての GitHub Actions チェックが成功しており、失敗が 0 件であること。
5. PR の説明に、条件 1～4 および 6 を裏付ける具体的な証拠が記載されていること。
6. 差分に無関係な変更が含まれていないこと。

いずれかの条件が満たされていない場合、PR はマージ可能な状態ではありません。

必ず守るガードレール

• 「シナリオ YAML が存在する」ことだけを十分な条件として扱わないでください。シナリオは検証され、さらに実行されている必要があります。
• 変更された対象範囲を確認せずに、ドキュメントは関係ないと判断しないでください。
• quality-audit のサイクルを 3 回未満で済ませないでください。
• 最後のサイクルがクリーンな結果でない quality-audit を受け入れないでください。
• CI が保留中または失敗している状態を受け入れないでください。
• PR の説明自体に証拠を追記するまでは、PR をマージ可能な状態と判断しないでください。
• 環境へのアクセス不可、PR へのアクセス不可、テストツールの不足などの阻害要因を黙って無視しないでください。明示的に報告してください。

ワークフロー

1. PR の状況を確認する

$ARGUMENTS が指定されている場合はそこから対象の PR を特定し、指定されていない場合は現在のブランチの PR を使用します。

以下を収集します。

• PR 番号、URL、タイトル、現在の PR の説明
• 変更ファイルと現在の差分範囲
• 変更が外部向けまたはユーザー向けのインターフェースに影響するかどうか
• 現在の CI 状態

便利なコマンド：

gh pr view "$PR" --json number,url,title,body
gh pr diff "$PR" --name-only
gh pr checks "$PR"
git diff --name-only origin/main...HEAD

まだ PR が存在しない場合でも証拠の準備はできますが、PR が作成され、CI 状態を確認できるようになるまでは、最終判定をブロック中のままにしてください。

2. qa-team で QA 条件を満たす

qa-team を呼び出し、外部ユーザーの視点から変更された動作を検証できるようにします。

必須の成果物：

• シナリオファイルのパス
• gadugi-test validate が成功した証拠
• gadugi-test run が成功した証拠
• 実行に使用した対象環境（ローカルまたはデプロイ済み）
• 証拠の場所、または実行出力の概要

最低限必要なコマンド：

gadugi-test validate path/to/scenario.yaml
gadugi-test run path/to/scenario.yaml

シナリオの実行に必要な環境がない場合は、作業を停止して阻害要因を報告してください。「定義のみ」に格下げしないでください。

3. ドキュメント条件を満たす

変更ファイルを確認し、この PR がユーザー向けのインターフェースを変更するかどうかを判断します。

• API
• 設定
• デプロイまたは運用のフロー
• CLI または TUI の動作
• ユーザーに表示されるワークフロー

該当する場合は、対応するドキュメントを更新し、そのドキュメントへのリンクを PR の説明に追加します。

該当しない場合は、確認した変更対象を列挙し、それぞれが内部専用である理由を説明します。例：「確認した変更対象：rust_runner.py、smart-orchestrator.yaml — どちらも内部のオーケストレーション処理であり、CLI／API／設定には影響しません。」

4. 品質監査の基準を満たす

quality-audit を実行し、次の完全な反復ループを実施します。

• 最低 3 サイクル
• 各サイクルは SEEK → VALIDATE（複数エージェントによる合意）→ FIX の順に実施
• 重大または高レベルの指摘事項が残る場合は、3 サイクルを超えて続ける
• 最終サイクルはクリーンな状態にする。重大または高レベルの指摘事項が 0 件であり、正確性またはセキュリティ上のリスクとなる中レベルの指摘事項も 0 件であること

この監査で見つかった修正はすべて default-workflow に従って実施してください。監査でコードやドキュメントの変更が必要な問題が見つかった場合は、該当する修正のために default-workflow に切り替え、作業を完了してから、このスキルに戻って検証を再開してください。

PR の説明には、次の内容を記載してください。

• サイクル数
• 各サイクルで確認された指摘事項
• 適用した修正
• 収束の概要
• 最終サイクルがクリーンであること（重大または高レベルの指摘事項が 0 件、正確性またはセキュリティ上の中レベルの指摘事項が 0 件）の明示

5. CI の基準を満たす

PR の GitHub Actions のステータスをすべて確認します。

ルール：

• すべてのチェックがグリーンであること（条件付きワークフローでスキップされたチェックは許容されますが、記載が必要です）
• 明らかに不安定なジョブのみ再実行する
• 実際の失敗を修正してから続行する
• 合格と見なされるのは失敗が 0 件の場合のみ
• CI が保留中、レッド、キャンセル済み、または利用できない場合、PR はマージ可能ではありません
• スキップされたチェックがあれば、名前とスキップ理由を PR の説明に記載する

便利なコマンド：

gh pr checks "$PR"
gh run list --branch "$(git branch --show-current)"

CI が保留中、レッド、キャンセル済み、または利用できない場合、PR はマージ可能ではありません。

6. スコープを徹底する

差分を確認し、PR が意図した変更に絞られていることを確認します。無関係な変更が含まれている場合は、ブロッカーとして報告し、PR を準備完了と判定しないでください。

7. PR の説明を更新する

手順 2～6 がすべて完了し、証拠を収集するまで、この手順を実行してはいけません。 プレースホルダーや見込みの証拠を使って PR の説明を更新しないでください。

pr-description-template.md を使い、すべてのプレースホルダーを実際の証拠に置き換えます。簡潔な表現を保ちつつ、レビュアーが推測せずに作業を検証できるだけの具体的な証拠を記載してください。

PR の説明にすでに有用なセクションがある場合は、見出しを重複させず、既存の構成に証拠を組み込んでください。

8. 二者択一の判定を返す

最後に、次のいずれかの結果を返してください。

• MERGE_READY：すべての基準を満たし、PR の説明も更新済み
• NOT_MERGE_READY：1 つ以上のブロッカーが残っている

次の形式を使用してください。

Verdict: MERGE_READY | NOT_MERGE_READY

Criteria:

- QA-team: pass | fail
- Docs: pass | fail | not-applicable
- Quality-audit: pass | fail
- CI: pass | fail
- Scope: pass | fail
- PR description evidence: pass | fail

Blockers:

- <concrete missing item or `none`>

停止してブロッカーを引き継ぐ場合

次のいずれかに該当する場合は、停止して NOT_MERGE_READY と報告してください。

• 必須の gadugi シナリオを実行できる環境がない
• PR または CI のステータスにアクセスできない
• quality-audit がクリーンな最終サイクルに収束していない
• ドキュメントの変更が必要だが、まだ作成されていない
• 差分に無関係な変更が含まれている

証拠の代わりに、実施の約束や TODO を用いてはいけません。