@zephyrdeng/pi-review 0.7.1 → 0.8.1

package/skills/pi-review/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: pi-review
-description: Use pi-review to delegate isolated code, diff, repository, architecture, or plan reviews to fresh Pi sessions and return review conclusions. Also use for loop review, review-fix-re-review closeout, structured review gates, and review status/progress. Model selection presets for code, frontend, and plan review are in references/model-selection.md. On Claude Code or Codex, default to --progress-log with a background shell run and tail the log (chat tools buffer stdout).
+description: Use pi-review to delegate isolated code, diff, repository, architecture, or plan reviews to fresh Pi sessions and return review conclusions. Also use for loop review, review-fix-re-review closeout, panel review gates, and review status/progress questions.
 ---
 
 # Pi Review
 
-Use `pi-review` to run a fresh Pi review session and return only the review conclusion.
+Use `pi-review` to run a fresh Pi review session and return only the review conclusion. Every review run is read-only: the child session never edits, patches, or commits — the host agent owns all fixes.
 
-## CLI Resolution
+## CLI resolution
 
 Prefer the shell command when it exists:
 
@@ -15,61 +15,68 @@ Prefer the shell command when it exists:
 pi-review --help
 ```
 
-If `pi-review` is not on PATH but this skill came from the Pi package, use the package-local CLI relative to this skill directory:
+If `pi-review` is not on PATH but this skill came from the Pi package, use the package-local CLI relative to the actual directory that contains this `SKILL.md`:
 
 ```bash
 node ../../bin/pi-review.js --help
 ```
 
-When resolving this fallback, use the actual directory that contains this `SKILL.md`.
-
-## Codex / Claude Code
-
-- Map skill mentions of `Bash` to your host shell tool.
-- Read **[references/codex-tools.md](./references/codex-tools.md)** for `--progress-log` + background run + tail.
-- Read **[references/model-selection.md](./references/model-selection.md)** when choosing `--model` after `pi-review models` (code / frontend / plan presets).
-- Do not use a blocking foreground shell alone for live progress; follow **Default workflow by host** below.
-
 ## Default workflow by host
 
 | Host | How to run `pi-review` |
 |------|-------------------------|
-| **Pi** (`/rv`) | New reviews call the native `pi_review` tool, which launches the packaged CLI in event mode and renders live Panel state. Continuations, kept sessions, and explicit `--no-stream` retain the foreground CLI path. |
-| **Claude Code, Codex, Cursor**, and similar AI agents | **Default: `--progress-log <path>` + background run + tail** (see below). Do **not** rely on foreground Bash stdout for “streaming” — the tool buffers until exit. |
-| Scripts / CI | Foreground is fine; use `--no-stream` only when you must buffer until exit. |
+| **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** 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** — hand the user the printed dashboard URL so they watch live progress in a browser instead of the chat. **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. |
+| Scripts / CI | Foreground is fine; add `--no-stream` only when the caller must buffer until exit (cannot combine with `--progress-log`). |
+
+`--progress-log <path>` tees the raw `--mode json` event stream to a file for outside observation and debugging; it is never a prerequisite for metrics. Token usage accumulates by default, and `pi-review` writes milestone notices (`pi-review: review started`, `pi-review: tool <name> started/finished`, `pi-review: review finished`) to stderr.
+
+`--ui web` starts a loopback-only browser dashboard for panel review; `--ui-url-file <path>` writes its URL atomically so a buffered-output host can read it without parsing stderr. It never substitutes for panel semantics — findings, gate status, and exit code come from the same `PI_REVIEW_META_JSON` as always.
+
+## Run metrics
+
+Quote metrics from the run output; never estimate or invent them.
+
+- **ASCII footer** (the `── pi-review` / `── pi-review panel` block): Duration, Tokens as `in · out · cache · reason` plus total, and Cost — the provider-reported value, or `n/a` when the provider reports none. On Pi `/rv` the panel tool result is **plain text / ASCII only** (Pi does not render markdown in tool results) — same classic chrome as the CLI, no `###` headings or fenced code blocks.
+- **Pi Review Panel**: each reviewer row shows **role persona · lifecycle · model · thinking · elapsed · tokens**. Lifecycle is `queued` / `running` / `completed` / `failed` / `cancelled`. Expanded view adds bounded activity, plain-text findings, and the ASCII footer.
+- Machine output: parse `PI_REVIEW_META_JSON:` from **stderr** (or set `PI_REVIEW_META_STDOUT=1` to emit it on stdout). Show users the plain review text and ASCII footer, not raw JSON, unless they ask for machine output. Do **not** rewrap the tool result into markdown tables or `###` report sections.
 
-## Pi host (`/rv`)
+## Pi host (`/rv*`)
 
-- In **Pi interactive** sessions, ordinary `/rv @path` calls the native `pi_review` tool and needs no streaming flags. The tool owns normalized events, live rendering, and the packaged CLI process.
-- `--continue`, `--keep-session`, and explicit `--no-stream` use the shell CLI path because they retain single-review session semantics.
+Slash commands select **strategy only**. Everything after the command is a **natural-language target**.
 
-## Streaming vs agent hosts (Claude Code / Codex)
+| Command | Strategy |
+|---------|----------|
+| `/rv <natural-language target>` | Panel review via native **Pi Review Panel** (`pi_review` API tool); preset `code-experts` unless `--reviewers`/`--panel` say otherwise |
+| `/rv-loop <natural-language target>` | Loop closeout via shell `pi-review loop`; host fix point `--max-rounds 1` by default |
+| `/rv-models` | Model catalog only |
+| `/rv --continue <handle> [text]` | Continue a kept single-review session |
 
-- `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** (`pi-review: review started`, `pi-review: tool <name> started/finished`, `pi-review: review finished`) to **stderr**. Token usage (`input`/`output`/`cache`/`reasoning`) is accumulated by default — no `--progress-log` required to see it in the ASCII footer or `PI_REVIEW_META_JSON`.
-- `--progress-log <path>` is now an **optional** convenience: it tees the raw `--mode json` event stream to a file for external observation (tail, debugging). It no longer gates token visibility.
-- **Claude Code, Cursor, Codex** and similar hosts still buffer a Bash tool's stdout until the command exits. The semantic milestone notices on stderr + the final Markdown + ASCII footer on stdout give you progress and the result without needing to tail a file. If you still want the full event log for fine-grained debugging, add `--progress-log <path>` and tail it.
-- **Pi interactive** sessions stream text deltas live to the terminal by default — no `--no-stream` or `--progress-log` needed.
+- Pass the user target **as given**. Path mentions like `@src` or `@src/foo.ts` are fine as text. Do **not** expand directories into multi-file lists in the parent agent.
+- Remaining strategy matching lives here and in the CLI: mode defaults (`code` / `plan` / `challenge`), model choice from `pi-review models` + [references/model-selection.md](./references/model-selection.md), panel width, and path-vs-file handling (directories stay tool path targets; only real files are attached).
+- `/rv` needs no streaming flags; the tool owns normalized events, live rendering, and the packaged CLI process. `/rv --reviewers 1` is an explicit non-panel single review and stays on the shell CLI path — never substitute the default panel.
 
 ## Review status (no slash command)
 
-There is **no** `/status` slash in this skill. When the user asks for **review status**, **progress**, **is pi-review still running**, or **/status** in the sense of review progress, run read-only checks and summarize—do **not** start a new review.
+There is **no** `/status` slash in this skill. When the user asks for **review status**, **progress**, or **is pi-review still running**, run read-only checks and summarize — do **not** start a new review.
 
 1. **In-flight review (heuristic)** — list likely `pi-review` / child `pi -p` processes:
    ```bash
    pgrep -fl 'pi-review' 2>/dev/null || true
    pgrep -fl 'pi.*-p' 2>/dev/null | head -20 || true
    ```
-   If matches exist, say a review **may still be running** (heuristic; other `pi -p` jobs can match). If none, say **no obvious in-flight pi-review** from process list—not that the last review failed.
+   If matches exist, say a review **may still be running** (heuristic; other `pi -p` jobs can match). If none, say **no obvious in-flight pi-review** from the process list — not that the last review failed.
 
 2. **Persisted sessions** (only after `--keep-session` / `--continue`) — default dir `~/.pi/pi-review/sessions`, overridable with `PI_REVIEW_SESSION_DIR`:
    ```bash
    ls -lt "${PI_REVIEW_SESSION_DIR:-$HOME/.pi/pi-review/sessions}" 2>/dev/null | head -15 || true
    ```
-   Mention newest folders and that **Session** from the ASCII footer (or `sessionHandle` in `PI_REVIEW_META_JSON` on stderr) is used with `--continue`.
+   Mention newest folders and that **Session** from the ASCII footer (or `sessionHandle` in `PI_REVIEW_META_JSON`) is used with `--continue`.
 
-3. **Last conclusion** — if this conversation already has the ASCII `── pi-review` footer, quote verdict, duration, and session path instead of re-running review.
+3. **Last conclusion** — if this conversation already has the ASCII `── pi-review` footer, quote verdict, duration, and session path instead of re-running the review.
 
-4. **Live output** — remind that chat tools may not stream; prefer re-running with `--progress-log <path>` + a background/tail workflow for live progress, or use a **terminal** running `pi-review` (default streaming) as a fallback.
+4. **Live output** — for live progress, re-run with the host's default workflow: panel review gets `--ui web` (browser dashboard) on agent hosts, single review/`loop` gets background + `--progress-log` + tail; a terminal running `pi-review` is a fallback for either.
 
 Do not implement findings from a status check; status is informational only.
 
@@ -78,26 +85,36 @@ Do not implement findings from a status check; status is informational only.
 Use this protocol when the host is closing out implementation work and may edit between reviews. `pi-review` and every child session remain review-only; the host agent owns all fixes.
 
 1. **Freeze the scope baseline before the first review.** Record the originating task, accepted files/modules, required behavior, and proof commands. Do not silently expand this baseline because a reviewer noticed adjacent cleanup.
-2. **Run a bounded structured gate.** Prefer the productized command:
+2. **Confirm until-clean stop conditions with the user.** An until-clean run starts only after the user confirms two things: what **clean** must mean for this run, and the hard `--max-rounds` cap. Offer a suggested default they can accept or adjust — e.g. "clean = zero confirmed actionable findings (advisories allowed), hard cap 10 rounds". A user request that already pins both counts as confirmation; restate it in one line and proceed. Fixed-round gates (`--max-rounds N` without `--until`) need no confirmation.
+3. **Run a bounded structured gate.** Prefer the productized command:
    ```bash
    pi-review loop --max-rounds 1 [shared review options] -- <@files|text...>
+   # Or host-driven until-clean (still hard-capped; never unlimited):
+   pi-review loop --until clean --max-rounds 10 [shared review options] -- <@files|text...>
    ```
-   A one-round invocation gives the host a fix point between reviews. Increase `--max-rounds` only when repeated independent review of the unchanged tree is intentional; the CLI never waits for edits. Re-invocation after a host fix is a new process. On Claude Code / Codex, compose `loop` with the normal `--progress-log <path>` background + tail workflow. On Pi, retain default foreground streaming. `loop` rejects `--keep-session`, `--continue`, and `--name`.
-3. **Read the gate signals.** Parse `status`, `findings`, and `actionableCount` from each `PI_REVIEW_META_JSON` line and use the final loop summary. Expected statuses are `clean`, `has_findings`, `needs_human`, and `blocked`.
-4. **Apply the scope governor to every finding:**
+   Round budgets: CLI `loop` defaults to `--max-rounds 3` when the flag is omitted; `--until clean` without an explicit flag defaults to a hard cap of 10; `/rv-loop` defaults to `--max-rounds 1` as a host fix point. A one-round invocation gives the host a fix point between reviews. `--until clean` declares the success **goal** and never removes the hard ceiling. The CLI never waits for edits and never loops forever on an unchanged tree. Re-invocation after a host fix is a new process (or the next host cycle under until-clean). Run `loop` with the host's default workflow from the table above. `loop` rejects `--keep-session`, `--continue`, and `--name`.
+
+   **Clean goal definition:**
+   - Single review: `status=clean` means no actionable findings (notes/non-actionable may remain).
+   - Panel review: `status=clean` means zero **confirmed** actionable clusters. Advisories do **not** fail clean.
+   - `needs_human` / `blocked` never count as clean.
+   - Successful closeout requires exit code `0`.
+4. **Read the gate signals.** Parse `status`, `findings`, and `actionableCount` from each `PI_REVIEW_META_JSON` line and use the final loop summary. Expected statuses are `clean`, `has_findings`, `needs_human`, and `blocked`.
+5. **Apply the scope governor to every finding:**
    - **in-scope blocker** — accepted, actionable, and required by the frozen task; the host may fix it now.
    - **follow-up** — valid but outside the baseline or not required for safe closeout; record it without drive-by edits.
    - **stop-and-escalate** — ambiguous intent, architectural expansion, unsafe migration, blocked tooling, or anything requiring a human decision; stop rather than guess.
    - A rejected finding must be intentional and recorded with its rationale in the final report. Never silently ignore it.
    - Check sibling instances of the same bug class only inside the frozen task/PR scope. Do not turn the check into a repository-wide refactor.
-5. **Fix only in-scope blockers in the host.** Never ask the child review session to implement fixes. After each host patch, rerun the narrowest relevant proof (focused test, typecheck, lint, or reproduction) before re-reviewing.
-6. **Re-review until a stop condition:**
-   - `clean` → gate open; proceed to final proof and closeout.
+6. **Fix only in-scope blockers in the host.** Never ask the child review session to implement fixes. After each host patch, rerun the narrowest relevant proof (focused test, typecheck, lint, or reproduction) before re-reviewing.
+7. **Re-review until a stop condition:**
+   - `clean` → clean goal met; proceed to final proof and closeout.
    - `has_findings` → classify, fix accepted in-scope blockers, and re-invoke within the agreed host-cycle budget.
    - `needs_human` or `blocked` → stop early and escalate with the review history.
    - budget exhausted → report remaining findings and ask for a decision; do not loop indefinitely.
-7. **Detect non-convergence.** After two non-converging patch cycles (the same finding persists, findings oscillate, or scope grows), pause and reclassify all remaining findings before any further edit.
-8. **Gate completion claims.** Never claim done, ship, commit-ready, or clean without a fresh `clean` result, unless the user gives explicit human acceptance of named remaining findings. Report accepted fixes, rejected findings with rationale, follow-ups, stop reason, and proof evidence.
+   - With `--until clean`, the host owns the fix→re-review cycle until clean or hard budget. Advisories alone do not block clean; confirmed actionable findings do.
+8. **Detect non-convergence.** After two non-converging patch cycles (the same finding persists, findings oscillate, or scope grows), pause and reclassify all remaining findings before any further edit.
+9. **Gate completion claims.** Never claim done, ship, commit-ready, or clean without a fresh `clean` result, unless the user gives explicit human acceptance of named remaining findings. Report accepted fixes, rejected findings with rationale, follow-ups, stop reason, and proof evidence.
 
 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.
 
@@ -108,7 +125,9 @@ Panel review runs multiple **independent** reviewers in isolated child sessions
 ### When to use panel vs single review
 
 - **Single review (default):** keep for small, low-cost changes. Reviewer count defaults to one; the existing execution, output, status mapping, and exit policy stay unchanged.
-- **Panel review:** use when a change deserves independent scrutiny. Activate it with `--reviewers <n>` (2-8) or `--panel <name>`.
+- **Panel review:** use when a change deserves independent scrutiny. Activate it with `--reviewers <n>` (2-8) or `--panel <name>`; the two flags cannot combine. `--reviewers 1` stays a shell single review, and the `pi_review` API tool accepts only 2-8 reviewers.
+- **Generic `--reviewers N` roles** are distinct persona labels (rappers / AI KOLs / sports stars), **not** the literal string `Independent reviewer`. Named presets (`code-experts`) keep their fixed roles (correctness/security/testing). Do not invent or hardcode role names when calling `pi_review` — the CLI assigns them.
+- **Per-reviewer thinking**: pass `id=provider/model:thinking` via `--reviewer-model` / `reviewerModels` (e.g. `r1=zenmux/deepseek/deepseek-v4-flash:low`). The `:thinking` suffix is stripped into the thinking field and **must not** be overridden by a shared `--thinking` or preset default. Display should look like `model · low`, never `model:low · high`.
 
 ### Consensus
 
@@ -146,12 +165,16 @@ Panel review rejects `--keep-session`, `--continue`, and `--name` in v1 (reviewe
 ### Examples
 
 ```bash
-# Single panel review
+# Single panel review (roles auto-assigned as distinct personas)
 pi-review --reviewers 3 --consensus quorum --min-agree 2 -- @src
+# Per-reviewer model + thinking (suffix wins over shared --thinking)
+pi-review --reviewers 3 --reviewer-model r1=zenmux/deepseek/deepseek-v4-flash:low --reviewer-model r2=zenmux/minimax/minimax-m3:off -- @src
 # Expert preset
 pi-review --panel code-experts --consensus majority -- @src
 # Panel loop review (up to 6 reviewer runs + adjudication)
 pi-review loop --reviewers 3 --consensus quorum --max-rounds 2 -- @src
+# Claude Code / Codex / Cursor default: browser dashboard instead of a tailed log
+pi-review --reviewers 3 --ui web --ui-url-file /tmp/pi-review-ui-url.txt -- @src
 ```
 
 ## Steps
@@ -161,53 +184,54 @@ pi-review loop --reviewers 3 --consensus quorum --max-rounds 2 -- @src
    pi-review models [search]
    ```
    Rules:
-   - Run this before building the review command.
-   - If the user named a model, use that text as `[search]` and verify the **exact** listed `provider/model` from the output.
-   - If the user did not name a model, follow **[references/model-selection.md](./references/model-selection.md)**: infer profile (code / frontend / plan), match the priority list against catalog ids, then set `--model` with optional `:thinking` when supported.
+   - Run this before building the review command. **Never invent a `provider/model` id** — only ids from the catalog output.
+   - Follow **[references/model-selection.md](./references/model-selection.md)** for everything else: profile inference (code / frontend / plan), priority lists, user-named-model resolution, and thinking aliases (`max`/`最高` → `xhigh`, with fallback to the nearest supported level).
+   - Ambiguous match across model families: show the top candidates and ask; do not guess.
+   - No priority match: omit `--model` (Pi default) or pick a listed reasoning model with a large context window — say which and why.
    - On **Claude Code / Codex / Cursor**, state the chosen model in one line (match the user's language) before running the review command.
-   - If nothing in the priority list matches, omit `--model` (Pi default) or pick a listed reasoning model with large context—say which and why.
    Completion criterion: exact listed `provider/model[:thinking]` or an explicit default; never invented ids.
 
 2. Choose one mode:
    - default `code` — code, diff, MR, file, or repository review.
    - `--mode plan` — broad plan, architecture, product, or strategy review through multiple expert lenses.
    - `--mode challenge` — adversarial review of assumptions, boundaries, dependencies, and missing evidence.
-   Completion criterion: use default `code` unless the target is clearly a plan/design review; if two modes fit equally, ask the user to choose.
+   **Challenge mode: grill first.** Before running an adversarial review, grill the user with 2-3 pointed questions — for example: what outcome must this work achieve, which assumption hurts most if wrong, what evidence supports it? Weave the answers into the natural-language target so the reviewer attacks the real weak points.
+   Completion criterion: use default `code` unless the target is clearly a plan/design review; if two modes fit equally, ask the user to choose. For `challenge`, the grill answers are folded into the target before the command runs.
 
 3. Run an isolated review:
    ```bash
-   pi-review [--mode <name>] [--model <provider/model[:thinking]>] [--keep-session|--continue <handle>] [--progress-log <path>] -- <@files|text...>
+   pi-review [--mode <name>] [--model <provider/model[:thinking]>] [--keep-session|--continue <handle>] [--progress-log <path>] -- <natural-language target...>
    ```
    Rules:
-   - Use the model decision from step 1; do not invent model IDs.
+   - Use the model decision from step 1 and the execution path from **Default workflow by host**.
    - Omit `--mode` for normal code review; the command defaults to `code`.
-   - Use `--keep-session` only when the user wants follow-up questions on this review.
-   - Use `--continue <handle>` only with a **Session** path from a prior ASCII footer or `sessionHandle` in `PI_REVIEW_META_JSON`.
-   - Put file references as `@path` after `--`.
+   - Use `--keep-session` only when the user wants follow-up questions on this review; use `--continue <handle>` only with a **Session** path from a prior ASCII footer or `sessionHandle` in `PI_REVIEW_META_JSON`.
+   - Pass the review request as natural language after `--`. Path mentions (`@src`, `@src/foo.ts`) are allowed as text. Do **not** expand directories into multi-file attachment lists — the CLI keeps directory `@refs` as tool path targets and only attaches real files.
+   - On Pi `/rv`, call `pi_review` with that same natural-language target. On Pi `/rv-loop`, run shell `pi-review loop` with it and follow **Loop closeout protocol**.
    - Do not ask `pi-review` to edit, patch, commit, or implement.
-   - **Pi `/rv`:** default streaming; no `--progress-log` unless the user asked.
-   - **Claude Code / Codex / Cursor:** **include `--progress-log <path>` by default**; background the CLI and tail the log for user-visible progress. Foreground Bash alone does not stream in chat.
-   - Add `--no-stream` only when the caller must buffer until exit (cannot combine with `--progress-log`).
-   Completion criterion: the command includes the resolved model/default choice and a concrete review target.
+   Completion criterion: the command includes the resolved model/default choice and a concrete natural-language review target.
 
 4. Return the result:
-   - Show the Markdown review body and the **ASCII footer** (`── pi-review` block on stdout). Do not paste raw `PI_REVIEW_META_JSON` to the user unless they ask for machine output.
-   - Scripts: parse `PI_REVIEW_META_JSON:` from **stderr** (or set `PI_REVIEW_META_STDOUT=1` to emit JSON on stdout instead).
+   - Show the review conclusion and ASCII footer as plain text, with metrics quoted per **Run metrics**. Do not reformat into markdown tables or invented `###` sections — Pi does not render markdown for this output.
    - For an ordinary review-only request, do not apply findings automatically; implementation is a separate user decision. When the user already requested implementation closeout, follow **Loop closeout protocol** and let only the host fix accepted in-scope blockers.
    Completion criterion: the user sees the review conclusion and readable footer.
 
 ## Examples
 
 ```bash
+pi-review -- @src
 pi-review -- @src/foo.ts
-pi-review --model openai/gpt-5.5 -- @src/foo.ts
-pi-review --mode challenge --keep-session -- @docs/design.md
+pi-review --model openai/gpt-5.5 -- "review the auth changes under @src"
+pi-review --mode challenge --keep-session -- @docs/design.md    # after the 2-3 grill questions
 pi-review --mode challenge --continue <sessionHandle> -- "expand finding 2"
-pi-review loop --max-rounds 1 -- @src
+pi-review loop --max-rounds 1 -- @src                           # host fix point
+pi-review loop -- @src                                          # CLI default: --max-rounds 3
+pi-review loop --until clean --max-rounds 10 -- @src            # after the user confirms the stop conditions
 pi-review loop --max-rounds 1 --progress-log /tmp/pi-review-loop.jsonl -- @src
 ```
 
 ## Status examples (user phrasing)
 
 - "review status" / "is the review still running?" → run **Review status** checks above.
-- "show streaming in Claude Code" / "the wait is bad, is there a better way" → explain tool buffering; re-run with `--progress-log <path>` + a background/tail workflow (or Pi `/rv`) for live progress, offering a local terminal only as a fallback.
+- "show streaming in Claude Code" / "the wait is bad, is there a better way" → explain that the host buffers tool output; re-run with the default workflow for the run type — panel review gets `--ui web` (share the dashboard URL), single review/`loop` gets background + `--progress-log` + tail (or Pi `/rv`) — offering a local terminal only as a fallback.
+- "give me a dashboard" / "watch it in the browser" / "can I see this visually" → if the run is (or can be) a panel review, re-run with `--ui web --ui-url-file <path>` and share the printed URL; single review and `loop` do not support `--ui web` (offer to make it a panel review, or fall back to `--progress-log` + tail).

package/skills/pi-review/references/codex-tools.md

@@ -12,28 +12,35 @@ General Codex subagent and worktree mappings live in the **using-superpowers** s
 
 ## Long-running `pi-review` (default on Codex / Claude Code)
 
-Native shell tools usually **buffer stdout/stderr until the command exits**. A multi-minute `pi-review` run can look like a silent wait, then one large dump. `pi-review` mitigates this in two ways that need **no** `--progress-log`:
+Native shell tools on these hosts **buffer stdout/stderr until the command exits**. A multi-minute foreground `pi-review` run looks like a silent wait, then one large dump — never promise live foreground streaming. Which side channel to use depends on the run type: panel review gets the browser dashboard; single review and `loop` get the tailed progress log.
 
-1. **Semantic milestone notices on stderr** (`pi-review: review started`, `pi-review: tool <name> started/finished`, `pi-review: review finished`). Capture stderr separately or interleave it to show progress.
-2. **Token usage by default**: the ASCII footer and `PI_REVIEW_META_JSON` always include `thinking` + token usage (`input`/`output`/`cache`/`reasoning`) when the child session reports them — no `--progress-log` required.
+### Panel review: browser dashboard (default)
 
-When the **pi-review** skill applies on Codex, Claude Code, or Cursor:
+`--reviewers <n>` or `--panel <name>` activates panel review. On Codex, Claude Code, or Cursor, default to the dashboard instead of a tailed log:
 
-1. **Default:** run `pi-review ... -- <target>` (foreground or background). Stderr carries milestone notices; stdout carries the review Markdown + ASCII footer on exit.
-2. If you want the **full** `--mode json` event log for fine-grained debugging, add `--progress-log <path>` and tail it — but this is optional, not required for tokens or progress.
-3. After exit, show the Markdown review body and ASCII `── pi-review` footer (skill step 4).
+1. Run `pi-review --reviewers <n> --ui web --ui-url-file <path> -- <target>` (or `--panel <name>`) in the **background**.
+2. Read `<path>` shortly after launch — it is written atomically as soon as the dashboard server is ready, well before reviewers finish (poll a few times a second for a couple of seconds if the file is not there yet). Share that URL with the user immediately: *"Dashboard: `<url>` — open it to watch live per-reviewer progress. I'll report back when the review completes."*
+3. Wait for the background job. On exit, show the Markdown review body and ASCII `── pi-review` footer as usual (skill step 4) — the dashboard is a presentation layer only; findings, gate status, and exit code always come from `PI_REVIEW_META_JSON`.
+4. `--ui web` requires an active panel and rejects `loop` — for a single review or a panel `loop`, fall back to the progress-log workflow below.
 
-**Pi interactive (`/rv`)**: foreground `pi-review`, default streaming. Text deltas appear live on the terminal; no `--progress-log` unless the user asked.
+### Single review / `loop`: progress log + tail
+
+1. **Default:** run `pi-review ... --progress-log <path> -- <target>` in the **background** and **tail the log** for user-visible progress (see the tail example below). Stdout still delivers the review Markdown + ASCII footer on exit.
+2. `--progress-log` tees the raw `--mode json` event stream to the chosen file for observation and debugging. It is **not** a prerequisite for metrics: the ASCII footer and `PI_REVIEW_META_JSON` always include `thinking` + token usage (`input`/`output`/`cache`/`reasoning`) when the child session reports them.
+3. `pi-review` also writes semantic milestone notices to stderr (`pi-review: review started`, `pi-review: tool <name> started/finished`, `pi-review: review finished`); they surface once the host flushes output.
+4. After exit, show the Markdown review body and ASCII `── pi-review` footer (skill step 4).
+
+**Pi interactive (`/rv`)**: foreground `pi-review`, default streaming. Text deltas appear live on the terminal; no `--progress-log`/`--ui web` unless the user asked — Pi already renders panel progress natively.
 
 See the parent skill: sections *Default workflow by host* and *Streaming vs agent hosts (Claude Code / Codex)*.
 
 ### Loop closeout
 
-`loop` composes with the same default streaming + stderr-milestone workflow:
+`loop` composes with the same background + `--progress-log` + tail workflow:
 
 ```bash
-pi-review loop --max-rounds 1 -- @src
-# optional: --progress-log /tmp/pi-review-loop.jsonl for the full event log
+pi-review loop --max-rounds 1 --progress-log /tmp/pi-review-loop.jsonl -- @src
+# CLI default when --max-rounds is omitted: 3; --until clean defaults to a hard cap of 10
 ```
 
 A non-zero command exit is an expected gate result when findings remain. Wait for the process, read the final `PI_REVIEW_META_JSON` / loop summary, let the host fix only accepted in-scope findings, rerun focused proof, and invoke a new loop process. The child review session never edits. Reuse or truncate the progress log deliberately because every loop round appends events to the chosen path.

package/skills/pi-review/references/model-selection.md

@@ -8,65 +8,86 @@ Use this after `pi-review models` (or `pi-review models <search>`). **Never inve
 2. Infer **review profile** from the target (see table below).
 3. Walk the **priority list** for that profile; pick the **first** row whose `idContains` matches some listed model id (case-insensitive substring). If several ids match one row, prefer the **newest** id (higher version suffix, e.g. `2.7` over `2.5`, `4-8` over `4-6`).
 4. Set `--model <exact-listed-provider/model>` from the catalog. Add `:thinking` only if that model supports it in Pi and the preset suggests it (see thinking column).
+   - User “max / 最高档” maps to Pi thinking `xhigh` when supported; otherwise fall back to the highest available level.
+   - User “low / off / medium / high” maps to that exact level when supported — **do not upgrade** a user-specified low/off to high/xhigh.
 5. If **no** priority row matches anything in the catalog, either omit `--model` (Pi default) or pick the best **reasoning** model with a large context window from the list—state the choice in one line to the user.
 
 ## Profiles
 
 | Profile | When to use |
 |---------|-------------|
-| **code** | Default: diffs, MRs, backend/ general code paths (`@src/...`, `.ts`, `.go`, …). |
-| **frontend** | UI-heavy targets: `.vue`, `.svelte`, `.css`, `.scss`, `.html`, or user says frontend / UI / multimodal. |
-| **plan** | `--mode plan` or `--mode challenge`, or reviewing `.md` / design / architecture docs (not line-by-line code only). |
+| **code** | **Fast review**: diffs, MRs, routine backend/general code (`@src/...`, `.ts`, `.go`, …). |
+| **frontend** | **Vision / UI / multimodal**: `.vue`, `.svelte`, `.css`, `.scss`, `.html`, screenshots, or user says frontend / UI / vision / 多模态. |
+| **plan** | **Complex / 方案评审**: `--mode plan` or `--mode challenge`, architecture docs, hard design trade-offs (not line-by-line code only). |
 
 ## Priority lists (same as Pi `/rv` package preset)
 
 Configurable on disk for Pi: `resources/rv-model-priorities.json` or `PI_REVIEW_RV_PRIORITIES`. Agents should follow this table unless the user overrides.
 
-### Code review
+Thinking notes: Pi levels are `off|minimal|low|medium|high|xhigh`. Treat user **max / 最高档** as **`xhigh`**.
 
-| Order | Match model id containing | Suggested thinking |
-|-------|---------------------------|------------------|
-| 1 | `gpt-5.5` | `xhigh` |
-| 2 | `glm-5.2` | `high` |
+### Code — fast review
 
-### Frontend / multimodal review
+| Order | Match model id containing | Suggested thinking | Notes |
+|-------|---------------------------|--------------------|--------|
+| 1 | `claude-sonnet` (prefer `5`) | `xhigh` (or `high`) | Fast strong default |
+| 2 | `deepseek-v4-flash` | `xhigh` | |
+| 3 | `glm-5.2` | `xhigh` (or `high`) | |
+| 4 | `minimax-m3` | `xhigh` | |
+| 5 | `grok-4.5` | `xhigh` (or `high`) | |
+| 6 | `gpt-5.6-terra` | any / omit | Any supported tier |
+| 7 | `gpt-5.6-luna` | `xhigh` | max/`xhigh` preferred |
+
+### Frontend — vision / multimodal
 
 | Order | Match model id containing | Notes |
 |-------|---------------------------|--------|
-| 1 | `kimi` | Prefer id that also contains `2.7` when multiple Kimi ids exist |
-| 2 | `claude-sonnet` | Prefer id containing `5` when multiple |
-| 3 | `minimax-m3` | Multimodal-friendly |
+| 1 | `claude` | Claude family first for vision |
+| 2 | `gpt` | GPT family |
+| 3 | `kimi` (prefer `2.7`, e.g. kimi-2.7-code) | Vision-friendly Kimi |
+| 4 | `minimax-m3` | Multimodal-friendly |
 
-Use **code** mode (`pi-review` default) unless the user asked for plan/challenge.
+Use **code** mode unless the user asked for plan/challenge.
 
-### Plan / challenge review
+### Plan / challenge — complex & 方案评审
 
-| Order | Match model id containing |
-|-------|---------------------------|
-| 1 | `claude-opus-4-8` |
-| 2 | `claude-opus-4` (+ prefer `8` in id if several) |
-| 3 | `deepseek-v4-pro` |
-| 4 | `deepseek-v4` |
+| Order | Match model id containing | Suggested thinking | Notes |
+|-------|---------------------------|--------------------|--------|
+| 1 | `gpt-5.6-sol` | `xhigh` (max) | Preferred for hard cases |
+| 2 | `claude-opus-4-8` / `claude-opus-4` (prefer `8`) | `xhigh` | |
+| 3 | `claude-fable-5` | `xhigh` (max) | **Use cautiously** |
+| 4 | `glm-5.2` | `xhigh` (最高档) | |
+| 5 | `deepseek-v4-pro` | `xhigh` (最高档) | |
+| 6 | `grok-4.5` | `xhigh` (最高档) | |
 
 Use `--mode plan` or `--mode challenge` as appropriate.
 
 ## Examples (illustrative—always substitute exact catalog strings)
 
 ```bash
-# Code
-pi-review --model openai-codex/gpt-5.5:xhigh -- @src/auth.ts
+# Fast code review
+pi-review --model px:anthropic/claude-sonnet-4-5:xhigh -- @src/auth.ts
 
-# Frontend
-pi-review --model wafer.ai/Kimi-K2.6 -- @src/App.vue
+# Complex / plan
+pi-review --mode plan --model openai-codex/gpt-5.6-sol:xhigh -- @docs/architecture.md
 
-# Plan
-pi-review --mode plan --model px:anthropic/claude-opus-4-8 -- @docs/architecture.md
+# Vision / frontend
+pi-review --model wafer.ai/Kimi-K2.7-code -- @src/App.vue
 ```
 
 ## User-named model
 
-If the user specifies a model, run `pi-review models <fragment>` and use the **exact** listed id. Do not normalize or guess provider prefixes.
+If the user specifies a model, resolve against the catalog instead of inventing an id:
+
+1. Exact `provider/model` match wins.
+2. Bare id / family fragment (`gpt-5.6-sol`, `kimi`, `opus`) may uniquely match one listed id. Prefer the host session's primary provider when the same id exists on multiple providers.
+3. If several unrelated families match, show the top candidates and ask. Do not silently jump from `gpt` to `claude`.
+4. Thinking aliases are allowed: `max`/`最高`/`最高档` → `xhigh`, `高` → `high`, `中` → `medium`, `快`/`off` → `off`. If unsupported by the chosen model, fall back to the nearest supported level.
+5. Inline form `provider/model:thinking` is valid.
+6. **Panel per-reviewer overrides** use the same inline form: `--reviewer-model r1=provider/model:low` (or `reviewerModels: ["r1=..."]` on `pi_review`). The CLI splits the trailing thinking level into its own field so a shared `--thinking high` / preset cannot clobber a per-reviewer `:low`. Prefer this over putting thinking only on the shared flag when reviewers need different levels.
+
+On Pi `/rv*`, short model/thinking tokens are resolved against the live registry before the review starts. On other hosts, run `pi-review models <fragment>` and apply the same rules.
 
 ## Language
 
-Explain your model choice briefly in the **same language** as the user's request (Chinese ↔ English). The review body language is independent; this rule is only for the one-line rationale before/after invoking `pi-review`.
+Explain your model choice briefly in the **same language** as the user's request (Chinese ↔ English). The review body language is independent; this rule is only for the one-line rationale before/after invoking `pi-review`.

package/dist/extensions/review.d.ts

@@ -1,2 +0,0 @@
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-export default function piReviewExtension(pi: ExtensionAPI): void;

package/dist/extensions/review.js

@@ -1,22 +0,0 @@
-import { buildRvOrchestrationPrompt, parseRvArgs, RV_COMPLETIONS } from "./rv-prompts.js";
-export default function piReviewExtension(pi) {
-    pi.registerCommand("rv", {
-        description: "Delegate pi-review to the agent (English prompts). Usage: /rv [--mode plan|challenge] [--model id] [--keep-session] @file-or-text | models",
-        getArgumentCompletions: (prefix) => {
-            const filtered = RV_COMPLETIONS.filter((item) => item.value.startsWith(prefix));
-            return filtered.length
-                ? filtered.map(({ value, hint }) => ({ value, label: value, description: hint }))
-                : null;
-        },
-        handler: async (rawArgs, ctx) => {
-            const trimmed = rawArgs.trim();
-            const parsed = parseRvArgs(trimmed);
-            const prompt = buildRvOrchestrationPrompt(parsed);
-            if (!trimmed && !parsed.modelsOnly) {
-                ctx.ui.notify("/rv needs a target or `models`. Try: /rv @path or /rv models", "warning");
-                return;
-            }
-            pi.sendUserMessage(prompt);
-        },
-    });
-}

package/dist/extensions/rv-prompts.d.ts

@@ -1,19 +0,0 @@
-/**
- * English orchestration prompts for /rv — parent Pi agent runs pi-review per skill.
- * Child review sessions use presets in resources/review-presets.json (also English).
- */
-export type RvParsed = {
-    mode: "code" | "plan" | "challenge";
-    model?: string;
-    keepSession: boolean;
-    continueHandle?: string;
-    modelsOnly: boolean;
-    target: string;
-};
-export declare function parseRvArgs(raw: string): RvParsed;
-export declare function buildRvOrchestrationPrompt(parsed: RvParsed): string;
-/** Short labels for TUI completions (English). */
-export declare const RV_COMPLETIONS: {
-    value: string;
-    hint: string;
-}[];