@mcgrapeng/ccg 3.1.0

package/bin/ccg.js

@@ -0,0 +1,391 @@
+#!/usr/bin/env node
+/**
+ * @mcgrapeng/ccg — Node.js CLI entry.
+ *
+ * Subcommands:
+ *   install     install /ccg slash command into ~/.claude/commands/
+ *   uninstall   remove the slash command
+ *   doctor      preflight: check Codex CLI, Gemini CLI, GEMINI_API_KEY
+ *   version     print version
+ *   help        show this message
+ *
+ * The CLI is a thin orchestrator. All review logic lives in the bash core
+ * (ccg.sh), which gets installed into ~/.claude/commands/ as a slash command.
+ *
+ * Source: https://github.com/mcgrapeng/ccg
+ */
+
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const os = require("node:os");
+const { spawnSync, execFileSync } = require("node:child_process");
+
+const PKG_ROOT = path.resolve(__dirname, "..");
+const PKG = require(path.join(PKG_ROOT, "package.json"));
+
+const CCG_SH = path.join(PKG_ROOT, "ccg.sh");
+const CCG_MD = path.join(PKG_ROOT, "ccg.md");
+const TARGET_DIR = path.join(os.homedir(), ".claude", "commands");
+
+// ──────────────────────────────────────────────────────────────
+// pretty helpers
+// ──────────────────────────────────────────────────────────────
+const TTY = process.stdout.isTTY;
+const C = {
+  reset: TTY ? "\x1b[0m" : "",
+  dim: TTY ? "\x1b[2m" : "",
+  bold: TTY ? "\x1b[1m" : "",
+  green: TTY ? "\x1b[32m" : "",
+  red: TTY ? "\x1b[31m" : "",
+  yellow: TTY ? "\x1b[33m" : "",
+  cyan: TTY ? "\x1b[36m" : "",
+};
+const ok = (m) => console.log(`${C.green}✓${C.reset} ${m}`);
+const warn = (m) => console.log(`${C.yellow}!${C.reset} ${m}`);
+const fail = (m) => console.error(`${C.red}✗${C.reset} ${m}`);
+const head = (m) => console.log(`\n${C.bold}${m}${C.reset}`);
+
+// ──────────────────────────────────────────────────────────────
+// commands
+// ──────────────────────────────────────────────────────────────
+function which(cmd) {
+  try {
+    execFileSync(process.platform === "win32" ? "where" : "command", ["-v", cmd], {
+      stdio: "ignore",
+      shell: true,
+    });
+    return true;
+  } catch {
+    // Fallback for systems where `command -v` cannot be located via execFile
+    const r = spawnSync("sh", ["-c", `command -v "${cmd}" >/dev/null 2>&1`]);
+    return r.status === 0;
+  }
+}
+
+function cmdInstall() {
+  head("Installing /ccg slash command for Claude Code");
+
+  if (!fs.existsSync(CCG_SH) || !fs.existsSync(CCG_MD)) {
+    fail("Package payload missing (ccg.sh / ccg.md). Reinstall the npm package.");
+    process.exit(2);
+  }
+
+  fs.mkdirSync(TARGET_DIR, { recursive: true });
+  fs.copyFileSync(CCG_SH, path.join(TARGET_DIR, "ccg.sh"));
+  fs.chmodSync(path.join(TARGET_DIR, "ccg.sh"), 0o755);
+  fs.copyFileSync(CCG_MD, path.join(TARGET_DIR, "ccg.md"));
+  fs.chmodSync(path.join(TARGET_DIR, "ccg.md"), 0o644);
+
+  ok(`wrote ${path.join(TARGET_DIR, "ccg.sh")}`);
+  ok(`wrote ${path.join(TARGET_DIR, "ccg.md")}`);
+
+  cmdDoctor({ silent: false, exitOnFail: false });
+
+  console.log("");
+  console.log(`${C.cyan}Next:${C.reset} open Claude Code and type ${C.bold}/ccg${C.reset} on a diff.`);
+}
+
+function cmdUninstall() {
+  head("Uninstalling /ccg slash command");
+  let removed = 0;
+  for (const f of ["ccg.sh", "ccg.md"]) {
+    const p = path.join(TARGET_DIR, f);
+    if (fs.existsSync(p)) {
+      fs.unlinkSync(p);
+      ok(`removed ${p}`);
+      removed += 1;
+    }
+  }
+  if (removed === 0) warn("Nothing to remove (slash command was not installed).");
+  console.log(`\n${C.dim}User data (cache / ledger) was NOT touched — they live under XDG paths.${C.reset}`);
+}
+
+function cmdDoctor({ silent = false, exitOnFail = true } = {}) {
+  if (!silent) head("Preflight checks");
+
+  const hasCodex = which("codex");
+  const hasGemini = which("gemini");
+  const hasGeminiKey = Boolean(
+    process.env.GEMINI_API_KEY && process.env.GEMINI_API_KEY.trim(),
+  );
+
+  const results = [
+    {
+      label: "Codex CLI (codex)",
+      pass: hasCodex,
+      hint: "npm i -g @openai/codex",
+    },
+    {
+      label: "Gemini CLI (gemini)",
+      pass: hasGemini,
+      hint: "npm i -g @google/gemini-cli",
+    },
+    {
+      label: "GEMINI_API_KEY environment variable",
+      pass: hasGeminiKey,
+      hint: 'put `export GEMINI_API_KEY="..."` into ~/.zshenv (works in non-interactive shells)',
+    },
+  ];
+
+  let anyFail = false;
+  for (const r of results) {
+    if (r.pass) ok(r.label);
+    else {
+      warn(`${r.label} ${C.dim}→ ${r.hint}${C.reset}`);
+      anyFail = true;
+    }
+  }
+
+  if (!silent) {
+    if (!anyFail) {
+      console.log(`\n${C.green}All checks passed.${C.reset} /ccg is ready.`);
+    } else if (hasCodex || hasGemini) {
+      console.log(
+        `\n${C.yellow}/ccg can run in degraded single-source mode.${C.reset} Install the missing tool for full divergence detection.`,
+      );
+    } else {
+      console.log(
+        `\n${C.red}/ccg cannot run yet — install at least one of Codex/Gemini and ensure GEMINI_API_KEY for full features.${C.reset}`,
+      );
+    }
+  }
+
+  if (exitOnFail && anyFail) process.exitCode = 1;
+}
+
+// ──────────────────────────────────────────────────────────────
+// `ccg about` — 7-layer capability probe
+//
+// Shows what ccg can do in this environment, not what the README claims.
+// Each layer is independently usable; layers below answer real engineering
+// problems even if you never touch the divergence-detection layer above.
+// ──────────────────────────────────────────────────────────────
+function cmdAbout() {
+  const xdg = {
+    config: process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config"),
+    cache: process.env.XDG_CACHE_HOME || path.join(os.homedir(), ".cache"),
+    data: process.env.XDG_DATA_HOME || path.join(os.homedir(), ".local/share"),
+  };
+  const cacheDir = path.join(xdg.cache, "ccg", "cache");
+  const dataDir = path.join(xdg.data, "ccg");
+  const ledger = path.join(dataDir, "ledger.jsonl");
+  const usageLog = path.join(dataDir, "usage.log");
+
+  const hasCodex = which("codex");
+  const hasGemini = which("gemini");
+  const hasGeminiKey = Boolean(
+    process.env.GEMINI_API_KEY && process.env.GEMINI_API_KEY.trim(),
+  );
+  const hasGit = which("git");
+  const installedSlash =
+    fs.existsSync(path.join(TARGET_DIR, "ccg.sh")) &&
+    fs.existsSync(path.join(TARGET_DIR, "ccg.md"));
+  const fileExists = (p) => {
+    try { return fs.statSync(p).isFile(); } catch { return false; }
+  };
+  const countLines = (p) => {
+    try {
+      return fs
+        .readFileSync(p, "utf8")
+        .split("\n")
+        .filter((line) => line.trim().length > 0).length;
+    } catch { return 0; }
+  };
+  const dirSize = (p) => {
+    try {
+      let total = 0;
+      for (const entry of fs.readdirSync(p, { withFileTypes: true })) {
+        const full = path.join(p, entry.name);
+        if (entry.isFile()) total += fs.statSync(full).size;
+      }
+      return total;
+    } catch { return 0; }
+  };
+  const fmtSize = (b) =>
+    b < 1024 ? `${b}B` : b < 1024 ** 2 ? `${(b / 1024).toFixed(1)}KB` : `${(b / 1024 ** 2).toFixed(1)}MB`;
+
+  const ledgerEntries = countLines(ledger);
+  const usageEntries = countLines(usageLog);
+  const cacheSize = dirSize(cacheDir);
+
+  // ── header ────────────────────────────────────────────
+  console.log(`${C.bold}@mcgrapeng/ccg${C.reset} v${PKG.version}`);
+  console.log(`${C.dim}A production-grade orchestrator for using Codex + Gemini CLI from inside Claude Code.${C.reset}`);
+  console.log("");
+  console.log(`Source:  ${PKG.repository.url.replace(/^git\+/, "").replace(/\.git$/, "")}`);
+  console.log("");
+
+  // ── 7-layer capability matrix ─────────────────────────
+  console.log(`${C.bold}7 layers of capability${C.reset}`);
+  console.log(`${C.dim}(Each layer is useful on its own. The famous "divergence detection" is just L7.)${C.reset}`);
+  console.log("");
+
+  const layers = [
+    {
+      id: "L1",
+      name: "Safe CLI scheduling",
+      solves: "timeouts / stdin preservation / secret redaction / cleanup safety",
+      status: "always-on",
+      detail: `cleanup, mktemp 700, 7-pattern redaction (sk-/AIza/Bearer/JWT/ghp_/AKIA/Slack)`,
+    },
+    {
+      id: "L2",
+      name: "Content-addressed cache",
+      solves: "stop paying for the same prompt twice during debugging",
+      status: process.env.CCG_NO_CACHE === "1" ? "disabled (CCG_NO_CACHE=1)" : "always-on",
+      detail: `SHA-256 prompt + model key, 24h TTL, failed calls NOT cached.  Current: ${fmtSize(cacheSize)} at ${cacheDir}`,
+    },
+    {
+      id: "L3",
+      name: "Smart diff capture",
+      solves: "captures changes even after you've committed them",
+      status: hasGit ? "ready" : "git missing",
+      detail: "4-level fallback: worktree → staged → upstream → origin-head (reports CCG_DIFF_SOURCE)",
+    },
+    {
+      id: "L4",
+      name: "Usage tracking & cost telemetry",
+      solves: "see how much you spend per month / per model",
+      status: "always-on",
+      detail: `${usageEntries} call(s) logged at ${usageLog}.  Run: ${C.cyan}source ccg.sh && ccg_usage --this-month${C.reset}`,
+    },
+    {
+      id: "L5",
+      name: "Risk-aware auto routing",
+      solves: "auto-pick cost/balanced/quality based on path+content+size",
+      status: "always-on",
+      detail: "Pure rule scoring (no LLM). Path matches auth/payment → +25..+40; SQL+interp → +30; docs only → -40",
+    },
+    {
+      id: "L6",
+      name: "Review ledger",
+      solves: "stateless AI can't tell you 'what did the model say last time on src/auth.ts?'",
+      status: "always-on",
+      detail: `${ledgerEntries} review(s) logged at ${ledger}.  Query: ${C.cyan}ccg_ledger_query "src/auth"${C.reset}`,
+    },
+    {
+      id: "L7",
+      name: "Divergence detection (synthesis)",
+      solves: "single-model review can't see its own blind spots",
+      status:
+        hasCodex && hasGemini && hasGeminiKey
+          ? "full (Codex + Gemini)"
+          : hasCodex || (hasGemini && hasGeminiKey)
+          ? "degraded (single source)"
+          : "unavailable",
+      detail: "Codex + Gemini → same prompt → Claude surfaces AGREEMENT / DIVERGENCE / BLINDSPOT",
+    },
+  ];
+
+  for (const layer of layers) {
+    const isFull =
+      layer.status.includes("ready") ||
+      layer.status === "always-on" ||
+      layer.status.startsWith("full");
+    const isDegraded = layer.status.startsWith("degraded") || layer.status.includes("disabled");
+    const isFail =
+      layer.status.includes("missing") || layer.status.includes("unavailable");
+
+    const dot = isFull
+      ? `${C.green}●${C.reset}`
+      : isDegraded
+      ? `${C.yellow}●${C.reset}`
+      : isFail
+      ? `${C.red}●${C.reset}`
+      : `${C.dim}●${C.reset}`;
+    console.log(`  ${dot} ${C.bold}${layer.id}${C.reset}  ${layer.name}  ${C.dim}— ${layer.status}${C.reset}`);
+    console.log(`     ${C.dim}why:${C.reset}    ${layer.solves}`);
+    console.log(`     ${C.dim}how:${C.reset}    ${layer.detail}`);
+    console.log("");
+  }
+
+  // ── environment ─────────────────────────────────────────
+  console.log(`${C.bold}Environment${C.reset}`);
+  const envRow = (label, status, hint) => {
+    const dot = status ? `${C.green}✓${C.reset}` : `${C.red}✗${C.reset}`;
+    console.log(`  ${dot}  ${label}${status ? "" : `  ${C.dim}→ ${hint}${C.reset}`}`);
+  };
+  envRow("Claude Code slash command installed", installedSlash, `run: ${C.cyan}ccg install${C.reset}`);
+  envRow("Codex CLI", hasCodex, "npm i -g @openai/codex");
+  envRow("Gemini CLI", hasGemini, "npm i -g @google/gemini-cli");
+  envRow("GEMINI_API_KEY env var", hasGeminiKey, 'add to ~/.zshenv: export GEMINI_API_KEY="..."');
+  envRow("git available", hasGit, "install git for diff capture");
+  console.log("");
+
+  // ── storage ─────────────────────────────────────────────
+  console.log(`${C.bold}Storage (XDG)${C.reset}`);
+  console.log(`  config:  ${path.join(xdg.config, "ccg")}/${fileExists(path.join(xdg.config, "ccg/config.json")) ? "" : `  ${C.dim}(no config.json yet)${C.reset}`}`);
+  console.log(`  cache:   ${cacheDir}  ${C.dim}(${fmtSize(cacheSize)})${C.reset}`);
+  console.log(`  data:    ${dataDir}  ${C.dim}(ledger=${ledgerEntries}, usage=${usageEntries})${C.reset}`);
+  console.log("");
+
+  // ── quick reference ────────────────────────────────────
+  console.log(`${C.bold}Common commands${C.reset}`);
+  console.log(`  ${C.cyan}/ccg${C.reset}                                          ${C.dim}(inside Claude Code) full divergence review on current diff${C.reset}`);
+  console.log(`  ${C.cyan}source ~/.claude/commands/ccg.sh${C.reset}`);
+  console.log(`    ${C.cyan}ccg_usage --this-month${C.reset}                      ${C.dim}month-to-date cost${C.reset}`);
+  console.log(`    ${C.cyan}ccg_ledger_query "path/fragment"${C.reset}             ${C.dim}past reviews touching a path${C.reset}`);
+  console.log(`    ${C.cyan}ccg_risk_score <diff_file>${C.reset}                   ${C.dim}preview routing decision${C.reset}`);
+  console.log("");
+  console.log(`  ${C.cyan}ccg doctor${C.reset}                                    ${C.dim}re-check environment${C.reset}`);
+  console.log(`  ${C.cyan}ccg uninstall${C.reset}                                 ${C.dim}remove slash command (user data preserved)${C.reset}`);
+}
+
+function cmdVersion() {
+  console.log(PKG.version);
+}
+
+function cmdHelp() {
+  console.log(`${C.bold}@mcgrapeng/ccg${C.reset} v${PKG.version} — Code Divergence Detector
+
+${C.bold}Usage${C.reset}
+  npx @mcgrapeng/ccg install      Install /ccg into ~/.claude/commands/
+  npx @mcgrapeng/ccg uninstall    Remove the slash command
+  npx @mcgrapeng/ccg about        What can ccg do? 7-layer capability probe
+  npx @mcgrapeng/ccg doctor       Verify Codex / Gemini / API key
+  npx @mcgrapeng/ccg version      Print version
+  npx @mcgrapeng/ccg help         Show this message
+
+${C.bold}After install${C.reset}
+  Open Claude Code → type ${C.bold}/ccg${C.reset} on a diff.
+
+${C.bold}Source${C.reset}  ${PKG.repository.url.replace(/^git\+/, "").replace(/\.git$/, "")}
+${C.bold}License${C.reset} ${PKG.license}`);
+}
+
+// ──────────────────────────────────────────────────────────────
+// dispatch
+// ──────────────────────────────────────────────────────────────
+const [, , subcommand = "help", ...rest] = process.argv;
+const dispatch = {
+  install: cmdInstall,
+  uninstall: cmdUninstall,
+  remove: cmdUninstall,
+  doctor: cmdDoctor,
+  preflight: cmdDoctor,
+  about: cmdAbout,
+  capabilities: cmdAbout,
+  caps: cmdAbout,
+  version: cmdVersion,
+  "-v": cmdVersion,
+  "--version": cmdVersion,
+  help: cmdHelp,
+  "-h": cmdHelp,
+  "--help": cmdHelp,
+};
+
+const action = dispatch[subcommand];
+if (!action) {
+  fail(`Unknown subcommand: ${subcommand}`);
+  cmdHelp();
+  process.exit(2);
+}
+
+try {
+  action(rest);
+} catch (err) {
+  fail(err.message || String(err));
+  process.exit(1);
+}

package/ccg.md

@@ -0,0 +1,303 @@
+---
+description: Code-divergence detector. Run Codex+Gemini in parallel on a diff, then surface where they DISAGREE (high-signal) vs where they agree. Auto-picks risk-aware mode. Logs each review to ledger. See README.md.
+---
+
+# CCG v3 — 代码分歧检测器
+
+**身份**：不是 review 工具，是**分歧检测器**。两个独立模型家族（Codex/Gemini）评审同一份 diff，Claude 综合时把"两边都说没事 / 两边都说有问题"压成低优先级，把"两边判断不一致的点"放到聚光灯下——这才是真正值得人类介入的地方。
+
+**默认行为**：无参数 → 抓 git diff → 风险打分 → 自动选 mode → 并行评审 → 输出 AGREEMENT / DIVERGENCE / BLINDSPOT 三段 → 落 ledger。
+
+## 三柱设计
+
+| 柱 | 解决的问题 | 实现 |
+|---|---|---|
+| Divergence Engine | 单源 review 看不到"自己看不到的盲区" | 同 prompt 双投喂 + Claude 综合时强调分歧 |
+| Risk-Aware Routing | 用户不应该手选 cost/balanced/quality | `ccg_risk_score` 基于路径/内容/规模规则打分自动选 |
+| Review Ledger | 这次评审的判断下次没法复用 | 每次评审追加 JSONL，按路径可查历史 |
+
+## 配置 (环境变量)
+
+| 变量 | 默认 | 说明 |
+|---|---|---|
+| `CCG_MODE` | `auto` | `auto` (按 risk score 决) / `cost` / `balanced` / `quality` |
+| `CCG_CODEX_MODEL` | — | 显式 codex 模型（优先于 CCG_MODE） |
+| `CCG_GEMINI_MODEL` | — | 显式 gemini 模型 |
+| `CCG_CODEX_TIMEOUT` | `240` | Codex 超时秒数 |
+| `CCG_GEMINI_TIMEOUT` | `120` | Gemini 超时秒数 |
+| `CCG_NO_CACHE` | `0` | `1` = 跳过 24h prompt-hash 缓存 |
+| `CCG_CACHE_TTL_HOURS` | `24` | 缓存 TTL |
+| `CCG_MAX_PROMPT_KB` | `100` | 防止把整个 repo 塞进 prompt |
+| `CCG_KEEP_ARTIFACTS` | `0` | `1` = 保留临时文件 |
+| `CCG_LEDGER_LOG` | `$XDG_DATA_HOME/ccg/ledger.jsonl` | 评审历史落盘位置（fallback `~/.local/share/ccg/`，自动迁移老路径 `~/.ccg/`） |
+
+### Mode → 默认模型映射
+
+| Mode | Codex | Gemini |
+|---|---|---|
+| `cost` | gpt-5-nano | gemini-2.5-flash-lite |
+| `balanced` (默认) | gpt-5-mini | gemini-2.5-flash |
+| `quality` | gpt-5 | gemini-2.5-pro |
+
+> ⚠️ 第三方代理若不支持上述模型名，会 5xx/404。用 `CCG_CODEX_MODEL`/`CCG_GEMINI_MODEL` 显式指定代理实际支持的型号。
+
+## 前置依赖
+
+- `npm i -g @openai/codex` `npm i -g @google/gemini-cli`
+- `export GEMINI_API_KEY=...` 放在 `~/.zshenv`（非交互 shell 也能读到）
+
+## 执行协议（Claude 严格按以下步骤）
+
+### 步骤 0. 初始化工作目录
+
+```bash
+source ~/.claude/commands/ccg.sh
+ccg_init
+```
+
+**⚠️ 跨 Bash 调用 env vars 不持久。把输出的字面 `CCG_DIR=...` 路径记住**，后续每个 Bash 调用开头先 `CCG_DIR=<字面路径>` 重建。
+
+### 步骤 1. 预检
+
+```bash
+source ~/.claude/commands/ccg.sh
+ccg_preflight
+```
+- `CCG_PREFLIGHT_CODEX=missing` → 说明缺哪个 CLI + 安装命令
+- `CCG_PREFLIGHT_GEMINI=no-api-key` → 标注 Gemini 不可用，跳过
+- 两者都不可用 → Claude 独立回答
+
+### 步骤 2. 确定任务输入（两种模式）
+
+**A. 用户给了参数**（如 `/ccg 评审 src/auth.ts`）：直接用用户输入作为 prompt。跳过 risk_score（让用户隐式选 mode 或用环境变量）。
+
+**B. 用户没给参数**（裸 `/ccg`）：**自动评审 git diff**：
+
+```bash
+CCG_DIR=<字面路径>
+source ~/.claude/commands/ccg.sh
+ccg_diff_capture "$CCG_DIR/diff.txt"
+```
+
+- `CCG_DIFF_OK` + `CCG_DIFF_SOURCE=worktree` → 工作区脏改动
+- `CCG_DIFF_SOURCE=staged` → 已 git add 但未 commit
+- `CCG_DIFF_SOURCE=upstream:<branch>` → 已 commit 但未 push（或本地领先上游）
+- `CCG_DIFF_SOURCE=origin-head` → 没有上游时，对比 origin/HEAD
+- `CCG_DIFF_FAIL=not-a-git-repo` → 提示用户在 git 仓库下使用，或显式给参数
+- `CCG_DIFF_FAIL=empty-diff` → 提示用户 "工作区干净 + 分支已对齐上游，没东西要评审"
+
+**Claude 必须在最终输出中显示对比的是哪个 source，让用户知道评审的范围。**
+
+### 步骤 3. 风险打分 + 自动选 mode（仅 B 模式）
+
+```bash
+CCG_DIR=<字面路径>
+source ~/.claude/commands/ccg.sh
+ccg_risk_score "$CCG_DIR/diff.txt" | tee "$CCG_DIR/risk.txt"
+```
+
+读取 `CCG_RISK_MODE`：
+- 用户已设 `CCG_MODE` 非空非 auto → 尊重用户选择
+- 否则用 risk_score 给的 mode：`export CCG_MODE=<推荐值>`
+
+> 设计立场：路径/内容/规模规则比 LLM 判断更**可解释、零成本、可改**。社区贡献者可以直接 PR 改权重。
+
+### 步骤 4. 写 prompt（结构化输出协议）
+
+**核心改动**：要求两端都按下面格式输出（便于 Claude 后续做对齐和分歧检测）。
+
+Prompt 模板：
+
+````
+你是代码评审者。仔细评审下面这段 diff，按 *严格* 的输出格式：
+
+===FINDINGS===
+[FINDING]
+file: <path>:<line>
+severity: critical|high|medium|low|nit
+category: bug|security|perf|readability|test|other
+title: <一行）
+detail: <2-4 行解释，必须可独立读懂>
+[/FINDING]
+（每个发现一个 [FINDING]…[/FINDING] 块；按 severity 倒序）
+
+===VERDICT===
+<3-5 行：整体判断 + 是否阻塞合并>
+
+===END===
+
+不要寒暄，不要在外面加任何文字。如果没有发现问题，FINDINGS 段落留空，但格式仍要保留。
+
+待评审的 diff（source: <CCG_DIFF_SOURCE>）：
+
+<贴入 diff 内容>
+````
+
+用 **Write tool**（不是 echo）写入：
+- `<CCG_DIR>/codex.prompt`
+- `<CCG_DIR>/gemini.prompt`
+
+两份 prompt 内容**完全相同**。让两个独立大脑产生差异——这正是分歧检测的来源。
+
+### 步骤 5. 并行调用 CLI（单消息两个 Bash 调用）
+
+helper 内部：检查大小 → 查缓存（命中则 $0）→ 真打 API → 落 cache + usage.log。
+
+**Codex** (timeout 260000)：
+```bash
+CCG_DIR=<字面路径>
+source ~/.claude/commands/ccg.sh
+ccg_codex "$CCG_DIR/codex.prompt" "$CCG_DIR/codex.result"
+echo "---ANSWER---"
+cat "$CCG_DIR/codex.result"
+```
+
+**Gemini** (timeout 140000)：
+```bash
+CCG_DIR=<字面路径>
+source ~/.claude/commands/ccg.sh
+ccg_gemini "$CCG_DIR/gemini.prompt" "$CCG_DIR/gemini.result"
+echo "---ANSWER---"
+cat "$CCG_DIR/gemini.result"
+```
+
+**两个 Bash 调用必须在同一条 assistant message 内发出**，才能真并行。
+
+### 步骤 6. 实际成本
+
+```bash
+CCG_DIR=<字面路径>
+source ~/.claude/commands/ccg.sh
+ccg_actual "$CCG_DIR/codex.prompt" "$CCG_DIR/codex.result" codex
+ccg_actual "$CCG_DIR/gemini.prompt" "$CCG_DIR/gemini.result" gemini
+```
+
+### 步骤 7. 健康判定 + 综合输出（**Pillar 1 关键**）
+
+| Codex | Gemini | 路径 |
+|---|---|---|
+| OK | OK | 完整三段输出（AGREEMENT / DIVERGENCE / BLINDSPOT）|
+| OK | FAIL | 只能输出 Codex 视角，标注分歧无法验证 |
+| FAIL | OK | 只能输出 Gemini 视角，标注分歧无法验证 |
+| FAIL | FAIL | Claude 独立回答 + 标注顾问不可用 |
+
+**Claude 的综合规则（必须严格遵守）：**
+
+1. **解析两边的 [FINDING] 块**，按 `(file, line, category, title 关键字)` 做对齐。Levenshtein 不重要，类别 + 文件 + 大致位置一致即视为同一发现。
+
+2. **AGREEMENT**：两边都报告了的发现。**降级展示**——通常这种问题 Claude 自己也能发现，新增信息量低。一句话带过即可，**不要展开**。
+
+3. **DIVERGENCE**：核心。**每条都展开**，必须包含：
+   - 一方说什么、另一方说什么（或没说）
+   - Claude 的判断：哪边更可能对？为什么？
+   - 用户行动建议（接受 / 驳回 / 需要人决定）
+   - 如果 Claude 也判断不了，**明确说"NEEDS HUMAN DECISION"**——这是工具最有价值的输出，不要装得自己都懂。
+
+4. **BLINDSPOT**：Claude 综合时怀疑两边都漏掉的点。慎用，每次最多 1-2 条，不要为了凑数硬挤。
+
+5. **VERDICT**：merge / fix / discuss 三选一，给一句话理由。
+
+### 步骤 8. 综合输出模板（**严格按此格式**）
+
+```
+## CCG v3 综合结果
+
+📍 评审范围：<source 标签，如 worktree | staged | upstream:origin/main>
+🎯 模式：<mode>（risk score: <分数> ｜ 触发: <reasons>）
+🩺 顾问状态：Codex ✓ ｜ Gemini ✓
+💰 本次成本：Codex $0.0023 + Gemini $0.0008 = **$0.0031**
+
+═══ AGREEMENT (N) ═══
+两边都指出，新增信息量低：
+- file:line — 简短描述（不展开）
+- ...
+
+═══ DIVERGENCE (M) ═══   ★ 这一段是 ccg 的核心价值 ★
+
+▸ DIV#1 — file:line
+  🔵 Codex: <Codex 的判断>
+  🟢 Gemini: <Gemini 的判断 / 没提到>
+  ⚖️  Claude 综合: <哪边更可信，为什么>
+  ➡️ 建议: <accept Codex / accept Gemini / NEEDS HUMAN DECISION>
+
+▸ DIV#2 — ...
+
+═══ BLINDSPOT (≤2) ═══
+两边都没提但 Claude 怀疑：
+- ...（如果不确定就不写）
+
+═══ VERDICT ═══
+<merge | fix-required | discuss>
+<一句话理由>
+
+═══ 来源原文（折叠展示）═══
+🔵 Codex (gpt-5-mini): <VERDICT 段原样>
+🟢 Gemini (gemini-2.5-flash): <VERDICT 段原样>
+```
+
+**关键纪律：**
+- AGREEMENT 段越短越好；DIVERGENCE 段越展开越好。这反映 ccg 的产品立场。
+- 任何"NEEDS HUMAN DECISION"的 DIVERGENCE 必须明确 — 这是 ccg 的核心价值信号
+- 失败原因摘要给用户（helper 已脱敏 API key/URL）
+- 用户没问怎么修，不给修复代码
+
+### 步骤 9. 落 ledger
+
+把上面综合输出的核心部分写到 `$CCG_DIR/synthesis.txt`（前 400 字符即可，ledger 自截断），然后：
+
+```bash
+CCG_DIR=<字面路径>
+source ~/.claude/commands/ccg.sh
+ccg_ledger_record "$CCG_DIR"
+```
+
+### 步骤 10. 清理
+
+```bash
+CCG_DIR=<字面路径>
+source ~/.claude/commands/ccg.sh
+ccg_cleanup "$CCG_DIR"
+```
+`CCG_KEEP_ARTIFACTS=1` 时跳过（调试用）。
+
+## 用量与历史查询（用户主动触发）
+
+```bash
+source ~/.claude/commands/ccg.sh
+ccg_usage --this-month                          # 本月成本
+ccg_usage --all                                 # 全部
+ccg_usage --since=2026-05                       # 自指定时间起
+
+ccg_ledger_query                                # 最近 5 条评审
+ccg_ledger_query "src/auth.ts"                  # 这个文件历史评审过几次
+```
+
+## 故障排除
+
+| 症状 | 原因 | 解决 |
+|---|---|---|
+| `CCG_PREFLIGHT_CODEX=missing` | 没装 Codex CLI | `npm i -g @openai/codex` |
+| `CCG_PREFLIGHT_GEMINI=missing` | 没装 Gemini CLI | `npm i -g @google/gemini-cli` |
+| `CCG_PREFLIGHT_GEMINI=no-api-key` | 任何 shell 模式拿不到 `GEMINI_API_KEY` | 写到 `~/.zshenv` |
+| `CCG_DIFF_FAIL=not-a-git-repo` | 不在 git 仓库 | cd 进仓库；或显式给参数 |
+| `CCG_DIFF_FAIL=empty-diff` | 工作区干净 + 分支与上游对齐 | 改点东西；或显式给参数；或对比指定 ref |
+| `CCG_*_FAIL=prompt-too-large-Nb-max-Mb` | prompt 超过 100KB | 缩小范围，或 `CCG_MAX_PROMPT_KB=500` |
+| `CCG_*_FAIL=Model ... not registered / 503` | 代理不支持当前模型 | 显式 `CCG_CODEX_MODEL=<代理支持的型号>` |
+| `CCG_GEMINI_FAIL=error-leaked-to-stdout` | 代理把错误写到 stdout | 检查 `$CCG_DIR/gemini.err`（需 `CCG_KEEP_ARTIFACTS=1`） |
+| `CCG_*_FAIL=timeout-Ns` | CLI 超时 | 调大 `CCG_*_TIMEOUT` |
+
+## 已知设计取舍
+
+- **Divergence over consensus**：放弃"给一份完整 review 报告"，转向"标记需要人裁决的点"。AGREEMENT 段意识形态上**故意降级**——单源 Claude 也能发现，无新增信号
+- **同 prompt 双投喂**：训练数据差异自然产生多样性，比拍脑袋分工（codex=arch、gemini=ux）更可靠
+- **24h 缓存**：调试同段代码反复跑时省 90% 费用；改了代码 prompt hash 自然变了，无需手动失效
+- **prompt 大小硬限**：100KB ≈ 32k token，比 codex/gemini context window 小一个数量级，防止把 repo 塞进去
+- **风险打分纯规则**：可解释、零成本、社区可改。LLM 自我打分会跟主评审产生循环
+- **Ledger JSONL**：append-only、grep-able。前 50 次看不出价值，长期是 stateless 工具复制不来的护城河
+- **失败不入缓存**：FAIL 的调用既不入 cache 也不入 usage.log（$0 失败不该污染历史）
+
+## 注意事项
+
+- 不要在 prompt 中泄露密钥（helper 会脱敏 stderr 和 ledger，但不脱敏 stdin）
+- Codex exec 在沙箱中运行，不会修改本地文件
+- 价格估算 ±15%（基于字符数 / 3.0 启发式）；要精确请用 tiktoken