setup-git-guardrails

git のガードレールを設定する

破壊的な git コマンドを実行する前に人間の判断を挟み、エージェントが確認なしに実行するのではなく、人間が一つずつ承認できるようにします。日常的な作業（コミット、フィーチャーブランチへのプッシュ、ドライラン）はそのまま通過します。この設定は特定のエージェントに依存しません。2 つのレイヤーで構成され、特定のハーネスを前提としません。

• ポータブルレイヤー：git の pre-push フックです。あらゆるエージェントや人に適用されますが、git には reset --hard などのローカルコマンド用のフックがないため、プッシュのみを対象とします。
• エージェントレイヤー：scripts/guard-git.py はコマンドガードです。各ハーネス固有のコマンドインターセプト方法を使って組み込みます。コマンド文字列を読み取るため、コマンドの連結（&&、;、|、&）、sudo、xargs、command、bash -c、$(...)、git -Cも検出します。

ガードレベル

各レベルには、その一つ下のレベルも含まれます。

レベル	ガード対象
1. 共有履歴	保護対象ブランチ（main、master、リモートのデフォルトブランチ、ユーザーが追加したブランチ）へのプッシュ、通常の強制プッシュ（-f、--force、+ refspec）、削除またはミラーを行うプッシュ（--delete、:branch、--mirror、--all、--prune）、プッシュ時の --no-verify。--force-with-lease と --dry-run は通過します
2. ローカル作業	reset --hard、clean -f（ドライラン以外）、branch -D、変更を破棄する checkout または switch（.、-- <paths>、-f、--discard-changes）、作業ツリーに対する restore（--staged のみなら通過）、stash drop と clear、worktree remove --force、reflog expire と delete、gc --prune、prune
3. 厳格	すべてのプッシュに加え、rebase、あらゆる形式の reset、commit --amend、ブランチまたはタグのあらゆる削除、filter-branch、filter-repo、update-ref

手順

1. 設定内容を確認する

1 回のやり取りで、それぞれの推奨回答とともに質問します（ハーネスに質問ツールがある場合はそれを使い、なければ通常のチャットで質問します）。

• レベル：1、2、または 3。2 を推奨します。
• 適用範囲：このプロジェクトのみ、またはすべてのプロジェクト。
• ハーネス：ユーザーが使用するエージェントハーネス。候補をディスク上から取得するには python3 -I scripts/detect-harnesses.py --project . を実行します（ディレクトリ、パス上のコマンド、指示ファイル。インストール済みスキルのみのディレクトリは skills-only の 1 行として返されます）。現在実行中のハーネスが候補にない場合は追加し、一覧を提示します。
• 保護対象ブランチ：main と master はそのままにし、develop などを追加します。

完了条件：レベル、適用範囲、ハーネス、保護対象ブランチへの回答がそろっていること。

2. ポータブルレイヤーをインストールする

scripts/pre-push をリポジトリのフックディレクトリ（core.hooksPath を反映する git rev-parse --git-path hooks の出力先）にコピーし、実行可能にして、先頭にある PROTECTED_BRANCHES と LEVEL を設定します。既存の pre-push フックがある場合は、既存のフックを引き続き動作させたまま、新しいフックをそこから呼び出します。フックはリポジトリごとに設定するため、すべてのプロジェクトに適用する場合は、どのリポジトリに設定するかを確認します。

完了条件：フックが実行可能で、シミュレートした削除を拒否し、終了コード 1 で終了すること。printf 'refs/heads/x 0000000000000000000000000000000000000000 refs/heads/feat abc\n' | <hook>

3. ハーネスごとにエージェント層を接続する

scripts/guard-git.py を、対象範囲に応じた安定したパス（プロジェクトでは .agents/hooks/、グローバルでは ~/.agents/hooks/）にコピーします。Python 3 と git が必要です。まず python3 --version を実行してください。Python 3 がないとフックはフェイルオープンになるため、この手順を省略し、その旨を伝えます。

各ハーネスについて、コマンドのインターセプトに関する最新のドキュメントを確認します。スキーマやファイルの場所はリリースによって変わるためです。ドキュメントに記載されている最も強力な仕組みを使います。

1. 確認またはブロックできるコマンド前フック。 python3 -I <path>/guard-git.py --level <N> --protected <branches> を指定し、フックのペイロードを stdin で渡します。デフォルトの text 形式は、ブロックフックで一般的な慣例に従い、理由を stderr に出力して終了コード 2 で終了します。--format ask-json は、Claude Code 形式のフックが受け付ける権限確認プロンプトの判定を出力します。
2. コマンドパターンを使った権限ルール。 ガード表を確認ルールに置き換えます。パターンではブランチやコマンドチェーンを確認できないため、ドライラン以外のすべての push で確認を求めます。
3. どちらもない場合。 ポータブル層のみを使います。レベル 2 と 3 のどのコマンドがガードされないかをユーザーに伝えます。

EXAMPLES.md に、最初の 2 つの仕組みをそれぞれ接続する例があります。ハーネスの既存の設定にマージし、すでにある項目はすべて残します。

完了条件：各ハーネスで仕組み（1、2、または 3）が記録され、設定ファイルを引き続き解析できる状態になっていること。

4. 検証する

選択したレベルで 3 つのコマンドに対してガードを実行し、最初のコマンドがガードされ（終了コード 2）、残りが通過する（終了コード 0）ことを確認します。

printf 'git push origin main' | python3 -I <path>/guard-git.py --level <N>
printf 'git push --force-with-lease origin feature' | python3 -I <path>/guard-git.py --level <N>
printf 'echo "git push origin main"' | python3 -I <path>/guard-git.py --level <N>

次に、ハーネス自体で許可されている場合は、ハーネスを通じて各ハーネスの接続状態を確認します（新しいセッションでガード対象のコマンドを実行し、プロンプトまたはブロックが表示されること）。

5. 報告する

各レイヤーとハーネスについて 1 行で、レベル、仕組み、検証した内容と設定しただけの内容、ガードされないものを報告します。

変更または削除する

新しい回答で手順を再実行します。ファイルはその場で上書きし、設定項目は重複させずに置き換えます。削除する場合は、フック、コピーしたスクリプト、各設定項目を示してから、ユーザーの同意を得て削除します。

ユーザーに伝える制限事項

• ガードはコマンドのテキストを読み取ります。Git エイリアス、git を実行するスクリプト、eval の中身は追跡されないため、ミスは検出できますが、意図的な回避は防げません。確実に阻止できるのは、リモートのブランチ保護だけです。
• 確認には人間が必要です。応答できる人がいない場合、ガード対象のコマンドは拒否されると想定してください。
• git push --no-verify はフックをスキップします。レベル 1 ではコマンドガードがその前に確認を求めるため、push を承認する場合は人が意図的に実行します。