@expo/code-review-cli 0.7.0 → 0.9.0

package/build/core/review.js

@@ -1,16 +1,21 @@
+// @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, CLAUDE_CODE_ENGINE, 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";
+import { reviewSetupRefNotes } from "./config-refs.js";
 import { verifyFindings } from "./verify.js";
 import { applyInlineIgnores } from "./suppress.js";
 /**
@@ -46,6 +51,7 @@ function makeRunId() {
  * credential that classifies as an API KEY is metered per-request and does NOT force
  * the cap. Exported for tests.
  */
+// @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;
@@ -77,9 +83,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.
@@ -158,6 +169,19 @@ export async function runReview(source, options) {
         progress("Reviewing the PR-head tree (so reads match the PR, not the checkout).");
         process.chdir(readRoot.dir);
     }
+    // Ref integrity of the setup that is about to review this PR. Resolved against the
+    // tree the reviewers read (PR head when materialized), while the setup itself may
+    // come from the trusted base ref — so a PR that moves cited code is reported against
+    // the prompts that will actually judge it.
+    // @ref LLP 0012#run-points-command-and-review [implements] — every review checks its own refs; advice only, never a gate
+    const setupNotes = await reviewSetupRefNotes({
+        root: readRoot?.dir ?? originalCwd,
+        setupDirs: [config.configDir],
+        changedFiles: kept.map((entry) => entry.path),
+    });
+    for (const note of setupNotes) {
+        progress(`  setup: ${note}`);
+    }
     const starting = [
         usesClaude ? "Claude Code engine" : null,
         usesOpencode ? "OpenCode server" : null,
@@ -259,6 +283,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) => {
@@ -349,6 +379,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
@@ -419,10 +450,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
@@ -460,6 +489,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`);
@@ -573,6 +608,13 @@ export async function runReview(source, options) {
         // 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".
@@ -592,7 +634,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);
@@ -620,8 +662,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);
@@ -639,6 +686,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);
@@ -647,17 +740,90 @@ 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).
@@ -698,6 +864,7 @@ export async function runReview(source, options) {
             agentFindings,
             coverageNotes,
             verifierDropped,
+            requalificationStrips,
             ...(rlTotal > 0
                 ? {
                     rateLimitEvents: rlTotal,
@@ -709,7 +876,10 @@ export async function runReview(source, options) {
             findingCount: output.findings.length,
             summary: output.summary,
         });
-        return output;
+        // Engine-owned: overwrite whatever the coordinator may have emitted under this key,
+        // so setup advice is always the checker's, never model text.
+        const reviewed = { ...output, setupNotes };
+        return feedbackRecords ? { ...reviewed, feedback: feedbackRecords } : reviewed;
     }
     catch (error) {
         await safeLog(logPath, {
@@ -734,13 +904,20 @@ export async function runReview(source, options) {
     }
 }
 /**
- * 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);
@@ -756,6 +933,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 = [];
@@ -795,6 +973,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.
@@ -810,6 +1089,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:
  *
@@ -913,6 +1204,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;