final-release-review

最終リリースレビュー

目的

BASE_TAG...TARGET を、次のいずれかのモードで監査します。

• リリース前の計画： ユーザーが次のリリースの計画を求めている場合、またはChangesetsのバージョンPRがまだ存在しない状態で origin/main をレビューする場合に使用します。TARGETに含まれる有効なchangesetから、予定されるリリース種別を導き出します。パッケージのバージョンが変わっていないことをブロッカーとして扱わないでください。
• 最終候補： ユーザーが最終候補の判定を求めている場合、またはTARGETにChangesetsが生成したバージョンコミットが含まれる場合に使用します。消費済みchangesetから候補のリリース種別を導き出し、生成されたパッケージのバージョンと変更履歴を検証します。

patch と minor の判定では、Changesetsを信頼できる情報源として扱います。各changesetがパッケージの差分に対して適切なバージョン更新を指定しているかどうかは、$changeset-validation に判断させてください。このレビューで、妥当な宣言済みの更新を、独自のセマンティックバージョニング上の判断に基づいて置き換えないでください。ランタイム互換性、リグレッション、パッケージング、リリースリスクは独立して監査します。ドキュメントの準備状況はリリースゲートとは分けて扱ってください。

クイックスタート

1. リポジトリのルートが openai-agents-js であることを確認します。
2. リモートタグを同期し、前回のリリースを選択します。

   BASE_TAG="$(.agents/skills/final-release-review/scripts/find_latest_release_tag.sh origin 'v*')"
   

3. TARGETを更新して解決します。デフォルトは origin/main です。

   git fetch origin main --prune
   TARGET="$(git rev-parse origin/main)"
   

   明示的に指定されたタグまたはrefは、git rev-parse "${TARGET_REF}^{commit}" を使って剥がしたコミットに解決します。レポートと比較URLでは、注釈付きタグオブジェクトではなくコミットSHAを使用します。
4. レビューのモードをリリース種別とは独立して決定します。
   1. リリース前の計画、または最終候補レビューを求めるユーザーの明示的なリクエストを優先します。
   2. それ以外の場合、TARGETにChangesetsが生成したバージョンコミットが含まれる、またはパッケージのバージョンがBASEより上がっている場合は、最終候補モードを使用します。
   3. それ以外の場合は、リリース前の計画モードを使用します。
5. Changesetsのリリース状態と種別を決定します。
   1. 計画モードでは、TARGETにある有効な .changeset/*.md ファイルをすべて確認します。ただし、.changeset/README.md は除きます。
   2. 最終候補モードでは、バージョンコミットを特定し、そのコミットの最初の親から削除された各changesetを読み取ります。また、生成された packages/*/package.json と packages/*/CHANGELOG.md の変更も確認します。
   3. すべての元のchangeset、パッケージエントリー、宣言された更新種別を記録します。
   4. リリース全体の種別は、妥当な宣言済み更新のうち最も高いものにします。優先順位は minor が patch より上です。.changeset/config.json の固定パッケージグループを考慮し、個々のパッケージのバージョンから低い種別を推測しないでください。
   5. major エントリー、不正なフロントマター、有効なリリースセットと消費済みリリースセットの混在、または適用可能なchangesetがない状態でのパッケージ変更は、無効なリリース状態として扱います。これらを patch または minor に読み替えないでください。
6. リリース差分のスナップショットを作成します。

   git diff --stat "${BASE_TAG}"..."${TARGET}"
   git diff --dirstat=files,0 "${BASE_TAG}"..."${TARGET}"
   git log --oneline --reverse "${BASE_TAG}".."${TARGET}"
   git diff --name-status "${BASE_TAG}"..."${TARGET}"
   

7. references/review-checklist.md を使って差分を監査し、各候補をリリース済みの仕様に照らして立証するか、却下します。
8. 現在の読み取り専用のGitHub情報を使って、関連する未解決のドキュメントPRを見つけてレビューします。ローカルブランチ、タイトル、過去の状況からカバレッジを推測しないでください。
9. Changesetsのリリース状態、リリース可否ゲート、リスク評価、ドキュメントのカバレッジ、および条件付きのminorリリース向け「主な変更点」の草案を報告します。

Changesets のリリースポリシー

• プレリリースの計画では有効な Changesets フロントマターを、生成された最終候補では消費済みの Changesets フロントマターを、リリース種別の正式な宣言として使用します。
• CI で必須の Changesets 検証に合格しているものとします。ただし、現在の証拠がそうでないことを示している場合は除きます。検証状況を確認できない場合は、その旨を伝え、このスキル内でセマンティックなバージョン更新の分類を黙って再実行しないでください。
• 現在の証拠から、Changesets が欠落している、形式が不正である、古い、または整合していないことが分かった場合は、リリース準備上の不備として報告します。計画モードでは、候補が存在するかのように装わず、正確な修正内容を示します。最終候補モードでは、Changesets の入力と生成された出力が一致するまで処理をブロックします。
• リリース対象パッケージの変更がなく、Changesets もない場合、リリース種別は none です。patch リリースを捏造しないでください。
• 計画モードでは、パッケージのバージョンがまだ BASE と一致している場合があります。その後のバージョン更新は Changesets ワークフローが担当します。
• 最終候補モードでは、消費されたリリース種別、生成されたパッケージバージョン、固定グループへの反映、変更履歴、バージョンコミットが一致していることを確認します。不一致があればブロック対象です。
• ユーザーが指定した patch または minor ラベルは、判断材料であり、リポジトリの Changesets の状態を上書きするものではありません。不一致を報告し、リポジトリ内の宣言を使用します。
• 文書化されていない移行と、利用可能な移行手段または互換性の経路が存在しないことを区別してください。文書の不足はブロック対象ではありません。実際にサポート対象の経路が破壊され、利用可能な移行手段やフォールバックもない場合は、宣言されたバージョン更新の種類にかかわらずブロックすることがあります。

決定論的なゲートポリシー

• ブロック条件が少なくとも1つ実証されない限り、デフォルトで 🟢 リリース可能 とします。
• 🔴 ブロック とするのは、具体的なリリース阻害の証拠と、解除するための実行可能な条件がある場合に限ります。
• ブロック条件：
  • BASE_TAG...TARGET で導入されたことが確認されたリグレッションまたはバグ。
  • 最終候補モードにおいて、Changesets の状態が無効である場合、または消費された Changesets と、生成されたバージョン、変更履歴、固定グループの更新との間に不一致がある場合。
  • 利用可能な移行手段、フォールバック、互換性の経路がない、公開 API、プロトコル、設定、または永続状態の破壊的変更が確認された場合。
  • 緩和策が未解決の、具体的なデータ損失、破損、またはセキュリティへの影響を伴う変更。
  • 差分によって、リリースに不可欠なパッケージング、ビルド、またはランタイムの経路が壊れている場合。
• 次の項目は、それだけでは決してブロック条件になりません：
  • 差分が大きいこと、広範なリファクタリング、多数のファイルが変更されていること。
  • 証拠のない「リグレッションが起きる可能性がある」という推測。
  • CI チェックをローカルで再実行しないこと。
  • ドキュメントの欠落、不完全、未マージ、古さ、またはリリース後の更新。
  • プレリリース計画モードにおいて、パッケージのバージョンメタデータが変わっていないこと。
• ドキュメントのレビューによって、根本にあるランタイムまたは互換性の不具合が判明することがあります。ブロックするのはその不具合に限り、ドキュメントの状態を理由にブロックしないでください。
• ゲートがグリーンであっても、ユーザーにとって重要なリリース内容は説明する必要があります。

ワークフロー

差分を準備して把握する

• 最新のリモートタグと対象 ref を取得します。比較対象からワーキングツリーの変更を除外してください。
• ユーザーがベースタグを指定した場合はそれを優先しますが、リモートタグは引き続き更新してください。
• 指示がない限り、$code-change-verification と $changeset-validation を含むリポジトリの CI に対象が合格しているものとします。通常のユニットテスト、lint、フォーマット、型チェック、カバレッジ、Changesets のチェックは、デフォルトでは再実行しないでください。
• 差分の統計、ディレクトリごとの分布、コミット順、変更されたファイル名から、リスクの高い領域を特定します。変更されたテストは動作上の証拠として読み取りますが、それだけで確証が得られたとはみなさないでください。

コントラクトを監査し、指摘事項の根拠を示す

• TARGETだけを単独でレビューするのではなく、BASEとTARGETを比較します。
• 公開APIについては、エクスポート、識別情報、TypeScriptシグネチャ、パラメーターの順序、デフォルト値、列挙型、文書化された動作を比較します。
• パッケージについては、サポート対象のNode.jsおよびTypeScriptのバージョン、依存関係、ピア依存関係、オプションの依存関係、パッケージのエクスポート、公開される内容、バージョンメタデータ、ESM／CJS／型の動作を比較します。
• 永続化される状態、スキーマ、プロトコル、設定、環境変数については、リリース済みの永続的な境界を特定し、後方互換の読み取り、または実行可能な移行パスを確認します。
• ランタイムの変更は、.agents/references/README.mdにある担当リファレンスを通じて追跡し、必要な利用側と対称性の軸を確認します。
• 差分によってコントラクト違反、サポート対象の経路で到達可能なリグレッション、またはユーザーに具体的に見えるリリース上の検討事項が裏付けられる場合にのみ、候補を採用します。
• 静的な証拠では判断に関わる疑問を解決できない場合は、BASEとTARGETで同一の公開経路またはパッケージ成果物を使った、最小限の検証を行います。
• 安全性が確認された検討事項には🟢 LOW、具体的ながら未解決のリグレッションの兆候には🟡 MODERATE、確認済みのブロッカーには🔴 HIGHを割り当てます。
• すべてのリスク項目にEvidence、Impact、Files、Actionを含めます。安全なリリース上の検討事項に対して、テストやコード作業を捏造しないでください。

ドキュメントのカバレッジをレビューする

• まずランタイム監査から、破壊的変更、移行、デフォルト値、オプトインまたはオプトアウト、主要機能、公開API、プロバイダーおよび依存関係の互換性、永続スキーマ、変更されたユーザーワークフローを洗い出し、ドキュメント化が必要な項目の一覧を作成します。
• 未対応の項目として報告する前に、承認済みの読み取り専用GitHubアクセスを使って、現在オープン中のPRを確認します。このリポジトリではghを使わず、GitHub上で変更を加えないでください。
• Changesetsのリリース種別、想定されるバージョン、機能名、関連する実装PR、ブランチ名、変更されたドキュメントのパスを手がかりに候補を探します。PRのタイトルだけに頼らないでください。
• 候補ごとに、PR番号またはURLと最新のhead SHAを記録し、現在の差分全体と、カバレッジに関する判断に実質的な影響を与える議論を確認します。複数のPRで一覧の項目を網羅している場合もあります。
• リリース対象の差分とドキュメントPRの差分は分けて扱います。オープン中のドキュメントPRがすでにリリース対象に含まれているかのように示さないでください。
• 全体のカバレッジをcovered、partially covered、not covered、stale/conflicting、unverifiedのいずれかに分類します。
• 現在の読み取り専用GitHubアクセスが利用できない場合はunverifiedとし、検索上の制約を説明します。ドキュメントPRが存在しないとは主張しないでください。
• カバレッジが確認できない各項目について、リリース後に更新するファイル、セクション、例または記述を具体的に示し、必要な移行または互換性に関する文言を提案します。カバレッジが未確認の場合、提案は暫定であることを明記します。
• マージされていないドキュメントPRも、リリース後の引き継ぎ先として認めます。SDKのリリースが利用可能になるまでマージを保留すべき場合は、その旨を記載します。

マイナーリリースの Key Changes ドラフト

• 変更セットの正式なリリース種別が minor の場合は、コピーしてすぐ使える Key Changes のドラフトを含めてください。ユーザーから依頼がない限り、patch または none では省略してください。

• 生のコミット数やディレクトリの概要ではなく、確認済みのユーザー向け契約と変更セットの要約に基づいてドラフトを作成してください。

• 確立された JS リリース形式に従ってください。

  ## Key Changes
  
  ### <User-facing theme>
  
  <A concise paragraph describing the behavior, exact public names, and migration or fallback when applicable.>
  

• 主要なテーマが 1 つの場合はセクションを 1 つにし、より広範なマイナーリリースでは通常 2〜7 個のセクションを作成してください。合成的な Highlights リストは追加しないでください。

• 破壊的な動作と、サポートされている移行方法または代替手段を最初に記載してください。マイナーリリースに破壊的変更がない場合は、関連する導入セクションまたは最初のテーマでその旨を伝えてください。

• 生成された ## What's Changed リストを再現せずに、主要なリリーステーマを網羅してください。正確な公開名称、既定値、バージョンの範囲、オプトアウト方法、互換性に関する条件をそのまま保持してください。

• 安定して公開されているドキュメント URL のみを使用してください。未マージのブランチへのリンクは含めず、未マージのドキュメント PR は Documentation coverage に別途記載してください。

• リリースがブロックされている場合もドラフトを作成してください。ただし、洗練されたリリース文面でブロッカーを隠さないでください。

推奨内容の作成

• BASE_TAG、TARGET コミット、レビュー方式、変更セットの状態とソース、正式なリリース種別、判明している場合は生成される候補バージョンを明記してください。
• 主要なディレクトリとファイル数を要約し、すべてのコミットをレポート項目にしないでください。
• 裏付けのあるブロッカーと、確認済みの最も重要なリリース上の考慮事項のみを、通常はユーザーへの影響ごとに 2〜5 項目にまとめて記載してください。
• ドキュメントの対応状況は、独立したブロッカーではないセクションに記載してください。
• ブロックされている場合は、ブロック解除のための具体的なチェックリストと合格条件を含めてください。具体的なブロック解除アクションがない場合は、ブロックしないでください。
• 通常のコマンド結果、合格数、スキップ、選択解除、検証ステータスの一覧は含めないでください。

出力形式（必須）

英語で、リポジトリの AGENTS.md にある「GitHub-ready Output」セクションに従ってレポートを作成してください。Key Changes のドラフトを含むレポート全体を、既定ではコピー可能な 1 つの markdown コードブロック内に記載してください。以下のテンプレートは、そのコードブロックに入れる文字列そのものです。フェンスなしのプレーンテキストを明示的に求められた場合は、それに従ってください。

レポート内では、固定の比較 URL https://github.com/openai/openai-agents-js/compare/<tag>...<target-commit> を、単独の URL として使用してください。ドキュメント PR とバージョン PR には、#123 などの GitHub 標準参照を使用してください。Markdown リンクを作成したり、すでにレンダリング済みのリンクを重ねて囲んだりしないでください。ファイルの根拠には、インラインコード内でリポジトリ相対パスを使用し、絶対ローカルパスやローカルファイルへのリンクは使用しないでください。ユーザーがファイルパスなしを求めた場合は、変更セットのソースとリスクの各欄を含め、影響を受けるコンポーネント名またはドキュメントのセクション名を使用してください。ホスト固有の引用や注釈は、レポートのコードブロックの外に記載してください。

送信前に、コピー可能なソースに比較 URL が 1 つだけ含まれていること、GitHub の PR 参照が標準形式であること、ファイルの根拠が移植可能であること、リンクの二重囲みやホスト固有のマークアップがないことを確認してください。書式のみを修正する場合は、レビューの元の根拠と対象範囲を維持してください。

### Release readiness review (<tag> -> TARGET <ref>)

This is a release readiness report done by `$final-release-review` skill.

### Diff

https://github.com/openai/openai-agents-js/compare/<tag>...<target-commit>

### Release intent

- Review mode: <pre-release planning | final candidate>
- Changesets state: <active | consumed | none | invalid>
- Changesets source: <repository-relative changeset paths or version commit; use a release-set description when paths are excluded; include validation limitation when material>
- Release type: <patch | minor | none | invalid>
- Candidate version: <version when generated, or not yet generated in planning mode>
- Versioning verdict: <declared plan | generated candidate consistent | correction required | invalid candidate>

### Release call

**<🟢 GREEN LIGHT TO SHIP | 🔴 BLOCKED>** <one-line rationale>

### Scope summary

- <N files changed (+A/-D); key areas touched: ...>

### Risk assessment (ordered by impact)

1. **<Finding or release consideration title>**
   - Risk: **<🟢 LOW | 🟡 MODERATE | 🔴 HIGH>**. <Impact statement.>
   - Evidence: <specific BASE-versus-TARGET evidence>
   - Files: <repository-relative paths, or affected components when paths are excluded>
   - Action: <next step and pass condition>

### Documentation coverage (non-blocking)

- Coverage source: <native PR reference and head SHA, multiple PRs, none found after a successful search, or search unavailable or partial>
- Status: <covered | partially covered | not covered | stale/conflicting | unverified>
- Covered obligations: <concise list or none>
- Gaps or post-release suggestions: <exact files, sections, claims, or none>
- Publication timing: <merge after release when docs describe unreleased behavior, or not applicable>

### Unblock checklist

1. [ ] <required only when blocked>
   - Exit criteria: <what must be true>

### Key Changes draft

<Include the copy-ready `## Key Changes` block only for a Changesets-declared minor release.>

### Notes

- <Material assumptions only>

• リリースに問題がない場合は、Unblock checklist を省略してください。
• ユーザーから依頼がない限り、patch または none では Key Changes draft を省略してください。
• 動作に影響する問題のないリリースでは、少なくとも 1 つの 🟢 LOW の考慮事項を残してください。「重大なリスクは確認されませんでした」だけを返してはいけません。
• 報告すべきユーザー向け契約がないメタデータのみのリリースでは、リスクがない旨を簡潔に記載してもかまいません。

リソース

• scripts/find_latest_release_tag.sh：リモートタグを更新し、最新の一致するリリースタグを返します。
• references/review-checklist.md：変更セットの解決、検出シグナル、ドキュメント対応状況のレビュー、根拠の要件について詳しく記載しています。