@expo/code-review-cli 0.7.0 → 0.9.0

package/build/commands/review.js

@@ -1,11 +1,14 @@
+// @ref LLP 0007#ecr-review-local-trust-and-flag-rules — local runs: the person at the terminal is the trust principal, even with --pr
 import { loadReviewConfig, loadScopeConfig } from "../config/load.js";
 import { loadRoutingManifest, resolveScopes, scopedCommentTag } from "../config/routing.js";
 import { repoRoot, resolveRepo } from "../core/exec.js";
 import { errorMessage } from "../core/util.js";
+import { readContextFile } from "../core/context-file.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 { memoizeSource } from "../sources/source.js";
+import { memoizeSource, stackConfirmFromConfig, stackWalkFromConfig } from "../sources/source.js";
 import { TerminalReporter } from "../reporters/terminal.js";
 import { GitHubReporter } from "../reporters/github.js";
 const USAGE = `ecr review — AI code review, printed to your terminal
@@ -34,6 +37,11 @@ Options:
                        runs its config over just that scope's changed files
   --config-dir <dir>   load config from <dir> instead of .expo-code-review/
                        (also ECR_CONFIG_DIR); can't combine with --scope
+  --context-file <p>   inject <p>'s UTF-8 text into reviewer prompts as an
+                       explicitly UNTRUSTED external-context block
+  --stack-aware        with --pr: walk the open PRs stacked on top and let the
+                       coordinator requalify absence-style findings a later PR
+                       already addresses (off by default; rejected without --pr)
   --json               emit machine-readable JSON on stdout
   --no-fail            always exit 0, even on request-changes
   -h, --help           show this help
@@ -57,6 +65,7 @@ function parseArgs(argv) {
         staged: false,
         post: false,
         route: false,
+        stackAware: false,
         json: false,
         noFail: false,
         help: false,
@@ -103,6 +112,12 @@ function parseArgs(argv) {
             case "--config-dir":
                 args.configDir = requireValue(arg, argv[++i]);
                 break;
+            case "--context-file":
+                args.contextFile = requireValue(arg, argv[++i]);
+                break;
+            case "--stack-aware":
+                args.stackAware = true;
+                break;
             case "--json":
                 args.json = true;
                 break;
@@ -147,6 +162,29 @@ export async function reviewCommand(argv) {
     if (root && root !== process.cwd()) {
         process.chdir(root);
     }
+    // @ref LLP 0007#ecr-review-local-trust-and-flag-rules [implements] — --context-file is orthogonal enrichment; local read errors fail loud (exit 2)
+    // Read the context file ONCE, in the command layer (routed review calls runReview
+    // per scope; reading inside would re-read the file N times). Local runs FAIL LOUD
+    // on a read error: the user typed the path, so a typo or oversized file is a
+    // mistake to surface, not to silently skip (unlike `ecr ci`, which warns and
+    // continues to keep the never-fail-checks invariant).
+    let contextText;
+    if (args.contextFile) {
+        try {
+            contextText = await readContextFile(args.contextFile);
+        }
+        catch (error) {
+            process.stderr.write(`--context-file: ${errorMessage(error)}\n`);
+            process.exitCode = 2;
+            return;
+        }
+        // Empty/whitespace-only file: warn (a typo'd or unwritten path) but do not fail
+        // — there is simply no context to add.
+        if (!contextText.trim()) {
+            process.stderr.write(`--context-file: ${args.contextFile} is empty; no context added.\n`);
+            contextText = undefined;
+        }
+    }
     try {
         const cwd = process.cwd();
         const makeSource = () => args.pr != null
@@ -176,46 +214,74 @@ export async function reviewCommand(argv) {
                     process.stdout.write(`No changed files in scope ${args.scope}.\n`);
                     return;
                 }
+                // Build the PR reporter up front when posting, so adjudicate mode can judge the
+                // replies against the source before the result is rendered (see the non-scope
+                // path). A scope always posts under the DERIVED marker `<rootTag>:<scope>` —
+                // from the ROOT config's tag exactly like `ecr ci` does (runRoutedCi prefers
+                // rootConfig.commentTag over manifest defaults when they diverge) — so a
+                // standalone scope post and CI's per-scope post/clear/reconcile paths always
+                // target the same marker, and the bare aggregate marker is never used here.
+                // (Per-scope commentTag overrides are rejected by the scope schema for exactly
+                // this reason.)
+                // @ref LLP 0007#ecr-review-local-trust-and-flag-rules [constrained-by] — must match ci.ts's derivation; the scope schema ban on commentTag is what keeps them aligned
+                const { repo: postRepo, error: postRepoError } = await resolvePostRepo(args, cwd);
+                const reporter = postRepo != null && args.pr != null
+                    ? new GitHubReporter({
+                        prNumber: args.pr,
+                        repo: postRepo,
+                        commentTag: scopedCommentTag(rootConfig.commentTag, args.scope),
+                        breakGlassMarker: config.breakGlassMarker,
+                        cwd,
+                        // Root-only feedback config (loadScopeConfig inherits it from the root).
+                        feedback: config.feedback,
+                        headSha: await reviewedHeadSha(source),
+                    })
+                    : null;
                 const review = await runReview(source, {
                     config,
                     mode: "local",
                     agents: args.agents,
                     route: args.route,
                     includePaths: files,
+                    contextText,
+                    // Explicit --stack-aware only: local config is not a trusted base, so the
+                    // user typing the flag is the trust principal. Bounds come from the root
+                    // config; validateArgs already rejected --stack-aware without --pr, and the
+                    // pr guard here keeps that invariant local.
+                    stack: args.stackAware && args.pr != null ? stackWalkFromConfig(rootConfig.stack) : undefined,
+                    stackConfirm: args.stackAware && args.pr != null
+                        ? stackConfirmFromConfig(rootConfig.stack)
+                        : undefined,
+                    feedback: reporter && feedbackNeedsRunSeam(config.feedback)
+                        ? { config: config.feedback, match: (r) => reporter.matchAdjudicationItems(r) }
+                        : undefined,
                     onProgress: (message) => process.stderr.write(`${message}\n`),
                 });
                 await new TerminalReporter({ json: args.json, noFail: args.noFail }).report(review);
-                if (args.post && args.pr != null) {
-                    const repo = args.repo ?? (await resolveRepo(cwd));
-                    // A scope always posts under the DERIVED marker `<rootTag>:<scope>` —
-                    // from the ROOT config's tag exactly like `ecr ci` does (runRoutedCi
-                    // prefers rootConfig.commentTag over manifest defaults when they
-                    // diverge) — so a standalone scope post and CI's per-scope post/clear/
-                    // reconcile paths always target the same marker, and the bare aggregate
-                    // marker is never used here. (Per-scope commentTag overrides are
-                    // rejected by the scope schema for exactly this reason.)
-                    const tag = scopedCommentTag(rootConfig.commentTag, args.scope);
-                    const reporter = new GitHubReporter({
-                        prNumber: args.pr,
-                        repo,
-                        commentTag: tag,
-                        breakGlassMarker: config.breakGlassMarker,
-                        cwd,
-                    });
-                    // Respect the author's break-glass opt-out, same as the non-scope path.
-                    let breakGlass = false;
-                    try {
-                        breakGlass = await reporter.checkBreakGlass();
-                    }
-                    catch {
-                        breakGlass = false;
-                    }
-                    if (breakGlass) {
-                        process.stderr.write(`\nNot posting: ${config.breakGlassMarker} is set on ${repo}#${args.pr} (break-glass).\n`);
+                if (args.pr != null && args.post) {
+                    if (reporter) {
+                        // Respect the author's break-glass opt-out, same as the non-scope path.
+                        let breakGlass = false;
+                        try {
+                            breakGlass = await reporter.checkBreakGlass();
+                        }
+                        catch {
+                            breakGlass = false;
+                        }
+                        if (breakGlass) {
+                            process.stderr.write(`\nNot posting: ${config.breakGlassMarker} is set on ${postRepo}#${args.pr} (break-glass).\n`);
+                        }
+                        else {
+                            await reporter.report(review, review.feedback);
+                            process.stderr.write(`\nPosted scope "${args.scope}" review to ${postRepo}#${args.pr}.\n`);
+                        }
                     }
                     else {
-                        await reporter.report(review);
-                        process.stderr.write(`\nPosted scope "${args.scope}" review to ${repo}#${args.pr}.\n`);
+                        // @ref LLP 0007#ecr-review-local-trust-and-flag-rules [implements] — a
+                        // `gh` failure resolving the repo must not hide the review already
+                        // printed above; only the post step fails here, with a clear message.
+                        process.stderr.write(`\nNot posted: could not resolve the repo for --post (${errorMessage(postRepoError)}). Pass --repo owner/repo.\n`);
+                        process.exitCode = 2;
                     }
                 }
             }
@@ -226,39 +292,65 @@ 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
+        // 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);
+        const reporter = postRepo != null && args.pr != null
+            ? new GitHubReporter({
+                prNumber: args.pr,
+                repo: postRepo,
+                commentTag: config.commentTag,
+                breakGlassMarker: config.breakGlassMarker,
+                cwd,
+                feedback: config.feedback,
+                headSha: await reviewedHeadSha(source),
+            })
+            : null;
         const review = await runReview(source, {
             config,
             mode: "local",
             agents: args.agents,
             route: args.route,
+            contextText,
+            // Explicit --stack-aware only (see the scope branch); validateArgs already
+            // rejected --stack-aware without --pr.
+            stack: args.stackAware && args.pr != null ? stackWalkFromConfig(config.stack) : undefined,
+            stackConfirm: args.stackAware && args.pr != null ? stackConfirmFromConfig(config.stack) : undefined,
+            feedback: reporter && feedbackNeedsRunSeam(config.feedback)
+                ? { config: config.feedback, match: (r) => reporter.matchAdjudicationItems(r) }
+                : undefined,
             onProgress: (message) => process.stderr.write(`${message}\n`),
         });
         // Always print the result here first.
         await new TerminalReporter({ json: args.json, noFail: args.noFail }).report(review);
         // Then, only if asked, publish the same result to the PR.
-        if (args.post && args.pr != null) {
-            const repo = args.repo ?? (await resolveRepo(cwd));
-            const reporter = new GitHubReporter({
-                prNumber: args.pr,
-                repo,
-                commentTag: config.commentTag,
-                breakGlassMarker: config.breakGlassMarker,
-                cwd,
-            });
-            // Respect the author's break-glass opt-out, same as the CI path.
-            let breakGlass = false;
-            try {
-                breakGlass = await reporter.checkBreakGlass();
-            }
-            catch {
-                breakGlass = false;
-            }
-            if (breakGlass) {
-                process.stderr.write(`\nNot posting: ${config.breakGlassMarker} is set on ${repo}#${args.pr} (break-glass).\n`);
+        if (args.pr != null && args.post) {
+            if (reporter) {
+                // Respect the author's break-glass opt-out, same as the CI path.
+                let breakGlass = false;
+                try {
+                    breakGlass = await reporter.checkBreakGlass();
+                }
+                catch {
+                    breakGlass = false;
+                }
+                if (breakGlass) {
+                    process.stderr.write(`\nNot posting: ${config.breakGlassMarker} is set on ${postRepo}#${args.pr} (break-glass).\n`);
+                }
+                else {
+                    await reporter.report(review, review.feedback);
+                    process.stderr.write(`\nPosted review to ${postRepo}#${args.pr}.\n`);
+                }
             }
             else {
-                await reporter.report(review);
-                process.stderr.write(`\nPosted review to ${repo}#${args.pr}.\n`);
+                // @ref LLP 0007#ecr-review-local-trust-and-flag-rules [implements] — a `gh`
+                // failure resolving the repo (no auth, no network, no GitHub remote, rate
+                // limit) must not hide the review already printed above; only the post
+                // step fails here, with a clear message.
+                process.stderr.write(`\nNot posted: could not resolve the repo for --post (${errorMessage(postRepoError)}). Pass --repo owner/repo.\n`);
+                process.exitCode = 2;
             }
         }
     }
@@ -267,6 +359,49 @@ export async function reviewCommand(argv) {
         process.exitCode = 2;
     }
 }
+/**
+ * The head commit the review reads, when the source can pin one (a GitHub PR). The
+ * reporter binds every adjudication verdict to it, so a stored verdict carries to a
+ * later run only while the reviewed source is unchanged (see mergeFeedback). Never
+ * throws: an unresolvable head reads as unknown source, which re-judges the reply
+ * instead of trusting a verdict about code we cannot pin.
+ */
+async function reviewedHeadSha(source) {
+    try {
+        return (await source.getMetadata()).headOid;
+    }
+    catch {
+        return undefined;
+    }
+}
+// @ref LLP 0007#ecr-review-local-trust-and-flag-rules [implements] — local runs
+// still print the review even when --post's repo can't be resolved
+/**
+ * Resolve the repo needed for --post --pr, without ever throwing: a `gh` failure
+ * (no auth, no network, no GitHub remote, rate limit) must degrade to "skip the
+ * post step", not abort the review itself — the local run already trusts the
+ * caller and should still show them the review. Callers treat a returned `error`
+ * as "no repo, and here's why" once they reach the post step; the review and its
+ * optional feedback seam simply run without a reporter until then.
+ *
+ * `resolve` is injectable (defaults to the real `resolveRepo`) purely so tests can
+ * exercise the failure path deterministically, without a `gh` binary or network.
+ */
+export async function resolvePostRepo(args, cwd, resolve = resolveRepo) {
+    if (!(args.post && args.pr != null)) {
+        return {};
+    }
+    if (args.repo) {
+        return { repo: args.repo };
+    }
+    try {
+        return { repo: await resolve(cwd) };
+    }
+    catch (error) {
+        return { error };
+    }
+}
+// @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) {
     if (args.pr != null && (args.base || args.head || args.staged)) {
@@ -275,6 +410,11 @@ function validateArgs(args) {
     if (args.pr == null && (args.repo || args.post)) {
         throw new Error("--repo/--post only apply together with --pr.");
     }
+    // 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.
+    if (args.pr == null && args.stackAware) {
+        throw new Error("--stack-aware only applies together with --pr.");
+    }
     // --staged diffs the index against HEAD, so --base/--head have no effect. Reject
     // the combination rather than silently ignoring the range the user asked for.
     if (args.staged && (args.base || args.head)) {

package/build/commands/setup-auth.js

@@ -1,3 +1,4 @@
+// @ref LLP 0007#doctor-and-setup-auth — derives a plan from auth config, then guides local credential acquisition
 import { spawnSync } from "node:child_process";
 import { readFile } from "node:fs/promises";
 import os from "node:os";
@@ -65,6 +66,7 @@ export function opencodeAuthJsonPath(env = process.env) {
     const dataHome = env.XDG_DATA_HOME || path.join(os.homedir(), ".local", "share");
     return path.join(dataHome, "opencode", "auth.json");
 }
+// @ref LLP 0007#doctor-and-setup-auth [constrained-by] — refresh tokens are single-use; they never leave OpenCode's store
 /**
  * The stored ChatGPT sign-in's ACCESS token, if OpenCode has a live one. The
  * refresh token deliberately never leaves OpenCode's store: refresh tokens are
@@ -102,6 +104,7 @@ async function confirm(question, skip) {
         rl.close();
     }
 }
+// @ref LLP 0007#doctor-and-setup-auth [constrained-by] — shell metacharacters in tokens never expand
 /** The line to paste into a shell config. Single-quoted: tokens never contain '. */
 export function exportLine(tokenEnv, value) {
     return `export ${tokenEnv}='${value}'`;

package/build/commands/verify-config.js

@@ -1,3 +1,4 @@
+// @ref LLP 0007#verify-config-the-config-guard — the CI trust guard that runs before the loaders are trusted, so it deliberately does not use them
 import { readdir, readFile } from "node:fs/promises";
 import path from "node:path";
 import { CONFIG_DIRNAME, stripJsonComments, stripTrailingCommas } from "../config/load.js";
@@ -28,6 +29,7 @@ Options:
   --json                  Emit {ok, findings:[{file, problem}]} on stdout.
 `;
 const CONFIG_FILENAMES = new Set(["config.jsonc", "config.json", ROUTING_FILENAME]);
+// @ref LLP 0007#verify-config-the-config-guard [implements] — on-disk sweep, not git index, not the manifest; CONFIG_FILENAMES must mirror load.ts
 /**
  * Discover every config the CLI could ever read via a plain recursive walk (not
  * `git ls-files`): a PR can't hide an unreferenced/untracked config dir from an
@@ -183,6 +185,7 @@ export async function verifyConfig(root, options = {}) {
         }
         seen.add(occurrence.value);
     }
+    // @ref LLP 0007#verify-config-the-config-guard [implements] — exact set equality; adding a credential is refused like repointing one
     // With an expectation set, the declared names must equal the expected SET
     // exactly (comma-separated; order-insensitive). A missing name is as much a
     // finding as an extra one — a PR must not add, drop, or repoint credentials.

package/build/config/load.js

@@ -1,9 +1,31 @@
+// @ref LLP 0006#loading-and-the-config-dir-escape-hatch — shared root/scope loader; ECR_CONFIG_DIR escape hatch
+// @ref LLP 0006#model-resolution — REVIEWER_MODEL env override resolution
+// @ref LLP 0006#auth-config-shapes — auth normalization (normalizeAuth, tokenEnvMismatch, loadAuthFromRoot)
+// @ref LLP 0006#root-vs-scope-config — scope config loading, commentTag derivation, enforceAgents injection
 import { readdir, readFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import path from "node:path";
 import { ReviewConfigSchema, ScopeReviewConfigSchema } from "./schema.js";
 import { toolMap } from "../core/tools.js";
 export const CONFIG_DIRNAME = ".expo-code-review";
+/** Stack config for a scope load (where `stack` is schema-rejected and absent). */
+const STACK_CONFIG_DEFAULTS = {
+    enabled: false,
+    maxDepth: 4,
+    maxPrs: 8,
+    maxFilesPerPr: 100,
+    requireSameAuthor: true,
+    confirmWithPatch: false,
+    maxConfirmations: 10,
+};
+/** Feedback config for a scope load (where `feedback` is schema-rejected and absent). */
+const FEEDBACK_CONFIG_DEFAULTS = {
+    mode: "annotate",
+    match: "both",
+    dismiss: "never",
+    protectedCategories: ["secrets", "security"],
+    maxAdjudications: 10,
+};
 /** 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) {
@@ -61,6 +83,7 @@ async function loadConfigDir(dir, schema) {
     // agent and the coordinator then ran on whatever OpenCode picked by default, so a
     // config saying `anthropic/claude-sonnet-5` reviewed with something else entirely and
     // nothing anywhere said so. Trim too: a stray newline is the same class of accident.
+    // @ref LLP 0006#model-resolution [constrained-by] — never ??; GitHub Actions passes an unset var as empty string, not undefined
     const override = process.env.REVIEWER_MODEL?.trim() || undefined;
     const defaultModel = override ?? parsed.model;
     const resolveModel = (frontmatterModel) => override ?? frontmatterModel ?? defaultModel;
@@ -121,6 +144,14 @@ async function loadConfigDir(dir, schema) {
         commentTag: parsed.commentTag ?? "expo-ai-code-reviewer",
         auth: normalizeAuth(parsed.auth),
         review: parsed.review,
+        // Root-only: the scope schema rejects `stack`, so parsed.stack is absent for a
+        // scope config and the defaults stand in (unused — the command layer reads the
+        // ROOT config's stack values to drive the walk).
+        stack: parsed.stack ?? STACK_CONFIG_DEFAULTS,
+        // Root-only: the scope schema rejects `feedback`, so parsed.feedback is absent
+        // for a scope config and the defaults stand in (unused — the command layer
+        // reads the ROOT config's feedback values; the comment lifecycle is global).
+        feedback: parsed.feedback ?? FEEDBACK_CONFIG_DEFAULTS,
     };
     return { config, raw: rawObject };
 }
@@ -185,6 +216,7 @@ export function loadAuthFromRoot(rootConfig, manifest) {
  * with the root config; the scope config activates after merge) instead of
  * failing the run on exactly the PR that introduces the scope.
  */
+// @ref LLP 0006#loading-and-the-config-dir-escape-hatch [implements] — deliberately bypasses ECR_CONFIG_DIR; scope subtrees stay repo-root-relative
 export function hasScopeConfig(root, scope) {
     if (scope.config === ".") {
         return true;
@@ -224,6 +256,7 @@ export async function loadScopeConfig(root, scope, manifest, rootConfig) {
         // loaded value here is only the manifest default, for display/doctor.
         commentTag = manifest.defaults.commentTag;
     }
+    // @ref LLP 0006#root-vs-scope-config [implements] — ROOT enforced agent always wins a same-id scope agent (risk 11)
     // Inject the enforced agents from the ROOT roster with alwaysRun, replacing any
     // same-id agent the scope defines (the enforced one wins — risk 11).
     const agents = base.agents.map((agent) => ({ ...agent }));
@@ -247,6 +280,12 @@ export async function loadScopeConfig(root, scope, manifest, rootConfig) {
         auth: loadAuthFromRoot(rootConfig, manifest),
         breakGlassMarker: rootConfig.breakGlassMarker,
         commentTag,
+        // Root-only, like stack: a non-default scope's `base` carries only the
+        // hardcoded placeholder (the scope schema rejects `feedback`), so re-derive
+        // from the root here or consumers of a nested scope's config would silently
+        // run the default policy instead of the repo's real one.
+        stack: rootConfig.stack,
+        feedback: rootConfig.feedback,
         scopeName: scope.name,
     };
 }

package/build/config/routing.js

@@ -1,3 +1,6 @@
+// @ref LLP 0006#routing-manifest — routing.jsonc parsing, scope resolution (last-match-wins), overlaps/unmatched
+// @ref LLP 0006#loading-and-the-config-dir-escape-hatch — routing.jsonc travels with config.jsonc via resolveConfigDir
+// @ref LLP 0006#budgets-and-chunking-defaults — per-scope budget split (scopePassesBudgetMs)
 import { readFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import path from "node:path";
@@ -15,6 +18,7 @@ export const ROUTING_FILENAME = "routing.jsonc";
  * Scope `config` paths stay repo-root-relative (see `loadScopeConfig`): an
  * override relocates only the ROOT artifacts, never the scopes' own subtrees.
  */
+// @ref LLP 0006#loading-and-the-config-dir-escape-hatch [implements] — travels with config.jsonc; a real bug once let them split
 export async function loadRoutingManifest(root, options = {}) {
     const manifestPath = path.join(resolveConfigDir(root, options.configDir), ROUTING_FILENAME);
     if (!existsSync(manifestPath)) {
@@ -30,6 +34,7 @@ export async function loadRoutingManifest(root, options = {}) {
 // silently miss root-level files (README.md, package.json). To give the double-star +
 // slash its conventional "zero or more directories" meaning, we also test the variant
 // with each such prefix removed, so the catch-all matches both `a.ts` and `src/b.ts`.
+// @ref LLP 0006#routing-manifest [constrained-by] — workaround for matchesIgnore's **-needs-a-slash limitation (LLP 0004 dialect)
 function patternVariants(pattern) {
     const collapsed = pattern.replace(/\*\*\//g, "");
     return collapsed !== pattern && collapsed.length > 0 ? [pattern, collapsed] : [pattern];
@@ -44,6 +49,7 @@ function scopeMatches(paths, file) {
  * matchesIgnore (supports ** across / and * within a segment — the manifest
  * documents this dialect). Deterministic, no filesystem access.
  */
+// @ref LLP 0006#routing-manifest [implements] — last-match-wins (CODEOWNERS discipline); each file lands in exactly one scope
 export function resolveScopes(manifest, changedFiles) {
     const buckets = new Map();
     const unmatched = [];
@@ -86,6 +92,7 @@ export function scopedCommentTag(rootTag, scopeName) {
  * starting — and `overshoot` flags that the run will exceed the total budget so
  * the caller can warn. Pure so the math is unit-testable.
  */
+// @ref LLP 0006#budgets-and-chunking-defaults [implements] — floor(total/active) clamped to a 5-min floor; overshoot flags the clamp
 export function scopePassesBudgetMs(totalMs, minMs, activeCount) {
     const count = Math.max(1, activeCount);
     const evenSplit = Math.floor(totalMs / count);

package/build/config/schema.js

@@ -1,5 +1,10 @@
+// @ref LLP 0006#root-vs-scope-config — schema for root vs. scope-overridable config keys
+// @ref LLP 0006#auth-config-shapes — auth union schema (legacy single credential + per-provider map)
+// @ref LLP 0006#routing-manifest — routing.jsonc manifest schema (scopes, budgets, traversal guard)
+// @ref LLP 0006#budgets-and-chunking-defaults — chunk/budget default values and re-tuning heuristics
 import path from "node:path";
 import { z } from "zod";
+import { CATEGORIES } from "../core/schema.js";
 export const ReviewConfigSchema = z.object({
     /** Default model for every agent + the coordinator. Override per-agent via
      * frontmatter in the agent's markdown, or globally via REVIEWER_MODEL. */
@@ -68,6 +73,7 @@ export const ReviewConfigSchema = z.object({
     // Union order matters: the map form must be tried FIRST — the legacy object's keys
     // all have defaults, so a non-strict legacy parse would accept (and gut) a
     // { providers } object by stripping the unknown key.
+    // @ref LLP 0006#auth-config-shapes [constrained-by] — map-first order is load-bearing; reordering silently guts multi-provider auth
     auth: z
         .union([
         z.object({
@@ -115,6 +121,77 @@ export const ReviewConfigSchema = z.object({
         skipLabel: z.string().default("ai-review:skip"),
     })
         .default({ trigger: "all", label: "ai-review", skipLabel: "ai-review:skip" }),
+    // Stack-aware requalification: walk the OPEN PRs stacked on top of this one and
+    // let the coordinator mark absence-style findings a later PR already addresses.
+    // ROOT-ONLY (one PR has one stack) and off by default — a suppression-adjacent
+    // feature earns trust with field data first. Under `ecr ci` it auto-enables from
+    // this trusted-base value; `ecr review --pr` needs an explicit --stack-aware.
+    // @ref LLP 0010#config-and-cli-surface [implements] — root-only + off-by-default; head config can never enable, widen, or disable it
+    stack: z
+        .object({
+        enabled: z.boolean().default(false),
+        maxDepth: z.number().int().positive().default(4),
+        // Children per level (per parent branch) the walk will follow.
+        maxPrs: z.number().int().positive().default(8),
+        maxFilesPerPr: z.number().int().positive().default(100),
+        // Only children whose author is the current PR's author enter the manifest —
+        // closes cross-author poisoning (a push-access colleague opening a child PR on
+        // the victim's branch). Set false from the trusted base for genuine team stacks.
+        requireSameAuthor: z.boolean().default(true),
+        // v2: confirm each requalification against the addressing PR's actual patch
+        // before believing it (a no-tools LLM reads the inlined patch). Default false so
+        // v2 ships dark until flipped; maxConfirmations bounds that cost.
+        confirmWithPatch: z.boolean().default(false),
+        maxConfirmations: z.number().int().positive().default(10),
+    })
+        .default({
+        enabled: false,
+        maxDepth: 4,
+        maxPrs: 8,
+        maxFilesPerPr: 100,
+        requireSameAuthor: true,
+        confirmWithPatch: false,
+        maxConfirmations: 10,
+    }),
+    // Author replies to findings: match them to the finding they answer, record
+    // them in the comment's embedded state, and (optionally) let a model judge the
+    // rebuttal against the source. ROOT-ONLY: the comment lifecycle is global.
+    // Defaults are deliberately ASYMMETRIC: `annotate` is on but `dismiss` is off.
+    // An adopting repo has its own config.jsonc and never re-copies this template,
+    // so a key it never set must still resolve to the safe, useful default via
+    // zod — annotating is safe and useful out of the box; suppressing a finding is
+    // not, so it stays opt-in.
+    // @ref LLP 0011#asymmetric-defaults [implements] — annotate on, dismiss off; adopting repos never re-copy the template
+    feedback: z
+        .object({
+        // "off"        — ignore replies entirely.
+        // "annotate"   — match + record + show "author replied" (no decision effect).
+        // "adjudicate" — also run a source-grounded judgment of the rebuttal and
+        //                record its verdict. Dismissal still obeys `dismiss`.
+        mode: z.enum(["off", "annotate", "adjudicate"]).default("annotate"),
+        // How a reply is MATCHED to a finding. Clearing one additionally requires the
+        // reply to cite its `id:` token in the replier's own words, whatever this says.
+        match: z.enum(["quote", "id", "both"]).default("both"),
+        // Who/what may actually remove a finding from the blocking set (always on a
+        // reply citing the finding's `id:` token — a quote only annotates):
+        //   "never"       — nothing does (default: adjudication ships dark).
+        //   "maintainers" — a maintainer reply dismisses, no model involved.
+        //   "adjudicated" — a maintainer reply, or an author reply the adjudicator
+        //                   confirmed against the source.
+        dismiss: z.enum(["never", "maintainers", "adjudicated"]).default("never"),
+        // Categories a reply can NEVER clear, whatever the verdict. Also hard-coded
+        // as a floor in code — this only widens the set, never narrows it.
+        protectedCategories: z.array(z.enum(CATEGORIES)).default(["secrets", "security"]),
+        // Cap on adjudication model calls per run.
+        maxAdjudications: z.number().int().positive().default(10),
+    })
+        .default({
+        mode: "annotate",
+        match: "both",
+        dismiss: "never",
+        protectedCategories: ["secrets", "security"],
+        maxAdjudications: 10,
+    }),
 });
 /** One routing scope: ordered globs → a directory containing .expo-code-review/. */
 export const RoutingScopeSchema = z.object({
@@ -126,6 +203,7 @@ export const RoutingScopeSchema = z.object({
      * routing.jsonc is read from the PR-head checkout, so this field is
      * PR-controllable input: absolute paths and `..` traversal are rejected so a
      * scope config can never resolve outside the repo. */
+    // @ref LLP 0006#routing-manifest [implements] — traversal guard; load.ts re-checks at runtime (defense in depth)
     config: z
         .string()
         .min(1)
@@ -159,6 +237,7 @@ export const RoutingManifestSchema = z
          * chain still fires the default when the key is absent, which would make
          * `defaults.auth` a phantom `{mode:'api-key',provider:'openai'}` for every
          * manifest that omits auth and silently override the root config's real auth. */
+        // @ref LLP 0006#routing-manifest [constrained-by] — zod v4 default().optional() trap; unwrap avoids a phantom auth stub
         auth: ReviewConfigSchema.shape.auth.unwrap().optional(),
         /** Agent ids injected into every scope with alwaysRun, from the ROOT roster. */
         enforceAgents: z.array(z.string()).default([]),
@@ -206,10 +285,13 @@ export const RoutingManifestSchema = z
  * standalone `ecr review --scope --post` always target the same marker — an
  * honored per-scope tag would let the two halves strand each other's comments.
  */
+// @ref LLP 0006#root-vs-scope-config [implements] — one of three enforcement layers; z.never fails at parse, not runtime
 export const ScopeReviewConfigSchema = ReviewConfigSchema.omit({
     auth: true,
     breakGlass: true,
     commentTag: true,
+    stack: true,
+    feedback: true,
 }).extend({
     auth: z
         .never({ error: "auth is locked to the root config; remove it from this scope config" })
@@ -220,4 +302,14 @@ export const ScopeReviewConfigSchema = ReviewConfigSchema.omit({
         error: "commentTag is locked: per-scope comment markers are derived as <rootTag>:<scope>; remove it from this scope config",
     })
         .optional(),
+    stack: z
+        .never({
+        error: "stack is locked to the root config (one PR has one stack); remove it from this scope config",
+    })
+        .optional(),
+    feedback: z
+        .never({
+        error: "feedback is locked to the root config (the comment lifecycle is global); remove it from this scope config",
+    })
+        .optional(),
 });