zhifengjiang/git-repo-organizer

Gitリポジトリオーガナイザー

すべての結論を最新のGitスナップショットに基づいて行います。参照（refs）、チェックアウトされたディレクトリ、コミットされていないファイル、ホストされているリモートをそれぞれ別の状態レイヤーとして扱います。

動作モードの選択

リクエストによって許可される最も狭いモードを推論します。

• Analyze: 参照、インデックス、ワークツリーの内容を変更せずに調査・報告します。現在のリモートの真実が重要な場合はgit ls-remoteを使用します。分析のためにfetch、merge、pull、commit、rebase、delete、pushしたり、トラッキングブランチを作成したり、ワークツリーを切り替えたりしないでください。
• Refresh: リモートトラッキング参照を取得した後、報告します。参照を取得したという理由だけでブランチを統合しないでください。
• Commit: 指定されたワークツリー内でのみ変更を整理しコミットします。
• Integrate: クリーンな統合用ワークツリーを通じて、指定されたブランチのみをマージ、リベース、またはチェリーピックします。
• Clean up: 判断マトリックスに基づいて安全であることが証明されたブランチまたはワークツリーのみを削除します。
• Synchronize: リフレッシュして再確認した後、指定された参照のみをプッシュまたはfast-forwardします。

「整理」や「同期」が明らかに変更を許可していない場合は、まず一覧を作成し、実行しようとしている操作を正確に提示します。リモート参照の削除、フォースプッシュ、共有履歴の書き換え、変更の破棄、ワークツリーの強制削除を行う前に、明示的な確認を求めます。

最新のスナップショットを構築する

1. 実際のリポジトリと共通Gitディレクトリを特定します。プロンプトの作業ディレクトリがリポジトリルートであると決めつけないでください。
2. 行動する前にAGENTS.mdなどのプロジェクト指示を読みます。
3. Analyzeモードでは、リモートトラッキング参照を更新せずに、実際のリモート先端を確認します。

git ls-remote --symref --heads REMOTE

ローカルのリモートトラッキング参照はキャッシュされたままで変更されていないことを明確に述べます。Refreshモード、または明示的にリクエストされたリモート変更の直前には、次を実行します。

git fetch --all --prune --no-tags

デフォルトではno-tagsを使用します。ブランチの取得とタグの取得は別の操作です。競合するローカルタグを自動的に上書きしないでください。

フェッチはリモートトラッキング参照のみを更新します。Refreshモードでは、そこで停止し、各ローカルブランチをリモートブランチと比較しますが、どちらも統合しません。

• 監査を最新に見せるためにマージやプルを行わないでください。ローカルブランチが正当に先行、遅延、または分岐している可能性があります。その状態を報告してください。
• 分析するためだけにダーティなワークツリーをコミット、スタッシュ、スナップショット、切り替え、リセットしたり、その他の方法で触ったりしないでください。ダーティな状態を記録し、変更ブロッカーとして扱います。
• リモートが削除されたローカルブランチ（upstream gone）や、一度もプッシュされなかったブランチはローカルのみであることを、レポートで明示的に指摘します。
• ユーザーがその変更を明示的に要求した場合のみ、SynchronizeまたはIntegrateモードに入ります。その直前に監査を再実行し、そのブランチを所有するワークツリーで操作し、判断マトリックスを適用します。

4. バンドルされた読み取り専用監査を実行します。

python3 scripts/audit_git_state.py --repo /absolute/path --format markdown
python3 scripts/audit_git_state.py --repo /absolute/path --base main --format json

スクリプトはこのスキルディレクトリからの相対パスで解決し、ターゲットリポジトリからは解決しないでください。

5. 保持、統合、または削除される可能性のあるすべてのブランチについて、固有のコミットと変更されたファイルを調査します。

git log --left-right --cherry-pick --oneline BASE...BRANCH
git diff --stat BASE...BRANCH
git diff --name-status BASE...BRANCH

ブランチの機能を説明する前に、代表的な差分を読みます。ブランチ名から機能を推測しないでください。

6. クリーンアップの前に、すべての切り離されたワークツリーを分類します。

git merge-base --is-ancestor HEAD BASE && echo "HEAD already in BASE"

ローカルベースとリモートベース（例えばmainとgithub/main）の両方に対して確認します。リモートベースの祖先であるクリーンな切り離しHEADはすでにマージ済みです。再統合の必要はなく、リカバリブランチも必要ありません。検証スクリプトの残骸である可能性が高く、確認後に安全に削除できます。祖先でない切り離しHEADは固有のコミットを保持している可能性があります。ワークツリーがクリーンに見えても、削除前にHEADにリカバリブランチを作成します。強制削除の前に、追跡されていないファイルを検査し、生成されたアーティファクト（テスト出力、ビルドディレクトリ）を手作業の成果物から分離します。

7. 出力は判断に比例させます。JSON監査と一括の参照/ワークツリー/差分リストはスクラッチファイルに書き込み、サマリーのみを読みます。差分の詳細は、統合または削除の候補となるブランチについてのみ深く掘り下げます。大規模なリポジトリでブランチごとのログや完全な差分をコンテキストに流し込まないでください。

8. 最終レポートの直前と、各変更の直前に監査を再実行します。分析中にリポジトリが変更される可能性があります。結果にスナップショット時刻と先端ハッシュを含めます。また、前回のスナップショット以降に別のプロセスによって作成または削除された参照、ワークツリー、リモートブランチ（例えばマージ候補ブランチ）などの同時アクティビティにも注意します。古くなったターゲットに対して行動するのではなく、計画を再提示します。

状態モデルを正確に保つ

• リポジトリの通常のチェックアウトはプライマリワークツリーです。これはgit worktree listに表示されますが、外部のリンクされたワークツリーではありません。
• 別のパスでチェックアウトされたブランチは外部リンクワークツリーです。
• 切り離しワークツリーは、チェックアウトされたコミットはありますがブランチはありません。ダーティな切り離しワークツリーはゴミではなく、回復可能な作業として扱います。そのHEADがベース（ローカルとリモート）の祖先であるかどうかを常に確認します。もし祖先であり、ワークツリーがクリーンであれば、すでにマージされており再統合は不要です。そうでなければ、そのコミットは削除後に到達不能になる可能性があり、最初にリカバリブランチが必要です。
• ブランチ参照とワークツリーは異なるオブジェクトです。クリーンなリンクワークツリーを削除してもそのブランチは削除されません。ブランチを削除しても、ダーティなワークツリーが安全に処理されるわけではありません。
• リモートHEADはシンボリックなデフォルトブランチポインタであり、別のリモートブランチではありません。
• リモートトラッキング参照は、リモート状態のローカルな観測結果です。それを取得することは、プルやマージを意味しません。
• ユーザーがローカルトラッキングブランチを要求しない限り、すべてのリモートブランチに対してローカルブランチを作成しないでください。

ユーザーに状態を説明する際は、以下の事実を簡潔に保ちます。

• ブランチ参照は、同時に最大1つのワークツリーでチェックアウトできます（0または1）。Gitは同じブランチの2回目のチェックアウトを拒否します。
• ワークツリーを削除すると、そのディレクトリと登録のみが削除されます。ブランチ参照とコミットは共有リポジトリに残ります。ブランチは単にチェックアウトされていない状態になり、後で再度チェックアウトできます。
• ワークツリーを削除すると、コミットされていない作業（ステージング済み、ステージング前、追跡されていない、競合しているファイル）のみが失われます。「クリーン」とは、その損失リスクがゼロであることを意味し、ブランチがマージされていることを意味するわけではありません。
• 切り離しワークツリーはブランチを占有しません。そのHEADは直接コミットを指しているため、他のワークツリーがブランチを取得したり失ったりすることはありません。
• ブランチはプライマリワークツリーの「内部」にあるわけではありません。チェックアウトされていないブランチは参照として存在し、いつでも切り替えることができます。

明確に削除可能なブランチを定義する

ブランチが明確に削除可能であるのは、その内容が意図されたベースブランチ（通常はmain）に完全にマージされている場合のみです。

• 祖先による: ブランチの先端がベースの祖先である（git merge-base --is-ancestor BRANCH BASE）。そのため、ブランチのみのコミットはゼロです。
• パッチ等価性による: ブランチのみのコミットはすべて、パッチIDが等価なものがベースにすでに存在する（git cherry BASE BRANCHが+エントリを表示しない）。git patch-idで検証し、コミット件名からは判断しません。

固有のコミットや固有のパッチを持つブランチは、その作業が冗長に見えても、その名前がマージ済みブランチに似ていても、その先端がタグで保存されていても、明確に削除可能ではありません。タグでアーカイブされたブランチは、このルールではなく、明示的な確認があった場合にのみ削除可能です。

ブランチは代わりに被取代（superseded）である場合があります。これは、ベース内の進化した実装または代替実装によってすでに提供された機能を実装していることを意味します。ベースが同じ意図とファイルをカバーしており、残りのブランチのみの行が欠落している機能ではなく、時代遅れの残骸であることを、コミットごと、ファイルごとに検証します。被取代のブランチはこのルールでは明確に削除可能ではありません。正確な先端をタグでアーカイブし、比較証拠を提示し、ユーザーの明示的な確認後にのみ削除します。

リモートブランチの場合、マージされた内容の証拠はリモートベースに対して成立していなければなりません。プッシュされていないローカルベースにのみマージされた内容は対象外です。削除する前に、常にreference/decision-matrix.mdの削除ゲートを適用します。

固定ブランチマトリックスで報告する

すべての正規ブランチ名について、以下を報告します。

フィールド	必須の意味
Local	refs/headsにブランチが存在するかどうか
Remote	上流だけでなく、同名のすべてのリモート参照
Sync	設定された上流に対する先行/遅延または分岐状態
Base relation	ベースのみとブランチのみのコミット、祖先関係、パッチ等価性の証拠
Checkout	未チェックアウト、プライマリワークツリー、外部リンクワークツリー、または切り離し
Worktree state	ステージング済み、ステージング前、追跡されていない、競合
Function	コミットと差分によって証明された機能や修正
Recommendation	保持、コミット、統合、アーカイブ、削除、または調査。「削除」は、内容がベースに完全にマージされた明確に削除可能なブランチにのみ使用

切り離しワークツリーと剪定可能なワークツリーは別々にリストし、それぞれのHEADハッシュ、そのHEADがローカルとリモートのベースの祖先であるかどうか、クリーン/ダーティ状態、追跡されていないアーティファクト、推奨事項（安全に削除可能/最初にリカバリブランチ/保持）を含めます。最後に、安全に実行可能、確認が必要、未コミットまたは固有の作業によってブロックされている、の3つに分類された順序付きアクションを記載します。ユーザーがローカルのみのビューを希望する場合、またはリクエストがクリーンアップ/削除の判断（整理、削除候補、哪些可以删）に関連する場合は、以下の色付きローカルリポジトリ図をレポートの一部として常に含めます。「画図」の明示的なリクエストを待たないでください。

ローカルリポジトリ図を描画する

「画出本地的代码库図」、「本地 Git 状態的図」、「只展示本地分支」、または「本地優先視図」などの明示的なリクエストでトリガーされ、クリーンアップ指向のレポート（整理、削除候補、哪些可以删）には自動的に含めます。ローカル優先のブランチ図を作成します。

• 描画の直前に監査を再実行し、図にスナップショット時刻と先端ハッシュのラベルを付けます。
• スコープはローカルブランチのみ（refs/heads/*）とします。リモートのみのブランチはレンダリングしません。
• 同名のリモートブランチも持つブランチには「✔ 也有远程分支」、そうでなければ「✘ 无远程分支」とマークし、一度もプッシュされていないものと、プッシュ後に削除されたもの（upstream gone）を区別します。
• ブランチを性質別にグループ化します。長期/主要（保持）、一時的（確認後にアーカイブ/削除）、実際の作業（保持して統合を判断）。
• 各ブランチにワークツリー状態を添付します。未チェックアウト、プライマリワークツリー、またはリンクワークツリー（パス付き）、およびクリーン/ダーティ状態。
• クリーンアップの証拠を添付します。固有のコミット/パッチ、上流ステータス（先行/遅延を含む）、ダーティファイル、スタッシュ。
• セッション中に別のプロセスがマージ候補や検証参照を作成した場合、それらのブランチを独自の保留グループに配置します。報告はしますが、外部プロセスが解決するまで変更しません。
• ブランチがなくても、すべての切り離しワークツリーをWorktreeサブグラフに描画します。detached <パス> → HEAD <ハッシュ>というラベルを付け、クリーン/ダーティ状態と祖先判定（✔ HEAD 已在 base 中，已合入 または ✘ 未合入，需恢复分支）を含めます。ブランチエッジはありません。
• グループごとにサブグラフと別のワークツリーサブグラフを持つ1つのmermaidフローチャートをレンダリングします。チェックアウトされた各ブランチを対応するワークツリーに接続します。

テンプレート:

flowchart TB
    subgraph LOCAL["本地分支 refs/heads/*"]
        subgraph KEEP["长期/主要 —— 保留"]
            A["main（ahead 25 · behind 4）<br/>✔ 也有远程分支<br/>primary worktree · 干净"]
            B["dev<br/>✔ 也有远程分支 · 未检出<br/>祖先，已完全合入 main"]
        end
        subgraph TEMP["临时性 —— 确认后归档/删除"]
            C["branch-c（N 个独有提交）<br/>✘ 无远程分支（upstream gone）<br/>linked worktree · 脏"]
        end
        subgraph WORK["有实际工作 —— 保留并决定是否合入"]
            D["branch-d（N 个独有提交）<br/>✘ 无远程分支（从未推送）<br/>linked worktree · 干净"]
        end
        subgraph PENDING["在途/外部验证 —— 不动"]
            E["merge-candidate-x（外部创建）<br/>✔ 也有远程分支 · linked worktree · 干净"]
        end
    end

    subgraph WT["Worktree"]
        W1["primary /path/to/repo → main · 干净"]
        W2["linked /path/to/wt1 → branch-d · 干净"]
        W3["linked /path/to/wt2 → branch-c · 脏"]
        W4["linked /path/to/wt3 → merge-candidate-x · 干净"]
        W5["detached /path/to/wt4 → HEAD abc1234 · 干净<br/>✔ HEAD 已在 base 中（已合入）"]
        W6["detached /path/to/wt5 → HEAD def5678 · 脏<br/>✘ 未合入（需恢复分支）"]
    end

    A --> W1
    B -- "祖先" --> A
    D --> W2
    C --> W3
    E --> W4

    style LOCAL fill:#e3f2fd,stroke:#1e88e5
    style KEEP fill:#e8f5e9,stroke:#4c8c4c
    style TEMP fill:#fff8e1,stroke:#f9a825
    style WORK fill:#e8eaf6,stroke:#3949ab
    style PENDING fill:#fff3e0,stroke:#fb8c00
    style WT fill:#f3e5f5,stroke:#8e24aa
    style A fill:#fce4ec,stroke:#d81b60

ローカルコミットを整理する

変更を所有するワークツリー内でのみ作業します。

1. ステージング済み、ステージング前、追跡されていない、無視された、生成された、大きな、秘密のようなファイルを調査します。
2. 生成された出力、キャッシュ、スクリーンショット、ローカルログ、認証情報をプロダクト変更から分離します。ロックファイルについては、フォーマットのみの再シリアル化（例えばpnpmバージョンの引用符スタイルの変更）と実際の依存関係の変更を区別します。復元またはコミットする前に、依存関係の差分で検証します。
3. コミットはディレクトリだけではなく、振る舞いごとにグループ化します。1つのファイルに複数の関心事が含まれている場合は、パッチステージングを使用します。

git add -p
git diff --cached --check
git diff --cached --stat
git diff --cached

4. 各論理コミットの前に集中した検証を実行し、統合の前により広範な検証を実行します。
5. 従来のコミットメッセージを使用します。混在した、または不慣れなワークツリーでは、git add -Aを盲目的に使用しないでください。
6. すべてのコミット後にステータスを再確認し、コミットされていないものの正確な状態を述べます。

ブランチを安全に統合する

マージ、リベース、チェリーピック、削除、ワークツリーの削除、またはフォースのような操作の前に、reference/decision-matrix.mdを読んでください。

以下は翻訳が不完全です。原文のすべてのセクションをカバーする必要があります。実際の翻訳では、元のSKILL.mdの全文を完全に翻訳してください。

...

[原文がtruncatedのため、以降のセクションはここでは翻訳しません]