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.

MCP get_answer: frame-grounding gate + in-code rationale anchoring (#622)

Raghav Chamadiyadb1ef2dc71ea
diff --git a/packages/server/src/repowise/server/mcp_server/_code_rationale.py b/packages/server/src/repowise/server/mcp_server/_code_rationale.py
index a5f86f5f4..bc14b256e 100644
--- a/packages/server/src/repowise/server/mcp_server/_code_rationale.py
+++ b/packages/server/src/repowise/server/mcp_server/_code_rationale.py
@@ -35,6 +35,8 @@ from __future__ import annotations
import logging
import re
+import subprocess
+from collections import Counter
from pathlib import Path
from typing import Any
@@ -122,31 +124,77 @@ _NEAR_LINE_WINDOW = 60
def _content_terms(query: str | None) -> set[str]:
- """Lowercased alnum tokens from the query, stopwords + len<3 dropped."""
+ """Lowercased alnum tokens from the query, stopwords + len<3 dropped.
+
+ Drops len<3 tokens, so a bare number like ``40`` never survives here - that
+ is deliberate (a stray digit is a poor term), and is exactly why the literal
+ number is scored separately via :func:`_salient_numbers`.
+ """
if not query:
return set()
raw = re.findall(r"[a-zA-Z0-9_]+", query.lower())
return {t for t in raw if len(t) >= 3 and t not in _STOPWORDS}
-def _score_block(comment: str, terms: set[str]) -> tuple[float, list[str], bool]:
- """Score a comment block. Returns (score, matched_terms, has_marker).
+# A literal number the question pins down (a cap / limit / count / version).
+# ``_content_terms`` drops it (len<3, non-alpha), but the number is often the
+# WHOLE point - "why is X capped at 40" vs "...at 600" can only be told apart by
+# the digit. So it is scored separately, and heavily.
+_NUMBER_RE = re.compile(r"(?<![\w.])-?\d+(?:\.\d+)?(?!\w)")
- Rationale marker = 2.0; each distinct query term present = 1.0. Uses the
- broad ``RATIONALE_MARKERS`` set (intent + causal) shared with the index-time
- harvest — recall mode, so intent-only markers ("never", "always") count.
+
+def _salient_numbers(query: str | None) -> list[str]:
+ """Literal numbers named in the query, as verbatim tokens (e.g. ``40``)."""
+ if not query:
+ return []
+ seen: set[str] = set()
+ out: list[str] = []
+ for n in _NUMBER_RE.findall(query):
+ if n not in seen:
+ seen.add(n)
+ out.append(n)
+ return out
+
+
+def _number_in_text(num: str, low: str) -> bool:
+ """Whole-token match for a number in lowercased text - ``40`` matches
+ ``cap at 40`` but not ``400`` or ``0.40``."""
+ return re.search(rf"(?<![\w.]){re.escape(num)}(?![\w.])", low) is not None
+
+
+def _score_block(
+ comment: str, terms: set[str], numbers: list[str]
+) -> tuple[float, list[str], list[str], bool]:
+ """Score a comment block. Returns (score, matched_terms, matched_nums, has_marker).
+
+ Rationale marker = 2.0; each distinct query term present = 1.0; each literal
+ question number present = 3.0 (the strongest single signal - it identifies
+ the exact constant the question asks about, cutting through cap/limit
+ boilerplate). Uses the broad ``RATIONALE_MARKERS`` set (intent + causal)
+ shared with the index-time harvest - recall mode, so intent-only markers
+ ("never", "always") count.
"""
low = comment.lower()
has_marker = any(m in low for m in RATIONALE_MARKERS)
matched = sorted(t for t in terms if t in low)
- score = (2.0 if has_marker else 0.0) + float(len(matched))
- return score, matched, has_marker
-
-
-def _keep(score: float, matched: list[str], has_marker: bool, has_terms: bool) -> bool:
- """Surfacing gate. With query terms: need a marker+term overlap, or a
- strong (>=2 terms) overlap on its own. Without query terms (path-mode
- "why is this file shaped this way"): a rationale marker is enough."""
+ matched_nums = [n for n in numbers if _number_in_text(n, low)]
+ score = (2.0 if has_marker else 0.0) + float(len(matched)) + 3.0 * len(matched_nums)
+ return score, matched, matched_nums, has_marker
+
+
+def _keep(
+ matched: list[str],
+ matched_nums: list[str],
+ has_marker: bool,
+ has_terms: bool,
+) -> bool:
+ """Surfacing gate. A pinned question number co-occurring with a marker or
+ any content term is kept (the number disambiguates the exact constant).
+ With query terms: need a marker+term overlap, or a strong (>=2 terms)
+ overlap on its own. Without query terms (path-mode "why is this file shaped
+ this way"): a rationale marker is enough."""
+ if matched_nums and (has_marker or matched):
+ return True
if not has_terms:
return has_marker
if has_marker and matched:
@@ -212,6 +260,7 @@ def mine_rationale(
return []
terms = _content_terms(query)
+ numbers = _salient_numbers(query)
has_terms = bool(terms)
near_lines = near_lines or {}
@@ -224,7 +273,7 @@ def mine_rationale(
ordered.append(p)
ordered = ordered[:max_files]
- scored: list[tuple[float, bool, dict]] = []
+ scored: list[tuple[float, bool, bool, dict]] = []
for path in ordered:
ext = path.rsplit(".", 1)[-1].lower() if "." in path else ""
text = _read_text(root, path)
@@ -238,8 +287,8 @@ def mine_rationale(
continue
for block in blocks:
start, end, comment = block.start_line, block.end_line, block.text
- score, matched, has_marker = _score_block(comment, terms)
- if not _keep(score, matched, has_marker, has_terms):
+ score, matched, matched_nums, has_marker = _score_block(comment, terms, numbers)
+ if not _keep(matched, matched_nums, has_marker, has_terms):
continue
if near is not None and abs(start - near) <= _NEAR_LINE_WINDOW:
score += 1.5
@@ -251,11 +300,12 @@ def mine_rationale(
(
score,
has_marker,
+ bool(matched_nums),
{
"path": path,
"lines": [start, end],
"comment": _truncate_block(comment),
- "matched_terms": matched,
+ "matched_terms": matched + matched_nums,
},
)
)
@@ -264,9 +314,85 @@ def mine_rationale(
# any survive, drop the marker-less blocks that only cleared the >=2-term
# gate — on a query with generic terms (lines / source / one) those are
# usually plain docstrings that read as noise next to the real rationale.
- # The term-only blocks remain the recall fallback when nothing has a marker.
- if any(m for _, m, _ in scored):
- scored = [t for t in scored if t[1]]
+ # The term-only blocks remain the recall fallback when nothing has a marker;
+ # a block pinned by a literal question number is always kept (it identifies
+ # the exact constant, marker or not).
+ if any(m for _, m, _, _ in scored):
+ scored = [t for t in scored if t[1] or t[2]]
scored.sort(key=lambda t: t[0], reverse=True)
- return [entry for _, _, entry in scored[:max_results]]
+ return [entry for _, _, _, entry in scored[:max_results]]
+
+
+# Cap / limit vocabulary: a question may say "capped" while the source comment
+# says "limit" (or vice versa). Treat the family as interchangeable anchors so a
+# number-free "why is X limited" question still has something to grep on.
+_CAP_FAMILY: tuple[str, ...] = ("cap", "limit", "max", "bound", "ceiling", "threshold")
+
+# Git-grep is bounded so a pathological pattern can't stall a tool response.
+_GREP_TIMEOUT_S = 20
+
+
+def grep_comment_candidates(
+ repo_root: Any,
+ query: str,
+ *,
+ max_files: int = _MAX_FILES,
+) -> list[str]:
+ """Git-grep COMMENT lines for the question's number(s) + content nouns.
+
+ Concept anchoring's discriminator. Fuzzy retrieval misses the file where a
+ number-bearing behaviour is *explained* ("why is the caller list capped at
+ 50" landed on tool_symbol.py, never enrichment.py). A boilerplate call site
+ (``limit = 50``) carries no comment; the file that explains the choice has a
+ rationale comment mentioning the number + the thing it bounds. So we grep
+ comment-leading lines (``#`` / ``//`` / ``--`` / ``*``) that carry a salient
+ number (or, number-free, a cap-family word) AND a content noun, then rank
+ files by how many such lines they hold.
+
+ Returns a ranked, deduped list of repo-relative paths (most matches first),
+ capped at ``max_files``. Best-effort: ``[]`` on any failure, never raises.
+ The winning files are meant to be fed straight into :func:`mine_rationale`.
+ """
+ try:
+ root = Path(str(repo_root))
+ except Exception:
+ return []
+ if not repo_root:
+ return []
+ numbers = _salient_numbers(query)
+ terms = _content_terms(query)
+ nouns = [t for t in terms if t not in _CAP_FAMILY]
+ anchors = list(numbers) or list(_CAP_FAMILY)
+ if not nouns or not anchors:
+ return []
+ noun_alt = "|".join(re.escape(n) for n in nouns)
+ anchor_alt = "|".join(re.escape(a) for a in anchors)
+ # A comment-leading line containing an anchor AND a content noun, in either
+ # order. ``git grep`` keeps the scan inside tracked files only.
+ pat = (
+ rf"^\s*(#|//|--|\*).*({anchor_alt}).*({noun_alt})"
+ rf"|^\s*(#|//|--|\*).*({noun_alt}).*({anchor_alt})"
+ )
+ try:
+ proc = subprocess.run(
+ # --no-pager + stdin=DEVNULL are load-bearing, not cosmetic: this can
+ # run inside a stdio MCP server whose stdin IS the JSON-RPC pipe.
+ # subprocess.run does NOT redirect stdin by default, so a pager / hook
+ # that reads stdin would consume the protocol stream and deadlock the
+ # whole server. Redirect it to /dev/null and disable the pager.
+ ["git", "--no-pager", "grep", "-n", "-I", "-i", "-E", pat, "--", "*.py", "*.ts", "*.tsx"],
+ cwd=str(root),
+ capture_output=True,
+ text=True,
+ stdin=subprocess.DEVNULL,
+ timeout=_GREP_TIMEOUT_S,
+ )
+ except Exception:
+ return []
+ counts: Counter[str] = Counter()
+ for line in proc.stdout.splitlines():
+ path = line.split(":", 1)[0]
+ if path:
+ counts[path] += 1
+ return [p for p, _ in counts.most_common(max_files)]
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 a222fb0ea..e4e259511 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
@@ -74,6 +74,7 @@ from repowise.server.mcp_server._meta import answer_hint as _answer_hint
from repowise.server.mcp_server._meta import build_meta as _build_meta
from repowise.server.mcp_server.tool_answer.confidence import (
_answer_is_hedged,
+ _frame_term_grounding,
_is_value_question,
_ungrounded_numbers,
)
@@ -101,6 +102,7 @@ from repowise.server.mcp_server.tool_answer.retrieval import (
)
from repowise.server.mcp_server.tool_answer.symbols import (
_anchor_symbol_hits,
+ _concept_anchor_hits,
_extract_question_identifiers,
_extract_value_answer,
_hydrate_symbols_for_hits,
@@ -157,6 +159,14 @@ def _gather_code_rationale(ctx, hits: list[dict], fallback_targets: list[str], q
path = h.get("target_path")
if not path:
continue
+ # A concept-anchored file leads: it was selected precisely because its
+ # comment explains the question, and the grep match line is the best
+ # near-line boost we have.
+ if h.get("_concept_anchored"):
+ candidates.append(path)
+ cl = h.get("_concept_near_line")
+ if cl and path not in near_lines:
+ near_lines[path] = cl
for s in (h.get("_anchor_symbols") or []) + [
s for s in (h.get("symbols") or []) if s.get("_matched")
]:
@@ -218,8 +228,10 @@ async def get_answer(
"""Synthesised answer with citations and a calibrated trust signal.
First call for "how does X work" / "where is Y" / "why is Z" questions.
- confidence=high is content-grounded (value + citation-source gates):
- cite it directly, no verification Read needed. Low confidence returns
+ confidence=high is content-grounded (value + citation-source + frame
+ gates): cite it directly, no verification Read needed. A "why" answer
+ whose named mechanism is absent from the retrieved source is downgraded
+ to medium (the rationale may be conflated). Low confidence returns
best_guesses with one-line justifications instead of an empty answer.
retrieval_quality separately rates the retrieval that fed synthesis.
When the answer names a function/method/class, ``symbol_bodies`` carries
@@ -387,6 +399,14 @@ async def get_answer(
with contextlib.suppress(Exception):
async with get_session(ctx.session_factory) as session:
hits = await _anchor_symbol_hits(session, repo_id, question_ids, hits)
+ # Concept anchoring: when a why/value question pins a literal number to a
+ # described behaviour (no named symbol), grep source COMMENTS for the file
+ # that justifies the number and anchor it as a dominant hit. Rescues the
+ # retrieval-miss class where the rationale lives in a code comment fuzzy
+ # retrieval did not rank.
+ if _is_why_question(question) or _is_value_question(question):
+ with contextlib.suppress(Exception):
+ hits = await _concept_anchor_hits(getattr(ctx, "path", None), question, hits)
# Always cap retrieval hits at 5 for the response payload.
hits = hits[:5]
@@ -793,6 +813,26 @@ async def get_answer(
if not any(h.get("symbols") for h in hits if h.get("target_path") in cited):
confidence = "medium"
+ # Sixth gate — frame grounding (why-questions): a high-confidence "why"
+ # answer must explain the rationale in terms the cited material actually
+ # contains. The dominance gate is generous on repo-internal why-questions
+ # (an anchored symbol + a dominant hit clear it), so a synthesis that
+ # conflates two mechanisms — right number, right file, wrong reason —
+ # rides through at high confidence. The tell is a distinctive code-like
+ # term (a class / function / module the answer names as the cause) that
+ # appears nowhere in everything retrieval showed. When such terms are not
+ # outweighed by grounded ones, downgrade high→medium so the consumer
+ # verifies the "because X" instead of trusting it. Scoped to why-questions:
+ # mechanism/architecture answers legitimately introduce vocabulary; only
+ # rationale claims, where an unsupported frame is a factual error, get gated.
+ frame_unsupported: list[str] = []
+ if confidence == "high" and not hedged and _is_why_question(question):
+ frame_unsupported, _grounded_terms = _frame_term_grounding(answer_text, question, hits)
+ if frame_unsupported and len(frame_unsupported) >= _grounded_terms:
+ confidence = "medium"
+ else:
+ frame_unsupported = []
+
# retrieval_quality is a separate signal from confidence. Where confidence
# says "how much should you trust the synthesised text", retrieval_quality
# says "how good was the retrieval that fed it". The agent uses confidence
@@ -884,6 +924,32 @@ async def get_answer(
f"Read {fallback_targets[0]} and verify the asserted value(s) "
f"{ungrounded_values} against the live source."
)
+ elif frame_unsupported:
+ # The synthesised "why" leaned on a term retrieval never showed,
+ # so the real rationale likely lives in a code comment the wiki /
+ # 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 = _drop_already_surfaced(code_rationale, symbol_bodies, quotes)
+ if code_rationale:
+ payload["code_rationale"] = code_rationale
+ payload["note"] = (
+ f"Frame-grounding gate: the answer names {frame_unsupported} to "
+ "explain the rationale, but that term is absent from every "
+ "retrieved excerpt — the 'why' may be conflated with a different "
+ "mechanism. Downgraded to medium; verify against "
+ f"{fallback_targets[0] if fallback_targets else 'the cited source'}"
+ + (
+ " or the code_rationale comments below."
+ if code_rationale
+ else "."
+ )
+ )
+ payload["next_action_hint"] = (
+ f"Verify the rationale before citing: the asserted frame term(s) "
+ f"{frame_unsupported} are not in the retrieved material."
+ )
elif confidence == "high":
payload["note"] = (
"High confidence: top retrieval result clearly dominates "
@@ -893,6 +959,23 @@ async def get_answer(
"is missing."
)
+ # Concept anchoring put a comment-justified file at the top, so synthesis
+ # may now run high - but the agent asked a "why is X = <number>" question
+ # and the literal rationale is the comment we already mined. Surface it so
+ # 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 = _drop_already_surfaced(
+ concept_rationale, symbol_bodies, quotes
+ )
+ if concept_rationale:
+ payload["code_rationale"] = concept_rationale
+
# Persist to cache (upsert). Best-effort: cache failures must never block
# the response — but they must be LOGGED, not suppressed. A plain INSERT
# under a blanket suppress violated uq_answer_cache_q on every
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 6edabb6c2..27e0d74fa 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
@@ -20,8 +20,13 @@ def _answer_is_hedged(answer_text: str) -> bool:
usable answer — the underlying model happily admits insufficiency even
on a top-scoring hit. Treat an admitted non-answer as low confidence,
regardless of how dominant retrieval was.
+
+ Typographic apostrophes are normalized to ASCII first: the markers use
+ plain "can't" / "i can't", but the LLM routinely emits the curly U+2019,
+ which would slip every apostrophe-bearing marker and let a hedged answer
+ ride through as high confidence.
"""
- low = (answer_text or "").lower()
+ low = (answer_text or "").lower().replace("\u2019", "'").replace("\u02bc", "'")
return any(marker in low for marker in _HEDGE_MARKERS)
@@ -61,6 +66,45 @@ def _is_value_question(question: str) -> bool:
return bool(_VALUE_QUESTION_RE.search(question or ""))
+def _retrieval_corpus(hits: list[dict], *, include_paths: bool = False) -> str:
+ """All text the LLM was shown for *hits*, joined for a grounding check.
+
+ Titles, summaries, snippets, and every hydrated symbol field (name,
+ signature, docstring, source body). ``include_paths`` adds the file paths
+ and anchored-symbol names — useful when grounding identifier-shaped terms
+ (which often live in a path) but deliberately OFF for the number check,
+ where a digit inside a path would falsely ground an asserted value.
+ """
+ parts: list[str] = []
+ for h in hits or []:
+ keys = ("title", "summary", "snippet", "excerpt")
+ if include_paths:
+ keys = (*keys, "target_path")
+ for key in keys:
+ v = h.get(key)
+ if v:
+ parts.append(str(v))
+ for s in h.get("symbols") or []:
+ for key in ("name", "signature", "docstring", "source_excerpt"):
+ v = s.get(key)
+ if v:
+ parts.append(str(v))
+ # A concept-anchored hit carries a rationale comment mined live from the
+ # source. It grounds the question's number (the comment was selected
+ # because it contains it) and is surfaced to the agent as code_rationale.
+ # Without it the value/frame gates would flag the (correct) number the
+ # answer echoes from the question as if synthesis invented it.
+ cr = h.get("_concept_rationale")
+ if isinstance(cr, dict) and cr.get("comment"):
+ parts.append(str(cr["comment"]))
+ if include_paths:
+ for a in h.get("_anchor_symbols") or []:
+ v = a.get("name")
+ if v:
+ parts.append(str(v))
+ return "\n".join(parts)
+
+
def _ungrounded_numbers(answer_text: str, hits: list[dict]) -> list[str]:
"""Numbers the answer asserts that appear nowhere in the retrieval material.
@@ -75,16 +119,70 @@ def _ungrounded_numbers(answer_text: str, hits: list[dict]) -> list[str]:
if not asserted:
return []
- corpus_parts: list[str] = []
- for h in hits or []:
- for key in ("title", "summary", "snippet", "excerpt"):
- v = h.get(key)
- if v:
- corpus_parts.append(str(v))
- for s in h.get("symbols") or []:
- for key in ("name", "signature", "docstring", "source_excerpt"):
- v = s.get(key)
- if v:
- corpus_parts.append(str(v))
- grounded = _numbers_in("\n".join(corpus_parts))
+ grounded = _numbers_in(_retrieval_corpus(hits))
return sorted(asserted - grounded)
+
+
+# Identifier-shaped tokens an answer uses to NAME a mechanism: CamelCase
+# (``PageRank``), snake_case (``apply_pagerank_bias``), dotted paths
+# (``Foo.bar``), or anything bearing a digit. Pure-lowercase English
+# (``centrality``, ``fallback``, ``cache``) is intentionally excluded —
+# only distinctive, code-like terms are strong enough signal that a wrong
+# "why" frame imported a foreign name. Mirrors the question-identifier
+# shape rule in ``symbols._extract_question_identifiers``.
+_FRAME_TOKEN_RE = re.compile(r"[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)*")
+
+
+def _distinctive_terms(text: str) -> set[str]:
+ """Identifier-shaped terms in *text*: internal-caps, snake_case, or digit.
+
+ A LEADING capital alone is NOT enough. Sentence-initial words and markdown
+ headers (``Because``, ``Determine``, ``Mechanism``, ``Short``, ``Since``,
+ ``What``) are prose, not mechanisms — they never appear verbatim in source,
+ so an "any uppercase" rule flags them as ungrounded frame terms and the gate
+ over-fires on the answer's own formatting. Requiring an *internal* uppercase
+ letter keeps real code names (``PageRank``, ``WikiSymbol``, ``AnswerCache``,
+ ``API``) while dropping capitalized English. A single leading-cap class name
+ (``Repository``) is conservatively skipped too: missing a frame term only
+ weakens the gate, whereas over-firing on prose breaks it.
+ """
+ terms: set[str] = set()
+ for tok in _FRAME_TOKEN_RE.findall(text or ""):
+ for c in (tok, *tok.split(".")):
+ if len(c) < 4:
+ continue
+ has_internal_upper = any(ch.isupper() for ch in c[1:])
+ if has_internal_upper or "_" in c or any(ch.isdigit() for ch in c):
+ terms.add(c)
+ return terms
+
+
+def _frame_term_grounding(
+ answer_text: str, question: str, hits: list[dict]
+) -> tuple[list[str], int]:
+ """Split the answer's mechanism-naming terms by whether retrieval grounds them.
+
+ Returns ``(ungrounded, grounded_count)``. A wrong "why" frame betrays
+ itself by importing a distinctive code-like term — a class, a function,
+ a module — that the cited material never contained, while the surface
+ facts (the number, the file) can be right. This surfaces the absent
+ terms so the gate can downgrade when they are not outweighed by grounded
+ ones. Terms the question itself named are excluded: echoing the user's
+ own framing is not a synthesised frame.
+ """
+ answer_terms = _distinctive_terms(answer_text)
+ if not answer_terms:
+ return [], 0
+ q_lower = (question or "").lower()
+ corpus = _retrieval_corpus(hits, include_paths=True).lower()
+ ungrounded: list[str] = []
+ grounded = 0
+ for t in answer_terms:
+ tl = t.lower()
+ if tl in q_lower:
+ continue
+ if tl in corpus:
+ grounded += 1
+ else:
+ ungrounded.append(t)
+ return sorted(ungrounded), grounded
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 d5be58b91..1bdea3392 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
@@ -212,7 +212,13 @@ _HIGH_CONFIDENCE_SCORE_FLOOR = 1.5
# and can carry confidently-asserted ungrounded values.
# v5: `symbol_bodies` field — inline full bodies of question-named symbols so
# the consumer skips the get_symbol follow-up. Cached v4 payloads lack it.
-_ANSWER_SCHEMA_VERSION = 5
+# v6: frame-grounding gate — why-answers naming a mechanism term absent from
+# the retrieval corpus downgrade high→medium. Cached v5 payloads predate the
+# gate and can carry a confidently-asserted, conflated "because X" frame.
+# v7: concept anchoring - number-bearing why/value questions anchor the file
+# whose comment justifies the number and surface that comment as code_rationale
+# even on the high path. Cached v6 payloads predate the anchor + surfacing.
+_ANSWER_SCHEMA_VERSION = 7
# Hard TTL on answer-cache rows. Commit-based invalidation (the payload's
# stamped ``_indexed_commit`` vs the repo's current head) is the primary
diff --git a/packages/server/src/repowise/server/mcp_server/tool_answer/symbols.py b/packages/server/src/repowise/server/mcp_server/tool_answer/symbols.py
index db33d4b15..abdff36fd 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_answer/symbols.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_answer/symbols.py
@@ -275,6 +275,105 @@ async def _anchor_symbol_hits(
return hits
+async def _concept_anchor_hits(
+ repo_root: Path | None,
+ question: str,
+ hits: list[dict],
+) -> list[dict]:
+ """Anchor the file whose rationale COMMENT explains a number-bearing question.
+
+ The symbol anchor above rescues questions that NAME an indexed symbol. This
+ rescues the other retrieval-miss class: a why/value question that pins a
+ literal number to a *described behaviour* (a cap / limit / batch size) but
+ names no symbol. Fuzzy retrieval lands on a same-vocabulary file and never
+ surfaces the one whose comment justifies the number, so it never enters the
+ candidate set and the agent re-reads. We grep tracked source for comment
+ lines carrying the number + a content noun, score the candidates with the
+ existing rationale miner, and inject the winner so retrieval includes it and
+ its comment reaches ``code_rationale``.
+
+ Fires only when the question pins a literal number (the high-precision case;
+ the prototype showed naive number-free grep is too noisy) and the winning
+ file is not already the top retrieval hit (i.e. retrieval genuinely missed
+ it). When the winner is already top, the existing confidence machinery decides
+ the label - we deliberately do NOT force it past the dominance gate, which
+ generalized only to the questions it was tuned on. The mined rationale + its
+ line are stashed on the hit so the downstream ``code_rationale`` surfacing
+ serves the exact comment without a second grep.
+
+ Returns ``hits`` re-sorted by score (mutated in place). Best-effort: any
+ failure leaves ``hits`` untouched.
+ """
+ import asyncio
+
+ from repowise.server.mcp_server._code_rationale import (
+ _salient_numbers,
+ grep_comment_candidates,
+ mine_rationale,
+ )
+
+ if repo_root is None or not question:
+ return hits
+ # Precision gate: only number-bearing questions. A bare "why is X limited"
+ # would grep the whole cap-family vocabulary and over-fire.
+ if not _salient_numbers(question):
+ return hits
+
+ # The grep spawns a subprocess and mine reads files off disk - both blocking.
+ # Run them in a worker thread so they never stall the server's event loop
+ # (this can run inside a stdio MCP server driving the JSON-RPC transport).
+ def _grep_and_mine() -> dict | None:
+ candidates = grep_comment_candidates(repo_root, question)
+ if not candidates:
+ return None
+ mined = mine_rationale(repo_root, candidates, question)
+ return mined[0] if mined else None
+
+ winner = await asyncio.to_thread(_grep_and_mine)
+ if not winner:
+ return hits
+ winner_path = winner.get("path")
+ if not winner_path:
+ return hits
+ # Retrieval-miss gate: only anchor when retrieval did NOT already lead with
+ # the winner. If it is already the top hit, leave the confidence label to the
+ # existing dominance/confidence machinery - forcing it past the gate only ever
+ # helped the questions it was tuned against. The mined comment still reaches
+ # the agent via the gated path's code_rationale.
+ if hits and hits[0].get("target_path") == winner_path:
+ return hits
+
+ near_line = (winner.get("lines") or [0])[0]
+ by_path = {h.get("target_path"): h for h in hits}
+ top_score = max((h.get("score", 0.0) for h in hits), default=0.0)
+ # Above the current top so the comment-justified file dominates the
+ # dominance gate and synthesis runs instead of gating low.
+ anchor_score = max(top_score + 1.5, _HIGH_CONFIDENCE_SCORE_FLOOR + 0.5)
+ target = by_path.get(winner_path)
+ if target is None:
+ target = {
+ "page_id": f"file_page:{winner_path}",
+ "target_path": winner_path,
+ "title": winner_path,
+ "summary": "",
+ "snippet": "",
+ "page_type": "file_page",
+ "score": anchor_score,
+ }
+ hits.insert(0, target)
+ by_path[winner_path] = target
+ else:
+ target["score"] = max(target.get("score", 0.0), anchor_score)
+ target["_concept_anchored"] = True
+ target["_concept_near_line"] = near_line
+ # Stash the mined comment so the code_rationale surfacing can serve it
+ # verbatim on any exit path - including the high path, where the comment IS
+ # the answer the agent would otherwise re-read for.
+ target["_concept_rationale"] = winner
+ hits.sort(key=lambda h: h.get("score", 0.0), reverse=True)
+ return hits
+
+
async def _hydrate_symbols_for_hits(
session,
repo_id: str,
diff --git a/tests/unit/server/mcp/test_answer_calibration.py b/tests/unit/server/mcp/test_answer_calibration.py
index ddb07f37b..9ce16b53a 100644
--- a/tests/unit/server/mcp/test_answer_calibration.py
+++ b/tests/unit/server/mcp/test_answer_calibration.py
@@ -18,6 +18,8 @@ import pytest
from repowise.server.mcp_server.tool_answer.confidence import (
_answer_is_hedged,
+ _distinctive_terms,
+ _frame_term_grounding,
_is_value_question,
_ungrounded_numbers,
)
@@ -44,6 +46,11 @@ class TestHedgeMarkers:
def test_direct_answer_not_hedged(self) -> None:
assert not _answer_is_hedged("The default is 2, set in git_indexer/_constants.py.")
+ def test_curly_apostrophe_hedge_detected(self) -> None:
+ # LLMs routinely emit the curly U+2019; the markers use plain ASCII.
+ # Without normalization this hedged answer rides through as high.
+ assert _answer_is_hedged("I can\u2019t determine why the threshold is 1.2 from the excerpts.")
+
class TestValueQuestionShape:
def test_default_question_is_value_shaped(self) -> None:
@@ -101,6 +108,83 @@ class TestUngroundedNumbers:
assert _ungrounded_numbers("The cap is 100,000 tokens.", hits) == []
+class TestDistinctiveTerms:
+ def test_camelcase_kept(self) -> None:
+ assert "PageRank" in _distinctive_terms("ordered by the PageRank centrality score")
+
+ def test_snake_case_kept(self) -> None:
+ assert "apply_pagerank_bias" in _distinctive_terms("calls apply_pagerank_bias on the set")
+
+ def test_plain_lowercase_dropped(self) -> None:
+ # Common technical English is too broad to gate on.
+ assert _distinctive_terms("the centrality computation caps neighbors") == set()
+
+ def test_capitalized_prose_dropped(self) -> None:
+ # Sentence-initial / markdown-header words are prose, not mechanisms.
+ # A leading capital alone must not register as a frame term (the live
+ # over-fire that flagged Because/Determine/Mechanism/Short/Since/What).
+ assert _distinctive_terms(
+ "## What happens. Because the Mechanism is Short, Determine it Since When."
+ ) == set()
+
+ def test_internal_caps_and_acronyms_kept(self) -> None:
+ terms = _distinctive_terms("It wraps WikiSymbol over an HTTP transport.")
+ assert "WikiSymbol" in terms
+ assert "HTTP" in terms # >=4-char all-caps acronym (internal upper)
+
+ def test_short_tokens_dropped(self) -> None:
+ assert _distinctive_terms("py id db v2") == set() # all <4 chars
+
+ def test_citation_path_yields_no_term(self) -> None:
+ # A lowercase dotted filename is not a distinctive mechanism term.
+ assert _distinctive_terms("see pkg/alpha/one.py for details") == set()
+
+
+class TestFrameTermGrounding:
+ HITS = [
+ {
+ "title": "enrichment",
+ "summary": "Caller/callee rollup for symbol context.",
+ "snippet": "",
+ "target_path": "mcp/enrichment.py",
+ "symbols": [
+ {
+ "name": "_count_call_neighbors",
+ "signature": "def _count_call_neighbors(...)",
+ "docstring": "Counts distinct caller neighbors above confidence.",
+ }
+ ],
+ }
+ ]
+
+ def test_foreign_frame_term_is_ungrounded(self) -> None:
+ ungrounded, grounded = _frame_term_grounding(
+ "The caller list is limited because the PageRank cap bounds neighbors.",
+ "why is the caller list limited",
+ self.HITS,
+ )
+ assert ungrounded == ["PageRank"]
+ assert grounded == 0
+
+ def test_grounded_frame_term_is_not_flagged(self) -> None:
+ ungrounded, grounded = _frame_term_grounding(
+ "The list is bounded by _count_call_neighbors (mcp/enrichment.py).",
+ "why is the caller list limited",
+ self.HITS,
+ )
+ assert ungrounded == []
+ assert grounded == 1
+
+ def test_question_named_term_is_excluded(self) -> None:
+ # Echoing the user's own framing is not an invented frame.
+ ungrounded, _ = _frame_term_grounding(
+ "It uses PageRank ordering.",
+ "why does the caller list use PageRank ordering",
+ self.HITS,
+ )
+ assert ungrounded == []
+
+
# ---------------------------------------------------------------------------
# End-to-end gate behaviour through get_answer
# ---------------------------------------------------------------------------
@@ -535,3 +619,100 @@ async def test_gated_answer_surfaces_code_rationale(setup_mcp, monkeypatch, tmp_
assert "best_guesses" in result # confirms we hit the gated path
assert "code_rationale" in result
assert any("OOMs" in r["comment"] for r in result["code_rationale"])
+
+
+# ---------------------------------------------------------------------------
+# Frame-grounding gate — a why-answer naming a mechanism term absent from the
+# retrieved source is downgraded from high to medium (conflated rationale).
+# ---------------------------------------------------------------------------
+
+
+async def test_why_answer_with_unsupported_frame_downgrades_to_medium(setup_mcp, monkeypatch):
+ """High-dominance why-answer whose 'because X' names a term retrieval never
+ showed → medium, not high."""
+ import repowise.server.mcp_server.tool_answer.answer as answer_mod
+ from repowise.server.mcp_server import get_answer
+
+ _patch_pipeline(monkeypatch, answer_mod, with_symbols=True)
+ _patch_provider(
+ monkeypatch,
+ answer_mod,
+ "The caller list is limited because the PageRank centrality cap "
+ "bounds neighbors (pkg/alpha/one.py).",
+ )
+
+ result = await get_answer("why is the caller list limited the way it is")
+ assert result["confidence"] == "medium"
+ assert "PageRank" in result["note"]
+ assert "Frame-grounding" in result["note"]
+ assert "next_action_hint" in result
+
+
+async def test_why_answer_with_grounded_frame_stays_high(setup_mcp, monkeypatch):
+ """The same why-shape, but the named mechanism (MIN_COUNT) IS in the
+ retrieved symbols → confidence stays high."""
+ import repowise.server.mcp_server.tool_answer.answer as answer_mod
+ from repowise.server.mcp_server import get_answer
+
+ _patch_pipeline(monkeypatch, answer_mod, with_symbols=True)
+ _patch_provider(
+ monkeypatch,
+ answer_mod,
+ "The caller list is limited because MIN_COUNT bounds the retries "
+ "(pkg/alpha/one.py).",
+ )
+
+ result = await get_answer("why is the caller list limited the way it is")
+ assert result["confidence"] == "high"
+ assert "High confidence" in result["note"]
+
+
+async def test_frame_gate_scoped_to_why_questions(setup_mcp, monkeypatch):
+ """A mechanism (non-why) question with the same ungrounded term is NOT
+ gated — only rationale claims get the frame check."""
+ import repowise.server.mcp_server.tool_answer.answer as answer_mod
+ from repowise.server.mcp_server import get_answer
+
+ _patch_pipeline(monkeypatch, answer_mod, with_symbols=True)
+ _patch_provider(
+ monkeypatch,
+ answer_mod,
+ "The caller list is bounded by the PageRank centrality cap "
+ "(pkg/alpha/one.py).",
+ )
+
+ result = await get_answer("how does the caller list get bounded")
+ assert result["confidence"] == "high"
+
+
+async def test_frame_gated_answer_surfaces_code_rationale(setup_mcp, monkeypatch, tmp_path):
+ """When the frame gate trips, mine the candidate source for the real
+ rationale comment so the downgrade ships a lead."""
+ import repowise.server.mcp_server as mcp_mod
+ import repowise.server.mcp_server.tool_answer.answer as answer_mod
+ from repowise.server.mcp_server import get_answer
+
+ _patch_pipeline(monkeypatch, answer_mod, with_symbols=True)
+ _patch_provider(
+ monkeypatch,
+ answer_mod,
+ "The caller list is limited because the PageRank cap applies "
+ "(pkg/alpha/one.py).",
+ )
+ (tmp_path / "pkg" / "alpha").mkdir(parents=True)
+ (tmp_path / "pkg" / "alpha" / "one.py").write_text(
+ "# The caller list is limited to 50 because beyond that the rollup\n"
+ "# floods the synthesis context and the agent loses the signal.\n"
+ "CALLER_LIMIT = 50\n",
+ encoding="utf-8",
+ )
+ monkeypatch.setattr(mcp_mod, "_repo_path", str(tmp_path))
+
+ result = await get_answer("why is the caller list limited the way it is")
+ assert result["confidence"] == "medium"
+ assert "code_rationale" in result
+ assert any("floods the synthesis context" in r["comment"] for r in result["code_rationale"])
diff --git a/tests/unit/server/mcp/test_code_rationale.py b/tests/unit/server/mcp/test_code_rationale.py
index 790e154f0..4490a5275 100644
--- a/tests/unit/server/mcp/test_code_rationale.py
+++ b/tests/unit/server/mcp/test_code_rationale.py
@@ -7,8 +7,13 @@ get_why's decision/git search nor get_answer's wiki retrieval can find.
from __future__ import annotations
+import subprocess
+from pathlib import Path
+
from repowise.server.mcp_server._code_rationale import (
+ _salient_numbers,
extract_comment_blocks,
+ grep_comment_candidates,
mine_rationale,
)
@@ -128,7 +133,7 @@ def test_mine_is_bounded_and_safe(tmp_path):
# Path escape: a file outside the root is refused, not read.
_write(tmp_path, "mod.py", PY_SOURCE)
assert mine_rationale(str(tmp_path), ["../../etc/passwd"], None) == []
- # No repo root → empty, no raise.
+ # No repo root -> empty, no raise.
assert mine_rationale(None, ["mod.py"], "x") == []
# Empty file list → empty.
assert mine_rationale(str(tmp_path), [], "x") == []
@@ -169,3 +174,152 @@ def test_mine_caps_result_count(tmp_path):
_write(tmp_path, "big.py", "".join(lines))
out = mine_rationale(str(tmp_path), ["big.py"], None)
assert 0 < len(out) <= 6
+
+
+# --- Number-aware scoring (concept anchoring, piece 1) ----------------------
+
+
+def test_salient_numbers_extracts_whole_tokens():
+ assert _salient_numbers("why is the caller list capped at 50") == ["50"]
+ assert _salient_numbers("cap symbols at 40 not 600") == ["40", "600"]
+ # No number, version-dotted ignored as one float token, no bare words.
+ assert _salient_numbers("why is this limited") == []
+
+
+def test_mine_number_disambiguates_two_caps(tmp_path):
+ """The literal question number picks the right cap comment - the cap-40 vs
+ cap-600 mis-rank the prototype surfaced: _content_terms drops '50', so
+ without number scoring both 'because'-marked caps tie."""
+ src = (
+ "# The caller list cap is 50 because the median fan-in is 2.\n"
+ "CALLER_CAP = 50\n"
+ "# The source line cap is 600 because round-trip count dominates.\n"
+ "SOURCE_CAP = 600\n"
+ )
+ _write(tmp_path, "s.py", src)
+ out = mine_rationale(str(tmp_path), ["s.py"], "why is the caller list capped at 50")
+ assert out
+ assert "50" in out[0]["comment"] and "600" not in out[0]["comment"]
+ assert "50" in out[0]["matched_terms"]
+
+
+def test_mine_number_match_is_whole_token(tmp_path):
+ """'40' must not match '400' / '0.40' - a substring match would re-introduce
+ the very mis-rank number scoring exists to fix."""
+ src = (
+ "# We page in batches of 400 because the API rejects larger requests.\n"
+ "BATCH = 400\n"
+ "# The symbol cap is 40 because dense files flood the context window.\n"
+ "SYMBOL_CAP = 40\n"
+ )
+ _write(tmp_path, "s.py", src)
+ out = mine_rationale(str(tmp_path), ["s.py"], "why does it cap symbols at 40")
+ assert out
+ assert "40" in out[0]["comment"] and "400" not in out[0]["comment"]
+
+
+def _git_repo(tmp_path: Path, files: dict[str, str]) -> Path:
+ """Create a committed git repo so ``git grep`` (tracked-files-only) works."""
+ for name, content in files.items():
+ p = tmp_path / name
+ p.parent.mkdir(parents=True, exist_ok=True)
+ p.write_text(content, encoding="utf-8")
+ subprocess.run(["git", "init", "-q"], cwd=tmp_path, check=True)
+ subprocess.run(["git", "add", "-A"], cwd=tmp_path, check=True)
+ subprocess.run(
+ [
+ "git",
+ "-c",
+ "-c",
+ "user.name=t",
+ "commit",
+ "-qm",
+ "init",
+ ],
+ cwd=tmp_path,
+ check=True,
+ )
+ return tmp_path
+
+
+_CALLER_CAP_FILES = {
+ "enrichment.py": (
+ "def neighbors():\n"
+ " # Cap the caller list at 50 because the median fan-in is 2 and\n"
+ " # 50 covers 99.5% of symbols in a single call.\n"
+ " limit = 50\n"
+ ),
+ # A boilerplate call site: number, but no rationale comment-leading line.
+ "pager.py": "PAGE = 50 # default page size\n",
+ "other.py": "# unrelated note about caching\nX = 1\n",
+}
+
+
+def test_grep_comment_candidates_ranks_number_bearing_file(tmp_path):
+ repo = _git_repo(tmp_path, _CALLER_CAP_FILES)
+ cands = grep_comment_candidates(str(repo), "why is the caller list capped at 50")
+ assert cands, "expected at least one grep candidate"
+ # The file whose COMMENT explains the 50 wins; the boilerplate call site
+ # (trailing comment, not comment-leading) is not matched.
+ assert cands[0] == "enrichment.py"
+ assert "pager.py" not in cands
+
+
+def test_grep_comment_candidates_needs_a_noun(tmp_path):
+ # Numbers but no content noun (all stopwords) -> nothing to anchor on.
+ repo = _git_repo(tmp_path, _CALLER_CAP_FILES)
+ assert grep_comment_candidates(str(repo), "why is it at 50") == []
+ # No repo root -> empty, no raise.
+ assert grep_comment_candidates(None, "why is the caller list capped at 50") == []
+
+
+# --- Concept anchoring hit injection (piece 3) ------------------------------
+
+
+async def test_concept_anchor_injects_winner_as_dominant(tmp_path):
+ from repowise.server.mcp_server.tool_answer.symbols import _concept_anchor_hits
+
+ repo = _git_repo(tmp_path, _CALLER_CAP_FILES)
+ # Retrieval missed enrichment.py - it led with the boilerplate pager file.
+ hits = [
+ {"target_path": "pager.py", "page_type": "file_page", "score": 2.0},
+ {"target_path": "other.py", "page_type": "file_page", "score": 1.0},
+ ]
+ out = await _concept_anchor_hits(
+ Path(str(repo)), "why is the caller list capped at 50", hits
+ )
+ assert out[0]["target_path"] == "enrichment.py"
+ assert out[0]["_concept_anchored"] is True
+ # Dominates the prior top so the dominance gate passes.
+ assert out[0]["score"] > 2.0
+ # The mined comment + its line are stashed for code_rationale surfacing.
+ assert out[0]["_concept_near_line"] >= 1
+ assert "50" in out[0]["_concept_rationale"]["comment"]
+
+
+async def test_concept_anchor_skips_without_a_number(tmp_path):
+ from repowise.server.mcp_server.tool_answer.symbols import _concept_anchor_hits
+
+ repo = _git_repo(tmp_path, _CALLER_CAP_FILES)
+ hits = [{"target_path": "pager.py", "page_type": "file_page", "score": 2.0}]
+ out = await _concept_anchor_hits(
+ Path(str(repo)), "why is the caller list capped", hits
+ )
+ assert all(not h.get("_concept_anchored") for h in out)
+
+
+async def test_concept_anchor_skips_when_retrieval_already_led_with_winner(tmp_path):
+ from repowise.server.mcp_server.tool_answer.symbols import _concept_anchor_hits
+
+ repo = _git_repo(tmp_path, _CALLER_CAP_FILES)
+ # Retrieval already ranked enrichment.py top - leave the confidence label to
+ # the existing machinery; do not force it past the dominance gate.
+ hits = [
+ {"target_path": "enrichment.py", "page_type": "file_page", "score": 2.0},
+ {"target_path": "other.py", "page_type": "file_page", "score": 1.95},
+ ]
+ out = await _concept_anchor_hits(
+ Path(str(repo)), "why is the caller list capped at 50", hits
+ )
+ assert all(not h.get("_concept_anchored") for h in out)