@zephyrdeng/pi-review 0.16.0 → 0.17.0

package/README.md

@@ -1,353 +1,60 @@
+<div align="center">
+
 # pi-review
 
+**Isolated, multi-reviewer AI code review — as a CLI, a CI gate, and an agent skill.**
+
 [![npm version](https://img.shields.io/npm/v/@zephyrdeng/pi-review.svg)](https://www.npmjs.com/package/@zephyrdeng/pi-review)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![npm downloads](https://img.shields.io/npm/dm/@zephyrdeng/pi-review.svg)](https://www.npmjs.com/package/@zephyrdeng/pi-review)
+[![GitHub stars](https://img.shields.io/github/stars/ZephyrDeng/pi-review?style=flat&logo=github)](https://github.com/ZephyrDeng/pi-review/stargazers)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D20-green.svg)](https://nodejs.org)
 
-**Isolated AI-powered code and plan reviews from the command line.**
-
-`pi-review` delegates review work to a fresh, isolated [Pi](https://github.com/anthropics/pi) session and returns a structured review conclusion. The child session is review-only — it reads code, analyzes it, and reports findings without making any changes.
-
-Works as a standalone CLI, a Pi package (extension + skill), or integrated into CI pipelines and editor workflows.
-
-## Prerequisites
-
-- [Pi CLI](https://pi.dev) installed and configured with at least one model provider
-
-## Run reviews on OrcaRouter
-
-`pi-review` is model-agnostic — it runs on any model provider configured in your
-[Pi](https://pi.dev) installation. To use [OrcaRouter](https://www.orcarouter.ai) as
-the provider behind your reviews:
-
-1. **Get a key** — no account yet? **Sign up with our referral link** <https://www.orcarouter.ai/ref/ref_07ca74b3e41670e5ff36> (also available from the badge below). Already have a key? Skip ahead.
-
-   ```bash
-   export ORCA_KEY="sk-orca-..."
-   ```
-
-2. **Register the provider** — merge [`resources/providers/orcarouter.json`](./resources/providers/orcarouter.json) into `~/.pi/agent/models.json` (OpenAI-compatible). If that file already exists, **merge, don't copy** — `cp` would overwrite every other provider you configured:
-
-   ```bash
-   # fresh machine (no models.json yet):
-   cp resources/providers/orcarouter.json ~/.pi/agent/models.json
-   # existing models.json — merge instead (or edit by hand):
-   jq -s '.[0] * .[1]' ~/.pi/agent/models.json resources/providers/orcarouter.json > /tmp/models.json && mv /tmp/models.json ~/.pi/agent/models.json
-   ```
-
-```json
-{
-  "providers": {
-    "orcarouter": {
-      "baseUrl": "https://api.orcarouter.ai/v1",
-      "api": "openai-completions",
-      "apiKey": "$ORCA_KEY",
-      "models": [
-        {
-          "id": "orcarouter/auto",
-          "name": "OrcaRouter Auto",
-          "reasoning": false,
-          "input": ["text"],
-          "contextWindow": 200000,
-          "maxTokens": 8192
-        }
-      ]
-    }
-  }
-}
-```
-
-3. **Pick the model** when you run a review:
-
-```bash
-pi-review --model orcarouter/orcarouter/auto -- @src/foo.ts
-```
-
-[![Powered by OrcaRouter](https://img.shields.io/badge/Powered_by-OrcaRouter-2563eb)](https://www.orcarouter.ai/ref/ref_07ca74b3e41670e5ff36)
-
-## Features
+[Quick start](#quick-start) · [Features](#why-pi-review) · [Screening workflow](docs/guide/screening.md) · [Panel review](docs/guide/panel-review.md) · [CLI reference](docs/guide/cli-reference.md) · [中文说明](README.zh-CN.md)
 
-- **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** — explicit `status`, structured findings (with optional per-finding `details`/`recommendation`/`location`), and a human-readable ASCII footer; one versioned, 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, compact JSON event log so agent hosts that buffer tool stdout (Claude Code, Codex, ...) can still show real-time progress (`--progress-log-raw` keeps the verbatim stream)
-- **Session continuity** — keep sessions alive for follow-up questions with `--keep-session`
-- **Customizable presets** — extend or override review modes via JSON configuration
-- **Pi package integration** — `/rv` slash command and agent skill included
+</div>
 
-## Language policy
+---
 
-- **Source code** (CLI, extensions, presets, prompts, TUI strings emitted from code): **English only**.
-- **Documentation** may be bilingual. See [README.zh-CN.md](./README.zh-CN.md) for 中文说明.
-- **Git commits**: [Husky](https://typicode.github.io/husky/) runs `ai-commit` on `prepare-commit-msg` / `commit-msg` / `pre-commit` (see [`.husky/`](./.husky/)). Config: [`.ai-commit.yaml`](./.ai-commit.yaml) (English, `ai_footer: off`, **ai-commit v0.1.45+** on PATH). Or run `ai-commit commit` / `ai-commit generate` directly after `git add`.
-
-## Installation
-
-Dev dependencies use the [public npm registry](https://registry.npmjs.org/) (see [`.npmrc`](./.npmrc)); run `npm install` in the repo root for Husky hooks.
-
-### CLI (recommended)
+`pi-review` hands review work to a fresh, **read-only** [Pi](https://pi.dev) session and returns a structured verdict: findings with severity, evidence, location and a stable exit code. Run one reviewer, or a **panel of independent reviewers** that must agree before a finding blocks the gate. Your agent (Claude Code, Codex, Cursor, Pi) stays the only editor.
 
 ```bash
 npm install -g @zephyrdeng/pi-review
+pi-review -- @src/foo.ts                                      # one reviewer
+pi-review --panel code-experts --consensus majority -- @src   # three lenses, one gate
 ```
 
-### One-shot (Pi + other agents)
-
-```bash
-npx @zephyrdeng/pi-review install
-```
-
-Runs `pi install npm:@zephyrdeng/pi-review` when the Pi CLI is on PATH, then installs the agent skill for Claude Code, Codex, Cursor, and agy / Antigravity (via the [skills CLI](https://www.npmjs.com/package/skills), non-interactive `-y`). Forward extra flags to the skill step, e.g. `npx @zephyrdeng/pi-review install --agent claude-code codex agy -y` or `npx @zephyrdeng/pi-review install --agents-only --all`.
-
-Use `--pi-only` or `--agents-only` to run one side. For Pi-only use, **do not** also run `install-skill` — the npm Pi package already exposes the skill via `pi.skills`.
-
-### Pi package only
-
-```bash
-pi install npm:@zephyrdeng/pi-review
-```
-
-### Agent skill only (Claude Code, Codex, Cursor, agy, ...)
-
-```bash
-npx @zephyrdeng/pi-review install-skill
-```
-
-This uses the [skills CLI](https://www.npmjs.com/package/skills) when available — it will prompt you to choose which agents to install to. Falls back to a direct copy into Claude Code (`~/.claude/skills`) and agy / Antigravity (`~/.gemini/config/skills`, discovered by AGY / AGY CLI / AGY IDE) if `skills` is not found.
-
-You can also specify agents directly. `agy` is accepted as a shorthand for the skills CLI ids `antigravity` + `antigravity-cli`:
-
-```bash
-pi-review install-skill --agent claude-code codex cursor agy
-# or only Antigravity:
-pi-review install-skill --agent agy
-```
-
-To remove:
-
-```bash
-pi-review uninstall-skill
-```
-
-### Update package + skill
-
-```bash
-pi-review update
-```
-
-Updates the global npm package when a newer version is available, then refreshes the installed agent skill content (via `skills update pi-review`, with a reinstall / Claude + agy direct-copy fallback).
-
-### From source
-
-```bash
-git clone https://github.com/ZephyrDeng/pi-review.git
-cd pi-review
-npm install && npm run build
-npm link
-```
-
-## Quick Start
-
-```bash
-# Review a file
-pi-review -- @src/foo.ts
-
-# Review with a specific model
-pi-review --model openai/gpt-5.5 -- @src/foo.ts
-
-# Multi-lens plan review
-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
-```
-
-From an agent host (Claude Code, Codex, Cursor, or **agy / Antigravity**), install the skill once, then ask the host to run a review — e.g. `/pi-review -- @src/foo.ts` or natural language that triggers the skill:
-
-```bash
-npx @zephyrdeng/pi-review install-skill --agent agy
-```
-
-## Review Modes
-
-| Mode | Description |
-|------|-------------|
-| `code` (default) | Code, diff, MR, file, and repository review. Focuses on correctness, regressions, security, concurrency, API contracts, edge cases, and missing tests. |
-| `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 --until clean --max-rounds 10 -- @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.
-
-Each round's `PI_REVIEW_META_JSON` line is the same enriched schema documented under [Machine finding schema](#machine-finding-schema) — `metaVersion`, per-finding `details`/`recommendation`/`location`, and (for panel rounds) `sourceFindings`. A consumer that wants enriched findings for a given round reads that round's stderr line directly, in emission order; no Markdown scraping and no change to `LoopRoundSummary` are needed.
-
-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. For an explicit clean goal with a hard ceiling, use `--until clean` (default budget 10 when `--max-rounds` is omitted; never unlimited). Clean means no gate-blocking findings (single: no actionable findings; panel: no confirmed actionable clusters; advisories may remain). `loop` accepts normal review target/model/progress options but rejects `--keep-session`, `--continue`, and `--name` in v1.
-
-**Cross-round comparison.** From round 2 onward each round is diffed against the previous round's actionable findings (`vs prev: =persisting · +new · -resolved` in the loop summary). Matching is deterministic first; with the Jev enhancement enabled, wording-drift pairs are adjudicated by Jev just like panel consensus. The comparison is advisory bookkeeping, never gate input, and a matcher failure degrades silently to no comparison. Under `--until clean`, when two consecutive rounds produce an identical actionable set (all persisting, nothing added or resolved), the loop stops early with `Stop: non_converging` — the tree does not change between rounds, so further rounds are dice rolls and the host should fix and re-invoke.
-
-## 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.
-
-**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).
-
-**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:
-
-```bash
-pi-review classify --baseline "fix the login crash; UI polish is out of scope" --meta /tmp/last-review-meta.txt
-# or pipe the review output directly:
-pi-review -- @src 2>&1 | pi-review classify --baseline "..."
-```
-
-Each actionable finding gets one Choice question (`in_scope_blocker` | `follow_up` | `stop_and_escalate`), all fanned out in a single call. Output is an ASCII summary plus a `PI_REVIEW_CLASSIFY_JSON` machine line on stderr; findings below confidence 0.5 are flagged as low-confidence. Classify is advisory and host-invoked — it never edits, never blocks a gate by itself, and requires `TYPESAFE_API_KEY` (exit 4 without it).
-
-**Gate-grade screening (`pi-review screen`).** Screen pushes Jev furthest left in the pipeline: instead of generating findings with an LLM reviewer (30s+ per round) and adjudicating them afterwards, it asks Jev typed questions about deterministically sliced code hunks and assembles findings from a defect-pattern catalog — no LLM prose on the critical path at all. Measured end-to-end on the [screening fixture](docs/research/jev-screening-case.md): **~1.2s wall time** for a 106-line service (12 hunks, 108 questions, one call), vs 32–53s for a full review round on the same file.
-
-```bash
-pi-review screen src/order-service.ts     # or @file refs; exits 1 on findings, 0 when clean
-```
-
-The architecture, end to end:
-
-```
-files ─► 1. deterministic slice            (local, ms — declaration-boundary hunks)
-            │
-            ├─► 2. one Jev call            (~1s — per hunk: 1 catch-all Noul
-            │     "any blocking defect?"     + 1 Noul per catalog pattern;
-            │     fanned out in parallel, chunked past 480 questions)
-            │
-            └─► 3. template assembly       (local, ms — pattern hit ⇒ finding
-                  + gate                    from catalog severity/title/fix;
-                                            catch-all hit without a pattern ⇒
-                                            "unmatched signal" finding, still
-                                            blocks — never silently dropped)
-```
-
-Who produces each `ReviewFinding` field: `id`/`path`/`location` come from the slicer (deterministic), `severity`/`summary`/`recommendation` come from the matched catalog pattern's template, `actionable` is the thresholded probability — the LLM's prose role shrinks to off-catalog novel defects and cross-hunk reasoning, which the unmatched-signal finding hands back to a full `pi-review` run. The catalog (`SCREEN_PATTERNS` in `src/screen.ts`) is the coverage knob: eight patterns ship today (off-by-one loops, fire-and-forget async, SQL injection, slice off-by-one, float money, float equality, cache aliasing, missing validation); add entries as history shows repeated unmatched signals. Output is an ASCII summary plus a `PI_REVIEW_SCREEN_JSON` machine line on stderr (status, findings, per-hunk probabilities, usage); exit codes mirror review (0 clean, 1 has_findings, 4 blocked/no key). Screen is a fast gate and a triage layer, not a replacement for evidence-backed review — measurements and honest limits are in [docs/research/jev-screening-case.md](docs/research/jev-screening-case.md).
-
-### 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.
-
-When the panel finishes, the CLI appends a panel ASCII footer on **stdout** with gate status, health, consensus, confirmed/advisory counts, mixed model/thinking when reviewers differ, aggregate tokens/cost, adjudicator use, and a per-reviewer line:
-
-![CLI panel footer: NEEDS HUMAN gate with 2/3 successful reviewers, quorum consensus, confirmed findings, advisories, mixed models, and per-reviewer status](docs/assets/panel-cli-footer.jpg)
-
-### 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. The panel-level `model` is each reviewer's effective model (configured, else the provider-reported `responseModel`) when they all agree, and the literal sentinel `"mixed"` when reviewers ran on different models — machine consumers parsing `model` must expect that value; per-reviewer entries keep their own `model`/`responseModel`.
-
-Panel machine metadata additionally carries `sourceFindings`: every contributing reviewer's raw findings, each tagged with its globally unique `id` (e.g. `"r1#F1"`) and `reviewerId`. This resolves every id referenced by `confirmedClusters[].sourceFindingIds` and `advisories[].sourceFindingIds` to its full enriched finding — including `details`/`recommendation`/`location` when the reviewer's Markdown supplied them (see [Machine finding schema](#machine-finding-schema)). Cluster-level summaries stay as they are today: `summary`/`severity`/`path` only, no enrichment fields.
-
-### Live Pi progress and event replay
-
-In Pi, slash commands select strategy only:
-
-- `/rv <natural-language target>` → panel review via native `pi_review`
-- `/rv-loop <natural-language target>` → loop closeout via shell CLI
-- `/rv-models` → model catalog
-
-Targets stay natural language as given. Path mentions like `@src` remain text; the CLI keeps directories as tool path targets and only attaches real files. Remaining strategy matching lives in the skill/CLI. In Pi, the user-facing tool name is **Pi Review Panel** (the API identifier remains `pi_review`); each reviewer renders as an independent live row with explicit `queued/running/completed/failed/cancelled` state, active tool, elapsed time, and token usage. Expand the tool result with `Ctrl+O` for bounded activity, final findings/provenance, duration, token totals, and cost.
-
-![Pi Review Panel live progress: code-experts panel with correctness, security, and testing reviewers, each showing status, model, thinking level, tokens, and cost](docs/assets/panel-live-pi.jpg)
-
-Example: `pi-review --panel code-experts -- @src` (or `/rv` in Pi with the same panel strategy).
-
-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.
-
-### Live web dashboard
-
-`--ui web` starts an opt-in, loopback-only dashboard for hosts without a native Pi renderer (Claude Code, Codex, plain terminals):
-
-```bash
-pi-review --reviewers 3 --consensus quorum --ui web -- @src
-```
-
-![Web dashboard while reviewing: aggregate reviewer/elapsed/token/tool counters and per-reviewer cards with RUNNING status, model, thinking level, and live activity](docs/assets/panel-web-dashboard.jpg)
+<p align="center">
+  <img src="docs/assets/panel-live-pi.jpg" alt="Pi Review Panel: correctness, security and testing reviewers running live with model, tokens and cost" width="820">
+</p>
 
-The CLI prints `PI_REVIEW_UI_URL: http://127.0.0.1:<port>/run/<token>` to stderr and opens it in the default browser before reviewers start (`--no-ui-open` disables the auto-open). The dashboard shows live per-reviewer status, streaming activity, animated token/tool-call counters, and — once the run completes — the gate result, confirmed findings/advisories, and each reviewer's full report rendered from markdown. `--ui-url-file <path>` additionally writes the URL atomically for hosts that buffer stdout/stderr. The review process still exits with the normal panel exit code as soon as the run completes.
+## Why pi-review
 
-After completion the page shows a 60-second countdown, then closes itself and stops the dashboard server; any interaction (scroll, click, keypress, or the "Keep open" button) cancels the countdown, and closing the tab afterwards also stops the server. As a backstop, the server self-terminates after a bounded idle TTL (default 900s; override with `--ui-ttl <seconds>`) so a browser can reconnect after a refresh.
+| | |
+|---|---|
+| **Isolated, read-only reviewers** | Every review is a fresh child process with a hard `read,grep,find,ls` allowlist. It cannot edit, commit, or leak context from your main session. |
+| **Panel consensus, not one opinion** | 2–8 independent reviewers who never see each other. A finding blocks only when enough of them agree (`any` / `quorum` / `majority` / `unanimous`); singletons stay visible as advisories. |
+| **Mix models per reviewer** | `--reviewer-model r1=openai/gpt-5.6:high --reviewer-model r2=anthropic/claude-opus-4.8:xhigh` — cross-family panels catch what one vendor misses. |
+| **Machine-readable, host-agnostic** | One versioned `PI_REVIEW_META_JSON` line, exit codes `0/1/3/4`, and an `events-jsonl` stream. Drop into CI, hooks, or your own renderer. |
+| **Loop gate for agent closeout** | `pi-review loop --until clean` re-reviews after each fix round, diffs findings across rounds, and stops on convergence — never unbounded. |
+| **~1s screening** | `pi-review screen` skips LLM generation entirely: deterministic slicing + typed [Jev](https://typesafe.ai) judgments against a defect catalog. Measured **1.2s** vs 30–50s for a full round. The catalog grows from use — custom patterns + a signal log via `pi-review screen-memory`. |
+| **Live everywhere** | Native live rows in Pi, a loopback **web dashboard** for Claude Code / Codex, streamed milestones on stderr for plain terminals. |
+| **Three review modes** | `code` (correctness, security, tests), `plan` (six expert lenses), `challenge` (adversarial pressure test). Extend via JSON presets. |
 
-The dashboard binds only to `127.0.0.1`/`::1`, protects every run with a high-entropy capability URL, sends a restrictive CSP with no remote assets or CORS, and renders all reviewer/finding text through safe DOM writes (markdown is parsed by a built-in renderer; links are restricted to http/https, and nothing goes through innerHTML). It is view-only: cancellation stays with the invoking terminal/agent host (`Ctrl+C`). `--ui web` requires an active panel and cannot combine with `loop`.
+## See it work
 
-## Output Format
+<table>
+<tr>
+<td width="50%"><img src="docs/assets/panel-cli-footer.jpg" alt="CLI panel footer with gate status, consensus, confirmed findings, advisories and per-reviewer lines"></td>
+<td width="50%"><img src="docs/assets/panel-web-dashboard.jpg" alt="Web dashboard with live per-reviewer cards, token and tool counters"></td>
+</tr>
+<tr>
+<td align="center"><sub>Panel footer in any terminal — gate, consensus, cost, per-reviewer status</sub></td>
+<td align="center"><sub><code>--ui web</code> dashboard for hosts that buffer stdout</sub></td>
+</tr>
+</table>
 
-Every review produces Markdown with these sections:
-
-```
-## Verdict
-approve | request_changes | needs_clarification | blocked
-
-## Summary
-## Findings
-### F1: <summary>
-- Severity: critical | high | medium | low
-- Path: <path or none>
-- Lines: <line or line-range in Path, or none>
-- Side: base | working (optional; defaults to working)
-- Actionable: yes | no
-- Evidence: <concrete evidence>
-- Impact: <why it matters>
-- Recommendation: <specific next step>
-
-## Risks and Blind Spots
-## Open Questions
-```
-
-The CLI appends a readable ASCII footer on **stdout**:
+Every review ends with a structured report and a footer you can read at a glance:
 
 ```
 ── pi-review ────────────────────────────
@@ -356,185 +63,108 @@ The CLI appends a readable ASCII footer on **stdout**:
   Mode        code
   Findings    1 actionable / 1 total
   Model       provider/model
-  Thinking    xhigh
-  Tokens      in 17.6K · out 512 · cache 2.0K · reason 0 · total 18.2K
+  Tokens      in 17.6K · out 512 · cache 2.0K · total 18.2K
   Cost        $0.05
   Duration    42.3s
 ──────────────────────────────────────────
 ```
 
-`Thinking` shows the requested thinking level when set; `Tokens` shows the child session's token usage (`in`/`out`/`cache`/`reason` plus total) parsed from the `--mode json` event stream. `Cost` shows the provider-reported total, or `n/a` when the provider does not report one. Both are collected during normal streaming; `--progress-log` is not required.
-
-For scripts, parse **`PI_REVIEW_META_JSON:`** from **stderr**. Existing keys remain, with additive fields:
-
-```json
-{"metaVersion":1,"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 when reported by the child; `usage` includes token totals and may include `costTotal`. 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.
-
-### Machine finding schema
-
-`PI_REVIEW_META_JSON` carries a top-level `metaVersion` schema discriminator (currently `1`). JSON emitted by pi-review versions before this field existed has no `metaVersion` key at all — treat that absence as the original, pre-enrichment contract. Every field below is additive under `metaVersion: 1`; a future breaking change to this shape would bump it.
+Scripts read `PI_REVIEW_META_JSON:` from stderr — findings carry `severity`, `path`, `location`, `details`, `recommendation`. No Markdown scraping. → [Output & integration](docs/guide/output-and-integration.md)
 
-Each finding gains three optional fields alongside the existing `{ id?, severity?, path?, summary, actionable }` shape:
+## Quick start
 
-| Field | Type | Present when |
-|-------|------|--------------|
-| `details` | `string` | At least one of the reviewer's Evidence/Impact fields parsed. Joins them as `"Evidence: <...>"` and/or `"Impact: <...>"` paragraphs separated by a blank line (`\n\n`); a finding with only one of the two carries only that labeled paragraph. Never fabricated. |
-| `recommendation` | `string` | The reviewer's Recommendation field parsed, verbatim and kept separate from `details`. |
-| `location` | `{ startLine: number; endLine?: number; side?: "base" \| "working" }` | The reviewer's `Lines` field held one positive integer (`42`) or a non-inverted positive range (`42-58`). Non-numeric, zero/negative, or inverted (`endLine < startLine`) values are dropped rather than guessed, so `location` is simply absent. `side` is only ever `"base"` (before the change); every other case — absent, unrecognized, or explicitly `"working"` — omits `side`, which means `"working"` (after the change). |
+**Prerequisite:** [Pi CLI](https://pi.dev) with at least one model provider configured.
 
-Example with all three populated:
+```bash
+# CLI
+npm install -g @zephyrdeng/pi-review
 
-```json
-{"metaVersion":1,"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,"details":"Evidence: runReview forwards the child exit code.\n\nImpact: A review gate passes with actionable findings.","recommendation":"Map structured status to a stable exit code.","location":{"startLine":42,"endLine":58}}],"actionableCount":1,"durationMs":42300,"model":"provider/model"}
+# …or one shot: Pi package + skill for Claude Code / Codex / Cursor / Antigravity
+npx @zephyrdeng/pi-review install
 ```
 
-All three finding-level fields and `metaVersion` are additive: existing consumers reading only `{ id?, severity?, path?, summary, actionable }` are unaffected, and a file-level finding with no reliable line data simply omits `location` while `details`/`recommendation` still populate when Evidence/Impact/Recommendation parsed. This machine schema — including the panel `sourceFindings` fields documented under [Panel Review § Machine output](#machine-output) and the per-round stream documented under [Loop Review](#loop-review) — is a **supported integration surface**: renderers should read `PI_REVIEW_META_JSON` directly and never need to scrape review Markdown for Evidence/Impact/Recommendation/line data.
+```bash
+pi-review -- @src/foo.ts                                   # single review
+pi-review --mode plan -- @docs/architecture.md             # multi-lens plan review
+pi-review --reviewers 3 --consensus quorum -- @src         # panel
+pi-review loop --until clean --max-rounds 5 -- @src        # bounded fix/re-review gate
+pi-review screen src/order-service.ts                      # ~1s catalog screening
+pi-review models                                           # what can I run on?
+```
 
-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`.
+In Pi: `/rv @src`, `/rv-loop fix until clean @src`, `/rv-models`. In other agent hosts, install the skill once and ask for a review in plain language.
 
-### Exit codes
+→ [Installation options](docs/guide/installation.md) · [Pi `/rv` commands](docs/guide/pi-package.md)
 
-| 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 |
+## How the panel decides
 
-## Session Management
+```
+reviewers (isolated, read-only) ──► findings ──► deterministic match (path + summary)
+                                                      │
+                                       ambiguous pairs ┴─► Jev typed adjudication (~100 ms)
+                                                             │  borderline 0.3–0.7 → one Pi re-judge
+                                                             ▼
+                                           consensus threshold ──► confirmed (blocks) / advisory
+```
 
-```bash
-# Keep a review session for follow-up
-pi-review --mode challenge --keep-session -- @docs/design.md
+Reviewer failure → `blocked`; unparseable output → `needs_human`; never a silent pass. Adjudication cannot invent, drop, or rewrite findings — it only clusters. → [Panel review in depth](docs/guide/panel-review.md) · [Loop review](docs/guide/loop-review.md)
 
-# Continue a previous session (same optional flags as an initial run)
-pi-review --continue <sessionHandle> --mode challenge --model provider/model -- "expand finding 2"
-```
+## Partners
 
-## Live Progress and Token Usage
+<table>
+<tr>
+<td width="50%" valign="top">
 
-`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**.
+### [OrcaRouter](https://www.orcarouter.ai/ref/ref_07ca74b3e41670e5ff36)
 
-Agent hosts like Claude Code, Cursor, Codex, and agy 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.
+One key, every frontier model. `pi-review` ships a ready-made provider file — drop it into Pi and run cross-family panels without juggling vendor accounts.
 
-`--progress-log <path>` is now an **optional** convenience for fine-grained debugging: it tees the `--mode json` event stream to a file. By default the tee is **slimmed** — each `message_update` line reduces its cumulative message snapshots (`assistantMessageEvent.partial` and the duplicate top-level `message`) to their `usage` field. A verbatim tee repeats the entire message-so-far plus provider metadata on every delta, growing the file quadratically with message length (real reviews measured a ~1600x byte amplification). Deltas and message boundaries (`message_end`, `turn_end`, `agent_end`) keep the complete record, so the slimmed log still reconstructs the review and replays through pi-review's own event parser with no feature loss. Add `--progress-log-raw` when you need the verbatim stream. `--progress-log` 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).
+[![Powered by OrcaRouter](https://img.shields.io/badge/Powered_by-OrcaRouter-2563eb)](https://www.orcarouter.ai/ref/ref_07ca74b3e41670e5ff36)
 
-```bash
-# Optional: capture the event log for debugging (slimmed by default; add --progress-log-raw for verbatim)
-pi-review --progress-log /tmp/pi-review.jsonl -- @src/foo.ts &
-tail -f -n +1 /tmp/pi-review.jsonl | jq -c --unbuffered '
-  select(.type != "message_update" and .type != "tool_execution_update")
-'
-```
+→ [Setup guide](docs/guide/providers.md)
 
-The JSON event schema is pi CLI's own internal format, not a contract `pi-review` guarantees — it may change between pi versions. `pi-review` parses it defensively (unparseable lines are skipped, missing events degrade to a diagnostic `parseError`) and still prints the same clean Markdown + ASCII footer to stdout once the child exits.
+</td>
+<td width="50%" valign="top">
 
-## CLI Reference
+### [TypeSafe Jev](https://typesafe.ai)
 
-```
-pi-review [review] [options] -- <@files|text...>
-pi-review loop [options] -- <@files|text...>
-pi-review screen <@files|paths...>
-pi-review classify --baseline <text|@file> [--meta <path>]
-pi-review models [search]
-```
+A System One model that answers typed questions with probabilities in ~100 ms. Powers consensus adjudication, cross-round finding memory, scope `classify`, and the 1-second `screen` gate.
 
-| Option | Description |
-|--------|-------------|
-| `--mode <name>` | Review mode (default: `code`) |
-| `--model <provider/model[:thinking]>` | Model to use for the review |
-| `--provider <name>` | Model provider |
-| `--thinking <level>` | Thinking level: `off\|minimal\|low\|medium\|high\|xhigh` |
-| `--skill <path>` | Load an extra Pi skill (repeatable) |
-| `--tools <csv>` | Override allowed tools |
-| `--keep-session` | Persist session for follow-up |
-| `--continue <handle>` | Continue an existing session |
-| `--name <name>` | Session name (with `--keep-session`) |
-| `--no-stream` | Buffer child output until exit (default: stream live) |
-| `--progress-log <path>` | Stream compact child `--mode json` events to this file (cannot combine with `--no-stream`) |
-| `--progress-log-raw` | With `--progress-log`: tee the verbatim event stream (full message snapshots; much larger files) |
-| `--max-rounds <n>` | Positive loop hard budget (default: `3`; with `--until clean` default: `10`; `loop` only) |
-| `--until clean` | Loop goal: keep going until the clean gate (still hard-capped by `--max-rounds`; never unlimited) |
-| `--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
-
-Persistent settings live in the review config file `~/.pi/pi-review/config.json` (override its location with `PI_REVIEW_CONFIG`). The config is advisory and forward-compatible: unknown keys are ignored, `null` counts as unset, and any other problem (wrong-typed value, invalid JSON) only prints a warning and falls back — the config never blocks core functionality, so a config written by a newer pi-review cannot brick an older one. In Pi, `/rv-config` shows the effective configuration (values, sources, warnings, resolved paths). There is deliberately no `/rv-config set` command — the preferred editor is your agent via the pi-review agent skill, which knows the config schema, keeps unknown keys, never overwrites invalid JSON, and never writes secrets (API keys stay environment variables, e.g. `TYPESAFE_API_KEY`; the config file holds flags only).
-
-| Key | Type | Default | Description |
-|-----|------|---------|-------------|
-| `childExtensions` | boolean | `false` | Let review children load host Pi extensions so providers registered only through extensions are usable. Equivalent to per-run `PI_REVIEW_CHILD_EXTENSIONS=1`; `false` keeps children isolated with `--no-extensions` (issue #8). |
-| `jev` | boolean | auto | Route panel consensus adjudication to TypeSafe Jev instead of a Pi adjudicator child. Default: enabled when `TYPESAFE_API_KEY` is set, disabled otherwise. Per-run override: `PI_REVIEW_JEV=1` / `=0`. An explicit `--consensus-model` always keeps the Pi adjudicator. |
-
-Per-process overrides via environment variables (env wins over the config file):
-
-| Variable | Description |
-|----------|-------------|
-| `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 print `PI_REVIEW_META_JSON` on stdout instead of stderr |
-| `PI_REVIEW_JEV` | Per-run override for `jev`: `1`/`true`/`on` routes panel consensus adjudication to TypeSafe Jev, any other set value (e.g. `0`) keeps the Pi adjudicator. Connection: `TYPESAFE_API_KEY` (required), optional `TYPESAFE_BASE_URL` and `PI_REVIEW_JEV_MODEL` (default `jev-latest`) |
-| `PI_REVIEW_CHILD_EXTENSIONS` | Per-run override for `childExtensions`: `1`/`true`/`keep` enables host extensions for this process, any other set value (e.g. `0`) forces isolation; an empty value counts as unset. Persistent equivalent: `{ "childExtensions": true }` in the config file. With an explicit `--provider`, pi-review first probes the model catalog and blocks with a hint if the provider only exists via extensions |
-| `PI_REVIEW_CONFIG` | Path to the review config file (default: `~/.pi/pi-review/config.json`) |
-
-## Pi Package Usage
-
-After installing as a Pi package, use the `/rv` slash command:
+Set `TYPESAFE_API_KEY` and it switches on.
 
-```
-/rv @src/foo.ts
-/rv --mode challenge @docs/design.md
-```
+→ [Comparison report](docs/research/jev-comparison-report.html) · [Screening study](docs/research/jev-screening-case.md)
 
-Slash commands inject a task message for the parent agent. Strategy is selected by the command (`/rv`, `/rv-loop`, `/rv-models`); the remainder is the natural-language target. `/rv-config` is read-only: it shows the effective configuration (config file, env overrides, resolved paths). Use plain `/rv @src`, `/rv review the auth changes`, or `/rv-loop fix until clean @src` in Pi — no extra streaming flags needed for panel runs. `--continue`, `--keep-session`, loop, and explicit `--no-stream` retain the shell CLI path.
+</td>
+</tr>
+</table>
 
-```
-/rv models
-/rv @src/foo.ts
-/rv --mode plan @docs/architecture.md
-/rv --mode challenge --keep-session @docs/design.md
-```
+## Documentation
 
-Argument completions are context-aware. After the host session starts, `/rv` reads the live model registry and offers:
+| Guide | What's inside |
+|---|---|
+| [Installation](docs/guide/installation.md) | CLI, Pi package, agent skills (Claude Code / Codex / Cursor / agy), updates, from source |
+| [CLI reference](docs/guide/cli-reference.md) | Every flag, review modes, when to use which command |
+| [Fast screening](docs/guide/screening.md) | The `screen` workflow, gate outcomes, machine output, and CI placement |
+| [Panel review](docs/guide/panel-review.md) | Consensus policies, aggregation, Jev, `classify`, `screen`, live UI, web dashboard |
+| [Loop review](docs/guide/loop-review.md) | Bounded rounds, `--until clean`, cross-round comparison, convergence stop |
+| [Output & integration](docs/guide/output-and-integration.md) | Markdown shape, `PI_REVIEW_META_JSON` schema, exit codes, sessions, progress logs |
+| [Configuration](docs/guide/configuration.md) | Config file, environment variables, security model |
+| [Providers](docs/guide/providers.md) | OrcaRouter and other provider setup |
+| [Research](docs/research/) | Jev architecture, screening measurements, adjudication case studies |
 
-- **Model list** after `--model `: candidates come from the live Pi registry; order follows **`resources/rv-model-priorities.json`** (override with `PI_REVIEW_RV_PRIORITIES`). Presets match registry ids by substring and prefer newer version strings (e.g. kimi `2.7`, `claude-opus-4-8`). Profiles: **code / fast** (claude-sonnet-5, deepseek-v4-flash, glm-5.2, minimax-m3, grok-4.5, gpt-5.6-terra/luna), **frontend / vision** (claude → gpt → kimi-2.7 → minimax-m3), **plan / complex** (gpt-5.6-sol max, claude-opus-4.8 xhigh, claude-fable-5 max cautious, glm-5.2 / deepseek-v4-pro / grok-4.5 max).
-- **Thinking suffix** after `provider/model:` — only levels the chosen model actually supports.
-- **Semantic phrases** (e.g. `code review` / 代码审核, `查看模型列表`) in addition to flags; orchestration prompts follow **session locale** (zh/en) for summaries.
-- **Scene templates** at the top level (code / frontend / plan presets).
+## Contributing
 
-**Claude Code / Codex / Cursor / agy:** the bundled skill includes **[skills/pi-review/references/model-selection.md](skills/pi-review/references/model-selection.md)** — same presets as `/rv` for choosing `--model` after `pi-review models`.
+Issues and PRs welcome. Source is English-only; docs may be bilingual. Commits go through `ai-commit` via Husky (`npm install` sets up the hooks). See [installation → contributing](docs/guide/installation.md#contributing-language-policy).
 
-Completions are a hint layer only; execution remains skill-driven. When the model registry is unavailable (e.g. non-TUI mode), `/rv` falls back to the static hint list.
+## Star history
 
-## Security
+If `pi-review` caught a bug before your reviewer did, a ⭐ helps others find it.
 
-- Each review and every loop round runs in an isolated child Pi session
-- Default runs use `--no-session` — no child context is stored
-- Children run isolated with `--no-extensions` by default so host usage HUDs / reload bridges cannot crash a reviewer via stale extension context after dispose (see issue #8). Enable host extension loading persistently with `{ "childExtensions": true }` in `~/.pi/pi-review/config.json`, or per run with `PI_REVIEW_CHILD_EXTENSIONS=1` — only when a custom provider truly must register inside the child.
-- Before spawning, pi-review probes the Pi model catalog when an explicit provider is in effect (via `--provider` or the `provider/` prefix of `--model`): if the provider only exists with host extensions loaded, the run is blocked with an actionable hint (`verdictSource: "config_error"`, meta `extensionHint`; panel runs aggregate every affected provider into `extensionHints`) instead of failing with a confusing unknown-provider error — set `childExtensions: true` in the config file or re-run with `PI_REVIEW_CHILD_EXTENSIONS=1`. Catalog probes are cached only on success; a transient probe failure never blocks a review.
-- On reviewer runtime failure, the panel footer and `reviewers[].runtimeError` keep a child stderr/stack tail for diagnosis
-- `--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
+[![Star History Chart](https://api.star-history.com/svg?repos=ZephyrDeng/pi-review&type=Date)](https://star-history.com/#ZephyrDeng/pi-review&Date)
 
 ## Acknowledgments
 
-The system prompt structure draws inspiration from [Codex-5.5-codex-instruct-5.5](https://github.com/yynxxxxx/Codex-5.5-codex-instruct-5.5) by li lingbo, licensed under the [MIT License](https://github.com/yynxxxxx/Codex-5.5-codex-instruct-5.5/blob/main/LICENSE).
+System prompt structure inspired by [Codex-5.5-codex-instruct-5.5](https://github.com/yynxxxxx/Codex-5.5-codex-instruct-5.5) (MIT).
 
 ## License