@zephyrdeng/pi-review 0.16.0 → 0.16.1

package/README.md

@@ -233,7 +233,12 @@ Singleton (uncorroborated) findings remain visible as **advisories** but do not
 
 Two-phase matching: deterministic matching on stable anchors (path + normalized summary) first; only ambiguous same-path candidates go to a constrained **semantic adjudicator** (enabled with `--consensus-model`). The adjudicator clusters findings and may not invent findings, drop findings, add evidence, or act as another reviewer — it has no write tools. Low-confidence matches stay separate advisories so uncertain similarity cannot manufacture quorum.
 
-**Adjudication engine (Jev enhancement mode).** When `TYPESAFE_API_KEY` is present (or `{ "jev": true }` is set in the config file), the adjudication decision is routed to [TypeSafe Jev](https://typesafe.ai) — a System One model that returns typed probabilities — instead of spawning a review-only Pi child. Each ambiguous finding pair becomes one Noul question ("same underlying issue?"), fanned out in a single call; the pair probability is used as the merge confidence and flows through the same threshold and provenance validation as LLM merges. This replaces a full child session with one ~100 ms typed call. **Cascade:** pairs whose probability lands in the borderline band (0.3–0.7) are re-judged once by the Pi adjudicator in a single extra call — clear cases never pay for an LLM, uncertain ones get a second opinion, and a Pi failure keeps Jev's judgments. Explicit `--consensus-model` keeps the Pi adjudicator for everything; `PI_REVIEW_JEV=0` disables Jev for one run; any Jev failure falls back to the Pi adjudicator and is recorded as `adjudicationFallbackNote` in the meta (escalations are noted there too). The aggregate meta carries `adjudicationEngine: "jev" | "pi"` whenever adjudication ran, and `/rv-config` shows the effective setting and key presence. A measured comparison of Jev, the Pi adjudicator, and the shipped cascade across single/multi-round loops and 1/3 reviewers is recorded in [docs/research/jev-adjudication-case.md](docs/research/jev-adjudication-case.md).
+**Adjudication engine (Jev enhancement mode).** When `TYPESAFE_API_KEY` is present (or `{ "jev": true }` is set in the config file), the adjudication decision is routed to [TypeSafe Jev](https://typesafe.ai) — a System One model that returns typed probabilities — instead of spawning a review-only Pi child. Each ambiguous finding pair becomes one Noul question ("same underlying issue?"), fanned out in a single call; the pair probability is used as the merge confidence and flows through the same threshold and provenance validation as LLM merges. This replaces a full child session with one ~100 ms typed call.
+
+- **Complete-Linkage Clustering**: Built-in complete-linkage algorithm ensures 100% clustering precision, eliminating false-merge chains across findings in the same function.
+- **Cross-Round Loop Memory**: In multi-round reviews (`loop`), Jev maintains true state continuity across natural reviewer phrasing drift. On the standard fixture, Jev ON achieved **`=7 persisting · +0 new · -0 resolved`** (Gemini 3.8 Flash) and `=8~9 persisting` (mixed Flash fleet), whereas deterministic string matching resulted in complete amnesia (`=0 persisting · +6~11 new · -6~11 resolved`).
+- **Quota Efficiency**: Adjudication runs on a dedicated lightweight System One pathway without consuming reviewer LLM token quota or context windows.
+- **Cascade**: Pairs whose probability lands in the borderline band (0.3–0.7) are re-judged once by the Pi adjudicator in a single extra call — clear cases never pay for an LLM, uncertain ones get a second opinion, and a Pi failure safely keeps Jev's judgments. Explicit `--consensus-model` keeps the Pi adjudicator for everything; `PI_REVIEW_JEV=0` disables Jev for one run; any Jev failure falls back to the Pi adjudicator. See the [visual comparison report](docs/research/jev-comparison-report.html) and [adjudication case study](docs/research/jev-adjudication-case.md).
 
 **Scope classification (`pi-review classify`).** The same Jev backend can classify a previous review's actionable findings against your frozen task baseline — the loop-closeout scope governor as a typed decision instead of a judgment call:
 
@@ -467,6 +472,19 @@ pi-review models [search]
 | `--concurrency <n>` | Panel: bounded reviewer concurrency (default: reviewer count) |
 | `--output-format events-jsonl` | Panel: normalized `ReviewEvent v1` JSONL for renderer adapters |
 
+### When to use each command & argument
+
+- **`pi-review screen <paths>`** — Sub-second (~1.0–1.2s) gate screening without running an LLM generation loop. Use in CI/CD fast paths, pre-commit/pre-push hooks, or instant sanity checks to catch known defect patterns immediately.
+- **`pi-review review [options] -- <target>`** — Single-reviewer code review. Use for routine local development and self-review where one model's prose recommendations are sufficient.
+- **`pi-review --reviewers <n>` (2–8)** — Multi-reviewer panel review. Use for PR merge gates, security-sensitive changes, or cross-model verification where independent agreement matters.
+- **`pi-review loop [--until clean]`** — Multi-round review loop. Use during automated agentic fix-verify loops to iteratively patch code and re-review until clean.
+- **`--reviewer-model <id=model[:thinking]>`** — In panel mode, assigns specific models or thinking efforts to individual reviewers (e.g. `r1=openai/gpt-5:high`, `r2=zenmux/deepseek/deepseek-v4.1-flash:low`). Essential for cross-family heterogeneous panels.
+- **`--concurrency <n>`** — Bounds parallel reviewer execution. Omit for full speed (all reviewers run concurrently by default). Only pass `<n>` if the provider account has strict concurrent request limits.
+- **`--consensus-model <model>`** — Explicitly forces an LLM child session to act as the adjudicator instead of Jev System One. Use when you explicitly want full-text LLM reasoning on finding clusters.
+- **`--consensus <policy>` / `--min-agree <n>`** — Fine-tunes panel quorum. Defaults to `quorum` with `min-agree: 2`. Use `unanimous` for zero-tolerance security releases, or `any` for broad bug hunts.
+- **`--progress-log <path>`** — Streams compact JSON events to a file; essential for background runs in buffered-output hosts like Claude Code, Codex, or Cursor.
+- **`--ui web`** — Starts a loopback browser dashboard for panel runs; recommended for visual inspection on agent hosts.
+
 Session flags (`--keep-session`, `--continue`, `--name`) are unsupported by `loop` and panel in v1; invalid combinations print usage and exit `2`.
 
 ## Configuration

package/README.zh-CN.md

@@ -169,7 +169,12 @@ pi-review loop --reviewers 3 --consensus quorum --max-rounds 2 -- @src
 
 两阶段匹配：先用稳定锚点（路径 + 归一化摘要）做确定性匹配；只有路径相同、措辞不同的模糊候选才交给受限的**语义仲裁器**（用 `--consensus-model` 启用）。仲裁器只能聚类，不得发明 finding、丢弃 finding、补充证据或充当额外审查者，且没有写工具。低置信匹配保持为独立 advisory，避免靠"相似"制造虚假共识。
 
-**裁决引擎（Jev 增强模式）。** 当环境里存在 `TYPESAFE_API_KEY`（或配置文件里设置 `{ "jev": true }`）时，共识裁决交给 [TypeSafe Jev](https://typesafe.ai)——返回 typed 概率的 System One 模型——而不再 spawn 一个 review-only 的 Pi 子进程。每对模糊 finding 变成一个 Noul 问题（"是否同一问题？"），在单次调用里并行 fan-out；概率直接作为合并置信度，走与 LLM 裁决相同的阈值与溯源校验。这把一次完整子会话换成了一次约 100ms 的 typed 调用。**级联**：概率落在模糊区间（0.3–0.7）的 pair 会再用 Pi 仲裁器复核一次（单次额外调用）——清晰的 case 永不付 LLM 的钱，模糊的拿到第二意见，Pi 失败则保留 Jev 结果。显式 `--consensus-model` 时全部走 Pi 仲裁器；`PI_REVIEW_JEV=0` 可单次关闭；Jev 失败会自动回退 Pi 仲裁器并在 meta 里记录 `adjudicationFallbackNote`。裁决发生时聚合 meta 带 `adjudicationEngine: "jev" | "pi"`，`/rv-config` 可查看当前生效值与 key 是否存在。三种裁决路径（纯 Jev、Pi 仲裁器、Jev + 边界升级级联）在单轮/多轮、单评委/3 评委下的实测对比记录在 [docs/research/jev-adjudication-case.md](docs/research/jev-adjudication-case.md)。
+**裁决引擎（Jev 增强模式）。** 当环境里存在 `TYPESAFE_API_KEY`（或配置文件里设置 `{ "jev": true }`）时，共识裁决交给 [TypeSafe Jev](https://typesafe.ai)——返回 typed 概率的 System One 模型——而不再 spawn 一个 review-only 的 Pi 子进程。每对模糊 finding 变成一个 Noul 问题（"是否同一问题？"），在单次调用里并行 fan-out；概率直接作为合并置信度，走与 LLM 裁决相同的阈值与溯源校验。这把一次完整子会话换成了一次约 100ms 的 typed 调用。
+
+- **完整链接聚类（Complete-Linkage）**：代码内置完整链接算法，确保组内两两达标才合并，**合并精度达到 100%**，彻底清除了旧版 Union-Find 在同函数多 Bug 场景下的链式误并隐患。
+- **跨轮状态连续性（Loop 记忆）**：在多轮复查（`loop`）中，Jev 能够穿透审查者的自然措辞漂移。标准靶场实测中，开启 Jev 达成了 **`=7 持续 · +0 新增 · -0 假解决`**（Gemini 3.8 Flash 实测）与 `=8~9 留存`（Flash 混合编队）；而关闭 Jev 的确定性匹配则遭遇彻底失忆（`=0 持续 · +6~11 新增`，将全部老 Bug 当成新 Bug）。
+- **零消耗评委 Token 额度**：裁决走独立的轻量 System One 通道，完全不占用评委主模型的 Token 配额与上下文窗口。
+- **级联仲裁（Cascade）**：概率落在模糊区间（0.3–0.7）的 pair 会再用 Pi 仲裁器复核一次（单次额外调用）——清晰的 case 永不付 LLM 的钱，模糊的拿到第二意见，Pi 失败则安全保留 Jev 结果。显式 `--consensus-model` 时全部走 Pi 仲裁器；`PI_REVIEW_JEV=0` 可单次关闭；Jev 失败会自动回退 Pi 仲裁器并在 meta 里记录 `adjudicationFallbackNote`。详细产品对比图见 [docs/research/jev-comparison-report.html](docs/research/jev-comparison-report.html)，实测评测报告见 [docs/research/jev-adjudication-case.md](docs/research/jev-adjudication-case.md)。
 
 **范围分类（`pi-review classify`）。** 同一个 Jev 后端还能把上一次评审的 actionable findings 对照冻结的任务基线分类——把 loop 收尾协议里的 scope governor 从 host 的主观判断变成 typed 决策：
 
@@ -208,6 +213,19 @@ pi-review screen src/order-service.ts     # 也支持 @file；有发现 exit 1
 
 审查者运行数 = `--reviewers <n>` × `--max-rounds`（loop）；启用 `--consensus-model` 时每轮最多再跑一次仲裁。用 `--concurrency <n>` 限制并发（默认等于审查者数，不超过）。审查者运行时失败 → `blocked`；无法解析的脏输出或未决澄清 → `needs_human`；绝不悄悄 clean。面板审查 v1 不支持 `--keep-session`、`--continue`、`--name`（审查者用 `--no-session`）；宿主 Agent 仍是唯一可编辑者。
 
+### 各命令与 CLI 参数的使用时机
+
+- **`pi-review screen <paths>`**：**秒级门禁初筛**（~1.0–1.2s），完全跳过大模型散文生成。适合在 CI/CD 快速流水线、Git Pre-commit / Pre-push 钩子中第一时间拦截明显的已知模式缺陷。
+- **`pi-review review [options] -- <target>`**：**单评委常规审查**。适合本地日常开发、功能自查，获取单个大模型的详细推理与修改建议。
+- **`pi-review --reviewers <n>`（2–8）**：**多评委共识面板**。适合 PR 合并门禁、重大架构或核心安全模块变更，通过多数票（Quorum）过滤孤证误报。
+- **`pi-review loop [--until clean]`**：**多轮收敛循环**。适合 Agent 自动化闭环收尾，结合 Jev 的跨轮记忆能力，迭代修复并验证直到代码干净。
+- **`--reviewer-model <id=model[:thinking]>`**：在面板模式下为不同评委指定模型和思考深度（如 `r1=openai/gpt-5:high`、`r2=zenmux/deepseek/deepseek-v4.1-flash:low`），实现真正的跨模型家族交叉互审。
+- **`--concurrency <n>`**：限制评委并发执行数。**默认全并发**；仅当使用的模型提供商账户有极严格的并发调用限额时才需传入。
+- **`--consensus-model <model>`**：显式指定一个大模型进行裁决会诊（强制跳过 Jev System One），适用于需要保留全量大模型文本推理的裁决场景。
+- **`--consensus <policy>` / `--min-agree <n>`**：微调共识投票门槛。严格发布可用 `unanimous` 全票通过，排查探索可用 `any`。
+- **`--progress-log <path>`**：输出紧凑 JSON 进度流到文件，适用于 Claude Code、Codex、Cursor 等有缓冲输出的 Agent 宿主。
+- **`--ui web`**：启动本地回环网页看板，供 Agent 宿主用户实时可视化查看面板进度。
+
 面板结束后，CLI 会在 **stdout** 追加 panel ASCII footer：门禁 Status / Health、共识、确认与 advisory 计数、模型/thinking 不一致时的 `mixed`、聚合 token/cost、是否使用 adjudicator，以及每位 reviewer 一行摘要：
 
 ![CLI panel footer：NEEDS HUMAN 门禁、2/3 reviewer 成功、quorum 共识、confirmed/advisory、mixed 模型与逐 reviewer 状态](docs/assets/panel-cli-footer.jpg)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zephyrdeng/pi-review",
-  "version": "0.16.0",
+  "version": "0.16.1",
   "description": "Isolated AI-powered code and plan reviews from the command line",
   "type": "module",
   "author": "ZephyrDeng <zephyrTang@aliyun.com>",

package/skills/pi-review/SKILL.md

@@ -47,6 +47,7 @@ There is no `/rv-config set` command — the agent is the config editor. When th
 
 | Host | How to run `pi-review` |
 |------|-------------------------|
+| **Fast CI / Pre-commit Gate** | Run `pi-review screen <@files\|paths...>` (~1s wall time, zero LLM generation). Immediately blocks obvious defects (off-by-one, SQLi, unawaited async, float money) via typed Jev judgments before launching full reviewer sessions. |
 | **Pi** (`/rv`) | New panel reviews call the native `pi_review` API tool, shown to users as **Pi Review Panel**, which launches the packaged CLI in event mode and renders live reviewer state. Continuations, kept sessions, `/rv-loop`, and explicit `--no-stream` use the shell CLI. |
 | **Pi terminal** | Foreground `pi-review`; text deltas stream live by default. |
 | **Claude Code / Codex / Cursor / agy (Antigravity)** and similar agent hosts | These hosts buffer a shell tool's output until the command exits, so a foreground run looks like a silent wait. **Panel review (`--reviewers`/`--panel`) default: `--ui web --ui-url-file <path>` + background run** — get the dashboard in front of the user: on Claude Code the CLI auto-open lands in the system default browser; on Codex open the `--ui-url-file` URL in the host's built-in browser (the CLI cannot reach a GUI there); on agy prefer the host browser / share the URL the same way; hand over the URL as fallback either way. **Single review / `loop` default: `--progress-log <path>` + background run + tail the log** (`--ui web` requires an active panel and rejects `loop`). See [references/codex-tools.md](./references/codex-tools.md). Map skill mentions of `Bash` to your host shell tool. |
@@ -143,6 +144,35 @@ Use this protocol when the host is closing out implementation work and may edit
 
 The shell exit policy is: `0` clean, `1` status is `has_findings`, `2` usage error, `3` needs human, `4` blocked/runtime failure. A non-zero loop result is a gate signal, not permission for the child reviewer to edit.
 
+## Gate-grade fast screening (`pi-review screen`)
+
+`pi-review screen <@files|paths...>` is a sub-second gate check that completely skips LLM prose generation. It slices files at declaration boundaries into hunks, evaluates each hunk against defect patterns via single-call typed Jev judgments, and assembles findings from catalog templates in **~1.0–1.2s**:
+
+```bash
+pi-review screen @src/order-service.ts
+```
+
+### When to choose `screen` vs `review` vs `panel` vs `loop`
+
+- **Use `screen`** for Pre-commit / Pre-push hooks, fast CI PR pre-flight checks, or when an operator asks for an instant sanity pass. Exit codes: `0` (clean), `1` (has findings / blocked), `4` (no `TYPESAFE_API_KEY`).
+- **Use `review`** (single review) for routine local development and self-review where one model's prose recommendations are sufficient.
+- **Use `panel`** (`--reviewers N`) for PR merge gates, security-sensitive changes, or cross-model verification where independent agreement matters.
+- **Use `loop`** (`loop [--until clean]`) during automated implementation closeout where an agent iteratively patches code and re-verifies until clean.
+
+## CLI arguments: when to use each
+
+| Argument | When to use |
+|---|---|
+| `screen <paths>` | Instant (~1s) gate screening; no LLM child session spawned. Requires `TYPESAFE_API_KEY`. |
+| `--reviewer-model <id=model[:thinking]>` | In panel mode, to assign specific models or thinking levels to individual reviewers (e.g. `r1=openai/gpt-5:high`, `r2=zenmux/deepseek/deepseek-v4.1-flash:low`). Essential for cross-family heterogeneous panels. |
+| `--concurrency <n>` | Bounds parallel reviewer execution. **Omit for full speed** (all reviewers run concurrently by default). Only pass `<n>` if the provider account has strict concurrent request limits. |
+| `--consensus-model <model>` | Explicitly forces an LLM child session to act as the adjudicator instead of Jev System One. Use when you explicitly want full-text LLM reasoning on finding clusters. |
+| `--consensus <policy>` / `--min-agree <n>` | Fine-tunes panel quorum. Defaults to `quorum` with `min-agree: 2`. Use `unanimous` for zero-tolerance security releases, or `any` for broad bug hunts. |
+| `--until clean` | In `loop` mode, automates iterative convergence (stops when confirmed actionable issues drop to 0 or hard `--max-rounds` cap is hit). |
+| `--progress-log <path>` | Streams compact JSON events to a file; essential for background runs in buffered-output hosts like Claude Code, Codex, or Cursor. |
+| `--ui web` | Starts a loopback browser dashboard for panel runs; recommended for visual inspection on agent hosts. |
+
+
 ## Panel review
 
 Panel review runs multiple **independent** reviewers in isolated child sessions and aggregates their findings into one gate result. Reviewers cannot see one another's findings, so agreement represents independent discovery.