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
docs(server): shorten comments in the get_answer tool package (#2576)
Raghav Chamadiyaec7bdb3b5210
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 728503b4a..7b077c411 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@@ -190,10 +190,8 @@ from repowise.server.mcp_server.tool_answer.synthesis import (_log = logging.getLogger("repowise.mcp.answer")-# The excerpt fetch and the prompt formatter each cap page content, and they-# live in different modules — which is how the formatter came to discard more-# than half of every excerpt the fetch had paid a database round-trip for.-# Checked here, at import, because this is the only module that sees both.+# The excerpt fetch and the prompt formatter each cap page content in different+# modules; checked at import here, the only module that sees both caps.if _MAX_CHARS_PER_HIT_EXCERPT < _GATED_EXCERPT_CHARS:raise RuntimeError("get_answer would truncate the page content it fetches: the prompt "@@ -222,15 +220,9 @@ async def _run_retrieval_pipeline() -> _Retrieved:"""Run every retrieval, ranking and enrichment stage, in order.- Everything here is about FINDING the material; nothing here decides what- the answer is. Each expansion stage is best-effort and suppressed on its- own, so one slow or broken backend costs its contribution and never the- call.-- Stages live in ``_answer_pipeline`` so each can evolve without rereading the- orchestrator: hybrid retrieval (FTS + vector + RRF) → hydration → coverage- rerank → domain penalty → intersection boost → PageRank bias → 1-hop graph- expansion. This function only sequences them and decides when to stop.+ Everything here is about FINDING the material; nothing decides the answer.+ Each expansion stage is best-effort and suppressed on its own, so one slow+ or broken backend costs its contribution and never the call."""hits = await _hybrid_retrieve(question, ctx)hits = await _hydrate_hits(hits, ctx, scope=scope)@@ -239,39 +231,23 @@ async def _run_retrieval_pipeline(# they never enter ranking, citations, or fallback_targets.hits = filter_dicts_by_key(hits, "target_path", exclude_spec)- # Identifiers the question names explicitly — drives symbol anchoring- # (below) and question-aware symbol promotion (during hydration).question_ids = _extract_question_identifiers(question)- # Term-coverage re-rank before any graph-aware bias so conjunctive- # matches survive the merge.+ # Coverage re-rank before any graph-aware bias so conjunctive matches survive.hits = _rerank_by_coverage(hits, question)- # Domain heuristic: down-weight cross-domain hits (e.g. UI files for a- # clearly backend question). Cheap tie-breaker, never a hard filter._apply_domain_penalty(hits, question)- # Intersection-retrieval boost for relational questions (multi-entity).- # Pages at the intersection of two split-FTS halves get a 2× bonus.with contextlib.suppress(Exception):await _intersection_boost(question, hits, ctx)- # PageRank bias: nudge architecturally central files above peripheral- # ones at the same retrieval score. Damped + normalised within the- # candidate set so it's a tie-breaker, not a wholesale reordering.+ # Damped and normalised within the candidate set: a tie-breaker only.with contextlib.suppress(Exception):await _apply_pagerank_bias(hits, ctx)- # Graph expansion: 1-hop walk from the top hits to rescue near-misses- # where retrieval landed in the right module but on the wrong file- # (consumer instead of orchestrator). Adds up to 3 neighbors with a- # damped score, then re-sorts.+ # 1-hop walk rescues "right module, wrong file" near-misses.with contextlib.suppress(Exception):hits = await _expand_via_graph(hits, ctx, repo_id)- # Re-filter: graph expansion can pull excluded neighbors back in (before the- # cap, so an excluded neighbor can't occupy a top-5 slot).+ # Graph expansion can pull excluded neighbors back in; re-filter before the cap.hits = filter_dicts_by_key(hits, "target_path", exclude_spec)- # Symbol anchoring: when the question names an indexed function / method /- # class, force its defining file into the candidate set as a dominant hit.- # Fuzzy retrieval misses deep-path definitions even when the symbol is- # indexed; this makes "explain X" one-shot-complete instead of degrading- # to best_guesses on plausible-but-wrong neighbors.+ # Symbol anchoring: force a question-named symbol's defining file in as a+ # dominant hit, since fuzzy retrieval misses deep-path definitions.homonyms: dict = {"union": {}, "qualified_miss": []}if question_ids:with contextlib.suppress(Exception):@@ -285,77 +261,47 @@ async def _run_retrieval_pipeline(repo_root=_anchor_root,session_factory=ctx.session_factory,)- # 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.+ # Concept anchoring: a why/value question pinning a number to a behaviour+ # anchors the file whose source comment justifies that number.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)- # Flow-path expansion: when the question anchors 2+ endpoints (a named- # symbol's file, a module it names), lead with the dependency/call path- # between them. Plain 1-hop expansion (above) rescues "right module wrong- # file" ranking misses; it does NOT reach a far endpoint 2-4 hops away that- # the question names but retrieval never ranked. This threads that path over- # imports + projected calls edges and injects its files so both endpoints- # surface in one call. Runs before the cap so an injected endpoint can take a- # top-5 slot.+ # Flow-path expansion: when the question anchors 2+ endpoints, inject the+ # files on the path between them, reaching a far endpoint 1-hop expansion+ # cannot. This and the stages below run before the cap so an injected file+ # can take a top-5 slot.flow_paths: list[list[str]] = []with contextlib.suppress(Exception):async with get_session(ctx.session_factory) as session:hits, flow_paths = await _expand_via_flow_path(session, repo_id, hits, question, question_ids)- # Neighborhood re-rank: the sibling to flow-path expansion for the flow- # questions it can't reach — the ones whose gold file is never *named*. Seeds- # from the top hits, walks 1-2 hops out over the same graph, and re-ranks the- # reached neighborhood by fused embedding+lexical relevance so a far endpoint- # that lost the corpus-wide retrieval but wins within its own subsystem gets- # a top-5 slot. Additive and gated to flow-shaped questions; a no-op- # otherwise. Runs before the cap so an injected file can land in the top-5.+ # Neighborhood re-rank: for flow questions whose target file is never named,+ # re-rank the 1-2 hop neighborhood of the top hits. No-op on other shapes.with contextlib.suppress(Exception):async with get_session(ctx.session_factory) as session:hits = await _expand_via_neighbor_rerank(session, repo_id, hits, question, ctx)- # Parent-concept surfacing: on a subsystem-shaped question ("overview of X",- # "what subsystem does Y belong to", "where would I add a Z"), lead with the- # concept/rollup page that documents the whole subsystem instead of the more- # specific child pages retrieval ranks above it. Structural + query-shape- # only; a no-op on every other question, so file/implementation queries keep- # today's ranking. Runs before the cap so the parent can take a top-5 slot.+ # Parent-concept surfacing: a subsystem-shaped question leads with the+ # rollup page for the subsystem. No-op on other shapes.with contextlib.suppress(Exception):hits = await _expand_via_parent_page(hits, question, ctx)- # Demote retrieval noise (decision records on non-why questions, test file- # pages on non-test questions) below real pages before the cap, so it can't- # occupy a top-5 slot and feed synthesis. Stable and non-dropping; runs after- # all anchoring/expansion (which inject file/symbol pages, never noise) so it- # only reorders what those stages left in place.+ # Demote noise (decisions on non-why, test pages on non-test questions)+ # below real pages. Non-dropping; after anchoring, which never injects noise.hits = _demote_noise_hits(hits, question, is_why=_is_why_question(question))- # Everything retrieval resolved, in rank order, before the cap. Synthesis- # keeps its 5-hit budget, which is a context-window decision and the- # right one, but the files below the cut are still the best answer to- # "where do I look next", and they used to be discarded. ``candidates``- # (built after synthesis) hands them over at one line each.+ # The pre-cap ranking feeds ``candidates``: files below the synthesis cut+ # are still the best answer to "where do I look next".resolved_pool = list(hits)- # Always cap retrieval hits at 5 for the response payload.hits = hits[:5]- # Enrich each file_page hit with its top-N WikiSymbol rows. Question-- # aware: identifiers extracted from the question promote matching- # symbols and attach a source-body excerpt — the difference between a- # hedged answer on a specific-method question and a grounded one.+ # Question-aware symbol hydration: matching symbols get a body excerpt.if hits:with contextlib.suppress(Exception):async with get_session(ctx.session_factory) as session:await _hydrate_symbols_for_hits(session, repo_id, hits, ctx, question_ids=question_ids, question=question)- # And the shortlist BELOW the synthesis cap: `candidates` names- # those files and, until now, said nothing about any of them.- # Runs here, sharing the open session, and against- # `resolved_pool` rather than `hits` because the whole point is- # the files the cap discarded. Suppressed with the block above:- # a missing `_defines` costs a `defines` key, never an answer.+ # Against `resolved_pool`: the point is the files below the cap.+ # A missing `_defines` costs a `defines` key, never an answer.await _hydrate_candidate_defines(session, repo_id, resolved_pool, question_ids=question_ids)@@ -420,15 +366,8 @@ async def get_answer(repo_id = repository.id# --- Data-shape fast path ----------------------------------------------- # "what fields does each entry in <blob> contain" is answered by mining the- # field set straight from source (a documented {...} shape, else consistent- # key accesses) instead of gating to a best_guesses pointer list — the exact- # payload that triggers the agent's Read/get_symbol drill. Runs before the- # cache and retrieval: it's deterministic from live source, cheap, and reads- # the field set directly (retrieval scatters across every file that touches- # the blob and misses the one file that documents it). Returns None (falls- # through) unless the fields are genuinely grounded, so it can never invent a- # shape.+ # Before cache and retrieval: deterministic from live source, and retrieval+ # scatters across every consumer of the blob. Falls through unless grounded.ds_ids = _extract_question_identifiers(question)if _is_data_shape_question(question, ds_ids):grounded = await asyncio.to_thread(mine_data_shape, getattr(ctx, "path", None), ds_ids)@@ -462,16 +401,8 @@ async def get_answer(homonyms = retrieved.homonymsflow_paths = retrieved.flow_paths- # Agreement dominance recovers the "both retrievers rank this #1" signal that- # RRF fusion compresses out of the numeric score. Computed once and OR'd into- # every place dominance is decided, so it can only LIFT a retrieval.- # Read the vector leg's own recorded status rather than inferring it from- # `hits`, which is capped to 5 by here: "no _vec_rank in the top 5" is also- # what a timed-out, errored, scope-filtered or simply outranked vector leg- # looks like, and those must NOT fall back to the symbol leg.- #- # Above the early returns because they rate their retrieval too. Pure over- # `hits` and the recorded leg status, both settled by the pipeline call above.+ # Computed once, above the early returns (they rate retrieval too). The leg+ # status is read, not inferred from the capped `hits`; see _agreement_dominant.agreement_dominant = (_agreement_dominant(hits,@@ -484,10 +415,8 @@ async def get_answer()# --- Qualified-miss guard ----------------------------------------------- # The question qualified a symbol (``Parent.leaf``) but the exact-name scan- # found the leaf only under OTHER parents. Return not-found rather than- # synthesizing from a same-named symbol elsewhere: a precise query must- # never degrade to a confidently-wrong answer.+ # ``Parent.leaf`` found only under OTHER parents: not-found, never a+ # confidently-wrong answer from a same-named symbol elsewhere.if homonyms.get("qualified_miss"):missed = homonyms["qualified_miss"]return _with_candidates(@@ -524,11 +453,8 @@ async def get_answer(]if not hits:- # Wrapped like every other post-retrieval return even though the pool is- # necessarily empty here (``resolved_pool`` is ``hits`` before the cap, so- # no hits means no pool). Keeping the invariant "every return after- # retrieval goes through ``_with_candidates``" is what stops the next- # reordering of this function quietly re-opening the hole.+ # The pool is empty here, but every post-retrieval return goes through+ # ``_with_candidates`` so a later reordering cannot skip it.return _with_candidates(_no_answer_payload("No wiki hits for this question. Rephrase around the code "@@ -539,16 +465,9 @@ async def get_answer(resolved_pool,)- # Attach real page content to the top hits, once, for every retrieval —- # before anything downstream branches on how good the retrieval looks.- #- # This used to run only when retrieval was NOT dominant, and dominance is- # what earns high confidence: the more certain retrieval was, the less- # prose the model was given, so confident answers were the ones built from- # symbol names alone. Whatever replaces the code below, keep this- # unconditional. Two call sites under different conditions is what made- # that inversion possible, and the cost of enriching a hit that a later- # fast path never reads is one indexed SELECT over at most five rows.+ # Page content for the top hits, unconditionally, before anything branches+ # on retrieval quality: gating it on dominance starves the confident+ # answers of prose. The cost is one indexed SELECT over at most five rows.hits_without_page_content = await _attach_page_excerpts(hits, ctx)if hits_without_page_content:_log.warning(@@ -559,17 +478,9 @@ async def get_answer()# --- Retrieval dominance ------------------------------------------------ # ``dominant`` = retrieval clearly pointed at ONE page (the top hit- # outscores the rest). It no longer decides WHETHER to synthesize — under- # the always-synthesize default, synthesis runs for every retrieval so- # coverage matches a research assistant that answers every question. It now- # feeds the confidence grade (as the starting grade AND the ceiling), rates- # the retrieval, and gates the ambiguous-retrieval evidence folded into the- # reply. All of those read `dominance_reason`, where the two-tier test now- # lives: a second copy of it inside the grade is what let one payload claim- # the top result dominated and append the no-dominant-page caveat to the same- # note. The grade takes the TIER rather than the bool, because the note it- # writes may only quote the measurement that was actually made.+ # Under always-synthesize, dominance feeds the grade, the retrieval rating+ # and the ambiguity evidence rather than deciding whether to synthesize.+ # The grade takes the TIER so its note quotes only the measurement made.always_synthesize = _always_synthesize()dominance = dominance_reason(hits, agreement_dominant=agreement_dominant)dominant = dominance is not None@@ -587,14 +498,9 @@ async def get_answer(resolved_pool,)- # Confidence is the only axis we gate on. We deliberately do NOT add a- # second gate keyed on question shape (e.g. relational questions- # containing connectives like "between", "and", "from"). Relational vs- # non-relational is the wrong axis to gate on: the hard relational- # failures already surface as low-dominance retrievals and are caught- # by the gate above, while a shape-based gate over-fires on confidently- # dominant relational questions and pushes cost back onto the agent's- # own reasoning loop.+ # No second gate on question shape (e.g. relational connectives): hard+ # relational failures already show as low dominance, and a shape gate+ # over-fires on dominant relational questions.# --- Value-extraction fast path ----------------------------------------# Value-shaped question + a question-matched constant in the top hits →@@ -614,9 +520,8 @@ async def get_answer()# --- Synthesis (LLM) ---------------------------------------------------- # Both ways synthesis can go missing return the same payload from the same- # evidence, so they name only what differs between them: why, and what to- # tell the caller.+ # Both ways synthesis can go missing share one payload; they differ only in+ # the reason and the note.async def _degrade(reason: str, note: str) -> dict:payload = await _degraded_payload(reason=reason,@@ -639,10 +544,8 @@ async def get_answer(provider = _resolve_provider_for_answer(getattr(ctx, "path", None))if provider is None:- # Retrieval-only mode (no provider). Return the hits so the agent can- # at least skip the search_codebase step — but mark the degradation- # loudly: an arm/user should never need to diff payload shapes to- # notice synthesis is unplugged.+ # Retrieval-only mode, logged loudly so nobody has to diff payload+ # shapes to notice synthesis is unplugged._log.warning("get_answer running WITHOUT synthesis: no LLM provider resolvable ""(set REPOWISE_PROVIDER + its API key, or any supported API key)."@@ -652,10 +555,8 @@ async def get_answer("Synthesis is unavailable; local retrieval and source evidence remain usable.",)- # Decision fusion (why-shaped questions only) + structured prelude. Both- # layers are gated on signal: no ADRs for the top hits → no decisions- # block, no symbols / commits / decisions → no prelude. Empty layers are- # dropped before formatting, so the prompt never carries hollow scaffolding.+ # Decision fusion (why questions only) and the structured prelude are both+ # dropped when empty, so the prompt never carries hollow scaffolding.top_paths = [h["target_path"] for h in hits if h.get("target_path")]decisions: list[dict] = []if _is_why_question(question) and top_paths:@@ -671,10 +572,8 @@ async def get_answer(context=_build_context_block_v2(hits, prelude=prelude, decisions=decisions),)- # The call budgets itself against what this provider actually needs. A- # remote API answers in single-digit seconds; an agent-CLI subprocess or a- # local model needs minutes, and a flat 30s cancelled every one of those- # before it could return.+ # Budgets its own timeout per provider: a remote API needs seconds, a CLI+ # subprocess or local model needs minutes.answer_text, failure_note = await synthesize(provider,_SYSTEM_PROMPT,@@ -695,11 +594,8 @@ async def get_answer(quotes = build_quotes(hits, answer_text)- # ``served_named_body`` is True once a tier-0 body (the exact symbol the- # question named, resolved by symbol anchoring) is inlined. Its full live- # body IS the ground truth, so a response carrying it is content-grounded- # even when synthesis hedges. The confidence gates read this to avoid the- # "low, go Read" label that contradicts a payload already holding the answer.+ # ``served_named_body``: the question-named symbol's live body is inlined, so+ # the response is content-grounded even when synthesis hedges.repo_root = _repo_root(ctx)symbol_bodies, served_named_body = _build_symbol_bodies(_gather_body_candidates(hits, answer_text), repo_root@@ -735,17 +631,11 @@ async def get_answer(exclude_spec=exclude_spec,)- # Flow-path lead: when the question anchored 2+ endpoints, surface the- # dependency/call chain the answer traverses so the agent sees the path in- # the same call instead of reconstructing it hop by hop.if flow_paths:payload["flow_path"] = [" -> ".join(p) for p in flow_paths[:2]]- # Where to look next, always. ``retrieval`` shrinks as confidence rises- # (correctly: it is re-read evidence, and a trustworthy answer needs less- # of it), but that left the highest-confidence answers naming no file at- # all, which is the one thing an agent always has a use for. This block is- # navigation rather than evidence: the ranked shortlist, one path per line.+ # Where to look next, always: navigation, not evidence, so it survives the+ # shrinking of ``retrieval`` on high-confidence answers.candidates = _serialize_candidates(resolved_pool)if candidates:payload["candidates"] = candidates@@ -777,19 +667,12 @@ async def get_answer(repository=repository,targets=[*citations, *fallback_targets],)- # Each retrieval leg is best-effort so one slow backend cannot block an- # answer, which is right, but it made a lexical-only answer indistinguishable- # from a whole one: nothing failed, nothing was logged where a caller could- # see it, and ``embedder_live`` stayed true because a configured embedder is- # live whether or not this call beat its budget. Named only when a leg- # actually fell over, so a healthy response pays nothing for it.+ # Legs are best-effort, so a lexical-only answer would otherwise look whole.+ # Named only when a leg fell over.if degraded:payload["_meta"]["retrieval_degraded"] = degraded- # After the cache write above, deliberately. That write copies the payload- # as it stood then, so the episode reaches the caller and never the cache- # row, which is why adding it needs no _ANSWER_SCHEMA_VERSION bump: a row- # written before this change and one written after are the same bytes, and- # bumping would invalidate every user's cache for a field that is not in it.+ # After the cache write on purpose: the episode never reaches the cache row,+ # so it needs no _ANSWER_SCHEMA_VERSION bump.await _attach_episode(payload,question=question,@@ -799,11 +682,8 @@ async def get_answer(return payload-# Keep the orchestrator as a literal ``get_answer`` definition for the source--# shape invariants that audit its early returns. The exported function below is-# also literal (rather than a decorator-generated coroutine), because CLI tool-# adapters inspect ``cr_code.co_qualname`` to confirm they invoked the requested-# tool. Both paths still share the one projector here.+# Both definitions are literal ``get_answer``: source-shape tests audit the+# orchestrator's early returns, and CLI adapters check ``cr_code.co_qualname``._get_answer_raw = get_answer_projected_get_answer = projected_answer(_get_answer_raw)diff --git a/packages/server/src/repowise/server/mcp_server/tool_answer/bodies.py b/packages/server/src/repowise/server/mcp_server/tool_answer/bodies.pyindex 1325d641d..32bd79fb5 100644--- a/packages/server/src/repowise/server/mcp_server/tool_answer/bodies.py+++ b/packages/server/src/repowise/server/mcp_server/tool_answer/bodies.py@@ -40,10 +40,8 @@ def _gather_body_candidates(order. Only definitions the answer text actually names qualify; constantsstay in ``quotes``.- ``anchor_names`` switches tier 0 off the prose and onto the identifiers the- QUESTION named: the degraded path, where there is no synthesised text to- match against. Tier 1 is skipped in that mode by construction, since it- exists to catch a symbol only the prose names.+ ``anchor_names`` switches tier 0 onto the identifiers the QUESTION named,+ for the degraded path that has no prose; tier 1 is skipped there."""candidates: list[tuple[int, int, int, str, dict]] = []for h in hits[:_ENRICH_TOP_N_HITS]:@@ -53,8 +51,7 @@ def _gather_body_candidates(for s in h.get("_anchor_symbols") or []:if _selection_names(s.get("name"), answer_text, anchor_names):candidates.append((0, _kind_rank(s), s.get("start_line") or 0, path, s))- # Tier 1 exists to catch a symbol only the PROSE names, so it has- # nothing to do in the degraded mode that has no prose.+ # Tier 1 catches symbols only the prose names; the degraded mode has none.if anchor_names is not None:continuefor s in h.get("symbols") or []:@@ -67,11 +64,8 @@ def _gather_body_candidates(def _selection_names(name: str | None, answer_text: str, anchor_names: set[str] | None) -> bool:"""Whether the text that selects bodies names this symbol.- Two selection texts, one predicate: normally the synthesised answer decides- which definitions are worth inlining, but the degraded path has no prose, so- ``anchor_names`` puts the question's own identifiers in its place. Note the- difference in kind: ``anchor_names`` is an exact set membership, the answer- text a substring match.+ ``anchor_names`` (exact membership) stands in for the answer text+ (substring match) on the degraded path, which has no prose."""if not name:return False@@ -109,21 +103,13 @@ def _build_symbol_bodies() -> tuple[list[dict], bool]:"""Inline the ranked definitions as live source, with the truncation contract.- Returns ``(symbol_bodies, served_named_body)``. ``served_named_body`` is True- once a tier-0 body (the exact symbol the question named) is inlined; the- confidence gates read it to avoid the "low, go Read" label on a payload that- already holds the answer.-- Every step here is prose-independent: the body is re-read live from disk at- the indexed bounds, and when the indexed body outruns the line cap a- ``continuation`` names the exact range read for the remainder plus the- ``withheld_symbols`` it covers. That is why the degraded path can call this- too.-- ``source`` is the live body sliced at the indexed bounds. ``verified: True``- is set only when the cheap bounds gate holds on the live file (the name is- still on its definition line and the stored end still closes the body), the- same gate get_symbol uses; an entry that fails it carries no such key.+ Returns ``(symbol_bodies, served_named_body)``; the latter is True once a+ tier-0 body (the exact symbol the question named) is inlined.++ Prose-independent, so the degraded path calls it too: bodies are re-read+ live at the indexed bounds, and a body past the line cap gets a+ ``continuation`` and its ``withheld_symbols``. ``verified: True`` is set+ only when get_symbol's bounds gate holds on the live file."""symbol_bodies: list[dict] = []seen: set[tuple[str, str]] = set()@@ -136,10 +122,8 @@ def _build_symbol_bodies(if (path, name) in seen:continuesym_end = s.get("end_line") or 0- # Re-read a fuller body than the synthesis excerpt: this block is for- # the agent, so a docstring-heavy def shouldn't spend its whole window- # on docstring and truncate the logic the question asked about. Falls- # back to the hydrator's excerpt if the re-read fails.+ # A fuller body than the synthesis excerpt, so a docstring-heavy def+ # still reaches its logic. Falls back to the hydrator's excerpt.if path not in texts:texts[path] = _read_repo_text(repo_root, path)text = texts[path]diff --git a/packages/server/src/repowise/server/mcp_server/tool_answer/cache.py b/packages/server/src/repowise/server/mcp_server/tool_answer/cache.pyindex 971606abf..f15334ac9 100644--- a/packages/server/src/repowise/server/mcp_server/tool_answer/cache.py+++ b/packages/server/src/repowise/server/mcp_server/tool_answer/cache.py@@ -32,9 +32,8 @@ _log = logging.getLogger("repowise.mcp.answer")def _json_default(obj):"""Serialize the non-JSON types retrieval hits carry (``_sources`` sets).- Before this fallback existed, EVERY cache write failed on the sets the- hybrid retriever attaches to hits — silently, under the old blanket- suppress. The cache never stored a single post-hybrid-pipeline answer.+ Without it every cache write fails on the sets the hybrid retriever+ attaches to hits."""if isinstance(obj, (set, frozenset)):# str-key the sort: a serializer whose whole job is "never fail the@@ -77,22 +76,13 @@ def _cache_bypass_reason(Each reason is logged where it is decided, with its own values, so the logsays why a caller got a fresh synthesis rather than merely that it did.- * schema: payloads from a pre-rework code path do not carry the fields the- current consumer expects. Serving them masks every later improvement until- the row happens to expire, so bypass silently and let the next write- upgrade the row.- * hedged: the retrieval and symbol pipeline has been upgraded since, so give- synthesis another shot with the new context rather than pinning a bad- answer.- * empty: older versions cached gated empty-answer payloads, which pinned a- retrieval miss until TTL. The write side no longer does this; the check- retires the rows that predate the fix.- * excluded: a row cached before ``exclude_patterns`` changed may reference a- now-excluded file in its fields or in its prose. Re-synthesize rather than- scrub the fields and leave the prose dangling.- * commit / TTL: a row synthesised against a previous index may cite moved- code or stale values. The TTL covers pre-stamping rows and gitless repos,- where there is no commit to compare.+ * schema: an older shape would mask every later improvement until expiry.+ * hedged: give synthesis another shot rather than pin a bad answer.+ * empty: retires gated empty-answer rows the write side no longer makes.+ * excluded: the row references a now-excluded file, possibly in its prose,+ so re-synthesize rather than scrub fields and leave the prose dangling.+ * commit / TTL: the row may cite moved code; the TTL covers unstamped rows+ and gitless repos."""cached_version = payload.get("_schema_version", 1)if cached_version < _ANSWER_SCHEMA_VERSION:@@ -164,9 +154,7 @@ async def _serve_cached_answer(targets=[p for p in cached_paths if isinstance(p, str) and p],extra=({"retrieval_degraded": retrieval_degraded} if retrieval_degraded else None),)- # Serve-time, on this path as well as the fresh one: the episode is read- # on every call and never cached into an answer, so a disagreement- # cannot be frozen into a row and served after it has been superseded.+ # Serve-time on this path too, so an episode is never frozen into a row.await _attach_episode(payload,question=question,@@ -190,14 +178,10 @@ async def _write_answer_cache() -> None:"""Persist this answer as the cache row for the question (upsert).- Best-effort: a cache failure must never block the response, but it must be- LOGGED rather than suppressed. A plain INSERT under a blanket suppress- violated ``uq_answer_cache_q`` on every bypass-and-resynthesize round and- failed silently, so hedged and stale rows were never upgraded.- Delete-then-insert in one transaction is the dialect-agnostic upsert. It- also removes the legacy question-only identity on the first successful- synthesis, while the versioned lookup guarantees that row is never served.- The stamped ``_indexed_commit`` is what the read-side freshness check reads.+ Best-effort, but LOGGED rather than suppressed, so a failing write cannot+ silently leave stale rows in place. Delete-then-insert in one transaction+ is the dialect-agnostic upsert (``uq_answer_cache_q``), and also removes the+ legacy question-only identity.The row is a shallow copy taken here, so anything the caller attaches to thepayload after this point reaches the caller and never the cache.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.pyindex 32635f13b..f6be5aacf 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@@ -44,15 +44,9 @@ from repowise.server.mcp_server.tool_answer.symbols import is_symbol_lookup_quesdef _answer_is_hedged(answer_text: str) -> bool:"""True when the synthesized answer confesses it can't answer.- Retrieval dominance alone doesn't tell you whether the LLM produced a- 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.+ The model admits insufficiency even on a top-scoring hit, so an admitted+ non-answer is low confidence however dominant retrieval was. Curly+ apostrophes are normalized first, or they would slip every "can't" marker."""low = (answer_text or "").lower().replace("\u2019", "'").replace("\u02bc", "'")return any(marker in low for marker in _HEDGE_MARKERS)@@ -76,11 +70,8 @@ _FILE_LINE_REF_RE = re.compile(r"[\w./-]+:\d+(?:-\d+)?")# matching sentence-final numbers ("the default is 3.")._NUMBER_RE = re.compile(r"(?<![\w.])-?\d+(?:\.\d+)?(?!\w)(?!\.\d)")-# Digit-grouping separators: ``100_000`` (source) and ``100,000`` (prose) are-# the same value as ``100000``. Strip them on both sides before comparing, or-# a correct constant like ``MAX = 100_000`` reads as ungrounded against an-# answer that says "100000" — a false downgrade on the exact value-shaped-# constants this gate exists to protect.+# Digit-grouping separators: ``100_000`` and ``100,000`` equal ``100000``.+# Stripped on both sides, or a correct constant reads as ungrounded._THOUSANDS_SEP_RE = re.compile(r"(?<=\d)[,_](?=\d)")@@ -126,11 +117,9 @@ def _retrieval_corpus(hits: list[dict], *, include_paths: bool = False) -> str: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.+ # A concept-anchored hit's rationale comment was selected for containing+ # the question's number; without it the value/frame gates would flag the+ # correct number the answer echoes as invented.cr = h.get("_concept_rationale")if isinstance(cr, dict) and cr.get("comment"):parts.append(str(cr["comment"]))@@ -145,11 +134,8 @@ def _retrieval_corpus(hits: list[dict], *, include_paths: bool = False) -> str:def _ungrounded_numbers(answer_text: str, hits: list[dict]) -> list[str]:"""Numbers the answer asserts that appear nowhere in the retrieval material.- The exact failure this guards: synthesis confidently inventing a default- ("the minimum count is 3") when no retrieved excerpt ever contained a 3.- Compares the answer's standalone numbers against the numbers present in- everything the LLM was shown for the hits — titles, summaries, snippets,- and hydrated symbols (signatures, docstrings, source excerpts).+ Guards against synthesis inventing a default ("the minimum count is 3")+ when no retrieved excerpt contained a 3."""asserted = _asserted_numbers(answer_text)if not asserted:@@ -159,28 +145,19 @@ def _ungrounded_numbers(answer_text: str, hits: list[dict]) -> list[str]: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``.+# Identifier-shaped tokens an answer uses to NAME a mechanism (CamelCase,+# snake_case, dotted, digit-bearing). Plain lowercase English is excluded: only+# code-like terms signal that a wrong frame imported a foreign name._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.+ A leading capital alone is not enough: sentence-initial words and headers+ (``Because``, ``What``) would read as ungrounded frame terms. A single+ leading-cap class name is skipped too, since missing a frame term only+ weakens the gate while over-firing on prose breaks it."""terms: set[str] = set()for tok in _FRAME_TOKEN_RE.findall(text or ""):@@ -198,13 +175,10 @@ def _frame_term_grounding() -> 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.+ Returns ``(ungrounded, grounded_count)``. A wrong "why" frame betrays itself+ by importing a code-like term the cited material never contained, even when+ the surface facts are right. Terms the question named are excluded: echoing+ the user's framing is not a synthesised frame."""answer_terms = _distinctive_terms(answer_text)if not answer_terms:@@ -224,12 +198,9 @@ def _frame_term_grounding(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.+# Unattributed exclusivity tokens: they assert a global property a top-k slice+# cannot observe. "always" / "never" are excluded: temporal, not spatial,+# and legitimate when quoting a constraint._EXCLUSIVITY_TOKENS = ("entirely","solely",@@ -248,14 +219,8 @@ def _has_unqualified_exclusivity_over_truncated() -> 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.+ Exhaustiveness asserted from a sample the pipeline knows is incomplete.+ A no-op when every body was served whole."""if not any(b.get("truncated") for b in (symbol_bodies or [])):return False@@ -278,14 +243,9 @@ _PATHISH_SPAN_RE = re.compile(def _code_reference(text: str, name: str) -> bool:"""Does *text* refer to *name* as CODE rather than as an English word?- A bare word-boundary match is not usable here. Withheld symbols include- ``on``, ``line``, ``input``, ``width`` and ``join``, all ordinary English,- so ``\bon\b`` matches "based on the excerpts" and scores a harmless- truncation as harmful. Measured across the transcripts on disk, the naive- matcher put the harm rate 4+ points high and its hits were visibly prose.-- The call shape allows no space before the paren: ``the width (in pixels)``- is a prose parenthetical, not a call, and admitting the space made it one.+ A bare word match is unusable: withheld names like ``on`` or ``width`` are+ ordinary English. The call shape allows no space before the paren, since+ ``the width (in pixels)`` is a prose parenthetical."""n = re.escape(name)patterns = [@@ -312,10 +272,8 @@ def _code_reference(text: str, name: str) -> bool:def _is_distinctive_name(name: str) -> bool:"""Is *name* code-shaped enough that a bare word match cannot be prose?- Internal capital, underscore or digit — the same shape rule- ``_distinctive_terms`` uses. ``_validate`` and ``TodoStore`` qualify;- ``write``, ``main``, ``line`` and ``on`` do not, and those are exactly the- names that collapse confidence on an ordinary English question.+ Internal capital, underscore or digit, the shape rule ``_distinctive_terms``+ uses. ``_validate`` qualifies; ``main`` and ``on`` do not."""return (any(ch.isupper() for ch in name[1:])@@ -343,15 +301,11 @@ def _question_names(question: str, name: str) -> bool:Three tiers, loosest first:- * distinctive names (``_validate``, ``TodoStore``) match case-insensitively- on a word boundary — no English word has that shape;- * a leading-capital name (``Store``) matches only with its own case, so- "the store where results land" does not implicate ``Store``, and not at- the start of a sentence, where the capital is grammar rather than a name- ("Run the indexer, then what?" must not implicate a symbol ``Run``);- * an all-lowercase name (``on``, ``line``, ``write``, ``main``) needs an- actual code context, because a bare word match on those demotes ordinary- questions like "what is the main entry point?".+ * distinctive names match case-insensitively on a word boundary;+ * a leading-capital name (``Store``) matches only with its own case, and+ not as a sentence-initial imperative ("Run the indexer" is not ``Run``);+ * an all-lowercase name (``main``) needs a code context, or "what is the+ main entry point?" would be demoted."""if not question:return False@@ -375,34 +329,19 @@ def implicated_withheld_symbols() -> list[str]:"""Withheld symbols the response actually leans on, worst case first.- Truncation on its own is not a defect: measured on the transcripts on disk,- 31% of responses truncate something and in 22% of those the withheld range- holds nothing the response relies on. Capping confidence on the bare flag- would spend `high` on those for no gain.-- What matters is whether a symbol the response DEPENDS ON is in the withheld- range. Two independent routes, and the split is deliberate:-- * the **question** names it. Always present, so it fires on any answer,- including one whose prose never mentions the symbol at all.- * the **answer** names it in a code context. Only when synthesis ran.-- The question route is what stops this becoming the mistake the previous gate- made: a check conditioned solely on prose stays silent on every answer whose- prose happens not to name the symbol, which was 3 responses in 4 measured.-- It is NOT what protects the no-LLM modes, and an earlier version of this- docstring wrongly claimed it was. Both of those paths now serve bodies:- ``_degraded_payload`` builds them from the question's anchors, and the- homonym-union early return inlines every definition, and neither calls this- gate. The union path caps on truncation alone. The degraded path does not gate- at all, because it has no synthesised claim to demote: its ``confidence`` is- already "low" for want of prose, and what a cut body costs it is said in the- payload instead, by the ``continuation`` on the entry and by the next action.-- ``body_continues`` entries sort first: a symbol whose body was cut by the- truncation boundary is the sharper failure, because the response has already- shown its signature and may reason about behaviour it never saw.+ Truncation alone is not a defect: often the withheld range holds nothing+ the response relies on. What matters is whether a symbol the response+ DEPENDS ON was withheld, found by two independent routes:++ * the **question** names it, which fires even when the prose never+ mentions the symbol;+ * the **answer** names it in a code context (only when synthesis ran).++ Neither no-LLM path calls this: the union path caps on truncation alone,+ and the degraded path has no synthesised claim to demote.++ ``body_continues`` entries sort first: the response has shown that+ symbol's signature and may reason about behaviour it never saw."""hits: list[tuple[int, str]] = []for body in symbol_bodies or []:@@ -451,47 +390,23 @@ def _top_two_score_ratio(hits: list[dict]) -> float:def _agreement_dominant(hits: list[dict], *, vector_leg_keyless: bool = False) -> bool:"""True when the top hit is the confident pick by retriever AGREEMENT.- RRF fusion compresses scores: a page both retrievers rank #1 barely- outscores one they rank #2, so the numeric dominance ratio calls the *most*- confident retrieval "non-dominant" and demotes it. This reads the per-source- ranks instead: when two retrievers put the SAME page at (or within a rank of)- the top, that consensus is a stronger ground-truth signal than any RRF score- margin.-- Conservative. Requires the top hit to be found by BOTH retrievers near the- top of each, to rank no lower than the runner-up in either source, and the- runner-up to be meaningfully weaker. Otherwise returns False and the caller- falls back to the pure ratio/gap gate. Agreement can only LIFT — the demotion- gates still apply.-- ``vector_leg_keyless`` swaps the vector leg for the symbol leg. On an index- with no semantic vectors the vector leg is skipped outright, so ``_vec_rank``- is never written for any question and a fixed FTS+vector pair makes this- signal permanently unreachable — every keyless answer is then graded by the- pure ratio gate, which is exactly the gate this function exists because it- mis-reads. The symbol leg runs on every index and records ``_sym_rank``.-- **The caller must pass the retrieval leg's own status, not infer it from- the hits.** By the time this runs, ``hits`` is capped to the top 5 out of a- much larger fused pool, so "no hit carries a ``_vec_rank``" is *not*- evidence the leg was skipped: a keyed index whose vector leg timed out,- errored, was scope-filtered, or was simply outranked by five FTS-and-symbol- hits presents identically. Substituting on that inference would fire exactly- when evidence is weakest and manufacture "high" confidence from it.-- The symbol pair is held to a stricter rank than the vector pair. FTS and the- symbol leg are not independent — the wiki page FTS indexes contains the- public symbol table the symbol leg matches on — so their agreeing is closer- to one lexical match observed twice than to two retrievers concurring, and- the fusion beside this already prices that leg well below the others.- Requiring an exact rank-0 tie keeps the weaker signal from carrying the- stronger claim.-- Note the consequence: at ``top_rank_max = 0`` the runner-up comparison below- can no longer reject anything, because two hits cannot share rank 0 within- one leg. The symbol pair therefore reduces exactly to "the top hit is #1 in- FTS and #1 in the symbol leg", which is the intended rule; the shared gap- check is retained for the vector pair, where it does constrain.+ RRF compresses scores, so the ratio calls the most confident retrieval+ (both retrievers rank the same page top) "non-dominant". This reads the+ per-source ranks instead. Conservative: the top hit must be found by BOTH+ retrievers near the top, rank no lower than the runner-up in either, and+ the runner-up must be weaker. Agreement only lifts; demotion gates apply.++ ``vector_leg_keyless`` swaps the vector leg for the symbol leg, since a+ keyless index never writes ``_vec_rank``. **The caller must pass the leg's+ own status, not infer it from the hits:** ``hits`` is capped to the top 5,+ so a missing ``_vec_rank`` is not evidence the leg was skipped (it may have+ timed out or been outranked), and substituting then would manufacture+ "high" exactly when evidence is weakest.++ The symbol pair needs an exact rank-0 tie because FTS and the symbol leg+ read overlapping text. At rank 0 the runner-up check cannot reject anything+ (two hits cannot share rank 0 in one leg), so the rule reduces to "#1 in+ both"; the gap check constrains the vector pair only."""if len(hits) < 2:return False@@ -504,9 +419,7 @@ def _agreement_dominant(hits: list[dict], *, vector_leg_keyless: bool = False) -top = hits[0]top_a = top.get("_fts_rank")top_b = top.get(second_field)- # Top must be a consensus pick: found by both retrievers, near the top of- # each. A one-retriever top hit is exactly the ambiguous case we must NOT- # lift.+ # A one-retriever top hit is exactly the ambiguous case not to lift.if top_a is None or top_b is None:return Falseif top_a > top_rank_max or top_b > top_rank_max:@@ -529,29 +442,19 @@ def _agreement_dominant(hits: list[dict], *, vector_leg_keyless: bool = False) -def dominance_reason(hits: list[dict], *, agreement_dominant: bool = False) -> str | None:"""WHICH test found the top hit dominant, or None if none did.- The single owner of "did retrieval clearly point at ONE page". Callers that- only need the verdict take :func:`is_dominant`; the note builder needs the- reason, because the three tiers measure different things and a note that- quotes the wrong one refutes itself.-- * ``"ratio"`` — the top hit outscores the runner-up by a clear multiple.- * ``"gap"`` — where both scores are excellent a close ratio is expected- (6.0 vs 5.4 is a clear win reading as 1.11x), so dominance is an absolute- gap and the RATIO IS NOT THE MEASUREMENT. Quoting it as one prints a near- tie as the reason for confidence.- * ``"agreement"`` — both retrievers independently rank this page top. RRF- compresses fused scores, so this fires around 1.02x; the ratio is not the- measurement here either.- * ``"sole_hit"`` — one hit, nothing to be ambiguous against.-- Coverage (fraction of query terms in the top hit) biases ranking but is- deliberately NOT a gate: natural-language questions rarely put every content- term in one page, so a coverage threshold over-fires.-- No hits at all is not dominance: there is no page for the claim to be about,- and rating that dominant would grade an empty retrieval as merely- under-scoring. Unreachable from the synthesised path, which returns early on- empty hits, but the degraded path rates its retrieval through here too.+ The single owner of "did retrieval clearly point at ONE page". The note+ builder needs the reason, not just the verdict, because a note quoting the+ wrong tier refutes itself.++ * ``"ratio"``: the top hit outscores the runner-up by a clear multiple.+ * ``"gap"``: both scores are excellent, so dominance is an absolute gap+ and the ratio is NOT the measurement (6.0 vs 5.4 reads as 1.11x).+ * ``"agreement"``: both retrievers rank this page top; fires near 1.02x,+ so the ratio is not the measurement here either.+ * ``"sole_hit"``: one hit, nothing to be ambiguous against.++ Coverage is deliberately not a gate: natural-language questions rarely put+ every content term in one page. No hits at all is not dominance."""if not hits:return None@@ -570,14 +473,9 @@ def dominance_reason(hits: list[dict], *, agreement_dominant: bool = False) -> sdef is_dominant(hits: list[dict], *, agreement_dominant: bool = False) -> bool:"""Did retrieval clearly point at ONE page? See :func:`dominance_reason`.- Three callers ask it and they must not disagree: the confidence grade uses it- as both the starting grade and the ceiling, :func:`_retrieval_quality` rates- the retrieval from it, and the payload folds in the ambiguous-retrieval- evidence on it. It used to be computed twice — a two-tier version in the- answer module and a ratio-only re-derivation inside the grade — and the two- disagree in a real window (a 6.0/5.4 pair is dominant by gap and not by- ratio), which is how one payload came to assert that the top result "clearly- dominates" while appending the caveat that retrieval found no dominant page.+ The confidence grade, :func:`_retrieval_quality` and the payload's+ ambiguity caveat all read this one test, so they cannot disagree about the+ same retrieval."""return dominance_reason(hits, agreement_dominant=agreement_dominant) is not None@@ -585,17 +483,9 @@ def is_dominant(hits: list[dict], *, agreement_dominant: bool = False) -> bool:def _retrieval_quality(hits: list[dict], agreement_dominant: bool) -> str:"""Rate the retrieval, independently of the text it fed.- Kept as one function because the degraded path needs the same rating and must- not invent a second one. That path has no synthesised text to rate, but it ran- exactly the same retrieval, and "high" has to mean the same thing to a keyless- caller as to a keyed one or the field is worth less than nothing. It is also- what :func:`_degraded_confidence` grades from, so the two fields on a- synthesis-less payload can never disagree about the same retrieval.-- Reads :func:`is_dominant` rather than re-deriving the ratio, so "weak" means- exactly "not dominant" — the same fact the confidence ceiling and the- ambiguity caveat are keyed on. Without that the payload could rate retrieval- weak and treat it as dominant in the same breath.+ Shared with the degraded path so "high" means the same to keyless and keyed+ callers, and :func:`_degraded_confidence` grades from it. "weak" means+ exactly "not dominant" per :func:`is_dominant`."""top_score = _confidence_score(hits[0]) if hits else 0.0dominant_grade = is_dominant(hits, agreement_dominant=agreement_dominant)@@ -607,27 +497,16 @@ def _retrieval_quality(hits: list[dict], agreement_dominant: bool) -> str:def _degraded_confidence(reason: str, retrieval_quality: str) -> str:"""Grade a synthesis-less payload on what a caller can act on, not on prose.- ``confidence`` used to be pinned to "low" here on the grounds that it rates- the synthesised text and there is none. That referent is the problem, not the- answer to it: the field is what an agent reads to decide whether it still has- work to do, and pinning it told 69 percent of field calls to distrust evidence- that was often excellent — 84 percent of those "low" verdicts were unearned,- and the keyless install that never configures a provider got one on every call- forever. So the field is graded from the retrieval it actually served.-+ The field tells an agent whether it still has work to do, so it is graded+ from the retrieval served rather than pinned "low" for want of prose.Two ceilings, both load bearing:- "high" is unreachable. ``answer`` on this path is assembled boilerplate, and- our own agent instructions license citing a high-confidence answer directly,- so a "high" here would be an invitation to cite the boilerplate. That was the- real objection behind the old pin and it is preserved as a cap rather than- discarded.-- ``synthesis-failed`` stays "low" whatever retrieval did. The evidence is- identical to the no-provider case, but the *situation* is not: a provider is- configured, so a retry can still produce a real answer and this payload is not- the end of the line. "no-llm-provider" is the end of the line — no better reply- is coming for that install — so there the evidence is all there is to grade.+ "high" is unreachable: ``answer`` here is assembled boilerplate, and a+ high-confidence answer is licensed to be cited directly.++ ``synthesis-failed`` stays "low": a provider is configured, so a retry can+ still produce a real answer. "no-llm-provider" is the end of the line, so+ there the evidence is all there is to grade."""if reason != "no-llm-provider":return "low"@@ -637,13 +516,9 @@ def _degraded_confidence(reason: str, retrieval_quality: str) -> str:def _is_question_named_body_cut_by_us(entry: dict, question_ids: set[str]) -> bool:"""Whether this body is the question's own symbol, cut because WE ran out of lines.- ``truncated`` alone is not trustworthy enough to demote on. The stale-bound- case this was written for is now fixed at its source — ``check_symbol_bounds``- clamps every bound to the live file — but the guard still earns its keep on- the ``source_excerpt`` fallback, where the served bytes come from the index- rather than from disk and the live length says nothing. Requiring the served- span to have reached the line cap says the cut was ours, which is the only- case where something was really withheld.+ ``truncated`` alone is not enough to demote on: on the ``source_excerpt``+ fallback the bytes come from the index, not disk. A served span at the line+ cap says the cut was ours, the only case where something was withheld."""if not (entry.get("truncated") and entry.get("continuation")):return False@@ -656,10 +531,8 @@ def _is_enclosing_continuation(entry: dict, implicated: set[str]) -> bool:"""Whether this body simply continues past the cut, rather than losing a symbol.A withheld entry carrying the served body's OWN name is the enclosing symbol- continuing past the cut, not something that never arrived. Calling that "not- served" is wrong about the payload directly above the note, and sends the- caller to get_symbol for a body they already hold most of. The accurate- pointer is the ``continuation`` the entry already carries.+ continuing past the cut; the accurate pointer is its ``continuation``, not+ a get_symbol call for a body the caller mostly holds."""name = entry.get("name")if not (entry.get("continuation") and name in implicated):@@ -670,10 +543,8 @@ def _is_enclosing_continuation(entry: dict, implicated: set[str]) -> bool:class _Grade(NamedTuple):"""The confidence verdict, and every finding the notes are written from.- The gates do not just produce a label: each one that fires records WHAT- it objected to, and the payload builder turns that into the note and the- next action. Carrying the findings out beside the verdict is what keeps- the two in step.+ Each gate that fires records WHAT it objected to, and the payload builder+ writes the note and next action from that, keeping the two in step."""confidence: str@@ -681,13 +552,10 @@ class _Grade(NamedTuple):ratio: floattop_score: floatsecond_score: float- #: Why the grade is "high", or None when it is not: a- #: :func:`dominance_reason` tier, or "symbol_body" / "grounding". The note is- #: written from this rather than from the bare label, because the reasons- #: license different sentences — only "ratio" may quote the ratio as the- #: measurement, and only a dominance tier or "symbol_body" may tell the agent- #: not to re-read. Writing one reason for every high is how a payload came to- #: quote a 1.00x dominance ratio, a tie, as the reason it was confident.+ #: Why the grade is "high", or None: a :func:`dominance_reason` tier, or+ #: "symbol_body" / "grounding". The reasons license different sentences:+ #: only "ratio" may quote the ratio, and only a dominance tier or+ #: "symbol_body" may tell the agent not to re-read.high_reason: str | Noneungrounded_values: list[str]frame_unsupported: list[str]@@ -710,44 +578,25 @@ def _grade_answer() -> _Grade:"""Grade the synthesised answer through the gate cascade, in order.- One starting grade from retrieval dominance, then a run of gates that can- only demote it. Several are guarded on the answer still being at high, so- that one response cannot be pushed two levels for one problem. Read them- as a list of reasons not to trust the prose: the order is the order they- were added, and each comment says which failure it was built to catch.+ One starting grade from retrieval dominance, then gates that can only+ demote it. Several fire only while the answer is still high, so one+ response is not pushed two levels for one problem.``dominance`` is :func:`dominance_reason`'s verdict, computed once by the- caller and used here for the starting grade, the ceiling, and the reason the- note is written from. A bare bool used to be accepted for the ceiling alone- while the starting grade re-derived a ratio-only version of the same- question, so a retrieval the rest of the pipeline treated as dominant could- start the cascade as if it were not.+ caller and used for the starting grade, the ceiling, and the note's reason."""dominant = dominance is not None_ratio = _top_two_score_ratio(hits)_top_score = _confidence_score(hits[0]) if hits else 0.0_second_score = _confidence_score(hits[1]) if len(hits) >= 2 else 0.0- # A response can EARN "high" on a NON-dominant retrieval, by two routes that- # are NOT equally good and so are tracked apart. Both need the score floor,- # and a retrieval that clears the floor and dominates is already high — so- # earning fires exactly when `retrieval_quality` reads "weak".- #- # * `earned_body` — the question named a symbol and its live body is inlined- # in this payload. Resolved by exact name, not by ranking, so how ambiguous- # the ranking was does not bear on it, and "do not re-read the source" is- # literally true: the source is in the response. (An oversized body can- # still arrive cut, which is why the note it writes says "the live body"- # rather than "the full body" and lets the truncation tail speak.)- # * `earned_grounding` — every distinctive mechanism term the answer names- # appears in the material it was shown, and a cited hit carries real symbol- # bodies. That is evidence the model did not FABRICATE a mechanism. It is- # not evidence retrieval found the right page, which is the only thing in- # doubt on a weak retrieval — an answer can be perfectly consistent with- # the wrong file. Off by default; see the env flag's comment.- #- # The demotion gates below (hedge, value, claim-support) still pull an earned- # high back down.+ # Two routes EARN "high" on a non-dominant (weak) retrieval, tracked apart:+ # * `earned_body`: the question-named symbol's live body is inlined, resolved+ # by exact name rather than ranking, so the source is in the response.+ # * `earned_grounding`: every mechanism term the answer names was in the+ # material shown. Shows no fabrication, not that retrieval found the right+ # page, so it is off by default (see the env flag's comment).+ # The demotion gates below still pull an earned high back down.earned_body = Falseearned_grounding = Falseif _flag_on(_EARN_HIGH_GROUNDING_ENV) and _top_score >= _HIGH_CONFIDENCE_SCORE_FLOOR:@@ -762,89 +611,55 @@ def _grade_answer(if (dominant or earn_high) and _top_score >= _HIGH_CONFIDENCE_SCORE_FLOOR:confidence = "high"elif dominant:- # Dominant but weak — the right file relative to its siblings, but- # the signal isn't strong enough to trust the synthesised answer- # without verification. Downgrade so the consumer Reads the source.+ # Dominant but weak: right file relative to its siblings, but not+ # strong enough to trust the synthesis without verification.confidence = "medium"else:confidence = "medium"- # Second gate: downgrade when the LLM's own answer admits insufficiency.- # Retrieval dominance only tells us we indexed the right file; it does- # not mean the synthesized text is usable. Shipping a hedged answer with- # confidence="high" misleads the consumer AND drags the full retrieval- # payload through the conversation cache for no benefit.+ # Hedge gate: dominance says we indexed the right file, not that the+ # synthesised text is usable.hedged = _answer_is_hedged(answer_text)if hedged:- # A hedge means the synthesised PROSE is weak — but when the exact- # symbol the question named is inlined in symbol_bodies (tier-0 anchor,- # full live body), the answer's ground truth is already in-hand. Labeling- # that "low" contradicts the payload and fires the "go Read" hint the- # body makes unnecessary, so the agent bails to Read when it never needed- # to. Hold such a response at medium; the note redirects the agent from- # the hedged prose to the served body.+ # When the question-named symbol's body is served, the ground truth is+ # in hand; "low" would send the agent to Read for nothing.confidence = "medium" if served_named_body else "low"- # Third gate — identifier-citation gate: when the question explicitly- # names identifiers (classes / methods / snake_case / CamelCase) and- # NONE of the top retrieval hits contain any of those identifiers as a- # hydrated symbol, retrieval may be pointing at plausible-but-wrong- # files (same module family, similar vocabulary). Downgrade high->medium- # so the consumer Reads the `fallback_targets`. Only applies when the- # question actually names identifiers — mechanism-descriptive questions- # (no symbol names) are unaffected.+ # Identifier-citation gate: the question names identifiers but no top hit+ # hydrates any of them, so retrieval may be on plausible-but-wrong files.if confidence == "high" and question_ids:top_n = [h for h in hits[:_ENRICH_TOP_N_HITS] if h.get("symbols")]has_match = any(s.get("_matched") for h in top_n for s in (h.get("symbols") or []))if not has_match:confidence = "medium"- # Fourth gate — value grounding: on value-shaped questions (default /- # threshold / limit / how many), every number the answer asserts must- # appear somewhere in the material retrieval actually contained. A- # number synthesis produced from thin air is a factual error delivered- # with authority — the single worst calibration failure, because the- # consumer was told not to verify. Cap and say why.+ # Value gate: on value-shaped questions every asserted number must appear in+ # the retrieved material. An invented number delivered as "high" is the+ # worst calibration failure, because the consumer was told not to verify.ungrounded_values: list[str] = []if not hedged and _is_value_question(question):ungrounded_values = _ungrounded_numbers(answer_text, hits)if ungrounded_values:- # A value derived from grounded operands is not a fabrication, so- # soften one notch instead of capping — but only on a clean high over- # dominant retrieval (earn_high on weak retrieval stays capped), and- # only when some OTHER asserted number is grounded. Without that- # second clause a lone invented value would soften too, which is the- # case this gate exists to catch. The note and next_action_hint fire- # on ungrounded_values regardless of tier.+ # A value derived from grounded operands softens one notch, but only+ # on a dominant high and only when another asserted number is+ # grounded; a lone invented value is what this gate exists to catch.grounded_sibling = len(_asserted_numbers(answer_text)) > len(ungrounded_values)if grounded_sibling and confidence == "high" and dominant:confidence = "medium"else:confidence = "low"- # Fifth gate — citation-source gate: a high-confidence answer must cite- # at least one page that contributed actual source material (hydrated- # symbols with signatures/bodies), not just file summaries. Summary-only- # grounding is how plausible-but-wrong syntheses get through.+ # Citation-source gate: a high answer must cite a page that contributed+ # hydrated symbols; summary-only grounding lets plausible-wrong prose through.if confidence == "high":cited = set(citations)if not any(h.get("symbols") for h in hits if h.get("target_path") in cited):confidence = "medium"- # Sixth gate — claim-support / frame grounding: a high-confidence answer- # must name its mechanism in terms the cited material actually contains. The- # dominance gate is generous on repo-internal questions (an anchored symbol +- # a dominant hit clear it), so a synthesis that conflates two mechanisms —- # right file, wrong reason/function — rides through at high confidence. The- # tell is a distinctive code-like term (a class / function / module the- # answer names AS the mechanism) that appears nowhere in everything retrieval- # showed. When such terms are not outweighed by grounded ones, downgrade- # high->medium so the consumer verifies instead of trusting.- #- # The original gate fired only on "why" questions, but the same failure- # occurs on "how" questions that name the mechanism in the ANSWER, not the- # question. Value questions have their own numeric gate above; naming/lookup- # questions legitimately just echo the named symbol, so they are excluded.+ # Claim-support gate: a synthesis can conflate mechanisms (right file, wrong+ # function) and still clear dominance. The tell is a code-like term the+ # answer names as the mechanism that retrieval never showed. Covers why and+ # how questions; lookups legitimately echo the named symbol.frame_unsupported: list[str] = []_claim_scope = _is_why_question(question) or (_flag_on(_CLAIM_SUPPORT_GATE_ENV) and _is_mechanism_question(question)@@ -856,12 +671,7 @@ def _grade_answer(else:frame_unsupported = []- # Seventh gate — completeness scope over truncated bodies: prose asserts an- # unqualified exclusivity claim ("entirely", "the sole", "the only") while a- # cited symbol body arrived truncated, so the answer asserts a global- # property from a sample it knows is incomplete.- # 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 gate: "the only" / "entirely" asserted over a truncated body.exclusivity_over_truncated = Falseif confidence == "high" and not hedged:exclusivity_over_truncated = _has_unqualified_exclusivity_over_truncated(@@ -870,41 +680,18 @@ def _grade_answer(if exclusivity_over_truncated:confidence = "medium"- # Eighth gate — a WITHHELD symbol the response depends on. The seventh gate- # needs an exclusivity token in the prose as well as truncation, and across- # repeated runs of the reference defect the token usually does not appear:- # the rest are equally incomplete, equally "high", and it stays silent. It is- # also inert by construction in no-LLM mode, where there is no prose to hold- # a token.- #- # This gate keys on the dependency instead. It fires when a symbol in the- # withheld range is named by the QUESTION (every mode) or referenced as code- # by the ANSWER (LLM mode). Truncation alone is deliberately NOT enough: a- # large minority of truncations withhold nothing the response leans on, and- # `high` is worth keeping when it is earned.+ # Withheld-dependency gate: a withheld symbol is named by the question or+ # referenced as code by the answer. Unlike the exclusivity gate it needs no+ # prose token; truncation alone is deliberately not enough.withheld_implicated = implicated_withheld_symbols(question, answer_text, symbol_bodies)if confidence == "high" and withheld_implicated:confidence = "medium"- # Ninth gate — the LOOKUP half of the eighth, and a routing hole rather- # than a threshold problem. Gate 8 asks whether the question names a- # WITHHELD symbol; on a bare-name lookup it provably never can, because the- # question names the symbol that was SERVED and the withheld names are that- # symbol's own inner members. The union path caps on truncation alone for- # exactly this shape, on the grounds that where the caller asked for a symbol- # the bodies ARE the answer. But a name with a single definition never- # reaches the union path — `_anchor_symbol_hits` short-circuits at- # `len(cands) == 1` before `homonyms["union"]` is built — so it lands here- # with the same shape and, until now, no cap. The dominance ratio is not the- # cause and is not touched.- #- # Deliberately narrow. It needs the question to read as a symbol lookup- # rather than prose, AND the truncated body to be the very symbol the- # question named. On a prose question the body is evidence for a claim rather- # than the answer itself, and truncation alone is a poor signal there, which- # is why gate 8 keeps the dependency test for that population. Kept as the- # entry rather than a flag so the note can quote the real served range and- # continuation instead of describing the cut in the abstract.+ # Lookup gate: on a bare-name lookup the question names the SERVED symbol,+ # so the withheld-dependency gate can never fire. A multi-def name caps on+ # truncation in the union path; a single-def name never reaches it, so it+ # is capped here. Narrow on purpose: a symbol-lookup question whose own+ # symbol was cut. Kept as the entry so the note can quote the real range.named_body_cut = next((b for b in symbol_bodies if _is_question_named_body_cut_by_us(b, question_ids)),None,@@ -917,28 +704,15 @@ def _grade_answer(if lookup_body_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- # if every gate passed. (A non-dominant retrieval already scores <high via- # the ratio, so this is usually a no-op; it is explicit so the- # always-synthesize contract — "answered, but verify" — is self-documenting.)- # Exception: an answer that EARNED high is not "cite without verifying". By- # default that means only the served-body route — the source IS in the- # payload — since grounded PROSE is merely consistent with material this same- # retrieval says may be the wrong material, and an agent reads "high" as- # permission to skip the verification that would catch precisely that. The- # exemption is written against `earn_high` rather than `earned_body` so the- # opt-in genuinely restores the old behaviour instead of being overruled two- # lines later.+ # Non-dominant ceiling: with no single dominant page the answer must not+ # read "high" (cite without verifying) unless it EARNED high. Keyed on+ # `earn_high`, not `earned_body`, so the grounding opt-in really restores+ # the old behaviour. Usually a no-op; explicit so the contract is visible.if not dominant and not earn_high and confidence == "high":confidence = "medium"- # Name the reason while the evidence for it is still in scope. The dominance- # tier first, and the specific tier rather than "dominant": the gap and- # agreement tiers fire at ratios near 1.0, so a note quoting the ratio as the- # measurement would print a near tie as its own justification — the reported- # defect, one layer down.+ # The specific dominance tier, not "dominant": gap and agreement fire near a+ # 1.0 ratio, so quoting the ratio would print a near tie as justification.high_reason = Noneif confidence == "high":high_reason = dominance or ("symbol_body" if earned_body else "grounding")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.pyindex 75d9df1d6..b16cec5bf 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@@ -1,9 +1,8 @@"""Tuning constants and prompt templates for get_answer.All of get_answer's knobs live here so the retrieval / synthesis / confidence-modules read like policy applied to data, and the data is tunable in one place.-None of these are repo-specific — they are properties of BM25-style retrieval-with a coverage re-ranker, not of any particular codebase.+modules read like policy applied to data. None are repo-specific: they are+properties of BM25-style retrieval with a coverage re-ranker."""from __future__ import annotations@@ -15,139 +14,77 @@ from repowise.server.mcp_server._query_terms import STOPWORDS_log = logging.getLogger("repowise.mcp.answer")-# How many top retrieval hits to enrich with WikiSymbol context. Enriching-# every hit produces large responses that bloat the cached prompt prefix on-# multi-turn agent sessions without changing the answer — the agent typically-# cites the top-1 file. Top-2 captures the primary navigation need with a-# bounded payload.+# Top hits enriched with WikiSymbol context. Enriching every hit bloats the+# cached prompt prefix on multi-turn sessions; the agent usually cites top-1._ENRICH_TOP_N_HITS = 2-# How many symbols per enriched file. Bounded to keep the context block from-# growing unboundedly on dense files. We allocate more slots to the top hit-# (where the answer usually lives) and fewer to secondary hits.+# Symbols per enriched file: more for the top hit, where the answer usually lives._MAX_SYMBOLS_TOP_HIT = 10_MAX_SYMBOLS_PER_HIT = 4-# When a retrieved file contains symbols whose name matches an identifier-# from the question, we promote those to the top of the symbol list for that-# file, pass a longer docstring, and attach a source excerpt so the LLM-# actually sees the method body — not just a stub docstring. Without this,-# specific-method questions get hedged answers even on dominant retrievals.+# Symbols whose name matches a question identifier are promoted, get a longer+# docstring and a source excerpt, so the LLM sees the body and not just a stub._MATCHED_SYMBOL_DOC_CHARS = 400_MATCHED_SYMBOL_SOURCE_LINES = 40-# Which symbols survive the per-file cap. A `start_line` tiebreak served a-# document-order prefix, so on a file larger than its symbol budget the symbol-# the question was about could not be reached at all. Scoring the already-loaded-# name / signature / docstring against the question's content terms changes which-# symbols fill the same budget, not how many: no extra I/O, no prompt growth.-# A name hit outranks a signature hit outranks a mention in the docstring. With-# no signal every score is 0 and the sort falls back to `start_line` as before.+# Which symbols survive the per-file cap: scored against the question's content+# terms (name > signature > docstring) so a large file's relevant symbol is+# reachable. Changes which symbols fill the budget, not how many. With no signal+# every score is 0 and the sort falls back to `start_line`._RELEVANCE_NAME_WEIGHT = 3_RELEVANCE_SIG_WEIGHT = 2_RELEVANCE_DOC_WEIGHT = 1# Score the docstring's opening prose only, so a long one can't out-score a# precise name on word count alone._RELEVANCE_DOC_CHARS = 400-# A source excerpt used to require a question IDENTIFIER match, so a question-# phrased in prose reached the right symbols and then showed only their-# signatures — the "excerpts don't include the actual code" answer. The leading-# few symbols the question scored against get a body too. Bounded hard: this is-# the one part of the change that adds prompt text.+# The top few relevance-scored symbols get a body excerpt even without an+# identifier match, so prose questions see code. Bounded: this adds prompt text._RELEVANT_EXCERPT_MAX_SYMBOLS = 2-# How many question-named symbol bodies get_answer inlines in `symbol_bodies`.-# The hydrator already reads these bodies live for synthesis; surfacing them-# in the response collapses the get_answer -> get_symbol drill-down on-# "how does X work" / "explain method Y" questions (the agent gets X's body in-# the same call). Bounded so the body block can't dominate the cached prefix.+# Question-named symbol bodies inlined in `symbol_bodies`, which saves the+# get_symbol follow-up. Bounded so the body block can't dominate the cached prefix._INLINE_BODY_MAX_SYMBOLS = 2-# Line cap for an inlined symbol_bodies block. Larger than the synthesis-# excerpt (_MATCHED_SYMBOL_SOURCE_LINES) because this body is for the agent,-# not the LLM prompt: a docstring-heavy definition (e.g. get_symbol) burns the-# 40-line synthesis cap on docstring and truncates the actual logic, forcing-# the get_symbol follow-up the field exists to remove. 120 serves the whole-# body of ~99% of symbols in one shot; the rest carry a continuation token.+# Line cap for an inlined body. Larger than the synthesis excerpt because a+# docstring-heavy definition would otherwise truncate before its logic; bodies+# past the cap carry a continuation token._INLINE_BODY_MAX_LINES = 120-# `candidates[].defines` — what each ranked file actually contains.-#-# `candidates` names up to 20 files and, until now, carried nothing about any of-# them beyond an optional line span. Measured on the 25 flow questions, 434 of-# the 499 paths a get_answer response served carried no content at all, and the-# Layer B taxonomy judged 89% of the agent's post-answer searches as EXPAND: it-# took a name we served and went to fetch the substance we did not attach. A-# file named without its definitions is a Grep the agent has to run.-#-# This is bounded hard rather than generously, because the same measurements say-# our payload is ALREADY the larger context (13,958 chars against a bare agent's-# 12,735) and scores lower. The goal is substance per served path, not more-# chars: names and line numbers, no signatures, no docstrings, no bodies.-#-# `_DEFINES_CHAR_BUDGET` is the ceiling for the whole block in one response and-# is spent in retrieval-rank order, so the best-ranked file is the one that-# always gets described. `_DEFINES_PER_CANDIDATE` stops a 200-symbol module from-# consuming the budget before the second candidate is reached.+# `candidates[].defines`: the definitions each ranked file contains, so a named+# file is not a Grep the agent has to run. Names and line numbers only; the goal+# is substance per served path, not more chars. The budget is spent in rank+# order so the best file is always described, and the per-candidate cap stops a+# large module from consuming it before the second candidate._DEFINES_PER_CANDIDATE = 6_DEFINES_CHAR_BUDGET = 1500-# Files whose symbols get looked up at all. Matches _CANDIDATE_LIMIT: querying-# beyond what `candidates` can emit is wasted work.+# Matches _CANDIDATE_LIMIT: querying beyond what `candidates` can emit is wasted._DEFINES_MAX_FILES = 20-# Synthesis-body depth for the top question-relevant symbols. The default-# _MATCHED_SYMBOL_SOURCE_LINES (40) excerpt cuts a docstring-heavy definition-# off before its answer-bearing logic reaches the LLM, so synthesis hedges-# ("not in the excerpts") on the very symbol whose full 120-line body the-# response then inlines in symbol_bodies — the excerpt the LLM saw and the body-# the agent gets were different depths. Read the top few matched symbols at the-# inline-body depth so what synthesis reasons over matches what the response-# serves. Bounded so a class-name flood (every sibling method "matches" through-# the parent's qualified name) can't balloon the synthesis prompt; the rest keep-# the cheap 40-line excerpt.+# The top few matched symbols are read at the inline-body depth so synthesis+# reasons over the same body the response serves, instead of hedging on a+# 40-line cut. Bounded so a class-name flood can't balloon the prompt._SYNTH_FULL_SOURCE_LINES = _INLINE_BODY_MAX_LINES_SYNTH_FULL_BODY_MAX_SYMBOLS = 2-# Answer-by-union (homonym exact-name lookup). When a question names a symbol-# with N>=2 defs that no qualifier disambiguates (`_severity_for` x 4), get_answer-# inlines the UNION of their bodies instead of a best_guesses pointer list — the-# pointer list is exactly what triggers the agent's get_symbol/get_context drill.-# Bodies render greedily under this char budget (mirrors the get_context budget-# philosophy); defs that don't fit are listed file:line with a "call get_symbol,-# do NOT Read" redirect. First def always renders even if it alone exceeds budget.+# Answer-by-union: when a question names a symbol with N>=2 undisambiguated defs,+# inline the union of their bodies rather than a pointer list that triggers a+# drill-down. Bodies render greedily under this budget; the rest are listed+# file:line. The first def always renders even if it alone exceeds the budget._HOMONYM_UNION_CHAR_BUDGET = 12000-# Line cap per union body — same rationale as _INLINE_BODY_MAX_LINES._HOMONYM_UNION_BODY_MAX_LINES = 120-# Ceiling on how many same-named defs a *prose* question may answer-by-union.-# The union is for a small set of genuine parallel implementations of one concept-# (``_severity_for`` has 4 across the biomarkers); past a handful, the name is a-# generic method implemented on many unrelated classes (``to_dict`` x33,-# ``from_dict`` x26, ``provider_name`` x12), and inlining every body as a-# confidence=high answer buries the actual question. So a prose question that-# merely *mentions* such a name (measured: "how does a wiki page get its-# provider_name during indexing?" dumped 12 unrelated provider stubs) falls-# through to synthesis, which grounds in the file the question is really about.-# An explicit symbol lookup (a bare name, where prose does not dominate) still-# unions at any count — that caller asked for every definition. The gap between a-# genuine union (<=4 seen) and a generic method (>=12 seen) is wide, so this is-# not tuned to an exact count.+# Ceiling on defs a *prose* question may union. A few defs are parallel+# implementations of one concept; many are a generic method on unrelated classes+# (`to_dict`), and unioning them buries the question, so prose falls through to+# synthesis. A bare-name lookup still unions at any count. The gap between the two+# cases is wide, so this is not tuned to an exact count._HOMONYM_UNION_PROSE_DEF_CEILING = 6-# Data-shape grounding. "what fields does each entry in <blob> contain" is-# answered directly by mining the field set from source instead of gating to a-# best_guesses pointer list (the pointer list is exactly what triggers the-# agent's Read/get_symbol drill). Two grounding sources, precision-ordered:-# * a documented {...} shape in a docstring/comment near the identifier-# (authoritative -> confidence high);-# * consistent key accesses (VAR.get("f") / VAR["f"]) on the value bound from-# the identifier (access-mined -> confidence medium).-# Every reported field is a quoted token lifted verbatim from source, so the-# path cannot synthesise a field with no source backing (no confidently-wrong-# shapes). Returns nothing (falls through to normal retrieval) unless a shape-# is genuinely grounded.-# Cap on files scanned for the shape. A specific blob name can be referenced-# across dozens of files (every consumer), and the one file that *documents* the-# shape need not sort first, so the cap is generous - source files are small and-# the doc scan must not miss the documenting file. Non-test files are scanned-# first (fixtures document nothing), so the cap mostly trims trailing tests.+# Data-shape grounding: "what fields does each entry in <blob> contain" is+# answered by mining the field set from source, precision-ordered:+# * a documented {...} shape near the identifier (confidence high);+# * consistent VAR.get("f") / VAR["f"] accesses on the bound value (medium).+# Every field is a token lifted verbatim from source, so no shape is invented;+# nothing is returned unless a shape is genuinely grounded.+# The file cap is generous because the documenting file need not sort first;+# non-test files are scanned first, so the cap mostly trims trailing tests._DATA_SHAPE_MAX_FILES = 30 # cap the identifier grep fan-out_DATA_SHAPE_DOC_WINDOW = 6 # lines below an identifier mention to scan for a {...}_DATA_SHAPE_ACCESS_WINDOW = 40 # lines below a binding to mine VAR key accesses@@ -155,71 +92,42 @@ _DATA_SHAPE_MIN_FIELDS = 2 # never answer from a single-field shape (too weak t_DATA_SHAPE_MIN_IDENT_LEN = 6 # identifier must be specific, not a bare generic name_DATA_SHAPE_GREP_TIMEOUT_S = 6.0-# Sort priority by symbol kind. Classes first because "what does X do" /-# "which class inherits from Y" questions resolve at the class level. Then-# top-level functions, then methods (which usually only matter once the-# class context is established).+# Classes first: "what does X do" / "which class inherits Y" resolve at class level._KIND_PRIORITY = {"class": 0, "interface": 0, "function": 1, "method": 2}-# Per-symbol docstring truncation. Keeps the context block bounded — the-# first sentence is typically sufficient and trailing prose mostly contributes-# cache-write cost on follow-up turns.+# The first sentence is usually enough; trailing prose is cache-write cost._MAX_SYMBOL_DOC_CHARS = 120-# The lower tier of the dominance test: how far the top hit must outscore the-# runner-up, as a multiple, when neither score is strong enough for the absolute-# gap below. Generic, repo-agnostic, no question parsing. The failure modes it-# addresses are (a) wrong-target retrieval where top-1 and top-2 are both-# plausible and (b) synthesis hallucination on tangential top hits.-#-# It no longer decides WHETHER to synthesise — under the always-synthesize-# default that gate is gone, and dominance feeds the confidence grade, the-# retrieval rating and the ambiguity caveat instead.+# Dominance, lower tier: how far the top hit must outscore the runner-up, as a+# multiple, when neither score is strong enough for the absolute gap below.+# Dominance feeds the confidence grade, retrieval rating and ambiguity caveat;+# it no longer decides whether to synthesise._DOMINANCE_RATIO = 1.2_COVERAGE_THRESHOLD = 0.66-# The second tier of the dominance test. Where both scores are excellent a close-# ratio is expected — 6.0 vs 5.4 is a clear win that reads as 1.11x — so above-# the score floor below, dominance is measured as an absolute gap instead. Held-# here beside the ratio because ``is_dominant`` is the sole reader of all three;-# they were inline in the answer module while a second, ratio-only copy of the-# test lived in the grade, and the two disagreed in exactly this window.+# Dominance, upper tier: between two excellent scores a close ratio is expected+# (6.0 vs 5.4 is a clear win), so above the floor dominance is an absolute gap.+# ``is_dominant`` is the sole reader of all three knobs._DOMINANCE_ABS_SCORE_FLOOR = 3.0_DOMINANCE_ABS_GAP = 0.5-# Agreement-aware dominance. The dominance ratio above is computed on-# RRF-fused scores, and RRF *compresses*: a page both retrievers rank #1-# (2/60) barely outscores one they rank #2 (2/61) — ratio ~1.017, far below-# _DOMINANCE_RATIO — so the numeric gate calls the *most* confident retrieval-# (both retrievers agree on the top page) "non-dominant". These knobs let the-# grade read the per-source ranks directly: when FTS and vector independently-# put the SAME page at (or within one rank of) the top and the runner-up is-# meaningfully weaker, that consensus is treated as dominance the ratio can't-# see. Conservative by design — agreement only LIFTS a retrieval to high; the-# six demotion gates still pull it back if the synthesised text is ungrounded.-# The top hit must rank no lower than this in EACH retriever (0-indexed, so-# 1 == "#1 or #2 in both").+# Agreement-aware dominance. RRF compresses scores, so a page both retrievers+# rank #1 barely outscores one they rank #2 and the ratio calls the most+# confident retrieval "non-dominant". When the retrievers independently put the+# same page at (or near) the top and the runner-up is weaker, that consensus+# counts as dominance. Agreement only lifts; the demotion gates still apply.+# Max 0-indexed rank of the top hit in EACH retriever (1 == "#1 or #2 in both")._AGREEMENT_TOP_RANK_MAX = 1-# The same ceiling for the FTS+symbol pair a keyless index has to use instead:-# no vector leg runs there, so it can never produce a rank, and a fixed-# FTS+vector pair would make agreement permanently unreachable for those users.-# Stricter than the vector pair on purpose — an exact rank-0 tie in both, not-# "#1 or #2". FTS and the symbol leg read overlapping text (the indexed wiki-# page carries the public symbol table the symbol leg matches on), so the two-# agreeing is nearer to one lexical match counted twice than to two independent-# retrievers concurring. `_SYMBOL_LEG_RRF_K` (180 vs `_RRF_K` 60) already prices-# that leg at a third of the others' in ranking, after a same-named React-# component displaced the right file on the 99-question eval; this stops the-# confidence gate from handing the same signal a full vote.+# The same ceiling for the FTS+symbol pair a keyless index uses (it has no+# vector leg). Stricter on purpose: FTS and the symbol leg read overlapping text,+# so their agreement is nearer one lexical match counted twice than two+# independent retrievers, and the symbol leg is already priced at a third weight._SYMBOL_AGREEMENT_TOP_RANK_MAX = 0-# The runner-up must trail the top by at least this many ranks in at least one-# source (when it was found by both). 1 == "top is strictly ahead somewhere".+# The runner-up must trail by at least this many ranks in at least one source._AGREEMENT_RANK_GAP = 1-# Hedge-phrase markers that indicate the LLM refused to synthesize even though-# retrieval was dominant. When the answer contains any of these, we downgrade-# confidence to "low" and drop the retrieval payload — the hits aren't useful-# to a consumer that has already been told to go read the source, and letting-# them ride through the conversation cache inflates multi-turn cost.+# Phrases that mean the LLM declined to answer despite dominant retrieval.+# A match downgrades confidence to "low" and drops the retrieval payload, since+# a consumer told to read the source gains nothing from it in the cache._HEDGE_MARKERS = ("do not contain","does not contain",@@ -260,35 +168,22 @@ _HEDGE_MARKERS = ("was not found in",)-# The dominance ratio threshold (top_score / second_score >= 1.2x) separates-# reliable retrievals from ambiguous ones. This is a property of BM25-style-# retrieval with a coverage re-ranker on top, not of any particular repository;-# tune if a deployment shows systematic over- or under-gating.--# How many chars of real page content to attach per top hit, for the synthesis-# prompt and for the pointer payload alike. 1500 chars is enough for a page's-# opening section plus a code reference; at 600 the excerpt stopped mid-context-# and agents fell back to native exploration anyway (context-tool bench-# transcripts, 2026-07-17).+# Page content chars attached per top hit, for synthesis and the pointer payload.+# Enough for a page's opening section plus a code reference; much less stops+# mid-context and agents fall back to native exploration._GATED_EXCERPT_CHARS = 1500# How many hits the low-confidence payload hands back to the agent._GATED_RETURN_HITS = 3-# How many top hits get their page content attached. Retrieval is capped at 5-# and all 5 reach the synthesis prompt, so this is 5: a hit the model is asked-# to read with no prose behind it is one it can only answer from symbol names.-# This is the cost knob for the feature — 5 hits × 1500 chars is roughly 2k-# prompt tokens on top of the symbol block, measured at +24% of the tool's own-# synthesis spend. Lower it to spend less; hits below the cut fall back to-# their one-line summaries.+# Top hits that get page content attached. All 5 retrieved hits reach synthesis,+# and a hit with no prose can only be answered from symbol names. This is the+# feature's cost knob; hits below the cut fall back to one-line summaries._PAGE_EXCERPT_HITS = 5-# Path-prefix domain heuristics — down-weight cross-domain retrievals so a-# clearly backend question doesn't anchor on a same-vocabulary UI file (and-# vice versa). The penalty is multiplicative, not absolute, so a strongly-# matching cross-domain file can still survive on raw signal; the goal is-# to break ties when retrieval is otherwise ambiguous, not to censor results.+# Path-prefix domain heuristics: down-weight cross-domain hits so a backend+# question doesn't anchor on a same-vocabulary UI file (and vice versa). The+# penalty is multiplicative, to break ties rather than censor strong matches._UI_PATH_PREFIXES = ("packages/ui/","packages/web/",@@ -302,9 +197,8 @@ _BACKEND_PATH_PREFIXES = ("backend/","modal_app/",)-# Tokens that flag a question as being about a specific domain. Kept small-# and conservative — ambiguous questions (both lists hit, or neither) fall-# through to no penalty rather than misclassify.+# Question tokens that flag a domain. Kept small; an ambiguous question (both+# lists hit, or neither) gets no penalty rather than a misclassification._UI_QUESTION_TOKENS = frozenset({"ui",@@ -351,127 +245,31 @@ _BACKEND_QUESTION_TOKENS = frozenset("sql",})-# Penalty factor applied to cross-domain hits. 0.5 is strong enough to-# overtake a same-domain near-tie but small enough that a dominant cross--# domain hit (real top score outlier) still survives.+# Strong enough to overtake a same-domain near-tie, weak enough that a dominant+# cross-domain hit survives._DOMAIN_PENALTY = 0.5-# Floor on raw top-hit score for "high" confidence. Below this the answer-# may be technically dominant but built on weak retrieval — downgrade to-# "medium" so the agent verifies. Tuned against observed BM25 ranges on-# the wiki corpus where useful hits routinely score >1.5.+# Floor on the top-hit score for "high": below it a dominant answer rests on+# weak retrieval, so it grades "medium". Useful wiki hits routinely score >1.5._HIGH_CONFIDENCE_SCORE_FLOOR = 1.5-# Schema version stamped on every cached payload. Bump whenever the response-# shape changes in a way that would mislead a consumer reading an old cached-# entry (new top-level fields, semantics of existing fields). On cache reads-# we treat any payload at a lower version as a miss and re-synthesise — the-# alternative (returning stale-shape payloads) silently bypasses every-# improvement to the tool and was the failure mode that hid the entire-# get_answer rework behind a cache hit during testing.-# v3: retrieval pipeline overhaul (hybrid FTS+vector, PageRank bias, graph-# expansion, structured prelude, decision fusion). Cached v2 payloads were-# synthesised over weaker retrieval — bumping forces re-synthesis so the-# upgrade actually reaches callers without waiting for cache expiry.-# v4: confidence calibration gates (value-grounding, citation-source,-# expanded hedge markers). Cached v3 confidence values predate the gates-# 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.-# 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.-# v8: always-synthesize — retrievals that used to abstain (no dominant page) now-# carry synthesized prose + best_guesses/code_rationale evidence at medium/low-# instead of an empty pointer list. Cached v8 gated (empty-answer) rows must-# bypass so the new answered-with-evidence contract reaches callers.-# v9: agreement-aware confidence — the top hit is graded "dominant/high" when-# both retrievers independently rank it at/near the top, not only when its-# RRF-fused score numerically dominates. RRF compresses scores, so retriever-# agreement (the most confident case) previously graded medium/low. Cached-# pre-v9 rows carry the compressed-ratio grade and must bypass.-# v10: (reserved for the agreement rollout above.)-# v11: answer-grounding calibration — (1) a mechanism/"how" question that merely-# names an indexed symbol no longer short-circuits to an exact_symbol body dump;-# (2) the claim-support gate now covers how-questions, not only why; (3) strong-# answer-grounding earns high on a non-dominant retrieval. Cached pre-v11 rows-# carry the old body-dump / dominance-only grade and must bypass so the-# recalibrated confidence reaches callers.-# v12: `candidates[].defines` — each ranked file now names the definitions it-# contains. Cached pre-v12 rows carry the bare {path, lines} shape, which is the-# named-but-not-carried payload this version exists to replace, so they must-# bypass rather than serve the old block back.-# v13: withheld-body calibration — a truncated symbol_bodies entry now carries-# `withheld_symbols`, confidence is capped when the response depends on one of-# them (and on the homonym-union path whenever any cited body was truncated),-# and the high/union notes no longer tell the caller to skip re-reading a-# payload that admits it withheld part of a cited body. Cached pre-v13 rows-# carry both the old `high` and the old "do not re-read the source" note, which-# is precisely what this version exists to stop serving, so they must bypass.-# v14: the LOOKUP half of v13. v13 capped the homonym-union path on truncation-# alone, but a name with exactly ONE definition never reaches that path, so a-# bare-symbol-name question about a uniquely-defined symbol still graded `high`-# with most of the cited body withheld (measured: 93% and 78% withheld, on two-# trees and two languages). It is now capped the same way. Separately, a-# withheld entry naming the very symbol the payload already served is described-# by its `continuation` range instead of being reported as "not served" with a-# get_symbol pointer to a body the caller already holds most of. Cached pre-v14-# rows carry both the old `high` and the old note, so they must bypass.-# v15: the scanner behind `withheld_symbols` stops reading backtick strings as-# code. Go raw strings and TS template literals were never masked, so the-# GraphQL and interpolated text inside them was emitted as symbols — 282 of-# 22,898 sweep entries on cli/cli, 19 of them the HEADLINE entry the note tells-# the agent to fetch. Those ids are not dead (`get_symbol` answers them with a-# live grep, since the name really is on that line) but they are misleading:-# the "symbol" is a GraphQL field. A cached pre-v15 row still lists them, so it-# must bypass. Secondarily, the note no longer advertises a symbol_id that-# resolves to nothing at all — a guard rather than an observed fix, since 0 of-# the 130 ids on the corpus were dead ends.-# NOT bumped for the degraded-payload rework (`symbol_bodies` / `citations` /-# `grounding` / `next_action_hint` / `retrieval_quality` on the no-provider and-# synthesis-failed paths). Every one of those is a response-shape change, which-# is normally exactly what this counter is for, but no cached row can carry the-# old shape: the cache write is gated on `answer_text` and sits below both-# degraded returns, so a degraded payload has never been written to it. The-# synthesised shape is untouched. A bump here would invalidate every keyed-# install's cache, and re-synthesis is real provider spend, for nothing.-# v16: the same scanner again, in three places, and unlike the degraded rework-# above every one of them changes the SYNTHESISED payload, which is the shape-# that gets cached. (1) A run left open at end of file no longer masks to EOF,-# so definitions below a phantom `"""` or `/*` are listed again — 26 real Rust-# definitions across two corpus files, one of which had 3,002 lines masked.-# (2) A cut inside a multi-line string keeps the symbol enclosing it, which-# changes which entry is the HEADLINE `body_continues`, and therefore the note-# and the get_symbol pointer. (3) An unverified symbol bound is clamped to the-# live file, so a body served whole is no longer flagged `truncated` — and-# v13/v14 cap confidence on that flag, so a cached row can carry a `medium`-# this version would not produce. Cached pre-v16 rows carry all three, so they-# must bypass.-# v17: `confidence` itself moves. Dominance now has one owner, so a retrieval-# with a strong absolute gap but a compressed ratio grades high where a cached-# v16 row holds medium; and answer-grounding no longer earns high over a weak-# retrieval, so the reverse case is cached too. The note is rewritten from the-# reason the grade was reached rather than from the bare fact that it is high,-# so v16 rows carry a note this version would not produce.+# Schema version stamped on every cached payload. Bump whenever the synthesised+# response shape or the meaning of a field (including `confidence` and `note`)+# changes: a cached row at a lower version is a miss and re-synthesises, since+# serving an old-shape row silently hides the change behind a cache hit.+# Degraded (no-provider / synthesis-failed) payloads are never cached, so changes+# confined to them need no bump; a needless bump costs every keyed install a+# round of provider spend._ANSWER_SCHEMA_VERSION = 17-# Hard TTL on answer-cache rows. Commit-based invalidation (the payload's-# stamped ``_indexed_commit`` vs the repo's current head) is the primary-# freshness gate, but rows written before commit stamping existed — or for-# repos without git metadata — need a backstop so they can't serve forever.+# Backstop TTL for cache rows. Commit stamping is the primary freshness gate;+# this covers rows without a stamp (older rows, repos without git metadata)._ANSWER_CACHE_TTL_DAYS = 14-# Intersection-retrieval connectives. If a question contains any of these-# (case-insensitive whole-word), it's likely a relational/multi-entity-# question. We split the question on the connective, run two FTS passes,-# and boost any page that appears in BOTH result sets — the page at the-# intersection is much more likely to be the actual answer than a page-# at the top of either single-side query.-# This is grammar, not domain — the same list applies to any English-language-# code question, independent of the repository or codebase.+# Intersection-retrieval connectives (case-insensitive whole-word). A question+# containing one is split on it, both sides are searched, and pages in BOTH+# result sets are boosted: the intersection is likelier the answer than either+# side's top. Grammar, not domain: it applies to any English code question._RELATIONAL_CONNECTIVES = (" between "," from ",@@ -483,32 +281,20 @@ _RELATIONAL_CONNECTIVES = (" vs ",)-# Term-coverage re-ranker tuning. Multiplies BM25 by (FLOOR + (1-FLOOR)*coverage)-# where coverage = (# distinct query terms present in hit) / (# query terms).-# FLOOR=0.5 → single-concept questions (coverage≈1.0) are unaffected;-# multi-constraint questions where a hit covers 1/3 of terms get scored at 0.67-# of their raw BM25 (vs 1.0 for a hit covering 3/3). Conjunctive coverage-# becomes a tie-breaker rather than a hard filter.+# Term-coverage re-ranker: BM25 * (FLOOR + (1-FLOOR)*coverage), where coverage is+# the share of distinct query terms present in the hit. Single-concept questions+# are unaffected; on multi-constraint ones coverage is a tie-breaker, not a filter._COVERAGE_FLOOR = 0.5-# English stopwords. Defined in ``_query_terms`` (stdlib-only, imported by-# nothing in this package) so the coverage re-ranker here and the prose-keyed-# symbol leg in ``_prose_symbols`` share one list instead of drifting apart.+# Shared with the prose-keyed symbol leg so the two lists cannot drift apart._STOPWORDS = STOPWORDS-# Cap on bytes read from source per symbol when we recover a real signature-# from disk (multi-line def with type annotations). Anything longer than this-# gets truncated; the agent can call get_symbol for the full body.+# Line cap on a real signature recovered from disk; get_symbol has the rest._MAX_RICH_SIG_LINES = 4-# Synthesis sampling. Answers target 150-400 words (~550 tokens), so the cap is-# headroom rather than the binding constraint; generation speed is. Temperature-# is low because the answer must track the retrieved excerpts, not embellish.-#-# That headroom reasoning holds only for a non-reasoning model. A reasoning-# model spends the same budget on hidden thinking *before* emitting any answer-# token, so 1024 is not headroom for it — it is the entire allowance, and the-# call comes back empty with a ``length`` finish_reason (see-# ``synthesis._empty_completion_note``). REPOWISE_SYNTHESIS_MAX_TOKENS exists-# so such a model can be given room, instead of being swapped for a weaker one.+# Synthesis sampling. Answers target 150-400 words, so for a non-reasoning model+# the token cap is headroom. A reasoning model spends the budget on hidden+# thinking first and can come back empty with a ``length`` finish_reason, so the+# env override lets such a model be given room. Low temperature: the answer+# must track the excerpts, not embellish._SYNTHESIS_MAX_TOKENS_ENV = "REPOWISE_SYNTHESIS_MAX_TOKENS"_SYNTHESIS_MAX_TOKENS_DEFAULT = 1024@@ -517,8 +303,7 @@ def _synthesis_max_tokens() -> int:"""The synthesis token budget, from env or the hosted-model default.An unparseable or non-positive value warns and keeps the default instead- of silently capping synthesis at 0 — matching how REPOWISE_EMBEDDING_TIMEOUT- and REPOWISE_VECTOR_SEARCH_TIMEOUT_S are resolved.+ of silently capping synthesis at 0."""raw = os.environ.get(_SYNTHESIS_MAX_TOKENS_ENV, "").strip()if not raw:@@ -577,63 +362,41 @@ of sites; qualify causal claims when a symbol's body was truncated.# --- Feature flags ------------------------------------------------------------# Every REPOWISE_ANSWER_* switch, read at call time so a test or an eval arm can-# flip one between calls. Each is independently reversible on purpose: they were-# added one at a time and an A/B must be able to switch one without the others.--# Always-synthesize. Default ON: synthesis runs for every retrieval and the-# post-synthesis grading cascade demotes confidence instead of the tool-# abstaining, so coverage matches a research assistant that answers every-# question. Falsey restores the legacy abstain-on-ambiguous behaviour.+# Every REPOWISE_ANSWER_* switch, read at call time so a test or eval arm can+# flip one between calls. Each is independently reversible so an A/B can switch+# one without the others.++# Default ON: synthesis runs for every retrieval and grading demotes confidence+# instead of abstaining. Falsey restores abstain-on-ambiguous._ALWAYS_SYNTHESIZE_ENV = "REPOWISE_ANSWER_ALWAYS_SYNTHESIZE"-# Retriever-agreement confidence lift (the measured FTS + vector pair).+# Retriever-agreement confidence lift (the FTS + vector pair)._AGREEMENT_CONFIDENCE_ENV = "REPOWISE_ANSWER_AGREEMENT_CONFIDENCE"-# The keyless-only half of that signal (FTS + symbol in place of FTS + vector,-# which a keyless index can never produce). Its own flag on purpose: it-# substitutes a leg the fusion already prices at a third weight, so it must be-# reversible WITHOUT also switching off the measured half.+# The keyless FTS + symbol pair. Its own flag so it can be reversed without+# switching off the FTS + vector half._SYMBOL_AGREEMENT_ENV = "REPOWISE_ANSWER_SYMBOL_AGREEMENT"# Keep the exact_symbol union fast path from hijacking a "how does X work"-# mechanism question, whose real answer often lives in a different file than the-# named symbol's body.+# question, whose answer often lives outside the named symbol's body._UNION_MECHANISM_DEFER_ENV = "REPOWISE_ANSWER_UNION_MECHANISM_DEFER"-# Require the answer's central named mechanism symbol to be grounded in served-# source before a mechanism/how answer may be stamped high.+# Require the answer's central mechanism symbol to be grounded in served source+# before a mechanism/how answer may be stamped high._CLAIM_SUPPORT_GATE_ENV = "REPOWISE_ANSWER_CLAIM_SUPPORT_GATE"-# Let a response earn "high" on a non-dominant retrieval — the served body of-# the symbol the question named — rather than only a clear dominance margin.+# Let the served body of the question-named symbol earn "high" on a+# non-dominant retrieval._EARN_HIGH_GROUNDING_ENV = "REPOWISE_ANSWER_EARN_HIGH_GROUNDING"-# The other half of that lift, and OFF by default: earning high from the prose-# being consistent with the material it was shown.-#-# It is only ever reachable over a weak retrieval. Earning high requires the top-# score to clear the confidence floor, and a retrieval that clears the floor and-# dominates is already high without earning anything — so the lift fires exactly-# when ``retrieval_quality`` reads "weak", which is the pipeline reporting that-# it may have surfaced the wrong material. Frame-term grounding cannot answer-# that: it checks that the answer named nothing retrieval did not show it, which-# is evidence against fabrication and says nothing about whether the material-# was the right material. The served-body lift above CAN answer it — that body-# is exact-name resolution rather than ranking, and the source is in the payload-# — which is why the two are split rather than capped together.-#-# On for the previous behaviour, where grounded prose over a tied top pair-# returned high with "do not re-read the source unless a specific detail is-# missing".+# Off by default: earning high from prose consistent with the material shown.+# This lift only fires over a weak retrieval (a strong dominant one is already+# high), and frame-term grounding shows the answer invented nothing, not that+# the material was the right material. The served-body lift above can show+# that (exact-name resolution, not ranking), which is why the two are split._EARN_HIGH_ON_WEAK_RETRIEVAL_ENV = "REPOWISE_ANSWER_EARN_HIGH_ON_WEAK_RETRIEVAL"-# Test/eval hook: skip the answer cache entirely (both read and write). The-# cache keys on (repo, question) only — not on feature-flag state — so an A/B-# eval that flips the flags above between arms would otherwise read the first-# arm's cached answers. Off by default.+# Skip the answer cache (read and write). The cache keys on (repo, question), not+# flag state, so an A/B flipping the flags above would read the first arm's rows._DISABLE_CACHE_ENV = "REPOWISE_ANSWER_DISABLE_CACHE"-# Opt-in: strip re-read evidence from high-confidence answers. A high answer's-# contract is "cite this, do not re-read the source", so the bodies, quotes,-# flow_path and candidate evidence are payload the consumer was told it does not-# need. Off by default; only safe once high-confidence answers are reliable-# enough that the prose + citation suffices, else the agent calls get_symbol and-# adds a round-trip.+# Opt-in: strip re-read evidence from high-confidence answers, whose contract is+# "cite this, do not re-read". Only safe once high answers are reliable enough;+# otherwise the agent calls get_symbol and adds a round-trip._LEAN_HIGH_ENV = "REPOWISE_ANSWER_LEAN_HIGH"# Re-read evidence stripped from a lean high answer. NOT stripped: answer,@@ -657,20 +420,14 @@ def _always_synthesize() -> bool:def _agreement_confidence_enabled() -> bool:- """Whether retriever-agreement lifts confidence (default) or pure ratio rules.-- Falsey restores the exact prior RRF-compressed ratio/gap behaviour, for A/B- measurement and instant reversibility.- """+ """Whether retriever-agreement lifts confidence (default) or pure ratio rules."""return _flag_on(_AGREEMENT_CONFIDENCE_ENV)def _symbol_agreement_enabled() -> bool:"""Whether a keyless index may read agreement from FTS + the symbol leg.- Independently reversible from :func:`_agreement_confidence_enabled`, which- governs the measured FTS + vector pair. Off restores the state where a- keyless index simply cannot earn the agreement lift.+ Independently reversible from :func:`_agreement_confidence_enabled`."""return _flag_on(_SYMBOL_AGREEMENT_ENV)diff --git a/packages/server/src/repowise/server/mcp_server/tool_answer/data_shape.py b/packages/server/src/repowise/server/mcp_server/tool_answer/data_shape.pyindex 172cd640c..c39627192 100644--- a/packages/server/src/repowise/server/mcp_server/tool_answer/data_shape.py+++ b/packages/server/src/repowise/server/mcp_server/tool_answer/data_shape.py@@ -1,19 +1,9 @@"""Ground data-shape questions ("what fields does each entry in X contain?").-A data-shape question names a data blob / row / record and asks for its field-set. Fuzzy retrieval scatters across every file that *touches* the blob and-gates low, so the tool hands back a best_guesses pointer list and the agent-drills with Read/get_symbol to find the fields itself. But the answer usually-lives verbatim in source: a documented ``{...}`` shape in a docstring near the-identifier, and/or the concrete keys consumers pull off the parsed value-(``partner.get("co_change_count")``). This module mines that field set directly-so the tool answers in one call.--Precision-first: every reported field is a quoted token lifted from source, so a-field with no source backing can never be synthesised. Two grounding sources,-precision-ordered: a documented brace shape (authoritative -> high) beats mined-key accesses (usage-inferred -> medium). Returns ``None`` (the caller falls-through to normal retrieval) unless a shape is genuinely grounded.+Fuzzy retrieval scatters across every file that touches a blob, but the field+set usually lives verbatim in source: a documented ``{...}`` shape (high) or the+keys consumers read off the value (medium). Every field is a quoted token lifted+from source; ``None`` means nothing was grounded and retrieval runs as normal."""from __future__ import annotations@@ -66,29 +56,21 @@ _CONTAINMENT_VERBS = ("contain", "consist", "comprise", "hold", "look like", "ma_WORD = re.compile(r"[a-z_]+")-# A body this long is not a question, it is a report that may contain one. The-# bound is deliberately generous: the longest genuine one-line data-shape-# question anyone writes is well under it, and the bug reports this exists to-# exclude run to a median of about 1200 characters.+# Longer than this with no `?` is a pasted report, not a question. Generous:+# genuine one-line shape questions are well under it._BARE_QUESTION_MAX_CHARS = 400-# Sentence-ish split. Only `?` actually matters below; `.`/`!`/newline are here-# so a question sentence is bounded by the prose around it rather than swallowing-# it. Fenced code and tracebacks are full of `.` and newlines, which is fine:-# splitting them finer only makes it harder for a stray cue to land in a clause-# that also ends in `?`.+# Only `?` matters below; the other splits bound a question sentence so it+# cannot swallow the prose around it._SENTENCE_SPLIT = re.compile(r"(?<=[.?!])\s+|\n+")def _interrogative_clauses(question: str) -> list[str]:"""The parts of ``question`` that are actually asking something.- A sentence ending in `?` is a question. If the whole input is short and asks- nothing explicitly, the input *is* the question — "what keys are in the- blame_record blob" and "describe the schema of GitCommitMeta" are how people- type, and demanding punctuation of them would break the short-question case- this fast path exists for. Anything longer with no `?` in it is a report, and- reports get no clauses.+ A sentence ending in `?` is a question. A short input with no `?` is itself+ the question (people rarely punctuate); a longer one is a report and gets+ no clauses."""clauses = [s.strip() for s in _SENTENCE_SPLIT.split(question) if s.strip().endswith("?")]if clauses:@@ -107,16 +89,9 @@ def _is_data_shape_question(question: str, question_ids: set[str]) -> bool:(entry/record/element/...) paired with a containment verb. Mechanismquestions ("how does X work") carry neither and fall through.- The cue itself is still cheap, and the miner is still the real precision- gate. What the clause restriction adds is a precondition on *where* the cue- may sit. "A false-positive cue is safe" holds for a question someone typed- and fails for a body someone pasted: across a bug-report corpus a shape noun- like `field` or `key` appears incidentally in nearly every ticket, the- identifier extractor always finds something to ground on, and the miner then- answers a question nobody asked — returning a field list to a caller who- pasted a stack trace, before retrieval has run at all. Requiring the cue to- sit in the question's own interrogative clause keeps the short-question case- intact and stops an arbitrarily long body from being mined by accident.+ The clause restriction matters for pasted bodies: shape nouns like `field`+ appear incidentally in most bug reports, and without it the miner would+ answer a question nobody asked before retrieval runs."""if not question or not question_ids:return False@@ -231,17 +206,10 @@ def _run_grep(def _grep_identifier_files(repo_root: Path, identifier: str, spec: object = None) -> list[str]:"""Source files naming ``identifier`` (whole word), repo-relative.- Tracked ``git grep`` first (fast, skips ignored/vendored). If the tree isn't- a git checkout (returncode 128), retry with ``--no-index`` so the tool still- grounds its answer on a non-git tree - both are fast C greps, never the- per-file Python read that wedges on a large tree. Returns the full match set;- the caller orders (doc files first) then caps, so the documenting file is- never dropped by an unlucky order.-- ``--no-index`` scans the raw filesystem and ignores ``.gitignore``, so a- gitignored stale wheel / vendored copy can surface as a match. The compiled- ``spec`` (gitignore + ``exclude_patterns``) filters those out authoritatively,- matching every other MCP read path.+ Tracked ``git grep`` first; on a non-git tree (returncode 128) retry with+ ``--no-index``, which ignores ``.gitignore``, so ``spec`` filters the hits+ like every other MCP read path. Returns the full match set; the caller+ orders then caps, so the documenting file is never dropped."""proc = _run_grep(repo_root, [], identifier)if proc is not None and proc.returncode == 128:@@ -344,14 +312,10 @@ def _alias_keys_on_documented_lines() -> list[tuple[str, int]]:"""Alias keys a documented field is read as a fallback for.- Targets one idiom precisely: ``<recv>.get("<A>") or <recv>.get("<B>")`` - the- same receiver reads two keys joined by ``or``, so when one is a documented- field the other is an alias for it (``partner.get("co_change_count") or- partner.get("count")`` -> ``count``; ``... or partner.get("path")`` ->- ``path``). Requiring the ``or`` fallback and a shared receiver keeps this tight:- an assignment that merely co-mentions a documented key on a different record- (``meta["prior_defect_count"] = ...meta["file_path"]``) or a test assertion- does not match. Returns ``(alias, line)`` for keys not in ``doc_fields``.+ Targets one idiom: ``<recv>.get("<A>") or <recv>.get("<B>")`` where one key+ is documented, so the other is its alias. The ``or`` and the shared receiver+ keep incidental co-mentions out. Returns ``(alias, line)`` for keys not in+ ``doc_fields``."""out: list[tuple[str, int]] = []for idx, line in enumerate(lines, 1):@@ -445,9 +409,7 @@ def mine_data_shape(repo_root: Path | None, question_ids: set[str]) -> dict | Noexcept Exception:return None- # Compile the repo's exclusion rules once per query. The grep fallbacks- # (esp. ``git grep --no-index`` on a non-git tree) don't honour .gitignore,- # so filter their hits the same way every other MCP read path does.+ # ``--no-index`` ignores .gitignore, so grep hits are filtered through this.exclude_spec = build_exclude_spec(root)for identifier in _specific_identifiers(question_ids):@@ -507,12 +469,8 @@ def mine_data_shape(repo_root: Path | None, question_ids: set[str]) -> dict | Noif any(src["file"] == s["file"] for s in sources):continuesources.append(src)- # Divergence: keys consumers read right beside a documented field but- # the doc never lists (a legacy alias like ``count`` for- # ``co_change_count``, an optional key). The documented shape is- # authoritative for what it declares, but if we said "cite it, no Read- # needed" while hiding a key four consumers defensively handle, an- # agent could ship a change that ignores it. Surface it instead.+ # Keys consumers read beside a documented field that the doc omits+ # (an alias): "no Read needed" must not hide a key the code handles.doc_field_set = set(fields)also_accessed: list[dict] = []also_seen: set[str] = set()@@ -582,9 +540,6 @@ def _data_shape_prose(grounded: dict, citations: list[str]) -> tuple[str, str]:"data_shape.sources lists every field's origin line.",)- # The doc lists the declared shape, but consumers read alias key(s) it omits- # (a legacy fallback). Surface them: telling the agent "no Read needed" while- # hiding a key it must handle would be a confidently-incomplete answer.alias_list = ", ".join(f"`{a['field']}`" for a in also_accessed)first_alias = also_accessed[0]return (diff --git a/packages/server/src/repowise/server/mcp_server/tool_answer/degraded.py b/packages/server/src/repowise/server/mcp_server/tool_answer/degraded.pyindex f9d153c23..1d3ba68d5 100644--- a/packages/server/src/repowise/server/mcp_server/tool_answer/degraded.py+++ b/packages/server/src/repowise/server/mcp_server/tool_answer/degraded.py@@ -1,12 +1,8 @@"""The synthesis-less get_answer reply.-Both ways synthesis can be missing — no provider resolvable, or the call failed —-return the same payload from the same evidence. Only synthesis is missing here:-retrieval ran, ranked the corpus and succeeded, and everything below the provider-check (bodies, citations, best guesses, mined rationale, the next action) is read-live off disk from index anchors and needs no LLM. The only thing that coupled-that evidence to synthesis was that body selection matched against the answer-text, so here the question's own identifiers stand in.+No provider and a failed call share one payload. Retrieval succeeded and all+evidence (bodies, citations, best guesses, rationale) is read live from disk+with no LLM; body selection matches the question's identifiers, not prose."""from __future__ import annotations@@ -41,19 +37,13 @@ from repowise.server.mcp_server.tool_answer.retrieval import (def _degraded_summary(reason: str, symbol_bodies: list[dict], served: int) -> str:"""The ``answer`` sentence a synthesis-less payload states about itself.- An empty ``answer`` beside a working retrieval reads as a failed call rather- than a partial one, and a reader who takes it at face value discards a usable- result and starts over. So the sentence is assembled from what the payload- actually carries — it can never claim more than it has, and it invents no- prose about the question itself, that being precisely the part that needs a- provider. Three cases, best evidence first: bodies in hand, a ranked- retrieval, or nothing.+ An empty ``answer`` reads as a failed call and gets a usable result+ discarded. Assembled only from what the payload carries, inventing no prose+ about the question. Best evidence first: bodies, a ranked retrieval, nothing."""if symbol_bodies:names = ", ".join(f"`{b['name']}`" for b in symbol_bodies)- # Never say "full" over a body the payload itself flags as cut. The- # entry carries `truncated` and a `continuation` two keys away, so the- # claim is refutable from inside the same response.+ # Never say "full" over a body the payload itself flags as cut.cut = any(b.get("truncated") for b in symbol_bodies)return (f"No synthesized prose ({reason}), but the evidence is here: "@@ -95,16 +85,9 @@ async def _degraded_payload() -> dict:"""Shape a synthesis-less get_answer response.- ``degraded`` is mirrored into ``_meta`` because consumers read freshness and- health signals from there; the failure path used to set only the top-level- key, so a caller watching ``_meta`` saw a normal empty answer.-- ``confidence`` is graded by :func:`_degraded_confidence` from the retrieval- this payload actually served, not pinned. It rates what the caller can act on- without further work, which is the same thing it rates on the keyed path; the- boilerplate ``answer`` is why "high" is unreachable here rather than why the- field says nothing. ``retrieval_quality`` rates the retrieval on its own and- is what the grade is derived from, so the two can never disagree.+ ``degraded`` is mirrored into ``_meta``, where consumers read health+ signals. ``confidence`` is graded by :func:`_degraded_confidence` from+ ``retrieval_quality``, so the two can never disagree."""retrieval_quality = _retrieval_quality(hits, agreement_dominant)confidence = _degraded_confidence(reason, retrieval_quality)@@ -113,10 +96,7 @@ async def _degraded_payload(_gather_body_candidates(hits, "", anchor_names=question_ids or set()),repo_root,)- # Cite what is actually in hand. `[]` was right when the payload carried no- # source; with bodies inlined the paths they were read from are citations in- # the ordinary sense, and a caller filtering on non-empty `citations` stops- # discarding this reply.+ # Inlined bodies are citations in the ordinary sense.citations = list(dict.fromkeys(b["path"] for b in symbol_bodies))summary = _degraded_summary(reason, symbol_bodies, len(hits))@@ -161,11 +141,8 @@ async def _degraded_payload("answer from that rather than re-reading the file.")elif best_guesses and retrieval_quality != "weak":- # No body, so the next step is a choice between files. Not on a weak- # retrieval: `_meta.hint` there says "refine the query rather than- # reading these files in order", and two hints that disagree are worse- # than one. Names `best_guesses`, not its excerpt — that copy is dropped- # on the way out, since this path always has a populated `retrieval`.+ # Not on a weak retrieval, where `_meta.hint` says to refine the query+ # and two disagreeing hints are worse than one.payload["next_action_hint"] = (f"Start from {best_guesses[0]['file']} — it ranked highest, and ""best_guesses says why each candidate is in the running."@@ -190,18 +167,10 @@ async def _degraded_payload(async def _degraded_next_action(symbol_bodies: list[dict], ctx, repository, exclude_spec) -> str:"""The one next step a degraded payload with bodies in hand should name.- A whole body is a terminal answer, so say so rather than sending the caller- to Read a file it already holds. A cut body is not: name the continuation, or- a withheld symbol when one resolves.-- Two filters on the withheld ids, both already established on the synthesised- path. A withheld entry carrying the served body's OWN name is the enclosing- symbol continuing past the cut, not something that never arrived, so it is- dropped and the ``continuation``, which fetches exactly the missing part, is- the pointer. And the ids come from a regex scanner over source lines, so it- can name something that is not a symbol at all: ``_first_resolvable_id``- keeps a fabricated id from becoming the next action here exactly as it does- there.+ A whole body is a terminal answer. A cut body names a withheld symbol that+ resolves, else its ``continuation``. As on the synthesised path, the+ enclosing symbol's own name is not a withheld symbol, and+ ``_first_resolvable_id`` keeps a scanner-invented id out of the hint."""cut = next((b for b in symbol_bodies if b.get("continuation")), None)if cut is None:diff --git a/packages/server/src/repowise/server/mcp_server/tool_answer/episodes.py b/packages/server/src/repowise/server/mcp_server/tool_answer/episodes.pyindex d94489555..3029172c2 100644--- a/packages/server/src/repowise/server/mcp_server/tool_answer/episodes.py+++ b/packages/server/src/repowise/server/mcp_server/tool_answer/episodes.py@@ -1,18 +1,9 @@"""Attach a dated episode that disagrees with a synthesised answer.-``get_answer`` reasons from the code as it is now, and it is confidently wrong-about what was *decided*. The reproduction this module exists for: asked-whether to run the declared formatter before committing, the tool reads a-``format`` target out of the build files and answers yes — while the checkout's-own episode store holds a ``formatter_drift`` record saying the tree is not-formatter-clean and a repo-wide run would produce a large unrelated diff.--**Add, never replace.** The synthesis stays exactly as it was; a matching-episode is appended beside it as a dated, attributed quotation. Replacing the-answer would introduce the failure this exists to prevent, because the episode-is sometimes the stale one and the synthesis the correct one. A reader who sees-"recorded at ``acd24602``" next to "run the formatter" does not run it, and-nothing is lost when the episode has expired.+``get_answer`` reasons from the code as it is now and can be confidently wrong+about what was *decided*. **Add, never replace:** a matching episode is appended+beside the synthesis as a dated quotation, because sometimes the episode is the+stale one.Three preconditions, checked in this order:@@ -20,10 +11,8 @@ Three preconditions, checked in this order:2. the episode is still true,3. the synthesis is below ``confidence: high``.-Any one missing means silence, and silence is byte-identical to today's-payload. This runs at **serve time on both the fresh and the cached path**, so-the episode is read fresh on every call and a disagreement is never frozen into-a cache row — which is also why adding it needs no answer-schema bump.+Any one missing means silence. Runs at serve time on the fresh and cached paths,+so an episode is never frozen into a cache row."""from __future__ import annotations@@ -52,20 +41,13 @@ _MAX_EPISODES = 1#: stays recoverable via ``repowise expand`` rather than vanishing._MAX_BODY_CHARS = 600-#: How many node-scoped candidates are tested for staleness before giving up.-#: Each test may cost one git query, so this is what keeps the sanctioned-#: read-time exception bounded no matter how large the store grows. One-#: repo-wide candidate may follow them (see :func:`_candidate_window`), so the-#: ceiling on git queries per call is this plus one.+#: Node-scoped candidates tested for staleness. Each may cost one git query, so+#: this bounds the read-time git cost; with one possible repo-wide candidate+#: (see :func:`_candidate_window`) the ceiling is this plus one._MAX_SCOPED_CANDIDATES = 4-#: The tiers this guard is willing to put in front of a reader. Shared with-#: every other episode reader (:mod:`repowise.server.mcp_server._episodes`),-#: because "which tiers are shareable" is a property of the store rather than-#: of one tool, and the first version of this constant reached the wrong answer-#: by being local: an unnamed default let the store's second tier arrive-#: uninvited, and with 56 of this repository's 426 sessions recorded the guard-#: went **silent on its own reproduction** and served a session instead.+#: Shared with every episode reader: which tiers are shareable is a property+#: of the store, not of one tool._SERVED_TIERS = SERVED_TIERS#: Room the block needs before it is worth attaching at all.@@ -187,25 +169,11 @@ def _attach(def _candidate_window(scoped: list[tuple[dict, list[str]]]) -> list[tuple[dict, list[str]]]:"""The candidates staleness is tested on: bounded, and never one-sided.- Ranking puts path matches above subject matches, which is right. But a- node-scoped episode is *suppressed outright* when anything has touched its- files since, while a repo-wide one is served with its age labelled. A store- holding hundreds of the former and a handful of the latter would therefore- fill the whole window with candidates that can only fall through, and the- surface would go silent on a repository that had more history rather than- less.-- So the best repo-wide candidate is **appended** when the window would- otherwise hold none. Appended rather than substituted, and the difference- is the whole point: a repo-wide verdict never suppresses, so putting one- in the last slot would not fall back to it, it would pre-empt the- node-scoped candidate standing there — trading a git-verified "nothing in- its scope has changed" for an unchecked claim about the whole tree, which- is backwards on a surface whose bar is precision at the acting stage.-- It costs one more possible git query in the worst case, and that is the- honest price of a fifth candidate rather than something to hide by- dropping the fourth.+ A stale node-scoped episode is suppressed, while a repo-wide one is served+ with its age labelled, so a window of node-scoped candidates alone could+ all fall through. The best repo-wide candidate is therefore **appended**+ when the window holds none. Not substituted: a repo-wide verdict never+ suppresses, so in the last slot it would pre-empt a git-verified candidate."""window = scoped[:_MAX_SCOPED_CANDIDATES]if any(not matched for _row, matched in window):@@ -228,28 +196,20 @@ def _scope() -> list[str] | None:"""The part of the answer this episode is about, or None if it is not.- Two rules, one per shape of episode. An episode that names files is scoped- by those files. An episode with an **empty node set is a claim about the- checkout as a whole** — it is not "unknown scope", and it does not- therefore intersect everything: read that way, the repo-wide facts would- ride along on every sub-high-confidence answer in the repository, which is- the noise this gate exists to prevent. Repo-wide episodes are scoped by- their subject instead, which the store already defines as the field that- discriminates episodes within a kind.+ An episode that names files is scoped by them. An empty node set is a claim+ about the whole checkout, not "unknown scope" that intersects everything,+ so repo-wide episodes are scoped by their subject instead."""nodes = [n for n in (row.get("nodes") or []) if isinstance(n, str) and n]if nodes:return sorted({p for p in answer_paths if _covers(nodes, p)}) or Nonesubject = (row.get("subject") or "").strip()- # A subject with no word character (``nested_repos`` uses ``.`` for the- # repo root) is not a topic — and ``\b`` around pure punctuation matches in- # places no reader would call a mention.+ # A punctuation-only subject (``.`` for the repo root) is not a topic, and+ # ``\b`` around punctuation matches nonsense.if not re.search(r"\w", subject):return None- # A subject equal to the repository's own name has no topic scope: every- # answer in a repo names the repo, so matching on it is matching on- # nothing.+ # Every answer names its own repo, so that subject scopes nothing.if repo_name and subject.casefold() == repo_name.strip().casefold():return Noneif not re.search(rf"\b{re.escape(subject.casefold())}\b", haystack):diff --git a/packages/server/src/repowise/server/mcp_server/tool_answer/evidence.py b/packages/server/src/repowise/server/mcp_server/tool_answer/evidence.pyindex 88413374e..d9199883e 100644--- a/packages/server/src/repowise/server/mcp_server/tool_answer/evidence.py+++ b/packages/server/src/repowise/server/mcp_server/tool_answer/evidence.py@@ -54,20 +54,10 @@ def _is_readable_path(target: str) -> bool:async def _first_resolvable_id(ids: list[str], ctx, repository, exclude_spec) -> str | None:"""The first id ``get_symbol`` would actually answer, or None if none would.- Notes and ``next_action_hint``s interpolate a ``symbol_id`` straight out of- the scanner. The scanner is a regex over source lines, so it can name- something that is not a symbol, and an answer must never advertise a next- action that dead-ends.-- ``get_symbol`` has THREE outcomes and only one of them is a failure: an- indexed row, a live-grep fallback when the name is in the file but not the- index, and nothing at all. Treating the live-grep case as unresolvable is a- mistake already made once while measuring this, so it counts as resolved.-- Deliberately conservative in the other direction: an id whose file cannot be- read is KEPT, because an unreadable file is absence of evidence, not- evidence the id is fabricated. Only a positive read that does not contain- the name, with no index row either, disqualifies one.+ The regex scanner can name a non-symbol, and a next action must never+ dead-end. ``get_symbol`` answers from an indexed row or a live grep of the+ file, so either counts as resolved. An unreadable file is KEPT (absence of+ evidence); only a read lacking the name, with no index row, disqualifies."""repo_root = _repo_root(ctx)for sid in ids:@@ -92,12 +82,9 @@ async def _first_resolvable_id(ids: list[str], ctx, repository, exclude_spec) ->def _rationale_anchors(h: dict) -> list[tuple[str, int | None]]:"""One ``(path, near-line)`` pair per reason this hit is worth scanning.- 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- available. Each anchored or question-matched symbol then contributes the- same path again at its own definition line, so a file with several matches- is repeated as many times as it has reasons, which is the weighting the- scan orders on.+ A concept-anchored file leads, at its grep match line. Each anchored or+ matched symbol repeats the path at its definition line, so a file appears+ once per reason: the weighting the scan orders on."""path = h.get("target_path")if not path:@@ -115,16 +102,10 @@ def _rationale_anchors(h: dict) -> list[tuple[str, int | None]]:async def _gather_code_rationale(ctx, hits: list[dict], fallback_targets: list[str], question: str):"""Mine in-code rationale comments for a low-confidence answer.- The wiki/decision corpus failed to ground the question; the "why" may be a- plain code comment instead. Scan the already-relevant files — anchored /- matched-symbol files lead, with a near-line boost on their definition, then- fallback_targets fill the rest — for comment blocks carrying a rationale- marker overlapping the question. Best-effort: returns [] on any failure,- never raises into the tool path.-- Off the loop, like the sibling live-source miner on the value fast path:- it is small per call, and every concurrent request pays it if it runs where- the loop can feel it.+ The "why" may be a plain code comment the wiki missed. Scans anchored and+ matched files first, then fallback_targets, for rationale comments+ overlapping the question. Best-effort ([] on failure) and off the event+ loop, so concurrent requests do not pay for it."""repo_root = getattr(ctx, "path", None)if not repo_root:@@ -149,11 +130,8 @@ async def _gather_code_rationale(ctx, hits: list[dict], fallback_targets: list[sdef _drop_already_surfaced(rationale: list[dict], *surfaced: list[dict]) -> list[dict]:"""Drop mined rationale comments already shown elsewhere in the response.- The same comment can reach the payload twice — once as material already in- the response (a ``symbol_bodies`` block whose body contains it, a quote, a- line-ranged citation, or a legacy ``code_comment`` decision) and once as a- live-mined ``code_rationale`` entry. Drop any mined comment whose- ``(path, line-range)`` overlaps an entry already surfaced. Entries without a+ Drops any mined comment whose ``(path, line-range)`` overlaps a surfaced+ entry (a body, quote or line-ranged citation). Entries without a``(path, lines)`` pair are ignored."""occupied = [span for entries in surfaced for span in map(_line_span, entries or []) if span]diff --git a/packages/server/src/repowise/server/mcp_server/tool_answer/payload.py b/packages/server/src/repowise/server/mcp_server/tool_answer/payload.pyindex e31d80373..abbf73101 100644--- a/packages/server/src/repowise/server/mcp_server/tool_answer/payload.py+++ b/packages/server/src/repowise/server/mcp_server/tool_answer/payload.py@@ -62,15 +62,9 @@ from repowise.server.mcp_server.tool_answer.symbols import (def _trim_served_payload(payload: dict) -> dict:"""Every size cut that runs on the way OUT, on both the fresh and cache paths.- Serve-time rather than build-time, and that is the whole point. A cut applied- where the payload is assembled reaches only fresh answers: a cache row- written by an older build keeps the old shape until ``_ANSWER_SCHEMA_VERSION``- moves, and bumping that invalidates every user's answer cache — re-synthesis,- i.e. real provider spend — to change the size of a block. Trimming on the way- out fixes old and new rows alike and costs nobody a re-synthesis.-- Anything that only REMOVES redundancy belongs here. Anything that changes- what an answer says does not, and still owes a schema bump.+ Serve-time so cached rows from older builds are trimmed too, without a+ ``_ANSWER_SCHEMA_VERSION`` bump and its re-synthesis spend. Only cuts that+ REMOVE redundancy belong here; changing what an answer says owes a bump."""_cap_candidates(payload)_drop_duplicated_guess_excerpts(payload)@@ -88,16 +82,9 @@ def _cap_candidates(payload: dict) -> dict:def _drop_duplicated_guess_excerpts(payload: dict) -> dict:"""Drop ``best_guesses[].excerpt`` where ``retrieval[]`` already carries it.- Both blocks slice the same page excerpt for the same file, so when both are- present the guess copy is byte-for-byte redundant.-- **Conditional, and the condition matters.** ``retrieval`` is- confidence-gated and shrinks to nothing as the prose gets more trustworthy;- the legacy abstain path ships ``retrieval: []`` outright. On those responses- the guess excerpt is the only content in the payload, not a duplicate of- anything. So the drop is keyed on the duplicate actually being present, which- makes it lossless rather than merely cheap — and keeps every ``excerpt``- mentioned by ``note`` / ``next_action_hint`` on the paths that mention it.+ Keyed on the duplicate actually being present: ``retrieval`` is often empty+ (high confidence, legacy abstain), and there the guess excerpt is the only+ content, so the drop stays lossless."""guesses = payload.get("best_guesses")if not guesses:@@ -117,12 +104,9 @@ def _drop_duplicated_guess_excerpts(payload: dict) -> dict:def _apply_lean_high(payload: dict, question: str) -> dict:"""Strip re-read evidence from a mainline high-confidence answer, in place.- No-op unless the flag is on and confidence is high. Two carve-outs keep the- evidence where it IS the answer: grounded fast paths (extracted /- exact_symbol / symbol_body / data_shape, which carry a ``grounding`` key,- and whose inlined body is the whole answer) and why-questions — a "because X"- is justified by exactly the code_rationale / quotes this strips, so a lean- why-answer loses the grounding its rationale stands on.+ No-op unless the flag is on and confidence is high. Evidence is kept where+ it IS the answer: grounded fast paths (a ``grounding`` key) and why-questions,+ whose "because X" rests on the code_rationale / quotes this strips."""if not _lean_high() or payload.get("confidence") != "high" or payload.get("grounding"):return payload@@ -139,23 +123,16 @@ def _apply_lean_high(payload: dict, question: str) -> dict:def _build_best_guesses(hits: list[dict]) -> list[dict]:"""Decision-shaped candidate list: per-file justification, score, excerpt.- The evidence an ambiguous-retrieval reply carries so the agent can pick ONE- file to verify instead of skimming five. Shared by the legacy abstain path,- the always-synthesize low/medium fold-in, and the degraded paths.-- ``file`` is resolved through ``hit_file_path``, and a hit resolving to no- file is skipped — both for the reason ``serialize_candidates`` does it: a- ``symbol_spotlight`` page's ``target_path`` is ``file.py::Symbol`` and a- module page's is a group key, neither of which a consumer can open. This- field is named "file" and gets Read.+ Lets the agent pick ONE file to verify on an ambiguous retrieval. ``file``+ goes through ``hit_file_path`` and unresolvable hits are skipped, since a+ spotlight or module page's ``target_path`` is not an openable file."""return [{"file": hit_file_path(h),"why_relevant": _candidate_justification(h),"score": round(h.get("score", 0.0), 3),- # Absent rather than null: a penalty applies to a minority of hits,- # so the common row would pay characters to say nothing happened.+ # Absent rather than null: most rows carry no penalty.**({"domain_penalty": h["_domain_penalty"]} if h.get("_domain_penalty") else {}),**({"excerpt": h["excerpt"]} if h.get("excerpt") else {}),}@@ -167,23 +144,10 @@ def _build_best_guesses(hits: list[dict]) -> list[dict]:def _with_candidates(payload: dict, resolved_pool: list[dict]) -> dict:"""Attach the ranked shortlist to a payload that is about to be returned.- ``get_answer`` has several early returns that fire *after* retrieval has run:- the qualified-miss guard, answer-by-union, the value-extraction fast path,- the legacy abstain, and both degraded paths. Each was written as a complete- reply in its own terms and each set ``retrieval`` to ``[]`` and returned.-- That is right about ``retrieval``, which is re-read evidence for a synthesised- answer, and wrong about what the caller is left holding. ``resolved_pool``- already exists at every one of these sites: the full ranked file list, built- before the 5-hit synthesis cap, at no further cost. Discarding it means a- caller whose question tripped one of these gates gets a narrower reply than- one whose question did not, and gets it *because* we recognised their question- more precisely.-- So the shortlist travels with every reply. This adds to a payload and takes- nothing away: no gate stops firing, no predicate moves, and the special reply- each gate exists to give is returned unchanged. It is deliberately NOT the- fix of loosening a gate, which measured worse on recall@5.+ Every post-retrieval early return empties ``retrieval``, but the pre-cap+ ranked pool is still free and useful, so a caller whose question tripped a+ special path is not left with less than one whose question did not. Adds to+ the payload only; no gate changes."""candidates = _serialize_candidates(resolved_pool)if candidates:@@ -194,14 +158,8 @@ def _with_candidates(payload: dict, resolved_pool: list[dict]) -> dict:def _no_answer_payload(note: str, *, repository, t0: float) -> dict:"""The reply for a post-retrieval gate that has nothing to answer with.- Two gates end this way and both mean the same thing: retrieval ran, and the- honest reply is "not this" plus what to do instead. The qualified-miss guard- refuses to substitute a same-named symbol from another file; the no-hits- guard has no candidates at all. ``note`` is the only part that differs, and- it carries the redirect.-- Both callers still wrap this in :func:`_with_candidates`, which is what keeps- the ranked shortlist travelling with every post-retrieval return.+ Used by the qualified-miss and no-hits guards; ``note`` carries the+ redirect. Callers still wrap it in :func:`_with_candidates`."""return {"answer": "",@@ -233,21 +191,13 @@ def _union_answer_payload() -> dict | None:"""The answer-by-union reply, or None to let synthesis handle the question.- The question named a symbol with N>=2 defs no qualifier disambiguates- (``_severity_for`` x 4). Instead of bailing to a best_guesses pointer list- (the exact thing that triggers the agent's get_symbol/get_context drill),- inline the UNION of the candidate bodies (char-budgeted, Read-parity) so the- agent picks the one it wants from material already in-hand. This is the fix- for the retrieval-MISS class: those defs are never in the fuzzy candidate- set, so the exact-name scan is the only thing that surfaces them.-- Returns None in three cases, all of which mean the union is not the answer:- the union is incidental (a prose question that merely mentions a many-def- generic method like ``to_dict`` would otherwise dump every unrelated body as- a confidence=high answer, burying what was actually asked), the question is a- mechanism/"how" question whose real answer often lives in another file the- union path never retrieves, or the bodies could not be read — in which case- falling through to the normal gate path beats returning an empty union.+ The question named a symbol with N>=2 undisambiguated defs, so the UNION of+ their bodies is inlined (char-budgeted) rather than a pointer list. The+ exact-name scan is the only thing that surfaces defs fuzzy retrieval missed.++ Returns None when the union is not the answer: a prose question merely+ mentioning a generic many-def method, a mechanism question whose answer+ often lives elsewhere, or unreadable bodies."""union_groups = homonyms.get("union") or {}if union_groups and union_defers_to_synthesis(question, question_ids, union_groups):@@ -259,25 +209,13 @@ def _union_answer_payload(repo_root = _repo_root(ctx)union_bodies, more_defs = build_homonym_union_bodies(repo_root, union_groups)if not union_bodies:- # Bodies unreadable (no repo root / files gone) — fall through to the- # normal retrieval/gate path rather than returning an empty union.return Nonenames = sorted(union_groups)total = sum(len(v) for v in union_groups.values())cited = sorted({b["path"] for b in union_bodies})- # This payload returns BEFORE synthesis, so none of the confidence gates ever- # see it: it is served in no-LLM mode and it used to hardcode- # confidence="high" with "no verification Read" even when a body arrived- # truncated. "this is the complete set" is also an exclusivity claim,- # generated by us rather than by a model, and it is true of the DEFINITION- # SET while saying nothing about whether each body was served whole.- #- # The dependency test the synthesis gate uses CANNOT work here, and keying on- # it made this gate dead code. This path is reached only for naming/lookup- # questions about the homonym, so the question names the SERVED symbol by- # construction while the withheld symbols are its inner members, and there is- # no answer prose to inspect either. Here the bodies simply ARE the answer,- # so truncation alone is the right condition.+ # Returns before synthesis, so no confidence gate sees it. The withheld+ # dependency test cannot fire here (the question names the SERVED symbol),+ # and the bodies ARE the answer, so truncation alone caps the grade.union_truncated = any(b.get("truncated") for b in union_bodies)_union_confidence = "medium" if union_truncated else "high"note = (@@ -311,9 +249,7 @@ def _union_answer_payload(),"citations": cited,"confidence": _union_confidence,- # Rates the `candidates` shortlist, not the bodies: the union answers by- # exact name and the note offers that shortlist for "if you meant- # something else". It is the one body-serving return that had no rating.+ # Rates the `candidates` shortlist, not the exact-name bodies."retrieval_quality": retrieval_quality,"grounding": "exact_symbol","symbol_bodies": union_bodies,@@ -340,17 +276,12 @@ async def build_abstain_payload() -> dict:"""The legacy abstain reply (REPOWISE_ANSWER_ALWAYS_SYNTHESIZE=off).- Retrieval is ambiguous, so skip synthesis and hand back ranked excerpts +- best_guesses for the agent to ground in. The excerpts those best_guesses- carry were attached by the caller: a pointers-only gated payload sends the- agent into a long Grep/Read spree that costs more than a bare agent, since it- paid for the tool call and still had to acquire all content natively.- Excerpts turn the miss path into "pick one candidate, verify with at most one- Read".+ Retrieval is ambiguous, so synthesis is skipped and best_guesses carry+ excerpts: pointers alone send the agent on a Grep/Read spree, excerpts turn+ the miss into "pick one candidate, verify with at most one Read"."""best_guesses = _build_best_guesses(hits)- # Mine source comments for rationale the wiki/decision corpus missed —- # turns "go Read these 5 files" into a cited why.+ # Source-comment rationale the wiki/decision corpus missed.code_rationale = await _gather_code_rationale(ctx, hits, fallback_targets, question)has_excerpts = any("excerpt" in g for g in best_guesses)gated: dict = {@@ -402,8 +333,7 @@ def build_value_payload("""The value-extraction fast path reply.The verbatim assignment line (read live by the hydrator) IS the answer.- One call, zero LLM cost, and it cannot hallucinate. Not cached: extraction is- cheap and must always reflect the current source.+ Not cached: extraction is cheap and must reflect the current source."""top_score_fp = hits[0].get("score", 0.0) if hits else 0.0answer_text = extraction["answer"]@@ -491,13 +421,8 @@ async def build_synthesized_payload(exclude_spec=exclude_spec,)- # Ambiguous-retrieval evidence (always-synthesize). The questions that used- # to abstain (no dominant page) now carry synthesized PROSE — but the- # retrieval was genuinely ambiguous, so ship the same evidence the old- # abstain path did: best_guesses (per-file justification + excerpts) and- # mined code_rationale, plus an honest caveat. This is the "answered, but- # verify against these candidates" reply that replaced the empty pointer- # list. Guarded so it never touches the dominant / high-confidence paths.+ # Non-dominant retrieval: the prose ships with the abstain path's evidence+ # (best_guesses, code_rationale) and a caveat, "answered, but verify".if not dominant:payload.setdefault("best_guesses", _build_best_guesses(hits))if "code_rationale" not in payload:@@ -506,11 +431,8 @@ async def build_synthesized_payload(if _cr:payload["code_rationale"] = _crif grade.high_reason == "symbol_body":- # Held at high over an ambiguous ranking because the body of the- # symbol the question named is inlined below. Telling the agent to- # verify against best_guesses would send it to the ranked pages the- # confidence deliberately does not rest on, so the caveat scopes the- # doubt to the page choice and leaves the served body alone.+ # High rests on the served body, not the ranking, so the caveat+ # scopes doubt to the page choice rather than pointing at best_guesses._caveat = ("Retrieval was ambiguous (no single dominant page), so the ""candidates listed are a ranking, not a finding — the confidence "@@ -549,13 +471,9 @@ async def _hedged_payload() -> dict:"""The reply for an answer whose own prose admits it could not answer.- Keep the retrieval payload lean but non-empty. The consumer has been told to- read the source, but the ranked hits are exactly what tells it WHICH source —- and a flow endpoint or a surfaced subsystem page that only lives in this block- would otherwise vanish from the response entirely, since it is not in- citations, which are drawn from the prose. The lean form (no per-hit- key_symbols dump) keeps the prompt-cache cost the empty payload was- protecting.+ The retrieval block stays lean but non-empty: the ranked hits say WHICH+ source to read, and a hit absent from the prose-drawn citations would+ otherwise vanish entirely."""payload = {"answer": answer_text,@@ -563,11 +481,8 @@ async def _hedged_payload("confidence": confidence,"retrieval_quality": retrieval_quality,"fallback_targets": fallback_targets[:5],- # The hedge is the priciest reply we send and the least likely to be- # right, so it gets the graded low branch's excerpt budget rather than- # one of its own. Safe to cut at build time, unlike most payload cuts:- # `_cache_bypass_reason` refuses every hedged row, so a hedged reply is- # always freshly built and no stored row can keep the wider shape.+ # The low branch's excerpt budget. Safe to cut at build time: hedged rows+ # are never served from cache, so no stored row keeps a wider shape."retrieval": _serialize_hits(hits, limit=5, lean_symbols=True, excerpt_rows=_GATED_RETURN_HITS),@@ -576,16 +491,10 @@ async def _hedged_payload("the indexed wiki. Read one of fallback_targets to answer."),}- # Even on a hedge, hand over any question-named symbol bodies we resolved —- # the agent can read the body directly instead of the fallback_targets file,- # which is the whole point of anchoring.if symbol_bodies:payload["symbol_bodies"] = symbol_bodiesif served_named_body:- # The exact symbol the question named is inlined below as live- # source. That is the answer; the hedge is about the surrounding- # prose, not the body. Say so, and mark the response grounded so the- # agent cites the body instead of re-reading the file.+ # The hedge is about the prose; the named body is the answer.payload["grounding"] = "symbol_body"payload["note"] = ("Synthesis hedged on the prose, but symbol_bodies carries "@@ -597,9 +506,8 @@ async def _hedged_payload("Synthesis hedged, but symbol_bodies carries the live body ""of the symbol(s) you named — read that to answer.")- # The hedge often means the rationale isn't in the wiki at all — it's a code- # comment. Mine the candidate source for it before sending the agent off to- # Read. A comment already visible in symbol_bodies must not surface twice.+ # A hedge often means the rationale is a code comment, not wiki prose. A+ # comment already visible in symbol_bodies must not surface twice.code_rationale = await _gather_code_rationale(ctx, hits, fallback_targets, question)code_rationale = _drop_already_surfaced(code_rationale, symbol_bodies)if code_rationale:@@ -614,16 +522,10 @@ async def _hedged_payload(def _high_confidence_note(grade: _Grade, tail: str) -> str:"""The high-confidence note, written from the reason the grade was reached.- Each branch quotes the measurement its own tier made and no other. The ratio- is a valid justification only under ``"ratio"``: the gap tier exists BECAUSE- the ratio is uninformative where both scores are strong (6.0 vs 5.4 reads as- 1.11x), and fusion compresses agreement pairs to about 1.02x, so quoting it- under either would print a near tie as the reason for confidence.-- Only the dominance tiers and ``"symbol_body"`` reach *tail*, which is what- tells the agent it need not re-read the source. ``"grounding"`` never does:- it establishes the prose is not fabricated, which is not a claim about- whether the page it describes is the right one.+ Each branch quotes only the measurement its own tier made (see+ :func:`dominance_reason`). Only the dominance tiers and ``"symbol_body"``+ reach *tail*, the "need not re-read" line; ``"grounding"`` shows the prose+ is not fabricated, not that the page is the right one."""if grade.high_reason == "symbol_body":return (@@ -683,15 +585,9 @@ async def _graded_payload() -> dict:"""The non-hedged reply, with the note the first applicable gate finding writes.- Confidence-conditional retrieval block: the block exists so the agent can- ground when the answer alone isn't trustworthy. At high confidence the- citations + answer suffice — carrying five enriched hits through the- conversation cache buys nothing. At medium the agent verifies the top- candidates: two truncated hits, no symbol enrichment for graph-expansion- neighbors. Low keeps a grounding block, but lean: the top hits with snippets,- symbols pipeable but stripped of docstrings/excerpts, since the full per-hit- key_symbols dump was the largest block by volume and went mostly unused on a- low-confidence answer.+ The retrieval block is confidence-conditional: empty at high (citations+ suffice), two truncated hits at medium, and a lean block at low (symbols+ without docstrings/excerpts, the largest and least-used part)."""confidence = grade.confidenceif confidence == "high":@@ -715,12 +611,7 @@ async def _graded_payload(if symbol_bodies:payload["symbol_bodies"] = symbol_bodiesif grade.high_reason == "symbol_body":- # Same value the hedged path already emits for the same situation: what- # this answer rests on is the served body, not the ranking. It also has- # to be set for `_apply_lean_high` to see it — that strips `symbol_bodies`- # from a high-confidence payload unless `grounding` marks it as the- # evidence, and the note below points the agent straight at the block it- # would otherwise have removed.+ # Also what stops `_apply_lean_high` stripping the body the note cites.payload["grounding"] = "symbol_body"if grade.ungrounded_values:payload["note"] = (@@ -736,11 +627,8 @@ async def _graded_payload(f"{grade.ungrounded_values} against the live source.")elif grade.frame_unsupported:- # The synthesised answer leaned on a mechanism term retrieval never- # showed, so the real mechanism likely lives in code 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.+ # The real mechanism likely lives in uncaptured code; mine source+ # comments so the downgrade ships a lead, not just a warning.code_rationale = await _gather_code_rationale(ctx, hits, fallback_targets, question)code_rationale = _drop_already_surfaced(code_rationale, symbol_bodies, quotes)if code_rationale:@@ -758,9 +646,7 @@ async def _graded_payload(f"{grade.frame_unsupported} are not in the retrieved material.")elif grade.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.+ # Names the axis of doubt, not the check that triggered it.payload["note"] = ("Answer may not cover every relevant site: a cited symbol's body ""was truncated and the answer makes an unqualified causal claim. "@@ -783,9 +669,7 @@ async def _graded_payload(exclude_spec=exclude_spec,)elif grade.lookup_body_truncated:- # The ninth gate fired: the caller asked for a symbol by name and its- # body did not fit. Without this the demotion would ship with no note at- # all, since the high-confidence branch below is unreachable for it.+ # The lookup gate fired; without this the demotion would ship no note.cut = grade.named_body_cutpayload["note"] = (f"You asked for {cut['name']} and its body did not fit: "@@ -798,34 +682,21 @@ async def _graded_payload(f"call get_symbol id='{cut['continuation']}' for the rest of {cut['name']}")elif confidence == "high":- # The rationale deliberately no longer cites "the answer is direct (no- # hedging)". _SYSTEM_PROMPT instructs the model not to hedge, so scoring- # the absence of hedging as evidence FOR confidence is circular: the- # pipeline mandates directness and then reads its own mandate back as a- # signal. Dominance is an independent measurement; directness is not.+ # "No hedging" is not cited as evidence: the prompt forbids hedging, so+ # reading its absence back as a signal would be circular._tail = ("Cite this answer; do not re-read the source unless a specific ""detail is missing."if not any(b.get("truncated") for b in symbol_bodies)- # Never tell the consumer to skip re-reading when the payload itself- # admits it withheld part of a cited body. The withheld names are in- # `symbol_bodies[].withheld_symbols`.+ # Never say "skip re-reading" when the payload admits it withheld+ # part of a cited body.else "Some cited bodies were truncated; see ""symbol_bodies[].withheld_symbols for what was not served.")- # Say which test earned the grade, and quote only the measurement that- # test actually made. Writing one sentence for every high is how a- # response came to quote "clearly dominates (dominance ratio 1.00x)" — a- # tie — as its own justification, beside the caveat that no page- # dominated. The gap and agreement tiers fire at ratios near 1.0 too, so- # naming them without their own numbers would reproduce it exactly.payload["note"] = _high_confidence_note(grade, _tail)- # 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.+ # A concept-anchored hit's comment is the literal rationale for a "why is+ # X = <number>" question; surface it unless a gate already did.if "code_rationale" not in payload and any(h.get("_concept_anchored") for h in hits):concept_rationale = await _gather_code_rationale(ctx, hits, fallback_targets, question)concept_rationale = _drop_already_surfaced(concept_rationale, symbol_bodies, quotes)@@ -845,23 +716,16 @@ async def _attach_withheld_note() -> None:"""Write the note and next action for a withheld symbol the answer depends on.- A withheld entry whose name matches the body it was found in is the ENCLOSING- symbol — served up to the cut and continuing past it — not a symbol that- never arrived. Calling that "not served" is wrong about the payload directly- above the note, and sends the caller to get_symbol for a body they already- hold most of. The accurate pointer is the ``continuation`` the entry already- carries, which fetches just the missing part and is a valid get_symbol id in- its own right ("path.py:174-221").+ An enclosing-symbol continuation (see :func:`_is_enclosing_continuation`)+ is pointed at by its ``continuation``, itself a valid get_symbol id+ ("path.py:174-221"), rather than reported as not served."""_implicated = set(withheld_implicated)_continuing = [b for b in symbol_bodies if _is_enclosing_continuation(b, _implicated)]_continuing_names = {b["name"] for b in _continuing}_absent = [n for n in withheld_implicated if n not in _continuing_names]- # Only advertise an id get_symbol can actually answer. The scanner that- # produced these is a regex over source lines, so it can name something that- # is not a symbol, and the id does not stay in a list of eight — it becomes- # the next action the payload tells the agent to take. When none resolves the- # names are still reported; only the dead pointer is withheld.+ # Only advertise an id get_symbol can answer: the regex scanner can name a+ # non-symbol, and this id becomes the next action. Names are still reported._hint_id = await _first_resolvable_id([s["symbol_id"]@@ -885,9 +749,7 @@ async def _attach_withheld_note(else ""))- # Qualify by path only when the same name was cut in more than one file, so- # the common case stays readable and the ambiguous case does not ship two- # sentences that look identical.+ # Qualify by path only when the same name was cut in more than one file._dupe = len({_b["name"] for _b in _continuing}) < len(_continuing)for _b in _continuing:_who = f"{_b['name']} ({_b['path']})" if _dupe else _b["name"]diff --git a/packages/server/src/repowise/server/mcp_server/tool_answer/projection.py b/packages/server/src/repowise/server/mcp_server/tool_answer/projection.pyindex 456c01375..a97e8a526 100644--- a/packages/server/src/repowise/server/mcp_server/tool_answer/projection.py+++ b/packages/server/src/repowise/server/mcp_server/tool_answer/projection.py@@ -273,12 +273,8 @@ def _keep(payload: dict[str, Any], key: str, limit: int | None) -> None:def _default_shape(payload: dict[str, Any], question: str) -> None:- # A degraded payload keeps the fullest evidence shape whatever it graded.- # The trimming above is keyed on prose REPLACING evidence: a high-confidence- # answer makes the ranked list redundant, so it goes. There is no answer on- # this path - the evidence IS the product - and its ``confidence`` now rates- # that evidence rather than prose, so reading the two on one scale would cut- # a body and a hit from exactly the caller who has nothing else to read.+ # A degraded payload keeps the fullest shape whatever it graded: trimming is+ # keyed on prose replacing evidence, and there the evidence IS the product.confidence = "low" if payload.get("degraded") else payload.get("confidence", "low")why = question.lstrip().lower().startswith("why")if confidence == "high":diff --git a/packages/server/src/repowise/server/mcp_server/tool_answer/retrieval.py b/packages/server/src/repowise/server/mcp_server/tool_answer/retrieval.pyindex 5fd921b39..1ead81f11 100644--- a/packages/server/src/repowise/server/mcp_server/tool_answer/retrieval.py+++ b/packages/server/src/repowise/server/mcp_server/tool_answer/retrieval.py@@ -36,63 +36,29 @@ from repowise.server.mcp_server.tool_answer.config import (_log = logging.getLogger("repowise.mcp.answer")-# How many files ``candidates`` names.-#-# Was 20, on the estimate that "twenty path lines cost roughly 800 characters-# against the ~10k a get_answer response already spends". Measured on the wire-# 2026-08-11 the block is **3,107-3,279 characters, up to 39.9% of a-# get_answer payload** — four times the estimate, because ``defines`` and the-# paths themselves are both longer than a bare path line. That estimate was-# also made before ``defines`` existed.-#-# Five, not zero. Rows 6-20 appear in no other block, but nor are rows 1-5-# redundant: on the repowise samples ``candidates`` is the only block naming-# files outside the top-two ``citations``, and dropping it whole (which the-# CLI projection does) pushes the agent into a Grep that costs more than the-# rows saved. The head keeps the ``defines`` budget, so the navigational value-# per character goes up.+# How many files ``candidates`` names. Rows with ``defines`` are long, so a large+# cap made this block a big share of the payload. Five, not zero: it is often the+# only block naming files beyond the top ``citations``, and without it the agent+# runs a Grep that costs more than the rows._CANDIDATE_LIMIT = 5def serialize_candidates(hits: list[dict], *, limit: int = _CANDIDATE_LIMIT) -> list[dict]:"""The files retrieval ranked, one line each, ordered best first.- Separate from ``retrieval`` on purpose, and deliberately not- confidence-gated. ``retrieval`` is *evidence*: enriched hits an agent reads- to check the prose, so it is right for it to shrink as the prose gets more- trustworthy. This block is *navigation*: the shortlist of files worth- opening next. Under the old shape a confident answer named zero files and a- medium one named two, which is backwards. The more sure we are of a- subsystem, the better placed we are to say which files it lives in.-- One entry per distinct path, ``{path, lines?}``. Line bounds are attached- only where a hit already carries hydrated symbols; nothing is fetched to- build this.-- ``path`` is always a **file** path, resolved through ``hit_file_path``. A- ``symbol_spotlight`` hit's ``target_path`` is ``file.py::Symbol``, which is- a page identifier, not something a consumer can open; two distinct symbols- in one file are also one file to read, so they collapse to one entry here.-- Pages naming no file at all are skipped rather than emitted (finding A15).- A module page's target_path is a structural group key that reads like a- directory and an onboarding page's is a slot name, so every "does this look- like a path" heuristic says yes and the agent that opens it gets an error.- Scoring impact is about zero, measured; it is wrong on the same argument- A14 was, which is that this field has one meaning and it is not "page id".-- ``defines`` carries what the file declares, as ``name:line`` pairs, when- ``_hydrate_candidate_defines`` resolved any. That is the difference between- a path the agent has to Grep and a line it can read: 434 of the 499 paths a- get_answer response served on the 25 flow questions carried no content- whatsoever, and the Layer B taxonomy judged 89% of the agent's post-answer- searches to be exactly that expansion. **Line numbers here are as indexed- and are not verified against the live file** (unlike ``get_symbol``); they- are navigation, not a citation.-- **Which paths are emitted, and in what order, is not affected by any of- this.** ``defines`` is attached to entries the existing loop already built,- so an added or exhausted budget can never add, drop or reorder a path.+ Deliberately not confidence-gated: ``retrieval`` is *evidence* and shrinks+ as the prose gets trustworthy, while this block is *navigation*, the files+ worth opening next, and a confident answer is best placed to name them.++ One entry per distinct **file** path (via ``hit_file_path``), ``{path,+ lines?}``; line bounds come only from already-hydrated symbols. Pages that+ name no file (module group keys, onboarding slots) are skipped, since they+ look like paths but cannot be opened.++ ``defines`` lists what the file declares as ``name:line`` pairs, turning a+ path to Grep into a line to read. **Line numbers are as indexed, not+ verified** against the live file: navigation, not a citation. The+ ``defines`` budget never adds, drops or reorders a path."""out: list[dict] = []seen: set[str] = set()@@ -131,37 +97,24 @@ def serialize_hits() -> list[dict]:"""Agent-facing view of retrieval hits — content only, no plumbing.- Internal scoring fields (``_coverage``, ``_coverage_multiplier``,- ``_confidence_score_factor``, ``_raw_score``, ``_sources``,- ``_pagerank``, …) and ``page_id`` are ranking debug an agent can do- nothing with; they were ~70% of a get_answer response by volume. Zero- information loss for the consumer: path, title, summary, snippet,- excerpt, score, and hydrated symbols all survive.-- ``summary_chars`` truncates summaries (medium-confidence diet);- ``symbols_for_expanded=False`` drops symbol enrichment from hits that- only entered via 1-hop graph expansion (they are routing material, not- answer material). ``lean_symbols=True`` keeps each symbol pipeable- (name/kind/signature/lines) but drops docstrings and excerpts — for the- gated low-confidence path, where the hits are candidates to pick between,- not answer material, and ``best_guesses`` + ``code_rationale`` already- carry the choosing signal.-- ``excerpt_rows`` serves the page excerpt on the first N rows only. An- excerpt is ~1,500 characters against ~300 for the whole rest of a row, so it- is essentially the entire cost of this block; rows past the cut keep path,- title, summary, snippet and score, which is a described candidate rather- than a bare pointer. Deliberately a *field* cut and not a row cut: dropping- rows takes paths out of the response, and a named path costs almost nothing.+ Internal scoring fields (``_coverage``, ``_raw_score``, ...) and+ ``page_id`` are ranking debug an agent cannot use, so they are dropped.++ ``summary_chars`` truncates summaries; ``symbols_for_expanded=False`` drops+ symbols from hits that only entered via graph expansion (routing material);+ ``lean_symbols=True`` keeps symbols pipeable but drops docstrings and+ excerpts, for the low-confidence path where hits are candidates to pick.++ ``excerpt_rows`` serves the page excerpt on the first N rows only: the+ excerpt is most of a row's cost. A *field* cut, not a row cut, because+ dropping rows takes paths out and a named path costs almost nothing."""out: list[dict] = []for idx, h in enumerate(hits[: limit if limit is not None else len(hits)]):target = h.get("target_path")entry: dict[str, Any] = {"path": target}- # A symbol_spotlight page's target_path is ``file.py::Symbol``: a page- # id, not a path a consumer can open. Keep it (callers pipe it into- # get_symbol) and name the file too, so ``path`` never has to be- # guessed at by anything downstream.+ # ``file.py::Symbol`` is a page id callers pipe into get_symbol; name+ # the openable file beside it.if target and "::" in target:entry["file"] = target.split("::", 1)[0]if h.get("title"):@@ -254,15 +207,11 @@ async def _intersection_boost(question: str, hits: list[dict], ctx: Any = None)async def _attach_page_excerpts(hits: list[dict], ctx: Any = None) -> int:"""Attach each top hit's real page content as ``excerpt``. Mutates `hits`.- Every consumer of a hit — the synthesis prompt and the pointer payload- alike — otherwise sees only the page's one-line LLM summary or a 200-char- opener, next to a symbol block carrying docstrings and source bodies. A- consumer given names but no prose reconstructs rationale from the names,- which is a confident wrong answer rather than a thin one.+ Without it a consumer sees only a one-line summary beside symbol names, and+ reconstructs rationale from the names: a confident wrong answer.- Returns the number of top hits left without page content. That count is- the point: a hit reaching synthesis with no body used to be invisible,- which is how this went unnoticed for as long as it did.+ Returns the number of top hits left without page content, so a hit+ reaching synthesis with no body is visible rather than silent."""if not hits:return 0@@ -280,9 +229,7 @@ async def _attach_page_excerpts(hits: list[dict], ctx: Any = None) -> int:res = await session.execute(select(Page.id, Page.content).where(Page.id.in_(page_ids)))content_by_id = {row[0]: (row[1] or "") for row in res.all()}except Exception:- # Never fail the answer over an excerpt fetch — but never lose the- # fact either. Without this line the whole prompt silently degrades- # to summaries and the answer still looks confident.+ # Never fail the answer over an excerpt fetch, but never hide it either._log.warning("get_answer: page-content fetch failed for %d hits; synthesis ""will read one-line summaries instead of page prose",@@ -303,12 +250,9 @@ async def _attach_page_excerpts(hits: list[dict], ctx: Any = None) -> int:def _detect_question_domain(question: str) -> str | None:"""Return ``"ui"``, ``"backend"``, or ``None`` when the question is ambiguous.- Used to break ties on retrievals where vocabulary overlaps across domains- (e.g. "how does indexing work" could plausibly retrieve a UI status-pill- component or the actual ingestion pipeline). The classifier is intentionally- conservative: if both domain token sets fire, or neither does, we return- ``None`` and apply no penalty — better to leave ranking alone than to- miscategorise a cross-cutting question.+ Breaks ties where vocabulary overlaps across domains. Conservative: if both+ token sets fire, or neither, no penalty applies rather than miscategorise a+ cross-cutting question."""qlow = question.lower()has_ui = any(tok in qlow for tok in _UI_QUESTION_TOKENS)@@ -346,11 +290,8 @@ def _apply_domain_penalty(hits: list[dict], question: str) -> None:def _candidate_justification(h: dict) -> str:"""One-line reason this hit might answer the question.- Used on the low-confidence return path so the agent sees something- decision-shaped ("Read file X because it implements Y") instead of a- flat list of paths it has to scan into. Prefers the matched-symbol name- over the file summary because the matched symbol is what tied this hit- to the question in the first place.+ Decision-shaped ("implements Y") rather than a bare path. Prefers the+ matched symbol, which is what tied this hit to the question."""syms = h.get("symbols") or []matched = next((s for s in syms if s.get("_matched")), None)@@ -360,8 +301,7 @@ def _candidate_justification(h: dict) -> str:return f"Implements {kind} {name}."summary = (h.get("summary") or h.get("snippet") or "").strip()if summary:- # First sentence only; trailing prose is mostly cache-write cost on- # the consumer side.+ # First sentence only; the rest is mostly cache-write cost.first = summary.split(". ")[0]return (first[:160].rstrip() + ".") if first else ""title = h.get("title") or ""@@ -376,12 +316,8 @@ def _rerank_by_coverage(hits: list[dict], question: str) -> list[dict]:so a generic lexical overlap such as ``coverage`` cannot beat a page thatalso agrees on ``PR``, ``test impact``, and ``changed files``. Raw fusedretrieval remains the base signal; this is a bounded multiplier, not a- replacement score.-- This addresses a common BM25 failure mode where a hit that matches one- constraint very strongly can outrank a hit that matches all constraints- moderately — the latter is usually the better answer for multi-constraint- questions.+ replacement score. Counters BM25 ranking one strongly-matched constraint+ above a hit that matches every constraint moderately."""return rerank_by_context_coverage(hits,