Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
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.pyindex 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 annotationsimport loggingimport re+import subprocess+from collections import Counterfrom pathlib import Pathfrom typing import Any@@ -122,31 +124,77 @@ _NEAR_LINE_WINDOW = 60def _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 Trueif not has_terms:return has_markerif 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(continuefor 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):continueif 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.pyindex 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_hintfrom repowise.server.mcp_server._meta import build_meta as _build_metafrom 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], qpath = 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] = clfor 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 returnsbest_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 everydiff --git a/packages/server/src/repowise/server/mcp_server/tool_answer/confidence.py b/packages/server/src/repowise/server/mcp_server/tool_answer/confidence.pyindex 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 evenon 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), groundeddiff --git a/packages/server/src/repowise/server/mcp_server/tool_answer/config.py b/packages/server/src/repowise/server/mcp_server/tool_answer/config.pyindex 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 primarydiff --git a/packages/server/src/repowise/server/mcp_server/tool_answer/symbols.py b/packages/server/src/repowise/server/mcp_server/tool_answer/symbols.pyindex 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.pyindex 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 pytestfrom 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 pathassert "code_rationale" in resultassert 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.pyindex 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",+ "[email protected]",+ "-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)