@expo/code-review-cli 0.7.0 → 0.8.0

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(),
 });

package/build/core/adjudicate.js

@@ -0,0 +1,194 @@
+import { addTokenUsage, promptAndParse, VERIFIER_AGENT } from "./opencode.js";
+import { buildAdjudicatorSystem, buildAdjudicatorTask } from "./prompts.js";
+import { parseAdjudication } from "./schema.js";
+import { errorMessage } from "./util.js";
+// Adjudication runs after coordination/verification (a serial tail step) and in
+// parallel over records; keep the per-call bound in the shape of the main verifier's
+// VERIFY_TIMEOUT_MS. A call that runs long finalizes on whatever it has.
+const ADJUDICATE_TIMEOUT_MS = 3 * 60 * 1000;
+// @ref LLP 0011#hard-floors-in-code [implements] — secrets/security can NEVER be cleared by a reply, whatever the config; a code floor `protectedCategories` can only widen, never narrow
+/** Categories no reply can ever clear, independent of the configured protected set. */
+export const HARD_FLOOR_CATEGORIES = ["secrets", "security"];
+/**
+ * Whether no config — current or future — can ever let a reply clear this finding.
+ * `feedbackApplied`'s floor and `adjudicateFeedback`'s "don't spend a model call on it"
+ * skip are the same question, so they read it from one place and cannot drift.
+ * Deliberately NOT `config.protectedCategories`/`dismiss`: those are user-tunable, so a
+ * stored verdict on such a finding becomes useful the moment the config changes.
+ */
+function hardFloored(finding) {
+    return finding.severity === "critical" || HARD_FLOOR_CATEGORIES.includes(finding.category);
+}
+// @ref LLP 0011#hard-floors-in-code [constrained-by] — dismissal is gated by `dismiss` alone (default "never"); critical + secrets/security are floored in code, and a prompt-injected verdict can't clear them
+/**
+ * Whether a reply actually removes this finding from the blocking set. `dismiss` is the
+ * one knob that gates clearing — it defaults to "never", so suppression is always an
+ * explicit opt-in. `mode` is a separate axis (how much machinery runs), so
+ * `dismiss: "maintainers"` works under `mode: "annotate"` with no model involved, the
+ * same trust gate as `/dismiss`. NEVER for a critical / secrets / security / protected
+ * finding — those floors live here in code, not in any prompt. A maintainer reply that
+ * CITES the finding's id clears; the PR author's cited reply clears only under
+ * `dismiss: "adjudicated"` with an "accepted" verdict. An untrusted third-party
+ * commenter (neither maintainer nor PR author) never clears — its reply is annotated
+ * only, as is any reply that merely quotes the finding.
+ */
+export function feedbackApplied(finding, record, config) {
+    if (config.mode === "off" || config.dismiss === "never") {
+        return false;
+    }
+    // @ref LLP 0011#a-quote-annotates-an-id-clears [implements] — a quote may annotate, only a cited id may clear, on BOTH clear paths below
+    // A quoted line is not consent: GitHub's "Quote reply" copies a comment the untrusted
+    // PR author wrote, so a maintainer can clear-by-accident (or be led to) on text they
+    // never authored. The `id:<fp>` token is printed only by our own comment and counts
+    // only outside a blockquote, so citing it is an act of the replier.
+    if (record.citedId !== true) {
+        return false;
+    }
+    // A human ran `/undismiss` on this reply-cleared finding: it is pinned back to the
+    // active list, so the still-present reply must not silently re-clear it.
+    if (record.unclearedByHuman) {
+        return false;
+    }
+    if (hardFloored(finding)) {
+        return false;
+    }
+    if (config.protectedCategories.includes(finding.category)) {
+        return false;
+    }
+    if (record.maintainer) {
+        return true;
+    }
+    // The adjudicated path is the PR author's alone. `record.author` is re-derived from
+    // the live comment's unspoofable login every run, so a random PR commenter — even
+    // with a model-accepted rebuttal — can never clear a finding.
+    return (config.dismiss === "adjudicated" && record.verdict === "accepted" && record.author === true);
+}
+// @ref LLP 0011#suppression-is-never-silent [implements] — a verdict binds to the source it judged; both merge paths (reporter + aggregate) share THIS predicate so they can never drift apart
+/**
+ * Strip a stored decision that no longer judges the source under review. A verdict is a
+ * claim about CODE, not only about words, and `fingerprintFinding` deliberately excludes
+ * the line number, so the author can edit away the code a rebuttal relied on while the
+ * finding keeps its identity. Unknown head — no `headSha` for this run, or a record
+ * written before the field existed — counts as different, never as trusted. A record
+ * with no verdict (a maintainer reply, an unjudged annotation) has no source-dependent
+ * decision and passes through untouched. The stale `applied` drops with the verdict:
+ * carrying `true` would hide the finding for one render before the recompute.
+ */
+export function dropStaleVerdict(record, headSha) {
+    if (record.verdict === undefined || (headSha !== undefined && record.sourceSha === headSha)) {
+        return record;
+    }
+    const { verdict: _verdict, reason: _reason, sourceSha: _sourceSha, ...rest } = record;
+    return { ...rest, applied: false };
+}
+// @ref LLP 0011#hard-floors-in-code [constrained-by] — the extra `gh pr view` runs only where the author flag can move an outcome; a skipped lookup reads exactly like a failed one (author:false, clears nothing)
+/**
+ * Whether the PR author's login has to be resolved at all for this config. The `author`
+ * flag gates exactly one thing — the adjudicated clear path in `feedbackApplied` (and,
+ * through it, which replies are worth a model call) — so under any other `dismiss`
+ * value resolving it is a `gh` call that can never move an outcome. Absent config (the
+ * `ecr feedback` crawl) resolves nothing, which is also the fail-closed answer: an
+ * unresolved author marks no reply as the author's and clears nothing.
+ */
+export function feedbackNeedsPrAuthor(config) {
+    return config?.dismiss === "adjudicated";
+}
+/**
+ * Whether the command layer must wire the runReview feedback seam at all: either a
+ * model judges replies ("adjudicate"), or replies may clear findings (`dismiss` opted
+ * in) and `applied` must be computed here even though no model runs. Everything else
+ * (annotate + never) is handled by the reporter at report time, with no seam.
+ */
+export function feedbackNeedsRunSeam(config) {
+    return config.mode === "adjudicate" || (config.mode !== "off" && config.dismiss !== "never");
+}
+/**
+ * Judge each author reply against the source and record its verdict, then recompute
+ * every record's `applied` flag under the hard floors. Bounded: at most
+ * `config.maxAdjudications` model calls per run, run in parallel; records past the cap
+ * are left unjudged and counted in `skipped` (never silently dropped). Fails open — a
+ * model/parse/timeout error on one record keeps it (verdict unset) and never throws.
+ * When mode !== "adjudicate" it makes no model calls at all and only recomputes
+ * `applied` — under `dismiss: "maintainers"` a maintainer reply still clears without
+ * any model; under `dismiss: "never"` nothing does.
+ *
+ * `sourceSha` is the head commit this run reviewed: every verdict decided here is
+ * stamped with it, so a later run can tell whether the verdict still judges the same
+ * source (see mergeFeedback). A source with no resolvable head OID (a local run) stamps
+ * nothing, which makes the verdict non-carrying rather than permanent.
+ */
+export async function adjudicateFeedback(handle, items, config, debug = () => { }, sourceSha) {
+    let cost = 0;
+    let model;
+    const tokens = {};
+    let failed = 0;
+    // Only judge in "adjudicate" mode, and only records without a verdict already decided
+    // on a prior run (the reporter carries those forward — re-judging would re-spend the
+    // budget on the same words). A reply with no text can't be judged. Only the PR
+    // author's replies are worth judging: a maintainer clears without any verdict, and a
+    // third-party commenter can never clear (feedbackApplied), so judging either would
+    // spend the budget on a rebuttal that changes no outcome. A reply that only quotes the
+    // finding can never clear it either, and would otherwise starve a cited reply of the
+    // cap. A finding a human already restored via `/undismiss` is likewise left unjudged.
+    // A hard-floored finding is skipped for the same reason and is deliberately NOT counted
+    // in `skipped` below: that figure means "reduced coverage, raise the cap", and a verdict
+    // no config could ever act on is not coverage a higher cap would buy back.
+    // @ref LLP 0011#hard-floors-in-code [constrained-by] — the code floor also means the model never judges a critical/secrets/security rebuttal: no verdict could move that outcome
+    const toJudge = config.mode === "adjudicate"
+        ? items.filter((item) => item.record.verdict === undefined &&
+            item.record.author === true &&
+            item.record.citedId === true &&
+            !item.record.unclearedByHuman &&
+            !hardFloored(item.finding) &&
+            item.replyText.trim() !== "")
+        : [];
+    // Never truncate silently: the first `maxAdjudications` are judged, the rest are
+    // reported as skipped so the caller can surface reduced coverage.
+    const within = toJudge.slice(0, config.maxAdjudications);
+    const skipped = toJudge.length - within.length;
+    if (skipped > 0) {
+        debug(`Feedback: ${skipped} repl${skipped === 1 ? "y" : "ies"} over ` +
+            `maxAdjudications=${config.maxAdjudications} — left unjudged this run.`);
+    }
+    // A successful call records the verdict against the record it judged; an error leaves
+    // it out of the map, so the record below stays untouched (fail open).
+    const judged = new Map();
+    await Promise.all(within.map(async (item, index) => {
+        try {
+            const { value, cost: callCost, tokens: callTokens, model: callModel, } = await promptAndParse(handle, {
+                // Reuse the verifier's OpenCode agent: it carries exactly the read+grep tool
+                // set the adjudicator needs (open the cited file, trace the path) and the
+                // reviewing model, and its distrust posture matches. The system prompt below
+                // is what makes this an adjudication rather than a verification.
+                agent: VERIFIER_AGENT,
+                system: buildAdjudicatorSystem(),
+                text: buildAdjudicatorTask(item.finding, item.replyText),
+                title: `adjudicate-${index}`,
+                maxWaitMs: ADJUDICATE_TIMEOUT_MS,
+                finalizeOnTimeout: true,
+            }, parseAdjudication);
+            cost += callCost;
+            addTokenUsage(tokens, callTokens);
+            model = callModel ?? model;
+            judged.set(item.record, { verdict: value.verdict, reason: value.reason });
+        }
+        catch (error) {
+            // Fail open: an error leaves the record unjudged and the finding intact.
+            failed++;
+            debug(`Feedback: could not adjudicate a reply (${errorMessage(error)}); leaving it unjudged.`);
+        }
+    }));
+    // Re-emit every record: set the verdict/reason where judged, then recompute `applied`
+    // under the hard floors (this also clears a maintainer reply, which needs no verdict).
+    const records = items.map((item) => {
+        const decision = judged.get(item.record);
+        // A fresh verdict is stamped with the source it judged (when the run knows it), so
+        // the next run re-judges the same reply once that source moves on.
+        // @ref LLP 0011#suppression-is-never-silent [implements] — the verdict is bound to the revision it was decided against
+        const withVerdict = decision
+            ? { ...item.record, verdict: decision.verdict, reason: decision.reason, sourceSha }
+            : item.record;
+        return { ...withVerdict, applied: feedbackApplied(item.finding, withVerdict, config) };
+    });
+    return { records, cost, tokens, model, adjudicated: judged.size, skipped, failed };
+}

package/build/core/auth.js

@@ -1,3 +1,4 @@
+// @ref LLP 0003#credential-resolution-and-forwarding [implements] — deny-list, cross-provider guard, isolated OAuth staging, and the forwarding-site recheck for Claude Code
 import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
@@ -32,7 +33,7 @@ const ANTHROPIC_TOKEN_ENVS = {
  * minted for that provider, so we hard-refuse these well-known unrelated secrets.
  * Defense-in-depth alongside loading config only from the trusted base ref.
  */
-const FORBIDDEN_TOKEN_ENVS = new Set([
+export const FORBIDDEN_TOKEN_ENVS = new Set([
     "GITHUB_TOKEN",
     "GH_TOKEN",
     "ACTIONS_RUNTIME_TOKEN",
@@ -154,6 +155,7 @@ export function checkOauthTokenShape(provider, token, tokenEnv) {
     }
     return ok;
 }
+// @ref LLP 0003#credential-resolution-and-forwarding [implements] — two deny checks: FORBIDDEN_TOKEN_ENVS refuses well-known unrelated secrets; the cross-provider ownership guard refuses a non-anthropic entry naming an ANTHROPIC_TOKEN_ENVS var
 /**
  * Decide whether ONE configured credential is usable, WITHOUT mutating the
  * environment. See checkProviderAuth for the all-entries wrapper.
@@ -398,6 +400,7 @@ export function jwtExpiryMs(token) {
  *   setup-token style bearers), far-future expiry so OpenCode never tries to
  *   refresh a credential that has no refresh half.
  */
+// @ref LLP 0003#credential-resolution-and-forwarding [implements] — JWT access tokens are used as-is and never refreshed; opaque tokens are stored with expires:0 for the codex refresh flow, only safe when this run is the token's sole consumer (refresh tokens are single-use)
 export function oauthAuthJsonEntry(provider, token) {
     if (provider === "openai" && !isJwtAccessToken(token)) {
         return { type: "oauth", access: "", refresh: token, expires: 0 };
@@ -420,6 +423,7 @@ export function oauthAuthJsonEntry(provider, token) {
  *   per-provider shapes). Isolated so it never touches the developer's real
  *   auth.json.
  */
+// @ref LLP 0003#credential-resolution-and-forwarding [implements] — stages all OAuth credentials into one isolated auth.json under a temp XDG_DATA_HOME; anthropic never passes through this path (its credential goes straight into startClaudeCode's child env)
 export async function prepareAuth(config) {
     const noop = { cleanup: async () => { } };
     // REVIEWER_MODEL is an explicit "use this model with my own creds" override — a

package/build/core/claude-code.js

@@ -1,8 +1,10 @@
+// @ref LLP 0003#claude-code-cli-containment [implements] — argv/env hardening for the claude -p subprocess
+// @ref LLP 0003#two-engines-per-agent-dispatch [implements] — anthropic/* routing and the per-agent engine map
 import { tmpdir } from "node:os";
 import path from "node:path";
 import { checkAuthEntry } from "./auth.js";
 import { pathInside, resolveOnPath, run } from "./exec.js";
-import { addTokenUsage, AgentTimeoutError, CLAUDE_CODE_ENGINE, CROSS_CUTTING_AGENT, VERIFIER_AGENT, withTransientRetry, } from "./opencode.js";
+import { addTokenUsage, AgentTimeoutError, CLAUDE_CODE_ENGINE, CROSS_CUTTING_AGENT, STACK_VERIFIER_AGENT, VERIFIER_AGENT, withTransientRetry, } from "./opencode.js";
 import { RateLimitWatch } from "./throttle.js";
 /** Coarse per-pass wander bound; the review's own maxWaitMs is the real ceiling. */
 const CLAUDE_MAX_TURNS = 60;
@@ -26,6 +28,7 @@ const READ_TOOL_MAP = {
     glob: "Glob",
 };
 const ALL_READ_TOOLS = ["Read", "Grep", "Glob"];
+// @ref LLP 0003#claude-code-cli-containment [implements] — deny enumeration (not allow-only) because an empty/absent --allowedTools list default-ALLOWS reads; verified against claude 2.1.212, revisit on every CLI version bump
 /**
  * Tools never available to a review pass, whatever the role. A DENY enumeration is
  * the only workable containment: permission rules cannot fail closed here — reads
@@ -102,6 +105,7 @@ const MISSING_CLI_MESSAGE = "The `claude` CLI is not installed. Install Claude C
  * served by the CLI; the retired anthropic-via-OpenCode x-api-key path no longer
  * exists (the CLI accepts an API key too).
  */
+// @ref LLP 0003#two-engines-per-agent-dispatch [implements] — engine choice is a pure function of the model id's provider prefix, no run-level auth-mode switch
 export function engineForModel(model) {
     const slash = model.indexOf("/");
     const provider = slash > 0 ? model.slice(0, slash) : model;
@@ -132,6 +136,8 @@ export function buildEngineMap(config, agents = config.agents) {
     const shared = config.agents[0]?.model ?? config.coordinator.model;
     modelOf[CROSS_CUTTING_AGENT] = shared;
     modelOf[VERIFIER_AGENT] = shared;
+    // @ref LLP 0010#patch-level-confirmation-v2 [constrained-by] — the id MUST live in modelOf/engineOf or a claude-routed run dispatches against an undefined handle and crashes
+    modelOf[STACK_VERIFIER_AGENT] = shared;
     modelOf["coordinator"] = config.coordinator.model;
     const engineOf = {};
     for (const [id, model] of Object.entries(modelOf)) {
@@ -330,6 +336,7 @@ export function usageLimitResetMs(errorText) {
  * reset time instead. The interpolated reset epoch is a long digit run with no
  * internal word boundary, so it can't spuriously match `\b429\b`/`\b50x\b`.
  */
+// @ref LLP 0003#retry-taxonomy [constrained-by] — message text deliberately avoids matching isTransientApiError's regex so a subscription cap fails fast rather than retrying
 export function usageLimitMessage(errorText) {
     const resetMs = usageLimitResetMs(errorText);
     const when = resetMs ? new Date(resetMs).toISOString() : "later";
@@ -577,6 +584,7 @@ export function claudeTokenCredential(entry, env = process.env) {
     }
     return { value, kind: value.startsWith("sk-ant-oat") ? "oauth" : "api-key" };
 }
+// @ref LLP 0003#credential-resolution-and-forwarding [implements] — re-runs checkAuthEntry at the forwarding site because REVIEWER_MODEL bypasses prepareAuth/checkProviderAuth entirely
 /** Start the Claude Code engine: resolve the CLI and build the subscription env. */
 export async function startClaudeCode(config) {
     const cliPath = await resolveOnPath("claude");
@@ -659,6 +667,9 @@ export async function startClaudeCode(config) {
     // consolidates findings and needs no repo tools.
     tools[CROSS_CUTTING_AGENT] = ["read", "grep"];
     tools[VERIFIER_AGENT] = ["read", "grep"];
+    // No tools: the addressing PR's patch is inlined into the task, so the stack
+    // verifier never reads the disk (mirrors the coordinator's empty list).
+    tools[STACK_VERIFIER_AGENT] = [];
     tools["coordinator"] = [];
     const defaultModel = config.agents[0]?.model ?? config.coordinator.model;
     return {

package/build/core/context-file.js

@@ -0,0 +1,42 @@
+import { open } from "node:fs/promises";
+// @ref LLP 0007#ecr-ci-the-trusted-root-run [constrained-by] — a missing/oversized context file WARNs and continues in ci; never fails checks
+/**
+ * Hard read ceiling for a `--context-file`. The file is read once in the command
+ * layer, byte-bounded here, then head/tail capped again for the prompt
+ * (CONTEXT_FILE_MAX_CHARS in prompts.ts). This ceiling bounds the read itself so a
+ * multi-gigabyte path can't exhaust memory before the prompt cap ever applies.
+ */
+export const MAX_CONTEXT_FILE_BYTES = 1_048_576; // 1 MiB
+const READ_CHUNK_BYTES = 65_536;
+/**
+ * Read an external context file as UTF-8 text. Throws on a missing/unreadable path
+ * or one over MAX_CONTEXT_FILE_BYTES — the command layer decides whether that is
+ * fatal (`ecr review`) or a warn-and-continue (`ecr ci`). The ceiling is enforced
+ * DURING the read, not by a stat beforehand: special files (`/dev/zero`, proc
+ * entries) report a small or zero size but read without end, and a regular file
+ * can grow between a stat and the read. Invalid UTF-8 decodes lossily
+ * (replacement chars); control chars are stripped later by sanitizeUntrusted.
+ */
+export async function readContextFile(filePath) {
+    const handle = await open(filePath, "r");
+    try {
+        const chunks = [];
+        let total = 0;
+        for (;;) {
+            const chunk = Buffer.alloc(READ_CHUNK_BYTES);
+            const { bytesRead } = await handle.read(chunk, 0, READ_CHUNK_BYTES);
+            if (bytesRead === 0) {
+                break;
+            }
+            total += bytesRead;
+            if (total > MAX_CONTEXT_FILE_BYTES) {
+                throw new Error(`context file too large (> 1 MiB): ${filePath}`);
+            }
+            chunks.push(chunk.subarray(0, bytesRead));
+        }
+        return Buffer.concat(chunks).toString("utf8");
+    }
+    finally {
+        await handle.close();
+    }
+}