@in-the-loop-labs/pair-review 3.9.1 → 4.1.0

package/README.md

@@ -20,6 +20,7 @@
   - [AI-Guided Review](#3-ai-guided-review-when-youre-accountable)
 - [Quick Start](#quick-start)
 - [Command Line Interface](#command-line-interface)
+  - [Local review scope](#local-review-scope)
   - [Headless analysis mode](#headless-analysis-mode)
 - [Configuration](#configuration)
   - [Environment Variables](#environment-variables)
@@ -65,7 +66,7 @@ pair-review is a local web application for keeping humans in the loop with AI co
 - **Local-First**: All data and processing happens on your machine - no cloud dependencies
 - **GitHub-Familiar UI**: Interface feels instantly familiar to GitHub users
 - **Human-in-the-Loop**: AI suggests, you decide
-- **Multiple AI Providers**: Support for Claude, Gemini, Codex, Copilot, OpenCode, Cursor, and Pi. Use your existing subscription!
+- **Multiple AI Providers**: Support for Claude, Antigravity, Codex, Copilot, OpenCode, Cursor, and Pi. Use your existing subscription!
 - **Progressive**: Start simple with manual review, add AI analysis when you need it
 
 ## Workflows
@@ -89,7 +90,8 @@ Compared to giving feedback in chat, this feels like moving from a machete to a
 
 **Tips:**
 - Stage previous changes in git, then only review new modifications in the next round
-- Local mode only shows unstaged changes and untracked files (opinionated by design)
+- By default local mode reviews unstaged changes and untracked files; adjust the range with `--scope` (or the web UI scope selector) — e.g. `branch..untracked` to cover the whole branch (see [Local review scope](#local-review-scope))
+
 ### 2. Meta-Review: Judging AI Suggestions
 
 **When to use:** You're not going to read every line of code. Let AI be your reader.
@@ -203,7 +205,10 @@ pair-review --local [path]
 | `-d`, `--debug` | Enable verbose debug logging for troubleshooting |
 | `-h`, `--help` | Show help message with full CLI documentation |
 | `-l`, `--local [path]` | Review local uncommitted changes. Optional path defaults to current directory |
+| `--scope <start>..<end>` | **Local mode only.** Set the diff range a local review covers. Stops (in order): `branch`, `staged`, `unstaged`, `untracked`. Six valid ranges (contiguous, must include `unstaged`); default `unstaged..untracked`. `branch..*` diffs from the merge-base with the base branch. See [Local review scope](#local-review-scope). |
+| `--base <branch>` | **Local mode only.** With a `branch..*` scope, override base-branch auto-detection. Errors if used without a branch-start scope. |
 | `--model <name>` | Override the AI model for any provider. Model availability depends on provider configuration. |
+| `--provider <name>` | Override the AI provider. Applies to headless modes (`--ai-draft` / `--ai-review`) **and** to browser-driven auto-analysis (`--ai`), where it overrides the repo/app default the browser would otherwise use — including across single-port delegation to an already-running server. Defaults to the repo/app default provider (`claude`). Pair with `--model` when the model belongs to a non-default provider (e.g. `--provider codex --model gpt-5.5`). |
 | `--register` | Register `pair-review://` URL scheme handler (macOS only) |
 | `--unregister` | Unregister `pair-review://` URL scheme handler (macOS only) |
 | `--command <cmd>` | Custom CLI command for `--register` (default: `npx @in-the-loop-labs/pair-review`) |
@@ -216,8 +221,10 @@ pair-review 123                        # Review PR #123 in current repo
 pair-review https://github.com/owner/repo/pull/456
 pair-review --local                    # Review uncommitted local changes
 pair-review 123 --ai                   # Auto-run AI analysis
+pair-review 123 --ai --provider codex  # Auto-run analysis in the browser with a specific provider
 pair-review --list-councils            # List saved councils and their handles
 pair-review 123 --ai-draft --council security-review  # Headless draft with a council
+pair-review 123 --ai-draft --provider codex --model gpt-5.5  # Headless draft with a specific provider + model
 pair-review --local --ai --council security-review    # Local review with a council
 pair-review --local --headless         # Analyze local changes, print a summary, exit
 pair-review --local --headless --json  # Analyze local changes, emit JSON, exit
@@ -240,6 +247,44 @@ pair-review --register --command "node bin/pair-review.js"  # Custom command
 > web UI's default **Analyze** action, so `--council`/`--model` are optional when
 > a repo default is configured.
 
+### Local review scope
+
+`--scope <start>..<end>` sets which changes a **local** review covers (it has
+no effect on PR reviews). The scope walks four ordered stops — `branch` →
+`staged` → `unstaged` → `untracked` — and a range must be contiguous and always
+include `unstaged`, since the AI models read files from the working tree and the
+diff must cover that state. That leaves six valid ranges:
+
+| Scope | Covers |
+|-------|--------|
+| `branch..unstaged` | All tracked changes since the base branch (committed + staged + unstaged); no new files |
+| `branch..untracked` | Everything since the base branch, including new files |
+| `staged..unstaged` | Staged changes plus working-tree edits vs `HEAD`; no new files |
+| `staged..untracked` | Staged changes, working-tree edits, and new files |
+| `unstaged..unstaged` | Only unstaged working-tree edits (staged changes treated as already reviewed) |
+| `unstaged..untracked` | Unstaged working-tree edits plus new files (**default**) |
+
+A scope ending at `untracked` includes new (untracked) files automatically — no
+`git add -N` needed. `branch..*` diffs from the merge-base with the base branch.
+
+`--base <branch>` overrides base-branch auto-detection for a `branch..*` scope.
+Detection order when `--base` is omitted: Graphite stack state (only when
+`enable_graphite: true` is set in `~/.pair-review/config.json`) → GitHub PR base →
+`origin`'s default branch → `main`/`master`. `--base` errors if used without a
+branch-start scope.
+
+Both flags are **local-mode only**: they error when given a PR argument and do
+**not** imply `--local`. An explicit `--scope` is persisted on the review
+session, so opening the web UI for that review later shows the same scope.
+
+```bash
+# Review everything on this branch since it diverged from the trunk, plus new files
+pair-review --local --scope branch..untracked
+
+# Same, but against an explicit base branch (stacked branches / non-default trunk)
+pair-review --local --scope branch..untracked --base develop
+```
+
 ### Headless analysis mode
 
 `--headless` runs an AI analysis (single provider or council), stores the results
@@ -427,7 +472,7 @@ Nested objects (like `chat`, `providers`, `chat_providers`, `monorepos`) are dee
 
 ### Alternate Git Hosts
 
-pair-review can review pull requests on self-hosted Git platforms that expose a GitHub-compatible REST API, configured per-repository via `repos["owner/repo"].api_host` and related keys. See [docs/alt-host.md](docs/alt-host.md) for the full configuration guide.
+pair-review can review pull requests on self-hosted Git platforms that expose a GitHub-compatible REST API, configured per-repository via `repos["owner/repo"].api_host` and related keys. By default an `api_host` repo is treated as living exclusively on the alt host; set `exclusive: false` on the repo entry to mark it as **dual-host**, where some PRs live on `github.com` and others on the alt host and pair-review resolves the host per PR. See [docs/alt-host.md](docs/alt-host.md) for the full configuration guide.
 
 ### Environment Variables
 
@@ -437,17 +482,20 @@ pair-review supports several environment variables for customizing behavior:
 |----------|-------------|---------|
 | `GITHUB_TOKEN` | GitHub Personal Access Token (takes precedence over config file) | - |
 | `PAIR_REVIEW_CLAUDE_CMD` | Custom command to invoke Claude CLI | `claude` |
-| `PAIR_REVIEW_GEMINI_CMD` | Custom command to invoke Gemini CLI | `gemini` |
+| `PAIR_REVIEW_ANTIGRAVITY_CMD` | Custom command to invoke Antigravity CLI | `agy` |
 | `PAIR_REVIEW_CODEX_CMD` | Custom command to invoke Codex CLI | `codex` |
 | `PAIR_REVIEW_COPILOT_CMD` | Custom command to invoke Copilot CLI | `copilot` |
 | `PAIR_REVIEW_OPENCODE_CMD` | Custom command to invoke OpenCode CLI | `opencode` |
 | `PAIR_REVIEW_CURSOR_AGENT_CMD` | Custom command to invoke Cursor Agent CLI | `agent` |
 | `PAIR_REVIEW_PI_CMD` | Custom command to invoke Pi CLI | `pi` |
 | `PAIR_REVIEW_MODEL` | Override the AI model to use (same as `--model` flag) | Provider default |
+| `PAIR_REVIEW_PROVIDER` | Override the AI provider to use (same as `--provider` flag) | `claude` |
 
 **Note:** `GITHUB_TOKEN` is the standard environment variable used by many GitHub tools (gh CLI, GitHub Actions, etc.). When set, it takes precedence over the `github_token` field in the config file.
 
-**Note:** The `--model` CLI flag is shorthand for setting `PAIR_REVIEW_MODEL`. If both are specified, the CLI flag takes precedence.
+**Note:** The `--model` CLI flag is shorthand for setting `PAIR_REVIEW_MODEL`, and `--provider` is shorthand for `PAIR_REVIEW_PROVIDER`. If both the flag and env var are specified, the CLI flag takes precedence. The `--provider` flag selects which provider runs the analysis; `--model` selects the model within that provider, so set both when the model belongs to a non-default provider (e.g. `--provider codex --model gpt-5.5`). The override outranks saved repository settings (`CLI/env > repo settings`); if the repo's default is a Review Council, an active `--provider`/`--model` override forces the single-provider path instead.
+
+**Delegation caveat:** With single-port mode (the default `single_port: true`), a new invocation delegates to an already-running server. On that path the `--provider`/`--model` override is carried to the running server only alongside browser auto-analysis (`--ai`). Delegating without `--ai` (just opening the review) does not seed the override into the other process's manual analysis dialog — use `--ai`, or a headless mode, to pin the provider on the delegated path.
 
 These variables are useful when:
 - Your CLI tools are installed in a non-standard location
@@ -466,12 +514,15 @@ PAIR_REVIEW_CLAUDE_CMD="/usr/local/bin/claude" pair-review 123
 # Use a wrapper command (supports multi-word commands)
 PAIR_REVIEW_CLAUDE_CMD="devx claude" pair-review 123
 
-# Use Gemini with npx
-PAIR_REVIEW_GEMINI_CMD="npx gemini" pair-review --local
+# Use a custom path for the Antigravity CLI
+PAIR_REVIEW_ANTIGRAVITY_CMD="/usr/local/bin/agy" pair-review --local
 
 # Force a specific model for this review
 PAIR_REVIEW_MODEL="opus" pair-review 123
 
+# Force a specific provider + model for a headless review
+PAIR_REVIEW_PROVIDER="codex" PAIR_REVIEW_MODEL="gpt-5.5" pair-review 123 --ai-draft
+
 # Combine multiple settings
 PAIR_REVIEW_CLAUDE_CMD="/opt/claude/bin/claude" PAIR_REVIEW_MODEL="haiku" pair-review 123
 ```
@@ -491,7 +542,7 @@ Create a Personal Access Token (PAT) with these scopes:
 pair-review integrates with AI providers via their CLI tools:
 
 - **Claude**: Uses Claude Code CLI
-- **Gemini**: Uses Gemini CLI
+- **Antigravity**: Uses the Antigravity CLI (`agy`), the successor to the Gemini CLI. Install it with `curl -fsSL https://antigravity.google/cli/install.sh | bash` (macOS/Linux; it is not an npm package) — see the [Antigravity docs](https://antigravity.google/docs). Antigravity is an analysis-only provider: it runs as an agentic reviewer in non-interactive print mode and has **no chat/ACP mode**.
 - **Codex**: Uses Codex CLI
 - **GitHub Copilot**: Uses Copilot CLI
 - **OpenCode**: Uses OpenCode CLI (requires model configuration)
@@ -502,7 +553,7 @@ You can select your preferred provider and model in the repository settings UI.
 
 #### Built-in vs. Configurable Providers
 
-Most providers (Claude, Gemini, Codex, Copilot) come with built-in model definitions. **OpenCode and Pi are different** - they have no built-in models and require you to configure which models to use.
+Most providers (Claude, Antigravity, Codex, Copilot) come with built-in model definitions. **OpenCode and Pi are different** - they have no built-in models and require you to configure which models to use.
 
 #### Configuring Custom Models
 
@@ -648,7 +699,7 @@ The key difference from Review Council is consolidation order: Advanced consolid
 
 - **Large changesets with Opus 4.6**: Use review council instructions to tell the model to use a Team — it will spawn sub-agents to divide the work
 - **Multi-model parallel review**: Give each model a specific focus area (security, performance, correctness) via per-model instructions and get combined results
-- **Cross-model perspectives**: Run the same analysis across different providers (e.g., Claude, Gemini, GPT) — where models agree signals high-confidence findings, but unique outliers from a single model can be equally valuable, catching issue types that only that model excels at spotting
+- **Cross-model perspectives**: Run the same analysis across different providers (e.g., Claude, Antigravity, GPT) — where models agree signals high-confidence findings, but unique outliers from a single model can be equally valuable, catching issue types that only that model excels at spotting
 
 ### Chat
 
@@ -683,7 +734,7 @@ Configure your preferred models in `providers.pi.models` — see [AI Provider Co
 }
 ```
 
-Available chat provider IDs: `pi`, `claude`, `codex`, `copilot-acp`, `gemini-acp`, `opencode-acp`, `cursor-acp`. Each supports `command`, `args` (replaces defaults), `extra_args` (appends), and `env` overrides. Codex chat also supports `sandbox`: use `workspace-write` by default, or `read-only` for discussion-only sessions.
+Available chat provider IDs: `pi`, `claude`, `codex`, `copilot-acp`, `opencode-acp`, `cursor-acp`. Each supports `command`, `args` (replaces defaults), `extra_args` (appends), and `env` overrides. Codex chat also supports `sandbox`: use `workspace-write` by default, or `read-only` for discussion-only sessions. (Antigravity is an analysis-only provider — it has no ACP mode, so there is no Antigravity chat provider.)
 
 **Keyboard shortcut:** Press `p` then `c` to toggle the chat panel.
 
@@ -791,7 +842,10 @@ Templates typically include `{description}` to render the suggestion body.
 
 ### Local Mode
 
-Review **unstaged**, uncommitted changes before creating a PR:
+Review your uncommitted changes before creating a PR — by default the unstaged
+working-tree edits plus untracked files, with the range adjustable via `--scope`
+(or the web UI scope selector), e.g. `branch..untracked` to cover the whole
+branch (see [Local review scope](#local-review-scope)):
 
 ```bash
 pair-review --local
@@ -806,11 +860,28 @@ Perfect for:
 
 ## Claude Code Plugins
 
-pair-review provides two [Claude Code plugins](https://code.claude.com/docs/en/plugins) that bring AI-powered code review directly into Claude Code.
+pair-review provides three [Claude Code plugins](https://code.claude.com/docs/en/plugins) that bring AI-powered code review directly into Claude Code.
+
+### pair-loop — Agent-Orchestrated Review Loop
+
+An implement→review→fix loop with pair-review as the review oracle. The agent runs multi-model council reviews through the headless CLI, triages the findings (fixing, dismissing with reasons, or asking you), applies fixes, and repeats with narrowing instructions until a final review returns no blockers. Every round persists to pair-review, and when the server is running the agent writes its triage back — so you can open the web UI, inspect every round, and see exactly what was fixed or dismissed and why. No MCP required.
+
+**Install via Marketplace:**
+
+```
+/plugin marketplace add in-the-loop-labs/pair-review
+/plugin install pair-review@pair-loop
+```
+
+**Available Skills:**
+
+| Skill | Description |
+|-------|-------------|
+| `/pair-loop:loop` | Implement, review with pair-review councils, triage, fix, and repeat until clean |
 
 ### code-critic — Standalone Analysis
 
-AI-powered code review analysis that works without any server or MCP dependency. Install this plugin for three-level AI analysis and implement-review-fix loops directly in your coding agent.
+AI-powered code review analysis that works without any server or MCP dependency. Install this plugin for three-level AI analysis directly in your coding agent.
 
 **Install via Marketplace:**
 
@@ -824,7 +895,8 @@ AI-powered code review analysis that works without any server or MCP dependency.
 | Skill | Description |
 |-------|-------------|
 | `/code-critic:analyze` | Run three-level AI analysis using Task agents directly (standalone, no server needed) |
-| `/code-critic:loop` | Implement code, review with AI, fix issues, and repeat until clean |
+
+Looking for an implement-review-fix loop? That's the [pair-loop plugin](#pair-loop--agent-orchestrated-review-loop) above, which replaced the former `/code-critic:loop` skill.
 
 These skills work standalone. If the pair-review MCP server happens to be available (from the pair-review plugin), `code-critic:analyze` will use it for prompts and push results to the web UI — but it's entirely optional.
 
@@ -857,10 +929,12 @@ If you prefer not to use the marketplace, load plugins directly from an npm-inst
 
 ```bash
 # From a local clone
+claude --plugin-dir ./path/to/pair-review/plugin-pair-loop
 claude --plugin-dir ./path/to/pair-review/plugin-code-critic
 claude --plugin-dir ./path/to/pair-review/plugin
 
 # From a globally installed npm package
+claude --plugin-dir "$(npm root -g)/@in-the-loop-labs/pair-review/plugin-pair-loop"
 claude --plugin-dir "$(npm root -g)/@in-the-loop-labs/pair-review/plugin-code-critic"
 claude --plugin-dir "$(npm root -g)/@in-the-loop-labs/pair-review/plugin"
 ```
@@ -880,6 +954,7 @@ To pre-configure plugins for all contributors on a repository, add this to your
     }
   },
   "enabledPlugins": {
+    "pair-review@pair-loop": true,
     "pair-review@code-critic": true,
     "pair-review@pair-review": true
   }
@@ -959,8 +1034,8 @@ These commands update your MCP configuration in `~/.claude/settings.json` (user-
 
 ### Prerequisites
 
-- Node.js 20.0.0 or higher
-- [pnpm](https://pnpm.io/) 10.x
+- Node.js 22.0.0 or higher
+- [pnpm](https://pnpm.io/) 11.x
 - Git
 
 ### Running Locally

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@in-the-loop-labs/pair-review",
-  "version": "3.9.1",
+  "version": "4.1.0",
   "description": "Your AI-powered code review partner - Close the feedback loop with AI coding agents",
   "main": "src/server.js",
   "bin": {
@@ -14,13 +14,15 @@
     "public/",
     "plugin/",
     "plugin-code-critic/",
+    "plugin-pair-loop/",
     "config.managed.json",
     "README.md",
     "LICENSE"
   ],
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=22.0.0"
   },
+  "packageManager": "pnpm@11.9.0",
   "scripts": {
     "start": "node src/server.js",
     "dev": "node bin/pair-review.js",
@@ -47,7 +49,7 @@
     "cursor",
     "copilot",
     "codex",
-    "gemini"
+    "antigravity"
   ],
   "author": "Tim Perkins",
   "license": "Apache-2.0",
@@ -63,7 +65,7 @@
     "@agentclientprotocol/sdk": "^0.14.1",
     "@modelcontextprotocol/sdk": "^1.25.3",
     "@octokit/rest": "^19.0.11",
-    "better-sqlite3": "^11.8.1",
+    "better-sqlite3": "^12.11.1",
     "express": "^4.18.2",
     "glob": "^13.0.6",
     "markdown-it": "^13.0.2",
@@ -83,10 +85,5 @@
     "jsdom": "^29.0.1",
     "supertest": "^7.1.4",
     "vitest": "^4.0.16"
-  },
-  "pnpm": {
-    "onlyBuiltDependencies": [
-      "better-sqlite3"
-    ]
   }
 }

package/plugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "pair-review",
-  "version": "3.9.1",
+  "version": "4.1.0",
   "description": "pair-review app integration — Open PRs and local changes in the pair-review web UI, run server-side AI analysis, and address review feedback. Requires the pair-review MCP server.",
   "author": {
     "name": "in-the-loop-labs",

package/plugin-code-critic/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "code-critic",
-  "version": "3.9.1",
-  "description": "AI-powered code review analysis — Run three-level AI analysis and implement-review-fix loops directly in your coding agent. Works standalone, no server required.",
+  "version": "4.1.0",
+  "description": "AI-powered code review analysis — Run three-level AI analysis directly in your coding agent. Works standalone, no server required.",
   "author": {
     "name": "in-the-loop-labs",
     "email": "tjwp@inthelooplabs.com"
@@ -13,7 +13,6 @@
     "code-review",
     "ai",
     "analysis",
-    "code-critic",
-    "critic-loop"
+    "code-critic"
   ]
 }

package/plugin-pair-loop/.claude-plugin/plugin.json

@@ -0,0 +1,19 @@
+{
+  "name": "pair-loop",
+  "version": "4.1.0",
+  "description": "Agent-orchestrated review loop — implement, review with pair-review multi-model councils via the headless CLI, triage, fix, and repeat until a final review returns no blockers. MCP-independent.",
+  "author": {
+    "name": "in-the-loop-labs",
+    "email": "tjwp@inthelooplabs.com"
+  },
+  "homepage": "https://github.com/in-the-loop-labs/pair-review",
+  "repository": "https://github.com/in-the-loop-labs/pair-review",
+  "license": "Apache-2.0",
+  "keywords": [
+    "code-review",
+    "ai",
+    "review-loop",
+    "council",
+    "feedback-loop"
+  ]
+}

package/plugin-pair-loop/skills/loop/SKILL.md

@@ -0,0 +1,233 @@
+---
+name: loop
+description: >
+  Drive an implement→review→fix loop with pair-review as the review oracle:
+  run multi-model council reviews, triage the findings, apply fixes, and
+  repeat with narrowing instructions until a final review returns no
+  blockers. Use when the user says "pair loop", "review loop",
+  "loop until clean", "review this with pair-review and fix what it finds",
+  or wants iterative development reviewed by pair-review councils.
+arguments:
+  council:
+    description: "Council handle (name, name-slug, or id prefix) to review with. Defaults to the repo's default council when omitted."
+    required: false
+  maxRounds:
+    description: "Budget for review rounds. On reaching it without convergence, stop and report honestly."
+    required: false
+    default: 5
+  instructions:
+    description: "Extra review instructions applied to every round (e.g. 'focus on security')"
+    required: false
+---
+
+# pair-loop
+
+You are a thin orchestrator. pair-review does the heavy lifting — multi-level,
+multi-model council reviews with persistence and a web UI. Your job is
+judgment: what to send for review, how to triage what comes back, what to
+fix, when to ask the user, and when to stop.
+
+Reviews run through **one execution mode: the headless CLI**. It is
+synchronous (no polling), emits JSON, and needs no server. The HTTP API is
+used for exactly one optional thing: writing triage back so a running web UI
+shows reality (see Write triage back).
+
+Any text in the user's request beyond the named arguments is the
+**objective** — what to build or change. If there is no objective, the loop
+runs over the changes already in the working tree.
+
+## Hard rules
+
+These are not judgment calls:
+
+1. **Never report "clean" or "ready" unless a full-quality council round,
+   instructed to report only merge-blockers, came back with an empty finding
+   list.** A cheaper or broader round cannot grant the final verdict.
+2. **Never silently stop.** If the loop is not converging or hits
+   `maxRounds`, say so, list the outstanding findings, and (when a server is
+   up) link the review URL.
+3. **Sequence strictly: fix → write triage back → then run the next round.**
+4. **One review at a time.** Never run two reviews concurrently for the same
+   repo.
+5. **Do not commit or push.** Leave changes in the working tree. New
+   (untracked) files are included automatically whenever the review scope ends
+   at `untracked` — which the default scope (`unstaged..untracked`) does — so
+   no `git add -N` (intent-to-add) is needed.
+6. **Report failures faithfully.** A failed run (`"ok": false`, non-zero
+   exit) is reported as what it is — never papered over as "no findings".
+
+## Phase: Setup
+
+1. `git rev-parse --show-toplevel` → `REPO_ROOT`. All commands run from here.
+2. Create the round log at `REPO_ROOT/.pair-loop/round-log.md` (mkdir -p; add
+   `.pair-loop/` to `.gitignore` if missing). Record: objective, arguments,
+   start time. Append to this file after every phase — it is your resume
+   state if the session compacts.
+3. If a `council` argument was given, confirm the handle exists:
+   `pair-review --list-councils` prints the saved councils. If `pair-review`
+   is not on PATH, use `npx -y @in-the-loop-labs/pair-review` for every CLI
+   call. An unknown handle → show the available names and ask the user.
+4. If an objective was given and the working tree has no relevant changes
+   yet, implement the objective first (directly or via a Task agent — your
+   call based on size). Verify with `git status --short` that changes exist
+   before the first review round; if none, tell the user and stop.
+
+## Running a review round
+
+```bash
+pair-review --local --headless --json --council <handle> [--scope <range>] --instructions "<round instructions>"
+```
+
+- Run from `REPO_ROOT`. `--local` with no path uses the current directory.
+- Omit `--council` to use the repo's default council.
+- **Scope (`--scope`).** By default a local review covers only uncommitted
+  working-tree changes plus new files (`unstaged..untracked`). That is right
+  only while all the work under review stays uncommitted. If the work under
+  review already spans commits on a branch, a clean working tree would review as
+  **empty** — pass
+  `--scope branch..untracked` so every round covers the whole branch
+  (everything since the base branch) plus the working tree and new files. Add
+  `--base <branch>` when the base branch is not auto-detected (a non-default
+  trunk, or a stacked branch). `--scope`/`--base` are local-mode only.
+- **Be patient — council reviews routinely take 15–40 minutes.** Individual
+  council voices have their own internal timeouts; trust the CLI to finish.
+  Run the command in the background (or with a timeout of at least 45
+  minutes) and wait for it to exit. Do not abandon or kill it early; do not
+  start a second review while one is running (hard rule 4).
+- stdout is exactly one JSON document (logs go to stderr):
+  - success: `{"ok": true, "mode": "local", "run": {...}, "suggestions":
+    [...], "count": N}` — exit code 0. **Zero suggestions is still
+    success.** Record `run.id` (the runId) and `run.review_id` (the
+    reviewId, used for write-back and the review URL).
+  - failure: `{"ok": false, "error": {"message": ...}}`, exit code 1.
+
+### Round instructions
+
+Build `--instructions` per round from, in order: this standing line —
+"Do not report praise findings; report only issues." — then the user's
+`instructions` argument, the objective, and this round's directive (see
+Convergence judgment). On rounds after the first, add: "Earlier review
+rounds already reported issues that have since been fixed or dismissed;
+report only issues present in the current code."
+
+### Suggestion fields
+
+Each entry in `suggestions`: `id`, `file`, `line_start`, `line_end`, `type`
+(`bug|improvement|suggestion|design|performance|security|code-style` —
+praise is instructed away; ignore it if it appears anyway), `severity`
+(`critical|medium|minor`), `title`, `body`, `reasoning`, `ai_confidence`
+(0–1).
+
+## Triage
+
+For each finding, decide one of:
+
+- **Fix** — it is real and in scope. Goes on this round's fix list.
+- **Dismiss** — false positive, out of scope, or explicitly contrary to the
+  user's stated intent. Requires a stated reason in the round log.
+- **Ask the user** — mandatory stop, not a preference, when any of:
+  (a) you would dismiss a **critical**-severity finding;
+  (b) the fix would change behavior beyond the stated objective;
+  (c) the same finding has survived two fix rounds;
+  (d) findings conflict with the user's explicit instructions.
+  Batch the questions, ask once per round at most, record the answers in the
+  round log so later rounds do not re-ask.
+
+Dedup against your round log: a finding you already dismissed in an earlier
+round, reappearing unchanged, keeps its dismissal (re-dismiss it in
+write-back) — unless a fix touched that code since, in which case judge it
+fresh.
+
+## Fix
+
+Apply the fixes (directly or via a Task agent for large batches — your
+call). Run the project's relevant tests for the changed code. A fix that
+breaks tests is not a fix.
+
+## Write triage back (optional, needs the server)
+
+If the pair-review server is running, keep its UI truthful. Probe once per
+loop: `curl -s http://localhost:7247/health` → it is pair-review iff the
+response has `"service": "pair-review"`. (7247 is the default and is right
+most of the time; if it isn't pair-review, check `port` in
+`REPO_ROOT/.pair-review/config.json` then `~/.pair-review/config.json`, then
+give up on write-back for this loop.)
+
+When the server is up, after fixing/dismissing, for each handled finding:
+
+```bash
+curl -s -X POST http://localhost:<port>/api/reviews/<run.review_id>/suggestions/<id>/status \
+  -H 'Content-Type: application/json' -d '{"status": "dismissed"}'
+```
+
+- Only `"dismissed"` and `"active"` are accepted; `"adopted"` is reserved
+  for the human's adopt flow — never send it.
+- Newer servers accept a `reason` field on this endpoint (check
+  `http://localhost:<port>/api.md?reviewId=<reviewId>` if unsure); when
+  supported, include it: `"Fixed in loop round <n>: ..."` or
+  `"Dismissed: <why>"`. Otherwise the fixed-vs-rejected distinction lives in
+  your round log and final report.
+- The human may be triaging in the same UI: before fixing, you may re-check
+  `GET /api/reviews/<reviewId>/suggestions` and skip findings whose status
+  is no longer `active` — the human got there first. Do not resurrect
+  anything the human dismissed.
+- The review URL for your report: `http://localhost:<port>/local/<reviewId>`.
+  Note: the UI does not live-update during CLI runs; results appear on
+  refresh.
+
+No server → skip this entirely; triage lives in the round log and final
+report, and the persisted run history is visible whenever the user next
+starts the server.
+
+## Convergence judgment
+
+You decide each round's directive and whether to continue. Principles:
+
+- **Round 1**: broad. Directive like: "Review these changes thoroughly.
+  Objective: <objective>."
+- **Escalate** back to a broad directive whenever the previous round
+  produced any `critical` finding.
+- **Narrow** as findings shrink. The gate directive:
+  "Final review. Only report blockers — issues that must be fixed before
+  merging. Is this ready to merge?"
+- **The gate uses the same council.** The round that says "merge it" must be
+  just as rigorous as the rounds that found problems. Do not substitute a
+  cheaper configuration for gate rounds.
+- **Continue vs stop**: another round is worth it when the last one caused
+  substantial fixes. When rounds churn the same ground without progress,
+  stop and ask the user instead of grinding the budget.
+- The loop **ends successfully** when a gate round returns **no blockers** —
+  an empty finding list (per hard rule 1). Read the run's `summary` for the
+  reviewer's own answer to the ready-to-merge question and quote it in your
+  report.
+
+## PR mode
+
+The loop also works against a GitHub PR:
+
+```bash
+pair-review <pr-number-or-url> --headless --json [--council <handle>] [--instructions "..."]
+```
+
+This self-bootstraps the PR (fetches metadata, prepares a review worktree)
+and requires a GitHub token in `~/.pair-review/config.json`. The review's
+checkout lives in a pair-review worktree — your fixes belong in whatever
+checkout the user asked you to work in; do not edit the pool worktree.
+Write-back and the review URL work the same way via `run.review_id`.
+`--scope`/`--base` do not apply here — they are local-mode only; a PR review
+always covers the PR's full diff.
+
+## Reporting
+
+Every loop ends with a report containing:
+
+1. **Verdict** — converged (quote the final run's summary) or not converged
+   (why, and what remains).
+2. **Rounds table** — per round: directive, findings found, fixed, dismissed,
+   asked.
+3. **Triage detail** — every dismissed finding with its reason; every fix in
+   one line each.
+4. **The review URL** when a server is up, so the user can inspect
+   everything in the web UI.
+5. Working-tree status reminder: changes are uncommitted, tests run and
+   their result.

package/public/js/components/AdvancedConfigTab.js

@@ -170,7 +170,7 @@ class AdvancedConfigTab {
   /**
    * Set default orchestration provider/model for new councils.
    * Falls back to 'claude'/'sonnet' if not provided.
-   * @param {string} provider - Default provider ID (e.g., 'claude', 'gemini')
+   * @param {string} provider - Default provider ID (e.g., 'claude', 'antigravity')
    * @param {string} model - Default model ID (e.g., 'sonnet', 'opus')
    */
   setDefaultOrchestration(provider, model) {

package/public/js/components/AnalysisConfigModal.js

@@ -627,7 +627,7 @@ class AnalysisConfigModal {
   selectModel(modelId) {
     // Guard: never store a model that doesn't belong to the current provider.
     // Callers can pass a model resolved from a different scope (e.g. 'opus'
-    // while the provider is 'gemini'); fall back to the provider's default so
+    // while the provider is 'antigravity'); fall back to the provider's default so
     // the UI always shows a selected card and submissions carry a valid pair.
     if (modelId && this.models.length && !this.models.some(m => m.id === modelId)) {
       const fallback = this.models.find(m => m.default) || this.models[0];
@@ -952,7 +952,7 @@ class AnalysisConfigModal {
     }
     // Only honour currentModel when it belongs to the selected provider.
     // selectProvider() has already chosen a valid model for the provider (via
-    // tier matching); applying a foreign model here (e.g. 'opus' under 'gemini')
+    // tier matching); applying a foreign model here (e.g. 'opus' under 'antigravity')
     // would leave no model card selected and submit an invalid pair.
     if (options.currentModel && this.models.some(m => m.id === options.currentModel)) {
       this.selectModel(options.currentModel);