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): give a keyless reply the evidence for choosing between files (#1576)

Raghav Chamadiyac3fdccbd2389
diff --git a/packages/server/src/repowise/server/mcp_server/_flow_path.py b/packages/server/src/repowise/server/mcp_server/_flow_path.py
index 16618e344..85f27c4be 100644
--- a/packages/server/src/repowise/server/mcp_server/_flow_path.py
+++ b/packages/server/src/repowise/server/mcp_server/_flow_path.py
@@ -40,7 +40,6 @@ from sqlalchemy import select
from repowise.core.persistence.models import GraphEdge, Page, WikiSymbol
from repowise.core.test_paths import is_test_related_path
-from repowise.server.mcp_server.tool_answer.retrieval import _question_terms
# Edge kinds that form the file-level dependency graph. ``imports`` is
# file-to-file already; ``calls`` is symbol-to-symbol and gets projected to
@@ -154,11 +153,15 @@ async def _resolve_question_anchors(
# Named symbols -> defining files.
if question_ids:
res = await session.execute(
- select(WikiSymbol.file_path).where(
+ select(WikiSymbol.file_path)
+ .where(
WikiSymbol.repository_id == repo_id,
- WikiSymbol.name.in_(list(question_ids)),
+ WikiSymbol.name.in_(sorted(question_ids)),
WikiSymbol.kind.in_(("function", "method", "class", "interface")),
)
+ # Insertion order here decides which anchors survive the
+ # _FLOW_MAX_ANCHORS cap, so it must not be the engine's whim.
+ .order_by(WikiSymbol.file_path)
)
for (fp,) in res.all():
if fp:
@@ -166,13 +169,23 @@ async def _resolve_question_anchors(
# Module-name matches. Build a stem -> file_page paths map once, then keep
# tokens that resolve tightly (not the generic ones).
- tokens = {t for t in _question_terms(question) if len(t) >= 4}
+ # Sorted for the same reason as the query above: this loop's order is the
+ # anchor insertion order.
+ # Imported here, not at module scope: `tool_answer.retrieval` pulls in the
+ # `tool_answer` package, whose __init__ imports `answer`, which imports this
+ # module. At module scope that cycle makes this file unimportable first.
+ from repowise.server.mcp_server.tool_answer.retrieval import _question_terms
+
+ tokens = sorted({t for t in _question_terms(question) if len(t) >= 4})
if tokens:
res = await session.execute(
- select(Page.target_path).where(
+ select(Page.target_path)
+ .where(
Page.repository_id == repo_id,
Page.page_type == "file_page",
)
+ # Same reason as the symbol query: this feeds anchor insertion order.
+ .order_by(Page.target_path)
)
stem_to_paths: dict[str, list[str]] = {}
for (tp,) in res.all():
@@ -191,12 +204,17 @@ async def _resolve_question_anchors(
return anchors
-async def _load_file_adjacency(session: Any, repo_id: str) -> dict[str, set[str]]:
+async def _load_file_adjacency(session: Any, repo_id: str) -> dict[str, list[str]]:
"""Undirected file-level adjacency from imports + projected calls edges.
Both directions are added: a flow can be read caller->callee or the reverse,
and the endpoints are anchored, not oriented. ``calls`` edges are projected
from symbol node_ids onto their files and self-loops dropped.
+
+ Neighbours come back **sorted**. Built as sets to dedupe, returned as lists
+ because BFS walks them: set iteration order over strings moves with the
+ per-process hash seed, so which of several equal-length paths was found
+ changed between runs on identical data.
"""
res = await session.execute(
select(
@@ -226,14 +244,18 @@ async def _load_file_adjacency(session: Any, repo_id: str) -> dict[str, set[str]
continue
adj.setdefault(src, set()).add(tgt)
adj.setdefault(tgt, set()).add(src)
- return adj
+ return {node: sorted(neighbours) for node, neighbours in adj.items()}
-def _bfs_path(adj: dict[str, set[str]], src: str, dst: str, max_depth: int) -> list[str] | None:
+def _bfs_path(adj: dict[str, list[str]], src: str, dst: str, max_depth: int) -> list[str] | None:
"""Shortest file path between ``src`` and ``dst`` (inclusive), or None.
Bidirectional BFS bounded to ``max_depth`` hops and ``_FLOW_MAX_VISITED``
nodes. Returns the node sequence ``[src, ..., dst]``.
+
+ Frontiers are lists, not sets: with several shortest paths the one found is
+ whichever neighbour is reached first, so the walk has to be ordered for the
+ result to be. ``parents`` already dedupes, so no node is queued twice.
"""
if src == dst:
return [src]
@@ -247,8 +269,8 @@ def _bfs_path(adj: dict[str, set[str]], src: str, dst: str, max_depth: int) -> l
# forward side would never close a path longer than the forward reach.
fwd: dict[str, Any] = {src: None}
bwd: dict[str, Any] = {dst: None}
- fwd_frontier = {src}
- bwd_frontier = {dst}
+ fwd_frontier = [src]
+ bwd_frontier = [dst]
fwd_depth = 0
bwd_depth = 0
visited = 0
@@ -258,7 +280,7 @@ def _bfs_path(adj: dict[str, set[str]], src: str, dst: str, max_depth: int) -> l
frontier, parents, other = fwd_frontier, fwd, bwd
else:
frontier, parents, other = bwd_frontier, bwd, fwd
- nxt: set[str] = set()
+ nxt: list[str] = []
for node in frontier:
for nb in adj.get(node, ()):
if nb in parents:
@@ -267,7 +289,7 @@ def _bfs_path(adj: dict[str, set[str]], src: str, dst: str, max_depth: int) -> l
visited += 1
if nb in other:
return _stitch(fwd, bwd, nb)
- nxt.add(nb)
+ nxt.append(nb)
if visited > _FLOW_MAX_VISITED:
return None
if expand_fwd:
@@ -332,7 +354,14 @@ async def expand_via_flow_path(
# Endpoints to connect: the question-derived anchors, plus the confident top
# hit as a bridge (a question often names one endpoint and the top hit is
# the other). Cap the set so the pairwise BFS stays cheap.
- endpoints = list(anchors)
+ #
+ # Retrieval rank decides who survives the cap. The anchors arrive in path
+ # order, so a plain cap would keep the six alphabetically-first files — a
+ # stable bias toward whichever package sorts early. A file retrieval already
+ # ranked is the better endpoint, and unranked anchors keep path order behind
+ # them, which leaves the whole thing deterministic either way.
+ rank = {h.get("target_path"): i for i, h in enumerate(hits) if h.get("target_path")}
+ endpoints = sorted(anchors, key=lambda p: (rank.get(p, len(hits)), p))
if top_hit and top_hit not in anchors:
endpoints.append(top_hit)
endpoints = endpoints[:_FLOW_MAX_ANCHORS]
@@ -354,8 +383,10 @@ async def expand_via_flow_path(
# coincidental basename match is rejected), but injecting it as extra hits
# just hands the agent pass-through files to drill into for a two-file
# question. Shortest paths first so a direct neighbor beats a 4-hop
- # coincidence; capped at _FLOW_MAX_INJECT.
- paths.sort(key=len)
+ # coincidence; capped at _FLOW_MAX_INJECT. The path itself breaks a length
+ # tie, so `flow_path` and the injected node order do not depend on which of
+ # two equally short paths happened to be enumerated first.
+ paths.sort(key=lambda p: (len(p), p))
path_nodes: list[str] = []
seen_nodes: set[str] = set()
for path in paths:
diff --git a/packages/server/src/repowise/server/mcp_server/_neighbor_rerank.py b/packages/server/src/repowise/server/mcp_server/_neighbor_rerank.py
index f8ebab0e5..17a768582 100644
--- a/packages/server/src/repowise/server/mcp_server/_neighbor_rerank.py
+++ b/packages/server/src/repowise/server/mcp_server/_neighbor_rerank.py
@@ -124,7 +124,7 @@ def _hub_cutoff(deg: dict[str, int]) -> int:
return max(vals[min(len(vals) - 1, int(len(vals) * _HUB_PERCENTILE))], 1)
-def _walk_neighborhood(adj: dict[str, set[str]], seeds: list[str]) -> set[str]:
+def _walk_neighborhood(adj: dict[str, list[str]], seeds: list[str]) -> set[str]:
"""Bounded BFS out from ``seeds``, never expanding through a hub or plumbing.
Such nodes may be *reached* (a hub can be the gold) but are never expanded
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 a13dd9c66..bbef71f65 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
@@ -115,6 +115,7 @@ from repowise.server.mcp_server._meta import build_meta as _build_meta
from repowise.server.mcp_server._neighbor_rerank import (
expand_via_neighbor_rerank as _expand_via_neighbor_rerank,
)
+from repowise.server.mcp_server._page_paths import hit_file_path
from repowise.server.mcp_server._symbol_lookup import (
bare_name,
parse_symbol_id,
@@ -405,12 +406,18 @@ def _build_best_guesses(hits: list[dict]) -> list[dict]:
"""Decision-shaped candidate list: per-file justification, score, excerpt.
The evidence an ambiguous-retrieval reply carries so the agent can pick ONE
- file to verify instead of skimming five. Shared by the legacy abstain path
- and the always-synthesize low/medium fold-in.
+ file to verify instead of skimming five. Shared by the legacy abstain path,
+ the always-synthesize low/medium fold-in, and the degraded paths.
+
+ ``file`` is resolved through ``hit_file_path``, and a hit resolving to no
+ file is skipped — both for the reason ``serialize_candidates`` does it
+ (finding A15): a ``symbol_spotlight`` page's ``target_path`` is
+ ``file.py::Symbol`` and a module page's is a group key, neither of which a
+ consumer can open. This field is named "file" and gets Read.
"""
return [
{
- "file": h.get("target_path"),
+ "file": hit_file_path(h),
"why_relevant": _candidate_justification(h),
"score": round(h.get("score", 0.0), 3),
# Absent rather than null. It was `null` in all six wire samples
@@ -420,7 +427,7 @@ def _build_best_guesses(hits: list[dict]) -> list[dict]:
**({"excerpt": h["excerpt"]} if h.get("excerpt") else {}),
}
for h in hits[:_GATED_RETURN_HITS]
- if h.get("target_path")
+ if hit_file_path(h)
]
@@ -787,7 +794,7 @@ def _rationale_anchors(h: dict) -> list[tuple[str, int | None]]:
return anchors
-def _gather_code_rationale(ctx, hits: list[dict], fallback_targets: list[str], question: str):
+async def _gather_code_rationale(ctx, hits: list[dict], fallback_targets: list[str], question: str):
"""Mine in-code rationale comments for a low-confidence answer.
The wiki/decision corpus failed to ground the question; the "why" may be a
@@ -796,6 +803,10 @@ def _gather_code_rationale(ctx, hits: list[dict], fallback_targets: list[str], q
line boost on their definition, then fallback_targets fill the rest — for
comment blocks carrying a rationale marker overlapping the question.
Best-effort: returns [] on any failure, never raises into the tool path.
+
+ Off the loop, like the sibling live-source miner on the value fast path.
+ Measured 13.3 ms over 234 KB of django candidates — small per call, and
+ every concurrent request pays it if it runs where the loop can feel it.
"""
repo_root = getattr(ctx, "path", None)
if not repo_root:
@@ -810,7 +821,9 @@ def _gather_code_rationale(ctx, hits: list[dict], fallback_targets: list[str], q
near_lines[path] = near_line
candidates.extend(p for p in (fallback_targets or []) if p)
try:
- return _mine_rationale(repo_root, candidates, question, near_lines=near_lines)
+ return await asyncio.to_thread(
+ _mine_rationale, repo_root, candidates, question, near_lines=near_lines
+ )
except Exception: # best-effort enrichment, never break the response
return []
@@ -1239,6 +1252,7 @@ async def _degraded_payload(
*,
reason: str,
note: str,
+ question: str,
hits: list[dict],
fallback_targets: list[str],
repository,
@@ -1289,6 +1303,12 @@ async def _degraded_payload(
keyed arm went on to cite. The same rule the synthesised path uses answers
that question here, and it stays honest in the other direction: 14 of the 26
retrievals were genuinely weak in both arms and still grade "weak".
+
+ ``best_guesses`` and ``code_rationale`` are here for the same reason as the
+ bodies: neither needs a provider, and the legacy abstain path has built both
+ from ``hits`` alone for as long as it has existed. Measured 0 of 26 here, so
+ the tool answered better when the reason for not synthesising was "retrieval
+ was ambiguous" than when it was "you have no key".
"""
retrieval_quality = _retrieval_quality(hits, agreement_dominant)
repo_root = _repo_root(ctx)
@@ -1304,6 +1324,12 @@ async def _degraded_payload(
summary = _degraded_summary(reason, symbol_bodies, len(hits))
+ best_guesses = _build_best_guesses(hits)
+ # No quotes to check against here — there is no prose to quote from.
+ code_rationale = _drop_already_surfaced(
+ await _gather_code_rationale(ctx, hits, fallback_targets, question), symbol_bodies
+ )
+
payload: dict = {
"answer": summary,
"citations": citations,
@@ -1314,6 +1340,14 @@ async def _degraded_payload(
"retrieval": _serialize_hits(hits),
"note": note,
}
+ if best_guesses:
+ payload["best_guesses"] = best_guesses
+ if code_rationale:
+ payload["code_rationale"] = code_rationale
+ payload["note"] += (
+ " code_rationale carries rationale comments mined from the candidate "
+ "source — they may already answer the question."
+ )
if symbol_bodies:
payload["symbol_bodies"] = symbol_bodies
payload["grounding"] = "symbol_body"
@@ -1324,6 +1358,16 @@ async def _degraded_payload(
" symbol_bodies carries the live body of the symbol(s) you named, so "
"answer from that rather than re-reading the file."
)
+ elif best_guesses and retrieval_quality != "weak":
+ # No body, so the next step is a choice between files. Not on a weak
+ # retrieval: `_meta.hint` there says "refine the query rather than
+ # reading these files in order", and two hints that disagree are worse
+ # than one. Names `best_guesses`, not its excerpt — that copy is dropped
+ # on the way out, since this path always has a populated `retrieval`.
+ payload["next_action_hint"] = (
+ f"Start from {best_guesses[0]['file']} — it ranked highest, and "
+ "best_guesses says why each candidate is in the running."
+ )
payload["_meta"] = {
**_build_meta(
timing_ms=(time.perf_counter() - t0) * 1000,
@@ -1339,7 +1383,12 @@ async def _degraded_payload(
),
"degraded": reason,
}
- return _with_candidates(payload, resolved_pool if resolved_pool is not None else hits)
+ # The serve-time cuts, which this return had never been routed through. It
+ # is now the only path carrying `best_guesses` beside a populated
+ # `retrieval`, so without the drop every excerpt ships twice.
+ return _trim_served_payload(
+ _with_candidates(payload, resolved_pool if resolved_pool is not None else hits)
+ )
async def _degraded_next_action(
@@ -1547,7 +1596,13 @@ async def _run_retrieval_pipeline(
def _union_answer_payload(
- question: str, question_ids: set[str], homonyms: dict, ctx, repository, t0: float
+ question: str,
+ question_ids: set[str],
+ homonyms: dict,
+ ctx,
+ repository,
+ t0: float,
+ retrieval_quality: str,
) -> dict | None:
"""The answer-by-union reply, or None to let synthesis handle the question.
@@ -1638,6 +1693,11 @@ def _union_answer_payload(
),
"citations": cited,
"confidence": _union_confidence,
+ # Rates the `candidates` shortlist, not the bodies: the union
+ # answers by exact name and the note offers that shortlist for
+ # "if you meant something else". It is the one body-serving
+ # return that had no rating at all.
+ "retrieval_quality": retrieval_quality,
"grounding": "exact_symbol",
"symbol_bodies": union_bodies,
"fallback_targets": [b["path"] for b in union_bodies],
@@ -2016,6 +2076,27 @@ async def get_answer(
homonyms = retrieved.homonyms
flow_paths = retrieved.flow_paths
+ # Agreement dominance recovers the "both retrievers rank this #1" signal that
+ # RRF fusion compresses out of the numeric score. Computed once and OR'd into
+ # every place dominance is decided, so it can only LIFT a retrieval.
+ # Read the vector leg's own recorded status rather than inferring it from
+ # `hits`, which is capped to 5 by here: "no _vec_rank in the top 5" is also
+ # what a timed-out, errored, scope-filtered or simply outranked vector leg
+ # looks like, and those must NOT fall back to the symbol leg.
+ #
+ # Above the early returns because they rate their retrieval too. Pure over
+ # `hits` and the recorded leg status, both settled by the pipeline call above.
+ agreement_dominant = (
+ _agreement_dominant(
+ hits,
+ vector_leg_keyless=(
+ _symbol_agreement_enabled() and _retrieval_legs().get("vector") == "keyless"
+ ),
+ )
+ if _agreement_confidence_enabled()
+ else False
+ )
+
# --- Qualified-miss guard ----------------------------------------------
# The question qualified a symbol (``Parent.leaf``) but the exact-name scan
# found the leaf only under OTHER parents. Return not-found rather than
@@ -2038,7 +2119,15 @@ async def get_answer(
resolved_pool,
)
- union_payload = _union_answer_payload(question, question_ids, homonyms, ctx, repository, t0)
+ union_payload = _union_answer_payload(
+ question,
+ question_ids,
+ homonyms,
+ ctx,
+ repository,
+ t0,
+ _retrieval_quality(hits, agreement_dominant),
+ )
if union_payload is not None:
return _with_candidates(union_payload, resolved_pool)
@@ -2103,24 +2192,6 @@ async def get_answer(
# (typical 0.15-0.25), so a coverage threshold over-fires. Default dominant
# for a lone hit (nothing to be ambiguous against).
always_synthesize = _always_synthesize()
- # Agreement dominance recovers the "both retrievers rank this #1" signal
- # that RRF fusion compresses out of the numeric score. Computed once and
- # OR'd into every place the ratio/gap gate decides dominance, so it can
- # only LIFT a retrieval — never demote one the ratio already trusts.
- # Read the vector leg's own recorded status rather than inferring it from
- # `hits`, which is capped to 5 by here: "no _vec_rank in the top 5" is also
- # what a timed-out, errored, scope-filtered or simply outranked vector leg
- # looks like, and those must NOT fall back to the symbol leg.
- agreement_dominant = (
- _agreement_dominant(
- hits,
- vector_leg_keyless=(
- _symbol_agreement_enabled() and _retrieval_legs().get("vector") == "keyless"
- ),
- )
- if _agreement_confidence_enabled()
- else False
- )
dominant = True
if len(hits) >= 2:
top_score = hits[0].get("score", 0.0)
@@ -2145,7 +2216,7 @@ async def get_answer(
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.
- code_rationale = _gather_code_rationale(ctx, hits, fallback_targets, question)
+ code_rationale = await _gather_code_rationale(ctx, hits, fallback_targets, question)
has_excerpts = any("excerpt" in g for g in best_guesses)
gated: dict = {
"answer": "",
@@ -2251,6 +2322,7 @@ async def get_answer(
return await _degraded_payload(
reason=reason,
note=note,
+ question=question,
hits=hits,
fallback_targets=fallback_targets,
repository=repository,
@@ -2438,7 +2510,7 @@ async def get_answer(
# The hedge often means the rationale isn't in the wiki at all — it's a
# code comment. Mine the candidate source for it before sending the
# agent off to Read.
- code_rationale = _gather_code_rationale(ctx, hits, fallback_targets, question)
+ code_rationale = await _gather_code_rationale(ctx, hits, fallback_targets, question)
# A comment already visible in symbol_bodies must not surface twice.
code_rationale = _drop_already_surfaced(code_rationale, symbol_bodies)
if code_rationale:
@@ -2497,7 +2569,7 @@ async def get_answer(
# decision corpus never captured. Mine the candidate source for it
# — the same lever the gated/hedged paths use — so the downgrade
# ships a lead, not just a warning.
- code_rationale = _gather_code_rationale(ctx, hits, fallback_targets, question)
+ code_rationale = await _gather_code_rationale(ctx, hits, fallback_targets, question)
code_rationale = _drop_already_surfaced(code_rationale, symbol_bodies, quotes)
if code_rationale:
payload["code_rationale"] = code_rationale
@@ -2639,7 +2711,7 @@ async def get_answer(
# the win is the answer AND the cited comment in one call (no re-read),
# unless a gate above already attached code_rationale.
if "code_rationale" not in payload and any(h.get("_concept_anchored") for h in hits):
- concept_rationale = _gather_code_rationale(ctx, hits, fallback_targets, question)
+ concept_rationale = await _gather_code_rationale(ctx, hits, fallback_targets, question)
concept_rationale = _drop_already_surfaced(concept_rationale, symbol_bodies, quotes)
if concept_rationale:
payload["code_rationale"] = concept_rationale
@@ -2654,7 +2726,7 @@ async def get_answer(
if not dominant:
payload.setdefault("best_guesses", _build_best_guesses(hits))
if "code_rationale" not in payload:
- _cr = _gather_code_rationale(ctx, hits, fallback_targets, question)
+ _cr = await _gather_code_rationale(ctx, hits, fallback_targets, question)
_cr = _drop_already_surfaced(_cr, symbol_bodies, quotes)
if _cr:
payload["code_rationale"] = _cr
diff --git a/tests/unit/server/mcp/test_answer_degraded_evidence.py b/tests/unit/server/mcp/test_answer_degraded_evidence.py
index 8b51613d2..4e001a859 100644
--- a/tests/unit/server/mcp/test_answer_degraded_evidence.py
+++ b/tests/unit/server/mcp/test_answer_degraded_evidence.py
@@ -20,7 +20,10 @@ from __future__ import annotations
from types import SimpleNamespace
from repowise.server.mcp_server.tool_answer import symbols as symbols_mod
-from repowise.server.mcp_server.tool_answer.answer import _degraded_payload
+from repowise.server.mcp_server.tool_answer.answer import (
+ _degraded_payload,
+ _drop_duplicated_guess_excerpts,
+)
def _tree(tmp_path, *, body_lines: int = 6) -> SimpleNamespace:
@@ -51,10 +54,11 @@ def _hits(*, end_line: int, name: str = "Flask") -> list[dict]:
]
-async def _degraded(ctx, hits, question_ids):
+async def _degraded(ctx, hits, question_ids, question="what is Flask"):
return await _degraded_payload(
reason="no-llm-provider",
note="DEGRADED: no LLM provider configured",
+ question=question,
hits=hits,
fallback_targets=["src/flask/app.py"],
repository=None,
@@ -116,7 +120,10 @@ async def test_degraded_selects_only_symbols_the_question_named(tmp_path):
assert "symbol_bodies" not in payload
assert payload["citations"] == []
- assert "next_action_hint" not in payload
+ # A hint is still given — it just cannot be a body hint, because no body was
+ # served. Nothing here may name symbol_bodies or tell the caller to read one.
+ assert "symbol_bodies" not in payload["next_action_hint"]
+ assert "body" not in payload["next_action_hint"]
async def test_degraded_keeps_the_truncation_contract(tmp_path):
@@ -179,12 +186,14 @@ async def test_degraded_hint_never_advertises_an_unresolvable_id(tmp_path, monke
assert "src/flask/app.py:122-200" in hint
-async def test_degraded_with_no_anchor_match_is_unchanged(tmp_path):
- """The no-evidence degraded payload keeps its old shape.
+async def test_degraded_with_no_anchor_match_keeps_its_verdict(tmp_path):
+ """The no-body degraded payload keeps every judgement it was making.
- This path is still reached (a question that names nothing indexed), and the
- reply it gives (ranked hits plus where to look) is the right one. The fix
- adds a branch; it must not rewrite the branch that was already correct.
+ This path is still reached (a question that names nothing indexed). It has
+ since gained the choosing evidence (best_guesses, and code_rationale where
+ the source carries any), but the verdict it reports about itself — low
+ confidence, the degradation reason, an `answer` that describes a ranking and
+ not a body — must be exactly what it was.
"""
ctx = _tree(tmp_path)
payload = await _degraded(ctx, _hits(end_line=6), set())
@@ -216,6 +225,7 @@ async def _quality(hits, **kw):
payload = await _degraded_payload(
reason="no-llm-provider",
note="DEGRADED",
+ question="how does the module work",
hits=hits,
fallback_targets=["pkg/m0.py"],
repository=None,
@@ -262,6 +272,7 @@ async def test_degraded_keeps_confidence_low():
payload = await _degraded_payload(
reason="no-llm-provider",
note="DEGRADED",
+ question="how does the module work",
hits=_scored(6.0, 1.0),
fallback_targets=["pkg/m0.py"],
repository=None,
@@ -280,6 +291,7 @@ async def test_degraded_hint_says_what_is_missing_not_what_to_doubt():
payload = await _degraded_payload(
reason="no-llm-provider",
note="DEGRADED",
+ question="how does the module work",
hits=_scored(6.0, 1.0),
fallback_targets=["pkg/m0.py"],
repository=None,
@@ -295,6 +307,7 @@ async def test_degraded_hint_still_pushes_back_on_weak_retrieval():
payload = await _degraded_payload(
reason="no-llm-provider",
note="DEGRADED",
+ question="how does the module work",
hits=_scored(6.0, 5.9),
fallback_targets=["pkg/m0.py"],
repository=None,
@@ -349,3 +362,137 @@ async def test_degraded_note_names_symbol_bodies_when_it_has_them(tmp_path):
assert "symbol_bodies" in payload["note"]
assert "symbol_bodies" in payload["_meta"]["hint"]
+
+
+# --- the choosing evidence, which never needed an LLM either (D12) ----------
+#
+# The legacy abstain path builds per-candidate justifications and mines
+# rationale comments from source, with no provider. The no-provider path is the
+# same situation with a different cause and got neither: 0 of 26 on both fields
+# in the paired keyless arm.
+
+
+async def test_degraded_carries_the_candidate_justifications(tmp_path):
+ """Why each ranked file is in the running — the pick-one signal.
+
+ Without it the reply is a ranked list with no stated reason, which is the
+ pointers-only shape that sends an agent into a Grep spree.
+ """
+ ctx = _tree(tmp_path)
+ payload = await _degraded(ctx, _hits(end_line=6), {"Blueprint"})
+
+ assert [g["file"] for g in payload["best_guesses"]] == ["src/flask/app.py"]
+ assert payload["best_guesses"][0]["why_relevant"]
+
+
+async def test_degraded_names_where_to_start_when_it_has_no_body(tmp_path):
+ """A payload with no body still owes the caller one next step."""
+ ctx = _tree(tmp_path)
+ payload = await _degraded(ctx, _hits(end_line=6), {"Blueprint"})
+
+ assert payload["next_action_hint"].startswith("Start from src/flask/app.py")
+
+
+async def test_degraded_body_hint_still_wins_over_the_candidate_hint(tmp_path):
+ """The two hints are exclusive; the candidate one must not overwrite the body one."""
+ ctx = _tree(tmp_path)
+ payload = await _degraded(ctx, _hits(end_line=6), {"Flask"})
+
+ assert "Read the Flask body" in payload["next_action_hint"]
+ assert "Start from" not in payload["next_action_hint"]
+
+
+async def test_degraded_mines_rationale_comments_from_the_candidates(tmp_path):
+ """A rationale comment is a cited answer, not a pointer — and needs no provider."""
+ src = tmp_path / "pkg"
+ src.mkdir()
+ (src / "cache.py").write_text(
+ "# The TTL is 300 seconds because the upstream feed refreshes every\n"
+ "# five minutes; polling faster only burns quota.\n"
+ "TTL = 300\n",
+ encoding="utf-8",
+ )
+ ctx = SimpleNamespace(path=str(tmp_path), session_factory=None)
+ hits = [{"target_path": "pkg/cache.py", "title": "cache", "summary": "s", "score": 4.0}]
+
+ payload = await _degraded_payload(
+ reason="no-llm-provider",
+ note="DEGRADED",
+ question="why is the TTL 300 seconds",
+ hits=hits,
+ fallback_targets=["pkg/cache.py"],
+ repository=None,
+ t0=0.0,
+ ctx=ctx,
+ question_ids=set(),
+ exclude_spec=None,
+ )
+
+ assert payload["code_rationale"]
+ assert "upstream feed" in payload["code_rationale"][0]["comment"]
+ assert "code_rationale" in payload["note"]
+
+
+async def test_degraded_does_not_ship_the_excerpt_twice(tmp_path):
+ """`best_guesses[].excerpt` and `retrieval[].excerpt` are the same bytes.
+
+ Redundant here and not on the abstain path, which ships `retrieval: []`.
+ Measured at 21.3% of one payload before the serve-time drop existed.
+ """
+ ctx = _tree(tmp_path)
+ hits = _hits(end_line=6)
+ hits[0]["excerpt"] = "x" * 1500
+ payload = await _degraded(ctx, hits, {"Blueprint"})
+
+ assert payload["retrieval"][0]["excerpt"] == "x" * 1500
+ assert "excerpt" not in payload["best_guesses"][0]
+
+
+async def test_degraded_keeps_the_guess_excerpt_when_nothing_duplicates_it(tmp_path):
+ """The drop is keyed on the duplicate being present, so it stays lossless."""
+ payload = {
+ "best_guesses": [{"file": "a.py", "excerpt": "only copy of this content"}],
+ "retrieval": [],
+ }
+ _drop_duplicated_guess_excerpts(payload)
+
+ assert payload["best_guesses"][0]["excerpt"] == "only copy of this content"
+
+
+# --- _first_resolvable_id: the second-id path -------------------------------
+#
+# The guard walks the withheld ids and returns the first one `get_symbol` would
+# answer. Every id on the measured corpus resolved, so "the first is dead, the
+# second is live" has no natural case — only a fixture reaches it.
+
+
+async def test_first_resolvable_id_falls_through_to_the_second(tmp_path):
+ from repowise.server.mcp_server.tool_answer.answer import _first_resolvable_id
+
+ (tmp_path / "m.py").write_text("def real_one():\n pass\n", encoding="utf-8")
+ ctx = SimpleNamespace(path=str(tmp_path), session_factory=None)
+
+ picked = await _first_resolvable_id(
+ ["m.py::Fabricated", "m.py::real_one"], ctx, None, None
+ )
+
+ assert picked == "m.py::real_one"
+
+
+async def test_first_resolvable_id_gives_up_when_none_resolve(tmp_path):
+ """None, not the first id anyway — a dead pointer is worse than no pointer."""
+ from repowise.server.mcp_server.tool_answer.answer import _first_resolvable_id
+
+ (tmp_path / "m.py").write_text("def real_one():\n pass\n", encoding="utf-8")
+ ctx = SimpleNamespace(path=str(tmp_path), session_factory=None)
+
+ assert await _first_resolvable_id(["m.py::Nope", "m.py::AlsoNope"], ctx, None, None) is None
+
+
+async def test_first_resolvable_id_keeps_an_id_whose_file_cannot_be_read(tmp_path):
+ """Absence of evidence, not evidence of fabrication."""
+ from repowise.server.mcp_server.tool_answer.answer import _first_resolvable_id
+
+ ctx = SimpleNamespace(path=str(tmp_path), session_factory=None)
+
+ assert await _first_resolvable_id(["gone.py::Thing"], ctx, None, None) == "gone.py::Thing"
diff --git a/tests/unit/server/mcp/test_answer_early_return_candidates.py b/tests/unit/server/mcp/test_answer_early_return_candidates.py
index e009ab49d..510714959 100644
--- a/tests/unit/server/mcp/test_answer_early_return_candidates.py
+++ b/tests/unit/server/mcp/test_answer_early_return_candidates.py
@@ -24,6 +24,7 @@ from __future__ import annotations
import ast
import inspect
from pathlib import Path
+from types import SimpleNamespace
from repowise.server.mcp_server.tool_answer import answer as answer_mod
from repowise.server.mcp_server.tool_answer.answer import _with_candidates
@@ -157,3 +158,63 @@ def test_a_page_that_names_no_file_never_becomes_a_candidate_here_either():
],
)
assert out["candidates"] == [{"path": "pkg/list.go"}]
+
+
+# --- the rating on the shortlist (D13) -------------------------------------
+#
+# `candidates` is a ranked list; `retrieval_quality` says whether the ranking is
+# worth trusting. Answer-by-union carried the list and no rating — measured 2 of
+# 26 on the paired keyless arm (`Field` / `EmailField`), and it fires for keyed
+# callers too. It is set on that path only, deliberately: see the
+# qualified-miss test below.
+
+
+def _union_payload(tmp_path, quality: str):
+ from repowise.server.mcp_server.tool_answer.answer import _union_answer_payload
+
+ src = "class Field:\n pass\n"
+ (tmp_path / "a.py").write_text(src, encoding="utf-8")
+ (tmp_path / "b.py").write_text(src, encoding="utf-8")
+ homonyms = {
+ "union": {
+ "Field": [
+ {"name": "Field", "file_path": "a.py", "start_line": 1, "end_line": 2},
+ {"name": "Field", "file_path": "b.py", "start_line": 1, "end_line": 2},
+ ]
+ },
+ "qualified_miss": [],
+ }
+ ctx = SimpleNamespace(path=str(tmp_path), session_factory=None)
+ return _union_answer_payload("Field", {"Field"}, homonyms, ctx, None, 0.0, quality)
+
+
+def test_the_union_payload_rates_the_shortlist_beside_it(tmp_path):
+ """It answers from exact bodies, but still offers `candidates` for the
+ wider question — and that offer is what the rating is about."""
+ payload = _union_payload(tmp_path, "high")
+
+ assert payload["grounding"] == "exact_symbol"
+ assert payload["retrieval_quality"] == "high"
+
+
+def test_the_union_rating_is_the_real_one_not_a_flattering_constant(tmp_path):
+ """A weak retrieval beside a confident union answer must still say weak."""
+ assert _union_payload(tmp_path, "weak")["retrieval_quality"] == "weak"
+
+
+def test_the_qualified_miss_guard_stays_unrated(tmp_path):
+ """Deliberate, and the reason is the guard's own purpose.
+
+ That payload exists to say the ranked material is NOT the answer (a
+ same-named symbol under the wrong parent). `_retrieval_quality` reads only
+ the top-two score ratio, so a confident retrieval of the WRONG symbol grades
+ "high" — which would tell the agent not to run the search_codebase call the
+ payload's own note is asking for. No honest value exists here, so no field.
+ """
+ from repowise.server.mcp_server.tool_answer.answer import _no_answer_payload
+
+ payload = _with_candidates(
+ _no_answer_payload("No indexed definition matches...", repository=None, t0=0.0),
+ [{"target_path": "a.py", "score": 6.0}],
+ )
+ assert "retrieval_quality" not in payload
diff --git a/tests/unit/server/mcp/test_answer_synthesis_timeout.py b/tests/unit/server/mcp/test_answer_synthesis_timeout.py
index 9e11804ca..12484a352 100644
--- a/tests/unit/server/mcp/test_answer_synthesis_timeout.py
+++ b/tests/unit/server/mcp/test_answer_synthesis_timeout.py
@@ -374,6 +374,7 @@ async def _payload(reason="synthesis-failed", note="DEGRADED: boom"):
return await _degraded_payload(
reason=reason,
note=note,
+ question="how does mod work",
hits=HITS,
fallback_targets=["pkg/mod.py"],
repository=None,
@@ -400,6 +401,8 @@ async def test_both_failure_modes_return_the_same_payload_shape(reason):
"fallback_targets",
"retrieval",
"candidates",
+ "best_guesses",
+ "next_action_hint",
"note",
"_meta",
}
@@ -439,6 +442,7 @@ async def test_degraded_answer_does_not_promise_hits_it_does_not_have():
payload = await _degraded_payload(
reason="no-llm-provider",
note="DEGRADED",
+ question="how does mod work",
hits=[],
fallback_targets=[],
repository=None,
diff --git a/tests/unit/server/mcp/test_flow_path.py b/tests/unit/server/mcp/test_flow_path.py
index 13609485c..3305120a9 100644
--- a/tests/unit/server/mcp/test_flow_path.py
+++ b/tests/unit/server/mcp/test_flow_path.py
@@ -233,3 +233,85 @@ def test_plumbing_covers_test_material_by_the_shared_rules():
# Production code that merely spells "test" is a legitimate endpoint.
assert not _is_plumbing("src/analysis/missing_test_signal.py")
assert not _is_plumbing("src/latest/api.py")
+
+
+# --- determinism -----------------------------------------------------------
+#
+# Found by the #1510 payload oracle: the same build, same question, same index
+# produced `flow_path` with two equal-length paths in opposite orders, one
+# ordering per run. Adjacency was a dict of sets and BFS walked it, so which of
+# several shortest paths was found moved with the per-process string hash seed —
+# and a nondeterministic ordering can be frozen into the answer cache.
+
+
+def test_adjacency_neighbours_come_back_ordered():
+ """Sets dedupe; the walk needs an order, so the dict hands out sorted lists."""
+ import asyncio
+
+ from repowise.server.mcp_server._flow_path import _load_file_adjacency
+
+ class _Res:
+ def all(self):
+ return [
+ ("a.py", "z.py", "imports", 1.0),
+ ("a.py", "b.py", "imports", 1.0),
+ ("a.py", "m.py", "imports", 1.0),
+ ]
+
+ class _Session:
+ async def execute(self, _stmt):
+ return _Res()
+
+ adj = asyncio.run(_load_file_adjacency(_Session(), "r1"))
+ assert adj["a.py"] == ["b.py", "m.py", "z.py"]
+
+
+def test_bfs_breaks_a_shortest_path_tie_the_same_way_every_time():
+ """A diamond: two 3-hop routes from `a` to `d`. The ordered walk picks one.
+
+ Asserted against the neighbour order rather than "runs twice agree", which a
+ single process cannot demonstrate — the seed is fixed for its lifetime.
+ """
+ from repowise.server.mcp_server._flow_path import _bfs_path
+
+ adj = {
+ "a.py": ["b.py", "c.py"],
+ "b.py": ["a.py", "d.py"],
+ "c.py": ["a.py", "d.py"],
+ "d.py": ["b.py", "c.py"],
+ }
+ assert _bfs_path(adj, "a.py", "d.py", 4) == ["a.py", "b.py", "d.py"]
+
+ # The walk is bidirectional and the sides alternate, so on a 2-hop diamond
+ # it is the BACKWARD frontier that reaches the meeting point first. Flip
+ # `d`'s neighbours and the chosen route flips with it — which is the point:
+ # the result follows the walk order, and the walk order is now fixed.
+ flipped = {**adj, "d.py": ["c.py", "b.py"]}
+ assert _bfs_path(flipped, "a.py", "d.py", 4) == ["a.py", "c.py", "d.py"]
+
+
+async def test_the_anchor_cap_keeps_what_retrieval_ranked(session, repo_id):
+ """Determinism must not become an alphabetical bias.
+
+ Eight anchors against a cap of six. The one file retrieval ranked sorts LAST
+ alphabetically, so it survives the cap only if rank is what decides.
+ """
+ stems = ["alpha", "beta", "gamma", "delta"]
+ ranked = "zzz/delta.py"
+ paths_seeded = [_ANSWER, ranked] + [f"{d}/{s}.py" for s in stems for d in ("aaa", "mmm")]
+ for path in dict.fromkeys(paths_seeded):
+ session.add(_page(repo_id, path))
+ session.add(_symbol(repo_id, "get_answer", _ANSWER))
+ session.add(_edge(repo_id, _ANSWER, ranked, "imports"))
+ await session.commit()
+
+ hits = [{"target_path": _ANSWER, "score": 5.0}, {"target_path": ranked, "score": 4.0}]
+ _combined, paths = await expand_via_flow_path(
+ session,
+ repo_id,
+ hits,
+ "how does get_answer reach alpha beta gamma delta",
+ {"get_answer"},
+ )
+
+ assert [_ANSWER, ranked] in paths