@zephyrdeng/pi-review 0.6.2 → 0.7.1

package/README.md

@@ -18,7 +18,8 @@ Works as a standalone CLI, a Pi package (extension + skill), or integrated into
 
 - **Isolated review sessions** — each review runs in a clean child process with no shared state
 - **Multiple review modes** — code review, multi-lens plan review, adversarial challenge review
-- **Structured output** — human-readable ASCII footer on stdout; `PI_REVIEW_META_JSON` on stderr for automation
+- **Structured output** — explicit `status`, structured findings, and a human-readable ASCII footer; one-line `PI_REVIEW_META_JSON` on stderr for automation
+- **Loop review gate** — bounded, isolated review rounds with `pi-review loop --max-rounds <n>`; the host remains the only editor
 - **Model-agnostic** — use any model available in your Pi installation
 - **Live streaming** — child review output is forwarded as it arrives (use `--no-stream` to buffer)
 - **Progress logging for AI hosts** — `--progress-log <path>` writes a live JSON event log so agent hosts that buffer tool stdout (Claude Code, Codex, ...) can still show real-time progress
@@ -102,6 +103,9 @@ pi-review --mode plan -- @docs/architecture.md
 # Adversarial challenge review
 pi-review --mode challenge -- @docs/design.md
 
+# Bounded review-only gate (default: 3 rounds)
+pi-review loop --max-rounds 3 -- @src
+
 # List available models
 pi-review models
 ```
@@ -114,6 +118,71 @@ pi-review models
 | `plan` | Broad plan/architecture review through multiple expert lenses: engineering, product, security, QA, operations, and DX. |
 | `challenge` | Adversarial review that pressure-tests assumptions, dependencies, reversibility, failure modes, and migration paths. |
 
+## Loop Review
+
+`pi-review loop` runs a bounded sequence of full, isolated review runs against the current working tree:
+
+```bash
+pi-review loop --max-rounds 3 -- @src
+pi-review loop --mode challenge --max-rounds 2 -- @docs/design.md
+```
+
+Each round is review-only. The process never edits, patches, waits for filesystem changes, or asks the child session to fix findings. It stops immediately on `clean`, `needs_human`, or `blocked`; otherwise it stops when the round budget is exhausted. Every round emits one `PI_REVIEW_META_JSON` line in order, and the final human summary lists each round's status, verdict, duration, and finding counts.
+
+This is a **host-driven gate**: if findings remain, the host or human fixes only accepted in-scope findings and invokes `loop` again. For patch-by-patch agent closeout, `--max-rounds 1` gives the host a fix point after each review; use a larger budget only when repeated review of the unchanged tree is intentional. `loop` accepts normal review target/model/progress options but rejects `--keep-session`, `--continue`, and `--name` in v1.
+
+## 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.
+
+```bash
+# Single panel review
+pi-review --reviewers 3 --consensus quorum --min-agree 2 -- @src
+# Expert preset (correctness, security, testing lenses)
+pi-review --panel code-experts --consensus majority -- @src
+# Panel loop review (up to reviewer_count × max-rounds reviewer runs + adjudication)
+pi-review loop --reviewers 3 --consensus quorum --max-rounds 2 -- @src
+```
+
+### Consensus
+
+A finding becomes a **confirmed finding** (gate-relevant) only when enough independent reviewers mark the issue **actionable**. Otherwise it stays a non-blocking **advisory**. Multi-reviewer panels default to **quorum** with minimum agreement **2** so panel mode never silently becomes any-finding fail-closed; single-review stays threshold one.
+
+| Policy | Threshold |
+|--------|----------|
+| `any` | one actionable reviewer confirms |
+| `quorum` (default) | configured minimum agreement (default 2; `--min-agree`) |
+| `majority` | `floor(reviewers / 2) + 1` |
+| `unanimous` | every reviewer |
+
+Singleton (uncorroborated) findings remain visible as **advisories** but do not change clean status or fail the gate. Confirmed actionable clusters produce `has_findings`; no confirmed clusters produce `clean`.
+
+### Aggregation
+
+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.
+
+### Cost and failure
+
+Reviewer runs = `--reviewers <n>` × `--max-rounds` (loop); one adjudication call may run per round when `--consensus-model` is set. Use `--concurrency <n>` to bound provider/machine pressure (default: reviewer count, never exceeds it). Reviewer runtime failure → `blocked`; unstructured dirty output or unresolved clarification → `needs_human`; never silently clean. Panel review rejects `--keep-session`, `--continue`, and `--name` (reviewers run `--no-session`); the host agent remains the only editor.
+
+### Machine output
+
+A panel evaluation emits **one** aggregate `PI_REVIEW_META_JSON` record with additive fields: `strategy: "panel"`, `configuredReviewers`, `successfulReviewers`, `consensusPolicy`, `consensusThreshold`, `panelHealth`, `confirmedClusters`, `advisories`, and per-`reviewers` outcomes. Top-level `findings` contain confirmed clusters only; advisories remain separate. Existing single-review keys remain unchanged, so older consumers can ignore the new fields.
+
+### Live Pi progress and event replay
+
+In Pi, `/rv @target` calls the native `pi_review` tool. It renders each reviewer as an independent live row with lifecycle state, active tool, elapsed time, and token usage; expand the tool result with `Ctrl+O` for bounded activity and final findings/provenance.
+
+Renderer adapters can consume the stable, versioned event stream directly:
+
+```bash
+pi-review --panel code-experts --output-format events-jsonl -- @src
+```
+
+This mode writes only `ReviewEvent v1` JSONL to stdout. Events have one `runId`, monotonically increasing `seq`, bounded/redacted activity text, and end in exactly one `panel.completed` event containing the same `PanelReviewMeta` as the default CLI path. The reducer is exported as `createPanelViewState()` and `reducePanelEvent()` for deterministic live delivery and replay.
+
+Panel reviewers use the hard allowlist `read,grep,find,ls`. Shell and mutation-capable tools are rejected before a reviewer starts. `Ctrl+C` cancels the reviewer and adjudicator process trees, emits cancellation lifecycle events, and produces one blocked final event.
+
 ## Output Format
 
 Every review produces Markdown with these sections:
@@ -124,6 +193,14 @@ approve | request_changes | needs_clarification | blocked
 
 ## Summary
 ## Findings
+### F1: <summary>
+- Severity: critical | high | medium | low
+- Path: <path or none>
+- Actionable: yes | no
+- Evidence: <concrete evidence>
+- Impact: <why it matters>
+- Recommendation: <specific next step>
+
 ## Risks and Blind Spots
 ## Open Questions
 ```
@@ -133,12 +210,37 @@ The CLI appends a readable ASCII footer on **stdout**:
 ```
 ── pi-review ────────────────────────────
   Verdict     ! REQUEST CHANGES
+  Status      HAS FINDINGS
   Mode        code
+  Findings    1 actionable / 1 total
+  Model       provider/model
+  Thinking    xhigh
+  Tokens      in 17.6K · out 512 · cache 2.0K · reason 0
   Duration    42.3s
 ──────────────────────────────────────────
 ```
 
-For scripts, parse **`PI_REVIEW_META_JSON:`** from **stderr** (same fields as before). Set `PI_REVIEW_META_STDOUT=1` to also emit that JSON line on stdout.
+`Thinking` shows the requested thinking level when set; `Tokens` shows the child session's token usage (`in`/`out`/`cache`/`reason`) parsed from the `--mode json` event stream — available only when `--progress-log` is used (otherwise both lines are omitted).
+
+For scripts, parse **`PI_REVIEW_META_JSON:`** from **stderr**. Existing keys remain, with additive fields:
+
+```json
+{"reviewMode":"code","verdict":"request_changes","verdictSource":"parsed","status":"has_findings","findings":[{"id":"F1","severity":"high","path":"src/cli.ts","summary":"Dirty reviews exit zero","actionable":true}],"actionableCount":1,"durationMs":42300,"model":"provider/model","thinking":"xhigh","usage":{"input":18031,"output":512,"cacheRead":2048,"cacheWrite":0,"reasoning":0,"totalTokens":18591,"costTotal":0.05}}
+```
+
+`status` is one of `clean`, `has_findings`, `needs_human`, or `blocked`: `approve` with no actionable findings is `clean`; `request_changes` or actionable findings are `has_findings`; `needs_clarification` is `needs_human`; runtime/fatal failures are `blocked`. Each finding always has `summary` and `actionable`; `id`, `severity`, and `path` are present when parsed. `thinking` and `usage` are additive and present only when available (token usage requires `--progress-log`). The line remains a single additive JSON record, so older consumers can ignore unknown keys. Set `PI_REVIEW_META_STDOUT=1` to emit it on stdout instead.
+
+The parser prefers the exact `### F1` shape above but also accepts legacy `###` headings and top-level finding lists. When `Actionable` is missing, findings under `request_changes` default to actionable and other verdicts default to non-actionable. A missing/unrecognized verdict falls back to `needs_clarification` / `needs_human` and includes `parseError`; runtime failures always remain `blocked`.
+
+### Exit codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | Final status is `clean` |
+| `1` | Final status is `has_findings` / loop budget exhausted |
+| `2` | CLI usage or argument error |
+| `3` | `needs_human` — clarification or a decision is required |
+| `4` | `blocked` — child/runtime failure or review cannot proceed |
 
 ## Session Management
 
@@ -150,19 +252,17 @@ pi-review --mode challenge --keep-session -- @docs/design.md
 pi-review --continue <sessionHandle> --mode challenge --model provider/model -- "expand finding 2"
 ```
 
-## Live Progress in AI Hosts
+## Live Progress and Token Usage
+
+`pi-review` always runs the child in `--mode json` internally. In streaming mode it forwards **readable text deltas** to stdout live and writes **semantic milestone notices** to stderr — `pi-review: review started`, `pi-review: tool <name> started/finished`, `pi-review: review finished`. Token usage (`input`/`output`/`cache`/`reasoning`) is accumulated by default and shown in the ASCII footer and `PI_REVIEW_META_JSON` — **no `--progress-log` required**.
 
-Agent hosts like Claude Code, Cursor, and Codex typically buffer a Bash tool's stdout until the command exits, so a multi-minute review can look like a silent wait followed by one large dump — even though `pi-review` streams by default. `--progress-log <path>` sidesteps this: it runs the child in `--mode json` and writes its event log to a file in real time, independent of what the calling tool does with stdout.
+Agent hosts like Claude Code, Cursor, and Codex typically buffer a Bash tool's stdout until the command exits. The stderr milestone notices give you progress signals without tailing a file. The final Markdown review + ASCII footer arrive on stdout when the process exits.
 
-The bundled **pi-review** agent skill tells parent agents to use `--progress-log` by default on those hosts (Pi `/rv` stays on default streaming). Details: [`skills/pi-review/SKILL.md`](skills/pi-review/SKILL.md) and [`skills/pi-review/references/codex-tools.md`](skills/pi-review/references/codex-tools.md).
+`--progress-log <path>` is now an **optional** convenience for fine-grained debugging: it tees the raw `--mode json` event stream to a file. It no longer gates token visibility. Details: [`skills/pi-review/SKILL.md`](skills/pi-review/SKILL.md) and [`skills/pi-review/references/codex-tools.md`](skills/pi-review/references/codex-tools.md).
 
 ```bash
-# Start the review in the background, writing structured progress events to a file
+# Optional: capture the full event log for debugging
 pi-review --progress-log /tmp/pi-review.jsonl -- @src/foo.ts &
-
-# Tail it from another process/tool (e.g. Claude Code's Monitor tool) for live updates.
-# `message_update` and `tool_execution_update` carry high-frequency token-level deltas —
-# excluding them keeps the feed to milestone events (tool start/end, turn end, agent end).
 tail -f -n +1 /tmp/pi-review.jsonl | jq -c --unbuffered '
   select(.type != "message_update" and .type != "tool_execution_update")
 '
@@ -173,7 +273,8 @@ The JSON event schema is pi CLI's own internal format, not a contract `pi-review
 ## CLI Reference
 
 ```
-pi-review [options] -- <@files|text...>
+pi-review [review] [options] -- <@files|text...>
+pi-review loop [options] -- <@files|text...>
 pi-review models [search]
 ```
 
@@ -190,6 +291,16 @@ pi-review models [search]
 | `--name <name>` | Session name (with `--keep-session`) |
 | `--no-stream` | Buffer child output until exit (default: stream live) |
 | `--progress-log <path>` | Stream child `--mode json` events to this file (cannot combine with `--no-stream`) |
+| `--max-rounds <n>` | Positive loop review budget (default: `3`; `loop` only) |
+| `--reviewers <n>` | Panel: number of independent reviewers (2-8; activates panel mode) |
+| `--panel <name>` | Panel: named expert-panel preset (cannot combine with `--reviewers`) |
+| `--consensus <policy>` | Panel: `any \| quorum \| majority \| unanimous` (default: `quorum`) |
+| `--min-agree <n>` | Panel: minimum reviewers for quorum (default: `2`; quorum only) |
+| `--consensus-model <model>` | Panel: model for semantic consensus adjudication |
+| `--concurrency <n>` | Panel: bounded reviewer concurrency (default: reviewer count) |
+| `--output-format events-jsonl` | Panel: normalized `ReviewEvent v1` JSONL for renderer adapters |
+
+Session flags (`--keep-session`, `--continue`, `--name`) are unsupported by `loop` and panel in v1; invalid combinations print usage and exit `2`.
 
 ## Configuration
 
@@ -200,9 +311,10 @@ Override defaults via environment variables:
 | `PI_BIN` | Pi executable path (default: `pi`) |
 | `PI_REVIEW_HOME` | Directory containing `review-presets.json` and `system-prompt.md` |
 | `PI_REVIEW_PRESETS` | Path to presets JSON file |
+| `PI_REVIEW_PANEL_PRESETS` | Path to panel presets JSON file |
 | `PI_REVIEW_SYSTEM_PROMPT` | Path to system prompt file |
 | `PI_REVIEW_SESSION_DIR` | Directory for persisted review sessions |
-| `PI_REVIEW_META_STDOUT` | Set to `1`/`true` to also print `PI_REVIEW_META_JSON` on stdout (default: stderr only) |
+| `PI_REVIEW_META_STDOUT` | Set to `1`/`true` to print `PI_REVIEW_META_JSON` on stdout instead of stderr |
 
 ## Pi Package Usage
 
@@ -213,7 +325,7 @@ After installing as a Pi package, use the `/rv` slash command:
 /rv --mode challenge @docs/design.md
 ```
 
-The `/rv` command injects a task message for the parent agent (Pi host rules: default streaming, no automatic `--no-stream` or `--progress-log` + the `pi-review` CLI to run). The agent follows the **pi-review** skill and runs an isolated child session. Use plain `/rv @path` in Pi — no extra streaming flags needed.
+The `/rv` command injects a task message for the parent agent. New Pi reviews call the native `pi_review` tool, which launches the packaged `pi-review` CLI in normalized event mode and renders live Panel rows. Use plain `/rv @path` in Pi — no extra streaming flags needed. `--continue`, `--keep-session`, and explicit `--no-stream` retain the single-review CLI path.
 
 ```
 /rv models
@@ -235,7 +347,7 @@ Completions are a hint layer only; execution remains skill-driven. When the mode
 
 ## Security
 
-- Each review runs in an isolated child Pi session
+- Each review and every loop round runs in an isolated child Pi session
 - Default runs use `--no-session` — no child context is stored
 - `--keep-session` stores only the child review session for explicit follow-up
 - The review session is read-only: no file edits, patches, commits, or deployments

package/README.zh-CN.md

@@ -42,6 +42,7 @@ pi-review -- @src/foo.ts
 pi-review --model openai/gpt-5.5 -- @src/foo.ts
 pi-review --mode plan -- @docs/architecture.md
 pi-review --mode challenge -- @docs/design.md
+pi-review loop --max-rounds 3 -- @src
 pi-review models
 ```
 
@@ -53,6 +54,70 @@ pi-review models
 | `plan` | 多视角方案 / 架构审查 |
 | `challenge` | 对抗式审查，压测假设与证据缺口 |
 
+## Loop Review
+
+`pi-review loop` 会对当前工作树执行有上限的、彼此隔离的只读审查轮次：
+
+```bash
+pi-review loop --max-rounds 3 -- @src
+```
+
+每轮都是完整 review run；命令不会编辑、打补丁、等待文件变化，也不会让子会话修复问题。遇到 `clean`、`needs_human`、`blocked` 会提前停止；仍有 actionable finding 时，在预算耗尽后以非零状态退出并输出逐轮摘要。宿主 Agent 或人工负责筛选并修复任务范围内的问题，再重新调用命令。需要在每次修复之间留出宿主处理点时，使用 `--max-rounds 1`。
+
+`loop` 复用普通审查的 mode/model/progress/target 参数；v1 明确不支持 `--keep-session`、`--continue`、`--name`。
+
+## Panel Review（面板审查）
+
+面板审查让多个**独立**审查者在隔离子会话中并行评审，再聚合为同一个门禁结论。审查者看不到彼此的发现，因此一致代表独立发现。
+
+```bash
+# 单次面板审查
+pi-review --reviewers 3 --consensus quorum --min-agree 2 -- @src
+# 专家预设（正确性 / 安全 / 测试三视角）
+pi-review --panel code-experts --consensus majority -- @src
+# 面板 loop（最多 reviewer 数 × max-rounds 次审查 + 仲裁）
+pi-review loop --reviewers 3 --consensus quorum --max-rounds 2 -- @src
+```
+
+### 共识（Consensus）
+
+只有当足够多的独立审查者把同一问题标为 **actionable** 时，该 finding 才成为 **confirmed finding**（参与门禁）；否则保留为非阻塞的 **advisory**（建议）。多审查者面板默认 **quorum**，最低同意数 **2**，避免面板模式悄悄退化为"任一发现即 fail-closed"；单审查仍为阈值 1。
+
+| 策略 | 阈值 |
+|------|------|
+| `any` | 1 个 actionable 审查者即确认 |
+| `quorum`（默认） | 配置的最低同意数（默认 2，用 `--min-agree`） |
+| `majority` | `floor(审查者数 / 2) + 1` |
+| `unanimous` | 全体审查者 |
+
+单条（未被交叉印证的）发现作为 **advisory** 可见，但不改变 clean 状态、不会让门禁失败。确认的可操作簇产生 `has_findings`；无确认簇则产生 `clean`。
+
+### 聚合
+
+两阶段匹配：先用稳定锚点（路径 + 归一化摘要）做确定性匹配；只有路径相同、措辞不同的模糊候选才交给受限的**语义仲裁器**（用 `--consensus-model` 启用）。仲裁器只能聚类，不得发明 finding、丢弃 finding、补充证据或充当额外审查者，且没有写工具。低置信匹配保持为独立 advisory，避免靠"相似"制造虚假共识。
+
+### 成本与失败
+
+审查者运行数 = `--reviewers <n>` × `--max-rounds`（loop）；启用 `--consensus-model` 时每轮最多再跑一次仲裁。用 `--concurrency <n>` 限制并发（默认等于审查者数，不超过）。审查者运行时失败 → `blocked`；无法解析的脏输出或未决澄清 → `needs_human`；绝不悄悄 clean。面板审查 v1 不支持 `--keep-session`、`--continue`、`--name`（审查者用 `--no-session`）；宿主 Agent 仍是唯一可编辑者。
+
+### 机器输出
+
+一次面板评估只输出**一条**聚合 `PI_REVIEW_META_JSON`，新增字段：`strategy: "panel"`、`configuredReviewers`、`successfulReviewers`、`consensusPolicy`、`consensusThreshold`、`panelHealth`、`confirmedClusters`、`advisories` 以及每个 `reviewers` 的结果。顶层 `findings` 只含确认簇；advisory 单独存放。旧字段保留，老消费者可安全忽略新字段。
+
+### Pi 实时进度与事件回放
+
+Pi 中执行 `/rv @target` 会调用原生 `pi_review` 工具。每位 reviewer 都有独立实时行，展示生命周期、当前工具、耗时和 token 用量；按 `Ctrl+O` 可展开查看有界活动记录、最终发现和溯源。
+
+渲染器可直接消费版本化事件流：
+
+```bash
+pi-review --panel code-experts --output-format events-jsonl -- @src
+```
+
+该模式只向 stdout 输出 `ReviewEvent v1` JSONL。每次运行拥有一个 `runId` 和单调递增的 `seq`，活动文本会脱敏和截断，结尾固定为一条携带 `PanelReviewMeta` 的 `panel.completed` 事件。`createPanelViewState()` 与 `reducePanelEvent()` 支持确定性的实时归约和回放。
+
+Panel reviewer 固定使用 `read,grep,find,ls` 白名单；shell 与可变更工具会在启动前被拒绝。`Ctrl+C` 会取消 reviewer 与 adjudicator 进程树，输出取消事件并生成一条 blocked 最终事件。
+
 ## Pi 包：`/rv` 命令
 
 安装 Pi 包后可在 Pi 里使用 `/rv`：
@@ -66,13 +131,23 @@ pi-review models
 
 跟进审查时，`--continue` 与首次 `/rv` 一样可**选填** `--mode`、`--model`（以及后续 CLI 支持的其它选项由 skill 直接调用 CLI 时传入）。
 
-`/rv` 会向主会话注入**英文任务说明**（**仅 Pi 宿主**：默认流式、**不要**自动加 `--no-stream` / `--progress-log`），由主 Agent 调用 `pi-review` CLI。普通 `/rv @path` 无需额外参数。需要整段缓冲时显式 `/rv --no-stream`。
+`/rv` 会向主会话注入**英文任务说明**。新的 Pi 审查会调用原生 `pi_review` 工具，由它以标准化事件模式启动打包的 `pi-review` CLI 并渲染实时 Panel。普通 `/rv @path` 无需额外参数；`--continue`、`--keep-session` 与显式 `--no-stream` 保持单审查 CLI 路径。
 
-**Claude Code / Codex 等 Agent 宿主**：Bash 工具会缓冲 stdout，不能指望“默认流式”在对话里逐字出现；**pi-review skill 默认建议** `--progress-log <path>` + 后台运行 + tail 日志。详见 `skills/pi-review/SKILL.md`、`skills/pi-review/references/codex-tools.md` 与英文 README。
+**Claude Code / Codex 等 Agent 宿主**：`pi-review` 默认把可读文本增量流到 stdout，把**语义化里程碑**写到 stderr（`pi-review: review started` / `pi-review: tool <name> started/finished` / `pi-review: review finished`）；token 用量默认就能拿到，无需 `--progress-log`。`--progress-log` 退化为可选的调试用全量事件日志。详见 `skills/pi-review/SKILL.md`、`skills/pi-review/references/codex-tools.md` 与英文 README。
 
 ## 输出格式
 
-审查结果包含 `## Verdict`、`## Summary`、`## Findings` 等章节，并以 **ASCII 页脚**（`── pi-review` 框线 + Verdict/Mode/Duration/Session）结尾；机器可读 JSON 在 **stderr** 一行 `PI_REVIEW_META_JSON:`（需写 stdout 时设 `PI_REVIEW_META_STDOUT=1`）。
+审查结果包含 `## Verdict`、`## Summary`、`## Findings` 等章节。每条 finding 使用 `F1 + Severity + Path + Actionable + Evidence + Impact + Recommendation` 结构。ASCII 页脚会显示 Verdict、`Status`、finding 数量、Mode、Duration/Session。
+
+机器可读 JSON 仍在 **stderr** 的单行 `PI_REVIEW_META_JSON:` 中，并以新增字段提供：
+
+- `status`: `clean | has_findings | needs_human | blocked`
+- `findings`: `{ id?, severity?, path?, summary, actionable }[]`
+- `actionableCount`: 可操作问题数量
+
+旧字段不删除；需改为写入 stdout 时设 `PI_REVIEW_META_STDOUT=1`。解析器优先识别上述 `### F1` 格式，也兼容旧的三级标题和顶层列表；缺少 `Actionable` 时，`request_changes` 下默认可操作，其它 verdict 默认不可操作。无法识别 verdict 时会回退到 `needs_human` 并附带 `parseError`，运行时失败始终保持 `blocked`。
+
+退出码：`0` clean、`1` 最终状态为 `has_findings` / loop 预算耗尽、`2` 参数错误、`3` needs human、`4` blocked / 运行时失败。
 
 ## 配置
 
@@ -88,4 +163,4 @@ pi-review models
 
 ## 许可
 
-[MIT](LICENSE) © ZephyrDeng
+[MIT](LICENSE) © ZephyrDeng

package/dist/args.d.ts

@@ -1,4 +1,12 @@
 import type { ParsedArgs } from "./types.js";
 export declare function usage(exitCode?: number): never;
+export declare const DEFAULT_MAX_ROUNDS = 3;
+export declare class ArgsParseError extends Error {
+    readonly exitCode: number;
+    constructor(message: string, exitCode?: number);
+}
+/** Pure parser for the review and loop command seam. */
+export declare function parseReviewCommand(input: string[]): ParsedArgs;
+export declare function isPanelActive(options: Pick<ParsedArgs, "reviewers" | "panel">): boolean;
 export declare function parseArgs(argv: string[]): ParsedArgs;
 //# sourceMappingURL=args.d.ts.map

package/dist/args.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../src/args.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAG7C,wBAAgB,KAAK,CAAC,QAAQ,SAAI,GAAG,KAAK,CAsCzC;AAUD,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CAkGpD"}
+{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../src/args.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAI7C,wBAAgB,KAAK,CAAC,QAAQ,SAAI,GAAG,KAAK,CA0DzC;AAED,eAAO,MAAM,kBAAkB,IAAI,CAAC;AAEpC,qBAAa,cAAe,SAAQ,KAAK;IACV,QAAQ,CAAC,QAAQ;gBAAlC,OAAO,EAAE,MAAM,EAAW,QAAQ,SAAI;CAInD;AAoBD,wDAAwD;AACxD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,UAAU,CAsH9D;AAsDD,wBAAgB,aAAa,CAAC,OAAO,EAAE,IAAI,CAAC,UAAU,EAAE,WAAW,GAAG,OAAO,CAAC,GAAG,OAAO,CAEvF;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CAyBpD"}

package/dist/args.js

@@ -1,8 +1,10 @@
+import { CONSENSUS_POLICIES, MAX_REVIEWERS, PANEL_READ_ONLY_TOOLS } from "./types.js";
 import { parseInstallCommand } from "./install-args.js";
 export function usage(exitCode = 0) {
     const out = `Usage:
   pi-review models [search]
-  pi-review [options] -- <@files|text...>
+  pi-review [review] [options] -- <@files|text...>
+  pi-review loop [options] -- <@files|text...>
   pi-review update                      Update to the latest version
   pi-review install [options]           Pi package + agent skills (one-shot)
   pi-review install-skill [options]     Install skill to AI agents only
@@ -19,18 +21,37 @@ Options:
   --tools <csv>                               Override allowed tools
   --no-stream                                 Buffer child output until exit (default: stream live)
   --progress-log <path>                       Stream child --mode json events to this file (cannot combine with --no-stream)
+  --max-rounds <n>                            Loop review budget (default: 3; loop only)
+  --reviewers <n>                             Panel: number of independent reviewers (2-8; activates panel mode)
+  --panel <name>                              Panel: named expert-panel preset (cannot combine with --reviewers)
+  --consensus <policy>                        Panel: any | quorum | majority | unanimous (default: quorum)
+  --min-agree <n>                             Panel: minimum reviewers for quorum (default: 2; quorum only)
+  --consensus-model <model>                   Panel: model for semantic consensus adjudication
+  --concurrency <n>                           Panel: bounded reviewer concurrency (default: reviewer count)
+  --output-format <events-jsonl>              Panel: emit normalized ReviewEvent v1 JSONL to stdout
   -h, --help                                  Show help
 
-Session (requires Pi session support):
+Session (single review only; rejected by loop and panel):
   --keep-session                              Persist the review session for follow-up
   --continue <sessionHandle>                  Continue an existing review session
   --name <name>                               Session name (with --keep-session)
 
+Exit codes:
+  0 clean | 1 findings remain | 2 usage | 3 needs human | 4 blocked/runtime failure
+
+Panel cost: reviewer runs = --reviewers <n> times --max-rounds (loop), plus one
+consensus-adjudication call per round when --consensus-model is set. Single-review
+commands (default, no --reviewers/--panel) keep the existing low-cost workflow.
+
 Examples:
   pi-review models
   pi-review -- @src/foo.ts
   pi-review --model openai/gpt-5.5 -- @src/foo.ts
   pi-review --mode challenge --keep-session -- @design.md
+  pi-review --reviewers 3 --consensus quorum --min-agree 2 -- @src
+  pi-review --panel code-experts --consensus majority -- @src
+  pi-review loop --reviewers 3 --consensus quorum --max-rounds 3 -- @src
+  pi-review loop --max-rounds 3 -- @src
   pi-review install
   pi-review install --agent claude-code codex -y
   pi-review install-skill
@@ -38,42 +59,50 @@ Examples:
     (exitCode === 0 ? process.stdout : process.stderr).write(out);
     process.exit(exitCode);
 }
+export const DEFAULT_MAX_ROUNDS = 3;
+export class ArgsParseError extends Error {
+    exitCode;
+    constructor(message, exitCode = 2) {
+        super(message);
+        this.exitCode = exitCode;
+        this.name = "ArgsParseError";
+    }
+}
 function requireValue(flag, argv) {
     if (argv.length === 0 || argv[0] === "--") {
-        process.stderr.write(`pi-review: ${flag} requires a value\n`);
-        process.exit(2);
+        throw new ArgsParseError(`${flag} requires a value`);
     }
     return argv.shift();
 }
-export function parseArgs(argv) {
-    if (argv.length === 0 || argv[0] === "-h" || argv[0] === "--help")
-        usage(0);
-    if (argv[0] === "models") {
-        return { command: "models", search: argv.slice(1), mode: "code", skills: [], payload: [], keepSession: false, stream: true };
+function parsePositiveInteger(flag, value) {
+    if (!/^[1-9]\d*$/.test(value)) {
+        throw new ArgsParseError(`${flag} must be a positive integer`);
     }
-    if (argv[0] === "install") {
-        return parseInstallCommand(argv.slice(1));
-    }
-    if (argv[0] === "install-skill") {
-        return { command: "install-skill", extraArgs: argv.slice(1), mode: "code", skills: [], payload: [], keepSession: false, stream: true };
-    }
-    if (argv[0] === "uninstall-skill") {
-        return { command: "uninstall-skill", extraArgs: argv.slice(1), mode: "code", skills: [], payload: [], keepSession: false, stream: true };
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed)) {
+        throw new ArgsParseError(`${flag} must be a safe positive integer`);
     }
-    if (argv[0] === "update") {
-        return { command: "update", mode: "code", skills: [], payload: [], keepSession: false, stream: true };
+    return parsed;
+}
+/** Pure parser for the review and loop command seam. */
+export function parseReviewCommand(input) {
+    const argv = [...input];
+    let command = "review";
+    if (argv[0] === "review" || argv[0] === "loop") {
+        command = argv.shift();
     }
     let mode = "code";
     if (argv[0] && !argv[0].startsWith("-")) {
         mode = argv.shift();
     }
     const options = {
-        command: "review",
+        command,
         mode,
         skills: [],
         payload: [],
         keepSession: false,
         stream: true,
+        ...(command === "loop" ? { maxRounds: DEFAULT_MAX_ROUNDS } : {}),
     };
     while (argv.length > 0) {
         const arg = argv.shift();
@@ -84,8 +113,7 @@ export function parseArgs(argv) {
         switch (arg) {
             case "-h":
             case "--help":
-                usage(0);
-                break;
+                throw new ArgsParseError("", 0);
             case "--mode":
                 options.mode = requireValue(arg, argv);
                 break;
@@ -119,10 +147,37 @@ export function parseArgs(argv) {
             case "--progress-log":
                 options.progressLog = requireValue(arg, argv);
                 break;
+            case "--max-rounds":
+                options.maxRounds = parsePositiveInteger(arg, requireValue(arg, argv));
+                break;
+            case "--reviewers":
+                options.reviewers = parsePositiveInteger(arg, requireValue(arg, argv));
+                break;
+            case "--panel":
+                options.panel = requireValue(arg, argv);
+                break;
+            case "--consensus":
+                options.consensus = requireValue(arg, argv);
+                break;
+            case "--min-agree":
+                options.minAgree = parsePositiveInteger(arg, requireValue(arg, argv));
+                break;
+            case "--consensus-model":
+                options.consensusModel = requireValue(arg, argv);
+                break;
+            case "--concurrency":
+                options.concurrency = parsePositiveInteger(arg, requireValue(arg, argv));
+                break;
+            case "--output-format": {
+                const format = requireValue(arg, argv);
+                if (format !== "events-jsonl")
+                    throw new ArgsParseError("--output-format must be events-jsonl");
+                options.outputFormat = format;
+                break;
+            }
             default:
                 if (arg.startsWith("--")) {
-                    process.stderr.write(`pi-review: unknown option: ${arg}\n`);
-                    process.exit(2);
+                    throw new ArgsParseError(`unknown option: ${arg}`);
                 }
                 options.payload.push(arg, ...argv);
                 argv.length = 0;
@@ -130,13 +185,97 @@ export function parseArgs(argv) {
         }
     }
     if (options.keepSession && options.continueHandle) {
-        process.stderr.write("pi-review: --keep-session and --continue cannot be used together\n");
-        process.exit(2);
+        throw new ArgsParseError("--keep-session and --continue cannot be used together");
     }
     if (options.progressLog && !options.stream) {
-        process.stderr.write("pi-review: --progress-log cannot be used with --no-stream\n");
-        process.exit(2);
+        throw new ArgsParseError("--progress-log cannot be used with --no-stream");
+    }
+    if (command !== "loop" && options.maxRounds !== undefined) {
+        throw new ArgsParseError("--max-rounds can only be used with loop");
     }
+    if (command === "loop" && (options.keepSession || options.continueHandle || options.name)) {
+        throw new ArgsParseError("loop cannot be used with --keep-session, --continue, or --name");
+    }
+    validatePanelOptions(options);
     return options;
 }
+function validatePanelOptions(options) {
+    const hasReviewers = options.reviewers !== undefined;
+    const reviewerCount = options.reviewers ?? 1;
+    const panelActive = reviewerCount > 1 || options.panel !== undefined;
+    const anyPanelOption = options.consensus !== undefined ||
+        options.minAgree !== undefined ||
+        options.consensusModel !== undefined ||
+        options.concurrency !== undefined;
+    if (hasReviewers && options.reviewers > MAX_REVIEWERS) {
+        throw new ArgsParseError(`--reviewers must be between 1 and ${MAX_REVIEWERS}`);
+    }
+    if (hasReviewers && options.panel) {
+        throw new ArgsParseError("--reviewers cannot be used with --panel");
+    }
+    if (!panelActive && anyPanelOption) {
+        throw new ArgsParseError("panel options require --reviewers > 1 or --panel");
+    }
+    if (!panelActive && options.outputFormat) {
+        throw new ArgsParseError("--output-format events-jsonl requires an active panel");
+    }
+    if (options.command === "loop" && options.outputFormat) {
+        throw new ArgsParseError("loop cannot be used with --output-format events-jsonl");
+    }
+    if (panelActive && (options.keepSession || options.continueHandle || options.name)) {
+        throw new ArgsParseError("panel cannot be used with --keep-session, --continue, or --name");
+    }
+    if (panelActive && options.tools) {
+        const disallowed = options.tools.split(",").map((tool) => tool.trim()).filter((tool) => tool && !PANEL_READ_ONLY_TOOLS.includes(tool));
+        if (disallowed.length > 0) {
+            throw new ArgsParseError(`panel reviewers only allow ${PANEL_READ_ONLY_TOOLS.join(",")}; rejected: ${disallowed.join(",")}`);
+        }
+    }
+    if (options.consensus !== undefined && !CONSENSUS_POLICIES.includes(options.consensus)) {
+        throw new ArgsParseError(`unknown consensus policy: ${options.consensus}. Available: ${CONSENSUS_POLICIES.join(", ")}`);
+    }
+    if (options.minAgree !== undefined) {
+        if (options.consensus !== undefined && options.consensus !== "quorum") {
+            throw new ArgsParseError("--min-agree is only meaningful with --consensus quorum");
+        }
+        if (hasReviewers && !options.panel && options.minAgree > options.reviewers) {
+            throw new ArgsParseError(`--min-agree ${options.minAgree} cannot exceed reviewer count ${options.reviewers}`);
+        }
+    }
+    if (options.concurrency !== undefined && hasReviewers && !options.panel && options.concurrency > options.reviewers) {
+        throw new ArgsParseError(`--concurrency ${options.concurrency} cannot exceed reviewer count ${options.reviewers}`);
+    }
+}
+export function isPanelActive(options) {
+    return (options.reviewers !== undefined && options.reviewers > 1) || options.panel !== undefined;
+}
+export function parseArgs(argv) {
+    if (argv.length === 0 || argv[0] === "-h" || argv[0] === "--help")
+        usage(0);
+    if (argv[0] === "models") {
+        return { command: "models", search: argv.slice(1), mode: "code", skills: [], payload: [], keepSession: false, stream: true };
+    }
+    if (argv[0] === "install") {
+        return parseInstallCommand(argv.slice(1));
+    }
+    if (argv[0] === "install-skill") {
+        return { command: "install-skill", extraArgs: argv.slice(1), mode: "code", skills: [], payload: [], keepSession: false, stream: true };
+    }
+    if (argv[0] === "uninstall-skill") {
+        return { command: "uninstall-skill", extraArgs: argv.slice(1), mode: "code", skills: [], payload: [], keepSession: false, stream: true };
+    }
+    if (argv[0] === "update") {
+        return { command: "update", mode: "code", skills: [], payload: [], keepSession: false, stream: true };
+    }
+    try {
+        return parseReviewCommand(argv);
+    }
+    catch (error) {
+        if (!(error instanceof ArgsParseError))
+            throw error;
+        if (error.message)
+            process.stderr.write(`pi-review: ${error.message}\n`);
+        usage(error.exitCode);
+    }
+}
 //# sourceMappingURL=args.js.map