safe-git-ops

Safe Git 操作

サンドボックスの失敗、リポジトリの状態に関する問題、実際のコンテンツの競合を混同せずに、ユーザーが一般的な Git 操作を実行できるよう支援します。

スキルのディレクトリ構成

<installed-skill-dir>/
├── SKILL.md
├── scripts/
│   └── project-push
└── references/
    ├── failure-modes.md
    ├── commit-paths.md
    └── worktrees.md

段階的な読み込み

• 必ず references/failure-modes.md を読みます
• ユーザーからコミット、プッシュ、クローズアウトの高速化、検証や再インストールの範囲の選択を求められた場合は、references/commit-paths.md を読みます
• リポジトリで git worktree を使用している場合、.git が別のディレクトリを指している場合、またはユーザーが複数のワークツリーに言及した場合は、references/worktrees.md を読みます

基本動作

• 事前確認と状態を変更する Git コマンドを分けます
• サンドボックスや権限に関する失敗と、マージコンフリクトを区別します
• ワークツリーは可視の作業ディレクトリ外にある共有 Git メタデータを書き換える場合があるため、特別なケースとして扱います
• reset --hard、checkout --、ブランチの削除、スタッシュの破棄などの破壊的な操作は、実行前に確認します
• 対話を必要としない Git コマンドを優先します
• リスクに応じてコミット手順を使い分け、リスクの低いテキストやドキュメントの変更に、完全な検証、完全なスモークテスト、スキルの完全な再インストールのコストをかけないようにします
• 通常のネットワークプッシュでは、cd repo && git push、bash -lc "git push"、相対形式と絶対形式の git -C の切り替えなど、場当たり的なコマンド形式より、安定したラッパー project-push <repo> <remote> <branch> を優先します。
• メインエージェントの判断時間を短縮でき、読み取り専用で実行できる場合は、複雑なクローズアウトに sidecar-task-runner の事前コミット分類を使用します
• サンドボックスによって書き込み操作がブロックされた場合は、その旨を明確に説明し、競合について推測するのではなく、権限のエスカレーションを依頼します
• ネットワーク Git 操作が失敗した場合は、ユーザーに認証情報の変更を求める前に、ネットワークやサンドボックスへのアクセスの問題と、認証、Git リモート、リポジトリの問題を区別します
• 早期に対応を開始します。ユーザーが曖昧な表現で Git の失敗を報告した場合は、状態を変更するコマンドを実行する前に、このスキルで原因を診断する必要があると判断します

起動の目安

次のいずれかに該当する場合は、すぐにこのスキルを使用します。

• ユーザーが git cherry-pick、merge、rebase、commit、stash、switch、checkout、branch、worktree の実行を求めた
• ユーザーが「Git が失敗した」「マージで問題が起きた」「cherry-pick がブロックされた」「競合がある」「このリポジトリがなぜこの状態になったのか」と述べた
• エージェントが、次の文字列を含むエラーメッセージを確認した：
  • CONFLICT
  • index.lock
  • operation not permitted
  • permission denied
  • Could not resolve host
  • Could not read from remote repository
  • Connection timed out
  • Network is unreachable
  • .git/worktrees/
  • ORIG_HEAD
  • CHERRY_PICK_HEAD
  • branch is already checked out

タスクが明らかに Git を中心とする場合は、書き込み操作が失敗するまでこのスキルの読み込みを待たないでください。

避けるべき誤診

Git によって実際に確認されていない限り、次のようなことは決して言わないでください。

• 実際には権限の問題なのに、「これはマージコンフリクトです」と言う
• 共通の Git ディレクトリが関係している可能性があるのに、「これは現在のワークツリー内だけの問題です」と言う
• 実際の問題が作業ツリーの未コミット変更、detached HEAD、または進行中の操作であるのに、「Git が壊れています」と言う
• 最初の失敗がサンドボックスによるネットワークまたは DNS の失敗なのに、「トークン、SSH キー、リモートに問題があります」と言う
• 競合、リポジトリの状態、サンドボックスのどれによるブロックなのか説明せずに、「そのまま再実行してください」と言う

ステップ 1 — リポジトリの状態を確認する

重要な Git 操作を行う前に、リポジトリの構成を確認します。

git rev-parse --show-toplevel
git rev-parse --git-dir
git branch --show-current
git status --short

ユーザーがワークツリーに言及した場合、または .git がディレクトリではなくファイルの場合は、次も確認します。

git worktree list
git rev-parse --git-common-dir

次の内容をまとめます。

• リポジトリのルート
• 現在のブランチ
• 作業ツリーに未コミットの変更があるか
• これがワークツリーかどうか
• 共有 Git メタデータが現在のディレクトリ外にあるか

ステップ 2 — 要求された操作を分類する

要求を次のいずれかのカテゴリとして扱います。

• inspect：ステータス、ログ、差分、ブランチ一覧、リモート、ワークツリーの構成
• network_inspect：fetch、pull、push のドライラン、ls-remote、サブモジュールの更新、または Git リモートに接続する Git 操作
• safe_write：add、commit、cherry-pick、merge、rebase、stash、ブランチの作成、ワークツリーの作成
• destructive_write：reset、ローカルの変更を上書きする checkout、clean、ブランチの削除、stash drop、強制 push

inspect の場合は、サンドボックスのルールで許可されていれば、コマンドを直接実行します。

network_inspect の場合は、ネットワーク権限が付与されない限り、サンドボックス化されたランタイムでは DNS や外部接続がブロックされることを想定してください。

safe_write の場合は、まず事前確認を行います。commit/push の完了処理では、references/commit-paths.md を使って変更を Fast Path、Skill Path、Code Path、Risk Path のいずれかに分類し、その経路に合った最小限の検証を実行します。

destructive_write の場合は、実行前にユーザーの明示的な確認を求めます。

ステップ 3 — 状態を変更する Git コマンドを実行する前に事前確認する

safe_write または destructive_write の前に、不注意な失敗処理を避けるために十分な状況を確認します。

git status --short
git branch --show-current
git rev-parse --short HEAD

通常の commit/push の完了処理では、Risk Path に該当する場合を除き、全体的な状況確認は避けてください。Fast Path の完了処理では、commit 前に git status --short、git diff --check、対象を明示した git add <files>、および git diff --cached --stat のみを使用できます。

cherry-pick、merge、または rebase の場合は、対象の commit またはブランチも事前に確認します。

git log --oneline --decorate -n 5
git show --stat --summary <target>

ワークツリーの場合は、共有メタデータの場所を確認します。

git rev-parse --git-common-dir

コマンドによってサンドボックスの書き込み可能なルート外にある共有 Git メタデータへ書き込まれる可能性が高い場合は、実行前にそのことをユーザーに伝え、権限の追加を求める準備をしてください。

ユーザーが cherry-pick、merge、commit など、ワークツリーに限定した書き込み操作を具体的に依頼した場合は、実行前に、ワークツリーのパスだけでなく共通の git dir への書き込みが必要になる可能性があることを明示してください。

ステップ 4 — 実行し、失敗を正しく解釈する

Git の書き込み操作が失敗した場合は、ユーザーに状況を伝える前に、失敗の種類を分類します。

references/failure-modes.md のガイダンスを使用してください。大まかなルールは次のとおりです。

• Git が CONFLICT、競合マーカーを報告した場合、またはファイルの解決を求めた場合は、コードの競合です。
• Git が operation not permitted、permission denied、ロックファイルの作成失敗、または refs やワークツリーのメタデータを更新できないことを報告した場合は、サンドボックスまたは権限の問題です。
• fetch、pull、push、ls-remote、またはサブモジュール操作中に Git が DNS エラー、API／ホストへの接続失敗、タイムアウト、またはネットワーク到達不能を報告した場合は、ネットワーク権限を付与して再実行するまで、ネットワーク／サンドボックスへのアクセスの問題です。
• Git が dirty 状態、未追跡ファイルの上書き、detached HEAD の不一致、または commit の欠落を報告した場合は、リポジトリの状態の問題です。

Git が実際に競合を報告していない限り、ユーザーに「競合があります」と伝えないでください。

DNS／ネットワーク／サンドボックスの制限により Git がホストに到達していない場合は、「認証に失敗しました」「SSH キーが間違っています」「リモートリポジトリがありません」とユーザーに伝えないでください。

ステップ 5 — サンドボックスの制限が本当の原因なら、適切にエスカレーションする

重要な書き込みコマンドがサンドボックスの制限によって失敗した場合：

1. 失敗はコードの競合ではなく、環境によるものだと伝えます
2. ブロックされた操作を明示します
3. 分かっている場合は、次のような書き込み先として考えられる場所を伝えます：
   • .git/index.lock
   • .git/worktrees/...
   • 共通 git ディレクトリ内の共有 refs
4. 権限の引き上げを依頼し、同じコマンドを再実行します

次のような表現を使います：

この git cherry-pick の失敗は、マージ競合ではなく、サンドボックスによる書き込み制限のようです。Git は共有 worktree メタデータを更新する必要があるため、権限を引き上げて再実行する必要があります。

DNS、API、またはホストへの接続がブロックされ、重要なネットワーク Git コマンドが失敗した場合：

1. 最初の失敗はネットワークまたはサンドボックスへのアクセスが原因であり、Git の認証やリモート設定の問題だと判明したわけではないと伝えます
2. git fetch、git push、git ls-remote など、コマンドを明示します
3. ネットワークの許可を依頼し、同じコマンドを再実行します
4. ネットワークを有効にして再実行した後に限り、認証情報、権限、リポジトリの不在、ブランチ、またはサーバー側のエラーとして分類します

次のような表現を使います：

この git ls-remote の失敗では GitHub まで到達していません。リポジトリがない、または SSH キーが不正という問題ではなく、サンドボックスによるネットワークアクセスのようです。認証情報を診断する前に、ネットワークの許可を得て再実行する必要があります。

コミット後の通常の push には、次の安定したラッパー形式を使います：

project-push <repo> <remote> <branch>

事前確認で見つかったブランチを使います。ラッパーが利用できない場合を除き、同じ push を cd <repo> && git push、git -C <repo> push、またはシェルでラップした形式に書き換えないでください。

ステップ 6 — worktree 固有のルール

リポジトリで worktree を使用している場合：

• commit、cherry-pick、merge、rebase などのコマンドは、現在の worktree ディレクトリの外部に書き込む可能性があると想定します
• 早い段階で git worktree list と git rev-parse --git-common-dir を確認します
• Git の書き込み先を確認するまでは、失敗が「この worktree 内だけ」のものだと断定しないでください
• 別の worktree が同じブランチを使用している可能性があるため、ブランチの削除やリセットには特に注意します

詳しい取り扱いルールについては、references/worktrees.md を読んでください。

ステップ 7 — 結果を正確に報告する

完了したら、次のいずれかの結果を明確に報告します：

• 成功
• 手動での解決が必要な競合
• サンドボックスまたは権限の制限
• ネットワークまたはサンドボックスの制限
• ユーザーの選択が必要なリポジトリの状態の問題

どの場合も、漠然とした Git の出力ではなく、次にユーザーが行うべき操作を伝えます。

よい例：

git cherry-pick <commit> はマージ解決に到達しませんでした。Git は共通 git ディレクトリ内の共有 worktree メタデータへの書き込みをブロックされたため、サンドボックスの問題です。次の手順は、権限を引き上げて同じコマンドを再実行することです。

悪い例：

cherry-pick に失敗しました。おそらく競合です

推奨する出力形式

ユーザーが「何が起きたの？」または「なぜ失敗したの？」と尋ねた場合は、次の構成で報告します：

Operation: <git command>
Classification: success | content conflict | sandbox restriction | network/sandbox restriction | repository state problem
Evidence: <the key git message or state observation>
Why it happened: <short explanation>
Next step: <single concrete next action>

分類の行は明確にしてください。ずさんな Git の診断を防ぐうえで、これが最も重要です。

このスキルで適切に扱うべきコマンド

• git status、log、diff、show、branch、remote
• git fetch、pull、push、ls-remote
• git add、commit、stash
• git cherry-pick
• git merge
• git rebase
• git switch、checkout、checkout -b
• git worktree list、git worktree add

特に注意が必要なコマンド

• git reset --hard
• git checkout -- <path>
• git clean -fd
• git branch -D
• git stash drop または clear
• git push --force

ユーザーの明示的な承認なしに、これらを実行しないでください。