commit

Git コミット

変更されない証拠に基づいて、意味のあるコミットメッセージを作成します。決定論的な準備、コミット、インデックスの整合、プッシュの仕組みは ai-commit に任せます。

すべてのコマンドは対象リポジトリの cwd から実行してください。ai-commit の前後に追加の git status、git log、git diff を実行しないでください。このワークフローに必要な証拠は、準備処理で完全に得られます。安定した TSV レコードを明示的に解析する決定論的な自動化でのみ、--porcelain を使用してください。通常のスキルフローでは、人間が読めるセクションを使用します。

1. 引数を解析する

引数：$ARGUMENTS

• ai-commit はリポジトリ設定からメッセージ形式を選択します。--natural または --conventional を渡すのは、明示的に一度だけ上書きする場合に限り、リポジトリのポリシーを再現するためには使用しないでください。
• --all：ワークツリーとインデックスのすべての変更を取得します。これにより、別のエージェントの作業を含めてしまうリスクが意図的に生じます。
• --staged：現在のインデックスをそのまま取得します。セッションのパスは追加しないでください。--all と併用できません。
• --natural：このコミットで自然言語形式を強制します。
• --conventional：このコミットで Conventional Prefix Format を強制します。
• --push：コミット後のプッシュを要求します。それ以外の場合は、常設の指示で許可されている場合にのみプッシュします。
• --rebase：--push と併用すると、プッシュ前に ai-commit が取得済みの upstream に対して、遅れているブランチをリベースします。ユーザーが除外していない限り、許可されたプッシュには毎回指定してください。
• --close <issue_numbers>：正の 10 進数の課題番号ごとに、ai-commit commit --close <N> を 1 回ずつ渡します。カンマ区切りまたはスペース区切りの入力を受け付けます。ai-commit が Closes #N の行を記述します。
• --finding <finding_ids>：このコミットで修正する台帳の検出事項ごとに、ai-commit commit --finding <id> を 1 回ずつ渡します。このセッションのコミットが特定の台帳の検出事項を修正する場合は、文脈から検出事項も推定してください。ai-commit は Finding-ID: <id> のトレーラーを記述し、コミット後に検出事項を解決済みにします。コミットで実際に修正しない検出事項を含めたり、解決したりしないでください。
• --squash：マージベース以降のブランチ上の各コミットを、ブランチの差分全体を含む 1 つのコミットに置き換えます。ヘルパーは、解決されたデフォルトブランチとのマージベースを検出します。スカッシュモードでは、クリーンなツリーとインデックス、およびデフォルト以外のブランチへのチェックアウトが必要です。--all、--staged、--push と併用できません。
• --base <branch>：デフォルトブランチの検出を上書きします。--squash と併用する場合にのみ使用してください。
• Conventional Prefix Format では、位置引数のタイプキーワードが推定されたタイプを上書きします。自然言語形式では、位置引数の動詞またはカテゴリキーワードが推定された動詞を上書きします。引用符で囲んだ位置引数のテキストは、推定された説明または件名を上書きします。

要求された操作が、すでに先行しているクリーンなブランチのプッシュだけである場合は、準備を省略してください。以下のプッシュ先を確認してから、ai-commit push --rebase を実行します。

プッシュ先

ai-commit は、設定済みの upstream（branch.<name>.remote および branch.<name>.merge）にプッシュします。リモートには、名前付きリモートまたは URL を指定できます。upstream ブランチの名前が異なる場合は、branch.<name>.pushRemote が branch.<name>.remote と一致している必要があります。gh pr checkout は、メンテナーがプッシュできる PR のためにこの設定を書き込みます。

既存の PR に取り組む場合は、コミットまたはプッシュの前に gh pr view でヘッドリポジトリとブランチを取得してください。別のブランチにプッシュしても PR は更新されません。upstream が PR のヘッドと一致しない場合は、ブランチ設定を修正してください。

git config branch.<branch>.remote '<head-remote-or-url>'
git config branch.<branch>.merge 'refs/heads/<head-branch>'
git config branch.<branch>.pushRemote '<head-remote-or-url>'

その後、ai-commit でプッシュしてください。手動でプッシュしないでください。強制プッシュしないでください。ai-commit がプッシュ先を拒否した場合は、そのエラーを報告してください。完了を報告する前に、PR をもう一度読み込み、ヘッド SHA がプッシュしたコミットと一致することを確認してください。

Squash モード

ユーザーが明示的に squash を要求した場合にのみ、squash モードに入ってください。ブランチの状態、マージリクエスト、または継続的な指示から推測してはいけません。--squash が指定されている場合は、計画とリセットの手順について references/squash.md に従ってください。その後、--staged モードで手順 2〜5 を続けてください。継続的な指示でプッシュが許可されている場合でも、squash モードでは --push を渡してはいけません。squash のリファレンスには、共同作成者のトレーラー、失敗時のロールバック、squash レポートが追加されています。

2. 1 回だけ準備する

準備コマンドを 1 つ実行します。

ai-commit prepare [--all | --staged] [--natural | --conventional] --diff full \
  [--exclude-baseline '<path>=<oid>']... [-- <session-modified-paths>...]

• 準備の出力をすべて読んでください。tail、head、awk、grep などにパイプしてはいけません。出力には、表示されたトランザクション ID と、手順 3 で分析する diff の両方が含まれます。出力を切り詰めるパイプを使うと、ID とともに証拠も失われます。

• diff 全体が一度に読めないほど大きい場合（たとえば、数百のファイルにまたがるリポジトリ全体の移行）で、このセッションですでに内容をレビュー済みの場合に限り、代わりに --diff summary を使用してください。その場合は、name-status、shortstat、そのレビュー内容をもとにメッセージを作成します。

• デフォルトモードで準備する前に、このセッションで編集したパスに限ってリポジトリのフォーマッターを実行してください。フォーマット用の pre-commit フックによって、固定した後に内容が変更されるのを防ぐためです。

• デフォルトモードのパス一覧は、このセッションに起因する変更がある、個々のリポジトリ相対ファイルから作成してください。ディレクトリのパスは、新規ファイルと削除ファイルを含む該当ファイルのパスに展開します。別のエージェントによる未追跡ファイルや変更済みファイルが含まれる場合があるため、git status または git status --porcelain の出力を解析して一覧を作成してはいけません。デフォルトモードでは、このセッションで編集したすべてのパスが必要です。名前変更の場合は、大文字・小文字だけが異なるファイル名またはディレクトリ名の変更も含め、旧パスと新パスの両方を含めてください。

• デフォルトモードで準備する前に、利用可能であれば ai-coord touched を実行し、その出力をセッションのパス一覧と照合してください。この相互確認では、見落としていたセッション編集済みのパスを追加します。このセッションで意味のある変更を加えていないパスは無視してください。touched パスはあくまで補助的な証拠であり、確定的な根拠ではありません。コマンドを利用できない場合や、セッションが認識されない場合は、この相互確認を何も表示せずに省略してください。

• --all では明示的なパスを指定できず、追跡対象、未追跡、変更済み、削除済み、ステージ済みの変更をすべて取得します。

• --staged では、明示的なパスもベースライン除外も指定できず、共有インデックスをそのまま取得します。

• ai-commit prepare は、このセッションの ai-coord による古い作業ツリーのベースラインを自動的に適用します。自動適用された除外は準備の証拠に表示され、変更せずに開示する必要があります。上書きには明示的な --exclude-baseline を引き続き使用でき、再現性のある自動化のために --no-auto-baseline を指定すると、ベースラインの検出が無効になります。無関係な変更は決して元に戻さないでください。

  調整の再参加によって、このセッションの完了済み編集がベースラインとして記録されている場合は、その blob ID を保持されているセッションの証拠または準備の証拠と比較してください。選択したすべてのファイルの差分全体が、許可されたタスクに起因する場合に限り、--no-auto-baseline を使用してください。所有者が混在する場合や帰属が不確かな場合は、除外を維持してください。

準備時に unclaimed paths が表示された場合、このセッションの有効な ai-coord claim はそのパスを対象にしていません。コミットする前に、パスごとに判断してください。変更がこのセッションで許可された作業である場合は、ai-coord start で不足している範囲を確保してください。別のエージェントの作業である場合は、トランザクションを破棄し、そのパスを含めずに準備し直してください。帰属を確認できないパスをコミットしてはいけません。

準備では、表示されたトランザクション ID のもとで正確なツリーと差分を固定し、共有インデックスは変更しません。その ID を保持してください。後続のコミットではトランザクションが再利用され、変更可能な作業ツリーや共有インデックスから意図した内容が再計算されることはありません。トランザクションは、その不変の差分をロックされた現在のブランチに適用します。途中でブランチが移動して競合が生じた場合、安全に失敗します。トランザクション ID が発行される前に準備が失敗した場合は、証拠に示された引数、帰属、または入力の問題を修正し、許可された範囲内で準備を再試行してください。

3. 分析して作成する

準備済みの単一の完全な差分を分析します。異なる証拠を得るためだけに、有効な準備を置き換えてはいけません。ファイルごとのセクションが大きすぎる場合は、DIFF_TRUNCATED の開示とともに切り詰められます。その場合も、名前ステータスと簡易統計の証拠に基づいてメッセージを作成します。

• 表示されたメッセージ形式とメッセージ形式のルールを使用します。これらのルールは ai-commit が提供します。別の Conventional または Natural のリファレンスを読み込んではいけません。
• 位置指定の上書きを適用し、破壊的変更を検出し、コードからスコープやコンテキストを推測します。本文は、実質的な根拠を加える場合にのみ含めます。
• --close と、このコミットで実際に解決されるトランスクリプト内の Issue 参照から、Issue 番号を収集します。--finding とコンテキストから、Finding ID を収集します。これらをステップ 4 のフラグとして渡します。-m の値に Closes、Finding-ID、Agent-Session の行を書いてはいけません。ai-commit は Closes の段落と、検証済みの準備トレーラーを含むトレーラーブロックを追加します。欠落したトレーラーを独自に作成したり、修正したりしてはいけません。

件名の段落を 1 つ作成し、必要な場合は本文の段落を 1 つ追加します。ai-commit が生成しないトレーラー（スカッシュモードの Co-authored-by: など）に限り、トレーラーの段落を自分で渡します。ai-commit は自身のトレーラーをその段落に統合します。

ai-commit は各 -m の値をそのまま受け取り、リテラルな \\n が含まれていると拒否します。ステップ 4 の例のように、引用符で囲んだ引数の中に実際の改行を入れてください。

4. トランザクションをコミットする

次を実行します。

ai-commit commit <transaction-id> -m '<subject>' [-m '<body>'] [--close <N>]... [--finding <id>]... [--push --rebase]

たとえば、本文に 2 項目を含める場合、物理的な改行を含む 1 つの -m 引数として渡します。

ai-commit commit <transaction-id> -m '<subject>' -m '- first material change
- second material change' --close 42 --finding 873d2a01bb9722f8 [--push --rebase]

プッシュが許可され、Push Destination チェックに合格した場合は、--push --rebase を追加します。その場合、ai-commit は Git 操作が進行中でなく、作業ツリーとインデックスがクリーンな場合に限り、取得済みのアップストリームに遅れているブランチをリベースします。リベースが停止した場合は中止します。同じコマンドで、デフォルト、--all、--staged の各トランザクションを処理できます。これらを直接 Git コマンドでステージングまたはコミットしてはいけません。

トランザクションは冪等です。中断、ロック競合、または再試行可能な終了の後は、同じトランザクション ID とメッセージ引数で再試行します。これらの再試行可能な失敗の場合、新しい可変状態から準備を作り直してはいけません。再実行すると、重複したコミットを作成せずに、保持されたレシートを復元するか返します。インデックスロックを削除してはいけません。

コミット作成前に発生したことが確認できる、決定的なコンテンツエラーの場合は、許可された作業を修正し、復旧用リファレンスを使用して未コミットの準備を置き換えます。これには snapshot-check hook modified prepared content が含まれます。変更不可の再試行では、失敗したスナップショットに固定されたコンテンツを修正できません。既存のタスク権限には、この復旧も含まれます。

失敗した準備を置き換える前、または --no-verify や --no-gpg-sign を追加する前に、references/failure-recovery.md を読んでください。バイパスフラグは試行ごとの明示的な復旧オプションであり、初回試行のデフォルトではありません。

--finding はコミットとプッシュの後に ai-coord finding resolve --as fixed で各 Finding を解決するため、FINDING_RESOLVED の行の後に別途解決コマンドを実行する必要はありません。終了コード 3 で FINDING_UNRESOLVED <id> が返された場合、コミットとプッシュは確定しています。同じコマンドを 1 回再実行します。それでも失敗する場合は、stderr に出力された理由を報告し、指定された ai-coord finding resolve コマンドを実行します。

5. 完了と結果の報告

結果は簡潔にまとめ、各結果行を装飾せずにそのまま転記します。

• COMMITTED <transaction-id> <commit-oid> は、コミットの作成または冪等な復旧を証明します。プッシュが許可されていない場合、これで完了です。

• HOOK_ADDED <path> は、準備済みパスのセット外にフックが追加した内容を示します。このような行はすべて開示してください。

• FINDING_RESOLVED <id> は、台帳の指摘事項がコミット OID とともに解決済みであることを証明します。FINDING_UNRESOLVED <id> は、コミットは確定したものの、台帳では指摘事項が未解決のままであることを意味します。ステップ 4 のリプレイルールに従ってください。

• REBASED <branch> <count> は、プッシュ前に ai-commit がブランチを <count> 件のアップストリームコミットにリベースしたことを示します。コミットワークフローでは、この行の後に INTEGRATED 行が続きます。

• PUSHED <branch> または PUSHED_NEW <branch> は反映済みであることを証明し、プッシュが許可された作業、またはプッシュのみの作業を完了します。

• PUSHED <transaction-id> <commit-oid> は、プッシュ済みのトランザクションを再実行したときに返される、保持された証明です。

• INTEGRATED <transaction-id> <head-oid> は、ブランチにトランザクションの元のコミットが含まれなくなった一方で、HEAD にその内容が含まれていることを開示します。たとえば、リベース後や同一のアップストリームコミットがある場合などです。その後に続く PUSHED 行によって、作業が完了します。プッシュ済みであることの証拠として、COMMITTED OID ではなく HEAD OID を示してください。

• SUPERSEDED <transaction-id> <commit-oid> は、安全に未完了となったことを示します。ブランチにはコミットもその内容も含まれず、何もプッシュされていません。ブランチを確認してください。変更がまだ必要な場合は、トランザクションを破棄して準備し直してください。

• BEHIND <branch> <count> は安全に未完了となったことを示し、完了を意味することはありません。ai-commit はフェッチ後、統合もプッシュも行わずに処理を拒否しました。それより前に COMMITTED が出力されていれば、ローカルコミットは証明されています。

  --rebase を指定していない場合は、同じトランザクションコマンドを --push --rebase を付けて再実行してください（プッシュのみの作業では ai-commit push --rebase を実行してください）。--rebase を指定した場合、アップストリームが統合されなかった理由は stderr の行に示されます。別の Git 操作が進行中の場合、またはワーキングツリーかインデックスがクリーンでない場合は、停止してブランチの調整が必要であることを報告してください。リベースが停止して中断された場合は、競合するパスを報告し、解決する前にユーザーに確認してください。自動でスタッシュしてはならず、手作業でリベースしてはなりません。

無関係なツリーの状態、コマンドが出力していない ahead/behind の件数、ステージングの説明、成功したフックの処理は報告しないでください。復旧リファレンスで必須とされる、バイパスについての 1 行の開示のみを追加してください。