@zephyrdeng/pi-review 0.6.2 → 0.7.0

package/dist/types.d.ts

@@ -1,7 +1,21 @@
 export declare const VERDICTS: readonly ["approve", "request_changes", "needs_clarification", "blocked"];
 export type Verdict = (typeof VERDICTS)[number];
+export declare const REVIEW_STATUSES: readonly ["clean", "has_findings", "needs_human", "blocked"];
+export type ReviewStatus = (typeof REVIEW_STATUSES)[number];
+export interface ReviewFinding {
+    id?: string;
+    severity?: string;
+    path?: string;
+    summary: string;
+    actionable: boolean;
+}
+export interface StructuredReviewResult extends VerdictInfo {
+    status: ReviewStatus;
+    findings: ReviewFinding[];
+    actionableCount: number;
+}
 export interface ParsedArgs {
-    command: "review" | "models" | "install" | "install-skill" | "uninstall-skill" | "update";
+    command: "review" | "loop" | "models" | "install" | "install-skill" | "uninstall-skill" | "update";
     /** For `install`: run `pi install npm:@zephyrdeng/pi-review` */
     installPi?: boolean;
     /** For `install`: run agent skill install (skills CLI / Claude fallback) */
@@ -15,6 +29,8 @@ export interface ParsedArgs {
     stream: boolean;
     /** When set, run the child in --mode json and stream its event log to this file path. */
     progressLog?: string;
+    /** Review budget for the loop command. */
+    maxRounds?: number;
     continueHandle?: string;
     model?: string;
     provider?: string;
@@ -22,6 +38,18 @@ export interface ParsedArgs {
     tools?: string;
     name?: string;
     search?: string[];
+    /** Panel: number of independent reviewers (generic same-model panel). */
+    reviewers?: number;
+    /** Panel: named expert-panel preset. */
+    panel?: string;
+    /** Panel: consensus policy (any | quorum | majority | unanimous). */
+    consensus?: string;
+    /** Panel: minimum agreement for quorum consensus. */
+    minAgree?: number;
+    /** Panel: model used for semantic consensus adjudication. */
+    consensusModel?: string;
+    /** Panel: bounded reviewer concurrency. */
+    concurrency?: number;
 }
 export interface ReviewPreset {
     description: string;
@@ -37,17 +65,131 @@ export interface VerdictInfo {
     verdictSource: "parsed" | "fallback" | "runtime_error";
     parseError?: string;
 }
-export interface ReviewMeta {
+export interface ReviewMeta extends StructuredReviewResult {
     reviewMode: string;
-    verdict: Verdict;
-    verdictSource: string;
     durationMs: number;
     model: string | null;
+    /** Thinking level requested for this review (off|minimal|low|medium|high|xhigh|max), if any. */
+    thinking?: string;
+    /** Token usage from the child pi --mode json stream, when available. */
+    usage?: TokenUsage;
     sessionHandle?: string;
-    parseError?: string;
+}
+export interface ReviewRunResult {
+    meta: ReviewMeta;
+    exitCode: number;
 }
 export interface SplitPayload {
     fileRefs: string[];
     userText: string;
 }
+export declare const CONSENSUS_POLICIES: readonly ["any", "quorum", "majority", "unanimous"];
+export type ConsensusPolicy = (typeof CONSENSUS_POLICIES)[number];
+/** Token usage accumulated across an agent turn (from pi's --mode json stream). */
+export interface TokenUsage {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    reasoning: number;
+    totalTokens: number;
+    costTotal?: number;
+}
+/** Documented initial maximum number of reviewers in one panel. */
+export declare const MAX_REVIEWERS = 8;
+/** Default minimum agreement for a multi-reviewer quorum panel. */
+export declare const DEFAULT_PANEL_MIN_AGREE = 2;
+/** Confidence at or above which a semantic adjudicator match merges clusters. */
+export declare const SEMANTIC_MATCH_CONFIDENCE_THRESHOLD = 0.6;
+/** A raw finding tagged with reviewer identity and a globally-unique source ID. */
+export interface SourceFinding {
+    /** Globally unique id scoped to reviewer identity, e.g. "r1#F1". */
+    id: string;
+    reviewerId: string;
+    finding: ReviewFinding;
+}
+/**
+ * A cluster of findings that represent the same underlying issue.
+ * `confirmed` is true only when actionable support meets the consensus
+ * threshold; otherwise the cluster is a non-blocking advisory.
+ */
+export interface FindingCluster {
+    /** Stable cluster id within one panel evaluation, e.g. "C1". */
+    id: string;
+    summary: string;
+    severity?: string;
+    path?: string;
+    confirmed: boolean;
+    /** Distinct reviewers contributing any finding to this cluster. */
+    supportCount: number;
+    /** Distinct reviewers contributing an actionable finding. */
+    actionableSupportCount: number;
+    supportingReviewerIds: string[];
+    sourceFindingIds: string[];
+}
+export type PanelHealth = "healthy" | "needs_human" | "blocked";
+/** Per-reviewer provenance recorded in the aggregate panel metadata. */
+export interface ReviewerOutcome {
+    reviewerId: string;
+    role?: string;
+    model?: string | null;
+    thinking?: string;
+    usage?: TokenUsage;
+    durationMs: number;
+    status: ReviewStatus;
+    verdict: Verdict;
+    verdictSource: VerdictInfo["verdictSource"];
+    /** True when this reviewer contributed parseable findings to aggregation. */
+    contributed: boolean;
+    runtimeError?: string;
+    parseError?: string;
+}
+/** Additive panel fields shared by the aggregation result and the review meta. */
+export interface PanelFields {
+    strategy: "panel";
+    panelPreset?: string;
+    configuredReviewers: number;
+    successfulReviewers: number;
+    consensusPolicy: ConsensusPolicy;
+    consensusThreshold: number;
+    panelHealth: PanelHealth;
+    confirmedClusters: FindingCluster[];
+    advisories: FindingCluster[];
+    reviewers: ReviewerOutcome[];
+    adjudicationUsed: boolean;
+    adjudicationErrors?: string[];
+}
+/** Pure aggregate panel result (no Pi, no I/O). */
+export interface PanelAggregationResult extends StructuredReviewResult, PanelFields {
+}
+/** Review metadata for a panel evaluation; additive over ReviewMeta. */
+export interface PanelReviewMeta extends ReviewMeta, PanelFields {
+}
+/** A reviewer's structured submission fed to the pure aggregation seam. */
+export interface ReviewerSubmission {
+    reviewerId: string;
+    role?: string;
+    model?: string | null;
+    thinking?: string;
+    usage?: TokenUsage;
+    durationMs: number;
+    result: StructuredReviewResult;
+}
+/** One reviewer definition inside a named panel preset. */
+export interface PanelReviewerSpec {
+    id: string;
+    role: string;
+    provider?: string;
+    model?: string;
+    thinking?: string;
+}
+/** A named expert-panel preset. */
+export interface PanelPreset {
+    description: string;
+    reviewers: PanelReviewerSpec[];
+    consensus?: ConsensusPolicy;
+    minAgree?: number;
+    consensusModel?: string;
+    concurrency?: number;
+}
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,QAAQ,2EAA4E,CAAC;AAClG,MAAM,MAAM,OAAO,GAAG,CAAC,OAAO,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC;AAEhD,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,eAAe,GAAG,iBAAiB,GAAG,QAAQ,CAAC;IAC1F,gEAAgE;IAChE,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,4EAA4E;IAC5E,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,WAAW,EAAE,OAAO,CAAC;IACrB,kGAAkG;IAClG,MAAM,EAAE,OAAO,CAAC;IAChB,yFAAyF;IACzF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,aAAa,EAAE,QAAQ,GAAG,UAAU,GAAG,eAAe,CAAC;IACvD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,UAAU;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;CAClB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -1,2 +1,13 @@
 export const VERDICTS = ["approve", "request_changes", "needs_clarification", "blocked"];
+export const REVIEW_STATUSES = ["clean", "has_findings", "needs_human", "blocked"];
+// ---------------------------------------------------------------------------
+// Panel review
+// ---------------------------------------------------------------------------
+export const CONSENSUS_POLICIES = ["any", "quorum", "majority", "unanimous"];
+/** Documented initial maximum number of reviewers in one panel. */
+export const MAX_REVIEWERS = 8;
+/** Default minimum agreement for a multi-reviewer quorum panel. */
+export const DEFAULT_PANEL_MIN_AGREE = 2;
+/** Confidence at or above which a semantic adjudicator match merges clusters. */
+export const SEMANTIC_MATCH_CONFIDENCE_THRESHOLD = 0.6;
 //# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,SAAS,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,SAAS,CAAU,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,SAAS,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,SAAS,CAAU,CAAC;AAGlG,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,SAAS,CAAU,CAAC;AA4F5F,8EAA8E;AAC9E,eAAe;AACf,8EAA8E;AAE9E,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,WAAW,CAAU,CAAC;AActF,mEAAmE;AACnE,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,CAAC;AAE/B,mEAAmE;AACnE,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC;AAEzC,iFAAiF;AACjF,MAAM,CAAC,MAAM,mCAAmC,GAAG,GAAG,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zephyrdeng/pi-review",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "description": "Isolated AI-powered code and plan reviews from the command line",
   "type": "module",
   "author": "ZephyrDeng <zephyrTang@aliyun.com>",
@@ -24,7 +24,7 @@
     "cli"
   ],
   "bin": {
-    "pi-review": "./bin/pi-review.js"
+    "pi-review": "bin/pi-review.js"
   },
   "exports": {
     ".": {
@@ -67,7 +67,7 @@
     "build": "tsc",
     "check": "tsc --noEmit",
     "smoke": "node dist/cli.js --help >/dev/null",
-    "test": "npx --yes tsx --test src/child-process.test.ts src/review.meta.test.ts src/meta-footer.test.ts src/json-events.test.ts src/install-args.test.ts extensions/rv-prompts.test.ts extensions/rv-completions.test.ts extensions/rv-model-priorities.test.ts extensions/rv-locale.test.ts extensions/rv-semantic.test.ts",
+    "test": "npx --yes tsx --test src/args.test.ts src/cli-exit.test.ts src/child-process.test.ts src/review.meta.test.ts src/review-result.test.ts src/loop.test.ts src/meta-footer.test.ts src/prompt.test.ts src/skill-protocol.test.ts src/json-events.test.ts src/install-args.test.ts src/panel-aggregate.test.ts src/matcher.test.ts src/panel-config.test.ts src/panel-loop.test.ts src/panel-cli.test.ts extensions/rv-prompts.test.ts extensions/rv-completions.test.ts extensions/rv-model-priorities.test.ts extensions/rv-locale.test.ts extensions/rv-semantic.test.ts",
     "test:rv": "npx --yes tsx --test extensions/rv-prompts.test.ts extensions/rv-completions.test.ts extensions/rv-model-priorities.test.ts extensions/rv-locale.test.ts extensions/rv-semantic.test.ts",
     "prepublishOnly": "npm run build",
     "pack:dry": "npm pack --dry-run"

package/resources/panel-presets.json

@@ -0,0 +1,21 @@
+{
+  "code-experts": {
+    "description": "Code review panel with independent correctness, security, and testing lenses.",
+    "consensus": "quorum",
+    "minAgree": 2,
+    "reviewers": [
+      {
+        "id": "correctness",
+        "role": "Correctness reviewer: focus on logic errors, regressions, concurrency, API contracts, edge cases, and maintainability."
+      },
+      {
+        "id": "security",
+        "role": "Security reviewer: focus on input validation, authn/authz, secrets, injection, unsafe deserialization, and trust boundaries."
+      },
+      {
+        "id": "testing",
+        "role": "Testing reviewer: focus on missing tests, weak assertions, flakiness, coverage gaps, and behavior that would escape the test suite."
+      }
+    ]
+  }
+}

package/resources/system-prompt.md

@@ -34,7 +34,17 @@ One of: approve | request_changes | needs_clarification | blocked
 Short conclusion in 2-5 bullets.
 
 ## Findings
-Prioritized findings. Each finding should include severity, evidence, impact, and recommendation. If there are no material findings, write "No material findings."
+Prioritized findings. For every material finding, use this exact shape (increment IDs as F1, F2, ...):
+
+### F1: <summary>
+- Severity: critical | high | medium | low
+- Path: <path or none>
+- Actionable: yes | no
+- Evidence: <concrete evidence>
+- Impact: <why it matters>
+- Recommendation: <specific next step>
+
+Set Actionable to yes when the host must fix or consciously reject the finding before clean closeout. Use no for informational or explicitly out-of-scope follow-up findings. If there are no material findings, write "No material findings."
 
 ## Risks and Blind Spots
 What could still be wrong, missing, or unverified.

package/skills/pi-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pi-review
-description: Use pi-review to delegate isolated code, diff, repository, architecture, or plan reviews to a fresh Pi session and return only the review conclusion. Model selection presets for code, frontend, and plan review (see 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). Use when the user asks for Pi review, isolated review, code review, plan review, challenge review, review status/progress, or wants to avoid context pollution.
+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).
 ---
 
 # Pi Review
@@ -45,15 +45,10 @@ When resolving this fallback, use the actual directory that contains this `SKILL
 
 ## Streaming vs agent hosts (Claude Code / Codex)
 
-- `pi-review` **streams** child `pi` stdout/stderr to the process terminal by default (`--no-stream` buffers until exit). That helps **Pi** and real terminals, not most agent chat UIs.
-- **Claude Code, Cursor, Codex**, and similar hosts **buffer tool stdout** until the bash command exits, so the chat shows the review **all at once** even though the CLI is streaming. That is expected—not a misconfiguration.
-- Default `text` mode also produces **no stdout** during tool-use/thinking (only the final answer), so even a local terminal stays quiet for most of a multi-minute review.
-- **Recommended for Claude Code / Codex (live progress):** always use `--progress-log <path>` unless the user explicitly wants a silent blocking wait:
-  1. Pick a writable path (e.g. `/tmp/pi-review-<id>.jsonl`).
-  2. Start `pi-review --progress-log <path> ...` in a **background** or **async** shell invocation (not a blocking foreground Bash that you wait on with no updates).
-  3. While the child runs, **tail** the log and summarize milestones to the user (filter out `message_update` / `tool_execution_update` unless they asked for token-level detail).
-  4. When the process exits, show the Markdown body and ASCII `── pi-review` footer from the command result (or re-read the final output as the skill’s step 4 describes).
-- Fall back to a **local terminal** with default streaming only if the host cannot run background commands or tail a file.
+- `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.
 
 ## Review status (no slash command)
 
@@ -78,6 +73,87 @@ There is **no** `/status` slash in this skill. When the user asks for **review s
 
 Do not implement findings from a status check; status is informational only.
 
+## Loop closeout protocol
+
+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:
+   ```bash
+   pi-review loop --max-rounds 1 [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:**
+   - **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.
+   - `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.
+
+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.
+
+## 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.
+
+### 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>`.
+
+### 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**.
+
+Consensus policies (default `quorum` for multi-reviewer panels):
+
+| Policy | Threshold |
+|--------|----------|
+| `any` | one actionable reviewer confirms |
+| `quorum` | configured minimum agreement (default 2; set with `--min-agree`) |
+| `majority` | `floor(reviewers / 2) + 1` |
+| `unanimous` | every reviewer |
+
+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.
+
+### Advisories
+
+Singleton (uncorroborated) findings remain visible as **advisories** but do **not** change clean status or fail the gate. They are recorded as non-blocking follow-ups; the host promotes them only with explicit human acceptance. Confirmed actionable clusters produce `has_findings`; no confirmed clusters produce `clean`.
+
+### Aggregation
+
+Two-phase matching: deterministic matching on stable anchors (path + normalized summary) first; only ambiguous same-path candidates go to a constrained **semantic adjudicator** (enabled with `--consensus-model`). The adjudicator clusters findings and may **not** invent findings, drop findings, add evidence, or act as another reviewer — it has no write tools. Low-confidence matches stay separate advisories so uncertain similarity cannot manufacture quorum.
+
+### Cost multipliers
+
+Cost is visible before execution. Reviewer runs = `--reviewers <n>` × `--max-rounds` (loop). One consensus-adjudication call may run per round when `--consensus-model` is set, tracked separately. Use `--concurrency <n>` to bound provider/machine pressure (default: reviewer count, never exceeds it).
+
+### Host-only fixes
+
+Panel review composes with Loop Review: one loop round evaluates one **complete panel** with fresh reviewer sessions. The CLI never edits, patches, or waits for filesystem changes — the host agent remains the only actor allowed to fix between process invocations. Apply the scope governor to **confirmed** findings exactly as for single-review findings. Rejected confirmed findings must be recorded with rationale. `--max-rounds 1` keeps the patch-by-patch closeout workflow.
+
+Panel review rejects `--keep-session`, `--continue`, and `--name` in v1 (reviewers run `--no-session`). Reviewer runtime failure → `blocked`; unstructured dirty output or unresolved clarification → `needs_human`; never silently clean.
+
+### Examples
+
+```bash
+# Single panel review
+pi-review --reviewers 3 --consensus quorum --min-agree 2 -- @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
+```
+
 ## Steps
 
 1. Prime the model catalog and pick a model:
@@ -116,8 +192,8 @@ Do not implement findings from a status check; status is informational only.
 
 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 also emit JSON on stdout).
-   - Do not apply findings automatically; implementation is a separate user decision.
+   - Scripts: parse `PI_REVIEW_META_JSON:` from **stderr** (or set `PI_REVIEW_META_STDOUT=1` to emit JSON on stdout instead).
+   - 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
@@ -127,6 +203,8 @@ 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 --mode challenge --continue <sessionHandle> -- "expand finding 2"
+pi-review loop --max-rounds 1 -- @src
+pi-review loop --max-rounds 1 --progress-log /tmp/pi-review-loop.jsonl -- @src
 ```
 
 ## Status examples (user phrasing)

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

@@ -12,19 +12,32 @@ 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—even though the CLI streams by default. Default `text` mode also emits **no stdout** during tool-use/thinking (only the final answer).
+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`:
+
+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.
 
 When the **pi-review** skill applies on Codex, Claude Code, or Cursor:
 
-1. **Default:** `pi-review --progress-log <path> ...` (writable file, e.g. `/tmp/pi-review-<id>.jsonl`).
-2. Start that command in a **background** or **async** shell invocation—not a single blocking call with no interim updates.
-3. **Tail** the log while the child runs; summarize milestones to the user (skip `message_update` / `tool_execution_update` unless they want token-level detail).
-4. After exit, show the Markdown review and ASCII `── pi-review` footer (skill step 4).
+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).
 
-**Pi interactive (`/rv`)** is different: foreground `pi-review`, default streaming only—do **not** auto-add `--progress-log` unless the user asked.
+**Pi interactive (`/rv`)**: foreground `pi-review`, default streaming. Text deltas appear live on the terminal; no `--progress-log` unless the user asked.
 
 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:
+
+```bash
+pi-review loop --max-rounds 1 -- @src
+# optional: --progress-log /tmp/pi-review-loop.jsonl for the full event log
+```
+
+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.
+
 **Model choice:** after `pi-review models`, use **[model-selection.md](./model-selection.md)** (code / frontend / plan presets)—same guidance as Pi `/rv` completions.
 
 Example tail (milestone events only):