feat(review): codebase-aware context beyond the diff (cross-file analysis)

[devops-thiago]

Sanitized 2026-08-13: the proposed solution originally offered two variants (fetch related files vs build a semantic/dependency index). It is now committed to the deterministic-first fetch design below; the index is recorded under Alternatives Considered. Part of the v0.8 phase of #669.

Problem Statement

Reviews see only the PR diff plus a base..head comparison, so the bot cannot reason about callers/callees outside the diff. The prompts have to legislate around unseen layers ("a sanitizer you cannot see is not a sanitizer"), and the verifier downgrades findings whose evidence lives outside the window. Cross-file bugs that diff-only review misses go uncaught, and correct findings get watered down.

Proposed Solution — deterministic extraction, one small selection call, bounded fetch

1. Deterministic reference extraction (free). From the diff itself, extract candidate related paths: import/package statements touched or surrounding changed hunks, plus symbols referenced by added lines. No model call; language-aware only to the depth of import-line parsing.
2. One small selection call (concise binding). Input: changed file list + extracted references + hunk headers — not diffs. Output: up to K paths worth fetching, each with a reason (caller / interface / sanitizer-or-validator / config-consumer). Ledger-gated (ReviewTokenLedger.ensureCallAllowed), counted in the maxAiCalls accounting, fail-open — no selection means the review proceeds exactly as today.
3. Bounded fetch + injection. Fetch selected files via the existing contents client, clip to the relevant regions, inject per batch as a fenced ## Related context (read-only, not part of the change) section — wrapped by PromptTemplateEscaper like every untrusted slot, capped at a fixed share of perCallInputBudget() the way PREVIOUS_FINDINGS_BUDGET_SHARE bounds the previous-findings block.
4. Feed the verifier too. Attach the fetched context to verification (per-finding via feat(review): targeted per-finding verification context — the verifier reads only the material each finding needs [opt-in] #668), turning "downgraded — not verifiable from the provided material" hedges into real confirm/reject verdicts.

Bounded by cost/latency and the per-PR spend cap (#42) by construction: one extra small call, and the injected context can never exceed its budget share.

Alternatives Considered

• Diff + base comparison only (current) — cheap and simple, but blind to cross-file impact.
• Lightweight semantic/dependency index of the repo — better recall on indirect relationships, but heavy for a small-footprint self-hosted bot (build, storage, invalidation per push). Revisit only if the fetch design measurably misses relationships that matter.

Priority

Important

Code of Conduct

• I have searched for existing issues and this is not a duplicate.

[devops-thiago]

Dogfood evidence — PR #99 (Fixes #95): the headline bug needed exactly this. evaluateCiChecks built a list of all CI checks while the caller (buildResult) gated APPROVE on !offendingCiChecks.isEmpty() — a producer/consumer mismatch split across two hunks. With only file.patch() in context (no enclosing functions/callers), the model could see both hunks but had no structural push to trace the contract between them. Pulling the full enclosing functions would make this class of cross-hunk bug visible. (Companion: the data-flow-contract rule that uses this context is filed separately as the producer→consumer trace dimension.)