ship-workflow

出荷ワークフロー

リポジトリで現在適用されているチェック、必須レビュー、ブランチ保護、マージポリシーに従い、許可されたエンドポイントを通じて出荷します。通常の出荷をデフォルトとします。実行ファイルは Git／プロバイダーへの変更、ジャーナル、調整、クリーンアップを担当し、アシスタントはスコープ、論理的な変更のグループ化、リポジトリの規約、原因が不明な障害の診断を担当します。

参照ファイル

ファイル	内容	読み込むタイミング
references/commit-planning.md	インベントリ、論理コミット計画、ローカルゲート用パケット	コミットを作成するとき、またはローカル／コミット単位の検証を依頼するとき
references/lifecycle-contract.md	明示的なポリシー、保証、公開、スタック用パケット、ジャーナル、復旧	--policy または --stack-plan を指定するとき、再開するとき、またはブロッカーを解釈するとき
references/project-detection.md	リポジトリのゲートソース検出	ローカルのテストコマンドを特定するとき。バージョン／変更履歴の表はリリース作業を許可するものではありません

ワークフロー

1. スコープを解決する

対象を次のうち1つだけ選びます：--pr N、--branch NAME、明示的なスタック、保存済みの実行、または対象を1つだけ特定できる場合の現在のブランチ。曖昧な対象またはベースは、プロバイダー／Git の事実から解決します。それらの事実だけでは決定できない場合に限り、確認を求めます。--repo [HOST/]OWNER/REPO は PR のベースリポジトリを指定し、--head-repo OWNER/REPO はフォークのヘッド名前空間を指定します。

依頼	エンドポイント
「出荷して」、「/ship」、「PR 12 を完了してクリーンアップして」	clean（デフォルト）
「マージして」、「PR 12 を取り込んで、ブランチは残して」	--until merged
「PR を作成して」、「プッシュして PR を作成して」	--until pr
「CI を確認して」、「PR 12 のブロッカーは何か」	--until pr --dry-run（確認のみ）
バージョン、変更履歴、タグ、リリース、パッケージ公開、デプロイ	別のリリース権限が必要であり、このスキルの対象外です

変更を加える前に、対象、エンドポイント、クリーンアップの範囲を明示します。再開時は保存済みの権限を維持します。pr は公開の確認のみを行います。merged は、マージの確認と該当するマージ後の受け入れ確認を追加します。clean は、証拠に基づくクリーンアップを追加します。作業中のもの、変更のあるもの、保護対象／デフォルト／リリース用のもの、未マージのもの、オープンな PR に依存するもの、不明なものは維持します。スタックの選択範囲や再開時のエンドポイントを暗黙に広げてはいけません。

2. 実行ファイルを通じて確認する

読み込んだスキルの、クライアントが報告する絶対パスから <skill-dir> を解決します。対象リポジトリのチェックアウトから実行します：

uv run --no-project --python 3.12 python "<skill-dir>/scripts/ship.py" --pr 12 --dry-run
uv run --no-project --python 3.12 python "<skill-dir>/scripts/ship.py" --inventory

Python 3.12 以降、Git、認証済みの gh が必要です。前提条件が不足している場合は BLOCKED となり、ライフサイクルを手動実行する代替手段はありません。確認処理ではオブジェクト、参照、フック、ロック、ジャーナルを書き込まず、フェッチやプルーニングも行いません。argv リストはリテラルで指定し、パスとリポジトリ管理下の値は引用符で囲み、パケットと PR 本文はリポジトリ外のプライベートな一時ディレクトリに置きます。

3. 定型の出荷を実行する

プロバイダーのマージポリシーが明確な既存の PR の場合：

uv run --no-project --python 3.12 python "<skill-dir>/scripts/ship.py" --pr 12 --until merged

必須でないジョブも含め、適用可能な最新のチェックすべてと、プロバイダーが必須とするチェックの発行元、現在のヘッドに対するレビュー、保護設定を使用してください。チェックが保留中または失敗している場合、マージを中止します。証拠が欠けている、またはアクセスできない場合は GREEN と見なせません。プロバイダーが必須とする厳格な現在のベースチェックが引き続き優先されます。表示名が重複するのは通常のことです。証拠の特定にはワークフロー、イベント、発行元、ジョブ、現在の試行を使用してください。プッシュの結果はヘッドのみを対象とし、PR のマージコンテキストでの結果の代わりにはなりません。新しい試行が以前の証拠に取って代わるのは、同じ論理ジョブの場合に限ります。ジョブの所属はプロバイダーが現在示すジョブ ID によって決まります。部分的な再実行では、以前の試行から同じ名前の別ジョブが引き継がれることがあります。このコントローラーに合わせるために、ジョブ名やワークフローを変更しないでください。

明示的な --policy を指定すると、実際の曖昧さを解消できます。たとえば、リポジトリのマージ方式に関する規約、想定されるジョブの一覧、正当なスキップやヘッドのみを対象とするチェック、文書化されたマージ後のコマンド、保護された参照、または意図的に CI を使用しないリポジトリなどです。ライフサイクルのリファレンスに従い、現在のヘッド／ベース（スキーマ 1）または公開（スキーマ 2）に紐付けてください。CI が空の場合は、根拠に基づく ci_free の判断が必要です。ジョブが存在しないことから推測してはなりません。

通常の保証では、チェックアウトログの証明や不変のアクションピンは不要です。明示的なポリシーまたは選択したスタックノードの判断で assurance: "high" を使用するのは、要求された場合に限ります。このオプションには、ライフサイクルのリファレンスに記載されている、より強いチェックアウト／コミット親の証拠が必要です。保存済みの実行の保証レベルを、暗黙のうちに引き下げてはなりません。レガシー実行や互換性のないソース更新では、明示的な移行／ポリシー判断が行われるまで中止してください。

4. プッシュ前にローカルの作業を検証する

未コミットの作業がある場合は、コミット計画のリファレンスに従ってください。すべての処理方針を一覧化し、論理的なグループ分けのドラフトを作成し、--draft と --gates を指定してコンパイルし、出力された計画を保存してから --plan を実行します。既存の妥当なコミットと保持対象の作業を維持してください。前提条件を満たすために、作業を stash したり、リセットしたり、無条件に追加したり、破棄したりしてはなりません。

公開時には、PR が作成される可能性がある場合、--title と --body-file を併せて指定してください。計画またはスキーマ 2 の紐付けを通じて、名前で指定されたベースを解決します。完全に一致する既存の PR を再利用し、重複を作成しないでください。リリース準備の引き継ぎは pr で終了します。

要求されたローカルゲートは、それぞれ独自の期限を設け、クリーンで分離されたチェックアウト内でプッシュ前に実行されます。公開とスタックの再適用には --gates を使用し、送信する、または再適用するすべてのコミットを検査する必要がある場合は、ゲートパケットで per_commit: true を指定してください。既存のリポジトリフックは通常どおり実行されます。pre-push フックをインストールまたは上書きしたり、プッシュ中に長時間の検証を実行したり、停止／検証／再開の手順を導入したりしないでください。

コントローラーは、公開前に再適用案を固定し、検証します。明確な拒否の後、入力に変更がなければ、まったく同じ提案済みコミットオブジェクトを再利用し、ガード付きプッシュを再試行する前に検証を更新します。呼び出し元が GIT_COMMITTER_DATE を設定してはなりません。結果が不明な場合は保留状態のままにし、以降の変更操作を行う前に、現在の事実から状況を再確認してください。

5. 既存のスタックは親から順に出荷する

登録済みの stacked-prs コンパニオンを読み込み、トポロジー、スライスの境界、来歴、ネイティブなメンバーシップを確認します。コンパニオンスキルが見つからない場合は BLOCKED です。明示的な --stack-plan パケットを1つ作成します。許可された PR だけを選択し、すべての祖先と関連する依存ノードをコンテキストとして含め、変更されていない来歴と、選択した各ノードのマージポリシーを記載します。高保証が要求されていない場合は、通常のノード保証を使用します。

uv run --no-project --python 3.12 python "<skill-dir>/scripts/ship.py" --stack-plan /tmp/ship.X/stack.json --dry-run
uv run --no-project --python 3.12 python "<skill-dir>/scripts/ship.py" --stack-plan /tmp/ship.X/stack.json --gates /tmp/ship.X/gates.json --until merged

コントローラーは各自のスライスを検証し、作成者、メッセージ、トレーラーのバイト列を保持して、正確な予期済み旧値を使った force-with-lease でリスタックを公開します。親のマージが確認されてからのみターゲットを変更し、新しいコンテキストに対するチェックの再実行を求めます。未選択の祖先がオープン状態の場合は、スコープに関する判断が必要なため停止します。クリーンアップはマージリクエストの提出後ではなく、マージの確認後に行います。

GitHub ネイティブの選択では、選択対象のうち最上位のメンバーに対して、ガード付きの非同期リクエストを1回だけ実行します。手動マージやフォールバックによる昇格は行いません。プロバイダーは保持された上位メンバーをリベースできます。その影響を明示し、コントローラーによるツリーとスライスの検証を必須にします。キューへの登録はマージではありません。このリクエストがガードするのは選択対象のうち最上位のヘッドのみであり、それより下のすべてのメンバーを原子的にガードするものではありません。

エラー処理と復旧

結果	対応
PLANNED	検査結果を報告します。変更は行われていません
COMPLETE	実際に達成したエンドポイントのみを報告します
WAITING	保留中の事実を報告します。返された保存済みの実行があれば再開し、なければ読み取り専用の検査を繰り返します
NEEDS_JUDGMENT	指定されたポリシー、スコープ、来歴、または失敗の責任に関する判断を解決します
BLOCKED	実際の前提条件、保護、または失敗を報告し、確認済みの事実を保持します

返された run_id がある場合に限り、--resume RUN_ID を使って再開します。値を推測してはいけません。プッシュ、PR 作成、ターゲット変更、マージ、削除の結果が不確かな場合は、再試行前に状態を照合します。マージ後のコマンド失敗や、必須のクリーンアップ失敗は成功ではなく、マージ済みだが未完了の状態です。変更に起因する CI の失敗はスコープ内で修正します。継承された失敗、権限エラー、保護による失敗は引き続きブロッカーとして扱います。保護の回避、管理者権限でのマージ、チェックの緩和、レビューボットへの依頼は行いません。

待機については、last_gate.reason を使って説明します。トランスポートレベルのブロッカーに操作識別子しか含まれていない場合は、サニタイズ済みの diagnostic を使います。監視の有限な期限と、必要な最小ディスパッチ時間を明記します。名前付きのベースが未解決の公開プレビューは、NEEDS_JUDGMENT ブロッカーを伴う resolve-base アクションであり、実行可能なプッシュ／PR 計画ではありません。

CI に関する質問は読み取り専用のまま扱います。明示的に待機する場合は、有限の外部期限を設けて gh pr checks N --repo owner/repo --watch --interval 10 --fail-fast を実行し、その後コントローラーによる検査を繰り返します。ウォッチャーだけでは、適用可能性、現在のベース、レビュー方針、または GREEN は証明できません。

出力

実際のレシート項目を伝えます。エンドポイント、PR URL、確認済みのコミット／マージ、実際に実施したチェックとローカルゲート、理由付きの削除済み／保持済み／失敗したクリーンアップ対象、使用可能なチェックアウト、ブロッカー、正確な残りのアクションです。終了コードは PLANNED／COMPLETE が 0、WAITING が 3、NEEDS_JUDGMENT が 4、ブロックまたは入力エラーが 2 または 5 です。解析エラーまたはジャーナル記録前のエラーでは、実行やその他のレシート項目が省略される場合があります。スタックの一部のみの出荷、保留中のキュー、未完了のクリーンアップは成功ではありません。通常の出荷では、バージョン、変更履歴、タグ、公開状況は変更しません。