@expo/code-review-cli 0.1.0 → 0.2.1

package/README.md

@@ -1,26 +1,115 @@
-# expo-code-review
+# @expo/code-review-cli
 
 A config-driven, multi-agent AI code reviewer. Specialist agents review a diff in
 parallel; a coordinator consolidates their findings into one structured review.
-Runs the same engine locally (advisory) and in CI (posts a PR comment).
+The same engine runs locally (advisory) and in CI (posts one PR comment). The CLI
+is the **engine** — each repo supplies its own agents and settings under
+`.expo-code-review/`, so behavior is configured per-repo, not baked in.
 
-> **Status: experimental.** Phase 1 is **comment-only and non-blocking** — it
-> never blocks a merge and never auto-approves. The package is incubated inside
-> `eas-cli` for fast iteration and is intended to graduate into its own repo; see
-> [`ROADMAP.md`](./ROADMAP.md).
+> **Status: experimental.** Comment-only and non-blocking — it never blocks a merge
+> and never auto-approves. See [`ROADMAP.md`](./ROADMAP.md).
+
+Inspired in part by Cloudflare's [_How we built our AI code review bot_](https://blog.cloudflare.com/ai-code-review/).
+
+```mermaid
+flowchart TD
+  SRC["Source<br/>local git · GitHub PR (gh)"] --> FILTER["Noise filter<br/>drop lockfiles · generated · binary"]
+  FILTER --> CHUNK["Chunk<br/>by changed lines (large diffs only)"]
+  CHUNK --> AGENTS["Agents (parallel)<br/>each .md in agents/ · read·grep·glob·list"]
+  CHUNK --> XCUT["Cross-cutting pass<br/>multi-file issues (large diffs)"]
+  AGENTS --> COORD["Coordinator<br/>dedupe · re-judge · decide"]
+  XCUT --> COORD
+  COORD --> VERIFY["Verify<br/>quote-ground · adversarially verify criticals"]
+  VERIFY --> REPORT["Reporter<br/>one PR comment (CI) · terminal (local)"]
+```
 
-The CLI is the **engine**. Each repo supplies its own agents and settings under
-`.expo-code-review/`, so behavior is configured per-repo, not baked in.
+## Usage
+
+Run via `npx @expo/code-review-cli <command>` (or the `ecr` / `expo-code-review`
+binary once installed).
+
+Reviewing a PR (`--pr`/`ci`) needs the GitHub CLI — `brew install gh && gh auth login`.
+Everything else the reviewer needs (including the `opencode` runtime) ships with the
+package.
+
+### First-time setup
+
+Scaffold, add credentials, verify.
+
+```bash
+# Scaffold .expo-code-review/ + a CI workflow (--no-workflow to skip)
+npx @expo/code-review-cli init
+```
 
-## How it works
+Then give it model credentials. **Recommended: a Claude Pro/Max subscription** — the
+scaffolded config uses OAuth by default, so just mint a token and export it under the
+env var your `config.jsonc`'s `auth.tokenEnv` names:
 
+```bash
+# Mint a Claude Pro/Max token (prints an sk-ant-oat… token)
+claude setup-token
+# Export it under the env var your config.jsonc's auth.tokenEnv names
+export ANTHROPIC_OAUTH_API_KEY=sk-ant-oat...
+# Check env, config, and credentials
+npx @expo/code-review-cli doctor
 ```
-diff source ─▶ noise filter ─▶ chunk ─▶ agents (parallel) ─▶ coordinator ─▶ reporter
-(git / gh)     drop lockfiles,  by       each agent reviews    dedupe,        one PR comment
-               generated,       changed  every chunk +         re-judge,      (CI) or terminal
-               binary files     lines    a cross-cutting pass   decide         output (local)
+
+Prefer an Anthropic **API key**, or **OpenAI/GPT** or another provider? See
+[Other providers & auth modes](#other-providers) at the bottom.
+
+### Reviewing (already configured)
+
+```bash
+# Review working-tree changes; prints here, posts nothing
+ecr review
+# Review a GitHub PR by number (preview only)
+ecr review --pr 4057
+# …and post it as the PR comment
+ecr review --pr 4057 --post
 ```
 
+Options (most to least common):
+
+| Flag | What it does |
+| --- | --- |
+| `--pr <n>` | Review GitHub PR #n by number (diff fetched via `gh`, no checkout); not combinable with `--base`/`--head`/`--staged`. |
+| `--post` | With `--pr`, also post the result as the PR comment (needs `gh` auth). Omit to preview only; re-run with `--post` to publish. |
+| `--staged` | Review only staged changes. |
+| `--base <ref>` | Base ref to diff against (default: merge-base with the default branch). |
+| `--head <ref>` | Head ref to diff (default: working tree, incl. uncommitted changes). |
+| `--agents <a,b>` | Run only these agents (comma-separated ids); default: all. |
+| `--route` | Let an LLM router pick the relevant agents from the diff. |
+| `--repo <owner/repo>` | Repo for `--pr` (default: inferred from the current checkout). |
+| `--json` | Emit machine-readable JSON on stdout. |
+| `--no-fail` | Always exit 0 (otherwise a `request_changes` decision exits non-zero). |
+| `-h`, `--help` | Show help. |
+
+`--pr` uses the PR's diff (authoritative) but reads your checked-out files for
+surrounding context; for full fidelity, `gh pr checkout <n>` first and run a plain
+`ecr review`.
+
+In CI it runs automatically from the scaffolded workflows — by label or a `/review`
+comment (see **CI usage**). From Claude Code (or another agent), add a slash command
+that runs it; eas-cli's
+[`/expo-review`](https://github.com/expo/eas-cli/blob/main/.claude/commands/expo-review.md)
+is a ready example to adapt.
+
+### Command reference
+
+| Command | What it does |
+| --- | --- |
+| `ecr init [--no-workflow] [--force]` | Scaffold `.expo-code-review/` (config, agents, prompts) + a CI workflow. |
+| `ecr review [options]` | Review local changes and print an advisory review (default command). |
+| `ecr ci` | Review the current GitHub PR and post/update a comment. For GitHub Actions. |
+| `ecr doctor` | Check environment, config, and model credentials. |
+
+(When developing this repo itself, use `bun run src/cli.ts <command>`.)
+
+---
+
+<details>
+<summary><b>How it works</b></summary>
+
 - **Source** — local git (working tree, staged, or a ref range) or a GitHub PR
   (diff + metadata fetched over the `gh` API).
 - **Noise filter** — drops lockfiles, generated bundles/maps, snapshots, files
@@ -33,6 +122,8 @@ diff source ─▶ noise filter ─▶ chunk ─▶ agents (parallel) ─▶ coo
   run in parallel with read-only repo tools (`read`/`grep`/`glob`/`list`).
 - **Coordinator** — a single pass that dedupes, re-judges severity, and produces
   the final `{ decision, findings, summary }`.
+- **Verify** — quote-grounds every finding against the real file and adversarially
+  verifies criticals, so a confident-but-wrong finding doesn't ship.
 - **Reporter** — posts/updates a single fingerprinted PR comment (CI), or prints
   a grouped summary (local). Findings below the configured severity floor are
   suppressed.
@@ -40,48 +131,10 @@ diff source ─▶ noise filter ─▶ chunk ─▶ agents (parallel) ─▶ coo
 Built on the [OpenCode](https://opencode.ai) SDK, which spawns the model provider
 and applies Anthropic prompt caching automatically.
 
-## Commands
+</details>
 
-Run via the workspace during incubation (`yarn workspace expo-code-review dev …`),
-or as the `ecr` / `expo-code-review` binary once built/installed.
-
-| Command | What it does |
-| --- | --- |
-| `ecr review [options]` | Review local changes and print an advisory review (default command). |
-| `ecr ci` | Review the current GitHub PR and post/update a comment. For GitHub Actions. |
-| `ecr init [--with-workflow] [--force]` | Scaffold `.expo-code-review/` (config, agents, prompts) in this repo. |
-| `ecr doctor` | Check environment, config, and model credentials. |
-
-### `ecr review` options
-
-```
---base <ref>       Base ref to diff against (default: merge-base with default branch)
---head <ref>       Head ref to diff (default: working tree, incl. uncommitted changes)
---staged           Review only staged changes
---pr <n>           Review GitHub PR #n by number (diff fetched via gh, no checkout);
-                   not combinable with --base/--head/--staged
---repo <owner/repo>  Repo for --pr (default: inferred from the current checkout)
---post             With --pr: also post the result as the PR comment (needs gh auth).
-                   Omit to preview only; re-run with --post to publish.
---agents <a,b>     Run only these agents (comma-separated ids); default: all
---route            Let an LLM router pick the relevant agents from the diff
---json             Emit machine-readable JSON on stdout
---no-fail          Always exit 0 (otherwise a request_changes decision exits non-zero)
--h, --help         Show help
-```
-
-Reviewing a PR without checking it out — preview, then optionally post:
-
-```bash
-ecr review --pr 4057            # print the review here; posts nothing
-ecr review --pr 4057 --post     # re-run and post it as the PR comment
-```
-
-`--pr` uses the PR's diff (authoritative) but reads your checked-out files for
-surrounding context; for full fidelity, `gh pr checkout <n>` first and run a plain
-`ecr review`.
-
-## Configuration — `.expo-code-review/`
+<details>
+<summary><b>Configuration — <code>.expo-code-review/</code></b></summary>
 
 ```
 .expo-code-review/
@@ -101,14 +154,19 @@ surrounding context; for full fidelity, `gh pr checkout <n>` first and run a pla
 ---
 description: One line the router uses to decide relevance.
 alwaysRun: true        # run even when the router would skip this agent
-model: anthropic/claude-sonnet-5     # override the default model (e.g. haiku for the coordinator)
+model: anthropic/claude-sonnet-5     # override the default model
 temperature: 0.1
 ---
 
 # Agent instructions in Markdown…
 ```
 
-### `config.jsonc`
+For a real-world example, see eas-cli's
+[`.expo-code-review/`](https://github.com/expo/eas-cli/tree/main/.expo-code-review)
+— correctness/security/consistency agents, Opus for security + the coordinator, and
+per-repo `noise.additionalIgnores`.
+
+`config.jsonc` (JSONC — comments + trailing commas supported):
 
 ```jsonc
 {
@@ -119,142 +177,115 @@ temperature: 0.1
   "breakGlass": { "marker": "/skip-review" }, // PR body marker that skips the review
   "commentTag": "expo-ai-code-reviewer",      // hidden tag used to find/update the comment
   "auth": { "mode": "oauth", "provider": "anthropic",
-            "tokenEnv": "DO_NOT_USE_EXPERIMENTAL_ANTHROPIC_API_KEY" }
+            "tokenEnv": "ANTHROPIC_OAUTH_API_KEY" }
 }
 ```
 
-JSONC (comments + trailing commas) is supported.
-
-## Authentication
-
-Model credentials come from OpenCode. Two modes, set in `config.auth`:
-
-- **`api-key`** — the token in `tokenEnv` is copied into the provider's API-key
-  env var (e.g. `ANTHROPIC_API_KEY`).
-- **`oauth`** — a Claude Pro/Max token (from `claude setup-token`, an
-  `sk-ant-oat…` token, *not* an x-api-key) is written into an isolated OpenCode
-  `auth.json` as a bearer credential, so it uses the native subscription path.
-
-Set **`REVIEWER_MODEL`** to override the model for every agent and use your own
-OpenCode login instead of the repo's configured credentials — handy locally
-(e.g. `REVIEWER_MODEL=openai/gpt-5.4-mini-fast`). There is no shared fallback key;
-if a run fails for lack of credentials, authenticate a provider in OpenCode.
+</details>
 
-Run `ecr doctor` to diagnose setup.
+<details>
+<summary><b>Model selection</b></summary>
 
-## Model selection
+Precedence: **`REVIEWER_MODEL` env** (global override) → per-file **frontmatter
+`model:`** → **`config.jsonc` `model`** (the default). So a repo can run a mixed
+setup, and a developer can override everything locally.
 
-Models are resolved with this precedence: **`REVIEWER_MODEL` env** (global override)
-→ per-file **frontmatter `model:`** → **`config.jsonc` `model`** (the default). So a
-repo can run a mixed setup, and a developer can override everything locally.
-
-Rules of thumb for the reviewer's workload:
-
-- **Specialist agents** (correctness/security/consistency) do the real bug-finding
-  and benefit from a reasoning-tier model — **Sonnet** is the quality/speed sweet
-  spot (the default for correctness/consistency). **Opus** finds more but is slower
-  and more rate-limited, which makes large-PR timeouts worse — so scope it to the
-  one agent where the extra threat-model reasoning pays off most: **security runs on
-  Opus** (set in `security.md` frontmatter), the rest on Sonnet. This keeps the
-  latency/rate-limit cost to a single agent, and the timeout handling (subdivide +
-  per-fetch deadline) keeps a slow Opus pass from hanging the run.
-- **The coordinator** only consolidates text (no repo tools), so a fast, cheap
-  model — **Haiku** — fits well and keeps the serial tail short. Set it in
-  `coordinator.md` frontmatter.
+- **Specialist agents** (correctness/security/consistency) benefit from a
+  reasoning-tier model — **Sonnet** is the quality/speed sweet spot (default for
+  correctness/consistency). **Opus** finds more but is slower and more
+  rate-limited, so scope it to the highest-stakes agent: **security runs on Opus**
+  (set in `security.md` frontmatter), the rest on Sonnet.
+- **The coordinator** makes the final call (dedupe / re-judge / decide) — worth a
+  strong model; set it in `coordinator.md` frontmatter.
 - If latency/timeouts dominate on big PRs, moving the specialists to a faster model
   is the most direct lever (a real recall tradeoff — measure it).
 
-Example mixed setup:
-
-```jsonc
-// config.jsonc
-"model": "anthropic/claude-sonnet-5"        // default: specialists + cross-file pass
-```
-```markdown
-<!-- security.md frontmatter -->  → Opus for the highest-stakes agent
----
-model: anthropic/claude-opus-4-8
----
-
-<!-- coordinator.md frontmatter --> → Haiku for the text-only consolidation
----
-model: anthropic/claude-haiku-4-5-20251001
----
-```
-
 There is no automatic cross-provider "equivalent" fallback — that would silently
 change which model reviewed your code. Use an explicit override instead.
 
-## Reliability
+</details>
 
-A review must never hang, silently produce nothing, or present an unreviewed
-change as "looks good":
+<details>
+<summary><b>Reliability</b> — never hangs, never silently drops work</summary>
 
-- **Per-task time caps** — focused chunk passes get 15 min; the cross-cutting pass
-  gets 25 min; the coordinator gets 10 min. A global passes budget (32 min) bounds
-  all passes incl. the subdivision waves below, so everything fits inside the CI
-  job's `timeout-minutes` (60), since the coordinator + verification run afterward.
+- **Per-task time caps** — chunk passes 15 min; cross-cutting 25 min; coordinator
+  10 min. A global passes budget (32 min) bounds all passes incl. the subdivision
+  waves, fitting inside the CI job's `timeout-minutes` (60).
 - **Tool-call cap** — a pass that makes too many `read`/`grep` calls without
-  finishing is *wandering*, not converging (the usual cause of a non-convergent
-  timeout). Hitting the cap trips the same soft landing as the time cap.
+  finishing is *wandering*, not converging; hitting the cap trips the soft landing.
 - **Soft landing on timeout** — at either cap, the run is interrupted and the agent
   is asked to return the findings it already has, rather than discarding its work.
-- **Subdivide-on-timeout — the reviewer never silently drops work.** If a pass
-  times out with nothing to show, its chunk is split in half and the halves are
-  re-reviewed (recursively, down to a single file). A chunk that won't converge at
-  13 files almost always converges at 6. If even a single file won't converge, a
-  fast **no-tools fallback** reviews just its inlined diff (a lighter review, but
-  never nothing). Only if *that* can't finish inside the budget is a coverage gap
-  reported — and it is always reported, never silent.
+- **Subdivide-on-timeout** — a pass that times out with nothing to show has its
+  chunk split in half and the halves re-reviewed (recursively, down to a single
+  file), then a fast **no-tools fallback** over the inlined diff. Only a genuinely
+  un-reducible pass reports a coverage gap — and it is always reported, never silent.
 - **Parse failures are retried** (same session, then once in a bounded fresh
-  session); that is separate from the timeout path above.
-- **A failed run never reads as "Approve"** — if every pass fails, the review says
-  it could not complete (treat as unreviewed); if some passes fail, the decision
-  is never a clean approve, and the coordinator is told coverage was reduced.
-- **The coordinator can't sink the run** — if the consolidation step fails, findings
-  are merged deterministically and still posted, rather than thrown away.
-- **Coverage notes** — passes that timed out or failed are listed so a real
-  coverage gap is never silent (routine noise filtering is *not* flagged — it's
-  expected and stays in the run log).
-- **CI always gets a terminal state** — on any failure the PR gets a comment saying
-  the reviewer didn't run, not a stuck reaction and silence.
-
-## CI usage
-
-`ecr init --with-workflow` scaffolds a `pull_request` workflow. In this repo the
-reviewer runs via two workflows, split along a clean line: **comments = one-shot
-actions, labels = persistent configuration.**
-
-- **`expo-code-review-command.yml`** — one-shot `/review` comments (maintainers):
-  - `/review` — run once now; the router picks the agents
-  - `/review all` — run once with every agent
-  - `/review correctness security` — run once with just those agents
-
-  These never change configuration.
-- **`expo-code-review.yml`** — continuous review, configured by **labels**:
-  - `ai-review` — auto-review every push; the router picks the agents
-  - `ai-review:all` — auto-review with every agent
-  - `ai-review:<agent>` — auto-review with only those agents (e.g.
-    `ai-review:security`); combine several to widen the set
-  - `ai-review:skip` — never auto-review this PR (opt-out)
-- **`expo-code-review-dismiss.yml`** — dismiss/restore a finding on a PR (maintainers):
-  - `/dismiss <id> [<id> …] [-- reason]` — hide finding(s); they move to a collapsed
-    "Dismissed" section and stay dismissed across re-reviews
-  - `/undismiss <id> …` — restore them
-
-  Each finding shows a short `` `id:…` `` in the comment. Dismissal is a **display
-  filter only** — the reviewer still analyzes the code every run, and a `critical`
-  or `secrets` finding can never be hidden this way. (Also: an inline
-  `expo-code-review-ignore` comment on/above a line suppresses that line's findings,
-  same critical/secrets carve-out.)
-
-These workflows are comment-only (they never fail the PR's checks). For security,
-they build/run only the trusted base ref (never the PR head) — see the comment at
-the top of each file.
-
-## Run logs
+  session) — separate from the timeout path.
+- **A failed run never reads as "Approve"** — all passes fail → "could not
+  complete"; some fail → never a clean approve, and coverage-reduced.
+- **The coordinator can't sink the run** — if consolidation fails, findings are
+  merged deterministically and still posted.
+- **Coverage notes** — passes that timed out/failed are listed (routine noise
+  filtering is *not* flagged — it's expected and stays in the run log).
+- **CI always gets a terminal state** — on any failure the PR gets a "didn't run"
+  comment, not a stuck reaction and silence.
+
+</details>
+
+<details>
+<summary><b>CI usage</b></summary>
+
+`ecr init --with-workflow` scaffolds a `pull_request` workflow. Split along a clean
+line: **comments = one-shot actions, labels = persistent configuration.**
+
+- **command workflow** — one-shot `/review` comments (maintainers): `/review`
+  (router picks agents), `/review all`, `/review correctness security`. Never
+  changes configuration.
+- **auto workflow** — continuous review, configured by **labels**: `ai-review`
+  (router), `ai-review:all`, `ai-review:<agent>` (e.g. `ai-review:security`;
+  combine to widen), `ai-review:skip` (opt-out).
+- **dismiss workflow** — `/dismiss <id> [… -- reason]` / `/undismiss <id>`
+  (maintainers). Each finding shows a short `` `id:…` ``. Dismissal is a **display
+  filter only** — the reviewer still analyzes everything, and a `critical`/`secrets`
+  finding can never be hidden. (An inline `expo-code-review-ignore` comment on/above
+  a line does the same, with the same critical/secrets carve-out.)
+
+These workflows are comment-only (they never fail the PR's checks). The engine runs
+as the published package via `npx`, so no PR-controlled code is built.
+
+</details>
+
+<details>
+<summary><b>Run logs</b></summary>
 
 Each run appends a JSON line to `.expo-code-review/.runs/reviews.jsonl` with the
 inputs, decision, finding count, duration, per-agent cost, and aggregate token
-usage (including prompt-cache read/write counts) — for auditing and measuring
+usage (incl. prompt-cache read/write counts) — for auditing and measuring
 cost/latency/cache reuse over time.
+
+</details>
+
+<a id="other-providers"></a>
+<details>
+<summary><b>Other providers & auth modes</b></summary>
+
+The recommended setup is a Claude Pro/Max subscription (OAuth) — see Usage above.
+Alternatives, all set in `config.auth` (credentials come from OpenCode):
+
+- **Anthropic API key** — set `auth.mode` to `"api-key"` and point `tokenEnv` at the
+  env var holding the key (e.g. `ANTHROPIC_API_KEY`); it's sent as `x-api-key`. Omit
+  the `auth` block entirely to fall back to OpenCode's own login / `ANTHROPIC_API_KEY`.
+- **OAuth (Pro/Max)** — `tokenEnv` holds an `sk-ant-oat…` token from
+  `claude setup-token` (*not* an x-api-key); it's written to an isolated OpenCode
+  `auth.json` as a bearer credential, using the native subscription path.
+- **OpenAI / GPT, or another provider** — the current path is the `REVIEWER_MODEL`
+  env override: `opencode auth login` once (pick the provider), then run with
+  e.g. `REVIEWER_MODEL=openai/gpt-5.4-mini-fast`. It overrides every agent's model
+  and uses your OpenCode login, so no `auth` block is needed. *(First-class
+  per-provider config — Anthropic/OpenAI/others in `config.jsonc`, and mixing them
+  per agent — is on the [roadmap](./ROADMAP.md).)*
+
+There is no shared fallback key; if a run fails for lack of credentials, authenticate
+a provider in OpenCode. `ecr doctor` diagnoses setup.
+
+</details>

package/build/commands/init.js

@@ -9,12 +9,12 @@ const TEMPLATES_DIR = fileURLToPath(new URL('../../templates/', import.meta.url)
 const USAGE = `ecr init — scaffold .expo-code-review/ in the current repo
 
 Usage:
-  ecr init [--with-workflow] [--force]
+  ecr init [--no-workflow] [--force]
 
 Options:
-  --with-workflow   Also write .github/workflows/expo-code-review.yml
-  --force           Overwrite existing files
-  -h, --help        Show this help
+  --no-workflow   Skip writing the CI workflow (.github/workflows/expo-code-review.yml)
+  --force         Overwrite existing files
+  -h, --help      Show this help
 `;
 export async function initCommand(argv) {
     if (argv.includes('-h') || argv.includes('--help')) {
@@ -32,7 +32,10 @@ export async function initCommand(argv) {
 /** Scaffold .expo-code-review/ (and optionally the CI workflow) into the repo. */
 async function scaffold(argv) {
     const force = argv.includes('--force');
-    const withWorkflow = argv.includes('--with-workflow');
+    // The CI workflow is scaffolded by default (most repos adopting this want it);
+    // `--no-workflow` opts out. `--with-workflow` is still accepted as a no-op for
+    // back-compat.
+    const withWorkflow = !argv.includes('--no-workflow');
     const root = (await repoRoot()) ?? process.cwd();
     const configDir = path.join(root, CONFIG_DIRNAME);
     // Create only the config dir; let copyInto create prompts/ so it reports
@@ -70,8 +73,8 @@ async function scaffold(argv) {
         '  2. Configure a model provider in OpenCode (or set REVIEWER_MODEL).',
         '  3. Run `ecr doctor`, then `ecr review`.',
         withWorkflow
-            ? '  4. Add the model-key secret referenced by the workflow.'
-            : '  4. Run `ecr init --with-workflow` to add the CI workflow.',
+            ? '  4. Add the model-key secret referenced by the workflow, then add an `ai-review` label to a PR.'
+            : '  4. (No CI workflow written — re-run without `--no-workflow` to add it.)',
         '',
     ].join('\n'));
 }

package/build/core/prompts.js

@@ -182,25 +182,34 @@ export function buildCrossCuttingTask(allFiles, filtered = []) {
 export function buildVerifierSystem() {
     return [
         'You are a skeptical verifier of a single code-review finding. Your default is',
-        'DISTRUST. Using your read/grep tools, open the cited file, locate the code, and',
-        'confirm the finding against what the source ACTUALLY says.',
+        'DISTRUST. Using your read/grep tools, open the cited file (search nearby files',
+        'if the code is not exactly there), locate the relevant code, and judge whether',
+        'the described PROBLEM is actually present in the source.',
+        '',
+        'Judge the SUBSTANCE, not the wording. The finding\'s quoted "evidence" may be',
+        'paraphrased, abbreviated, quoted across non-adjacent lines, or slightly',
+        'misquoted, and its file/line may be approximate. None of that alone makes the',
+        'finding false — verify against what the code actually does. Do NOT reject merely',
+        'because the quoted snippet is not a verbatim match; reject only if the',
+        'underlying problem is not real.',
         '',
         'Mark verified=false (reject) if any of these hold:',
-        '- the code the finding describes or quotes is not actually present as claimed',
-        '  (it misread or invented the code),',
-        '- the described failure/exploit cannot actually occur,',
+        '- the described problem does not actually occur in the code (it misread or',
+        '  invented the behavior),',
+        '- the described failure/exploit cannot actually happen,',
         "- the claim is internally contradictory (e.g. asserts a type error in code that",
         '  compiles), or',
-        '- you cannot substantiate it after reading the file.',
+        '- you cannot substantiate the underlying issue after reading the file.',
         '',
-        'Only mark verified=true when you have CONFIRMED, from the real source, that the',
-        'flagged code exists as described and the problem is genuine. When unsure, reject.',
+        'Mark verified=true when you have CONFIRMED, from the real source, that the',
+        'described problem genuinely exists. When genuinely unsure whether it is real,',
+        'reject.',
         '',
         'Return ONLY this JSON object and nothing else:',
         '{"verified": true|false, "reason": "one concise sentence grounded in the file"}',
     ].join('\n');
 }
-export function buildVerifierTask(finding) {
+export function buildVerifierTask(finding, opts = {}) {
     const lines = [
         'Verify this finding by reading the real source (do not trust its wording):',
         '',
@@ -214,6 +223,9 @@ export function buildVerifierTask(finding) {
     if (finding.evidence) {
         lines.push('- code the finding claims is present (UNTRUSTED — verify it against the file):', '<<<EVIDENCE', finding.evidence, 'EVIDENCE');
     }
+    if (opts.evidenceUngrounded) {
+        lines.push('', 'NOTE: the quoted evidence could NOT be located verbatim in the file. It may be', 'a paraphrase, an elision, or a slightly wrong location — do not reject on that', 'basis alone. Read the file (and nearby files) and judge whether the described', 'problem is genuinely present.');
+    }
     lines.push('', 'Open the file, find the relevant code, and return the single verdict JSON object.');
     return lines.join('\n');
 }

package/build/core/verify.js

@@ -10,16 +10,46 @@ const VERIFY_TIMEOUT_MS = 3 * 60 * 1000;
 // Evidence shorter than this (normalized) is too weak to conclude "hallucinated".
 const MIN_EVIDENCE_LEN = 12;
 /**
- * Deterministic quote-grounding: does the finding's `evidence` snippet actually
- * appear in the file? Returns `unknown` (don't judge) when there's too little
- * evidence or the file can't be read (e.g. a base-ref checkout that lacks a
- * PR-added file), so we never drop a finding we couldn't actually check.
+ * Break `evidence` into normalized, substantive fragments for fuzzy matching:
+ * split on newlines AND ellipses (the model often elides with `…`/`...`), strip
+ * leading diff markers (`+`/`-`) and comment markers (`//`, `#`, `*`) it may have
+ * copied along, normalize, and keep only fragments long enough to be meaningful.
  */
-async function evidencePresence(finding, cwd) {
-    const evidence = normalizeCode(finding.evidence ?? '');
-    if (evidence.length < MIN_EVIDENCE_LEN) {
+export function evidenceFragments(evidence) {
+    return evidence
+        .split(/\r?\n|…|\.\.\./)
+        .map(line => line.replace(/^[+\-\s]*/, '').replace(/^(\/\/+|#+|\*+|\/\*)\s?/, ''))
+        .map(normalizeCode)
+        .filter(fragment => fragment.length >= MIN_EVIDENCE_LEN);
+}
+/**
+ * Does the finding's `evidence` correspond to code in the file?
+ *  - exact (whitespace-normalized) substring → 'present'
+ *  - else any substantive line/fragment present verbatim → 'present' (fuzzy: this
+ *    rescues cross-line quotes, ellipsis elisions, and copied comment/diff markers)
+ *  - a real quote that matches nothing → 'absent'
+ * Returns 'unknown' (don't judge) when evidence is too short to conclude anything
+ * or the file can't be read, so we never drop a finding we couldn't actually check.
+ * NOTE: 'absent' is NOT terminal — the caller escalates it to the LLM verifier
+ * rather than dropping, because an imperfect quote does not mean a false finding.
+ */
+export function matchEvidence(evidence, content) {
+    const normEvidence = normalizeCode(evidence);
+    if (normEvidence.length < MIN_EVIDENCE_LEN) {
+        return 'unknown';
+    }
+    const normContent = normalizeCode(content);
+    if (normContent.includes(normEvidence)) {
+        return 'present';
+    }
+    const fragments = evidenceFragments(evidence);
+    if (fragments.length === 0) {
         return 'unknown';
     }
+    return fragments.some(fragment => normContent.includes(fragment)) ? 'present' : 'absent';
+}
+/** Read the cited file and grade the evidence against it (see matchEvidence). */
+async function evidencePresence(finding, cwd) {
     let content;
     try {
         content = await readFile(path.resolve(cwd, finding.file), 'utf8');
@@ -27,67 +57,73 @@ async function evidencePresence(finding, cwd) {
     catch {
         return 'unknown';
     }
-    return normalizeCode(content).includes(evidence) ? 'present' : 'absent';
+    return matchEvidence(finding.evidence ?? '', content);
 }
 /**
- * Guard against hallucinated findings before they're surfaced:
- *  1. Quote-grounding (deterministic, all findings): drop any whose quoted
- *     `evidence` is definitively not in the file.
- *  2. Adversarial verify (LLM, criticals only): a skeptical pass re-reads the real
- *     file and must confirm the critical is genuine; refuted criticals are dropped.
- * Fails OPEN — if a verify call itself errors, the critical is kept (better a
- * possible false positive than hiding a real critical on an infra hiccup).
+ * Guard against hallucinated findings before they're surfaced, WITHOUT silently
+ * dropping real ones on an imperfect quote:
+ *  1. Quote-grounding (deterministic, all findings): grade each finding's `evidence`
+ *     against the file (exact + fuzzy — see matchEvidence).
+ *  2. LLM verify (adversarial, in parallel) runs for a finding when EITHER:
+ *       - its evidence is `absent` (any severity) — the quote isn't grounded, but
+ *         that alone doesn't make the finding false, so the verifier re-reads the
+ *         real file (and nearby files) and judges the underlying problem; or
+ *       - it's a `critical` (even if grounded) — a skeptical double-check.
+ *     A finding is dropped ONLY when the verifier refutes it. `present`/`unknown`
+ *     non-criticals are kept without an LLM call (the fast, cheap path).
+ * Fails OPEN — if a verify call itself errors, the finding is kept (better a
+ * possible false positive than hiding a real finding on an infra hiccup).
+ *
+ * This replaces the old "absent evidence → hard drop" rule, which was suppressing
+ * real findings whose natural evidence (a structural/absence bug, a cross-line
+ * quote, a slightly-wrong location) wasn't a verbatim substring.
  */
 export async function verifyFindings(handle, findings, cwd, onProgress) {
     const dropped = [];
     let cost = 0;
     const tokens = {};
-    // Phase 1 — quote-grounding for every finding.
+    // Phase 1 — deterministic quote-grounding for every finding.
     const checked = await Promise.all(findings.map(async (finding) => ({ finding, presence: await evidencePresence(finding, cwd) })));
-    const survivors = [];
+    // Decide which findings need an LLM check vs. can be kept directly.
+    const verdicts = new Map();
+    const toVerify = [];
     for (const { finding, presence } of checked) {
-        if (presence === 'absent') {
-            dropped.push({ finding, reason: 'quoted code not found in file (likely hallucinated)' });
-            onProgress?.(`  verify: dropped ${finding.severity} "${finding.title}" — quoted code not in ${finding.file}`);
+        if (presence === 'absent' || finding.severity === 'critical') {
+            toVerify.push({ finding, presence });
         }
         else {
-            survivors.push(finding);
+            verdicts.set(finding, 'keep'); // grounded (or uncheckable) non-critical
         }
     }
-    // Phase 2 — adversarial verify for surviving criticals, in parallel.
-    const refuted = new Set();
-    await Promise.all(survivors
-        .filter(finding => finding.severity === 'critical')
-        .map(async (finding, index) => {
+    // Phase 2 — LLM verify (parallel). Refuted → drop; verified or errored → keep.
+    await Promise.all(toVerify.map(async ({ finding, presence }, index) => {
         try {
             const { value, cost: verifyCost, tokens: verifyTokens } = await promptAndParse(handle, {
                 agent: VERIFIER_AGENT,
                 system: buildVerifierSystem(),
-                text: buildVerifierTask(finding),
+                text: buildVerifierTask(finding, { evidenceUngrounded: presence === 'absent' }),
                 title: `verify-${index}`,
                 maxWaitMs: VERIFY_TIMEOUT_MS,
                 finalizeOnTimeout: true,
             }, parseVerdict);
             cost += verifyCost;
             addTokenUsage(tokens, verifyTokens);
-            if (!value.verified) {
-                refuted.add(finding);
-                onProgress?.(`  verify: dropped critical "${finding.title}" — ${value.reason || 'refuted by verifier'}`);
+            if (value.verified) {
+                verdicts.set(finding, 'keep');
+            }
+            else {
+                verdicts.set(finding, 'drop');
+                dropped.push({ finding, reason: value.reason || 'refuted by verifier' });
+                onProgress?.(`  verify: dropped ${finding.severity} "${finding.title}" — ${value.reason || 'refuted by verifier'}`);
             }
         }
         catch (error) {
-            // Fail open: keep the critical if verification itself failed.
-            onProgress?.(`  verify: could not verify critical "${finding.title}" (${errorMessage(error)}); keeping it`);
+            // Fail open: keep the finding if verification itself failed.
+            verdicts.set(finding, 'keep');
+            onProgress?.(`  verify: could not verify "${finding.title}" (${errorMessage(error)}); keeping it`);
         }
     }));
-    const kept = [];
-    for (const finding of survivors) {
-        if (refuted.has(finding)) {
-            dropped.push({ finding, reason: 'refuted by verifier' });
-        }
-        else {
-            kept.push(finding);
-        }
-    }
+    // Preserve original order.
+    const kept = findings.filter(finding => verdicts.get(finding) === 'keep');
     return { kept, dropped, cost, tokens };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expo/code-review-cli",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Generic, config-driven AI code reviewer engine. Repos supply their agents via .expo-code-review/.",
   "license": "MIT",
   "repository": {
@@ -28,6 +28,7 @@
     "typecheck": "tsc --noEmit",
     "dev": "bun run src/cli.ts",
     "test:unit": "bun test",
+    "release": "bash scripts/release.sh",
     "prepublishOnly": "rimraf build && tsc -p tsconfig.build.json"
   },
   "dependencies": {

package/templates/config.jsonc

@@ -31,14 +31,16 @@
   // HTML marker used to find + update the single PR comment. Keep it stable.
   "commentTag": "expo-ai-code-reviewer",
 
-  // How model credentials are provided.
-  //   "api-key": tokenEnv holds a provider API key (sent as x-api-key). If you
-  //              omit `auth`, OpenCode's own login / ANTHROPIC_API_KEY is used.
+  // How model credentials are provided. Default: a Claude Pro/Max subscription.
   //   "oauth":   tokenEnv holds a Claude Pro/Max OAuth token (from
   //              `claude setup-token`); it's injected as a bearer credential.
+  //   "api-key": tokenEnv holds a provider API key (sent as x-api-key). If you
+  //              omit `auth`, OpenCode's own login / ANTHROPIC_API_KEY is used.
+  // For OpenAI/GPT or another provider, omit `auth` and set REVIEWER_MODEL after an
+  // `opencode auth login` for that provider.
   "auth": {
-    "mode": "api-key",
+    "mode": "oauth",
     "provider": "anthropic",
-    "tokenEnv": "ANTHROPIC_API_KEY"
+    "tokenEnv": "ANTHROPIC_OAUTH_API_KEY"
   }
 }

package/templates/shared.md

@@ -65,7 +65,7 @@ Return **only** a single fenced ```json code block, an object of this shape:
       "line": 142,
       "title": "short one-line summary",
       "rationale": "why this is a problem, with the concrete failure/exploit path",
-      "evidence": "the exact line(s) of code you are flagging, copied VERBATIM",
+      "evidence": "one contiguous line of the flagged code, copied VERBATIM",
       "suggestion": "optional concrete fix, or omit"
     }
   ]
@@ -73,7 +73,9 @@ Return **only** a single fenced ```json code block, an object of this shape:
 ```
 
 `line` is the start line in the new version of the file, or `null` if not
-line-specific. `evidence` MUST be the flagged code copied **verbatim** from the
-file — it is used to verify the finding, and a finding whose evidence isn't found
-in the file is discarded (don't paraphrase or invent it). If you have nothing to
-report, return `{ "findings": [] }`. Emit no prose outside the JSON block.
+line-specific. `evidence` is used to help verify the finding, so make it easy to
+locate: copy **one contiguous line** of the flagged code **verbatim** (not spanning
+multiple lines, no `…` elisions, no paraphrasing). For a structural/"missing" issue,
+quote the single most relevant real line (e.g. the early `return` that skips the
+handling). If you have nothing to report, return `{ "findings": [] }`. Emit no prose
+outside the JSON block.

package/templates/workflow.yml

@@ -2,12 +2,13 @@ name: AI code review
 
 on:
   pull_request:
-    types: [opened, synchronize, reopened]
+    types: [opened, synchronize, reopened, labeled, unlabeled]
 
-# Comment-only: needs to read the repo and write PR comments.
+# Comment-only: read the repo, write PR comments (issue comments API).
 permissions:
   contents: read
   pull-requests: write
+  issues: write
 
 concurrency:
   group: ai-code-review-${{ github.event.pull_request.number }}
@@ -16,28 +17,53 @@ concurrency:
 jobs:
   review:
     runs-on: ubuntu-latest
+    # Opt-in per PR: only run when the `ai-review` label is present. Remove this
+    # line to review every PR automatically.
+    if: contains(join(github.event.pull_request.labels.*.name, ','), 'ai-review')
+    # Backstop so a stalled review fails fast instead of hanging.
+    timeout-minutes: 60
     # A reviewer failure must never fail the PR's checks.
     continue-on-error: true
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
         with:
-          fetch-depth: 0
+          # Shallow is enough — the reviewer gets the diff from the API (`gh`).
+          fetch-depth: 1
 
-      - uses: actions/setup-node@v4
+      # SECURITY: this workflow checks out the PR's code, including
+      # .expo-code-review/config.jsonc, whose auth.tokenEnv names the env var the CLI
+      # forwards as the model credential. Refuse to run unless it's the expected value
+      # (below / repo var ECR_EXPECTED_TOKEN_ENV) so a PR can't repoint it at another
+      # secret in the runner. Keep this in sync with auth.tokenEnv in config.jsonc.
+      - name: Guard config.jsonc tokenEnv
+        env:
+          EXPECTED: ${{ vars.ECR_EXPECTED_TOKEN_ENV || 'ANTHROPIC_OAUTH_API_KEY' }}
+        run: |
+          values=$(grep -oE '"tokenEnv"[[:space:]]*:[[:space:]]*"[A-Za-z0-9_]+"' .expo-code-review/config.jsonc | sed -E 's/.*"([A-Za-z0-9_]+)"$/\1/')
+          count=$(printf '%s\n' "$values" | grep -c .)
+          if [ "$count" != "1" ] || [ "$values" != "$EXPECTED" ]; then
+            echo "::error::.expo-code-review/config.jsonc auth.tokenEnv must be \"$EXPECTED\" (found: \"${values:-none}\"). Refusing to run so a PR can't redirect which secret is forwarded to the model provider."
+            exit 1
+          fi
+
+      - uses: actions/setup-node@v5
         with:
           node-version: 24
+          # The reviewer runs via npx and never installs with a package manager, so
+          # disable setup-node's auto package-manager cache (its post step would try
+          # to save an empty cache and error).
+          package-manager-cache: false
 
       - name: Run AI review
-        # Requires the `expo-code-review` package to be published to npm. Until
-        # then, vendor the CLI or run it from a checkout instead of via npx.
-        # npx installs the CLI and its bundled `opencode` binary and puts them on
-        # PATH for this process.
-        run: npx --yes expo-code-review@latest ci
+        # npx installs @expo/code-review-cli and its bundled `opencode` binary and
+        # puts them on PATH for this process. Pin @latest to a version to freeze it.
+        run: npx --yes -p "@expo/code-review-cli@latest" ecr ci
         continue-on-error: true
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          # OpenCode reads ANTHROPIC_API_KEY. Source it from a dedicated,
-          # code-review-scoped secret. Swap for your provider's key/var.
-          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY_FOR_CODE_REVIEW }}
-          # Optional: override the model for every agent.
+          # Claude Pro/Max OAuth token (from `claude setup-token`) — the env var
+          # named by auth.tokenEnv in config.jsonc. Store it as a repo secret.
+          # (For an API key instead, set auth.mode "api-key" and pass that key here.)
+          ANTHROPIC_OAUTH_API_KEY: ${{ secrets.ANTHROPIC_OAUTH_API_KEY }}
+          # Optional: override the model for every agent (uses your OpenCode login).
           REVIEWER_MODEL: ${{ vars.REVIEWER_MODEL }}