version-release

# version-release: バージョンリリースの定型手順 > **skill version**: 1.4.0 セッション内で初めて本スキルを使用するときは「version-release スキル v1.4.0 を使用します」と宣言する。 実装・検証が完了したバージョンを、作業ブランチから既定ブランチ(`main` 等。リポジトリの実際の既定ブランチを使う)へのマージとタグ付与まで確実に届けるためのゲート式チェックリスト。**各ゲートは順番に実行し、確認結果を必ずユーザーに見える形で出力する。ゲートが失敗したら先へ進まず、修正(要コミット)後に当該ゲートから再実行する**。 ## 前提と一般化ルール - **完了要件の達成とユーザーの最終承認が済んでいること**。未承認ならこのスキルを進めず、承認を求めて停止する。**達成の証拠はG0で照合する。** - 対象プロジェクトの言語・エコシステムを**前提にしない**。バージョン宣言ファイルもホスティングサービスも派生公開先も「探索と慣行の読み取り」で特定する。 - git hostingがGitHubでない/リモートが無いプロジェクトでは、PR・リリースの各ゲートを相応の手段に読み替えるか、該当ゲートをスキップしてタグ付与までで完了とする(どう読み替えたかを報告する)。 - 公開系の操作は**ドラフトまで**(リリースの公開ボタンはユーザーが押す)。force push・履歴改変は使わない。 - ユーザーに選択肢を提示するときは、何を決めるのか・各選択肢を採るとどうなるか・推奨案とその理由を、計画書もコードも精読していない読み手が判断できる日本語で書き、ファイル名・ブランチ名・コマンドは補足に留める(理由: コードを読まないと答えられない問いは、それ自体が進行のボトルネックになる)。 ## 版の状態の見分け方 > この節は version-start / version-implement / version-release の3スキルが**同じ文**で持つ。直すときは3つを同時に直す。 各スキルの入口の手順は、指定された版が**いまどの段階にあるか**を本節の①〜③で決め、要約を表示してから進む。 **① 状態の表。** 表は後ろの状態(リリース済み)から並べてある。判定は**上から順に当て、最初に当てはまった状態を採る**。リリース済みの版はブランチも計画書も持つので、未着手の側から当てると誤る。 | 状態 | 意味 | 見分ける証拠 | |---|---|---| | リリース済み | リリースが完了 | タグがあり、作業ブランチが既定ブランチにマージ済み。進行文書の当該版の記載がリリース済みを示す | | リリース中 | リリース(version-release 相当)が途中 | PR・既定ブランチへのマージ・タグ・リリース文書・進行文書のリリース済みの記載のうち、**一部だけ**がある | | 実装完了 | 実装が完了し、リリース待ち | 実装記録に完了要件の全数照合と申し送りがあり、進行文書の当該版の記載が実装完了を示す。タグが無く、既定ブランチに未マージ | | 実装中 | 実装(version-implement 相当)が途中 | 計画書が「確定」になっている、または実装記録がある。実装記録に完了要件の全数照合が無い。タグが無い | | 設計済み | 設計が完了し、計画は確定待ち | 作業ブランチ・計画書(ドラフト)・進行文書の当該版の記載(設計)があり、実装記録が無い | | 設計中 | 設計(version-start 相当)が途中で止まっている | 作業ブランチと計画書のどちらか一方だけがある。または計画書はあるが、直近版の計画書にある節が欠けている。または両方あるが、進行文書に当該版の記載が無い | | 未着手 | 誰も手を付けていない | 作業ブランチ・計画書・実装記録・タグのいずれも無い | **② 証拠の在処。** 名前や置き場は決め打ちせず、進行文書と既存の配置・慣行から特定する。 | 証拠 | 見る場所 | 注意 | |---|---|---| | 作業ブランチ | ローカルとリモートの両方のブランチ一覧。命名慣行は既存ブランチから読む | **リモートにだけあって計画書が手元に無い**ときは、別マシンで設計中・設計済みの可能性がある(計画書が git 非追跡のプロジェクトで起こる) | | タグ | タグ一覧(リモートから取得してから見る)。命名慣行は既存タグから読む。**直近リリース版は、タグを版番号順に並べた最大** | 取得できなければローカルのタグで判定し、その旨を要約に書く | | マージ状況 | 作業ブランチの先端が既定ブランチに含まれるか | 既定ブランチはリポジトリの実際のものを使う | | PR・リリース文書 | ホスティングサービスの CLI で照会する。**照会するのは version-release だけ**(version-start / version-implement は git の証拠で足りる) | 照会できなければ「未確認」と書く。推測で埋めない。CLI のアカウント確認の規定に従う | | 計画書 | 実装計画の置き場(進行文書の参照と既存の配置から特定)。存在、前付けの状態(ドラフト/確定)、直近版の計画書と比べた節の欠け | 直近版が無い初版は、version-start が定める標準構成と比べる | | 実装記録 | 同じ置き場。存在、進捗管理の表、完了要件の照合の節、申し送りの節、未解決の中断論点 | | | 進行文書 | 当該版の記載(状態〈設計/実装完了/リリース済み〉と日付、要点。旧形式の版ごとのエントリも記載として読む)、次版への要望の反映済みの印、ロードマップ | **進行文書が次に予定している版**はここから読む(未反映の要望、ロードマップの次の版) | | 版宣言ファイル | version-release の G1 が探索するもの(例: `VERSION`)。現在値が直近リリース版と一致するか | 補助。食い違えば要約に書く | **③ 要約の形。期待どおりでも必ず表示する。** - リポジトリ(名前と場所)と進行文書の表題 — 別プロジェクトの版番号を打っていないかを目に入れるため - 直近リリース版(タグ) - 進行文書が次に予定している版 - 着手済みで未リリースの版(ブランチまたは計画書があってタグが無いもの) - 指定された版と、①で決めた状態とその根拠 - 判定: **一致**(このスキルが期待する状態)か、食い違いの種類(下の語彙) **食い違いの語彙。** 版 A.B の「後継」は A.(B+1) または (A+1).0。引数は `X.Y.Z` でも `X.Y` でも受け、ブランチ名とタグ名は慣行に従って読み替える。 | 語 | 定義 | |---|---| | 飛び越し | 指定版より小さい版に、リリースされていないものがある(着手済みで未リリース、または進行文書が予定していて未着手) | | 不在 | 指定版が進行文書のどこにも無く、直近リリース版の後継でも、着手済みで未リリースの版の後継でもない。**別プロジェクトの版番号の疑い** | | 後退 | 指定版が直近リリース版より小さい。タグがあればリリース済みの扱い、無ければ不在の扱い | | 前工程が未了 | 指定版の状態が、このスキルが期待する状態より前 | | 後工程に進んでいる | 指定版の状態が、このスキルが期待する状態より後 | | 自スキルの途中 | 指定版の状態が、このスキル自身の「途中」(設計中/実装中/リリース中)。**再開の対象** | **判定の順**: ①で指定版の状態を決める → 不在(状態が未着手のときだけ起こる) → 飛び越し → スキルごとの入口の判定。不在と飛び越しが同時なら不在を優先する(別プロジェクトの疑いの方が重い)。入口の判定は各スキルの表を上から順に当て、最初に当てはまった行を採る。不在と飛び越しは、行に当たらなくても要約に書く。 **選択肢の出し方。** 食い違いのときは、何が食い違っているか、各選択肢を採るとどうなるか、推奨案とその理由を、計画書もコードも精読していない読み手が判断できる日本語で書く。ブランチ名・ファイル名・コマンドは括弧書きに留める。選択肢を示して回答を得られる対話手段があればそれを使い、無ければ通常の対話で尋ねる。**得た方針でそのまま継続する**(回答を待って中断する形にしない)。「停止」を選ばれたら、要約と次に使う手順を報告して止まる。**期待どおりのときは確認を取らず、要約の表示だけで進む。** ## 申し送りの扱い > この節は version-start / version-implement / version-release の3スキルが**同じ文**で持つ。直すときは3つを同時に直す。 **申し送りとは**、将来の版で行動を要する事項である。環境の事実・教訓・観察の記録は申し送りではなく実装記録に残す(申し送りを必要以上に重く扱わないために、まず「事実」を申し送りから外す)。 **3段階。** 上から順に当て、最初に当たった段階を採る。どれにも当たらなければ Optional。 | 段階 | 定義 | |---|---| | Critical | 近い将来の版で対応が必須のもの。意図的に先送りして実装が存在しない部分、明らかなセキュリティホール、致命的なバグ、依存ライブラリ・外部サービスの仕様変更による動作不能(の予告) | | Recommended | 実装することがプロジェクトの自然な次の版になるもの。大きな性能改善、利用者体験の明確な向上 | | Optional | それ以外。完全性は上がるが前2者ほどの重大性は無いもの | **申し送り文書。** 内部資料置き場(実装計画・実装記録と同じ置き場)に1つ置く。名前は進行文書や既存のファイルに別名があればそれ、無ければ `エージェント申し送り事項.md`。**無ければ最初に必要としたスキルが作る。** 形式は段階ごとの表(列: ID／発生版／要旨／実装すると何が変わるか／望ましい実装／考えられる影響／状態〈未着手・採用(vX.Y)・保留〉)と、末尾の「消去した項目」(ID／消去日／理由)。ID は `H` に通し番号を付け、消去しても再利用しない。 **消去の規則。** version-start と version-release は文書を見直し、obsolete になった項目(実装済み・対象消失・ユーザーが恒久的に対応しないと指示したもの)を本文から消して「消去した項目」に1行残す。消去はユーザーに確認してから行う。 **採用の規則。** 進行文書の要望欄(ユーザー記載)が最上位であり、申し送りはそれを補う参考に過ぎない。version-start は **Critical だけ**「本版で対応するか」をまとめて1回尋ねる(Critical が無ければ尋ねず、その旨を報告する)。Recommended と Optional は件数と要旨の一覧を示すだけで、採用を勧めず、計画に勝手に入れない(ユーザーが選んだものだけ入れる)。採用が決まった項目は version-start が状態列を「採用(vX.Y)」にし、実装が終わった項目は version-implement の G3 で消去の規則に回す(理由は実装済み)。 **進行文書の記載。** 版ごとの記載は進行文書の1か所に集約する(履歴の表の1行など、進行文書の既存の形に従う)。各フェーズ(設計・実装完了・リリース)は追記ではなくその1か所を**更新**し(状態と日付、要点)、合計の目安は200字。詳細は計画書と実装記録に書く。ユーザー記載は消さない。旧形式(版ごとに設計／実装完了／リリースのエントリを足す形)が既にある進行文書では、既存の版は旧形式のまま読み、新しい版から集約する。旧形式のエントリしか無い版(移行期)は、そのエントリを当該版の記載として更新するか、新しい形へ写してから更新する。 ## プロジェクト毎スクリプトの利用(推奨) 決定論的に判定できるゲート(G1バージョン照合・G4検証・G5クリーン確認)は、**プロジェクト毎のリリース前チェックスクリプト**(例: `tools/release_check.sh <version>`)に落とすのが望ましい。G0のgit側の証拠収集(ブランチ・タグ・マージ状況)も含めてよい。 - スクリプトが**既にあるプロジェクトでは、手動手順の代わりにそれを実行**し、結果を報告する。 - 無いプロジェクトで本スキルを初めて実行した際は、G1〜G5を手動で通した後に「今回の探索結果を固定したチェックスクリプトの作成」をユーザーに提案する(以後のバージョンでチェックが機械的保証になる)。 ## ホスティングサービスのCLIとアカウントの確認 PR作成やリリースドラフトの作成には、ホスティングサービスのCLI(GitHubなら`gh`)を使うことが多い。この種のCLIは**複数のアカウントを同時に保持し、そのうち1つがアクティブ**という構成を取れる。**アクティブなアカウントがリモートリポジトリの所有者と異なると、権限エラーで操作が落ちる**。作業の途中で落ちると復旧が煩雑なので、CLIを使うゲート(G0・G6・G7・G8等)に入る**前に**確認する。 1. **リモートの所有者を読む**(`git remote -v`等)。 2. **CLIが保持しているアカウントと、どれがアクティブかを確認する**(GitHubなら`gh auth status`)。CLIを使わないゲートでは確認自体が不要。 3. **アクティブなアカウントがリモートの所有者と異なる場合**、そのままでは落ちる。CLIの設定はリポジトリの外にあるため、**切り替えの承認をユーザーに求める**。 **このとき手順を停止しない。** その場でユーザーに方針を尋ね(選択肢を提示できる質問手段があればそれを使う)、**得た方針でそのまま進行を継続する**。「回答を待って中断する」形にはしない。 4. 承認が得られたら**アクティブなアカウントを一時的に切り替える**(GitHubなら`gh auth switch`)。承認が得られなければ、該当ゲートを実施せず、**何が未了かを明示して報告する**。 5. 目的の作業を行う。 6. **作業の成否にかかわらず、必ず元のアクティブアカウントへ戻す。** 作業が失敗した場合も、中断した場合も戻す。**戻す操作に承認は要らない**(元の状態に復するだけであるため)。 7. 戻したことを完了報告に明記する。 なお、リモートのURLがSSHのホストエイリアス等で解決される構成では、`git push`自体はCLIのアクティブアカウントに影響されない。一方、HTTPS+CLIの認証ヘルパを使う構成では`git push`も影響を受ける。**どちらかを決め打ちせず、実際にエラーが出た操作を手がかりに判断する**。 ## ゲート ### G0: 入場ゲート — 版の状態照合と再開判定 1. **「版の状態の見分け方」の表を引いて証拠を集め、要約を表示する。** PRとリリース文書の照会にCLIを使うので、**着手前に「ホスティングサービスのCLIとアカウントの確認」を実施する**。照会できなければ「未確認」と書き、推測で埋めない。本スキルが期待する状態は**実装完了**(再開ならリリース中)。 2. **判定は次の表を上から順に当てる。** | 判定 | 扱い | 選択肢 | |---|---|---| | 未着手・設計中・設計済み・実装中(未実装) | **停止。** 何が欠けているか(計画書の確定/実装記録の完了要件照合/進行文書の当該版の記載〈実装完了〉)を列挙し、version-implement(の完了ゲート)を案内する。ユーザーが完了を明言する場合も、実装記録の完了要件照合を済ませてから再実行するよう伝える | 出さない | | リリース済み | **停止。** タグ・マージコミット・PR・リリース文書を示し、追加の変更は次の版(パッチを含む)としてversion-startから始めることを案内する | 出さない | | 飛び越し(下位に着手済みで未リリースの版がある) | 情報を提示して尋ねる | (a) **停止して確認**(推奨) (b) 指定版で続行(リリース順が入れ替わることの帰結を要約に書く: 「最新リリース」の印の付き方、後から出す下位版の版番号の扱い) | | リリース中(自スキルの途中) | 3の再開判定へ | (a) **残りのゲートから再開**(推奨) (b) 停止 | | 一致(実装完了) | 進む。**確認は取らない** | — | 3. **再開判定**(リリース中のとき)。**済んだと判定できるのは、リポジトリの外か既定ブランチに痕跡が残るゲートだけ。G1〜G5は常に再実行する**(安価で冪等。マージ済みなら既定ブランチ上で見る)。G9も常に実行する。 | 証拠 | 意味 | 再開位置 | |---|---|---| | PRがある(未マージ) | G6の途中 | CIの確認とマージから(PRは作り直さない) | | 作業ブランチが既定ブランチにマージ済み | G6完了 | マージコミットを特定してG7へ | | タグがローカルにだけある | G7の途中 | タグのpushから(付け直さない) | | タグがリモートにもある | G7完了 | G8へ(タグ起点の派生先があれば起動確認だけは行う) | | リリース文書がある(ドラフトまたは公開) | G8完了 | G9・G10へ(ドラフトを作り直さない) | | 進行文書の当該版の記載がリリース済みを示す | G10完了 | 完了報告へ | 再開の表(ゲート/証拠/済・未)を出力してから、最初の未済ゲートへ進む。**済んだゲートをやり直さない**(タグの付け直し・PRの作り直し・リリース文書の二重作成をしない)。リリース文書が無いことはG8未済を意味するが、スキップするかどうかはG8の規定で決める(前回`--no-release`を付けていたなら再実行でも付ける)。 4. G0の結果は他のゲートと同じく**ユーザーに見える形で出力**する。 ### G1: バージョン宣言の探索と照合(上げ忘れ検出の核心) 特定ファイルを決め打ちせず、**バージョンを宣言しているファイルをリポジトリ全体から探索**する。探索の観点: - マニフェスト類: `pyproject.toml` / `package.json` / `Cargo.toml` / `*.gemspec` / `*.csproj` / `CMakeLists.txt` / `VERSION` / `Makefile` 等、そのエコシステムでバージョンを持つファイル - コード内宣言: `__version__` / `version =` / `VERSION =` 等のgrep - 文書内表記: README(多言語版含む)の版数・変更履歴、ステータス表記 見つかった**全宣言を「ファイル:行 → 現在値 → 目標版との整合」の表で表示**し、照合する。dev サフィックスの扱い等の慣行は進行文書(プロジェクトのコンセプトと各版の計画概要を記載した文書。名称・形式はプロジェクトによって異なる)・実装記録・既存タグから読む(例: タグ時点で`X.Y.0.dev0`を維持する慣行のプロジェクトもある — 前版の実績に合わせる)。不一致は修正し、コミットしてから次へ。 ### G2: 派生公開先の追随確認 タグとリリース文書はリポジトリの中で完結するが、**利用者が実際に取りに行く場所はその外にある**ことが多い。パッケージレジストリ、コンテナレジストリ、静的ホスティング、URLで直接取得されるマニフェスト、文書サイトなど、**リポジトリから派生してリポジトリの外で公開・配備されるもの**が本版で最新になるかを、マージ前に確かめる。タグとリリース文書そのものはここに含めない(タグはG7、リリース文書はG8の担当)。 1. **派生公開先を探索する。** 下の「探索の手がかり」の表を**上から順に当たり**、該当するものを全部拾う。表は手がかりの種別を示すものであり、例示したファイル名・サービス名に限らない。 | 手がかり | 見るもの | 分かること | |---|---|---| | CI/CDの公開ジョブ | ワークフロー定義にある publish / deploy / upload / push 相当のステップと、その起動条件(タグpush・リリース公開・既定ブランチへのpush・手動) | 自動更新の有無とトリガ | | デプロイ設定ファイル | 静的ホスティング・コンテナ・PaaSの設定(例: `wrangler.toml` / `netlify.toml` / `vercel.json` / `fly.toml` / `Dockerfile` / compose / Helm chart) | 公開先の種別と、設定内に直書きされた版 | | パッケージのメタデータ | `pyproject.toml` / `package.json` / `Cargo.toml` / gemspec 等の公開用メタデータ(レジストリ名・非公開の印・長い説明文の出どころ) | レジストリ公開の有無と、公開文書がREADMEから流れるか | | 文書サイトの設定 | mkdocs / Docusaurus / Sphinx 等の設定、Pages用ブランチ | 文書サイトの有無と版表記の出どころ | | URLで配られるマニフェスト | 利用者がURLで直接取得するファイル(index / marketplace / formula / プラグインのmanifest等) | 既定ブランチへのマージで即時に反映される公開物 | | READMEのバッジ・導入コマンド | バッジのURL、`pip install` / `docker pull` / `npm i` / `brew` 等の導入コマンド | 利用者が取りに行く公開先の名前 | | 進行文書・前版の記録 | 配布経路の記載、前版のリリース記録にある公開後の確認 | 探索の見落とし防止 | 2. **見つかった派生公開先を表にして表示する。** 列は「公開先 / 種別 / 更新のトリガ / 版の出どころ(ファイル:行 またはタグ) / 本版で最新になるか(自動・要修正・手動・未確認) / 必要な作業」。**派生公開先が無ければ「派生公開先なし」と明記して pass とする。** 3. **1件ずつ判定する。上から順に当てはまるものを採る。** - **自動**: トリガが本リリースの操作(タグpush・リリース公開・既定ブランチへのマージ)で発火し、公開される版がG1で照合済みの宣言から取られる → pass。派生先がコミット済みの生成物なら、再生成済みで宣言と一致していることまで見る。**トリガの種類を控えておく**(G7・G8・完了報告で使う)。タグ名の規則(例: `v*`)と本版のタグ名が合うことも見る。 - **要修正**: 派生先の設定に版が直書きされていて古い、または派生先へ流れる公開文書に旧版の表記がある → 直してコミットし、**本ゲートを再実行する**(G1と同じ扱い)。 - **手動**: 公開ジョブが無い、または手動トリガしか無い → 手順とコマンドを**完了報告の「ユーザーに残る作業」に書く**。公開ジョブを新設することは本スキルの範囲外であり、提案に留める。 - **未確認**: 外部サービス側の状態を確認できない → 「未確認」と書く。**推測で埋めない**(実在しない「更新あり」を並べない)。 要修正の分岐がコミットを伴うため、本ゲートはマージ(G6)より前に置いている。 ### G3: 文書の追随確認 - README(および多言語版)が本バージョンの内容に追随しているか、obsoleteな記述(旧手順・旧バージョン表記)が残っていないかを確認する。変更履歴があれば本版のエントリを確認する。 - 実装記録(または相当文書)が完成しているか確認する。 ### G4: 検証ゲート - プロジェクトの検証一括スクリプト(例: `tools/check.sh`)を実行し全pass。無ければlint+テストの相当コマンドを実行する。 - 失敗した場合は原因を解析し(必要なら解析専任サブエージェントへ委譲)、修正→再実行。**テスト側を弱めて通すことは禁止**。 ### G5: クリーン確認 - `git status`で未コミット変更なし(進行文書などgit非追跡のものは除く)。 - ブランチの全コミットがリモートへpush済み。 ### G6: PR作成とマージ - **着手前に「ホスティングサービスのCLIとアカウントの確認」を実施する**(未実施なら先にそちらを行う)。 - 作業ブランチ→既定ブランチのPRを作成する。本文は「Summary(変更の要点)+Verification(検証結果の実測値)」構成とし、プロジェクトの言語方針(OSSなら英語)に従う。 - CIがあれば**グリーンを確認してから**マージする。マージ方式(merge commit / squash / rebase)は`git log`の過去マージの慣行に合わせる。 ### G7: タグ付与 - タグ命名は既存タグの慣行に合わせる(例: `vX.Y.0`)。**注釈付きタグをマージコミットに付与**し、pushする。 - **タグpushをトリガとする派生公開先(G2で「自動」と判定したもの)があれば、push後に自動公開のジョブが起動したかを1回確認する**(GitHubなら`gh run list`等)。完了を待ち続けない。起動の有無と直近の状態を報告し、失敗していれば**先へ進まずユーザーに報告する**(タグの削除やロールバックはしない)。 ### G8: リリースノート(該当する場合のみ) - `--no-release`指定時、またはリリースに値しない版(内部整理のみ,プライベートリポジトリの場合等)はスキップ。判断に迷う場合はユーザーに確認する。 - 作成する場合: 前版までのリリースノートのスタイル・言語を踏襲し、**ドラフトとして**作成する(GitHubなら`gh release create --draft`)。公開はユーザーが行う旨を報告に明記する。 - **リリース公開をトリガとする派生公開先(G2)があれば、「公開後に○○が動くので確認してほしい」を報告の案内に含める。** ### G9: ローカルブランチとリモートブランチの同期確認 - ローカルブランチ(特に既定ブランチ)がリモートと同期されているかを確認する。**マージ後もローカルの既定ブランチが古いまま取り残されやすい**ため、明示的に確認する。 - ローカルブランチが古い場合はリモートから同期を行い、最新の状態に更新されていることを確認する。 ### G10: 進行文書への完了記載 - **先に申し送り文書を見直す**(「申し送りの扱い」の節に従う): 本版で消化した項目など obsolete を消去して「消去した項目」に残し、リリース時に判明した「行動を要する」事項を段階付きで追加する。環境の事実は実装記録に書く。(再開判定は進行文書の記載で G10 の完了を見るので、見直しを先に済ませる) - 次に進行文書の当該版の記載を更新する(「申し送りの扱い」の「進行文書の記載」に従う。状態=リリース済み、日付、タグ、PR。要点は必要なら整える。**エージェント記載であることと日付を明示**する)。実装記録にはリリースの節を足す: PR番号・マージコミット・タグ・リリースドラフトの有無、**派生公開先の最終状態(G2の表)**、次バージョンの予定。 ## 完了報告 全ゲートの結果(pass/修正内容)、PR・タグ・リリースドラフトのURL、**派生公開先ごとの最終状態**(自動で済んだもの・公開後に動くもの・手作業が要るもの)、ユーザーに残る作業(リリース公開、手動の派生公開)、申し送り文書への変更(消去・追加した ID)を整理して報告する。アカウントを一時的に切り替えた場合は、**元へ戻したことを明記**する。再開したときは、飛ばしたゲートとその根拠を明記する。