Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

fix(answer): attach page content on every retrieval, not only the weak ones (#1169)

Swati Ahuja09847f61ddfa
diff --git a/packages/server/src/repowise/server/mcp_server/tool_answer/answer.py b/packages/server/src/repowise/server/mcp_server/tool_answer/answer.py
index 9d8dc0340..f6dd6cffa 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_answer/answer.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_answer/answer.py
@@ -120,6 +120,7 @@ from repowise.server.mcp_server.tool_answer.config import (
_HIGH_CONFIDENCE_SCORE_FLOOR,
_INLINE_BODY_MAX_LINES,
_INLINE_BODY_MAX_SYMBOLS,
+ _PAGE_EXCERPT_HITS,
_SYSTEM_PROMPT,
_USER_TEMPLATE,
)
@@ -129,8 +130,8 @@ from repowise.server.mcp_server.tool_answer.data_shape import (
)
from repowise.server.mcp_server.tool_answer.retrieval import (
_apply_domain_penalty,
+ _attach_page_excerpts,
_candidate_justification,
- _enrich_gated_excerpts,
_intersection_boost,
_rerank_by_coverage,
)
@@ -1021,6 +1022,25 @@ async def get_answer(
),
}
+ # Attach real page content to the top hits, once, for every retrieval —
+ # before anything downstream branches on how good the retrieval looks.
+ #
+ # This used to run only when retrieval was NOT dominant, and dominance is
+ # what earns high confidence: the more certain retrieval was, the less
+ # prose the model was given, so confident answers were the ones built from
+ # symbol names alone. Whatever replaces the code below, keep this
+ # unconditional. Two call sites under different conditions is what made
+ # that inversion possible, and the cost of enriching a hit that a later
+ # fast path never reads is one indexed SELECT over at most five rows.
+ hits_without_page_content = await _attach_page_excerpts(hits, ctx)
+ if hits_without_page_content:
+ _log.warning(
+ "get_answer: %d of %d top hits have no page content; those hits "
+ "reach synthesis as a one-line summary only",
+ hits_without_page_content,
+ min(len(hits), _PAGE_EXCERPT_HITS),
+ )
+
# --- Retrieval dominance -----------------------------------------------
# ``dominant`` = retrieval clearly pointed at ONE page (the top hit
# outscores the rest). It no longer decides WHETHER to synthesize — under
@@ -1058,14 +1078,12 @@ async def get_answer(
# is ambiguous, so skip synthesis and hand back ranked excerpts +
# best_guesses for the agent to ground in.
#
- # Attach real page content to the top candidates before shaping the
- # reply. Agent-transcript evidence (context-tool bench, 2026-07-17): a
- # pointers-only gated payload sends the agent into an 8-15 call Grep/Read
- # spree that costs more than a bare agent — it paid for the tool call and
- # still had to acquire all content natively. Excerpts turn the miss path
- # into "pick one candidate, verify with at most one Read".
- with contextlib.suppress(Exception):
- await _enrich_gated_excerpts(hits, ctx)
+ # The excerpts those best_guesses carry were attached above. Agent-
+ # transcript evidence (context-tool bench, 2026-07-17): a pointers-only
+ # gated payload sends the agent into an 8-15 call Grep/Read spree that
+ # costs more than a bare agent — it paid for the tool call and still had
+ # to acquire all content natively. Excerpts turn the miss path into
+ # "pick one candidate, verify with at most one Read".
best_guesses = _build_best_guesses(hits)
# Mine source comments for rationale the wiki/decision corpus missed —
# turns "go Read these 5 files" into a cited why.
@@ -1187,15 +1205,6 @@ async def get_answer(
t0=t0,
)
- # Ambiguous retrieval (always-synthesize): pull real page content across the
- # non-dominant top pages so the LLM synthesizes over the actual candidate
- # content, not one-line summaries — the same excerpts the legacy abstain path
- # served the agent. No-op on dominant retrievals. (The excerpts also back the
- # best_guesses folded into a low/medium reply below.)
- if not dominant:
- with contextlib.suppress(Exception):
- await _enrich_gated_excerpts(hits, ctx)
-
# Decision fusion (why-shaped questions only) + structured prelude. Both
# layers are gated on signal: no ADRs for the top hits → no decisions
# block, no symbols / commits / decisions → no prelude. Empty layers are
diff --git a/packages/server/src/repowise/server/mcp_server/tool_answer/config.py b/packages/server/src/repowise/server/mcp_server/tool_answer/config.py
index 34bd967f2..9aeb438f1 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_answer/config.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_answer/config.py
@@ -191,16 +191,25 @@ _HEDGE_MARKERS = (
# retrieval with a coverage re-ranker on top, not of any particular repository;
# tune if a deployment shows systematic over- or under-gating.
-# When the gate triggers and we drop synthesis, fetch this many chars of
-# real page content per top hit so the agent has substantive raw material
-# to ground in (vs. one-line summary that's too thin to act on). 1500 chars
-# is enough for a page's opening section plus a code reference; at 600 the
-# excerpt stopped mid-context and agents fell back to native exploration
-# anyway (context-tool bench transcripts, 2026-07-17). Three hits at 1500
-# chars is ~1.1k tokens — well under any MCP output budget.
+# How many chars of real page content to attach per top hit, for the synthesis
+# prompt and for the pointer payload alike. 1500 chars is enough for a page's
+# opening section plus a code reference; at 600 the excerpt stopped mid-context
+# and agents fell back to native exploration anyway (context-tool bench
+# transcripts, 2026-07-17).
_GATED_EXCERPT_CHARS = 1500
+
+# How many hits the low-confidence payload hands back to the agent.
_GATED_RETURN_HITS = 3
+# How many top hits get their page content attached. Retrieval is capped at 5
+# and all 5 reach the synthesis prompt, so this is 5: a hit the model is asked
+# to read with no prose behind it is one it can only answer from symbol names.
+# This is the cost knob for the feature — 5 hits × 1500 chars is roughly 2k
+# prompt tokens on top of the symbol block, measured at +24% of the tool's own
+# synthesis spend. Lower it to spend less; hits below the cut fall back to
+# their one-line summaries.
+_PAGE_EXCERPT_HITS = 5
+
# Path-prefix domain heuristics — down-weight cross-domain retrievals so a
# clearly backend question doesn't anchor on a same-vocabulary UI file (and
# vice versa). The penalty is multiplicative, not absolute, so a strongly
diff --git a/packages/server/src/repowise/server/mcp_server/tool_answer/retrieval.py b/packages/server/src/repowise/server/mcp_server/tool_answer/retrieval.py
index b14fecfe6..f330d84c1 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_answer/retrieval.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_answer/retrieval.py
@@ -1,14 +1,15 @@
-"""Re-ranking, domain penalty, intersection boost, and gated-excerpt helpers.
+"""Re-ranking, domain penalty, intersection boost, and page-excerpt helpers.
These operate on the candidate hit list after the hybrid-retrieval stages in
``_answer_pipeline``. They tune the ranking (coverage rerank, domain penalty,
-intersection boost) and prepare the low-confidence return path
-(gated excerpts, candidate justifications).
+intersection boost), attach real page content to the top hits, and build the
+candidate justifications the low-confidence return path hands back.
"""
from __future__ import annotations
import asyncio
+import logging
from typing import Any
from sqlalchemy import select
@@ -21,13 +22,15 @@ from repowise.server.mcp_server.tool_answer.config import (
_COVERAGE_FLOOR,
_DOMAIN_PENALTY,
_GATED_EXCERPT_CHARS,
- _GATED_RETURN_HITS,
+ _PAGE_EXCERPT_HITS,
_RELATIONAL_CONNECTIVES,
_STOPWORDS,
_UI_PATH_PREFIXES,
_UI_QUESTION_TOKENS,
)
+_log = logging.getLogger("repowise.mcp.answer")
+
def serialize_hits(
hits: list[dict],
@@ -147,30 +150,53 @@ async def _intersection_boost(question: str, hits: list[dict], ctx: Any = None)
hits.sort(key=lambda h: h["score"], reverse=True)
-async def _enrich_gated_excerpts(hits: list[dict], ctx: Any = None) -> None:
- """For the gated (low-confidence) return path, fetch real page content
- for top hits so the agent has substantive raw material instead of
- one-line summaries. Mutates `hits` in place — adds an `excerpt` field.
+async def _attach_page_excerpts(hits: list[dict], ctx: Any = None) -> int:
+ """Attach each top hit's real page content as ``excerpt``. Mutates `hits`.
+
+ Every consumer of a hit — the synthesis prompt and the pointer payload
+ alike — otherwise sees only the page's one-line LLM summary or a 200-char
+ opener, next to a symbol block carrying docstrings and source bodies. A
+ consumer given names but no prose reconstructs rationale from the names,
+ which is a confident wrong answer rather than a thin one.
- Universal motivation: thin retrieval output forces consumers to fall
- back on priors instead of grounding in source. Symmetric with the
- enrichment we already do for synthesis.
+ Returns the number of top hits left without page content. That count is
+ the point: a hit reaching synthesis with no body used to be invisible,
+ which is how this went unnoticed for as long as it did.
"""
if not hits:
- return
- page_ids = [h["page_id"] for h in hits[:_GATED_RETURN_HITS] if h.get("page_id")]
+ return 0
+ top = hits[:_PAGE_EXCERPT_HITS]
+ page_ids = [h["page_id"] for h in top if h.get("page_id")]
if not page_ids:
- return
+ _log.warning(
+ "get_answer: none of the %d top hits carry a page_id, so no page "
+ "content can be attached — synthesis will read summaries only",
+ len(top),
+ )
+ return len(top)
try:
async with get_session(ctx.session_factory) as session:
res = await session.execute(select(Page.id, Page.content).where(Page.id.in_(page_ids)))
content_by_id = {row[0]: (row[1] or "") for row in res.all()}
except Exception:
- return
- for h in hits[:_GATED_RETURN_HITS]:
+ # Never fail the answer over an excerpt fetch — but never lose the
+ # fact either. Without this line the whole prompt silently degrades
+ # to summaries and the answer still looks confident.
+ _log.warning(
+ "get_answer: page-content fetch failed for %d hits; synthesis "
+ "will read one-line summaries instead of page prose",
+ len(page_ids),
+ exc_info=True,
+ )
+ return len(top)
+ missing = 0
+ for h in top:
body = content_by_id.get(h.get("page_id"), "")
if body:
h["excerpt"] = body[:_GATED_EXCERPT_CHARS]
+ else:
+ missing += 1
+ return missing
def _detect_question_domain(question: str) -> str | None:
diff --git a/tests/unit/server/mcp/test_answer_calibration.py b/tests/unit/server/mcp/test_answer_calibration.py
index 6c5381d45..1849b4437 100644
--- a/tests/unit/server/mcp/test_answer_calibration.py
+++ b/tests/unit/server/mcp/test_answer_calibration.py
@@ -1069,10 +1069,11 @@ async def test_non_dominant_best_guesses_carry_candidate_excerpts(setup_mcp, mon
async def _fake_excerpts(hits, ctx=None):
for h in hits:
h["excerpt"] = f"Page content for {h['target_path']}: chunking rationale..."
+ return 0
monkeypatch.setattr(answer_mod, "_hybrid_retrieve", _fake_retrieve)
monkeypatch.setattr(answer_mod, "_hydrate_hits", _fake_hydrate)
- monkeypatch.setattr(answer_mod, "_enrich_gated_excerpts", _fake_excerpts)
+ monkeypatch.setattr(answer_mod, "_attach_page_excerpts", _fake_excerpts)
_patch_provider(monkeypatch, answer_mod, "Uploads chunk at 8MB (pkg/alpha/one.py).")
(tmp_path / "pkg" / "alpha").mkdir(parents=True)
(tmp_path / "pkg" / "alpha" / "one.py").write_text("CHUNK = 8\n", encoding="utf-8")
@@ -1192,22 +1193,23 @@ async def test_frame_gated_answer_surfaces_code_rationale(setup_mcp, monkeypatch
# ---------------------------------------------------------------------------
-# Gated-path excerpt enrichment
+# Page-content excerpt enrichment
# ---------------------------------------------------------------------------
-class TestGatedExcerptEnrichment:
- """_enrich_gated_excerpts must run its real query against the real Page
+class TestPageExcerptEnrichment:
+ """_attach_page_excerpts must run its real query against the real Page
model — a silently-swallowed AttributeError here shipped pointers-only
gated payloads and re-opened the 8-15 call fallback spree the excerpts
exist to prevent."""
async def test_excerpts_attached_from_real_page_rows(self, factory, populated_db):
from repowise.server.mcp_server.tool_answer.retrieval import (
- _enrich_gated_excerpts,
+ _attach_page_excerpts,
)
hits = [{"page_id": "repo_overview:test-repo", "score": 1.0}]
ctx = SimpleNamespace(session_factory=factory)
- await _enrich_gated_excerpts(hits, ctx)
+ missing = await _attach_page_excerpts(hits, ctx)
assert hits[0].get("excerpt", "").startswith("# Test Repo")
+ assert missing == 0
diff --git a/tests/unit/server/mcp/test_answer_page_excerpts.py b/tests/unit/server/mcp/test_answer_page_excerpts.py
new file mode 100644
index 000000000..ff287f545
--- /dev/null
+++ b/tests/unit/server/mcp/test_answer_page_excerpts.py
@@ -0,0 +1,225 @@
+"""Every retrieval gets the page's prose, including the confident ones.
+
+Page content used to be attached only when retrieval was *not* dominant — and
+dominance is what earns high confidence. So the more certain retrieval was,
+the less prose the model was given: a confident answer was built from the
+page's one-line summary plus a symbol table of names, while an ambiguous one
+got 1500 chars of the actual page. Answers written from names read as
+confident and reconstruct rationale that is not there.
+
+These tests hold the two halves of that: prose reaches the prompt on a
+dominant retrieval, and a hit that reaches synthesis with no page content
+behind it is counted and logged rather than passing silently.
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import UTC, datetime
+from types import SimpleNamespace
+
+import pytest
+
+from repowise.core.persistence.models import Page
+
+_PAGE_IDS = ("file_page:pkg/alpha/one.py", "file_page:pkg/alpha/two.py")
+_NOW = datetime(2026, 3, 19, 12, 0, 0, tzinfo=UTC)
+
+# Long enough that a summary-sized snippet would not reach the marker, short
+# enough that the marker survives any per-hit cap in play — what is under test
+# here is whether page prose arrives at all, not how much of it does.
+_BODY = ("## Overview\n\nThe alpha module owns the write path. " * 10) + (
+ "HARD INVARIANT: it only ever writes the returned result object."
+)
+_MARKER = "HARD INVARIANT: it only ever writes the returned result object."
+
+
+async def _add_pages(factory, repo_id: str, content: str) -> None:
+ async with factory() as s:
+ for page_id in _PAGE_IDS:
+ s.add(
+ Page(
+ id=page_id,
+ repository_id=repo_id,
+ page_type="file_page",
+ title=page_id.removeprefix("file_page:"),
+ content=content,
+ target_path=page_id.removeprefix("file_page:"),
+ source_hash=page_id,
+ model_name="mock",
+ provider_name="mock",
+ generation_level=2,
+ confidence=0.9,
+ freshness_status="fresh",
+ created_at=_NOW,
+ updated_at=_NOW,
+ )
+ )
+ await s.commit()
+
+
+def _patch_pipeline(monkeypatch, answer_mod, *, dominant: bool) -> None:
+ """``dominant=True`` is a runaway top score — the branch that used to be
+ denied page content. ``False`` is the ambiguous pair that always had it."""
+ scores = (5.0, 1.0) if dominant else (2.0, 1.9)
+
+ async def _fake_retrieve(question, ctx):
+ return [
+ {"page_id": _PAGE_IDS[0], "score": scores[0], "_sources": {"fts"}},
+ {"page_id": _PAGE_IDS[1], "score": scores[1], "_sources": {"fts"}},
+ ]
+
+ async def _fake_hydrate(hits, ctx, *, scope=None):
+ for h in hits:
+ h["target_path"] = h["page_id"].removeprefix("file_page:")
+ h["title"] = h["target_path"]
+ h["summary"] = "One-line summary of the page."
+ h["snippet"] = ""
+ h["page_type"] = "file_page"
+ return hits
+
+ monkeypatch.setattr(answer_mod, "_hybrid_retrieve", _fake_retrieve)
+ monkeypatch.setattr(answer_mod, "_hydrate_hits", _fake_hydrate)
+
+
+def _capture_prompt(monkeypatch, answer_mod, answer_text: str) -> list[str]:
+ """Record the user prompt handed to synthesis; short-circuit the LLM."""
+ seen: list[str] = []
+
+ class _Provider:
+ provider_name = "mock"
+ model_name = "mock-1"
+
+ async def generate(self, **kwargs):
+ return SimpleNamespace(content=answer_text)
+
+ async def _fake_synthesize(provider, system_prompt, user_prompt):
+ seen.append(user_prompt)
+ return answer_text, None
+
+ monkeypatch.setattr(answer_mod, "_resolve_provider_for_answer", lambda _p: _Provider())
+ monkeypatch.setattr(answer_mod, "synthesize", _fake_synthesize)
+ return seen
+
+
+async def test_dominant_retrieval_prompt_carries_page_prose(setup_mcp, factory, monkeypatch):
+ """The regression: a confident retrieval's context block contains the
+ page's body text, not only its summary."""
+ import repowise.server.mcp_server.tool_answer.answer as answer_mod
+ from repowise.server.mcp_server import get_answer
+
+ await _add_pages(factory, setup_mcp, _BODY)
+ _patch_pipeline(monkeypatch, answer_mod, dominant=True)
+ prompts = _capture_prompt(
+ monkeypatch, answer_mod, "The alpha module owns the write path (pkg/alpha/one.py)."
+ )
+
+ await get_answer("how does the alpha module handle the write path")
+
+ assert prompts, "synthesis must run"
+ assert _MARKER in prompts[0], (
+ "a dominant retrieval's prompt must carry the page's real prose, not "
+ "only its one-line summary"
+ )
+
+
+async def test_ambiguous_retrieval_still_carries_page_prose(setup_mcp, factory, monkeypatch):
+ """The path that already worked keeps working — this change moves the call,
+ it does not trade one branch for the other."""
+ import repowise.server.mcp_server.tool_answer.answer as answer_mod
+ from repowise.server.mcp_server import get_answer
+
+ await _add_pages(factory, setup_mcp, _BODY)
+ _patch_pipeline(monkeypatch, answer_mod, dominant=False)
+ prompts = _capture_prompt(monkeypatch, answer_mod, "Alpha owns writes (pkg/alpha/one.py).")
+
+ await get_answer("how does the alpha module handle the write path")
+
+ assert prompts, "synthesis must run"
+ assert _MARKER in prompts[0]
+
+
+async def test_hit_with_no_page_content_is_counted_and_logged(
+ setup_mcp, factory, monkeypatch, caplog
+):
+ """A hit reaching synthesis with nothing to read is the state that made the
+ original inversion invisible. It must be counted, and it must not raise."""
+ import repowise.server.mcp_server.tool_answer.answer as answer_mod
+ from repowise.server.mcp_server import get_answer
+
+ await _add_pages(factory, setup_mcp, "") # rows exist, bodies empty
+ _patch_pipeline(monkeypatch, answer_mod, dominant=True)
+ prompts = _capture_prompt(monkeypatch, answer_mod, "Alpha owns writes (pkg/alpha/one.py).")
+
+ with caplog.at_level(logging.WARNING, logger="repowise.mcp.answer"):
+ result = await get_answer("how does the alpha module handle the write path")
+
+ assert result["answer"], "a missing page body degrades the prompt, never the response"
+ assert prompts and "One-line summary of the page." in prompts[0]
+ assert any("no page content" in r.getMessage() for r in caplog.records), (
+ "hits served to synthesis without page content must be reported"
+ )
+
+
+async def test_page_fetch_failure_warns_and_does_not_break_the_answer(
+ setup_mcp, monkeypatch, caplog
+):
+ """The fetch is best-effort, but its failure is not silent: the prompt
+ quietly falling back to summaries is exactly the invisible degradation
+ this whole change is about."""
+ import repowise.server.mcp_server.tool_answer.answer as answer_mod
+ import repowise.server.mcp_server.tool_answer.retrieval as retrieval_mod
+ from repowise.server.mcp_server import get_answer
+
+ _patch_pipeline(monkeypatch, answer_mod, dominant=True)
+ _capture_prompt(monkeypatch, answer_mod, "Alpha owns writes (pkg/alpha/one.py).")
+
+ def _boom(*a, **kw):
+ raise RuntimeError("database gone")
+
+ monkeypatch.setattr(retrieval_mod, "get_session", _boom)
+
+ with caplog.at_level(logging.WARNING, logger="repowise.mcp.answer"):
+ result = await get_answer("how does the alpha module handle the write path")
+
+ assert result["answer"]
+ assert any("page-content fetch failed" in r.getMessage() for r in caplog.records)
+
+
+async def test_every_hit_the_prompt_shows_is_offered_page_content(setup_mcp, monkeypatch):
+ """The enrichment bound must not sit below the number of hits synthesis is
+ asked to read — a hit in the prompt with no prose can only be answered
+ from its symbol names."""
+ from repowise.server.mcp_server.tool_answer.config import _PAGE_EXCERPT_HITS
+
+ # Retrieval is capped at 5 hits for the prompt and the payload.
+ assert _PAGE_EXCERPT_HITS >= 5
+
+
+async def test_enriched_prompt_stays_within_the_synthesis_budget(setup_mcp, factory, monkeypatch):
+ """Five hits of page prose on top of the symbol block must still fit the
+ budgeter's ceiling."""
+ import repowise.server.mcp_server.tool_answer.answer as answer_mod
+ from repowise.server.mcp_server import get_answer
+ from repowise.server.mcp_server.tool_answer.config import (
+ _GATED_EXCERPT_CHARS,
+ _PAGE_EXCERPT_HITS,
+ )
+
+ await _add_pages(factory, setup_mcp, "x" * 20_000)
+ _patch_pipeline(monkeypatch, answer_mod, dominant=True)
+ prompts = _capture_prompt(monkeypatch, answer_mod, "Alpha owns writes (pkg/alpha/one.py).")
+
+ await get_answer("how does the alpha module handle the write path")
+
+ assert prompts
+ # Generous headroom over the excerpt budget for the prelude, symbol block
+ # and template; the point is that no excerpt escapes its cap.
+ excerpt_budget = _GATED_EXCERPT_CHARS * _PAGE_EXCERPT_HITS
+ assert len(prompts[0]) < excerpt_budget + 8000