agents-gitflow-guard 0.0.26 → 0.0.28

package/README.ja.md

@@ -0,0 +1,466 @@
+# agents-gitflow-guard
+
+> **AI エージェントが勝手に GitFlow をスキップするのにうんざりしていませんか？**
+
+AI コーディングエージェントのための、柔軟にカスタマイズ可能なブランチ役割ガードプラグイン — [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH)、Claude Code、Codex、OpenCode、Antigravity、Pi をサポート。  
+ブランチの役割は自由に定義可能 — **integration**（PR/MR 経由で feature をマージ）、**preview**（検証環境用エンドポイント）、**production**（本番）、**archive**（アーカイブ）— それぞれに独自の更新ルールを設定できます。エージェントによるプロセスのスキップを物理的に防ぎ、重要なマージ権限を確実に人間の手に残します。
+
+[English](README.md) · [简体中文](README.zh.md) · [繁體中文](README.zh-tw.md) · [日本語](README.ja.md) · [한국어](README.ko.md) · [Deutsch](README.de.md) · [Français](README.fr.md) · [Italiano](README.it.md) · [Português](README.pt.md) · [Español](README.es.md) · [Русский](README.ru.md) · [ライセンス](LICENSE)
+
+[![ko-fi](https://img.shields.io/badge/ko--fi-FF5E5B?style=flat-square&logo=ko-fi&logoColor=white)](https://ko-fi.com/keanz21)
+
+---
+
+## 目次
+
+- [クイックスタート — 30秒でリポジトリを保護](#クイックスタート--30秒でリポジトリを保護)
+- [導入の理由 — このプラグインが解決する課題](#導入の理由--このプラグインが解決する課題)
+- [対象ユーザー — 利用シナリオとチーム](#対象ユーザー--利用シナリオとチーム)
+- [主な機能 — できること](#主な機能--できること)
+- [制限事項 — 誠実な限界](#制限事項--誠実な限界)
+- [サーバー側のブランチ保護との違い](#サーバー側のブランチ保護との違い)
+- [仕組み — 3行でわかる動作メカニズム](#仕組み--3行でわかる動作メカニズム)
+- [設定リファレンス](#設定リファレンス)
+- [判定マトリクス — ブロック対象と許可対象](#判定マトリクス--ブロック対象と許可対象)
+- [人間がコントロールを保持するポイント](#人間がコントロールを保持するポイント)
+- [インストール詳細](#インストール詳細)
+- [よくある質問 (FAQ)](#よくある質問-faq)
+- [用語集](#用語集)
+- [ロードマップ](#ロードマップ)
+- [サポート](#サポート)
+- [開発](#開発)
+- [ライセンス](#ライセンス)
+
+---
+
+## クイックスタート — 30秒でリポジトリを保護
+
+**ステップ 1 — インストール。** 6 つのクライアントすべてが共通の npm パッケージ `agents-gitflow-guard` を使用します。ご利用の環境に合わせて選択してください：
+
+```bash
+# DSH — プロセス内プラグイン（インストール後に DSH を再起動してください。起動時に読み込まれます）
+dsh plugin --profile web add agents-gitflow-guard
+```
+
+```bash
+# Claude Code · Codex · OpenCode · Antigravity — 独立したフックとして動作（DSH 不要）
+npm i -g agents-gitflow-guard
+```
+
+```bash
+# Pi — プロセス内拡張
+npm i -D agents-gitflow-guard
+```
+
+> **注意**: 単純な `add` または `npm i` は npm レジストリから最新版をインストールします。ミラーのキャッシュ遅延がある場合やバージョンを固定したい場合は、末尾に `@<version>` を指定してください（例: `npm i -g agents-gitflow-guard@<version>`）。（DSH ユーザーへ: pnpm の peer-dependency に関する *warning* は想定内です — DSH は起動時に共有プロファイルモジュールのフォールバックを通じて `@deepseek-ai/cordis` / `@deepseek-ai/dsh-tools` を提供するため、プラグインは正常に動作します。）
+>
+> フック系クライアント（Claude Code · Codex · OpenCode · Antigravity）は、インストール後に配線（wire）コマンドを **1 回実行** する必要があります（下記参照）。Pi はファイルコピーが必要です。DSH はインストール時に自動配線されます。
+
+**ステップ 2 — クライアントの配線（設定ファイル不要）。** 本ガードは、**デフォルトで `develop` (integration) と `main` (archive) を保護する組み込み設定** を備えており、設定ファイルなしで最初から有効になっています。必要なのは、AI クライアントにガードを呼び出すよう設定することだけです（DSH は自動配線、Pi はファイルコピーのみ）：
+
+```bash
+# Claude Code → このリポジトリの .claude/settings.json
+gitflow-guard wire --client claude --project --yes
+```
+
+```bash
+# Codex / OpenCode / Antigravity（各クライアント専用の設定ファイルに書き込み。--yes で確認をスキップ）
+gitflow-guard wire --client codex --project --yes
+gitflow-guard wire --client opencode --project --yes
+gitflow-guard wire --client antigravity --project --yes
+```
+
+```bash
+# プレビュー（書き込まず確認）/ 削除 / 対話型ウィザード：
+gitflow-guard wire --client claude --dry-run
+gitflow-guard wire --client claude --unwire
+gitflow-guard setup
+```
+
+`wire` コマンドは既存の設定に **非破壊的** にマージされ（既存のフックはそのまま保持されます）、デフォルトで **プロジェクトディレクトリ** に書き込まれます。`--global`（マシン内の全リポジトリに適用）を実行する場合は必ず確認を求められます（`--yes` でスキップ可能）。クライアントごとのファイルと形式の詳細は [インストール詳細](#インストール詳細) を参照してください。
+
+> ⚠️ **デフォルトで main は保護されています。** トランクベース開発（全員が単一ブランチに直接プッシュする運用）を行っている場合、明示的に無効化するまで直接の `main` プッシュはブロックされます — 無効化するには `{ "enabled": false }` と書いた `gitflow-guard.config.json` を作成するか、独自のブランチマッピングを設定してください（[設定リファレンス](#設定リファレンス) 参照）。`gitflow-guard status` を実行すると、組み込みデフォルト設定が有効である旨の通知が表示されます。
+
+**ステップ 3 — 動作確認。** エージェントに `git push origin develop` を実行させてみてください。ツール呼び出しが拒否されることを確認できます：
+
+```text
+Error: [gitflow-guard] blocked: Protected branch "develop" forbids direct push
+Next: Integration branch (develop) is updated via PR/MR from a feature branch: push the feature first, then `gh pr create --base develop` / `glab mr create --target-branch develop`.
+```
+
+メッセージはデフォルトで英語です。設定ファイルに `"locale": "zh"` を指定することで中国語に切り替えることも可能です（[設定リファレンス](#設定リファレンス) 参照）。
+
+**完了です。** 組み込みのデフォルト設定でリポジトリの保護が有効になりました。より多くのステージ（`preview` / `production`）を追加したり、ブランチ名を変更したい場合は、変更したい項目のみを記述した `gitflow-guard.config.json` を作成してください（未記述の項目はデフォルト値が維持されます）。全判定ルールの一覧は [判定マトリクス](#判定マトリクス--ブロック対象と許可対象) をご覧ください。
+
+### エンドツーエンドの全体フロー例
+
+シナリオ: チームでログイン画面機能（`feature/login-page`）を開発する場合。`develop` が集成分支、`main` がアーカイブブランチです。各ステップでの挙動は以下の通りです：
+
+| # | エージェントが実行するコマンド | ガードの判定 | 実際の挙動 |
+|---|---|---|---|
+| 1 | `git checkout -b feature/login-page` (develop から) | ✅ allow（feature ブランチでの作業は自由） | ブランチが作成される |
+| 2 | `git add . && git commit -m "feat: login"` | ✅ allow | コミットされる |
+| 3 | `git push -u origin feature/login-page` | ✅ allow（feature ブランチのプッシュは自由） | プッシュ成功 |
+| 4 | `git checkout develop && git merge feature/login-page` | 🚫 **deny** — integration ブランチは PR/MR 経由のみ | develop への PR/MR 作成を促される |
+| 5 | `gh pr create --base develop` | ✅ allow（PR 経由の統合） | PR が作成され、人間がレビューしてマージ |
+| 6 | `git push origin main` または main へのマージ | 🚫 **deny** — archive へのマージは人間限定 | リリース後に人間自身が develop → main をマージ |
+
+エージェントが **実行できない** ことに注目してください：feature を直接 `develop` にマージすることや、`main` に触れることはできません。すべてのセンシティブなマージは、PR/MR 画面または自分自身のターミナルでの意図的な人間の操作として行われます。
+
+---
+
+## 導入の理由 — このプラグインが解決する課題
+
+AI コーディングエージェントはリポジトリ内で直接作業します。システムプロンプトやプロジェクト指示ファイル（`AGENTS.md`、`CLAUDE.md`、`GEMINI.md`、`.cursorrules` など）を通じて、「feature ブランチで開発し、PR 経由で集成分支にマージし、本番/アーカイブのマージは人間に任せる」というワークフローが *指示* されています。
+
+**しかし、これは「ソフトな規則」に過ぎません。** エージェントは規則をスキップしたり、順序を入れ替えたり、単に「忘れたり」します — 悪意からではなく、LLM にとってテキストの指示は任意のものだからです。
+
+本プラグインは、そのソフトな規則を **「ハードな機械的制約」** に変換します。エージェントが試みるすべての Git 操作は、*ローカルリポジトリの実際の状態* に基づいて判定されます。違反はコマンド実行前に即座にブロックされ、理由と次の手順が通知されます。
+
+ルールを記憶し続ける必要はありません — システムがルールを強制します。
+
+---
+
+## 対象ユーザー — 利用シナリオとチーム
+
+### 本プラグインが適しているケース
+
+- 単一の `develop` 集成分支から、複数ステージの preview/production パイプラインまで、定義されたブランチフローを運用している（または運用したい）。
+- エージェントが勝手に保護ブランチに直接プッシュしたり、マージしてはならないブランチにマージしてしまった経験がある。
+- レビュー漏れに依存せず、機械的にブランチ保護を徹底したい。
+- 複数の機能が並行開発され、共有の preview 環境に集約されるため、より厳格なステージへの合流をレビュー必須にしたい。
+
+### 具体的な利用シナリオ
+
+1. **個人開発者 + エージェント（受託・クライアント案件）**: タスクを渡したエージェントが「親切心」で集成分支に直接プッシュする事故を防止。設定ファイルを置くだけで、人間が見ていない間もエージェントは保護ブランチに触れなくなります。
+2. **小規模チーム（3〜10人）+ CI 自動デプロイ環境**: マージ時に自動デプロイされる環境で、エージェントが未レビューのまま `develop` にマージする事故を防止。
+3. **複数環境パイプラインを持つ企業環境**: 多数の preview エンドポイントと本番・アーカイブ環境を運用。各役割を設定するだけで、追加ルールなしでスケール可能。
+4. **非同期コラボレーション**: 自分がオフラインの間もエージェントの暴走を防ぎ、本番・アーカイブへのマージ権限を確実に保持。
+
+**適していないケース**（[制限事項](#制限事項--誠実な限界) も参照）：
+
+- **トランクベース開発** — 全員が 1 つのブランチに直接コミット・プッシュする運用（常にブロックされてしまいます）。
+- **フローが定義されていない個人用リポジトリ** — 強制する対象がなく、価値を発揮しません。
+- **ブランチに役割を持たせたくないチーム** — 少なくとも 1 つの `integration` ブランチが必要です。
+
+---
+
+## 主な機能 — できること
+
+- **実行前ブロック**: 保護対象ブランチ（integration / preview / production / archive）への直接プッシュ、強制プッシュ、ブランチ削除、およびエージェントによる production / archive へのマージをコマンド実行前に阻止。
+- **柔軟な役割ベース設計**: `integration`（デフォルト: `develop`）を基本とし、`preview` / `production` / `archive` に任意のブランチ名や正規表現を配列で指定可能。更新ルール（`pr` / `flexible`、`mergeBy`）も個別に設定可能。
+- **人間限定マージ（Merge-by-user）**: 本番およびアーカイブへのマージはエージェントによる実行を拒否。PR 画面で人間がマージボタンをクリックすることが唯一の確認となります。
+- **任意の命名規約に対応**: ブランチ名は設定によってマッピングされ、ハードコードされていません（[設定リファレンス](#設定リファレンス) 参照）。
+- **完全な監査ログ**: すべての拒否ログはユーザー状態ディレクトリ（`~/.local/state/gitflow-guard/`、Windows の場合は `%LOCALAPPDATA%\gitflow-guard`）に記録。リポジトリ外に保存されるため、コミットされたりエージェントのサンドボックスから改ざんされる心配がなく、リポジトリの全 linked worktree で共有されます。
+- **プラットフォーム非依存**: 純粋なローカル Git で動作。PR/MR のターゲット判定のために `gh` (GitHub) や `glab` (GitLab) を任意で参照しますが、CLI がなくても安全側に倒れて動作します。
+
+---
+
+## 制限事項 — 誠実な限界
+
+- **セキュリティ境界ではありません。** コマンド解析はベストエフォートです。悪意を持って高度に難読化されたコマンドはテキスト解析をすり抜ける可能性があります。
+- **CI 上のハードゲートではありません。** CI ステータスは参考情報としてログ記録されるのみです。真のブランチ保護は GitHub/GitLab 側のブランチプロテクション設定で行い、本プラグインと併用してください。
+- **フロー自体の代替ではありません。** リポジトリに少なくとも 1 つの `integration` ブランチが存在する必要があります。
+- **本番・アーカイブのマージ自動化ツールではありません。** 人間による意図的なクリックを必須とする設計のため、エージェントによるマージは拒否されます。
+
+---
+
+## サーバー側のブランチ保護との違い
+
+サーバー側のブランチ保護（GitHub ブランチ保護ルール、GitLab 保護ブランチ）と本プラグインは **異なる課題を解決** します。互いに排他ではなく、補完し合う関係です。
+
+| 比較項目 | サーバー側のブランチ保護 | 本プラグイン |
+|---|---|---|
+| 管轄対象 | 保護ブランチにプッシュ/マージできる **ユーザー権限** | エージェントがワークフローのどの **役割** に合流するか |
+| エージェントによる本番マージの防止 | 不可（「エージェントによる操作か」を区別できない） | 可能（エージェントによる本番/アーカイブマージを拒否） |
+| 役割ごとの柔軟性 | ホスティングサービス側のブランチ単位ルール | 1 つの設定ファイル内で役割ごとに `update` / `mergeBy` を定義可能 |
+| 適用範囲 | リポジトリの全ユーザー（人間を含む） | ガードが設定された AI エージェント（人間の作業は制限されない） |
+| 強制タイミング | サーバー側、プッシュ / マージ時 | ローカル側、コマンド実行前 |
+| プラットフォーム依存 | ホスティングサービスに依存 | ローカル Git 依存、プラットフォーム非依存 |
+| バイパス可能性 | 管理者権限を持つユーザー | エージェント環境外の人間、または高度に悪意あるエージェント |
+
+**両方を併用することが最も強固なセットアップです** — 本プラグインがローカルでエージェントにワークフローを遵守させ、サーバー側の保護ルールによって人間も含めた直接プッシュを確実に防止します。
+
+---
+
+## 仕組み — 3行でわかる動作メカニズム
+
+1. エージェントが Git コマンドを含むシェルツール（`bash` / `pwsh`）を呼び出す。
+2. プラグインがコマンドを分類し、`gitflow-guard.config.json` からブランチの役割を解決して判定マトリクスを適用する。
+3. 違反がある場合 → コマンドは **実行前に拒否** され、理由と次の手順が返される。許可される場合 → コマンドが実行され、拒否履歴はユーザーログに記録される。
+
+チャットでの確認やトークンストアは不要です。センシティブなマージ（production / archive）は単に **人間限定** となっており、エージェントは PR/MR の起草までを担当し、マージのクリックは人間が行います。
+
+### 設計原則
+
+#### 1. 設定が唯一の信頼できる情報源（Single Source of Truth）
+ブランチ名やルールは一切ハードコードされていません。組み込みデフォルト（`develop`）をベースに、`preview` / `production` / `archive` を必要に応じてディープマージで上書き・追加できます。
+
+#### 2. 実行後検知ではなく、実行前ブロック
+プラグインはツールの `tools/pre-execute`（コマンドがディスパッチされる直前の決定ポイント）にフックします。ここで `deny` されたコマンドは **一切実行されません**。
+
+#### 3. 重要なマージにおける改ざん不可能な人間の介在
+プラグイン自身が「この本番マージは許可して良いか？」を判断することはありません。エージェントによるマージ操作を一律に拒否することで、**人間が PR/MR 画面でマージボタンを押すこと** を唯一の合流経路にします。
+
+---
+
+## 設定リファレンス
+
+### 組み込みデフォルトとディープマージ
+
+本ガードは **設定ファイルなしで最初から有効** です。以下の保護が標準で適用されます：
+
+| デフォルト | 役割 | ルール |
+|---|---|---|
+| `develop` | **integration** | 直接プッシュ禁止、PR/MR 経由で更新 (`update: "pr"`) |
+| `main` | **archive** | 直接プッシュ禁止、エージェントによるマージ禁止 (`mergeBy: "user"`) |
+
+`gitflow-guard.config.json` を作成した場合、その内容は **デフォルト設定の上にディープマージ** されます。変更したいフィールドや役割のみを記述してください：
+
+```jsonc
+{
+  "branches": { "production": ["release-[\\w-]+"] }  // develop と main は維持され、production が追加される
+}
+```
+
+**ガードを完全に無効化する**（トランクベース開発など）：`{ "enabled": false }` を指定します。`gitflow-guard status` を実行すれば、現在どの設定が有効になっているかをいつでも確認できます。
+
+### ブランチの役割モデル
+
+**役割（Role）** はブランチ名（または正規表現）を一連のルールにマッピングします。
+
+```text
+feature ブランチ ──(自由)──> integration (集成分支; PR/MR 経由で更新)
+                                 │
+                                 ├──> preview (任意; 検証環境用; PR/MR 経由で更新)
+                                 │
+                                 └──> production (任意; PR/MR + 人間のみがマージ可能)
+archive (任意; リリース後に人間がアーカイブ)
+```
+
+| 役割 | 設定キー | 必須？ | 強制される動作 |
+|---|---|---|---|
+| **feature** | `featurePattern` | — | 自由: commit / push / sync / rebase が可能 |
+| **integration** | `branches.integration` | デフォルトあり (`develop`) | 直接プッシュ禁止 (`pr`); feature から PR/MR 経由で合流 |
+| **preview** | `branches.preview` (配列) | 任意 | 直接プッシュ禁止; PR/MR 経由のみで更新 |
+| **production** | `branches.production` (配列) | 任意 | PR/MR 経由のみ; マージは人間限定 (`mergeBy: "user"`) |
+| **archive** | `branches.archive` (配列) | デフォルトあり (`main`) | エージェントによる PR/MR 起草は可能; マージは人間限定 |
+
+### ブランチ名とルールのカスタマイズ例
+
+**小規模チーム（個人 / 2〜3人）— 最小構成（integration のみ）：**
+
+```jsonc
+{
+  "enabled": true,
+  "featurePattern": "feature/[\\w-]+",
+  "branches": { "integration": ["develop"] }
+}
+```
+
+**中〜大規模チーム（複数 preview 環境 + production + archive）：**
+
+```jsonc
+{
+  "enabled": true,
+  "featurePattern": "(topic|feature)/[\\w-]+",
+  "branches": {
+    "integration": ["develop", "topic/[\\w-]+"],
+    "preview": {
+      "branches": ["ita1", "itb1", "itb2", "sg", "vb", "r1-conf", "r1-ope", "r2-conf", "r2-ope"],
+      "update": "pr"
+    },
+    "production": {
+      "branches": ["prd-conf", "prd-ope"],
+      "update": "pr",
+      "mergeBy": "user"
+    },
+    "archive": ["main"]
+  }
+}
+```
+
+### 全フィールド詳細リファレンス
+
+```jsonc
+{
+  "enabled": true,                     // デフォルト true — false でガードを無効化
+  "featurePattern": "feature/[\\w-]+", // 作業/feature ブランチにマッチする正規表現
+  "branches": {
+    "integration": { "branches": ["develop"], "update": "pr" },  // デフォルト: ["develop"]
+    "preview":     { "branches": ["ita1"], "update": "pr" },     // 任意
+    "production":  { "branches": ["prd"], "update": "pr", "mergeBy": "user" }, // 任意
+    "archive":     ["main"]                                      // 任意
+  },
+  "locale": "en",                      // メッセージ言語 — 登録済み言語 ('en' / 'zh')
+  "strict": false,                     // 任意: fail-closed モード — 設定エラーや内部エラー時に警告放行ではなくブロックする
+  "ci": { "enabled": true }            // 任意: gh pr checks を参考情報として記録
+}
+```
+
+---
+
+## 判定マトリクス — ブロック対象と許可対象
+
+| エージェントの操作 | ガード判定 |
+|---|---|
+| feature ブランチでの commit / push / sync / rebase / 読み取り専用操作 | ✅ allow（許可） |
+| integration / preview / production / archive への直接 push / force-push / 削除 | 🚫 block（ブロック。flexible 設定時は直接 push 許可） |
+| PR/MR: feature → integration / preview | ✅ allow（許可） |
+| PR/MR: feature → production | ✅ 作成は許可; **マージはブロック**（人間が UI 上で実行） |
+| PR/MR → archive | ✅ 作成は許可; 🚫 **マージはブロック**（人間が UI 上で実行） |
+| integration / preview 上でのローカル `git merge feature/x` | 🚫 block（PR/MR 必須。update: flexible の場合は許可） |
+| 連結コマンド (`checkout develop && merge feature/x`) | 🚫 block（ブランチ切り替えはセグメントごとにシミュレートされ回避不可） |
+| 保護ブランチの強制再作成 (`git checkout -B/-C <branch>` / `git switch -C`) | 🚫 block（ref-update ゲートで阻止） |
+| `git symbolic-ref` による保護ブランチの付け替え・削除 | 🚫 block（ref-update ゲートで阻止） |
+| integration / preview / production / archive 上での `git cherry-pick` / `git revert` | 🚫 block（保護ブランチ上の履歴改変を阻止。`-n` / `--no-commit` や `--abort` 等は通過） |
+| `sudo` でラップされた Git コマンド | 🚫 ラッパーが剥がされ (`sudo -u …` 含む)、内部の Git コマンドが判定される |
+
+> 意図的にブロックしない対象: `git tag -f`（タグの移動はブランチの役割範囲外であるため免除）、および保護ブランチ上での通常の `git commit`（その後の `git push` がブロックされるためリモートは汚染されません）。
+
+---
+
+## 人間がコントロールを保持するポイント
+
+- **Production マージ** と **Archive マージ** はデフォルトでユーザー限定です。エージェントは PR/MR の起草を支援できますが、**マージボタンをクリックするのは人間** です。
+- すべての拒否操作はユーザーレベルの監査ログ（`gitflow-guard audit`）に追記されます。
+
+---
+
+## インストール詳細
+
+**前提条件**: `PATH` に **Node.js ≥ 22** がインストールされていること。全クライアント共通で **同じ npm パッケージ** `agents-gitflow-guard` を使用します。
+
+| クライアント | インストールコマンド | 次の手順 |
+|---|---|---|
+| DSH | `dsh plugin --profile web add agents-gitflow-guard` | DSH を再起動（プロファイル層として自動マウント） |
+| Claude Code · Codex · OpenCode · Antigravity | `npm i -g agents-gitflow-guard` | `gitflow-guard wire --client <name>`（コマンド 1 回） |
+| Pi | `npm i -D agents-gitflow-guard` | `pi/gitflow-guard.ts` を `.pi/extensions/` にコピー |
+
+### 独立したエージェントフックの配線 (Wire)
+
+```bash
+npm i -g agents-gitflow-guard   # `gitflow-guard` バイナリを提供
+gitflow-guard wire --client claude --project --yes
+gitflow-guard wire --client codex --project --yes
+gitflow-guard wire --client opencode --project --yes
+gitflow-guard wire --client antigravity --project --yes
+```
+
+各クライアントで生成される設定ファイルの内容：
+
+```jsonc
+// Claude Code — .claude/settings.json
+{
+  "hooks": {
+    "PreToolUse": [
+      { "matcher": "Bash", "hooks": [{ "type": "command", "command": "gitflow-guard check --platform claude" }] }
+    ]
+  }
+}
+```
+
+```jsonc
+// Codex — .codex/hooks.json
+{
+  "hooks": {
+    "PreToolUse": [
+      { "matcher": "^Bash$", "hooks": [{ "type": "command", "command": "gitflow-guard check --platform codex" }] }
+    ]
+  }
+}
+```
+
+```json
+// Antigravity (Google) — .agents/hooks.json
+{
+  "gitflow-guard": {
+    "PreToolUse": [
+      { "matcher": "run_command", "hooks": [ { "type": "command", "command": "gitflow-guard check --platform antigravity" } ] }
+    ]
+  }
+}
+```
+
+```jsonc
+// Pi — .pi/settings.json
+{ "extensions": ["extensions/gitflow-guard.ts"] }
+```
+
+**GitHub Copilot について**: Copilot は自身でツールごとの **allow/deny/ask** 権限およびプロジェクトルール（`rules.json` + `AGENTS.md`）を備えているため、本プラグインではフックを提供していません。
+
+---
+
+## よくある質問 (FAQ)
+
+### ブランチ名がデフォルトと異なる場合でも利用できますか？
+はい。ブランチ名は一切固定されていません。`gitflow-guard.config.json` で自由にマッピングできます。
+
+### preview / production / archive はすべて設定する必要がありますか？
+いいえ。実際に運用している役割のみを設定してください。小規模であれば `integration: ["develop"]` のみで運用できます。
+
+### これはセキュリティツールですか？
+いいえ、ワークフローを遵守させるためのガードツールです。真のセキュリティ境界には、GitHub/GitLab 側のブランチ保護ルールを必ず併用してください。
+
+### エージェント自身に本番マージを実行させられないのはなぜですか？
+本番やアーカイブへのマージは意図的に **人間限定（User-only）** として分類されているためです。エージェントがマージ権限を自己付与できる仕組みは排除されています。
+
+### 通常の開発作業が妨げられることはありますか？
+ありません。feature ブランチ内でのコミット、プッシュ、同期、リベース等の日常的な作業は一切ブロックされません。
+
+---
+
+## 用語集
+
+| 用語 | 意味 |
+|---|---|
+| **integration** | 基本となる集成分支（デフォルト: `develop`）。feature は PR/MR 経由で合流する。保護対象。 |
+| **preview** | 任意の検証環境ブランチ（`branches.preview` 配列）。PR/MR 経由のみで更新。 |
+| **production** | 任意の本番ブランチ（`branches.production` 配列）。PR/MR 経由 + マージは人間限定。 |
+| **archive** | 任意のアーカイブブランチ（`branches.archive` 配列）。エージェントは PR/MR 起草可能、マージは人間限定。 |
+| **feature branch** | `featurePattern` に一致する作業ブランチ。制限のない自由領域。 |
+| **gate matrix** | 分類された各コマンドの許可/拒否を定義する判定テーブル。 |
+| **pre-execute** | コマンド実行前にフックして拒否を行うツールパイプラインのフックポイント。 |
+| **merge-by-user** | 本番/アーカイブへのマージ権限を人間の手に残す設計。PR/MR 上でのクリックが確認となる。 |
+
+---
+
+## ロードマップ
+
+現在検討・進行中の機能拡張：
+
+- **新しいエージェントの統合**: Cursor、Windsurf、その他の新しいエージェント CLI への対応調査と適合。
+- **監査ログの集約**: 複数マシン間での監査ログ同期およびチームレベルのコンプライアンス出力。
+- **ワークフロープリセット**: 一般的なブランチモデル（トランクベース、多環境エンタープライズ構成など）用の設定プリセット。
+- **CI ハードゲート連携**: ゼロ依存のローカル実行性を保ちつつ、ネイティブな CI パイプライン連携を提供。
+
+リリース履歴の詳細は [CHANGELOG.md](CHANGELOG.md) をご覧ください。
+
+---
+
+## サポート
+
+本プラグインは MIT ライセンスのオープンソースです。もしチームの開発フロー保護にお役に立ちましたら、ご支援いただけると幸いです：
+
+[![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/keanz21)
+
+---
+
+## 開発
+
+```bash
+npm install
+npm test              # 単体テスト (vitest)
+npm run typecheck     # 型チェック (tsc --noEmit)
+npm run build         # ビルド (tsdown -> lib/)
+npm run test:platforms # 6 プラットフォームの Wire プロトコル復測マトリクス
+npm run test:git-matrix # 135 種類の Git コマンド判定窮挙マトリクス
+npm run test:realflow # Feature ブランチ全ライフサイクルの実機放行テスト
+npm run test:all      # 全テストスイートの一括実行
+```
+
+---
+
+## ライセンス
+
+[MIT](LICENSE) © FeatureAgents

package/README.ko.md

@@ -0,0 +1,136 @@
+# agents-gitflow-guard
+
+> **AI 에이전트가 GitFlow 규칙을 무단으로 건너뛰는 문제로 고민하고 계신가요?**
+
+AI 코딩 에이전트를 위한 유연하고 안전한 브랜치 역할 가드 플러그인 — [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH), Claude Code, Codex, OpenCode, Antigravity 및 Pi 지원.  
+자신만의 브랜치 역할을 자유롭게 정의하세요 — **integration** (PR/MR을 통해 feature 통합), **preview** (스테이징/테스트 환경 엔드포인트), **production** (운영), **archive** (아카이브) — 각각 고유한 업데이트 규칙을 설정할 수 있습니다. 에이전트는 정의된 흐름을 임의로 건너뛸 수 없으며, 민감한 머지 권한은 확실하게 사람의 손에 유지됩니다.
+
+[English](README.md) · [简体中文](README.zh.md) · [繁體中文](README.zh-tw.md) · [日本語](README.ja.md) · [한국어](README.ko.md) · [Deutsch](README.de.md) · [Français](README.fr.md) · [Italiano](README.it.md) · [Português](README.pt.md) · [Español](README.es.md) · [Русский](README.ru.md) · [라이선스](LICENSE)
+
+[![ko-fi](https://img.shields.io/badge/ko--fi-FF5E5B?style=flat-square&logo=ko-fi&logoColor=white)](https://ko-fi.com/keanz21)
+
+---
+
+## 목차
+
+- [빠른 시작 — 30초 만에 저장소 보호하기](#빠른-시작--30초-만에-저장소-보호하기)
+- [도입 배경 — 이 플러그인이 해결하는 문제](#도입-배경--이-플러그인이-해결하는-문제)
+- [적용 대상 — 추천 시나리오 및 팀](#적용-대상--추천-시나리오-및-팀)
+- [주요 기능 — 지원하는 동작](#주요-기능--지원하는-동작)
+- [제한 사항 — 정직한 한계](#제한-사항--정직한-한계)
+- [서버 측 브랜치 보호와의 차이점](#서버-측-브랜치-보호와의-차이점)
+- [동작 원리 — 3줄 요약 메커니즘](#동작-원리--3줄-요약-메커니즘)
+- [설정 레퍼런스](#설정-레퍼런스)
+- [판정 매트릭스 — 차단 및 허용 규칙](#판정-매트릭스--차단-및-허용-규칙)
+- [사람의 통제권이 유지되는 영역](#사람의-통제권이-유지되는-영역)
+- [상세 설치 가이드](#상세-설치-가이드)
+- [자주 묻는 질문 (FAQ)](#자주-묻는-질문-faq)
+- [용어집](#용어집)
+- [로드맵](#로드맵)
+- [후원 및 지원](#후원-및-지원)
+- [개발](#개발)
+- [라이선스](#라이선스)
+
+---
+
+## 빠른 시작 — 30초 만에 저장소 보호하기
+
+**1단계 — 설치.** 6개 클라이언트 모두 동일한 npm 패키지 `agents-gitflow-guard`를 사용합니다:
+
+```bash
+# DSH — 프로세스 내 플러그인 (설치 후 DSH 재시작 필요)
+dsh plugin --profile web add agents-gitflow-guard
+```
+
+```bash
+# Claude Code · Codex · OpenCode · Antigravity — 독립형 훅 (DSH 불필요)
+npm i -g agents-gitflow-guard
+```
+
+```bash
+# Pi — 프로세스 내 확장
+npm i -D agents-gitflow-guard
+```
+
+**2단계 — 클라이언트 연결 (설정 파일 불필요).** 본 가드는 **기본적으로 `develop` (통합) + `main` (아카이브)을 보호하는 내장 기본값**을 포함하고 있어, 별도 설정 없이 바로 활성화됩니다:
+
+```bash
+# Claude Code → 현재 저장소의 .claude/settings.json
+gitflow-guard wire --client claude --project --yes
+```
+
+```bash
+# Codex / OpenCode / Antigravity (클라이언트별 전용 파일에 작성)
+gitflow-guard wire --client codex --project --yes
+gitflow-guard wire --client opencode --project --yes
+gitflow-guard wire --client antigravity --project --yes
+```
+
+```bash
+# 미리보기 (쓰기 없음) / 제거 / 대화형 마법사:
+gitflow-guard wire --client claude --dry-run
+gitflow-guard wire --client claude --unwire
+gitflow-guard setup
+```
+
+`wire` 명령어는 기존 설정 파일에 **비파괴적으로** 병합됩니다.
+
+> ⚠️ **main 브랜치는 기본적으로 보호됩니다.** 트렁크 기반 개발(단일 브런치에 직접 푸시)을 사용하는 경우, `gitflow-guard.config.json`에 `{ "enabled": false }`를 추가하여 가드를 비활성화할 수 있습니다.
+
+**3단계 — 동작 검증.** 에이전트에게 `git push origin develop` 명령을 실행하도록 요청해 보세요. 즉시 차단됩니다:
+
+```text
+Error: [gitflow-guard] blocked: Protected branch "develop" forbids direct push
+Next: Integration branch (develop) is updated via PR/MR from a feature branch: push the feature first, then `gh pr create --base develop` / `glab mr create --target-branch develop`.
+```
+
+---
+
+## 도입 배경 — 이 플러그인이 해결하는 문제
+
+AI 코딩 에이전트는 저장소 내에서 직접 작업합니다. 프로젝트 지침 문서(`AGENTS.md`, `CLAUDE.md` 등)를 통해 워크플로우를 지시하지만, 이는 텍스트 기반의 **소프트 규칙**에 불과합니다.
+
+본 플러그인은 이러한 소프트 규칙을 **물리적인 하드 제약**으로 변환합니다. 에이전트가 시도하는 모든 Git 명령어는 실행 전에 로컬 저장소의 실제 상태를 기준으로 검증되며, 위반 시 명령 실행 자체가 즉시 차단됩니다.
+
+---
+
+## 주요 기능 — 지원하는 동작
+
+- **실행 전 차단 (Pre-execution block)**: 보호 브랜치(integration, preview, production, archive)에 대한 직접 push, force-push, 브랜치 삭제 및 에이전트의 production/archive 머지 시도를 원천 차단.
+- **사람 전용 머지 (Merge-by-user)**: 에이전트는 PR/MR 초안을 작성할 수 있지만, 최종 머지 버튼 클릭은 사람만 수행할 수 있습니다.
+- **안전한 감사 로그**: 모든 차단 내역은 저장소 외부인 `~/.local/state/gitflow-guard/`에 기록되어 위변조를 방지합니다.
+
+---
+
+## 판정 매트릭스 — 차단 및 허용 규칙
+
+| 에이전트 작업 | 판정 |
+|---|---|
+| feature 브랜치에서의 commit / push / rebase / sync | ✅ allow (허용) |
+| integration / preview / production / archive로의 직접 push / force-push / 삭제 | 🚫 block (차단) |
+| PR/MR 생성: feature → integration / preview | ✅ allow (허용) |
+| PR/MR 생성: feature → production | ✅ 생성 허용; **머지 차단** (사람이 UI에서 수행) |
+| PR/MR 생성 → archive | ✅ 생성 허용; 🚫 **머지 차단** (사람이 UI에서 수행) |
+| integration / preview 상에서 로컬 `git merge feature/x` 실행 | 🚫 block (PR/MR 필수) |
+| 보호 브랜치 대상 `git checkout -B` / `git switch -C` 강제 재작성 | 🚫 block |
+| `sudo`로 래핑된 Git 명령어 | 🚫 래퍼 제거 후 내부 Git 명령어 검증 및 차단 |
+
+---
+
+## 상세 설치 가이드
+
+**사전 요구사항**: `PATH`에 **Node.js ≥ 22** 설치 필요.
+
+```bash
+npm i -g agents-gitflow-guard
+gitflow-guard wire --client claude --project --yes
+gitflow-guard wire --client codex --project --yes
+gitflow-guard wire --client opencode --project --yes
+gitflow-guard wire --client antigravity --project --yes
+```
+
+---
+
+## 라이선스
+
+[MIT](LICENSE) © FeatureAgents

package/README.md

@@ -6,7 +6,7 @@ A configurable branch-role guard for AI coding agents — [DeepSeek Harness](htt
 You define your own branches —
 **integration** (features merge in via PR/MR), **preview** (env endpoints), **production**, **archive** — each with its own update rules. Agents can't skip the flow, and sensitive merges stay in your hands.
 
-[中文文档](README.zh.md) · [License](LICENSE)
+[English](README.md) · [简体中文](README.zh.md) · [繁體中文](README.zh-tw.md) · [日本語](README.ja.md) · [한국어](README.ko.md) · [Deutsch](README.de.md) · [Français](README.fr.md) · [Italiano](README.it.md) · [Português](README.pt.md) · [Español](README.es.md) · [Русский](README.ru.md) · [License](LICENSE)
 
 [![ko-fi](https://img.shields.io/badge/ko--fi-FF5E5B?style=flat-square&logo=ko-fi&logoColor=white)](https://ko-fi.com/keanz21)