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(get_answer): completeness scope gate for truncated symbol bodies (#1444) (#1445)

Akshat malikbd577942efac
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 8f2e78618..70884bef9 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
@@ -117,6 +117,7 @@ from repowise.server.mcp_server._neighbor_rerank import (
from repowise.server.mcp_server.tool_answer.confidence import (
_answer_is_hedged,
_frame_term_grounding,
+ _has_unqualified_exclusivity_over_truncated,
_is_value_question,
_ungrounded_numbers,
)
@@ -1729,6 +1730,20 @@ async def get_answer(
else:
frame_unsupported = []
+ # Seventh gate — completeness scope over truncated bodies: when prose asserts
+ # an unqualified exclusivity claim ("entirely", "the sole", "the only") while
+ # any cited symbol body arrived truncated: true, the answer asserts a global
+ # property from a sample it knows is incomplete (#1444).
+ # Guard: only fires at high (like gates 3 / 5 / 6) so it cannot stack with
+ # other downgrades and push a single response two levels for one problem.
+ exclusivity_over_truncated = False
+ if confidence == "high" and not hedged:
+ exclusivity_over_truncated = _has_unqualified_exclusivity_over_truncated(
+ answer_text, symbol_bodies
+ )
+ if exclusivity_over_truncated:
+ confidence = "medium"
+
# Non-dominant ceiling: ambiguous retrieval is the calibration cost of
# always synthesizing — the answer may be right, but with no single dominant
# page it must never read "high" (cite without verifying). Cap at medium even
@@ -1873,6 +1888,22 @@ async def get_answer(
f"Verify the mechanism before citing: the asserted term(s) "
f"{frame_unsupported} are not in the retrieved material."
)
+ elif exclusivity_over_truncated:
+ # Note names the axis of doubt (what to be uncertain about), not the
+ # check that triggered it — so a reader can tell which kind of doubt
+ # this is without consulting the source code.
+ payload["note"] = (
+ "Answer may not cover every relevant site: a cited symbol's body "
+ "was truncated and the answer makes an unqualified causal claim. "
+ "Other functions may also participate; call get_symbol for the "
+ "full body or verify against "
+ f"{fallback_targets[0] if fallback_targets else 'the cited source'}."
+ )
+ if fallback_targets:
+ payload["next_action_hint"] = (
+ f"Read {fallback_targets[0]} to verify whether other functions "
+ "participate beyond what the truncated symbol body shows."
+ )
elif confidence == "high":
payload["note"] = (
"High confidence: top retrieval result clearly dominates "
diff --git a/packages/server/src/repowise/server/mcp_server/tool_answer/confidence.py b/packages/server/src/repowise/server/mcp_server/tool_answer/confidence.py
index 27e0d74fa..b9fd5cfd5 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_answer/confidence.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_answer/confidence.py
@@ -186,3 +186,44 @@ def _frame_term_grounding(
else:
ungrounded.append(t)
return sorted(ungrounded), grounded
+
+
+# Unattributed exclusivity tokens. Words like "entirely" / "the sole" assert
+# a global property ("I have seen every relevant site") that get_answer cannot
+# observe from a top-k slice. They are only valid when the retrieved material
+# itself makes the claim (a type constraint, an assertion, an explicit comment).
+# "always" / "never" are intentionally excluded — those are temporal, not
+# spatial exhaustiveness claims, and are legitimate when quoting a constraint.
+_EXCLUSIVITY_TOKENS = (
+ "entirely",
+ "solely",
+ "the only",
+ "the sole",
+ "only cause",
+ "only place",
+ "depends only on",
+ "only reason",
+)
+
+
+def _has_unqualified_exclusivity_over_truncated(
+ answer_text: str,
+ symbol_bodies: list[dict],
+) -> bool:
+ """True when the prose makes an exclusivity claim over a truncated body.
+
+ The co-occurrence of (1) an unattributed exclusivity token in the prose
+ and (2) truncated: true on any symbol_bodies entry is the structural bug
+ from issue #1444: exhaustiveness is asserted from a sample the pipeline
+ knows is incomplete.
+
+ Does not fire when no symbol body was truncated — the check gates on the
+ structured flag already present in the response, so it is a no-op on the
+ common case where all bodies were served whole.
+ """
+ if not any(b.get("truncated") for b in (symbol_bodies or [])):
+ return False
+ low = (answer_text or "").lower()
+ low = low.replace("\u2019", "'").replace("\u02bc", "'")
+ return any(tok in low for tok in _EXCLUSIVITY_TOKENS)
+
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 f330d087c..e2d1c1011 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
@@ -429,9 +429,15 @@ _SYSTEM_PROMPT = (
"Aim for 150–400 words — enough to cover the asked aspects without "
"padding. If a [question-match] symbol's source body is provided, "
"you have enough material to answer — ground in that body. Only "
- "hedge (say 'inspect the source' / 'the excerpts do not contain…') "
- "when there is genuinely no relevant signature, docstring, or source "
- "body in the excerpts. Never invent file paths."
+ "hedge about having enough material (say 'inspect the source' / "
+ "'the excerpts do not contain…') when there is genuinely no relevant "
+ "signature, docstring, or source body in the excerpts. Never assert "
+ "exhaustiveness: state what the retrieved excerpts show, not that "
+ "they are the complete set of sites. Unattributed exclusivity "
+ "language ('entirely', 'the sole', 'the only place', 'depends only on') "
+ "is not justified from a top-k slice — omit it unless the retrieved "
+ "material itself (an assertion, a type constraint, or an explicit "
+ "comment) says so. Never invent file paths."
)
_USER_TEMPLATE = """\
@@ -444,6 +450,8 @@ Project wiki excerpts (top {n} retrieval hits):
Answer thoroughly (150–400 words). Cite file paths inline and line
numbers when the excerpt provides them. Prefer a structured layout
(headings, bullets, short code block from the source body) on
-mechanism / architecture questions. Only hedge if no signature,
-docstring, or source body in the excerpts is relevant.
+mechanism / architecture questions. Only hedge about having enough
+material if no signature, docstring, or source body in the excerpts is
+relevant. Do not assert that what you were shown is the complete set
+of sites; qualify causal claims when a symbol's body was truncated.
"""
diff --git a/tests/unit/server/mcp/test_answer_completeness_scope.py b/tests/unit/server/mcp/test_answer_completeness_scope.py
new file mode 100644
index 000000000..242d66835
--- /dev/null
+++ b/tests/unit/server/mcp/test_answer_completeness_scope.py
@@ -0,0 +1,202 @@
+"""Unit tests for completeness scope over truncated symbol bodies (Issue #1444).
+
+The defect: get_answer prose makes an unqualified exclusivity claim ('entirely',
+'the sole', 'the only') while the same response carries truncated: true on a
+cited symbol body. Exhaustiveness is not a property the pipeline can observe.
+
+Proof direction:
+ test_exclusivity_claim_over_truncated_body_fires — FAILS on main, PASSES after fix.
+ test_no_exclusivity_over_complete_body_does_not_fire — PASSES on main and after fix.
+ test_scoped_claim_over_truncated_body_does_not_fire — PASSES on main and after fix.
+
+The assertion targets the exclusivity *claim*, not the omission of the second
+symbol. The natural wrong assertion ("does the answer mention the symbol?")
+would already pass on main because the answer did mention it.
+"""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+import pytest
+
+_TRUNCATED_FN_SYMBOL = {
+ "name": "min_count_policy",
+ "kind": "function",
+ "signature": "def min_count_policy() -> int",
+ "docstring": "Returns the default minimum count.",
+ "start_line": 10,
+ "end_line": 60, # far beyond the hydrated excerpt → truncated: True on the body entry
+ "_matched": True,
+ "source_excerpt": "def min_count_policy() -> int:\n # gate retries\n return MIN_COUNT",
+}
+
+_COMPLETE_FN_SYMBOL = {
+ "name": "min_count_policy",
+ "kind": "function",
+ "signature": "def min_count_policy() -> int",
+ "docstring": "Returns the default minimum count.",
+ "start_line": 10,
+ "end_line": 12, # fits inside the source_excerpt → no truncated flag
+ "_matched": True,
+ "source_excerpt": "def min_count_policy() -> int:\n # gate retries\n return MIN_COUNT",
+}
+
+
+def _patch_pipeline(monkeypatch, answer_mod, *, symbol: dict):
+ async def _fake_retrieve(question, ctx):
+ return [
+ {"page_id": "file_page:pkg/alpha/one.py", "score": 5.0},
+ {"page_id": "file_page:pkg/alpha/two.py", "score": 4.0},
+ ]
+
+ async def _fake_hydrate(hits, ctx, *, scope=None):
+ for i, h in enumerate(hits):
+ h["target_path"] = h["page_id"].removeprefix("file_page:")
+ h["title"] = h["target_path"]
+ h["summary"] = "Auth service summary."
+ h["snippet"] = ""
+ h["page_type"] = "file_page"
+ if i == 0:
+ h["symbols"] = [dict(symbol)]
+ return hits
+
+ monkeypatch.setattr(answer_mod, "_hybrid_retrieve", _fake_retrieve)
+ monkeypatch.setattr(answer_mod, "_hydrate_hits", _fake_hydrate)
+
+
+def _patch_provider(monkeypatch, answer_mod, content: str):
+ class _Provider:
+ provider_name = "mock"
+ model_name = "mock-1"
+
+ async def generate(self, **kwargs):
+ return SimpleNamespace(content=content)
+
+ monkeypatch.setattr(answer_mod, "_resolve_provider_for_answer", lambda _p: _Provider())
+
+
+# ---------------------------------------------------------------------------
+# Predicate unit tests
+# Import is inside methods so the module can be collected on main (where the
+# function does not exist yet) and the e2e tests below can fail properly.
+# ---------------------------------------------------------------------------
+
+
+class TestExclusivityPredicate:
+ def test_exclusivity_detected_when_truncated(self) -> None:
+ from repowise.server.mcp_server.tool_answer.confidence import (
+ _has_unqualified_exclusivity_over_truncated,
+ )
+
+ symbol_bodies = [{"name": "min_count_policy", "truncated": True}]
+ assert _has_unqualified_exclusivity_over_truncated(
+ "The outcome depends entirely on min_count_policy.",
+ symbol_bodies,
+ )
+
+ def test_exclusivity_ignored_when_not_truncated(self) -> None:
+ from repowise.server.mcp_server.tool_answer.confidence import (
+ _has_unqualified_exclusivity_over_truncated,
+ )
+
+ symbol_bodies = [{"name": "min_count_policy"}] # no truncated flag
+ assert not _has_unqualified_exclusivity_over_truncated(
+ "The outcome depends entirely on min_count_policy.",
+ symbol_bodies,
+ )
+
+ def test_scoped_claim_not_flagged(self) -> None:
+ from repowise.server.mcp_server.tool_answer.confidence import (
+ _has_unqualified_exclusivity_over_truncated,
+ )
+
+ symbol_bodies = [{"name": "min_count_policy", "truncated": True}]
+ assert not _has_unqualified_exclusivity_over_truncated(
+ "min_count_policy gates the retry loop; other factors may participate.",
+ symbol_bodies,
+ )
+
+
+# ---------------------------------------------------------------------------
+# End-to-end pipeline tests
+# These three tests prove the fix in both directions without importing any new
+# symbol at module level — they must be collectable on main before the fix.
+# ---------------------------------------------------------------------------
+
+
+async def test_exclusivity_claim_over_truncated_body_fires(setup_mcp, monkeypatch):
+ """FAILS on main, PASSES after fix.
+
+ The defect (#1444): prose makes an unqualified exclusivity claim while a
+ cited symbol body carries truncated: true. The assertion targets the claim,
+ not whether the symbol is mentioned — the answer did mention it on main too.
+ """
+ import repowise.server.mcp_server.tool_answer.answer as answer_mod
+ from repowise.server.mcp_server import get_answer
+
+ _patch_pipeline(monkeypatch, answer_mod, symbol=_TRUNCATED_FN_SYMBOL)
+ _patch_provider(
+ monkeypatch,
+ answer_mod,
+ "The behavior of min_count_policy depends entirely on the initial retry count.",
+ )
+
+ result = await get_answer("Why does min_count_policy behave this way?")
+
+ # On main (no gate): confidence is "high", note is the standard high-confidence note.
+ # After fix: confidence is downgraded to "medium", note names the completeness doubt.
+ assert result["confidence"] != "high", (
+ "Expected confidence to be downgraded because the prose makes an unqualified "
+ "exclusivity claim over a truncated symbol body, but got 'high'."
+ )
+ note = result.get("note", "")
+ assert "truncated" in note.lower(), (
+ f"Expected the note to name the truncation doubt, got: {note!r}"
+ )
+ assert "may not cover" in note.lower() or "other functions" in note.lower(), (
+ f"Expected the note to describe the completeness axis of doubt, got: {note!r}"
+ )
+
+
+async def test_no_exclusivity_over_complete_body_does_not_fire(setup_mcp, monkeypatch):
+ """PASSES on main and after fix (negative control: no truncated body)."""
+ import repowise.server.mcp_server.tool_answer.answer as answer_mod
+ from repowise.server.mcp_server import get_answer
+
+ _patch_pipeline(monkeypatch, answer_mod, symbol=_COMPLETE_FN_SYMBOL)
+ _patch_provider(
+ monkeypatch,
+ answer_mod,
+ "The behavior of min_count_policy depends entirely on the initial retry count.",
+ )
+
+ result = await get_answer("Why does min_count_policy behave this way?")
+
+ # Gate must not fire when no symbol body is truncated.
+ note = result.get("note", "")
+ assert "may not cover" not in note.lower()
+ assert "other functions may also participate" not in note.lower()
+
+
+async def test_scoped_claim_over_truncated_body_does_not_fire(setup_mcp, monkeypatch):
+ """PASSES on main and after fix (negative control: prose is already scoped)."""
+ import repowise.server.mcp_server.tool_answer.answer as answer_mod
+ from repowise.server.mcp_server import get_answer
+
+ _patch_pipeline(monkeypatch, answer_mod, symbol=_TRUNCATED_FN_SYMBOL)
+ _patch_provider(
+ monkeypatch,
+ answer_mod,
+ "The excerpts show min_count_policy gating retries; other functions may also participate.",
+ )
+
+ result = await get_answer("Why does min_count_policy behave this way?")
+
+ # No exclusivity token in prose → gate must not fire despite truncated body.
+ note = result.get("note", "")
+ assert "may not cover" not in note.lower()
+ assert "other functions may also participate" not in note.lower()