@mcgrapeng/ccg 3.1.0

package/README.md

@@ -0,0 +1,220 @@
+# ccg — Code Divergence Detector
+
+> A Claude Code slash command. Install once, type `/ccg` on a diff.
+
+[![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.zh-CN.md) ｜ [日本語](README.ja.md) ｜ [한국어](README.ko.md)　·　[Architecture →](docs/ARCHITECTURE.md)
+
+---
+
+## What is ccg
+
+You're about to merge a change to `auth/login.go`. You want a sanity check. Today you have three options, all of them flawed:
+
+- **Single-model review** (Copilot, Cursor `/review`, Aider) gives you **one perspective**. If Claude misses a timing attack, you miss it too.
+- **Multi-model gateways** (zen-mcp-server etc.) **average opinions**, hiding exactly the places where smart models disagreed — which is the only place you actually needed help.
+- **Manual cross-checking** is what you'd do if you had unlimited time. You don't.
+
+ccg is a `/ccg` slash command for Claude Code that fixes all three. On any diff, it:
+
+1. Sends the same prompt to **Codex (OpenAI)** and **Gemini (Google)** in parallel
+2. Has **Claude** read both reports and surface **specifically where they disagree** — that's where human judgment is needed
+3. Tracks cost, picks the cheapest model good enough for the risk level, and remembers past reviews
+
+**Think of it like:** asking two senior engineers from different teams to review the same PR, then having a tech lead synthesize: "they agree on these issues, they disagree on this one — you decide, and here's my read."
+
+## When to use ccg
+
+The trigger isn't a *domain* — it's a *feeling*. Use ccg when, looking at your own diff, you catch yourself thinking:
+
+| Inner monologue | Use ccg? |
+|---|---|
+| "If I get this wrong, I'll get paged at 3am." | ✅ Yes |
+| "This is a judgment call — no obviously right answer." | ✅ Yes |
+| "I wish someone else would look at this first." | ✅ Yes |
+| "I just renamed a variable." | ❌ No |
+| "Docs-only change." | ❌ No |
+| "I want streaming chat with one model." | ❌ No (use the CLI directly) |
+
+**Examples across domains** — none of these are auth/crypto, all of them are real "two senior engineers would disagree" moments:
+
+- **Social platforms** — re-ranking the feed with a new engagement signal · comment-thread fan-out strategy · A/B test bucketing logic · anti-abuse rate-limit policy · graph-DB schema for follow relationships
+- **Data / AI infra** — switching embedding model (do you re-index?) · changing chunking strategy · RAG retrieval scoring · prompt-injection defense layering
+- **Frontend** — SSR vs ISR vs RSC for a new page · cache invalidation strategy · state-management refactor · accessibility trade-offs
+- **API design** — cursor vs offset pagination · error response model · versioning approach · idempotency-key handling
+- **Distributed systems** — timeout/retry policy · cache TTL vs event-driven invalidation · partition tolerance trade-off · leader-election semantics
+- **Database** — multi-step migration sequencing · index choice on a hot path · transaction isolation level · soft-delete vs hard-delete
+- **Security** — yes, auth / crypto / payments too — but just one of many domains
+
+**The pattern:** any change where a reasonable engineer might pick option A and another reasonable engineer might pick option B. That's when divergence detection earns its $0.04.
+
+## Why ccg (vs everything else)
+
+**1. Disagreement is the signal, not the noise.**
+When Codex says "use `subtle.ConstantTimeCompare`" and Gemini says "bcrypt is already constant-time, that's cargo-cult", *that* is where you need to think. Other tools blend these into a vague "consider timing attacks". ccg shows you the conflict verbatim.
+
+**2. Cost telemetry built in.**
+Codex/Gemini CLIs don't tell you what you spent. ccg logs every call, picks the cheapest sufficient model automatically (risk-aware routing), and caches identical prompts for 24h. `ccg_usage --this-month` answers "how much have I spent so far?".
+
+**3. A review history that survives across sessions.**
+"What did the model say about `src/auth.ts` two weeks ago?" — ccg's append-only ledger answers that. No stateless tool can.
+
+## Install
+
+Pick one:
+
+```bash
+# npm (recommended)
+npx @mcgrapeng/ccg install
+
+# or curl one-liner, no Node
+curl -fsSL https://raw.githubusercontent.com/mcgrapeng/ccg/main/scripts/curl-install.sh | bash
+```
+
+Then install the AI CLIs once:
+
+```bash
+npm i -g @openai/codex @google/gemini-cli
+echo 'export GEMINI_API_KEY="<your-key>"' >> ~/.zshenv
+```
+
+Verify:
+
+```bash
+npx @mcgrapeng/ccg doctor      # check Codex / Gemini / API key
+npx @mcgrapeng/ccg about       # 7-layer capability probe + runtime state
+```
+
+## Try it — a walkthrough
+
+Say you just edited `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
+}
+```
+
+You open Claude Code and type:
+
+```
+/ccg
+```
+
+After ~30 seconds you see something like this — **real output**, not a placeholder:
+
+```
+📍 Scope: worktree · 1 file · +4 -1 lines
+🎯 Mode:  quality  (risk=65 · auth+35 size>0+5 crypto-mention+25)
+🩺 Both reviewers OK: Codex ✓ · Gemini ✓
+💰 Cost: $0.041
+
+═══ AGREEMENT (2) — both flagged, low signal ═══
+• auth/login.go:3 — sha256 wasn't a password hash; bcrypt is correct
+• auth/login.go:5 — handle the bcrypt error explicitly (you do)
+
+═══ DIVERGENCE (1) — the models disagreed ★ you decide ═══
+
+▸ auth/login.go:6 — how to compare bcrypt hashes
+  🔵 Codex:   "Wrap with subtle.ConstantTimeCompare to prevent timing attacks
+              even with bcrypt."
+  🟢 Gemini:  "bcrypt.CompareHashAndPassword is already constant-time. Wrapping
+              it is cargo-cult and can mask bugs (length mismatch panics)."
+  ⚖️ Claude:  Gemini is correct. bcrypt.CompareHashAndPassword is the canonical
+              comparison; ConstantTimeCompare on its raw output is a category
+              error — you'd be comparing the freshly-hashed `pw` against the
+              stored hash, but bcrypt salts each hash uniquely so direct
+              comparison ALWAYS returns false.
+  ➡️ Action:  Replace the ConstantTimeCompare line with:
+              `err := bcrypt.CompareHashAndPassword(u.Hash, []byte(pw))`
+              `return err == nil`
+
+═══ BLINDSPOT (1) — neither saw, Claude suspects ═══
+• Error path: returning `false` on bcrypt error is correct for the caller but
+  silently swallows infrastructure errors (e.g. bcrypt OOM). Log the error.
+
+═══ VERDICT: fix-required ═══
+The comparison logic as written will always reject valid passwords. Apply
+the DIVERGENCE action, add error logging, and you're good to merge.
+```
+
+### How to read this output
+
+| Section | What it means | What to do |
+|---|---|---|
+| **AGREEMENT** | Both Codex and Gemini flagged the same thing. Your single-source Claude likely catches these too — **low new information**. | Skim, fix if not already done. |
+| **DIVERGENCE** ★ | The two models disagreed. **This is the whole reason ccg exists.** Claude's "Action" line gives you a recommendation, but you're the final decider. | Read carefully. Apply Claude's call or override it. |
+| **BLINDSPOT** | Neither model raised it, but Claude noticed something while synthesizing. **Use sparingly** — limit 2 per run. | Treat as a hint, not gospel. |
+| **VERDICT** | `merge` / `fix-required` / `discuss`. One-line summary. | Use as merge gate. |
+
+After the review, `ccg_ledger_record` writes one JSONL line to your ledger. Two weeks from now you can:
+
+```bash
+source ~/.claude/commands/ccg.sh
+ccg_ledger_query "auth/login.go"
+# → "auth/login.go: 3 reviews · last 2026-05-23 (fix-required) · 2026-05-09 (merge) · 2026-04-28 (discuss)"
+```
+
+## Configure (defaults are usually fine)
+
+Mode and model picks are automatic. Override only when needed:
+
+```bash
+CCG_MODE=quality /ccg          # force quality models on any diff
+CCG_CODEX_MODEL=o3 /ccg        # override one model
+CCG_NO_CACHE=1 /ccg            # skip 24h cache for this call
+```
+
+Common knobs (full list in [Architecture → §5](docs/ARCHITECTURE.md#5-extension-points)):
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `CCG_MODE` | `auto` | `auto` / `cost` / `balanced` / `quality` |
+| `CCG_CACHE_TTL_HOURS` | `24` | Cache TTL |
+| `CCG_MAX_PROMPT_KB` | `100` | Per-call prompt size cap |
+
+Cost reference (USD per call, after cache):
+
+| Mode | Codex | Gemini | Typical cost |
+|---|---|---|---|
+| `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 |
+
+See accumulated spend any time:
+
+```bash
+source ~/.claude/commands/ccg.sh
+ccg_usage --this-month
+```
+
+## Not for
+
+- IDEs other than Claude Code (try [zen-mcp-server](https://github.com/BeehiveInnovations/zen-mcp-server))
+- Replacing static analysis (pair with Semgrep / CodeQL)
+- Auto-running on every PR (ccg is a triage tool, not a bot)
+- Streaming or multi-turn conversation
+
+## Architecture & contributing
+
+ccg is **7 layers**, only the top one is "divergence detection". The other six (cache, ledger, usage, risk routing, smart diff, safe CLI scheduling) each independently solve a real problem. Read [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) before changing anything in `ccg.sh`.
+
+Tests:
+
+```bash
+bash tests/test_ccg.sh                # 99 regression tests, ~31s
+REAL_CLI=1 bash tests/test_ccg.sh     # +2 live API tests (incurs cost)
+```
+
+## License & credits
+
+MIT — see [LICENSE](LICENSE).
+
+Built on [oh-my-claudecode](https://github.com/Yeachan-Heo/oh-my-claudecode)'s original `/ccg` concept · Claude Code · OpenAI Codex CLI · Google Gemini CLI.

package/README.zh-CN.md

@@ -0,0 +1,219 @@
+# ccg — 代码分歧检测器
+
+> Claude Code 的 slash command。装一次，在 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.ja.md) ｜ [한국어](README.ko.md)　·　[架构文档 →](docs/ARCHITECTURE.zh-CN.md)
+
+---
+
+## ccg 是什么
+
+你刚改完 `auth/login.go`，准备 merge。你想"保险一下"再走。今天你只有三种选择，每种都有硬伤：
+
+- **单模型 review**（Copilot、Cursor `/review`、Aider）只给**一种视角**。如果 Claude 漏看了 timing attack，你也会一起漏。
+- **多模型聚合工具**（zen-mcp-server 等）把多个模型的意见**平均化**，恰好遮盖了它们意见分歧的地方——而那才是你真正需要思考的位置。
+- **手工双查**理论上最稳，但你没那个时间。
+
+ccg 是 Claude Code 的 `/ccg` slash command，针对这三件事都做了真正的解决：
+
+1. 把同一个 prompt **并行**发给 **Codex（OpenAI）** 和 **Gemini（Google）**
+2. 让 **Claude** 读完两份报告，**聚焦它们意见不一致的地方**——人需要拍板的就在那里
+3. 自动按代码风险选最便宜够用的模型、记录每次调用成本、保留历史评审账本
+
+**类比理解**：就像让两个不同团队的 senior 工程师 review 同一份 PR，再让一个 tech lead 综合："这几点他们都同意，这一点他们意见不一致——你来定，下面是我的看法。"
+
+## 什么时候用 ccg
+
+触发条件不是**领域**，而是**感觉**。当你看着自己刚写完的 diff，心里冒出下面这种念头，就是 ccg 的场景：
+
+| 你心里在想 | 用 ccg？ |
+|---|---|
+| "这个改错了，我凌晨会被叫起来" | ✅ 用 |
+| "这是个判断题，没有一定对的答案" | ✅ 用 |
+| "我希望有第二个人帮我看一眼" | ✅ 用 |
+| "我就是改了个变量名" | ❌ 不用 |
+| "只改了文档" | ❌ 不用 |
+| "我想跟单个模型流式对话" | ❌ 不用（直接用 CLI） |
+
+**跨领域真实例子** —— 都不是 auth / 加密的场景，但都是"两个资深工程师真会吵起来"的瞬间：
+
+- **社交平台** —— feed 排序换了新的互动信号 · 评论树 fan-out 策略 · A/B 实验分桶逻辑 · 反滥用限流策略 · 关注关系的图数据库 schema
+- **数据 / AI 基建** —— 换 embedding 模型（向量库要不要重建？） · 改 chunking 策略 · RAG 检索打分 · prompt injection 防御分层
+- **前端** —— 新页面用 SSR 还是 ISR 还是 RSC · 缓存失效策略 · 状态管理重构 · 可访问性取舍
+- **API 设计** —— 分页用 cursor 还是 offset · 错误响应模型 · 版本管理策略 · 幂等性 key 处理
+- **分布式系统** —— 超时 / 重试策略 · cache TTL vs 事件驱动失效 · 分区容忍度取舍 · leader election 语义
+- **数据库** —— 多步迁移的拆分顺序 · 热点路径的索引选择 · 事务隔离级别 · 软删 vs 硬删
+- **安全** —— 对，auth / 加密 / 支付也属于这类 —— 但只是众多领域之一
+
+**判断标准**：任何一个"合理的工程师可能选 A、另一个合理的工程师可能选 B"的改动，就是分歧检测赚回 $0.04 的时刻。
+
+## 为什么是 ccg（和其他工具的对比）
+
+**1. 分歧才是信号，不是噪音。**
+当 Codex 说"加上 `subtle.ConstantTimeCompare` 防 timing attack"，而 Gemini 说"bcrypt 自己就是恒定时间的，加包装是 cargo-cult"——**这才是你需要思考的地方**。别的工具会把这种冲突糊成一句模糊的"注意 timing 攻击"。ccg 把两边原话端给你。
+
+**2. 内置成本可见性。**
+Codex / Gemini CLI 都不告诉你花了多少钱。ccg 记录每次调用，按风险自动选最便宜够用的模型（risk-aware routing），相同 prompt 24h 内命中缓存零成本。`ccg_usage --this-month` 立刻回答"这个月我花了多少？"。
+
+**3. 跨会话保留的评审历史。**
+"两周前模型对 `src/auth.ts` 说了什么？"——ccg 的 append-only 账本能回答。任何无状态工具都做不到。
+
+## 怎么安装
+
+二选一：
+
+```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="<你的-key>"' >> ~/.zshenv
+```
+
+验证：
+
+```bash
+npx @mcgrapeng/ccg doctor      # 检查 Codex / Gemini / API key
+npx @mcgrapeng/ccg about       # 看 7 层能力 + 当前环境状态
+```
+
+## 完整使用示例
+
+假设你刚改了 `auth/login.go`：
+
+```go
+// 改前                                              // 改后
+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  (风险=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 说： "外包一层 subtle.ConstantTimeCompare 防 timing 攻击，
+                即使用了 bcrypt 也要加。"
+  🟢 Gemini 说："bcrypt.CompareHashAndPassword 自身就是恒定时间的。
+                外包一层是 cargo-cult，反而可能因为长度不一致 panic。"
+  ⚖️ Claude 综合：Gemini 是对的。bcrypt.CompareHashAndPassword 才是
+                标准比较方式；对它的原始输出做 ConstantTimeCompare 是
+                根本性错误——你比较的是"刚 hash 的 pw"和"存储的 hash"，
+                而 bcrypt 每次 hash 都用新的盐，所以直接比较永远返回 false。
+  ➡️ 建议动作： 把 ConstantTimeCompare 那行替换为：
+                `err := bcrypt.CompareHashAndPassword(u.Hash, []byte(pw))`
+                `return err == nil`
+
+═══ BLINDSPOT (1) — 两边都没看到 Claude 怀疑 ═══
+• 错误处理路径：bcrypt 出错时返回 false 对调用方是对的，但是会静默吞掉
+  基础设施错误（比如 bcrypt OOM）。建议加日志。
+
+═══ VERDICT: fix-required ═══
+当前比较逻辑会永远拒绝合法密码。按 DIVERGENCE 的建议改完 + 加错误日志，
+就可以 merge 了。
+```
+
+### 怎么看懂这份输出
+
+| 段落 | 是什么意思 | 你该怎么办 |
+|---|---|---|
+| **AGREEMENT** | Codex 和 Gemini 都标记的同一个问题。你单源用 Claude 也大概率能发现——**新信息量低**。 | 扫一眼，没改的就改。 |
+| **DIVERGENCE** ★ | 两个模型意见不一致。**这才是 ccg 存在的真正原因。** Claude 的"建议动作"给你推荐，但你是最终拍板的人。 | 仔细读，接受 Claude 判断或自己覆盖。 |
+| **BLINDSPOT** | 两个模型都没看到，但 Claude 综合时怀疑。**慎用**——每次最多 2 条。 | 当提示看，不是金科玉律。 |
+| **VERDICT** | `merge` / `fix-required` / `discuss`。一句话结论。 | 当 merge 门禁用。 |
+
+评审完，`ccg_ledger_record` 会写一行 JSONL 到账本。两周后你可以：
+
+```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.zh-CN.md#5-扩展点)）：
+
+| 变量 | 默认 | 用途 |
+|---|---|---|
+| `CCG_MODE` | `auto` | `auto` / `cost` / `balanced` / `quality` |
+| `CCG_CACHE_TTL_HOURS` | `24` | 缓存 TTL |
+| `CCG_MAX_PROMPT_KB` | `100` | 单次 prompt 大小硬上限 |
+
+成本参考（USD / 次，缓存命中 $0）：
+
+| 模式 | 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 层**，"分歧检测"只是最上面一层。下面 6 层（缓存、账本、用量、风险路由、智能 diff、安全 CLI 调度）各自独立解决真问题。改 `ccg.sh` 之前先读 [docs/ARCHITECTURE.zh-CN.md](docs/ARCHITECTURE.zh-CN.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。