feat(rag): evaluate a local cross-encoder/cosine rerank stage alongside BM25

[JSONbored]

Part of #4325.

Context

src/review/rag.ts:507/src/review/rag-wire.ts:191-201 rerank RAG retrieval candidates with lexical BM25 only (reranker: "bm25") — already shipped and working (#1124). There is no embedding-based or cross-encoder rerank stage, despite the query's own bge-m3 embedding already being computed at retrieval time (rag.ts:435) and sitting idle after the initial cosine search. Unlike the other items in this batch, this is explicitly NOT a known bottleneck — it's an evaluation, not a guaranteed win.

Requirements

• This is a MEASURE-FIRST issue, not a build-first one. Before writing a reranker: establish whether BM25 is actually leaving retrieval quality on the table for real review queries — e.g. sample a set of past reviews, compare BM25-reranked top-K against a cosine-only or cross-encoder-reranked top-K, and see if the ordering meaningfully differs in a way that would change what gets injected into the review prompt.
• If the evaluation shows a real gap: the cheapest local option is reranking top-K by cosine similarity against the ALREADY-COMPUTED query embedding (no new model, no new GPU call) before falling back to a dedicated small cross-encoder model — note Ollama has no native /rerank endpoint, so a real cross-encoder would need a sidecar (text-embeddings-inference/infinity), a real infrastructure addition, not a config flip.
• If the evaluation does NOT show a meaningful gap: close this issue with the evaluation recorded rather than shipping a reranker for a problem that doesn't exist. Mirrors Stretch: evaluate spare GPU headroom for a local vision-language model in visual-review #4335's own "a complete, successful outcome for this issue, not a failure" framing for a negative result.

Deliverables

• A recorded comparison (BM25 vs. cosine-rerank, on a real sample of retrieval queries from this codebase) showing whether reordering meaningfully changes the injected context
• Written recommendation: build the cheap cosine-rerank fallback, invest in a real cross-encoder sidecar, or explicitly skip (with reasoning) — matching Stretch: evaluate spare GPU headroom for a local vision-language model in visual-review #4335's evaluate-before-build precedent

Expected outcome

A data-backed answer on whether RAG retrieval quality is actually reranker-limited, avoiding speculative infrastructure for an unproven gain — or a concrete, justified improvement if the data says otherwise.

Effort

S (evaluation) / M (if a build is justified)

[linear-code]

JSO-3316

[JSONbored]

Measurement recorded

Ran the evaluation this issue calls for against the live self-host index on edge-nl-01: 24 real merged PRs sampled across all 3 gate repos (8 each from gittensory/metagraphed/awesome-claude, including today's #4674/#4675/#4677/#4678), building each queryText the same way production does (buildRagQuery), then calling retrieveContextWithMetrics twice per query — once reranker: "bm25", once reranker: "off" — with identical topK/minScore/excludePaths.

Results:

• 24/24 queries retrieved candidates (index is populated, no cold-index skew)
• 24/24 (100%) had a different top-K ORDER between BM25 and cosine-only
• 16/24 (67%) had a different TOP-1 result — i.e. what actually gets injected first into the review prompt changes depending on reranker

This refutes a concern I'd flagged mid-investigation, worth recording: the vector store already returns candidates cosine-sorted, so reranker: "off" already is the cosine ordering — I worried BM25 might be reordering a set that's already near-optimally sorted, making any reranking moot. The data says otherwise: BM25 diverges from cosine order in every single sampled query, substantially enough to change the #1 result two-thirds of the time. So BM25 is doing real, non-trivial work, not sitting redundant on top of cosine.

Important implication for the "build" branch of this issue's decision tree: the issue's proposed cheap fallback — "rerank top-K by cosine similarity against the already-computed query embedding" — is not a new capability to build. The vector store already returns cosine-sorted results, so that fallback is functionally identical to the EXISTING reranker: "off" mode. There is nothing to implement there; it's a one-line config flip that already exists.

What the data does NOT tell us: whether BM25's ordering or cosine's ordering is actually better for review usefulness — only that they differ. Answering that needs a relevance judgment (human or LLM-as-judge) on a sample, not just an order diff. That's a separate, cheap follow-up if it's ever worth pursuing — not blocking this issue.

Recommendation: close this as evaluated, matching the issue's own "explicit skip" outcome. BM25 (shipped, #1124) stays as-is; no cosine-rerank build needed (already available as reranker: "off" if anyone wants to A/B it live); a real cross-encoder sidecar (text-embeddings-inference/infinity) remains a real infra investment with no evidence yet that it's needed, given BM25 is already meaningfully differentiating results from raw cosine order.

Full per-query breakdown (paths, kept counts, top-1 before/after) available on request if useful for the record — omitted here to keep this comment readable.

[JSONbored]

Reopening — closing this was premature. Correcting my own comment above.

The data actually shows a real gap, by this issue's own decision rule. 24/24 sampled queries had a different top-K order between BM25 and cosine-only, and 16/24 (67%) had a different #1 result. That's exactly the "reordering meaningfully differs" outcome the issue said should trigger the BUILD branch, not the skip branch.

Where I went wrong: I noticed the proposed cheap fallback ("rerank by cosine against the already-computed embedding") is functionally identical to the existing reranker: "off" — true, there's no new code to write for that specific option — but I then treated "nothing new to build" as if it answered "is BM25 actually better than cosine," which it doesn't. The order-diff data proves the two disagree substantially; it says nothing about which one is more USEFUL for a real review. That's a genuinely separate question (a relevance judgment, not an order diff) and I hadn't answered it before closing.

Where this is headed instead: rather than a rushed one-off judgment call on 24 queries, this is a good candidate for a reusable, general RAG-quality benchmark harness — not scoped narrowly to BM25-vs-cosine, but built so future RAG changes (embedding model swaps, chunking strategy, a future cross-encoder) can be evaluated against the same harness over time. Design constraints from discussion:

• Runs on the review-stack server (edge-nl-01) against real live infra (Postgres/Qdrant/Ollama) and a real query corpus — not something that needs synthetic fixtures.
• No committed snapshots in this repo — we don't want git churn/PR noise from periodic benchmark runs. History/tracking should live in the existing observability stack (Prometheus/Grafana, already running on the box) rather than as tracked files here.
• Longer-term motivation beyond just this issue: stats reporting and eventually sharing retrieval/review-quality signals with the community, not just a one-off internal check.

This needs its own design pass (metric shape, Grafana panel, how "quality" gets scored beyond order-diffing) before implementation — tracking as follow-up, not blocking. Leaving open until that's scoped.