@expo/code-review-cli 0.6.0 → 0.8.0

package/build/core/review.js

@@ -1,12 +1,17 @@
+// @ref LLP 0002#pipeline-stages [implements] — the mode-agnostic pipeline core owning budgets, coverage, and logging
 import path from "node:path";
 import { prepareAuth } from "./auth.js";
 import { coordinate } from "./coordinator.js";
 import { writeRunLog } from "./log.js";
 import { filterNoise, writePatchWorkspace } from "./noise.js";
-import { addTokenUsage, AgentTimeoutError, assertModelsResolvable, buildOpencodeConfig, CROSS_CUTTING_AGENT, promptAndParse, startOpencode, } from "./opencode.js";
+import { addTokenUsage, AgentTimeoutError, assertModelsResolvable, buildOpencodeConfig, CLAUDE_CODE_ENGINE, CROSS_CUTTING_AGENT, promptAndParse, STACK_VERIFIER_AGENT, startOpencode, } from "./opencode.js";
+import { buildEngineMap, claudeTemperatureNote, claudeTokenCredential, startClaudeCode, } from "./claude-code.js";
 import { routeAgents } from "./router.js";
 import { buildCrossCuttingSystem, buildCrossCuttingTask, buildReviewerSystem, buildReviewerTask, NO_TOOLS_INSTRUCTION, } from "./prompts.js";
-import { fingerprintFinding, parseReviewerOutput } from "./schema.js";
+import { fingerprintFinding, isOverallRiskHandoff, parseReviewerOutput } from "./schema.js";
+import { adjudicateFeedback } from "./adjudicate.js";
+import { buildManifestMembership, manifestKey, normalizeManifestPath } from "./stack.js";
+import { confirmStackRequalifications, patchConfirmer } from "./stack-confirm.js";
 import { sortFindings } from "./render.js";
 import { appendStepSummary } from "./step-summary.js";
 import { errorMessage, sleep } from "./util.js";
@@ -33,18 +38,36 @@ function makeRunId() {
  * thin wrappers that supply a Source and render the result.
  */
 /**
- * Max concurrent reviewer calls: an explicit config value wins; otherwise 3 when a
- * subscription (oauth) credential is configured, else 6. One ChatGPT account
- * handles six parallel streams poorly — requests get parked server-side (the
- * stall signature seen on eas-cli#4084), and several PRs may be reviewing on the
- * same credential at once — so subscription runs trade a little wall-clock for a
- * lot of reliability. Exported for tests.
+ * Max concurrent reviewer calls: an explicit config value wins; otherwise 3 when the
+ * run leans on a subscription credential, else 6. One subscription account handles
+ * six parallel streams poorly — requests get parked server-side (the stall signature
+ * seen on eas-cli#4084), and several PRs may be reviewing on the same credential at
+ * once — so subscription runs trade a little wall-clock for a lot of reliability.
+ *
+ * A subscription run is any of: an oauth (ChatGPT/Codex) entry; OR the Claude Code
+ * engine being in use (an `anthropic/…` model) on an OAUTH credential — a subscription
+ * token OR the local `claude` login fallback (no forwardable token). An anthropic
+ * credential that classifies as an API KEY is metered per-request and does NOT force
+ * the cap. Exported for tests.
  */
-export function effectiveConcurrency(config) {
+// @ref LLP 0002#concurrency-and-budgets [implements] — compound oauth/API-key detection is load-bearing, not simplifiable
+export function effectiveConcurrency(config, env = process.env) {
     if (config.chunk.concurrency) {
         return config.chunk.concurrency;
     }
-    return config.auth.some((entry) => entry.mode === "oauth") ? 3 : 6;
+    if (config.auth.some((entry) => entry.mode === "oauth")) {
+        return 3;
+    }
+    if (buildEngineMap(config).usesClaude) {
+        const entry = config.auth.find((auth) => auth.provider === "anthropic");
+        const credential = claudeTokenCredential(entry, env);
+        // No forwardable token ⇒ the `claude` login (a subscription) covers the run; an
+        // "sk-ant-oat…" token is a subscription too. Either caps; an API key does not.
+        if (!credential || credential.kind === "oauth") {
+            return 3;
+        }
+    }
+    return 6;
 }
 export async function runReview(source, options) {
     const { config } = options;
@@ -59,9 +82,14 @@ export async function runReview(source, options) {
     const explicitAgents = options.agents?.length
         ? selectAgents(config.agents, options.agents)
         : null;
-    const [metadata, changedFiles] = await Promise.all([
+    const [metadata, changedFiles, stackManifest] = await Promise.all([
         source.getMetadata(),
         source.getChangedFiles(),
+        // Only walk when enabled AND the source can (LocalGitSource omits the method).
+        // The source itself fails open to null, so this never rejects the Promise.all.
+        options.stack && source.getStackContextAsync
+            ? source.getStackContextAsync(options.stack)
+            : Promise.resolve(null),
     ]);
     // Scope isolation: when includePaths is set, this run only ever sees its own
     // scope's files — no scope reviews another team's diff.
@@ -105,6 +133,18 @@ export async function runReview(source, options) {
     // with a base-SHA checkout the fallback tree is pre-PR content, and silently
     // reviewing/verifying that drops real findings — while a local run falls back to
     // the user's own checkout with a warning.
+    // Resolve each agent's engine BEFORE prepareAuth/readRoot, so the per-engine
+    // startup below can't leak the readRoot worktree or a temp auth dir holding a
+    // live credential (buildEngineMap only inspects config, so nothing needs cleanup
+    // yet at this point). Nothing throws here anymore — one run may drive BOTH the
+    // Claude Code CLI engine and OpenCode at once, inferred per agent from its model.
+    //
+    // Scope the engine set to the SELECTED agents so a run whose passes never touch
+    // Claude doesn't start (and fail on a missing CLI/token for) the Claude Code
+    // engine. An explicit `--agents` subset is known here; routing picks from the full
+    // roster later (its router needs an engine up first), so a routed/all run keeps
+    // the full roster and can drive either engine.
+    const { engineOf, modelOf, usesOpencode, usesClaude } = buildEngineMap(config, explicitAgents ?? config.agents);
     const originalCwd = process.cwd();
     const readRoot = await resolveReadRoot(source, options.mode, progress);
     // Prepare auth BEFORE the chdir below: it doesn't depend on the working directory,
@@ -128,10 +168,21 @@ export async function runReview(source, options) {
         progress("Reviewing the PR-head tree (so reads match the PR, not the checkout).");
         process.chdir(readRoot.dir);
     }
-    progress("Starting OpenCode server…");
-    let handle = null;
+    const starting = [
+        usesClaude ? "Claude Code engine" : null,
+        usesOpencode ? "OpenCode server" : null,
+    ]
+        .filter(Boolean)
+        .join(" + ");
+    progress(`Starting ${starting}…`);
+    // Start each engine the run actually uses. OpenCode first so a claude failure can
+    // close it. Two separate try blocks keep the precise per-engine error messages.
+    let opencodeHandle = null;
+    let claudeHandle = null;
     try {
-        handle = await startOpencode(buildOpencodeConfig(config));
+        if (usesOpencode) {
+            opencodeHandle = await startOpencode(buildOpencodeConfig(config));
+        }
     }
     catch (error) {
         await auth.cleanup();
@@ -139,11 +190,71 @@ export async function runReview(source, options) {
         throw new Error(`Failed to start the OpenCode server. Ensure the \`opencode\` CLI is installed and ` +
             `model credentials are configured (\`ecr doctor\` checks both).\n${errorMessage(error)}`);
     }
-    // Preflight: a model id the server can't resolve would otherwise fail EVERY pass
-    // identically — N indistinguishable coverage gaps, after spending the run's budget
-    // discovering the same fixable thing N times. Throw once, up front, naming the fix.
     try {
-        await assertModelsResolvable(handle, [...config.agents.map((agent) => agent.model), config.coordinator.model], config.auth);
+        if (usesClaude) {
+            claudeHandle = await startClaudeCode(config);
+        }
+    }
+    catch (error) {
+        opencodeHandle?.close();
+        await auth.cleanup();
+        await restoreCwd();
+        throw new Error(`Failed to start the Claude Code engine. Ensure the \`claude\` CLI is installed and ` +
+            `logged into a Max/Team subscription (\`ecr doctor\` checks both).\n${errorMessage(error)}`);
+    }
+    // Build the single carrier handle so every downstream `handle` call is unchanged;
+    // per-agent dispatch happens inside via engineOf. When OpenCode is in use the
+    // carrier is the opencode handle (claude reached via `.claude`); a claude-only run
+    // uses the claude handle itself as the carrier (engineOf maps every id → claude).
+    const engineFn = (agent) => engineOf[agent] ?? "opencode";
+    let handle;
+    if (opencodeHandle) {
+        handle = opencodeHandle;
+        handle.claude = claudeHandle ?? undefined;
+        handle.engineOf = engineFn;
+        const closeOpencode = opencodeHandle.close;
+        handle.close = () => {
+            closeOpencode();
+            claudeHandle?.close(); // claude close is a noop, but keep the composition explicit
+        };
+    }
+    else {
+        handle = claudeHandle; // claude-only: the carrier is the claude handle itself
+        handle.engineOf = engineFn;
+    }
+    // The claude-code engine has no temperature control (the CLI exposes no flag), so
+    // surface a tuned-but-ignored temperature once, here, instead of letting the config
+    // divergence pass silently. Applies whenever any pass is claude-routed.
+    if (usesClaude) {
+        const note = claudeTemperatureNote(config, engineOf);
+        if (note) {
+            progress(`Note: ${note}`);
+        }
+    }
+    // Preflight: a model id an engine can't resolve would otherwise fail EVERY pass
+    // routed to it identically — N indistinguishable coverage gaps, after spending the
+    // run's budget rediscovering the same fixable thing. Throw once, up front, naming
+    // the fix. Split per engine so each engine only ever sees its own model subset: the
+    // OpenCode server never receives an anthropic-claude id (unknown-provider error) and
+    // assertClaudeModels never receives a non-anthropic id (its foreign-id throw).
+    const modelsFor = (eng) => [
+        ...new Set(Object.keys(engineOf)
+            .filter((id) => engineOf[id] === eng)
+            .map((id) => modelOf[id])),
+    ];
+    try {
+        if (opencodeHandle) {
+            const models = modelsFor("opencode");
+            if (models.length > 0) {
+                await assertModelsResolvable(opencodeHandle, models, config.auth);
+            }
+        }
+        if (claudeHandle) {
+            const models = modelsFor("claude-code");
+            if (models.length > 0) {
+                await assertModelsResolvable(claudeHandle, models, config.auth);
+            }
+        }
     }
     catch (error) {
         handle.close();
@@ -158,6 +269,12 @@ export async function runReview(source, options) {
     // reviewers produced before the failure — partial findings are exactly what's
     // needed to debug a run that died mid-way.
     const agentFindings = {};
+    // First reviewer (by scheduling order) that produced each fingerprint, so a finding's
+    // originating agent can be carried through the coordinator's merge/rewrite by matching
+    // on fingerprint. Kept separate from agentFindings so the coordinator prompt and the
+    // run log stay byte-identical (attribution is engine metadata, never sent to a model).
+    // @ref LLP 0011#attribution-and-identity [constrained-by] — engine-set, excluded from fingerprintFinding, so attribution never re-keys a dismissal
+    const agentByFp = new Map();
     // Every model request's usage lands in the run total AND its bucket, so the run
     // log can show cache effectiveness per pass and not just run-wide.
     const trackTokens = (bucket, tokens) => {
@@ -172,6 +289,10 @@ export async function runReview(source, options) {
     // log, reported in the log line, and surfaced as a coverage note when it happens.
     const agentModels = {};
     const substituted = new Set();
+    // The buckets whose model was substituted, so the coverage note can name each
+    // one's OWN engine (a mixed run may substitute on either side, for different
+    // reasons — a CLI usage-limit downgrade vs. OpenCode's silent default fallback).
+    const substitutedBuckets = new Set();
     const trackModel = (bucket, configured, actual) => {
         if (!actual) {
             return;
@@ -179,6 +300,7 @@ export async function runReview(source, options) {
         agentModels[bucket] = actual;
         if (configured && actual !== configured) {
             substituted.add(`${bucket}: configured ${configured}, ran ${actual}`);
+            substitutedBuckets.add(bucket);
         }
     };
     try {
@@ -243,6 +365,7 @@ export async function runReview(source, options) {
         // whole-diff no-tools fallback with, and "elastic budget" would have quietly
         // reintroduced the coverage gap it exists to prevent. Sized for the finalize
         // soft-landing plus one FALLBACK_TIMEOUT_MS pass.
+        // @ref LLP 0002#the-cross-cutting-pass [constrained-by] — not a trimmable margin; funds the whole-diff fallback on timeout
         const CROSS_CUTTING_RESERVE_MS = FALLBACK_TIMEOUT_MS + 4 * 60 * 1000;
         // Floor: never LESS generous than one chunk pass. On a run whose window is already
         // small (many active scopes dividing the budget) this can exceed what's left, but
@@ -313,10 +436,8 @@ export async function runReview(source, options) {
         // smaller file set); a fallback task forbids tools and reviews the inlined diff.
         const buildTaskText = (task) => {
             const base = task.kind === "cross-cutting"
-                ? buildCrossCuttingTask(task.files, selectedAgents, filtered, {
-                    noTools: task.fallback,
-                })
-                : buildReviewerTask(task.files, workspace.files, filtered);
+                ? buildCrossCuttingTask(task.files, selectedAgents, filtered, { noTools: task.fallback }, options.contextText)
+                : buildReviewerTask(task.files, workspace.files, filtered, options.contextText);
             return task.fallback ? `${base}\n\n${NO_TOOLS_INSTRUCTION}` : base;
         };
         const filesLabel = (files) => files.length === 1
@@ -354,6 +475,12 @@ export async function runReview(source, options) {
                 trackTokens(task.bucket, tokens);
                 trackModel(task.bucket, taskModel(task), model);
                 (agentFindings[task.bucket] ??= []).push(...value.findings);
+                for (const finding of value.findings) {
+                    const fp = fingerprintFinding(finding);
+                    if (!agentByFp.has(fp)) {
+                        agentByFp.set(fp, task.bucket);
+                    }
+                }
                 completedPasses++;
                 if (truncated) {
                     progress(`  ${task.label}: hit its budget — returned partial findings`);
@@ -448,15 +575,32 @@ export async function runReview(source, options) {
             for (const line of substituted) {
                 progress(`  ⚠ model substituted — ${line}`);
             }
+            const subEngines = new Set([...substitutedBuckets].map((bucket) => engineOf[bucket] ?? "opencode"));
+            const why = [];
+            if (subEngines.has(CLAUDE_CODE_ENGINE)) {
+                why.push("The Claude Code CLI answered with a different model than configured (usage-limit " +
+                    "downgrades do this on a subscription), so these findings may come from a weaker " +
+                    "model than intended — check the configured model ids and the subscription's limits.");
+            }
+            if (subEngines.has("opencode")) {
+                why.push("OpenCode silently falls back to a default model when the configured id is empty or " +
+                    "unusable, so these findings may come from a different (possibly much weaker) model " +
+                    "than intended — check the agents' `model`, `coordinator.model`, REVIEWER_MODEL, and the provider credential.");
+            }
             incomplete.push(`Some passes did not run on the configured model (${[...substituted].join("; ")}). ` +
-                `OpenCode silently falls back to a default model when the configured id is empty or ` +
-                `unusable, so these findings may come from a different (possibly much weaker) model ` +
-                `than intended — check the agents' \`model\`, \`coordinator.model\`, REVIEWER_MODEL, and the provider credential.`);
+                why.join(" "));
         }
         // Note: routine noise filtering (lockfiles, generated, binary) is expected and
         // NOT a coverage gap — it stays in the run log (filteredFiles), not the
         // user-facing coverage note, which is reserved for passes that didn't finish.
         const coverageNotes = [...new Set(incomplete)];
+        // Severity LOCK: capture which FILES carried a critical/secrets/security reviewer
+        // finding BEFORE the coordinator can lower or rewrite it. groundStackRequalification
+        // uses this so a coordinator steered into "downgrade critical→warning, then
+        // requalify" can't slip a real critical past the carve-out. Built here (after the
+        // fan-out populated agentFindings) whether or not the stack feature is on — cheap,
+        // and keeps the grounding call unconditional.
+        const preCoordinationFileLocks = buildPreCoordinationFileLocks(agentFindings);
         let output;
         if (completedPasses === 0) {
             // Nothing succeeded — do NOT let this render as a clean "approve".
@@ -476,7 +620,7 @@ export async function runReview(source, options) {
             progress("Coordinating findings…");
             let consolidated;
             try {
-                const { output: rawOutput, cost, tokens: coordinatorTokens, truncated: coordinatorTruncated, model: coordinatorModel, } = await coordinate(handle, config, metadata, agentFindings, coverageNotes);
+                const { output: rawOutput, cost, tokens: coordinatorTokens, truncated: coordinatorTruncated, model: coordinatorModel, } = await coordinate(handle, config, metadata, agentFindings, coverageNotes, stackManifest);
                 agentCosts["coordinator"] = cost;
                 trackTokens("coordinator", coordinatorTokens);
                 trackModel("coordinator", config.coordinator.model, coordinatorModel);
@@ -504,8 +648,13 @@ export async function runReview(source, options) {
         // Guard against hallucinated findings before surfacing: quote-ground every
         // finding against the real file, and adversarially verify criticals. This is
         // what stops a confident but wrong critical from shipping.
+        // @ref LLP 0002#post-coordination-order [constrained-by] — verify must run before suppress; order is load-bearing
         const findingCountBeforeChecks = output.findings.length;
+        const decisionBeforeChecks = output.decision;
         let verifierDropped = [];
+        // Stripped requalifications (finding + reason), persisted to the run log so the
+        // stack-aware decision trail is auditable after the fact — mirrors verifierDropped.
+        const requalificationStrips = [];
         if (output.findings.length > 0) {
             progress("Verifying findings…");
             const verification = await verifyFindings(handle, output.findings, process.cwd(), progress);
@@ -523,6 +672,52 @@ export async function runReview(source, options) {
                 };
             }
         }
+        // Stack-aware requalification grounding (deterministic, zero LLM): strip any
+        // `requalifiedBy` the coordinator wrote that is forged, hallucinated, or touches a
+        // protected finding class, then re-derive the decision over the still-BLOCKING
+        // (non-requalified) subset. Runs between verify and suppress, preserving the
+        // load-bearing verify → ground → suppress → reconcile order.
+        // @ref LLP 0010#grounding-and-the-decision [constrained-by] — must run after verify and before suppress; a stripped requalification means the finding stays fully blocking
+        if (output.findings.length > 0) {
+            // The decision entering this block (post-verify, pre-requalification softening)
+            // is the ceiling both grounding and confirmation re-derive against: confirmation
+            // returns findings to blocking, so re-running decisionAfterRequalification over
+            // the post-confirmation set re-hardens up to this value, never past it.
+            const decisionBeforeRequalification = output.decision;
+            const grounding = groundStackRequalification(output.findings, stackManifest, preCoordinationFileLocks, progress);
+            requalificationStrips.push(...grounding.stripped);
+            let grounded = grounding.findings;
+            // v2 patch confirmation (gated by stack.confirmWithPatch): for the requalifications
+            // that survived grounding, read the addressing PR's actual patch and strip any not
+            // clearly addressed. Fail toward blocking on any fetch/verify error or timeout.
+            // @ref LLP 0010#patch-level-confirmation-v2 [constrained-by] — runs right after grounding, before the decision is re-derived; never materializes the patch
+            if (options.stackConfirm &&
+                stackManifest &&
+                grounded.some((finding) => finding.requalifiedBy)) {
+                progress("Confirming stacked-PR requalifications against their patches…");
+                const confirmation = await confirmStackRequalifications(grounded, options.stackConfirm.maxConfirmations, patchConfirmer(handle, source), progress);
+                grounded = confirmation.findings;
+                requalificationStrips.push(...confirmation.strippedFindings);
+                agentCosts[STACK_VERIFIER_AGENT] = confirmation.cost;
+                trackTokens(STACK_VERIFIER_AGENT, confirmation.tokens);
+                trackModel(STACK_VERIFIER_AGENT, config.agents[0]?.model ?? config.coordinator.model, confirmation.model);
+                if (confirmation.stripped > 0) {
+                    progress(`Stack confirmation returned ${confirmation.stripped} requalified finding(s) to blocking.`);
+                }
+            }
+            output = {
+                ...output,
+                findings: grounded,
+                // decisionAfterGrounding only re-derives when a requalification SURVIVED
+                // grounding + confirmation: with none, the coordinator's decision must stand
+                // untouched — an unconditional decisionAfterRequalification here would
+                // soften every non-critical request_changes on every run, stack feature or
+                // not. Criticals never carry requalifiedBy (grounding strips it), so the
+                // later decisionAfterRequalification call in the suppression block cannot
+                // re-escalate past this softened decision.
+                decision: decisionAfterGrounding(decisionBeforeRequalification, grounded),
+            };
+        }
         // Inline `expo-code-review-ignore` directives suppress non-critical findings.
         if (output.findings.length > 0) {
             const { kept, suppressed } = await applyInlineIgnores(output.findings, process.cwd(), progress);
@@ -531,24 +726,109 @@ export async function runReview(source, options) {
                 output = {
                     ...output,
                     findings: kept,
-                    decision: decisionAfterVerification(output.decision, kept),
+                    // decisionAfterRequalification, NOT decisionAfterVerification: `kept` may
+                    // still hold requalified (non-blocking) findings, and the decision must be
+                    // re-derived over the BLOCKING subset — else suppressing the last blocking
+                    // finding leaves a stale approve_with_comments. With no requalifications
+                    // the two derivations are identical.
+                    decision: decisionAfterRequalification(output.decision, kept),
                 };
             }
         }
         // The coordinator's summary was written against the pre-check finding set, so if
         // verification/suppression removed anything it can now reference issues that are
         // no longer listed. Reconcile the summary so it never contradicts the findings.
+        // A decision change WITHOUT a count drop gets its own note: only requalification
+        // does that — every finding is still listed, so the "removed" wording of the
+        // count-drop note would be factually wrong there.
         const removedAfterChecks = findingCountBeforeChecks - output.findings.length;
         if (removedAfterChecks > 0) {
             output = { ...output, summary: reconcileSummary(output.summary, output.findings.length) };
         }
+        else if (output.decision !== decisionBeforeChecks) {
+            output = { ...output, summary: reconcileRequalifiedSummary(output.summary) };
+        }
+        // Attribution: carry each surviving finding's originating agent onto the output. The
+        // coordinator merges and rewrites findings, so match by fingerprint and keep the
+        // first agent that produced it; a finding the coordinator changed enough to break the
+        // fingerprint stays unattributed (reported as "unknown") rather than guessed. Agent
+        // is excluded from the fingerprint, so setting it can never lapse a dismissal. This
+        // lookup is the ONLY writer: the model-facing schema drops any `agent` the
+        // coordinator emitted, so nothing here has to trust (or defer to) model attribution.
+        // @ref LLP 0011#attribution-and-identity [implements] — attribution rides through the coordinator by fingerprint; annotation-only, and engine-set only
+        if (agentByFp.size > 0 && output.findings.length > 0) {
+            output = {
+                ...output,
+                findings: output.findings.map((finding) => {
+                    const agent = agentByFp.get(fingerprintFinding(finding));
+                    return agent ? { ...finding, agent } : finding;
+                }),
+            };
+        }
+        // Author-feedback adjudication (ships dark): when the caller supplied feedback input
+        // and the mode is on, match the replies to the final findings and — in "adjudicate"
+        // mode — judge each rebuttal against the source, then record the verdict and whether
+        // it cleared the finding. Fails open: any error leaves the review untouched, so the
+        // feedback path can never break a review (`ecr ci` must never fail a PR's checks).
+        // @ref LLP 0011#the-rebuttal-is-a-hypothesis [implements] — runs after verification, before reporting; the hard floors and the cap live in adjudicate.ts, not the prompt
+        let feedbackRecords;
+        if (options.feedback && options.feedback.config.mode !== "off") {
+            try {
+                const items = await options.feedback.match(output);
+                const adjudication = await adjudicateFeedback(handle, items, options.feedback.config, progress, 
+                // The revision each verdict is judged against: the PR head OID this run
+                // materialized and read from. A source without one (local git) stamps
+                // nothing, so its verdicts never carry to a later run.
+                metadata.headOid);
+                feedbackRecords = adjudication.records;
+                agentCosts["adjudicator"] = adjudication.cost;
+                trackTokens("adjudicator", adjudication.tokens);
+                trackModel("adjudicator", config.agents[0]?.model ?? config.coordinator.model, adjudication.model);
+                // Never silent: a capped or failed adjudication is a reduced-coverage fact.
+                if (adjudication.skipped > 0 || adjudication.failed > 0) {
+                    const parts = [];
+                    if (adjudication.skipped > 0) {
+                        parts.push(`${adjudication.skipped} left unjudged over the maxAdjudications=${options.feedback.config.maxAdjudications} cap`);
+                    }
+                    if (adjudication.failed > 0) {
+                        parts.push(`${adjudication.failed} could not be judged (the source check failed)`);
+                    }
+                    output = {
+                        ...output,
+                        incomplete: [
+                            ...new Set([
+                                ...output.incomplete,
+                                `Author-reply adjudication was reduced this run: ${parts.join("; ")}. ` +
+                                    `Those replies carry no verdict and cleared no finding.`,
+                            ]),
+                        ],
+                    };
+                }
+            }
+            catch (error) {
+                // Fail open — feedback never breaks a review.
+                progress(`Author-reply adjudication failed (${errorMessage(error)}); continuing without it.`);
+            }
+        }
         // Surface provider throttling as a fact about the run: passes already waited or
         // backed off, but the operator should still SEE that it happened (a run that
         // was rate-limited is slower and may carry partial passes — that's the cause).
-        await handle.rateLimit.check();
-        if (handle.rateLimit.events > 0) {
-            progress(`  ⚠ provider rate-limited this run ${handle.rateLimit.events} time(s) ` +
-                `(429s in the OpenCode server log) — passes waited it out rather than failing`);
+        // Sum both engines' watches; name a cause only for an engine whose watch fired
+        // (claude events arrive via note() in runClaudePrompt; opencode via its server log).
+        await opencodeHandle?.rateLimit.check();
+        const rlOpencode = opencodeHandle?.rateLimit.events ?? 0;
+        const rlClaude = claudeHandle?.rateLimit.events ?? 0;
+        const rlTotal = rlOpencode + rlClaude;
+        if (rlTotal > 0) {
+            const causes = [];
+            if (rlClaude > 0) {
+                causes.push("subscription rate/usage limits reported by the Claude Code CLI");
+            }
+            if (rlOpencode > 0) {
+                causes.push("429s in the OpenCode server log");
+            }
+            progress(`  ⚠ provider rate-limited this run ${rlTotal} time(s) (${causes.join("; ")}) ` +
+                `— passes waited it out rather than failing`);
         }
         // Every pass says which model actually answered it — in the job log, the step
         // summary table, and the run log — so a wrong or substituted model is always
@@ -570,13 +850,19 @@ export async function runReview(source, options) {
             agentFindings,
             coverageNotes,
             verifierDropped,
-            ...(handle.rateLimit.events > 0 ? { rateLimitEvents: handle.rateLimit.events } : {}),
+            requalificationStrips,
+            ...(rlTotal > 0
+                ? {
+                    rateLimitEvents: rlTotal,
+                    rateLimitByEngine: { opencode: rlOpencode, claudeCode: rlClaude },
+                }
+                : {}),
             durationMs: Date.now() - started,
             decision: output.decision,
             findingCount: output.findings.length,
             summary: output.summary,
         });
-        return output;
+        return feedbackRecords ? { ...output, feedback: feedbackRecords } : output;
     }
     catch (error) {
         await safeLog(logPath, {
@@ -595,19 +881,26 @@ export async function runReview(source, options) {
         throw error;
     }
     finally {
-        handle?.close();
+        handle.close();
         await auth.cleanup();
         await restoreCwd();
     }
 }
 /**
- * Policy backstop: drop suggestions unless opted in, cap by count (most severe
- * first), and downgrade approve_with_comments to approve when nothing remains.
+ * Policy backstop: strip the internal risk handoff, drop suggestions unless
+ * opted in, cap by count (most severe first), and downgrade
+ * approve_with_comments to approve when nothing remains.
  */
 export function applyReviewPolicy(output, policy) {
-    let findings = policy.includeSuggestions
-        ? output.findings
-        : output.findings.filter((finding) => finding.severity !== "suggestion");
+    // Unconditional, and before the severity filter: the handoff is `suggestion`-
+    // severity, so `includeSuggestions: true` would otherwise publish it as a
+    // finding whenever the coordinator forgot to strip it. It is prompt-authored
+    // metadata for the coordinator's summary, never something an author should see.
+    // @ref LLP 0009#prompt-rules-for-adopters [implements] — code-level strip, not prompt-only
+    let findings = output.findings.filter((finding) => !isOverallRiskHandoff(finding));
+    if (!policy.includeSuggestions) {
+        findings = findings.filter((finding) => finding.severity !== "suggestion");
+    }
     findings = sortFindings(findings);
     if (policy.maxFindings != null) {
         findings = findings.slice(0, policy.maxFindings);
@@ -623,6 +916,7 @@ export function applyReviewPolicy(output, policy) {
  * Merges + de-dupes (by fingerprint), applies the same policy, and picks a
  * conservative decision (never a clean approve when there are findings).
  */
+// @ref LLP 0002#coordinator-and-degraded-decisions [implements] — coordinator failure must never discard already-collected findings
 function fallbackConsolidation(agentFindings, policy) {
     const seen = new Set();
     const merged = [];
@@ -662,6 +956,107 @@ export function decisionAfterVerification(previous, kept) {
     }
     return previous;
 }
+/**
+ * The normalized FILES where any reviewer emitted a critical, `secrets`, or `security`
+ * finding PRE-coordination. This is the severity LOCK: no finding on such a file is
+ * requalifiable, no matter what the coordinator later assigns it. Keyed on the file
+ * alone — NOT a content fingerprint — because the coordinator legitimately
+ * re-categorizes and paraphrases findings, and a fingerprint over those mutable
+ * fields would let a downgraded-then-reworded critical dodge the lock. Over-locking
+ * a whole file only keeps findings blocking (the feature's fail direction).
+ * Exported for tests.
+ */
+// @ref LLP 0010#grounding-and-the-decision [implements] — pre-coordination file locks defeat downgrade-then-requalify
+export function buildPreCoordinationFileLocks(agentFindings) {
+    const locked = new Set();
+    for (const findings of Object.values(agentFindings)) {
+        for (const finding of findings) {
+            if (finding.severity === "critical" ||
+                finding.category === "secrets" ||
+                finding.category === "security") {
+                locked.add(normalizeManifestPath(finding.file));
+            }
+        }
+    }
+    return locked;
+}
+// @ref LLP 0010#grounding-and-the-decision [implements] — deterministic zero-LLM floor over data ecr fetched itself; strips forged/hallucinated/protected requalifications even with a prompt-injected coordinator
+/**
+ * Strip a finding's `requalifiedBy` (leaving the finding itself fully intact and
+ * blocking) when any of these hold — every check is over data the coordinator cannot
+ * influence:
+ *  - the cited `(prNumber, file)` is not an EXACT normalized member of the fetched
+ *    manifest (forged or hallucinated citation);
+ *  - the finding is `critical` severity, or category `secrets` or `security`;
+ *  - the finding's FILE carried a pre-coordination critical/secrets/security reviewer
+ *    finding (severity lock — keyed on the file, so a coordinator re-categorization
+ *    or paraphrase cannot dodge it).
+ * Returns the grounded findings plus every stripped requalification (finding +
+ * reason): a debug line covers the live stderr stream, and the caller persists the
+ * strips to the run log (mirroring verifierDropped) so a silent under-fire stays
+ * diagnosable after the run. Exported for tests.
+ */
+export function groundStackRequalification(findings, manifest, lockedFiles, debug = () => { }) {
+    const members = manifest ? buildManifestMembership(manifest) : new Set();
+    const stripped = [];
+    const grounded = findings.map((finding) => {
+        const requalified = finding.requalifiedBy;
+        if (!requalified) {
+            return finding;
+        }
+        const strip = (reason) => {
+            debug(`Stack: stripped requalification on "${finding.file}" (${reason}).`);
+            const { requalifiedBy: _dropped, ...rest } = finding;
+            stripped.push({ finding: rest, reason });
+            return rest;
+        };
+        if (finding.severity === "critical") {
+            return strip("critical severity is never requalifiable");
+        }
+        if (finding.category === "secrets" || finding.category === "security") {
+            return strip(`${finding.category} category is never requalifiable`);
+        }
+        if (lockedFiles.has(normalizeManifestPath(finding.file))) {
+            return strip("a reviewer emitted a critical/secrets/security finding on this file (severity lock)");
+        }
+        if (!members.has(manifestKey(requalified.prNumber, requalified.file))) {
+            return strip(`cited #${requalified.prNumber} "${requalified.file}" is not an exact manifest member`);
+        }
+        return finding;
+    });
+    return { findings: grounded, stripped };
+}
+/**
+ * Re-derive the decision after requalification over the still-BLOCKING (non-requalified)
+ * findings only — the parallel of decisionAfterVerification. Requalified findings stay
+ * shown and counted but never block: no blocking findings → approve; a request_changes
+ * with no blocking critical left → soften to approve_with_comments. Exported for tests.
+ */
+// @ref LLP 0010#grounding-and-the-decision [implements] — decision is computed over the active subset, so a requalified warning stops blocking but stays visible
+export function decisionAfterRequalification(previous, findings) {
+    const blocking = findings.filter((finding) => !finding.requalifiedBy);
+    if (blocking.length === 0) {
+        return "approve";
+    }
+    if (previous === "request_changes" &&
+        !blocking.some((finding) => finding.severity === "critical")) {
+        return "approve_with_comments";
+    }
+    return previous;
+}
+/**
+ * The grounding block's decision step: re-derive ONLY when a requalification
+ * survived grounding. With none (the overwhelmingly common case — stack feature
+ * off, or every requalification stripped), the incoming decision stands untouched:
+ * re-deriving unconditionally would soften every non-critical request_changes on
+ * every run, silently overriding the coordinator's (and any adopter rubric's)
+ * decision policy. Exported for tests.
+ */
+export function decisionAfterGrounding(previous, findings) {
+    return findings.some((finding) => finding.requalifiedBy)
+        ? decisionAfterRequalification(previous, findings)
+        : previous;
+}
 /**
  * The coordinator writes its summary before findings are verified/suppressed, so a
  * post-coordination drop can leave the summary referencing issues no longer shown.
@@ -677,6 +1072,18 @@ export function reconcileSummary(summary, remaining) {
         "this summary was written, so it may mention issues no longer listed below._\n\n" +
         summary);
 }
+/**
+ * The decision-changed-without-removal reconcile: requalification softened the
+ * decision while keeping every finding listed, so the summary prose (written before
+ * grounding ran) can read stricter than the final decision. Nothing was removed —
+ * the note must not claim it was. Exported for tests.
+ */
+export function reconcileRequalifiedSummary(summary) {
+    return ("_Note: after this summary was written, some findings were requalified as " +
+        "addressed in stacked PRs — they are still listed below but no longer block, " +
+        "so the prose may read stricter than the final decision._\n\n" +
+        summary);
+}
 /**
  * Resolve the tree the review reads from, applying the mode's trust policy:
  *
@@ -780,6 +1187,7 @@ const QUEUE_IDLE_POLL_MS = 100;
  * running (a running worker might yet enqueue more), so dynamically-added work is
  * never lost. `fn` receives the item and an `enqueue` callback.
  */
+// @ref LLP 0002#timeouts-stalls-and-subdivision [implements] — terminates on active===0, not queue-empty, so growth mid-drain isn't lost
 export async function runGrowableQueue(initial, limit, fn) {
     const queue = [...initial];
     let active = 0;