Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
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.pyindex 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 arediff --git a/packages/server/src/repowise/server/mcp_server/tool_answer/config.py b/packages/server/src/repowise/server/mcp_server/tool_answer/config.pyindex 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 stronglydiff --git a/packages/server/src/repowise/server/mcp_server/tool_answer/retrieval.py b/packages/server/src/repowise/server/mcp_server/tool_answer/retrieval.pyindex 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 annotationsimport asyncio+import loggingfrom typing import Anyfrom 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 missingdef _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.pyindex 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, monasync def _fake_excerpts(hits, ctx=None):for h in hits:h["excerpt"] = f"Page content for {h['target_path']}: chunking rationale..."+ return 0monkeypatch.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 Pagemodel — a silently-swallowed AttributeError here shipped pointers-onlygated payloads and re-opened the 8-15 call fallback spree the excerptsexist 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 == 0diff --git a/tests/unit/server/mcp/test_answer_page_excerpts.py b/tests/unit/server/mcp/test_answer_page_excerpts.pynew file mode 100644index 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