@expo/code-review-cli 0.11.0 → 0.12.0

package/README.md

@@ -71,6 +71,9 @@ ecr review
 ecr review --pr 123
 # …and post it as the PR comment
 ecr review --pr 123 --post
+# Preview once, save the exact result, and post it later without another model run
+ecr review --repo owner/repo --pr 123 --save-review --json
+ecr post-review --artifact .expo-code-review/.runs/deferred/<artifact>.json --repo owner/repo --pr 123
 ```
 
 Options (most to least common):
@@ -79,6 +82,7 @@ Options (most to least common):
 | --- | --- |
 | `--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. |
+| `--save-review` | With explicit `--repo` + `--pr`, save the exact preview as a private postable artifact. Mutually exclusive with `--post`. |
 | `--staged` | Review only staged changes (index vs HEAD; not combinable with `--base`/`--head`). |
 | `--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). |
@@ -111,6 +115,7 @@ is a ready example to adapt.
 | `ecr setup-auth [--yes]` | Walk through getting model credentials for local runs (ChatGPT/Claude sign-in and/or API keys), printing the `export` lines for your shell config. |
 | `ecr review [options]` | Review local changes and print an advisory review (default command). |
 | `ecr review --scope <name>` | Review only one routing scope over just that scope's changed files. |
+| `ecr post-review --artifact <path> --repo <owner/repo> --pr <n>` | Post an exact saved PR preview without re-running models; refuses target, head, config, or break-glass drift. |
 | `ecr ci` | Review the current GitHub PR and post/update a comment. For GitHub Actions. |
 | `ecr doctor [--list-scopes]` | Check environment, config, credentials, and (with a manifest) scopes. |
 | `ecr feedback [--repo <owner/repo>]` | Report which findings PR authors pushed back on, across history. See below. |
@@ -168,6 +173,83 @@ Two run points:
 
 ---
 
+## Providing context and research capabilities
+
+`@expo/code-review-cli` includes `review-research-mcp` and can run it as a trusted
+host-side prepass. This is deliberately not an agent-visible MCP: Claude Code
+keeps `--safe-mode`, `--strict-mcp-config`, path-scoped read tools, and its
+execution/network/write deny list. Before model startup, ECR extracts only short
+API identifiers from added native code, asks the documentation MCP for bounded evidence,
+and appends the results to reviewer and cross-file prompts as explicitly untrusted
+reference text.
+
+Enable it only in the root config, which CI loads from the PR's trusted base:
+
+```jsonc
+{
+  "research": {
+    "enabled": true,
+    "indexPath": "/opt/expo-review/docs-index.json",
+    "maxQueries": 8,
+    "resultsPerQuery": 2,
+    "timeoutMs": 15000
+  }
+}
+```
+
+ECR resolves the MCP entry point inside its own installed package and starts it
+with the current absolute Node executable, so a PR-owned `PATH` entry cannot replace
+either component. Build the index in a separate networked job and mount it read-only
+in review jobs. The child runs from the OS temp directory with a minimal environment, a 2 MB output
+cap, and a hard timeout. It receives no model credentials, source snippets, string
+literals, comments, removed lines, or repository paths—only normalized identifiers,
+the platform, and named provider filters. MCP failures are visible in the job log
+but fail open to an ordinary review; they never skip or weaken review passes.
+
+Research is root-only in routed monorepos because it starts a host process; scope
+configs cannot change its index path or limits. Result-cache reuse is disabled while
+research is enabled because an index can change at the same mounted path. For CI,
+pin the ECR package/Node version and verify a signed index checksum before invoking
+ECR. A simpler initial deployment may build the index in an earlier, secretless
+workflow step using the same pinned published package, with no PR code executed and
+failure allowed so review can continue without research. Keep `update` out of the
+credential-bearing `ecr ci` process itself; the review pipeline always starts `serve`.
+
+The built-in query router recognizes Apple/Android APIs plus Media3, Glide, OkHttp,
+Kotlin coroutines, Gradle/AGP, Swift concurrency/evolution, platform release/API
+availability, Expo, React Native, Reanimated, Gesture Handler, Screens, and Worklets.
+Queries are short exact symbols plus at most one useful member or behavior term. For
+example, `CameraView barcodeScannerSettings` is useful; a source snippet, import path,
+or natural-language question is not. The MCP publishes the same guidance in its tool
+metadata for direct clients. An empty result stays empty; it is not replaced with a
+loose semantic guess.
+
+For a query routed to the `expo` provider, `serve` POSTs the already-sanitized query
+directly to Expo's public Algolia search endpoint and prefers the returned canonical
+`docs.expo.dev` hits.
+The endpoint, application id, and browser-visible search-only key are fixed in the
+package; redirects are rejected; response size, timeout, hit count, and returned URL
+host are bounded. Algolia receives the query text; a failed request falls back to the
+mounted local index. The local index is still required for that fallback and every
+other provider. Direct MCP clients can omit the `expo` provider; ECR installations
+requiring a fully offline review should leave research disabled until provider
+selection becomes installation-configurable.
+
+The MCP and its trusted updater ship with ECR. From this repository, build an index
+with `bun run research:update`; an installed package exposes the equivalent
+`review-research-mcp update`. The built-in seed catalog lives in
+`research/sources.json`, while the generated `research/data/` directory is ignored
+and is not published. `seedUrls` are deterministic starting pages for the bounded
+crawler; ordinary link extraction, parsing, indexing, and searching use no LLM.
+Installation-specific provider configuration is intentionally
+deferred: when added, it should follow the trusted root-config model used for agents
+without permitting PR-controlled URLs, commands, or executable parsers. Expo skills
+are complementary, not another search corpus: their pinned procedural guidance can
+later be supplied to review agents as separately labeled trusted context, while
+documentation search continues to return citable API evidence. Dynamic skills or
+instructions retrieved from documentation must never become executable reviewer
+instructions.
+
 ## Monorepos (routing manifest)
 
 A monorepo can route different subtrees to different reviewer rosters from a single
@@ -250,10 +332,11 @@ your-monorepo/
 
 ### Security
 
-- **auth is locked to the root.** `tokenEnv` (which env var becomes the model
+- **auth and research are locked to the root.** `tokenEnv` (which env var becomes the model
   credential) is honored in exactly one place: the root `config.jsonc` or
-  `routing.jsonc` `defaults.auth`. A scope config declaring `auth`/`breakGlass`
-  **fails to parse** (Zod-level rejection), and the CI guard step independently
+  `routing.jsonc` `defaults.auth`. A scope config declaring `auth`/`breakGlass`/`research`
+  **fails to parse** (Zod-level rejection). A scope declaring `research` also fails,
+  so PR-controlled routing cannot select a different host index. The CI guard step independently
   sweeps every `.expo-code-review/config.jsonc`/`routing.jsonc` repo-wide and refuses
   to run unless `tokenEnv` appears exactly once, in a root-owned file, equal to
   `ECR_EXPECTED_TOKEN_ENV`. A routing manifest can never widen exposure — globs only
@@ -661,6 +744,12 @@ that the PR comment embeds for machine consumers. The same totals are printed as
 one-line summary to the terminal / CI job log at the end of each run, so cache reuse
 is visible even in CI (where the run log is ephemeral).
 
+`ecr review --save-review` additionally writes a versioned artifact under
+`.expo-code-review/.runs/deferred/` with owner-only permissions. It contains the
+verified final review and bounded feedback metadata, but no credential. `ecr
+post-review` schema-validates it and refuses to post if its explicit repo/PR, live
+head commit, or local comment-policy fingerprint no longer matches.
+
 </details>
 
 <a id="other-providers"></a>

package/build/cli.js

@@ -5,6 +5,7 @@ import { dismissCommand } from "./commands/dismiss.js";
 import { doctorCommand } from "./commands/doctor.js";
 import { feedbackCommand } from "./commands/feedback.js";
 import { initCommand } from "./commands/init.js";
+import { postReviewCommand } from "./commands/post-review.js";
 import { refCheckCommand } from "./commands/ref-check.js";
 import { reviewCommand } from "./commands/review.js";
 import { setupAuthCommand } from "./commands/setup-auth.js";
@@ -13,6 +14,7 @@ const USAGE = `expo-code-review (ecr) — config-driven AI code reviewer
 
 Usage:
   ecr review [options]   Review local changes (default). See \`ecr review --help\`.
+  ecr post-review --artifact <path> --repo <owner/repo> --pr <n>   Post an exact saved preview.
   ecr ci                 Review the current PR and post a comment (GitHub Actions).
   ecr dismiss --pr <n> <id...>     Hide a finding on a PR (see \`ecr dismiss --help\`).
   ecr undismiss --pr <n> <id...>   Restore a dismissed finding.
@@ -43,6 +45,9 @@ async function main() {
         case "review":
             await reviewCommand(rest);
             break;
+        case "post-review":
+            await postReviewCommand(rest);
+            break;
         case "ci":
             await ciCommand(rest);
             break;

package/build/commands/ci.js

@@ -463,7 +463,10 @@ async function runLegacyCi(source, repo, prNumber, cwd, configRoot, options) {
     // Dynamic stack context and model-backed reply adjudication have inputs outside
     // the scoped diff. Keep those paths fresh until their inputs join the cache key.
     // A maintainer's explicit /review is also always a real rerun.
-    const cacheAllowed = !bypassTriggerGate && !stack && !feedback && metadata !== undefined;
+    // Research output depends on the mounted index contents, not merely its configured
+    // path. Until a signed index digest joins the cache key, a researched review must
+    // run fresh rather than reuse evidence from an older artifact at the same path.
+    const cacheAllowed = !bypassTriggerGate && !stack && !feedback && !config.research.enabled && metadata !== undefined;
     let inputHash;
     try {
         if (cacheAllowed) {
@@ -701,6 +704,7 @@ async function runRoutedCi(source, manifest, repo, prNumber, cwd, configRoot, op
     const cacheAllowed = !bypassTriggerGate &&
         !stackWalk &&
         !feedbackNeedsRunSeam(rootConfig.feedback) &&
+        !rootConfig.research.enabled &&
         metadata !== undefined;
     let cacheReadRoot;
     if (cacheAllowed) {

package/build/commands/post-review.js

@@ -0,0 +1,147 @@
+// @ref LLP 0007#deferred-review-posting [implements] — no-model post of an exact, target-bound preview artifact
+import path from "node:path";
+import { loadReviewConfig } from "../config/load.js";
+import { assertDeferredReviewCurrent, readDeferredReviewArtifact, reviewPostingConfigFingerprint, } from "../core/deferred-review.js";
+import { repoRoot } from "../core/exec.js";
+import { errorMessage } from "../core/util.js";
+import { GitHubReporter } from "../reporters/github.js";
+import { GitHubPRSource, isCommitOid } from "../sources/github-pr.js";
+const USAGE = `ecr post-review — post an exact saved PR review without re-running models
+
+Usage:
+  ecr post-review --artifact <path> --repo <owner/repo> --pr <n>
+
+The artifact must come from \`ecr review --save-review --repo <owner/repo> --pr <n>\`.
+Before writing to GitHub, this command verifies the explicit repo/PR, the live PR
+head commit, the local posting policy, and the PR's break-glass marker.
+`;
+function requireValue(flag, value) {
+    if (value === undefined || value.startsWith("--")) {
+        throw new Error(`${flag} requires a value`);
+    }
+    return value;
+}
+export function parsePostReviewArgs(argv) {
+    const args = { help: false };
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        switch (arg) {
+            case "--artifact":
+                args.artifact = requireValue(arg, argv[++i]);
+                break;
+            case "--repo":
+                args.repo = requireValue(arg, argv[++i]);
+                break;
+            case "--pr": {
+                const value = requireValue(arg, argv[++i]);
+                const number = Number(value);
+                if (!Number.isSafeInteger(number) || number <= 0) {
+                    throw new Error(`--pr requires a positive safe integer (got "${value}")`);
+                }
+                args.pr = number;
+                break;
+            }
+            case "-h":
+            case "--help":
+                args.help = true;
+                break;
+            default:
+                throw new Error(`Unknown argument: ${arg}`);
+        }
+    }
+    return args;
+}
+function validatePostReviewArgs(args) {
+    if (!args.artifact || !args.repo || args.pr == null) {
+        throw new Error("--artifact, --repo, and --pr are all required");
+    }
+    if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(args.repo)) {
+        throw new Error(`--repo requires owner/repo (got "${args.repo}")`);
+    }
+}
+/** Break-glass errors fail closed: no report call occurs unless the check says false. */
+export async function publishDeferredReview(poster, artifact, assertReadyToPost = async () => { }) {
+    if (await poster.checkBreakGlass()) {
+        return "break-glass";
+    }
+    await assertReadyToPost();
+    await poster.report(artifact.review, artifact.feedback);
+    return "posted";
+}
+export async function postReviewCommand(argv) {
+    let args;
+    try {
+        args = parsePostReviewArgs(argv);
+        if (args.help) {
+            process.stdout.write(USAGE);
+            return;
+        }
+        validatePostReviewArgs(args);
+    }
+    catch (error) {
+        process.stderr.write(`${errorMessage(error)}\n\n${USAGE}`);
+        process.exitCode = 2;
+        return;
+    }
+    // Resolve before chdir so a relative artifact path keeps the caller's meaning.
+    const artifactPath = path.resolve(process.cwd(), args.artifact);
+    try {
+        const root = await repoRoot();
+        if (root && root !== process.cwd()) {
+            process.chdir(root);
+        }
+        const cwd = process.cwd();
+        const [artifact, config] = await Promise.all([
+            readDeferredReviewArtifact(artifactPath),
+            loadReviewConfig(cwd),
+        ]);
+        const source = new GitHubPRSource({ prNumber: args.pr, repo: args.repo, cwd });
+        const headSha = (await source.getMetadata()).headOid;
+        if (!isCommitOid(headSha)) {
+            throw new Error(`could not resolve a full head commit for ${args.repo}#${args.pr}`);
+        }
+        assertDeferredReviewCurrent(artifact, {
+            repo: args.repo,
+            pr: args.pr,
+            headSha,
+            configFingerprint: reviewPostingConfigFingerprint(config),
+        });
+        const reporter = new GitHubReporter({
+            prNumber: args.pr,
+            repo: args.repo,
+            commentTag: config.commentTag,
+            breakGlassMarker: config.breakGlassMarker,
+            cwd,
+            feedback: config.feedback,
+            headSha,
+        });
+        const result = await publishDeferredReview(reporter, artifact, async () => {
+            // Re-fetch rather than reusing GitHubPRSource's memoized metadata, and reload
+            // config after the break-glass API call. This narrows the unavoidable remote
+            // TOCTOU window and prevents a head/policy change during setup from reaching
+            // the reporter.
+            const [latestMetadata, latestConfig] = await Promise.all([
+                new GitHubPRSource({ prNumber: args.pr, repo: args.repo, cwd }).getMetadata(),
+                loadReviewConfig(cwd),
+            ]);
+            if (!isCommitOid(latestMetadata.headOid)) {
+                throw new Error(`could not re-resolve a full head commit for ${args.repo}#${args.pr}`);
+            }
+            assertDeferredReviewCurrent(artifact, {
+                repo: args.repo,
+                pr: args.pr,
+                headSha: latestMetadata.headOid,
+                configFingerprint: reviewPostingConfigFingerprint(latestConfig),
+            });
+        });
+        if (result === "break-glass") {
+            process.stderr.write(`Not posting: ${config.breakGlassMarker} is set on ${args.repo}#${args.pr}.\n`);
+            return;
+        }
+        process.stderr.write(`Posted saved review to ${args.repo}#${args.pr}.\n`);
+    }
+    catch (error) {
+        process.stderr.write(`Saved review was not posted: ${errorMessage(error)}\n`);
+        process.exitCode = 2;
+    }
+}

package/build/commands/review.js

@@ -4,10 +4,11 @@ import { loadRoutingManifest, resolveScopes, scopedCommentTag } from "../config/
 import { repoRoot, resolveRepo } from "../core/exec.js";
 import { errorMessage } from "../core/util.js";
 import { readContextFile } from "../core/context-file.js";
+import { writeDeferredReviewArtifact } from "../core/deferred-review.js";
 import { feedbackNeedsRunSeam } from "../core/adjudicate.js";
 import { runReview } from "../core/review.js";
 import { LocalGitSource } from "../sources/local-git.js";
-import { GitHubPRSource } from "../sources/github-pr.js";
+import { GitHubPRSource, isCommitOid } from "../sources/github-pr.js";
 import { memoizeSource, stackConfirmFromConfig, stackWalkFromConfig } from "../sources/source.js";
 import { TerminalReporter } from "../reporters/terminal.js";
 import { GitHubReporter } from "../reporters/github.js";
@@ -15,7 +16,8 @@ const USAGE = `ecr review — AI code review, printed to your terminal
 
 Usage:
   ecr review [options]                 review local changes
-  ecr review --pr <n> [--post]         review a GitHub PR by number
+  ecr review --pr <n> [--post | --save-review]
+                                       review a GitHub PR by number
 
 Source (pick one):
   (default)          diff the working tree against the merge-base
@@ -31,6 +33,8 @@ Options:
   --post               with --pr: also post the result as the PR comment (needs
                        \`gh\` auth). Omit to only preview here; re-run with --post
                        to publish.
+  --save-review        with explicit --repo + --pr: save this exact preview as a
+                       postable artifact for a later \`ecr post-review\` command.
   --agents <a,b>       run only these agents (comma-separated ids); default: all
   --route              let the router pick relevant agents from the diff
   --scope <name>       review only this routing scope (needs a routing.jsonc);
@@ -60,10 +64,11 @@ function requireValue(flag, value) {
     }
     return value;
 }
-function parseArgs(argv) {
+export function parseReviewArgs(argv) {
     const args = {
         staged: false,
         post: false,
+        saveReview: false,
         route: false,
         stackAware: false,
         json: false,
@@ -85,8 +90,8 @@ function parseArgs(argv) {
             case "--pr": {
                 const value = requireValue(arg, argv[++i]);
                 const number = Number(value);
-                if (!Number.isInteger(number) || number <= 0) {
-                    throw new Error(`--pr requires a positive PR number (got "${value}")`);
+                if (!Number.isSafeInteger(number) || number <= 0) {
+                    throw new Error(`--pr requires a positive safe integer (got "${value}")`);
                 }
                 args.pr = number;
                 break;
@@ -97,6 +102,9 @@ function parseArgs(argv) {
             case "--post":
                 args.post = true;
                 break;
+            case "--save-review":
+                args.saveReview = true;
+                break;
             case "--agents":
                 args.agents = requireValue(arg, argv[++i])
                     .split(",")
@@ -137,7 +145,7 @@ function parseArgs(argv) {
 export async function reviewCommand(argv) {
     let args;
     try {
-        args = parseArgs(argv);
+        args = parseReviewArgs(argv);
     }
     catch (error) {
         process.stderr.write(`${errorMessage(error)}\n\n${USAGE}`);
@@ -149,7 +157,7 @@ export async function reviewCommand(argv) {
         return;
     }
     try {
-        validateArgs(args);
+        validateReviewArgs(args);
     }
     catch (error) {
         process.stderr.write(`${errorMessage(error)}\n\n${USAGE}`);
@@ -292,11 +300,13 @@ export async function reviewCommand(argv) {
         }
         const config = await loadReviewConfig(cwd, { configDir: args.configDir });
         const source = makeSource();
-        // Build the PR reporter up front when posting, so adjudicate mode can judge the
+        // Build the PR reporter up front when posting OR saving a postable preview, so
+        // adjudicate mode can judge the
         // PR's replies against the source before the result is rendered. Feedback only
         // has replies to match when reviewing a PR and posting (the terminal preview never
-        // renders annotations), so it is wired only on the --post --pr path.
-        const { repo: postRepo, error: postRepoError } = await resolvePostRepo(args, cwd);
+        // renders annotations), so it is wired only when a later/current post is possible.
+        const { repo: postRepo, error: postRepoError } = await resolvePostRepo({ ...args, post: args.post || args.saveReview }, cwd);
+        const headSha = postRepo != null && args.pr != null ? await reviewedHeadSha(source) : undefined;
         const reporter = postRepo != null && args.pr != null
             ? new GitHubReporter({
                 prNumber: args.pr,
@@ -305,7 +315,7 @@ export async function reviewCommand(argv) {
                 breakGlassMarker: config.breakGlassMarker,
                 cwd,
                 feedback: config.feedback,
-                headSha: await reviewedHeadSha(source),
+                headSha,
             })
             : null;
         const review = await runReview(source, {
@@ -325,6 +335,19 @@ export async function reviewCommand(argv) {
         });
         // Always print the result here first.
         await new TerminalReporter({ json: args.json, noFail: args.noFail }).report(review);
+        if (args.saveReview) {
+            if (postRepo == null || args.pr == null || !isCommitOid(headSha)) {
+                throw new Error(`could not save a postable review: ${postRepoError ? errorMessage(postRepoError) : "the PR head commit could not be resolved"}`);
+            }
+            const artifactPath = await writeDeferredReviewArtifact(config, {
+                repo: postRepo,
+                pr: args.pr,
+                headSha,
+                review,
+                feedback: review.feedback,
+            });
+            process.stderr.write(`\nSaved postable review artifact: ${artifactPath}\n`);
+        }
         // Then, only if asked, publish the same result to the PR.
         if (args.pr != null && args.post) {
             if (reporter) {
@@ -403,12 +426,21 @@ export async function resolvePostRepo(args, cwd, resolve = resolveRepo) {
 }
 // @ref LLP 0007#ecr-review-local-trust-and-flag-rules [implements] — mutually exclusive flags rejected outright, never silently ignored
 /** Reject flag combinations that don't make sense together. */
-function validateArgs(args) {
+export function validateReviewArgs(args) {
     if (args.pr != null && (args.base || args.head || args.staged)) {
         throw new Error("--pr reviews a PR by its diff and cannot be combined with --base/--head/--staged.");
     }
-    if (args.pr == null && (args.repo || args.post)) {
-        throw new Error("--repo/--post only apply together with --pr.");
+    if (args.pr == null && (args.repo || args.post || args.saveReview)) {
+        throw new Error("--repo/--post/--save-review only apply together with --pr.");
+    }
+    if (args.saveReview && !args.repo) {
+        throw new Error("--save-review requires explicit --repo owner/repo.");
+    }
+    if (args.saveReview && args.post) {
+        throw new Error("--save-review and --post are mutually exclusive.");
+    }
+    if (args.saveReview && (args.scope || args.configDir)) {
+        throw new Error("--save-review does not support --scope or --config-dir.");
     }
     // Same rule as --repo/--post: the stack walk needs a PR to walk from, so a bare
     // --stack-aware would be silently ignored — reject it instead.

package/build/config/load.js

@@ -26,6 +26,13 @@ const FEEDBACK_CONFIG_DEFAULTS = {
     protectedCategories: ["secrets", "security"],
     maxAdjudications: 10,
 };
+/** Research defaults for a scope load (where `research` is schema-rejected). */
+const RESEARCH_CONFIG_DEFAULTS = {
+    enabled: false,
+    maxQueries: 8,
+    resultsPerQuery: 2,
+    timeoutMs: 15_000,
+};
 /** Default OpenCode tool toggles for a reviewer: read the repo, never mutate it. */
 const DEFAULT_AGENT_TOOLS = toolMap(["read", "grep", "glob", "list"]);
 export function configDirFor(repoRoot) {
@@ -136,6 +143,9 @@ async function loadConfigDir(dir, schema) {
         policy: parsed.policy,
         chunk: parsed.chunk,
         noise: parsed.noise,
+        // Root-only: scope schemas reject research configuration, so an untrusted
+        // subtree cannot select the index or alter the network-facing runtime.
+        research: parsed.research ?? RESEARCH_CONFIG_DEFAULTS,
         // parsed.breakGlass/auth are always present for the root schema (defaults) and
         // absent for the scope schema; loadScopeConfig overrides both afterwards.
         breakGlassMarker: parsed.breakGlass?.marker ?? "/skip-review",
@@ -286,6 +296,7 @@ export async function loadScopeConfig(root, scope, manifest, rootConfig) {
         // run the default policy instead of the repo's real one.
         stack: rootConfig.stack,
         feedback: rootConfig.feedback,
+        research: rootConfig.research,
         scopeName: scope.name,
     };
 }

package/build/config/schema.js

@@ -58,6 +58,33 @@ export const ReviewConfigSchema = z.object({
         additionalMarkers: z.array(z.string()).default([]),
     })
         .default({ additionalIgnores: [], additionalMarkers: [] }),
+    research: z
+        .object({
+        enabled: z.boolean().default(false),
+        indexPath: z
+            .string()
+            .min(1)
+            .refine((value) => path.isAbsolute(value), "research.indexPath must be an absolute path")
+            .optional(),
+        maxQueries: z.number().int().min(1).max(20).default(8),
+        resultsPerQuery: z.number().int().min(1).max(3).default(2),
+        timeoutMs: z.number().int().min(1000).max(60_000).default(15_000),
+    })
+        .superRefine((value, context) => {
+        if (value.enabled && !value.indexPath) {
+            context.addIssue({
+                code: "custom",
+                path: ["indexPath"],
+                message: "research.indexPath is required when research.enabled is true",
+            });
+        }
+    })
+        .default({
+        enabled: false,
+        maxQueries: 8,
+        resultsPerQuery: 2,
+        timeoutMs: 15_000,
+    }),
     breakGlass: z
         .object({ marker: z.string().default("/skip-review") })
         .default({ marker: "/skip-review" }),
@@ -278,7 +305,7 @@ export const RoutingManifestSchema = z
  * Scope config = root config MINUS the centrally locked keys. Allowlist of
  * scope-overridable keys (Turborepo-style, graft 6): model, policy, chunk,
  * noise (+ the prompt files living beside it: shared.md, coordinator.md,
- * agents/). NEVER auth or breakGlass — declaring either fails parsing at the
+ * agents/). NEVER auth, breakGlass, or research — declaring one fails parsing at the
  * Zod level so IDE/doctor catch it before CI. commentTag is also locked: a
  * scope's comment marker is always DERIVED (`<rootTag>:<scope>`; the default
  * scope keeps the root tag) so `ecr ci`'s post/clear/reconcile paths and a
@@ -292,6 +319,7 @@ export const ScopeReviewConfigSchema = ReviewConfigSchema.omit({
     commentTag: true,
     stack: true,
     feedback: true,
+    research: true,
 }).extend({
     auth: z
         .never({ error: "auth is locked to the root config; remove it from this scope config" })
@@ -312,4 +340,9 @@ export const ScopeReviewConfigSchema = ReviewConfigSchema.omit({
         error: "feedback is locked to the root config (the comment lifecycle is global); remove it from this scope config",
     })
         .optional(),
+    research: z
+        .never({
+        error: "research is locked to the root config because it starts a trusted host process; remove it from this scope config",
+    })
+        .optional(),
 });