@expo/code-review-cli 0.7.0 → 0.8.0

package/build/commands/ci.js

@@ -1,13 +1,17 @@
+// @ref LLP 0007#ecr-ci-the-trusted-root-run — fails CLOSED: trusted-root materialization failure never falls back to reading the checkout
 import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { CONFIG_DIRNAME, hasScopeConfig, loadAuthFromRoot, loadReviewConfig, loadScopeConfig, tokenEnvMismatch, } from "../config/load.js";
 import { loadRoutingManifest, resolveScopes, scopedCommentTag, scopePassesBudgetMs, formatOwnerTable, } from "../config/routing.js";
 import { repoRoot, resolveTrustedTool, run } from "../core/exec.js";
 import { errorMessage, publicFailureReason } from "../core/util.js";
+import { readContextFile } from "../core/context-file.js";
 import { buildDiffLineIndex } from "../core/render.js";
+import { applyPins, collectPins, scopedFingerprint } from "../core/schema.js";
+import { dropStaleVerdict, feedbackApplied, feedbackNeedsRunSeam } from "../core/adjudicate.js";
 import { runReview } from "../core/review.js";
 import { GitHubPRSource } from "../sources/github-pr.js";
-import { memoizeSource } from "../sources/source.js";
+import { memoizeSource, stackConfirmFromConfig, stackWalkFromConfig } from "../sources/source.js";
 import { GitHubReporter } from "../reporters/github.js";
 /** Resolve the PR number from the Actions event payload or GITHUB_REF. */
 async function resolvePrNumber() {
@@ -63,7 +67,11 @@ Options:
                        prompts, model, auth mapping) that evaluates itself.
                        Never scaffolded; prints a security warning; will be
                        removed on a scheduled minor boundary.
+  --context-file <p>   Inject <p>'s UTF-8 text into reviewer prompts as UNTRUSTED
+                       external context (missing/oversized file: warn, continue)
   --comment <mode>     Override manifest comment mode: single | per-scope
+  --no-stack-aware     Force stack-aware requalification off for this run (it is
+                       otherwise auto-enabled from the trusted-base stack.enabled)
   --force              Manual override: review even if the trigger policy (label
                        trigger / ai-review:skip) would skip. Break-glass and the
                        auth lock still apply. A /review comment command implies this.
@@ -82,12 +90,18 @@ export async function ciCommand(argv = []) {
     const route = argv.includes("--route");
     const scopesFilter = parseListFlag(argv, "--scopes");
     const commentOverride = parseCommentMode(argv);
+    // Stack-aware review auto-enables from the trusted-base config; this argv escape
+    // hatch forces it off for one run. Safe to expose: it only ever makes the review
+    // more conservative (findings stay blocking).
+    const noStackAware = argv.includes("--no-stack-aware");
     // The ROOT config dir escape hatch (mirrors `ecr review`): an explicit
     // --config-dir wins, else resolveConfigDir falls back to ECR_CONFIG_DIR, else
     // the default .expo-code-review/. Applies to config.jsonc AND routing.jsonc.
     let configDir;
+    let contextFile;
     try {
         configDir = parseValueFlag(argv, "--config-dir");
+        contextFile = parseValueFlag(argv, "--context-file");
     }
     catch (error) {
         process.stderr.write(`${errorMessage(error)}\n\n${CI_USAGE}`);
@@ -103,6 +117,25 @@ export async function ciCommand(argv = []) {
         process.chdir(root);
     }
     const cwd = process.cwd();
+    // @ref LLP 0007#ecr-ci-the-trusted-root-run [implements] — --context-file degrades to no-context on read error; never fails checks
+    // Read the context file ONCE (routed CI runs runReview per scope; reading inside
+    // would re-read it N times). CI WARNS and continues on any read error: a broken
+    // Atlantis-provided plan file must never turn the PR's check red.
+    let contextText;
+    if (contextFile) {
+        try {
+            contextText = await readContextFile(contextFile);
+        }
+        catch (error) {
+            process.stderr.write(`CI reviewer: --context-file unusable, continuing without it: ${errorMessage(error)}\n`);
+        }
+        // Empty/whitespace-only plan file (e.g. Atlantis wrote nothing): warn and
+        // continue with no context — never fail the check on it.
+        if (contextText != null && !contextText.trim()) {
+            process.stderr.write(`CI reviewer: --context-file ${contextFile} is empty; continuing without context.\n`);
+            contextText = undefined;
+        }
+    }
     const repo = process.env.GITHUB_REPOSITORY;
     const prNumber = await resolvePrNumber();
     if (!repo || prNumber == null) {
@@ -113,6 +146,7 @@ export async function ciCommand(argv = []) {
     // the PR-head read root are each fetched once and shared across scopes.
     const ghSource = new GitHubPRSource({ prNumber, repo, cwd });
     const source = memoizeSource(ghSource);
+    // @ref LLP 0007#ecr-ci-the-trusted-root-run [implements] — trusted base config; fail closed with one hardcoded-tag terminal comment
     // Trusted configuration root: review policy and reviewer config load from the
     // PR's immutable BASE commit, so the PR head is data, never policy. Fail CLOSED:
     // when the base can't be materialized, post the one terminal comment and stop —
@@ -155,6 +189,8 @@ export async function ciCommand(argv = []) {
                 route,
                 bypassTriggerGate,
                 configDir,
+                contextText,
+                noStackAware,
             });
             return;
         }
@@ -166,6 +202,8 @@ export async function ciCommand(argv = []) {
                 commentOverride,
                 bypassTriggerGate,
                 configDir,
+                contextText,
+                noStackAware,
             });
         }
         catch (error) {
@@ -206,6 +244,144 @@ async function postTerminalFailureNote(repo, prNumber, cwd, reason) {
         process.stderr.write(`CI reviewer: also failed to post the failure notice: ${errorMessage(postError)}\n`);
     }
 }
+// @ref LLP 0011#the-rebuttal-is-a-hypothesis [constrained-by] — only "adjudicate" mode runs the model; the reporter reads the same comment it posts to, and `fpOf` keys records the same way that comment stores them, so a prior verdict carries and the same words are not re-judged
+/**
+ * The runReview feedback seam for a single-comment reporter. Wired when the mode
+ * judges replies ("adjudicate") OR when `dismiss` is opted in — a maintainer reply
+ * clearing a finding under `mode: "annotate"` needs the seam to compute `applied`,
+ * with no model call (see feedbackNeedsRunSeam). Otherwise the reporter matches
+ * replies itself at report time and the seam is absent (undefined). `fpOf` maps a
+ * finding to the fingerprint the target comment stores its feedback under
+ * (scope-namespaced for the aggregate comment, plain otherwise); omit it for the
+ * plain default.
+ */
+function adjudicationSeam(config, reporter, fpOf) {
+    if (!feedbackNeedsRunSeam(config.feedback)) {
+        return undefined;
+    }
+    return {
+        config: config.feedback,
+        match: (review) => reporter.matchAdjudicationItems(review, fpOf),
+    };
+}
+// @ref LLP 0011#hard-floors-in-code [constrained-by] — one reporter per comment, so the
+// PR-author lookup and the paginated comment list are fetched once per scope, not twice
+/**
+ * Memoize one value per scope name. Used for the per-scope GitHubReporter: a scope's
+ * feedback seam reads the very comment that scope's report writes, and each reporter
+ * instance holds its own comment-list TTL cache and bot-login memo, so a second instance
+ * for the same comment tag re-fetches the identical paginated comment list and re-resolves
+ * the login. Exported so that sharing is unit-testable.
+ */
+export function memoizeByScope(build) {
+    const cache = new Map();
+    return (scope) => {
+        let value = cache.get(scope);
+        if (value === undefined) {
+            value = build(scope);
+            cache.set(scope, value);
+        }
+        return value;
+    };
+}
+/**
+ * A freshly-reviewed scope's adjudicated feedback records, already keyed under the
+ * scope-namespaced ids the aggregate comment renders (the single-mode seam builds them
+ * with a scoped `fpOf`, see runRoutedCi), so they merge into the aggregate view as-is.
+ * A carried-over prior scope (no fresh feedback) contributes nothing here.
+ */
+function scopeFeedbackRecords(result) {
+    return result.review.feedback ?? [];
+}
+// @ref LLP 0011#the-rebuttal-is-a-hypothesis [constrained-by] — matchAdjudicationItems
+// throws on a seam fetch error BY DESIGN so the legacy/per-scope paths fall back to
+// computeFeedback's stored-state preservation; runReview leaves `review.feedback`
+// undefined in exactly that case (never `[]` — a successful-but-empty seam sets `[]`,
+// which is truthy, see scopeFeedbackRecords). This merge honors the same rule for the
+// aggregate comment: a scope's fresh records are authoritative for its findings'
+// fingerprints ONLY when its own seam actually returned records this run.
+// @ref LLP 0011#suppression-is-never-silent [implements] — the aggregate path applies
+// the SAME dropStaleVerdict rule as the reporter's mergeFeedback, so a verdict can never
+// clear a finding against a head it never judged just because this path was the one used.
+// @ref LLP 0011#the-rebuttal-is-a-hypothesis — fresh records come ONLY from `results`,
+// never `finalResults`: a carried scope's `finalResults` entry can still embed a stale
+// per-scope `review.feedback` copy from a past full run, which would resurrect a record
+// a human /undismiss already overrode at the top level.
+/**
+ * The aggregate comment's feedback records for comment:'single' mode, merging:
+ * - fresh records for scopes whose seam succeeded this run (`review.feedback` is an
+ *   array, possibly empty) — authoritative for their findings' fingerprints, so a
+ *   prior record with no fresh counterpart there means the reply is gone
+ *   (deleted/edited) and is dropped;
+ * - prior records for every OTHER fingerprint: carried-over scopes (a `--scopes`
+ *   partial run) AND a re-reviewed scope whose seam itself failed (`review.feedback`
+ *   stayed undefined) — so a transient GitHub fetch error can never delete a scope's
+ *   prior reply attributions/verdicts with nothing to replace them.
+ *
+ * Every record taken from `prior` first goes through `dropStaleVerdict` against
+ * `headSha` — the SAME rule mergeFeedback applies on the reporter side. Without it this
+ * path would re-apply a verdict decided against a head the run no longer reviews: a
+ * scope whose seam threw keeps its prior record, `feedbackApplied` never looks at
+ * `sourceSha`, and reportAggregate skips computeFeedback when it gets explicit records,
+ * so nothing else would ever check. Fresh records are NOT re-checked — they were just
+ * stamped with this run's own source.
+ *
+ * `applied` is recomputed on every kept record (idempotent for fresh ones) so a
+ * carried/fallback record also honors a `dismiss` policy that changed since it was
+ * stored. `results` is this run's freshly-reviewed scopes — the SOLE source of fresh
+ * records AND the set whose fingerprints are fresh-authoritative; a carried scope's
+ * prior records already ride the `prior` top-level map, so reading records back out of
+ * `finalResults` would re-inject a stale per-scope copy (e.g. one a human /undismiss
+ * already overrode at the top level). `finalResults` is the full set the aggregate
+ * comment renders (includes scopes carried over via `mergePartialAggregate`), used only
+ * to resolve each kept record's current finding. Pure so it's unit-testable.
+ */
+export function mergeAggregateFeedback(results, finalResults, prior, feedbackConfig, headSha, pins) {
+    const scopedFpOf = (result, finding) => scopedFingerprint(result.isDefault ? null : result.scope, finding);
+    const seamOkByScope = new Map(results.map((result) => [
+        result.scope,
+        result.review.feedback !== undefined,
+    ]));
+    const freshFps = new Set(results
+        .filter((result) => seamOkByScope.get(result.scope))
+        .flatMap((result) => result.review.findings.map((f) => scopedFpOf(result, f))));
+    const byFp = new Map(prior
+        .filter((record) => !freshFps.has(record.fp))
+        // A verdict decided against a head this run no longer reviews is dropped here,
+        // exactly as mergeFeedback drops it: the reply is judged again instead of
+        // clearing the finding against source it never saw.
+        .map((record) => [record.fp, dropStaleVerdict(record, headSha)]));
+    // Fresh records come only from THIS run's reviewed scopes; carried scopes'
+    // records already sit in `prior` above (a re-inject from `finalResults` would
+    // resurrect a stale per-scope copy over a newer top-level record).
+    for (const record of results.flatMap(scopeFeedbackRecords)) {
+        byFp.set(record.fp, record);
+    }
+    const findingByFp = new Map(finalResults.flatMap((result) => result.review.findings.map((f) => [scopedFpOf(result, f), f])));
+    // The maintainer `/undismiss` pins are state about FINDINGS, so they apply to fresh
+    // and carried records alike — a scope whose seam matched no reply this run must not
+    // hand back a record that a pin no longer covers.
+    const { records } = applyPins([...byFp.values()], collectPins(pins, prior));
+    return records.map((record) => {
+        const finding = findingByFp.get(record.fp);
+        return finding
+            ? { ...record, applied: feedbackApplied(finding, record, feedbackConfig) }
+            : record;
+    });
+}
+// @ref LLP 0010#config-and-cli-surface [implements] — under ci, stack-aware is gated by the trusted-base config; a stack walk failure only ever warns (source fails open), never a check failure
+/** Resolve the walk bounds when stack-aware is on (trusted-base enabled AND not
+ * forced off), else undefined (feature off → the manifest fetch is skipped). */
+function resolveStackWalk(stack, noStackAware) {
+    return stack.enabled && !noStackAware ? stackWalkFromConfig(stack) : undefined;
+}
+// @ref LLP 0010#patch-level-confirmation-v2 [constrained-by] — v2 rides the same trusted-base gate as the walk, plus stack.confirmWithPatch (default false, so it ships dark)
+/** Resolve the v2 patch-confirmation cap when the walk is on AND confirmWithPatch is
+ * set in the trusted-base config, else undefined (v2 off → grounding is the floor). */
+function resolveStackConfirm(stack, noStackAware) {
+    return stack.enabled && !noStackAware ? stackConfirmFromConfig(stack) : undefined;
+}
+// @ref LLP 0007#ecr-ci-the-trusted-root-run [constrained-by] — run logs anchor at the workspace, never the removed-on-exit trusted root
 /**
  * Run-log + patch-workspace anchor: ALWAYS the workspace checkout, never the
  * (temporary, removed-on-exit) trusted config root — the workflow uploads
@@ -219,7 +395,7 @@ function workspaceRunsDir(cwd) {
  * routing.jsonc the CLI behaves exactly as before (backcompat invariant).
  */
 async function runLegacyCi(source, repo, prNumber, cwd, configRoot, options) {
-    const { agents, route, bypassTriggerGate, configDir } = options;
+    const { agents, route, bypassTriggerGate, configDir, contextText, noStackAware } = options;
     let config;
     try {
         config = await loadReviewConfig(configRoot, { configDir });
@@ -228,6 +404,7 @@ async function runLegacyCi(source, repo, prNumber, cwd, configRoot, options) {
         process.stderr.write(`CI reviewer: ${errorMessage(error)}\n`);
         return;
     }
+    // @ref LLP 0007#verify-config-the-config-guard [implements] — runtime auth lock; the workflow bash sweep is only layer 2
     // Layer-1 auth lock (mirrors doctor): when the workflow pins the expected token
     // env var name, refuse to run if the config names anything else. The workflow's
     // bash guard is a text sweep (layer 2) and can't see through JSON escapes; this
@@ -240,17 +417,32 @@ async function runLegacyCi(source, repo, prNumber, cwd, configRoot, options) {
             return;
         }
     }
+    // @ref LLP 0007#trigger-policy-and-break-glass [implements] — exact-match labels; /review bypasses only the trigger gate
     // Config-driven trigger policy (.expo-code-review/config.jsonc → review): decide
     // whether this PR should be reviewed at all (bypassed by a manual /review).
     if (!passesTriggerGate(await fetchPrLabels(repo, prNumber, cwd), config.review, bypassTriggerGate)) {
         return;
     }
+    // The head commit this run reviews: it binds every adjudication verdict to the source
+    // it judged, so a stored verdict carries to the next run only while the head is
+    // unchanged (see mergeFeedback). Memoized on the source — no extra API call. A
+    // metadata failure leaves it unknown, which re-judges replies instead of trusting a
+    // verdict against source we cannot pin.
+    let headSha;
+    try {
+        headSha = (await source.getMetadata()).headOid;
+    }
+    catch {
+        // leave headSha unset → stored verdicts do not carry (fail safe, costs budget only)
+    }
     const reporter = new GitHubReporter({
         prNumber,
         repo,
         commentTag: config.commentTag,
         breakGlassMarker: config.breakGlassMarker,
         cwd,
+        feedback: config.feedback,
+        headSha,
     });
     try {
         if (await reporter.checkBreakGlass()) {
@@ -268,10 +460,18 @@ async function runLegacyCi(source, repo, prNumber, cwd, configRoot, options) {
             mode: "ci",
             agents,
             route,
+            contextText,
+            stack: resolveStackWalk(config.stack, noStackAware),
+            stackConfirm: resolveStackConfirm(config.stack, noStackAware),
             runsDir: workspaceRunsDir(cwd),
+            // Adjudicate mode judges the matched replies against the source before the
+            // comment is rendered; annotate mode lets the reporter match them at report
+            // time. Either way the feedback path is fail-open (runReview swallows its own
+            // errors), so it never fails the PR's checks.
+            feedback: adjudicationSeam(config, reporter),
             onProgress: (message) => process.stderr.write(`${message}\n`),
         });
-        await reporter.report(review);
+        await reporter.report(review, review.feedback);
         process.stderr.write(`CI reviewer: posted review (${review.decision}).\n`);
     }
     catch (error) {
@@ -303,9 +503,10 @@ function failureReview(scopeName, reason) {
         incomplete: [],
     };
 }
+// @ref LLP 0007#routed-ci-fan-out [implements] — root tag wins; sequential per-scope budgets; partial --scopes merges prior state
 /** The routing fan-out: one process, N scopes reviewed sequentially, one render. */
 async function runRoutedCi(source, manifest, repo, prNumber, cwd, configRoot, options) {
-    const { agents, route, scopesFilter, commentOverride, bypassTriggerGate, configDir } = options;
+    const { agents, route, scopesFilter, commentOverride, bypassTriggerGate, configDir, contextText, noStackAware, } = options;
     // The root config + manifest follow the override; scope configs stay
     // relative to the TRUSTED root (loadScopeConfig reads
     // <configRoot>/<scope.config>/.expo-code-review).
@@ -397,11 +598,15 @@ async function runRoutedCi(source, manifest, repo, prNumber, cwd, configRoot, op
         prNumber,
         diffLines: buildDiffLineIndex(changed.map((file) => ({ path: file.path, patch: file.patch }))),
     };
+    // The reviewed head OID also binds each adjudication verdict to the source it judged
+    // (see mergeFeedback); unresolved leaves it unknown, so verdicts are re-judged.
+    let headSha;
     try {
-        const { baseOid } = await source.getMetadata();
+        const { baseOid, headOid } = await source.getMetadata();
         if (baseOid) {
             link.baseSha = baseOid;
         }
+        headSha = headOid;
     }
     catch {
         // leave baseSha unset → out-of-diff findings degrade to plain text
@@ -417,6 +622,35 @@ async function runRoutedCi(source, manifest, repo, prNumber, cwd, configRoot, op
         const expectedMinutes = Math.round((active.length * budget) / 60_000);
         process.stderr.write(`CI reviewer: ⚠ ${active.length} scopes × floor = ${expectedMinutes}min exceeds budget.totalPassesMinutes (${manifest.budget.totalPassesMinutes}m); expect longer runs — raise the job timeout or trim scopes.\n`);
     }
+    // One PR has one stack: resolve the walk once from the ROOT (trusted-base) config
+    // and share it across every scope. The source memoizes the actual fetch.
+    const stackWalk = resolveStackWalk(rootConfig.stack, noStackAware);
+    const stackConfirm = resolveStackConfirm(rootConfig.stack, noStackAware);
+    const reporterFor = (tag, withLink = false) => new GitHubReporter({
+        prNumber,
+        repo,
+        commentTag: tag,
+        breakGlassMarker: rootConfig.breakGlassMarker,
+        cwd,
+        linkContext: withLink ? link : undefined,
+        // Root-only feedback config (see loadScopeConfig): lets a reporter posting with
+        // no explicit records match replies itself (annotate mode) at report time.
+        feedback: rootConfig.feedback,
+        headSha,
+    });
+    // comment:'single' mode: every active scope's feedback seam AND the final
+    // aggregate post target the SAME root-tag comment, so share one reporter
+    // instance (and its comment-list/login cache, see GitHubReporter's
+    // `fetchAllComments` TTL cache) across the whole run — a fresh reporter per
+    // scope would otherwise re-fetch the paginated comment list and re-resolve
+    // the bot login once per scope for the identical comment.
+    const singleModeReporter = mode === "single" ? reporterFor(rootTag, true) : undefined;
+    // Per-scope mode has the same property, one comment tag at a time: a scope's feedback
+    // seam reads the very comment that scope's review is posted to, so both must use the
+    // same instance or each scope re-fetches its comment list and re-resolves the bot
+    // login. `withLink` is inert for the seam (matchAdjudicationItems renders nothing), so
+    // one link-carrying reporter serves both uses.
+    const scopeReporter = memoizeByScope((name) => reporterFor(scopedCommentTag(rootTag, name), true));
     const results = [];
     for (const scope of active) {
         const scopeDef = manifest.scopes.find((entry) => entry.name === scope.name);
@@ -435,14 +669,28 @@ async function runRoutedCi(source, manifest, repo, prNumber, cwd, configRoot, op
                 effectiveScopeDef = { ...scopeDef, config: "." };
             }
             const config = await loadScopeConfig(configRoot, effectiveScopeDef, manifest, rootConfig);
+            // The seam reads the replies off the comment this scope's review will land
+            // in — the aggregate (root) comment in "single" mode, the scoped comment
+            // otherwise — so prior verdicts carry. The fingerprint the records are keyed
+            // under must match how THAT comment stores them: scope-namespaced for the
+            // aggregate comment, plain for the scoped one. Feedback is root-only, so gate on it.
+            const feedbackSeam = feedbackNeedsRunSeam(rootConfig.feedback)
+                ? adjudicationSeam(rootConfig, mode === "single" ? singleModeReporter : scopeReporter(scope.name), mode === "single"
+                    ? (finding) => scopedFingerprint(isDefault ? null : scope.name, finding)
+                    : undefined)
+                : undefined;
             review = await runReview(source, {
                 config,
                 mode: "ci",
                 agents,
                 route,
                 includePaths: scope.files,
+                contextText,
+                stack: stackWalk,
+                stackConfirm,
                 passesBudgetMs: budget,
                 runsDir: workspaceRunsDir(cwd),
+                feedback: feedbackSeam,
                 onProgress: (message) => process.stderr.write(`[${scope.name}] ${message}\n`),
             });
         }
@@ -452,34 +700,36 @@ async function runRoutedCi(source, manifest, repo, prNumber, cwd, configRoot, op
         }
         results.push({ scope: scope.name, isDefault, review });
     }
-    const reporterFor = (tag, withLink = false) => new GitHubReporter({
-        prNumber,
-        repo,
-        commentTag: tag,
-        breakGlassMarker: rootConfig.breakGlassMarker,
-        cwd,
-        linkContext: withLink ? link : undefined,
-    });
     if (mode === "single") {
-        const aggregate = reporterFor(rootTag, true);
+        const aggregate = singleModeReporter;
         let finalResults = results;
         if (scopesFilter) {
             // A partial run (--scopes) is authoritative ONLY for the named scopes: merge
             // the other scopes' previous results out of the existing aggregate comment's
             // state so re-running one scope doesn't silently discard the rest.
             const prior = (await aggregate.readState())?.scopes ?? [];
-            const byName = new Map(results.map((result) => [result.scope, result]));
-            for (const previous of prior) {
-                if (!scopesFilter.includes(previous.scope) && !byName.has(previous.scope)) {
-                    byName.set(previous.scope, previous);
-                }
-            }
-            // Manifest order; scopes no longer in the manifest drop out.
-            finalResults = manifest.scopes
-                .map((scope) => byName.get(scope.name))
-                .filter((entry) => entry != null);
+            finalResults = mergePartialAggregate(results, prior, scopesFilter, manifest.scopes.map((scope) => scope.name));
+        }
+        if (finalResults.length === 0) {
+            // No scope has anything to report (no changed file matched any scope, and no
+            // prior scope results carry over): a review of nothing is not a review, so
+            // post nothing and delete a stale aggregate comment from an earlier run
+            // instead of leaving it up. The unmatched-files warning stays in the job log.
+            // @ref LLP 0007#routed-ci-fan-out — zero active scopes → no comment
+            await aggregate.clear();
+        }
+        else {
+            // A seam-backed run hands the reporter the computed records (re-keyed to the
+            // scope-namespaced ids the aggregate renders under). Without the seam it
+            // passes none and the reporter matches replies itself.
+            const aggState = feedbackNeedsRunSeam(rootConfig.feedback)
+                ? await aggregate.readState()
+                : null;
+            const aggFeedback = feedbackNeedsRunSeam(rootConfig.feedback)
+                ? mergeAggregateFeedback(results, finalResults, aggState?.feedback ?? [], rootConfig.feedback, headSha, aggState?.pins)
+                : undefined;
+            await aggregate.reportAggregate(finalResults, resolution.unmatched, aggFeedback);
         }
-        await aggregate.reportAggregate(finalResults, resolution.unmatched);
         // Clean up any per-scope comments from a previous per-scope run. A partial run
         // only ever touches the named scopes' comments.
         for (const scope of manifest.scopes) {
@@ -488,7 +738,9 @@ async function runRoutedCi(source, manifest, repo, prNumber, cwd, configRoot, op
             }
             await reporterFor(scopedCommentTag(rootTag, scope.name)).clear();
         }
-        process.stderr.write(`CI reviewer: posted aggregate review for ${finalResults.length} scope(s).\n`);
+        process.stderr.write(finalResults.length === 0
+            ? "CI reviewer: no scope matched the changed files; nothing posted.\n"
+            : `CI reviewer: posted aggregate review for ${finalResults.length} scope(s).\n`);
     }
     else {
         for (const scope of manifest.scopes) {
@@ -497,10 +749,12 @@ async function runRoutedCi(source, manifest, repo, prNumber, cwd, configRoot, op
             if (scopesFilter && !scopesFilter.includes(scope.name)) {
                 continue;
             }
-            const reporter = reporterFor(scopedCommentTag(rootTag, scope.name), true);
+            // The same instance the scope's feedback seam already used (its comment-list and
+            // login caches are per-instance), so the report reuses that fetch.
+            const reporter = scopeReporter(scope.name);
             const result = results.find((entry) => entry.scope === scope.name);
             if (result) {
-                await reporter.report(result.review);
+                await reporter.report(result.review, result.review.feedback);
             }
             else {
                 // A reconciled scope with zero matched files gets its stale comment deleted.
@@ -517,6 +771,23 @@ async function runRoutedCi(source, manifest, repo, prNumber, cwd, configRoot, op
         process.stderr.write("CI reviewer: posted per-scope reviews.\n");
     }
 }
+/**
+ * Merge a partial run's fresh results (--scopes) with the prior aggregate
+ * comment's stored state, in manifest order. Fresh results win for their scope;
+ * scopes outside the filter keep their previous result; scopes no longer in the
+ * manifest drop out. Pure so it's unit-testable.
+ */
+export function mergePartialAggregate(results, prior, scopesFilter, manifestScopeNames) {
+    const byName = new Map(results.map((result) => [result.scope, result]));
+    for (const previous of prior) {
+        if (!scopesFilter.includes(previous.scope) && !byName.has(previous.scope)) {
+            byName.set(previous.scope, previous);
+        }
+    }
+    return manifestScopeNames
+        .map((name) => byName.get(name))
+        .filter((entry) => entry != null);
+}
 /**
  * Current PR labels via gh (more authoritative than the possibly-stale event
  * payload); on failure, returns [] so a label-read hiccup never silently skips a

package/build/commands/dismiss.js

@@ -1,3 +1,4 @@
+// @ref LLP 0007#init-and-dismiss [implements] — display-only mutation; dismissals persist across re-reviews, never re-run the review
 import { loadReviewConfig } from "../config/load.js";
 import { repoRoot, resolveRepo } from "../core/exec.js";
 import { errorMessage } from "../core/util.js";
@@ -33,6 +34,7 @@ function parseArgs(argv) {
                 if (arg.startsWith("--")) {
                     throw new Error(`Unknown argument: ${arg}`);
                 }
+                // @ref LLP 0007#init-and-dismiss — a malformed id is silently mangled to hex, not rejected; it just becomes "unmatched" later
                 // Bare arg = a finding id. Sanitize to the fingerprint alphabet.
                 args.ids.push(arg.replace(/[^a-f0-9]/g, ""));
         }
@@ -78,6 +80,10 @@ export async function dismissCommand(argv, mode) {
             commentTag: config.commentTag,
             breakGlassMarker: config.breakGlassMarker,
             cwd,
+            // The re-render re-derives every feedback record's `applied` flag, so it needs the
+            // feedback policy in force now — without it a reply-cleared finding would be
+            // un-hidden by an unrelated /dismiss.
+            feedback: config.feedback,
         });
         const result = await reporter.applyDismissal(mode === "add" ? args.ids : [], mode === "remove" ? args.ids : [], args.by, args.reason);
         if (mode === "add") {

package/build/commands/doctor.js

@@ -1,3 +1,4 @@
+// @ref LLP 0007#doctor-and-setup-auth — a preflight that must never disagree with a real run
 import { loadReviewConfig, loadScopeConfig, loadAuthFromRoot, hasConfig, resolveConfigDir, tokenEnvMismatch, } from "../config/load.js";
 import { loadRoutingManifest, resolveScopes, scopePassesBudgetMs, formatOwnerTable, } from "../config/routing.js";
 import readline from "node:readline/promises";
@@ -39,6 +40,7 @@ async function opencodeVersion(cliPath) {
     }
     return stdout.trim().split("\n")[0]?.trim() || null;
 }
+// @ref LLP 0007#doctor-and-setup-auth [implements] — folds routed scopes' models in; silently skips unloadable scope configs by design
 /**
  * The engines this repo actually drives, mirroring how real reviews resolve them:
  * engineForModel over every ROOT agent + coordinator model, PLUS every loaded scope
@@ -236,6 +238,7 @@ export async function doctorCommand(argv = []) {
                         if (version.code === 0) {
                             line(true, `claude ${version.stdout.trim().split("\n")[0]?.trim()}`);
                         }
+                        // @ref LLP 0007#doctor-and-setup-auth [constrained-by] — mirrors startClaudeCode's condition exactly; warn() never flips the exit code
                         // Mirror startClaudeCode's credential condition EXACTLY so doctor fails
                         // iff a review would: a run needs an active `claude` subscription login OR
                         // a token value (the configured tokenEnv, else an ambient