@mcgrapeng/ccg 3.1.0

package/CHANGELOG.md

@@ -0,0 +1,119 @@
+# Changelog
+
+All notable changes to /ccg.
+
+## [3.1.0] — 2026-05-23
+
+Documentation and discoverability release. No core behavior changes; safe drop-in upgrade from 3.0.0.
+
+### Added
+- **`ccg about` subcommand** — 7-layer capability probe. Shows what ccg can do in *this* environment (not what the README claims), with green/yellow/red status per layer, environment readiness checks (Codex CLI / Gemini CLI / GEMINI_API_KEY / git / slash command installation), XDG storage state (ledger entries, usage entries, cache size), and a quick-reference command palette.
+  - Aliases: `ccg capabilities`, `ccg caps`
+  - Use case: "I'm a new user / contributor — what is ccg actually doing on my machine right now?"
+- **`docs/ARCHITECTURE.md`** — 387-line engineering reference for contributors and integrators. Documents the 7-layer architecture (L1 Safe CLI scheduling → L7 Divergence synthesis), each layer's purpose / problem / solution / "what breaks if you remove it", end-to-end data flow, extension points (signed contract for new risk rules / new LLM providers / new storage paths / pricing customization), invariants enforced by the test suite, and load-bearing design decisions that look weird at first glance.
+- **4-language ARCHITECTURE translations**: `docs/ARCHITECTURE.zh-CN.md`, `docs/ARCHITECTURE.ja.md`, `docs/ARCHITECTURE.ko.md`. Cross-linked from each language's README.
+
+### Changed
+- **README fully rewritten** with a concrete bcrypt walkthrough — actual output (not placeholder mockups) showing how AGREEMENT / DIVERGENCE / BLINDSPOT sections render in practice. The example shows two real-world disagreement: should `bcrypt` be wrapped with `subtle.ConstantTimeCompare`? Claude synthesizes that Codex's recommendation would break the comparison entirely because bcrypt uses a fresh salt every call.
+- **"When to use ccg" rewritten** — replaced the security-only framing (auth / payments / migrations / crypto) with judgment-difficulty framing. New trigger: *feeling*, not *domain*. Added cross-domain examples across social platforms, data/AI infra, frontend, API design, distributed systems, database, and security — emphasizing that divergence detection earns its cost on *any* change where two reasonable engineers might disagree.
+- **README structure** restructured into three-part flow: What / Why-vs-alternatives / Install / Walkthrough — designed to answer "what does it do" and "what does the output mean" before diving into config.
+- README v-prefix removed from H1 headings (no more "v3" branding in titles; version lives in CHANGELOG + npm).
+
+### Internal
+- `PROMO.md` added to `.gitignore` (marketing copy file, not part of npm package).
+
+## [3.0.0] — 2026-05-23
+
+Repositioning: from "multi-model review tool" to **"code divergence detector"**. Three structural pillars added; product opinion sharpened. 99-test regression (stable across 3 consecutive runs).
+
+### Identity shift
+**Before (v2):** "Get multi-model second opinions, see consensus + disagreement + actions."
+**After (v3):** "Surface where Codex and Gemini *disagree* — that's where you actually need to make a call. Agreement is low-signal; divergence is the gold."
+
+This is a category change. v3 deliberately downgrades the AGREEMENT section (one-liners only) and elevates DIVERGENCE (full expansion + `NEEDS HUMAN DECISION` markers).
+
+### Added — Pillar 1: Divergence Engine
+- Structured `[FINDING]…[/FINDING]` prompt protocol; both reviewers must conform
+- Three-section synthesis output: `AGREEMENT (N) / DIVERGENCE (M) / BLINDSPOT (≤2)`
+- `VERDICT` line: merge | fix-required | discuss
+- `NEEDS HUMAN DECISION` is an explicit signal, not implied
+
+### Added — Pillar 2: Risk-Aware Routing
+- `ccg_risk_score <diff_file>` — deterministic 0..100+ scoring
+  - Path signals: auth/payment/migration/crypto/security/infra/ci (+15..+40)
+  - Body signals: shell exec/SQL interp/fs delete/privilege ops (+5..+30)
+  - Size signals: lines and files-changed (+5..+25)
+  - Docs-only subtraction (-40)
+- Auto mode selection: <20 cost, <60 balanced, ≥60 quality
+- Manual `CCG_MODE=` override always wins
+- Outputs reason string for full transparency: `auth+35 sql_interp+30 size>300+15`
+- Pure rules, zero LLM cost, social-PR friendly
+
+### Added — Pillar 3: Review Ledger
+- `ccg_ledger_record <workdir>` — append JSONL row to `~/.ccg/ledger.jsonl`
+  - Fields: ts, repo, branch, sha, mode, risk, files, lines, paths[], synthesis (redacted, ≤400 chars)
+- `ccg_ledger_query [path-substring]` — search prior reviews
+- `CCG_LEDGER_LOG` env override
+- Synthesis excerpt runs through `_ccg_redact` before write (secret hygiene)
+
+### Fixed — diff capture deep gap
+- Old behavior: `git diff HEAD` only → empty after commit
+- New 4-level fallback: `worktree → staged → upstream:@{u}…HEAD → origin/HEAD…HEAD`
+- Reports `CCG_DIFF_SOURCE=<level>` so caller knows what scope was captured
+- Resolves "I committed and now /ccg sees nothing" footgun
+
+### Changed
+- Default `CCG_MODE=auto` (was `balanced`); auto uses risk score
+- `ccg_init` now also exposes `CCG_SYNTHESIS_FILE` and `CCG_RISK_FILE` paths
+- Dispatch subcommands added: `risk_score`, `ledger_record`, `ledger_query`
+
+### Tests
+- 13 new test cases (13.1 - 13.13) covering all three pillars + diff fallback
+- All 99 tests pass; 31s runtime; stable across consecutive runs
+
+## [2.0.0] — 2026-05-23
+
+Major refactor based on honest self-critique: drop low-value features, add high-leverage ones.
+86-test regression (stable across 10 consecutive runs).
+
+### Removed
+- **Pre-execution cost estimate** (`ccg_estimate`). Estimating output tokens by assumption produced 3-5× wrong predictions, misleading users. Post-execution `ccg_actual` remains — it uses real byte counts.
+- **Asymmetric prompt split** (codex=architecture, gemini=UX). It was pure intuition with no evidence. v2 sends the **same prompt to both providers** — training-data differences create natural diversity.
+- `ccg_mode_resolve` public subcommand (resolution is now internal/silent)
+- `CCG_USD_CNY_RATE`, `CCG_OUTPUT_TOKENS_ESTIMATE`, `CCG_TOKEN_CHARS_RATIO` knobs (no one tuned them)
+
+### Added
+- **Auto `git diff` mode**: naked `/ccg` (no args) captures `git diff HEAD` and runs a pre-commit triangulated review. One-keystroke workflow.
+- `ccg_diff_capture <out_file>` — captures `git diff HEAD`, falls back to `--cached`, returns `CCG_DIFF_OK/FAIL`
+- **24h prompt-hash cache** keyed by SHA-256(model + prompt). Same prompt + same model → cached result, $0.00 cost. Iterating on the same code saves 90%+ on repeat calls.
+- `CCG_CACHE_DIR` (default `~/.ccg/cache`) and `CCG_CACHE_TTL_HOURS` (default 24)
+- `CCG_NO_CACHE=1` opt-out per-call
+- **Usage log** at `~/.ccg/usage.log` (TSV: timestamp, provider, model, in_tokens, out_tokens, USD, cached). Only successful calls logged. Override path via `CCG_USAGE_LOG`.
+- `ccg_usage [--this-month|--all|--since=YYYY-MM]` aggregates spend by provider with cache-hit count
+- **Prompt size guard**: `CCG_MAX_PROMPT_KB=100` default. Hard reject prompts above this. Prevents the "I piped my whole repo and got a $5 bill" footgun.
+- New dispatch subcommands: `diff_capture`, `usage`, `actual`
+
+### Fixed
+- Test suite now isolates cache via `CCG_CACHE_DIR` (not `HOME`), so test runs no longer break codex/gemini auth lookup
+- Mock-mode test helpers always set `CCG_NO_CACHE=1` so failure-mode tests can't be masked by an earlier success-mode cache entry
+
+## [1.0.0] — 2026-05-22
+
+First production-ready release.
+
+### Added
+- `CCG_MODE=cost|balanced|quality` for model selection
+- `CCG_CODEX_MODEL`/`CCG_GEMINI_MODEL` explicit overrides
+- `ccg_codex` passes `-m <model>` when set
+- LICENSE (MIT), CHANGELOG, scripts/install.sh
+- 86-test regression in `tests/test_ccg.sh`
+
+### Fixed
+- **CRITICAL**: pure-bash timeout fallback lost stdin in async children. Real Codex/Gemini stdin delivery now works in all bash modes via explicit `<&0`.
+- Timeout polling granularity: 1s → 0.1s + wall-clock deadline for sub-second responsiveness.
+- Orphan sweep threshold: 60min → 1440min (24h).
+- `eval`-safety for any printed shell-meta in mode descriptions.
+
+## [0.x] — pre-release
+
+Initial two-file plugin (commands/ccg.md + commands/ccg.sh).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zhangpeng
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ja.md

@@ -0,0 +1,220 @@
+# ccg — Code Divergence Detector
+
+> Claude Code のスラッシュコマンド。一度インストールして、diff の上で `/ccg` と入力するだけ。
+
+[![Tests](https://img.shields.io/badge/tests-99%20passing-brightgreen.svg)]()
+[![npm](https://img.shields.io/npm/v/@mcgrapeng/ccg.svg)](https://www.npmjs.com/package/@mcgrapeng/ccg)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+[English](README.md) ｜ [简体中文](README.zh-CN.md) ｜ **日本語** ｜ [한국어](README.ko.md)　·　[アーキテクチャ →](docs/ARCHITECTURE.ja.md)
+
+---
+
+## ccg とは
+
+あなたは `auth/login.go` を編集し終え、マージしようとしています。念のため確認したい。今の選択肢は 3 つしかなく、全て欠点があります：
+
+- **単一モデルのレビュー**（Copilot、Cursor `/review`、Aider）は **1 つの視点** しか提供しません。Claude が timing attack を見逃せば、あなたも一緒に見逃します。
+- **複数モデル集約ツール**（zen-mcp-server 等）は意見を **平均化** してしまい、優秀なモデル同士が意見を異にした箇所——人間が本当に助けを必要とする箇所——を覆い隠してしまいます。
+- **手動の二重チェック** は時間が無限にあればやりますが、ありませんね。
+
+ccg は Claude Code 用の `/ccg` スラッシュコマンドで、この 3 つを本当に解決します。任意の diff に対して：
+
+1. 同じ prompt を **Codex（OpenAI）** と **Gemini（Google）** に並列で送信
+2. **Claude** に両方のレポートを読ませ、**両者が意見を異にした箇所を浮かび上がらせる**——そこが人間の判断が必要な場所
+3. コストを記録、リスクに応じて最安充足モデルを自動選択、過去のレビュー履歴を保持
+
+**例え話**：別チームの 2 人のシニアエンジニアに同じ PR をレビューさせ、テックリードに統合させる：「ここは両方同意、ここは意見が分かれた——あなたが決めて、私の見解は以下」。
+
+## いつ ccg を使うか
+
+トリガーは **領域** ではなく **感覚** です。書き終えた自分の diff を見ながら、心の中で次のように考えていたら、ccg の場面です：
+
+| 心の中の独り言 | ccg を使う？ |
+|---|---|
+| 「これを間違えたら午前 3 時に呼び出される」 | ✅ Yes |
+| 「これは判断問題 — 明らかに正しい答えはない」 | ✅ Yes |
+| 「誰か他に先に見てほしい」 | ✅ Yes |
+| 「変数の名前を変えただけ」 | ❌ No |
+| 「ドキュメント変更だけ」 | ❌ No |
+| 「単一モデルとストリーミング対話したい」 | ❌ No（CLI を直接使う） |
+
+**ドメイン横断の実例** —— auth / 暗号ではないが、すべて「シニア 2 人が意見を異にしうる」瞬間：
+
+- **ソーシャルプラットフォーム** —— フィードに新エンゲージメントシグナルを追加して再ランキング · コメントツリー fan-out 戦略 · A/B テストバケッティングロジック · 反スパムレート制限ポリシー · フォロー関係のグラフ DB スキーマ
+- **データ / AI インフラ** —— embedding モデル切替（再インデックスする？） · chunking 戦略変更 · RAG 検索スコアリング · prompt injection 防御レイヤリング
+- **フロントエンド** —— 新ページに SSR vs ISR vs RSC · キャッシュ無効化戦略 · 状態管理リファクタリング · アクセシビリティのトレードオフ
+- **API 設計** —— cursor vs offset ページング · エラーレスポンスモデル · バージョニング方式 · 冪等性キーの扱い
+- **分散システム** —— タイムアウト / 再試行ポリシー · cache TTL vs イベント駆動無効化 · partition tolerance トレードオフ · leader election のセマンティクス
+- **データベース** —— マルチステップマイグレーションの順序 · ホットパスのインデックス選択 · トランザクション分離レベル · 論理削除 vs 物理削除
+- **セキュリティ** —— ええ、auth / 暗号 / 決済もここ —— ただし多くのドメインの 1 つに過ぎない
+
+**パターン**：「妥当なエンジニアが選択肢 A を選ぶこともあれば、別の妥当なエンジニアが B を選ぶこともある」変更 —— これが分岐検出が $0.04 を稼ぐ瞬間。
+
+## なぜ ccg なのか（他ツールとの比較）
+
+**1. 意見の相違こそがシグナル、ノイズではない。**
+Codex が「`subtle.ConstantTimeCompare` を使え」と言い、Gemini が「bcrypt は既に恒定時間、それは cargo-cult」と言った時、**そここそ考える必要がある場所**。他のツールはこれを「timing attack に注意」とぼやかして混ぜます。ccg は両者の生の言葉を見せます。
+
+**2. コスト可視化が組み込み。**
+Codex / Gemini CLI は支出を教えません。ccg は全呼び出しを記録、リスクに応じて最安充足モデルを自動選択（リスクルーティング）、同一プロンプトは 24h キャッシュでゼロコスト。`ccg_usage --this-month` が「今月いくら使った？」に即答。
+
+**3. セッションを跨いで残るレビュー履歴。**
+「2 週間前、モデルは `src/auth.ts` について何と言ったか？」——ccg の追記専用台帳がこれに答えます。ステートレスなツールには不可能です。
+
+## インストール
+
+どちらかを選択：
+
+```bash
+# npm (推奨)
+npx @mcgrapeng/ccg install
+
+# または curl ワンライナー、Node 不要
+curl -fsSL https://raw.githubusercontent.com/mcgrapeng/ccg/main/scripts/curl-install.sh | bash
+```
+
+次に AI CLI を一度だけインストール：
+
+```bash
+npm i -g @openai/codex @google/gemini-cli
+echo 'export GEMINI_API_KEY="<your-key>"' >> ~/.zshenv
+```
+
+確認：
+
+```bash
+npx @mcgrapeng/ccg doctor      # Codex / Gemini / API key をチェック
+npx @mcgrapeng/ccg about       # 7 層の機能と現在の環境状態を表示
+```
+
+## 使い方の完全な例
+
+`auth/login.go` を編集したとします：
+
+```go
+// before                                            // after
+func Login(user, pw string) bool {                   func Login(user, pw string) bool {
+    u := lookupUser(user)                                u := lookupUser(user)
+-   return u.Hash == sha256.Sum256([]byte(pw))           hashed, err := bcrypt.GenerateFromPassword([]byte(pw), 12)
++                                                        if err != nil { return false }
++                                                        return subtle.ConstantTimeCompare(u.Hash, hashed) == 1
+}
+```
+
+Claude Code を開いて入力：
+
+```
+/ccg
+```
+
+約 30 秒後に表示されるもの——**実際の出力例**、プレースホルダーではない：
+
+```
+📍 範囲：worktree · 1 ファイル · +4 -1 行
+🎯 モード：quality  (risk=65 · auth+35 size>0+5 crypto-mention+25)
+🩺 両レビュアー正常：Codex ✓ · Gemini ✓
+💰 コスト：$0.041
+
+═══ AGREEMENT (2) — 両方が指摘、低シグナル ═══
+• auth/login.go:3 — sha256 はパスワードハッシュでない；bcrypt が正しい
+• auth/login.go:5 — bcrypt エラーは明示的に処理（やっている）
+
+═══ DIVERGENCE (1) — 両モデルが意見不一致 ★ あなたが決定 ═══
+
+▸ auth/login.go:6 — bcrypt ハッシュの比較方法
+  🔵 Codex： 「bcrypt を使っても timing attack を防ぐため
+              subtle.ConstantTimeCompare でラップせよ」
+  🟢 Gemini：「bcrypt.CompareHashAndPassword は既に恒定時間。
+              ラッピングは cargo-cult、長さ不一致 panic を生み得る」
+  ⚖️ Claude： Gemini が正しい。bcrypt.CompareHashAndPassword が標準的な
+              比較方法；その生の出力に対する ConstantTimeCompare は
+              カテゴリ誤り——「ハッシュした pw」と「保存されたハッシュ」を
+              比較しているが、bcrypt は毎回新しいソルトを使うので
+              直接比較は常に false を返す。
+  ➡️ アクション：ConstantTimeCompare 行を以下に置換：
+              `err := bcrypt.CompareHashAndPassword(u.Hash, []byte(pw))`
+              `return err == nil`
+
+═══ BLINDSPOT (1) — どちらも見ていないが Claude が疑う ═══
+• エラーパス：bcrypt エラー時に false を返すのは呼び出し側には正しいが、
+  インフラエラー（bcrypt OOM 等）を静かに飲み込む。ログを追加せよ。
+
+═══ VERDICT: fix-required ═══
+現在の比較ロジックは正しいパスワードを常に拒否する。DIVERGENCE の
+アクションを適用 + エラーログ追加で、マージ可能。
+```
+
+### この出力をどう読むか
+
+| セクション | 意味 | 何をすべきか |
+|---|---|---|
+| **AGREEMENT** | Codex と Gemini の両方が同じ問題を指摘。単一の Claude でも見つかる可能性が高い——**新規情報量低**。 | 流し読み、未修正なら修正。 |
+| **DIVERGENCE** ★ | 両モデルが意見不一致。**これが ccg の存在意義**。Claude の「アクション」行が推奨をくれるが、最終判断はあなた。 | 注意深く読む、Claude の判断を受け入れるかオーバーライド。 |
+| **BLINDSPOT** | どちらのモデルも気付かなかったが Claude が合成時に疑った。**控えめに**——1 回あたり最大 2 件。 | ヒントとして扱う、聖典ではない。 |
+| **VERDICT** | `merge` / `fix-required` / `discuss`。1 行サマリー。 | マージゲートとして使用。 |
+
+レビュー後、`ccg_ledger_record` が JSONL 1 行を台帳に書きます。2 週間後：
+
+```bash
+source ~/.claude/commands/ccg.sh
+ccg_ledger_query "auth/login.go"
+# → "auth/login.go: 3 レビュー · 最新 2026-05-23 (fix-required) · 2026-05-09 (merge) · 2026-04-28 (discuss)"
+```
+
+## 設定（デフォルトで通常は十分）
+
+モードとモデルの選択は自動です。必要なときだけ上書き：
+
+```bash
+CCG_MODE=quality /ccg          # 任意の diff で quality モデルを強制
+CCG_CODEX_MODEL=o3 /ccg        # 1 つのモデルだけ上書き
+CCG_NO_CACHE=1 /ccg            # この呼び出しのみ 24h キャッシュをスキップ
+```
+
+よく使うもの（全部は [アーキテクチャ §5](docs/ARCHITECTURE.ja.md#5-拡張ポイント)）：
+
+| 変数 | デフォルト | 用途 |
+|---|---|---|
+| `CCG_MODE` | `auto` | `auto` / `cost` / `balanced` / `quality` |
+| `CCG_CACHE_TTL_HOURS` | `24` | キャッシュ TTL |
+| `CCG_MAX_PROMPT_KB` | `100` | 1 回あたりのプロンプトサイズ上限 |
+
+コスト目安（USD / 呼び出し、キャッシュヒット後）：
+
+| モード | Codex | Gemini | 標準コスト |
+|---|---|---|---|
+| `cost`     | gpt-5-nano  | gemini-2.5-flash-lite | ~$0.0007 |
+| `balanced` | gpt-5-mini  | gemini-2.5-flash      | ~$0.0046 |
+| `quality`  | gpt-5       | gemini-2.5-pro        | ~$0.0440 |
+
+累計支出はいつでも確認可能：
+
+```bash
+source ~/.claude/commands/ccg.sh
+ccg_usage --this-month
+```
+
+## 適さない用途
+
+- Claude Code 以外の IDE（[zen-mcp-server](https://github.com/BeehiveInnovations/zen-mcp-server) を試してください）
+- 静的解析の置き換え（Semgrep / CodeQL と併用してください）
+- 全 PR で自動実行（ccg はトリアージツール、ボットではありません）
+- ストリーミング出力やマルチターン会話
+
+## アーキテクチャとコントリビュート
+
+ccg は **7 層** で構成されており、「分岐検出」は最上位 1 層にすぎません。下の 6 層（キャッシュ、台帳、使用量、リスクルーティング、スマート diff、安全な CLI スケジューリング）はそれぞれ独立して実問題を解決します。`ccg.sh` を変更する前に [docs/ARCHITECTURE.ja.md](docs/ARCHITECTURE.ja.md) を読んでください。
+
+テスト：
+
+```bash
+bash tests/test_ccg.sh                # 99 個の回帰テスト、~31s
+REAL_CLI=1 bash tests/test_ccg.sh     # +2 個のライブ API テスト（課金あり）
+```
+
+## ライセンスと謝辞
+
+MIT —— [LICENSE](LICENSE) を参照。
+
+[oh-my-claudecode](https://github.com/Yeachan-Heo/oh-my-claudecode) の元々の `/ccg` コンセプト · Claude Code · OpenAI Codex CLI · Google Gemini CLI を基に構築。

package/README.ko.md

@@ -0,0 +1,219 @@
+# ccg — Code Divergence Detector
+
+> Claude Code 슬래시 명령. 한 번 설치하고 diff 위에서 `/ccg`를 입력하세요.
+
+[![Tests](https://img.shields.io/badge/tests-99%20passing-brightgreen.svg)]()
+[![npm](https://img.shields.io/npm/v/@mcgrapeng/ccg.svg)](https://www.npmjs.com/package/@mcgrapeng/ccg)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+[English](README.md) ｜ [简体中文](README.zh-CN.md) ｜ [日本語](README.ja.md) ｜ **한국어**　·　[아키텍처 →](docs/ARCHITECTURE.ko.md)
+
+---
+
+## ccg란
+
+`auth/login.go` 변경 후 머지하려고 합니다. 안전 점검을 하고 싶습니다. 오늘 선택지는 세 가지뿐이고, 모두 결함이 있습니다:
+
+- **단일 모델 리뷰**(Copilot, Cursor `/review`, Aider)는 **한 가지 관점**만 제공합니다. Claude가 timing attack을 놓치면 당신도 함께 놓칩니다.
+- **다중 모델 게이트웨이**(zen-mcp-server 등)는 의견을 **평균화**하여, 똑똑한 모델들이 의견을 달리한 곳 — 인간이 정말로 도움이 필요한 유일한 곳 — 을 정확히 가립니다.
+- **수동 교차 검증**은 시간이 무한하다면 할 일. 당신에겐 없습니다.
+
+ccg는 Claude Code용 `/ccg` 슬래시 명령으로, 이 세 가지 모두를 진짜로 해결합니다. 임의의 diff에 대해:
+
+1. 같은 prompt를 **Codex(OpenAI)** 와 **Gemini(Google)** 에 병렬 전송
+2. **Claude** 가 두 보고서를 읽고 **그들이 의견을 달리하는 곳을 부각** —— 인간 판단이 필요한 곳
+3. 비용 추적, 위험 수준에 적합한 가장 저렴한 모델 자동 선택, 과거 리뷰 기억
+
+**비유**: 다른 팀의 시니어 엔지니어 두 명에게 같은 PR을 리뷰시키고, 테크 리드가 종합: "이건 둘 다 동의, 이건 의견이 갈렸음 — 당신이 결정, 내 견해는 다음".
+
+## 언제 ccg를 사용할까
+
+트리거는 **도메인**이 아니라 **느낌**입니다. 방금 작성한 diff를 보면서 마음속으로 다음과 같이 생각하고 있다면 — ccg의 순간입니다:
+
+| 마음속 독백 | ccg 사용? |
+|---|---|
+| "이걸 잘못하면 새벽 3시에 호출됨." | ✅ 예 |
+| "이건 판단의 문제 — 명백히 정답이 있는 게 아님." | ✅ 예 |
+| "누가 먼저 봐줬으면 좋겠다." | ✅ 예 |
+| "변수 이름만 바꿨다." | ❌ 아니요 |
+| "문서만 편집." | ❌ 아니요 |
+| "단일 모델과 스트리밍 대화하고 싶음." | ❌ 아니요 (CLI 직접 사용) |
+
+**도메인 횡단 실제 예시** — 모두 auth/암호화가 아니지만, 모두 "시니어 엔지니어 두 명이 의견이 갈릴" 순간입니다:
+
+- **소셜 플랫폼** — 새 참여 신호로 피드 재정렬 · 댓글 트리 fan-out 전략 · A/B 테스트 버킷팅 로직 · 어뷰즈 방지 레이트 리밋 정책 · 팔로우 관계의 그래프 DB 스키마
+- **데이터 / AI 인프라** — embedding 모델 교체(재인덱싱?) · 청킹 전략 변경 · RAG 검색 점수 · 프롬프트 인젝션 방어 레이어링
+- **프론트엔드** — 새 페이지에 SSR vs ISR vs RSC · 캐시 무효화 전략 · 상태 관리 리팩토링 · 접근성 트레이드오프
+- **API 설계** — 페이지네이션 cursor vs offset · 에러 응답 모델 · 버전 관리 방식 · 멱등성 키 처리
+- **분산 시스템** — 타임아웃 / 재시도 정책 · cache TTL vs 이벤트 기반 무효화 · 분할 내성 트레이드오프 · 리더 선출 의미론
+- **데이터베이스** — 다단계 마이그레이션 순서 · 핫 패스 인덱스 선택 · 트랜잭션 격리 수준 · 소프트 삭제 vs 하드 삭제
+- **보안** — 네, auth / 암호화 / 결제도 여기 — 하지만 많은 도메인 중 하나일 뿐
+
+**패턴**: 합리적인 엔지니어 한 명은 A를 선택하고 다른 합리적인 엔지니어는 B를 선택할 수 있는 모든 변경 — 그게 분기 검출이 $0.04를 회수하는 순간.
+
+## 왜 ccg인가 (다른 도구와의 비교)
+
+**1. 의견 불일치가 신호, 잡음이 아님.**
+Codex가 "`subtle.ConstantTimeCompare`를 사용하라"고 하고 Gemini가 "bcrypt는 이미 constant-time, 그건 cargo-cult"라고 할 때, *그곳이* 당신이 생각해야 할 곳입니다. 다른 도구는 이런 충돌을 모호한 "timing attack 주의"로 섞어버립니다. ccg는 양쪽의 말을 그대로 보여줍니다.
+
+**2. 내장 비용 텔레메트리.**
+Codex / Gemini CLI는 지출을 알려주지 않습니다. ccg는 모든 호출을 기록하고, 위험에 따라 가장 저렴하고 충분한 모델을 자동 선택(위험 라우팅)하며, 같은 prompt는 24h 캐시로 비용 0. `ccg_usage --this-month`가 "지금까지 얼마 썼지?"에 답합니다.
+
+**3. 세션 간에 살아남는 리뷰 이력.**
+"2주 전에 모델이 `src/auth.ts`에 대해 뭐라고 했지?" —— ccg의 추가 전용 원장이 답합니다. 어떤 무상태 도구도 못 합니다.
+
+## 설치
+
+둘 중 선택:
+
+```bash
+# npm (권장)
+npx @mcgrapeng/ccg install
+
+# 또는 curl 한 줄 설치, Node 불필요
+curl -fsSL https://raw.githubusercontent.com/mcgrapeng/ccg/main/scripts/curl-install.sh | bash
+```
+
+그다음 AI CLI를 한 번 설치:
+
+```bash
+npm i -g @openai/codex @google/gemini-cli
+echo 'export GEMINI_API_KEY="<your-key>"' >> ~/.zshenv
+```
+
+확인:
+
+```bash
+npx @mcgrapeng/ccg doctor      # Codex / Gemini / API key 점검
+npx @mcgrapeng/ccg about       # 7개 계층의 기능과 현재 환경 상태 확인
+```
+
+## 사용법 — 완전한 예제
+
+`auth/login.go`를 막 편집했다고 해봅시다:
+
+```go
+// before                                            // after
+func Login(user, pw string) bool {                   func Login(user, pw string) bool {
+    u := lookupUser(user)                                u := lookupUser(user)
+-   return u.Hash == sha256.Sum256([]byte(pw))           hashed, err := bcrypt.GenerateFromPassword([]byte(pw), 12)
++                                                        if err != nil { return false }
++                                                        return subtle.ConstantTimeCompare(u.Hash, hashed) == 1
+}
+```
+
+Claude Code를 열고 입력:
+
+```
+/ccg
+```
+
+약 30초 후 다음과 같은 출력 —— **실제 출력**, 플레이스홀더 아님:
+
+```
+📍 범위: worktree · 1 파일 · +4 -1 줄
+🎯 모드: quality  (risk=65 · auth+35 size>0+5 crypto-mention+25)
+🩺 두 리뷰어 정상: Codex ✓ · Gemini ✓
+💰 비용: $0.041
+
+═══ AGREEMENT (2) — 양쪽 모두 지적, 낮은 신호 ═══
+• auth/login.go:3 — sha256은 비밀번호 해시 아님; bcrypt가 맞음
+• auth/login.go:5 — bcrypt 에러 명시적 처리 (당신이 했음)
+
+═══ DIVERGENCE (1) — 두 모델이 의견 불일치 ★ 당신이 결정 ═══
+
+▸ auth/login.go:6 — bcrypt 해시 비교 방법
+  🔵 Codex:  "bcrypt를 사용해도 timing attack 방지를 위해
+              subtle.ConstantTimeCompare로 감싸라."
+  🟢 Gemini: "bcrypt.CompareHashAndPassword는 이미 constant-time.
+              감싸는 것은 cargo-cult이고 길이 불일치 panic을 유발할 수 있다."
+  ⚖️ Claude: Gemini가 맞다. bcrypt.CompareHashAndPassword가 표준 비교
+              방법; 그 원시 출력에 ConstantTimeCompare는 카테고리 오류 ——
+              "막 해시한 pw"와 "저장된 해시"를 비교하지만 bcrypt는
+              매번 새 솔트를 쓰므로 직접 비교는 항상 false 반환.
+  ➡️ 액션:   ConstantTimeCompare 줄을 다음으로 교체:
+              `err := bcrypt.CompareHashAndPassword(u.Hash, []byte(pw))`
+              `return err == nil`
+
+═══ BLINDSPOT (1) — 둘 다 못 봤지만 Claude 의심 ═══
+• 에러 경로: bcrypt 오류 시 false 반환은 호출자에겐 맞지만,
+  인프라 오류(bcrypt OOM 등)를 조용히 삼킴. 로그를 추가하라.
+
+═══ VERDICT: fix-required ═══
+현재 비교 로직은 유효한 비밀번호도 항상 거부한다. DIVERGENCE 액션
+적용 + 오류 로깅 추가 후 머지 가능.
+```
+
+### 이 출력을 어떻게 읽는가
+
+| 섹션 | 의미 | 무엇을 할까 |
+|---|---|---|
+| **AGREEMENT** | Codex와 Gemini 둘 다 같은 것을 지적. 단일 소스 Claude도 잡을 가능성 높음 —— **새로운 정보량 낮음**. | 훑어보고, 미수정 시 수정. |
+| **DIVERGENCE** ★ | 두 모델이 의견 불일치. **ccg가 존재하는 진짜 이유**. Claude의 "액션" 줄이 추천을 주지만 최종 결정자는 당신. | 주의 깊게 읽고, Claude 판단 수용 또는 재정의. |
+| **BLINDSPOT** | 어떤 모델도 제기하지 않았지만 Claude가 합성하면서 의심. **신중히 사용** —— 호출당 최대 2건. | 힌트로 다루고, 절대 진리 아님. |
+| **VERDICT** | `merge` / `fix-required` / `discuss`. 한 줄 요약. | 머지 게이트로 사용. |
+
+리뷰 후 `ccg_ledger_record`가 원장에 JSONL 한 줄 기록. 2주 후:
+
+```bash
+source ~/.claude/commands/ccg.sh
+ccg_ledger_query "auth/login.go"
+# → "auth/login.go: 3 리뷰 · 최신 2026-05-23 (fix-required) · 2026-05-09 (merge) · 2026-04-28 (discuss)"
+```
+
+## 설정 (기본값으로 보통 충분)
+
+모드와 모델 선택은 자동입니다. 필요할 때만 재정의:
+
+```bash
+CCG_MODE=quality /ccg          # 모든 diff에 quality 모델 강제
+CCG_CODEX_MODEL=o3 /ccg        # 단일 모델만 재정의
+CCG_NO_CACHE=1 /ccg            # 이번 호출만 24h 캐시 우회
+```
+
+자주 쓰는 것 (전체는 [아키텍처 §5](docs/ARCHITECTURE.ko.md#5-확장-지점)):
+
+| 변수 | 기본값 | 용도 |
+|---|---|---|
+| `CCG_MODE` | `auto` | `auto` / `cost` / `balanced` / `quality` |
+| `CCG_CACHE_TTL_HOURS` | `24` | 캐시 TTL |
+| `CCG_MAX_PROMPT_KB` | `100` | 호출당 프롬프트 크기 상한 |
+
+비용 참고 (USD / 호출, 캐시 적중 후):
+
+| 모드 | Codex | Gemini | 표준 비용 |
+|---|---|---|---|
+| `cost`     | gpt-5-nano  | gemini-2.5-flash-lite | ~$0.0007 |
+| `balanced` | gpt-5-mini  | gemini-2.5-flash      | ~$0.0046 |
+| `quality`  | gpt-5       | gemini-2.5-pro        | ~$0.0440 |
+
+누적 지출은 언제든:
+
+```bash
+source ~/.claude/commands/ccg.sh
+ccg_usage --this-month
+```
+
+## 적합하지 않은 경우
+
+- Claude Code 이외의 IDE ([zen-mcp-server](https://github.com/BeehiveInnovations/zen-mcp-server) 시도)
+- 정적 분석 대체 (Semgrep / CodeQL과 함께 사용)
+- 모든 PR에 자동 실행 (ccg는 트리아지 도구, 봇이 아닙니다)
+- 스트리밍 출력 또는 멀티턴 대화
+
+## 아키텍처 및 기여
+
+ccg는 **7개 계층**으로 구성되며, "분기 검출"은 최상위 1개 계층일 뿐입니다. 아래 6개 계층(캐시, 원장, 사용량, 위험 라우팅, 스마트 diff, 안전한 CLI 스케줄링)은 각각 독립적으로 실제 문제를 해결합니다. `ccg.sh`를 변경하기 전에 [docs/ARCHITECTURE.ko.md](docs/ARCHITECTURE.ko.md)를 읽어주세요.
+
+테스트:
+
+```bash
+bash tests/test_ccg.sh                # 99개 회귀 테스트, ~31s
+REAL_CLI=1 bash tests/test_ccg.sh     # +2개 실제 API 테스트 (비용 발생)
+```
+
+## 라이선스 및 감사의 말
+
+MIT —— [LICENSE](LICENSE) 참조.
+
+[oh-my-claudecode](https://github.com/Yeachan-Heo/oh-my-claudecode)의 원래 `/ccg` 컨셉 · Claude Code · OpenAI Codex CLI · Google Gemini CLI 기반.