gugabfigueiredo/semver-howto

semver-howto は何をしますか？

すべてのロジックは scripts/resolve-version.sh にあります。 このファイルはエージェントに いつ 呼び出すか、そして ルールが何か を伝えます。 手順そのものを再導出することはありません — スクリプトの --help でフラグを、インラインコメントでアルゴリズムを確認してください。

呼び出すタイミング

• コード変更後、バージョンタグの提案が必要なとき。
• ユーザーが「タグを付けて」/「バージョンを上げて」/「バージョンは？」と言ったとき。
• タグ選択をエージェントに委譲するCIステップから。

コミットメッセージの作成やチェンジログ生成のために呼び出さないでください。

スクリプトが強制するルール

1. インパクトゾーン: 変更されたパス → git log -1 -- <paths> → git describe --match "*v*" <commit>。モノレポで全タグまで対象を広げることはありません。
2. バンプ: インパクトゾーンのコミットに feat: があればマイナー、それ以外はパッチ。メジャーは自律的には行いません。
3. 衝突: パターンスコープでローカルに git tag -l を実行し、次に対象を絞って git ls-remote --tags origin "refs/tags/<candidate>" で浅いプリフライトを実施。使用済みアドレスを通り越して進みます。
4. RCのみ: 自律的な出力は常に -rc[n] です。クリーンなタグは拒否されます。
5. 提案、プッシュはしない: 標準出力 = 1つのタグ。人間（またはプロモーションワークフロー）がミューテーションを実行します。

使用法

./skills/semver-howto/scripts/resolve-version.sh              # 次の -rc[n] を提案
./skills/semver-howto/scripts/resolve-version.sh --promote    # 最も高いRCから -rc を削除
./skills/semver-howto/scripts/resolve-version.sh --paths "a b" # 明示的なインパクトゾーン
./skills/semver-howto/scripts/resolve-version.sh --help       # フラグとアルゴリズムのメモ

終了コード 0 は成功。非ゼロはあいまい/安全でない状態（詳細は標準エラー出力）。

パフォーマンスと安全性

• git describe --match "<prefix>*v*" <commit> はタグウォークを関連する参照に制限します — 数千のモジュールごとのタグがあるモノレポでは重要です。
• git tag -l "<pattern>" は packed-refs から提供されます。O(マッチ数) で、O(履歴) ではありません。
• git ls-remote --tags origin "refs/tags/<candidate>" は単一の参照を要求します。オブジェクトフェッチや FETCH_HEAD の更新はなく、巨大なリモートでも通常1秒未満です。git fetch --tags を完全に回避します。
• diff とログのクエリはインパクトゾーンのパスにスコープされるため、各実行は履歴の関連部分のみに触れます。
• 安全性: RCのみの書き込み、ローカル+リモートの二重衝突チェック、プッシュなし、メジャーバンプなし、事前タグがない場合の決定論的ブートストラップ (v0.1.0-rc1) は標準エラー出力に表示され、人間の確認を求めます。