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
feat(mcp): hybrid MCP improvements — verified trust contract, honest savings, constant indexing (#467)
Swati Ahuja28f58fb71b39
diff --git a/packages/cli/src/repowise/cli/commands/update_cmd.py b/packages/cli/src/repowise/cli/commands/update_cmd.pyindex 2413bbc12..8de56b4b5 100644--- a/packages/cli/src/repowise/cli/commands/update_cmd.py+++ b/packages/cli/src/repowise/cli/commands/update_cmd.py@@ -396,6 +396,7 @@ def _persist_index_only_update(head: str | None,start: float,changed_paths: list[str],+ file_diffs: list | None = None,) -> None:"""Persist the index-only update (graph + git + dead-code + health), savestate, and print the completion line. No LLM regeneration.@@ -413,6 +414,7 @@ def _persist_index_only_update(dead_code_report,partial_health_report,changed_paths,+ file_diffs=file_diffs,log=console.print,))@@ -527,9 +529,7 @@ def _run_full_health_rescore(pass # metrics fall back to lazy computationexclude_spec = (- pathspec.PathSpec.from_lines("gitwildmatch", exclude_patterns)- if exclude_patterns- else None+ pathspec.PathSpec.from_lines("gitwildmatch", exclude_patterns) if exclude_patterns else None)async def _rescore() -> None:@@ -555,9 +555,7 @@ def _run_full_health_rescore(sf = create_session_factory(engine)async with get_session(sf) as session:- repo = await upsert_repository(- session, name=repo_path.name, local_path=str(repo_path)- )+ repo = await upsert_repository(session, name=repo_path.name, local_path=str(repo_path))repo_id = repo.idgm_result = await session.execute(@@ -619,9 +617,7 @@ def _run_full_health_rescore({**state, "last_sync_commit": head, "config_fingerprint": curr_fingerprint},)elapsed = time.monotonic() - start- console.print(- f"[green]Config-triggered health re-score complete[/green] in {elapsed:.1f}s"- )+ console.print(f"[green]Config-triggered health re-score complete[/green] in {elapsed:.1f}s")# ---------------------------------------------------------------------------@@ -923,9 +919,7 @@ def update_command(# new rules/excludes instead of being left stale.console.print("[yellow]Config files changed — re-running health analysis.[/yellow]")if dry_run:- console.print(- "[yellow]Dry run — health would be re-scored. No changes made.[/yellow]"- )+ console.print("[yellow]Dry run — health would be re-scored. No changes made.[/yellow]")returncfg = load_config(repo_path)exclude_patterns = list(cfg.get("exclude_patterns") or [])@@ -996,6 +990,7 @@ def update_command(head,start,[fd.path for fd in file_diffs],+ file_diffs=file_diffs,)return@@ -1025,9 +1020,7 @@ def update_command(# all subsequent updates.from repowise.cli.providers import build_cost_tracker- cost_tracker = build_cost_tracker(- repo_path, repo_path.name, no_cost_tracking=no_cost_tracking- )+ cost_tracker = build_cost_tracker(repo_path, repo_path.name, no_cost_tracking=no_cost_tracking)provider._cost_tracker = cost_tracker# (dead_code_report computed above, before the index-only branch)@@ -1222,6 +1215,17 @@ def update_command(repo_id = repo.idfor page in generated_pages:await upsert_page_from_generated(session, page, repo_id)+ # Tombstone pages for deleted/renamed files — regeneration only+ # rewrites pages for files that still exist.+ try:+ from repowise.core.pipeline.persist import (+ mark_tombstone_pages,+ tombstone_candidates,+ )++ await mark_tombstone_pages(session, repo_id, tombstone_candidates(file_diffs))+ except Exception as exc:+ console.print(f"[yellow]Tombstone marking skipped: {exc}[/yellow]")# Persist updated git metadata + recompute percentilesif git_meta_map:diff --git a/packages/core/src/repowise/core/generation/templates/claude_md.j2 b/packages/core/src/repowise/core/generation/templates/claude_md.j2index 7bbac88d2..3f919b7ee 100644--- a/packages/core/src/repowise/core/generation/templates/claude_md.j2+++ b/packages/core/src/repowise/core/generation/templates/claude_md.j2@@ -105,22 +105,27 @@ This repo has the Repowise MCP server configured. The tools below answer questio| Tool | What only this tool answers ||------|------------------------------|-| `get_answer(question)` | Synthesised answer with verified citations and a calibrated `retrieval_quality`. First call for "how does X work" / "why is Y like this". On low confidence returns `best_guesses` with one-line justifications instead of an empty answer. |-| `get_context(targets=[...])` | Triage card for files/modules/symbols — title, summary, signatures, `hotspot` bit, `decision_records` titles, and `symbol_id`s to pipe into `get_symbol`. Use `include=["callers","ownership",...]` to widen. NOT for source bytes. |-| `get_symbol("path/to/file.py::Name")` | Raw source bytes for one indexed symbol with exact line bounds. Cheaper and safer than `Read` + offset math. Use the `symbol_id` returned by `get_context`. |-| `search_codebase(query, kind?)` | Find pages by concept when you don't know the file. Each result carries `search_method` (`embedding` vs `bm25` fallback). For exact identifiers use Grep — the tool will hint when it sees one. |+| `get_answer(question)` | Synthesised answer with citations and a content-grounded `confidence`. First call for "how does X work" / "where is Y" / "why is Z". Value questions may return `grounding: "extracted"` — the verbatim source line, no synthesis involved. On low confidence returns `best_guesses` with one-line justifications. |+| `get_context(targets=[...])` | Triage card for files/modules/symbols — title, summary, signatures, `hotspot` bit, `decision_records` titles, `symbol_id`s. File targets auto-upgrade to a `verified` skeleton (every signature, ~37% of a full Read). `include=["callers"]` works on file targets too (import + call rollup). |+| `get_symbol(...)` | Source bytes with live-verified bounds. Three forms: `"path.py::Name"` (indexed symbol), `"path.py:140-180"` (live range read, ≤200 lines), `"repowise#<hex>"` (omission ref). Index misses return `fallback_lines` from a live grep instead of a dead end. |+| `search_codebase(query, kind?)` | Find pages by concept when you don't know the file. Results carry `search_method` (`embedding` vs `bm25` fallback). Decision records rank below file pages unless the query is why-shaped. Identifier-bearing queries get a `grep_hint` — prefer Grep for those tokens. || `get_why(query, targets?)` | Architectural decision archaeology — *why* the code is shaped this way. Call before refactors or pattern divergences. Falls back to git archaeology when no ADRs exist for a file. || `get_risk(targets, changed_files?)` | What history says about touching these files: churn, owners, blast radius. Pass `changed_files` for PR mode → returns a `directive` (`will_break`, `missing_cochanges`, `missing_tests`). || `get_dead_code(...)` | Tiered unreachable / unused-export / zombie-package findings. Run before a cleanup sprint, not before a targeted fix. |-| `get_overview(repo?)` | Architecture map for an unfamiliar repo. One-time orientation; skip on subsequent calls in the same session. |+| `get_overview(repo?)` | Architecture map + `tool_guide` recipes. One-time orientation; skip on subsequent calls in the same session. |++**Trust protocol — when a response replaces reading the source:**+- `verified: true` on any response means the served content was checked against the live working tree. **Never follow a verified response with a Read of the same lines** — you would be paying twice for identical bytes.+- `get_answer` with `confidence: "high"` or `grounding: "extracted"` is content-grounded (asserted values were verified against retrieved source; ≥1 citation is source-backed). Cite it directly. `quotes` entries `{path, lines, quote}` are verbatim live source — quote them instead of re-reading.+- Reading code: `get_context` skeleton first (~37% of a full Read), then `get_symbol` for bodies, `"path.py:a-b"` range reads for anything between symbols. Raw `Read` is for files the index marks `mostly_full` or cannot serve.+- The **only** re-read triggers: `bounds: "approximate"`, `_meta.stale_warning`, `search_method: "bm25"`, or `confidence: "low"`/`retrieval_quality: "weak"`.+- Disallowed rationalizations for extra reads: "just to be safe", "to double-check the tool", "to see the full context" (use the skeleton / a range read), "the file might have changed" (that is what `verified` already checked).**Composition tips:**-- `get_answer` → if `confidence` is `medium`/`low`, follow the `best_guesses[0].file` or `fallback_targets[0]` into `get_context`, then `get_symbol` for bytes.-- `get_context` returns `decision_records` titles → call `get_why(targets=[...])` for the rationale.-- `get_context` returns `hotspot: true` → call `get_risk` before editing.+- `get_answer` → if `confidence` is `medium`/`low`, follow `best_guesses[0].file` or `fallback_targets[0]` into `get_context`, then `get_symbol` for bytes.+- `get_context` returns `decision_records` titles → `get_why(targets=[...])` for the rationale; `hotspot: true` → `get_risk` before editing.- PR review → `get_risk(targets=[...], changed_files=[...])`; read the `directive` block first.--**Verify when:** `_meta.stale_warning` is present, or `retrieval_quality` is `partial`/`weak`, or `search_method` is `bm25`. Otherwise trust the response and act on it.+- A `tombstone` error means the file was deleted/renamed since indexing — follow `successor_paths`.### Output Distillationdiff --git a/packages/core/src/repowise/core/ingestion/extractors/signatures.py b/packages/core/src/repowise/core/ingestion/extractors/signatures.pyindex 6f2c542af..9060cea43 100644--- a/packages/core/src/repowise/core/ingestion/extractors/signatures.py+++ b/packages/core/src/repowise/core/ingestion/extractors/signatures.py@@ -58,5 +58,15 @@ def build_signature(node_type: str, name: str, params_text: str, def_node: Node,return f"impl {name}"if node_type in ("class_specifier",):return f"class {name}"+ if node_type in ("assignment", "variable_declarator"):+ # Module-level constant/variable: the signature IS the assignment —+ # the verbatim line answers "what is the default value of X" without+ # a follow-up source read. First line only, bounded; multi-line+ # values (dicts, arrays) stay reachable via get_symbol.+ text = node_text(def_node, src)+ first_line = text.splitlines()[0].strip() if text else name+ if len(first_line) > 160:+ first_line = first_line[:157] + "..."+ return first_line# Fallbackreturn f"{name}{params_text}"diff --git a/packages/core/src/repowise/core/ingestion/language_configs.py b/packages/core/src/repowise/core/ingestion/language_configs.pyindex 0f0065919..c708c964a 100644--- a/packages/core/src/repowise/core/ingestion/language_configs.py+++ b/packages/core/src/repowise/core/ingestion/language_configs.py@@ -58,12 +58,14 @@ class LanguageConfig:parent_class_types: frozenset[str] = field(default_factory=frozenset)-LANGUAGE_CONFIGS: dict[str, LanguageConfig] = {"python": LanguageConfig(symbol_node_types={"function_definition": "function","class_definition": "class",+ # Module-level assignments (the .scm pattern is module-anchored).+ # Refined in the parser: SCREAMING_CASE → constant, else variable.+ "assignment": "constant",},import_node_types=["import_statement", "import_from_statement"],export_node_types=[],@@ -83,6 +85,9 @@ LANGUAGE_CONFIGS: dict[str, LanguageConfig] = {"enum_declaration": "enum","method_definition": "method","lexical_declaration": "function", # const foo = () => {}+ # Top-level const/let with a literal value (the .scm pattern is+ # program-anchored). Refined in the parser like Python assignments.+ "variable_declarator": "constant",},import_node_types=["import_statement"],export_node_types=["export_statement"],@@ -98,6 +103,7 @@ LANGUAGE_CONFIGS: dict[str, LanguageConfig] = {"class_declaration": "class","method_definition": "method","lexical_declaration": "function",+ "variable_declarator": "constant",},import_node_types=["import_statement"],export_node_types=["export_statement"],diff --git a/packages/core/src/repowise/core/ingestion/parser.py b/packages/core/src/repowise/core/ingestion/parser.pyindex 71aa5c002..00ee0c6e8 100644--- a/packages/core/src/repowise/core/ingestion/parser.py+++ b/packages/core/src/repowise/core/ingestion/parser.py@@ -80,6 +80,12 @@ _SYMBOL_COUNT_WARN_THRESHOLD = 500QUERIES_DIR = Path(__file__).parent / "queries"+# Node types whose .scm patterns are anchored at module/program level+# (constants and module variables). They can never be function-local, so+# the callable-ancestor filter must not apply — and for TS/JS declarators+# it would misfire on the parent lexical_declaration kind mapping.+_MODULE_ANCHORED_NODE_TYPES = frozenset({"assignment", "variable_declarator"})+@lru_cache(maxsize=None)def _load_compiled_query(lang: str, grammar_tag: str | None = None) -> object | None:@@ -363,8 +369,13 @@ class ASTParser:# exports. Filtering by callable ancestor restricts extraction# to module-top-level + class-body members. Class bodies don't# match (``class_definition`` is not callable), so methods are- # preserved.- if _has_callable_ancestor(def_node, config.symbol_node_types):+ # preserved. Module-anchored node types skip the check: their+ # .scm patterns only match at module/program level, and a TS+ # variable_declarator's parent (lexical_declaration → "function")+ # would otherwise read as a callable ancestor.+ if node_type not in _MODULE_ANCHORED_NODE_TYPES and _has_callable_ancestor(+ def_node, config.symbol_node_types+ ):continue# Refine "struct" kind for Go type_spec (check if struct or interface body)@@ -379,6 +390,15 @@ class ASTParser:):kind = refine_kotlin_class_kind(def_node)+ # Refine module-level assignments: SCREAMING_CASE names are+ # constants by convention; the rest are module variables+ # (singletons like ``app = FastAPI()``, registries, caches).+ # ``str.isupper()`` requires at least one cased char, so names+ # with no letters (``_``, ``__all__``) fall to "variable" rather+ # than being mislabelled constants by ``name == name.upper()``.+ if node_type in _MODULE_ANCHORED_NODE_TYPES:+ kind = "constant" if name.isupper() else "variable"+# Params signature textparams_text = _node_text(params_nodes[0], src) if params_nodes else ""@@ -628,7 +648,8 @@ class ASTParser:# Language-specific import name + binding extractionimported_names, bindings = extract_import_bindings(stmt_node, src, file_info.language)is_relative = (- module_text.startswith(".") or module_text.startswith("./")+ module_text.startswith(".")+ or module_text.startswith("./")or module_text.startswith(("self::", "super::", "crate::")))diff --git a/packages/core/src/repowise/core/ingestion/queries/javascript.scm b/packages/core/src/repowise/core/ingestion/queries/javascript.scmindex 227eeb458..15371b4e0 100644--- a/packages/core/src/repowise/core/ingestion/queries/javascript.scm+++ b/packages/core/src/repowise/core/ingestion/queries/javascript.scm@@ -36,6 +36,40 @@)) @symbol.def+; Top-level const/let with a non-function value — module constants. The+; declarator (not the lexical_declaration) is @symbol.def so the kind map+; can distinguish it from the arrow-function pattern above. Anchored at+; (program …) — directly or under an export_statement — so function-local+; declarations never match. require() declarators (call_expression or+; member_expression values) are imports, never symbols.+(program+ (lexical_declaration+ (variable_declarator+ name: (identifier) @symbol.name+ value: [+ (string) (template_string) (number) (true) (false) (null) (undefined)+ (array) (object) (unary_expression) (binary_expression)+ (new_expression)+ ]+ ) @symbol.def+ )+)++(program+ (export_statement+ (lexical_declaration+ (variable_declarator+ name: (identifier) @symbol.name+ value: [+ (string) (template_string) (number) (true) (false) (null) (undefined)+ (array) (object) (unary_expression) (binary_expression)+ (new_expression)+ ]+ ) @symbol.def+ )+ )+)+; ---------------------------------------------------------------------------; Imports; ---------------------------------------------------------------------------diff --git a/packages/core/src/repowise/core/ingestion/queries/python.scm b/packages/core/src/repowise/core/ingestion/queries/python.scmindex 394948561..4cfb284b6 100644--- a/packages/core/src/repowise/core/ingestion/queries/python.scm+++ b/packages/core/src/repowise/core/ingestion/queries/python.scm@@ -27,6 +27,17 @@name: (identifier) @symbol.name) @symbol.def+; Module-level assignment — constants and module config values. Anchored at+; (module …) so function-local and class-body assignments never match; the+; parser refines the kind (SCREAMING_CASE → constant, otherwise variable).+(module+ (expression_statement+ (assignment+ left: (identifier) @symbol.name+ ) @symbol.def+ )+)+; Decorated function or class — captures the decorator as a modifier(decorated_definition(decorator) @symbol.modifiersdiff --git a/packages/core/src/repowise/core/ingestion/queries/typescript.scm b/packages/core/src/repowise/core/ingestion/queries/typescript.scmindex c62fc71ba..cd330d638 100644--- a/packages/core/src/repowise/core/ingestion/queries/typescript.scm+++ b/packages/core/src/repowise/core/ingestion/queries/typescript.scm@@ -66,6 +66,39 @@name: (property_identifier) @symbol.name) @symbol.def+; Top-level const/let with a non-function value — module constants. The+; declarator (not the lexical_declaration) is @symbol.def so the kind map+; can distinguish it from the arrow-function pattern above. Anchored at+; (program …) — directly or under an export_statement — so function-local+; declarations never match.+(program+ (lexical_declaration+ (variable_declarator+ name: (identifier) @symbol.name+ value: [+ (string) (template_string) (number) (true) (false) (null) (undefined)+ (array) (object) (unary_expression) (binary_expression)+ (new_expression) (member_expression) (as_expression) (satisfies_expression)+ ]+ ) @symbol.def+ )+)++(program+ (export_statement+ (lexical_declaration+ (variable_declarator+ name: (identifier) @symbol.name+ value: [+ (string) (template_string) (number) (true) (false) (null) (undefined)+ (array) (object) (unary_expression) (binary_expression)+ (new_expression) (member_expression) (as_expression) (satisfies_expression)+ ]+ ) @symbol.def+ )+ )+)+; ---------------------------------------------------------------------------; Imports; ---------------------------------------------------------------------------diff --git a/packages/core/src/repowise/core/pipeline/incremental.py b/packages/core/src/repowise/core/pipeline/incremental.pyindex 344965535..af385d126 100644--- a/packages/core/src/repowise/core/pipeline/incremental.py+++ b/packages/core/src/repowise/core/pipeline/incremental.py@@ -393,6 +393,7 @@ async def persist_incremental_index(partial_health_report: Any,changed_paths: list[str],*,+ file_diffs: list[Any] | None = None,log: LogFn | None = None,) -> None:"""Persist an incremental index refresh (graph + git + dead-code + health).@@ -422,6 +423,20 @@ async def persist_incremental_index(repo = await upsert_repository(session, name=repo_path.name, local_path=str(repo_path))repo_id = repo.id+ # Tombstone pages for deleted/renamed files FIRST — a fresh page+ # for a file that no longer exists misleads every retrieval+ # consumer until the next full regeneration.+ if file_diffs:+ try:+ from repowise.core.pipeline.persist import (+ mark_tombstone_pages,+ tombstone_candidates,+ )++ await mark_tombstone_pages(session, repo_id, tombstone_candidates(file_diffs))+ except Exception as exc:+ log(f"[yellow]Tombstone marking skipped: {exc}[/yellow]")+if git_meta_map:try:from repowise.core.persistence.crud import (diff --git a/packages/core/src/repowise/core/pipeline/persist.py b/packages/core/src/repowise/core/pipeline/persist.pyindex c5f0ee8ff..699c30160 100644--- a/packages/core/src/repowise/core/pipeline/persist.py+++ b/packages/core/src/repowise/core/pipeline/persist.py@@ -15,6 +15,71 @@ import structloglogger = structlog.get_logger(__name__)+def tombstone_candidates(file_diffs: list[Any]) -> list[tuple[str, list[str]]]:+ """(dead_path, successor_paths) pairs from deleted/renamed file diffs.++ A renamed file's old path gets its new path as the successor; a deleted+ file has no successor. Diffs of other statuses contribute nothing.+ """+ out: list[tuple[str, list[str]]] = []+ for fd in file_diffs or []:+ status = getattr(fd, "status", None)+ if status == "deleted" and fd.path:+ out.append((fd.path, []))+ elif status == "renamed" and fd.old_path:+ out.append((fd.old_path, [fd.path] if fd.path else []))+ return out+++async def mark_tombstone_pages(+ session: Any, repo_id: str, candidates: list[tuple[str, list[str]]]+) -> int:+ """Mark file pages for deleted/renamed files as tombstones.++ A ``freshness_status="fresh"`` page for a file that no longer exists is+ an active trap: retrieval serves it, agents cite it, and the index-age+ metadata says nothing is wrong. Tombstoned pages keep their content+ (the prose may still orient a reader) but carry status=tombstone and+ ``successor_paths`` in metadata so serving layers can skip or redirect.++ Returns the number of pages marked.+ """+ if not candidates:+ return 0+ from sqlalchemy import select++ from repowise.core.persistence.models import Page++ page_ids = {f"file_page:{path}": (path, successors) for path, successors in candidates}+ res = await session.execute(+ select(Page).where(Page.repository_id == repo_id, Page.id.in_(page_ids))+ )+ marked = 0+ for page in res.scalars().all():+ _, successors = page_ids[page.id]+ page.freshness_status = "tombstone"+ try:+ meta = json.loads(page.metadata_json or "{}")+ except (json.JSONDecodeError, TypeError):+ meta = {}+ meta["successor_paths"] = successors+ page.metadata_json = json.dumps(meta)+ marked += 1+ if marked:+ logger.info("pages_tombstoned", repo_id=repo_id, count=marked)+ elif candidates:+ # Candidates existed but no page matched — the id scheme drifted from+ # ``file_page:{path}`` or the paths don't line up. Silent success here+ # would let stale pages keep serving, so surface it.+ logger.debug(+ "tombstone_no_match",+ repo_id=repo_id,+ candidate_count=len(candidates),+ sample=[p for p, _ in candidates[:3]],+ )+ return marked++async def persist_graph_nodes(session: Any,repo_id: str,diff --git a/packages/server/src/repowise/server/mcp_server/_answer_pipeline.py b/packages/server/src/repowise/server/mcp_server/_answer_pipeline.pyindex 6ae453f54..bbf65ee15 100644--- a/packages/server/src/repowise/server/mcp_server/_answer_pipeline.py+++ b/packages/server/src/repowise/server/mcp_server/_answer_pipeline.py@@ -192,15 +192,16 @@ async def hydrate_hits(hits: list[dict], ctx: Any, *, scope: str | None = None)page_ids = [h["page_id"] for h in hits]async with get_session(ctx.session_factory) as session:res = await session.execute(- select(Page.id, Page.target_path, Page.summary, Page.page_type).where(- Page.id.in_(page_ids)- )+ select(+ Page.id, Page.target_path, Page.summary, Page.page_type, Page.freshness_status+ ).where(Page.id.in_(page_ids)))meta_by_id = {row[0]: {"target_path": row[1] or "","summary": row[2] or "","page_type": row[3] or "",+ "freshness": row[4] or "",}for row in res.all()}@@ -208,6 +209,10 @@ async def hydrate_hits(hits: list[dict], ctx: Any, *, scope: str | None = None)out: list[dict] = []for h in hits:meta = meta_by_id.get(h["page_id"], {})+ # Tombstoned pages document deleted/renamed files — serving them as+ # answer material would cite code that no longer exists.+ if meta.get("freshness") == "tombstone":+ continuetarget_path = meta.get("target_path", "")if scope and target_path and not target_path.startswith(scope):continue@@ -288,9 +293,7 @@ async def expand_via_graph(hits: list[dict], ctx: Any) -> list[dict]:"""if not hits:return hits- seed_paths = [- h.get("target_path") for h in hits[:_GRAPH_EXPAND_TOP_N] if h.get("target_path")- ]+ seed_paths = [h.get("target_path") for h in hits[:_GRAPH_EXPAND_TOP_N] if h.get("target_path")]if not seed_paths:return hitsexisting = {h.get("target_path") for h in hits}@@ -349,18 +352,20 @@ async def expand_via_graph(hits: list[dict], ctx: Any) -> list[dict]:parent_score = max((h.get("score", 0.0) for h in hits[:_GRAPH_EXPAND_TOP_N]), default=0.0)candidates: list[dict] = []for path, summary, page_type in page_rows:- candidates.append({- "page_id": f"file_page:{path}",- "target_path": path,- "title": f"File: {path}",- "summary": summary or "",- "snippet": (summary or "")[:200],- "page_type": page_type or "file_page",- "score": parent_score * _GRAPH_EXPAND_DAMPING,- "_sources": {"graph_expand"},- "_expanded_from": "graph",- "_pagerank": pr_by_path.get(path, 0.0),- })+ candidates.append(+ {+ "page_id": f"file_page:{path}",+ "target_path": path,+ "title": f"File: {path}",+ "summary": summary or "",+ "snippet": (summary or "")[:200],+ "page_type": page_type or "file_page",+ "score": parent_score * _GRAPH_EXPAND_DAMPING,+ "_sources": {"graph_expand"},+ "_expanded_from": "graph",+ "_pagerank": pr_by_path.get(path, 0.0),+ }+ )# Rank candidates by PageRank within the expansion set so we pick the# most central neighbor first when we have multiple plausible ones.diff --git a/packages/server/src/repowise/server/mcp_server/_savings/counterfactual.py b/packages/server/src/repowise/server/mcp_server/_savings/counterfactual.pyindex 58efa925c..e9431257c 100644--- a/packages/server/src/repowise/server/mcp_server/_savings/counterfactual.py+++ b/packages/server/src/repowise/server/mcp_server/_savings/counterfactual.py@@ -62,18 +62,63 @@ def _estimate_search_codebase(result: dict[str, Any]) -> int:results = result.get("results")if not isinstance(results, list):return 0+ paths = {r["target_path"] for r in results if isinstance(r, dict) and r.get("target_path")}+ return len(paths) * SEARCH_FLOOR_PER_HIT+++#: get_answer subsumes a search_codebase call plus opening the cited files.+#: Same undersell philosophy as SEARCH_FLOOR_PER_HIT — the dict carries paths,+#: never sizes.+ANSWER_SEARCH_FLOOR = 400+ANSWER_READ_FLOOR_PER_FILE = 400++#: Modest fixed counterfactuals for the analysis tools. Each replaces an+#: exploration the agent cannot cheaply reproduce (git log/blame spelunking,+#: ADR archaeology, README + entry-point skim) but whose size the result dict+#: cannot ground — so a flat, deliberately-low floor per successful call.+RISK_FLOOR = 500+WHY_FLOOR = 400+HEALTH_FLOOR = 400+OVERVIEW_FLOOR = 1200+++def _estimate_get_answer(result: dict[str, Any]) -> int:+ """Search call + cited-file reads the answer obviated.++ Counts only answered calls (non-empty ``answer``): a gated/low response+ explicitly tells the agent to go read, so the reads still happen and+ claiming them as saved would repeat the E11 miscalibration.+ """+ if not str(result.get("answer") or "").strip():+ return 0paths = {- r["target_path"]- for r in results- if isinstance(r, dict) and r.get("target_path")+ p+ for p in [*(result.get("citations") or []), *(result.get("fallback_targets") or [])[:3]]+ if isinstance(p, str) and p}- return len(paths) * SEARCH_FLOOR_PER_HIT+ if not paths:+ return 0+ return ANSWER_SEARCH_FLOOR + len(paths) * ANSWER_READ_FLOOR_PER_FILE+++def _fixed_floor(tokens: int) -> Callable[[dict[str, Any]], int]:+ """Flat counterfactual for successful calls; errors contribute nothing."""++ def _estimate(result: dict[str, Any]) -> int:+ return 0 if result.get("error") else tokens++ return _estimate#: Tool name → estimator. Tools absent here emit no counterfactual (skip)._ESTIMATORS: dict[str, Callable[[dict[str, Any]], int]] = {"get_context": _estimate_get_context,"search_codebase": _estimate_search_codebase,+ "get_answer": _estimate_get_answer,+ "get_risk": _fixed_floor(RISK_FLOOR),+ "get_why": _fixed_floor(WHY_FLOOR),+ "get_health": _fixed_floor(HEALTH_FLOOR),+ "get_overview": _fixed_floor(OVERVIEW_FLOOR),}diff --git a/packages/server/src/repowise/server/mcp_server/_savings/recorder.py b/packages/server/src/repowise/server/mcp_server/_savings/recorder.pyindex 4392ea7c3..3292d269d 100644--- a/packages/server/src/repowise/server/mcp_server/_savings/recorder.py+++ b/packages/server/src/repowise/server/mcp_server/_savings/recorder.py@@ -48,6 +48,34 @@ def record_mcp_saving("""if replaced_tokens <= delivered_tokens or not repo_root:return False+ return _write_row(repo_root, tool, f"mcp:{tool}", replaced_tokens, delivered_tokens)+++def record_mcp_dead_end(+ repo_root: str | Path | None,+ tool: str,+ delivered_tokens: int,+) -> bool:+ """Debit a dead-end call: tokens delivered, nothing replaced.++ An error response costs the agent its full delivered size and saves+ nothing. Recording raw=0 / distilled=delivered makes the row a negative+ contribution at aggregation (saved = raw - distilled) — without these+ debits the ledger only ever credits and overstates net savings (the E11+ sign-flip: +138.7k claimed while the session net-spent).+ """+ if delivered_tokens <= 0 or not repo_root:+ return False+ return _write_row(repo_root, tool, f"mcp:{tool}:dead_end", 0, delivered_tokens)+++def _write_row(+ repo_root: str | Path,+ tool: str,+ source: str,+ raw_tokens: int,+ distilled_tokens: int,+) -> bool:db_path = Path(repo_root) / ".repowise" / OMISSIONS_DIRNAME / OMISSIONS_DB_FILENAMEif not db_path.is_file():# No repo-local sidecar → repo never opted in via `repowise init`.@@ -60,10 +88,10 @@ def record_mcp_saving(try:store.record_saving(filter_name=tool,- source=f"mcp:{tool}",+ source=source,command=None,- raw_tokens=replaced_tokens,- distilled_tokens=delivered_tokens,+ raw_tokens=raw_tokens,+ distilled_tokens=distilled_tokens,)return Trueexcept Exception:diff --git a/packages/server/src/repowise/server/mcp_server/_savings/wrapper.py b/packages/server/src/repowise/server/mcp_server/_savings/wrapper.pyindex c1742649e..6f75ee96c 100644--- a/packages/server/src/repowise/server/mcp_server/_savings/wrapper.py+++ b/packages/server/src/repowise/server/mcp_server/_savings/wrapper.py@@ -37,7 +37,7 @@ from typing import Anyfrom repowise.core.distill.budget import estimate_tokensfrom . import counterfactual-from .recorder import record_mcp_saving+from .recorder import record_mcp_dead_end, record_mcp_savinglogger = logging.getLogger(__name__)@@ -85,8 +85,18 @@ def _delivered_tokens(result: Any) -> int:def _record(tool: str, result: Any) -> None:"""Measure, derive the counterfactual, and record — all best-effort."""declared = _declared_tokens(result)- replaced = declared if declared is not None else counterfactual.replaced_tokens_for(tool, result)+ replaced = (+ declared if declared is not None else counterfactual.replaced_tokens_for(tool, result)+ )if replaced <= 0:+ # Dead-end debit: an error response delivered tokens and replaced+ # nothing — net negative for the session, and the ledger must say so.+ if isinstance(result, dict) and result.get("error"):+ from repowise.server.mcp_server import _state++ record_mcp_dead_end(+ getattr(_state, "_repo_path", None), tool, _delivered_tokens(result)+ )returndelivered = _delivered_tokens(result)diff --git a/packages/server/src/repowise/server/mcp_server/_verify.py b/packages/server/src/repowise/server/mcp_server/_verify.pynew file mode 100644index 000000000..0aaa1944f--- /dev/null+++ b/packages/server/src/repowise/server/mcp_server/_verify.py@@ -0,0 +1,209 @@+"""Serve-time freshness verification for symbol bounds.++WikiSymbol line bounds are written at index time and the source file may+have changed since — historically get_symbol sliced the live file with+stale bounds and served the wrong lines while ``_meta`` claimed the index+was fresh. The agent's rational response was to re-read every MCP response+from disk, which is the verification tax this module deletes.++The contract:++* ``verified: true`` — the served bytes were checked against the live+ file (either the stored bounds still match, or the file was re-parsed+ and the bounds corrected). A verified response never needs a follow-up+ Read.+* ``bounds: "approximate"`` — the live file no longer contains the symbol+ where the index said (rename/delete since indexing) and re-location+ failed; the served slice is the indexed guess, treat accordingly.++Verification is two-tier:++1. Cheap gate (every call): the symbol's bare name must appear on its+ stored definition line in the live file. String containment on one+ line — effectively free since the file is already read for slicing.+2. Re-parse (mismatch only): tree-sitter re-parses just this file+ (compiled queries are process-cached; milliseconds), the symbol is+ re-located by id → (name, parent) → name, and the corrected bounds are+ written back to the WikiSymbol row so the next call hits the cheap+ gate again.+"""++from __future__ import annotations++import logging+from dataclasses import dataclass+from datetime import datetime++from repowise.core.persistence.models import WikiSymbol++_log = logging.getLogger("repowise.mcp.verify")++# Substring containment on a 1-2 char name is meaningless — a constant named+# ``T`` (TypeVar) or ``e`` "matches" almost any line. Names shorter than this+# skip the cheap gate and go straight to a re-parse, which can actually+# confirm them. (Module-level constants/variables now indexed make short+# names common, so the gate must not rubber-stamp them.)+_MIN_GATE_NAME_LEN = 3+++@dataclass+class BoundsCheck:+ """Outcome of verifying one symbol's bounds against live source."""++ start_line: int+ end_line: int+ verified: bool+ corrected: bool = False # True when re-parse moved the bounds+ approximate: bool = False # True when the symbol could not be re-located+++def name_at_line(lines: list[str], name: str, start_line: int) -> bool:+ """Cheap gate: does the stored definition line still carry the name?++ ``lines`` is the live file split into lines; ``start_line`` is+ 1-indexed. The bare name (last segment of a qualified name) must appear+ as a substring of the definition line — true for def/class/assignment+ lines across every indexed language.+ """+ if start_line < 1 or start_line > len(lines):+ return False+ bare = _bare_name(name)+ return bool(bare) and bare in lines[start_line - 1]+++def _bare_name(name: str) -> str:+ """Last segment of a qualified name, regardless of separator style."""+ return (name or "").rsplit(".", 1)[-1].rsplit("::", 1)[-1]+++def _line_indent(line: str) -> int:+ return len(line) - len(line.lstrip())+++def end_anchor_holds(lines: list[str], start_line: int, end_line: int) -> bool:+ """Cheap end check: the line past the stored end isn't still the body.++ The start gate confirms the definition line, but it cannot see an edit+ *inside* the body — lines inserted after the definition leave the def+ line in place while pushing the true end down, so the stored end now+ truncates the symbol. We can't pin the exact end without re-parsing, but+ we can catch that common failure cheaply: if the line immediately after+ the stored end is indented deeper than the definition line, the body+ grew and the stored end is wrong. EOF, a blank line, or a dedented line+ is consistent with a real boundary (brace-closers and module-level+ neighbours both satisfy ``<=`` the definition indent).+ """+ if end_line < start_line or end_line < 1 or end_line > len(lines):+ return False+ def_indent = _line_indent(lines[start_line - 1])+ if end_line >= len(lines):+ return True # symbol ends at EOF+ after = lines[end_line] # 0-indexed: first line past the 1-indexed end+ if not after.strip():+ return True+ return _line_indent(after) <= def_indent+++def relocate_symbol(row: WikiSymbol, source_text: str) -> tuple[int, int] | None:+ """Re-parse the live file and find the symbol's current bounds.++ Returns (start_line, end_line) or None when the symbol no longer+ exists in the file (deleted/renamed) or the file cannot be parsed.+ """+ try:+ from repowise.core.ingestion.models import FileInfo+ from repowise.core.ingestion.parser import ASTParser++ fi = FileInfo(+ path=row.file_path,+ abs_path=row.file_path,+ language=row.language,+ size_bytes=len(source_text),+ git_hash="",+ last_modified=datetime.now(),+ is_test=False,+ is_config=False,+ is_api_contract=False,+ is_entry_point=False,+ )+ parsed = ASTParser().parse_file(fi, source_text.encode("utf-8", errors="replace"))+ except Exception as exc:+ _log.warning("re-parse failed for %s: %s", row.file_path, exc)+ return None++ symbols = parsed.symbols or []+ # Strongest match first: exact symbol_id, then (name, parent), then name.+ for sym in symbols:+ if sym.id == row.symbol_id:+ return sym.start_line, sym.end_line+ for sym in symbols:+ if sym.name == row.name and (sym.parent_name or None) == (row.parent_name or None):+ return sym.start_line, sym.end_line+ candidates = [s for s in symbols if s.name == row.name]+ if len(candidates) == 1:+ return candidates[0].start_line, candidates[0].end_line+ return None+++def check_symbol_bounds(row: WikiSymbol, source_text: str) -> BoundsCheck:+ """Verify (and if needed correct) a symbol's bounds against live source.++ Cheap gate (no re-parse) only when ALL hold: the name is long enough for+ substring containment to mean something, it still sits on the stored+ definition line, AND the stored end still bounds the body. Any miss+ falls through to a one-file re-parse that pins the true bounds.+ """+ lines = source_text.splitlines()+ bare = _bare_name(row.name)+ cheap_ok = (+ len(bare) >= _MIN_GATE_NAME_LEN+ and name_at_line(lines, row.name, row.start_line)+ and end_anchor_holds(lines, row.start_line, row.end_line)+ )+ if cheap_ok:+ end = min(max(row.end_line, row.start_line), len(lines))+ return BoundsCheck(start_line=row.start_line, end_line=end, verified=True)++ located = relocate_symbol(row, source_text)+ if located is not None:+ corrected = located != (row.start_line, row.end_line)+ if corrected:+ _log.info(+ "bounds corrected for %s: %d-%d -> %d-%d",+ row.symbol_id,+ row.start_line,+ row.end_line,+ located[0],+ located[1],+ )+ return BoundsCheck(+ start_line=located[0], end_line=located[1], verified=True, corrected=corrected+ )++ return BoundsCheck(+ start_line=row.start_line,+ end_line=row.end_line,+ verified=False,+ approximate=True,+ )+++async def heal_symbol_row(session_factory, row: WikiSymbol, start: int, end: int) -> None:+ """Persist corrected bounds so the next serve hits the cheap gate.++ Best-effort: a failed heal only costs a re-parse on the next call.+ """+ from sqlalchemy import update++ from repowise.core.persistence.database import get_session++ try:+ async with get_session(session_factory) as session:+ await session.execute(+ update(WikiSymbol)+ .where(WikiSymbol.id == row.id)+ .values(start_line=start, end_line=end)+ )+ await session.commit()+ except Exception as exc:+ _log.warning("bounds self-heal failed for %s: %s", row.symbol_id, exc)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 1ca3a3c4a..6c1d9bc6b 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@@ -30,7 +30,7 @@ import json as _jsonimport loggingimport time-from sqlalchemy import select+from sqlalchemy import delete, selectfrom repowise.core.persistence.database import get_sessionfrom repowise.core.persistence.models import AnswerCache@@ -65,8 +65,13 @@ from repowise.server.mcp_server._helpers import ()from repowise.server.mcp_server._meta import answer_hint as _answer_hintfrom repowise.server.mcp_server._meta import build_meta as _build_meta-from repowise.server.mcp_server.tool_answer.confidence import _answer_is_hedged+from repowise.server.mcp_server.tool_answer.confidence import (+ _answer_is_hedged,+ _is_value_question,+ _ungrounded_numbers,+)from repowise.server.mcp_server.tool_answer.config import (+ _ANSWER_CACHE_TTL_DAYS,_ANSWER_SCHEMA_VERSION,_DOMINANCE_RATIO,_ENRICH_TOP_N_HITS,@@ -82,8 +87,12 @@ from repowise.server.mcp_server.tool_answer.retrieval import (_intersection_boost,_rerank_by_coverage,)+from repowise.server.mcp_server.tool_answer.retrieval import (+ serialize_hits as _serialize_hits,+)from repowise.server.mcp_server.tool_answer.symbols import (_extract_question_identifiers,+ _extract_value_answer,_hydrate_symbols_for_hits,)from repowise.server.mcp_server.tool_answer.synthesis import (@@ -94,30 +103,48 @@ from repowise.server.mcp_server.tool_answer.synthesis import (_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.+ """+ if isinstance(obj, (set, frozenset)):+ # str-key the sort: a serializer whose whole job is "never fail the+ # cache write" must not raise TypeError on a mixed-type set.+ return sorted(obj, key=str)+ return str(obj)+++def _cache_entry_expired(created_at) -> bool:+ """True when an answer-cache row is older than the hard TTL."""+ if created_at is None:+ return False+ from datetime import UTC, datetime, timedelta++ ts = created_at if created_at.tzinfo else created_at.replace(tzinfo=UTC)+ return (datetime.now(UTC) - ts) > timedelta(days=_ANSWER_CACHE_TTL_DAYS)++@mcp.tool()async def get_answer(question: str,scope: str | None = None,repo: str | None = None,) -> dict:- """Synthesised answer to a code question with verified citations and a calibrated trust signal.+ """Synthesised answer with citations and a calibrated trust signal.- The only tool that pairs RAG retrieval over the wiki with an LLM-written- answer plus a separately-reported retrieval_quality. Use it as the first- call on "how does X work" / "where is Y" / "why is Z structured this way"- questions — it eliminates the search → context → read loop when retrieval- is dominant. On low confidence it returns a structured ``best_guesses``- list (one-line justifications per candidate) instead of an empty answer,- so the caller always has somewhere concrete to Read next.-- Returns ``{answer, citations, confidence, retrieval_quality,- fallback_targets, best_guesses?, next_action_hint?}``. Always verify cited- paths exist if you intend to act on them.+ First call for "how does X work" / "where is Y" / "why is Z" questions.+ confidence=high is content-grounded (value + citation-source gates):+ cite it directly, no verification Read needed. Low confidence returns+ best_guesses with one-line justifications instead of an empty answer.+ retrieval_quality separately rates the retrieval that fed synthesis.Args:question: developer question.- scope: optional path prefix to restrict retrieval (e.g. "src/pkg/").- repo: repository identifier; usually omitted.+ scope: optional path-prefix filter (e.g. "src/pkg/").+ repo: usually omitted."""if repo == "all":return _unsupported_repo_all("get_answer")@@ -175,10 +202,23 @@ async def get_answer(cached_paths = [*(payload.get("citations") or []),*(payload.get("fallback_targets") or []),- *(h.get("target_path") for h in (payload.get("retrieval") or [])),+ # "path" is the serialized key; "target_path" survives in+ # rows cached before the clean retrieval view existed.+ *(h.get("path") or h.get("target_path") for h in (payload.get("retrieval") or [])),*(g.get("file") for g in (payload.get("best_guesses") or [])),]excluded_cache = any(is_excluded(p, exclude_spec) for p in cached_paths)+ # Freshness: a row synthesised against a previous index may cite+ # moved code or stale values. The write path stamps the repo's+ # head commit into the persisted payload; a mismatch (or a row+ # past the hard TTL, for pre-stamping rows and gitless repos)+ # forces re-synthesis.+ current_commit = getattr(repository, "head_commit", None)+ cached_commit = payload.get("_indexed_commit")+ stale_commit = bool(+ cached_commit and current_commit and cached_commit != current_commit+ )+ expired = _cache_entry_expired(cached.created_at)if schema_stale:_log.info("Bypassing cache entry at schema v%s (current v%s)",@@ -189,7 +229,19 @@ async def get_answer(_log.info("Bypassing hedged cache entry for re-synthesis")elif excluded_cache:_log.info("Bypassing cache entry referencing a now-excluded path")+ elif stale_commit:+ _log.info(+ "Bypassing cache entry from commit %s (repo now at %s)",+ cached_commit,+ current_commit,+ )+ elif expired:+ _log.info("Bypassing cache entry past the %d-day TTL", _ANSWER_CACHE_TTL_DAYS)else:+ # Cache-internal fields never reach the consumer (response+ # keys must not start with "_" except _meta).+ payload.pop("_indexed_commit", None)+ payload.pop("_schema_version", None)payload["_meta"] = _build_meta(timing_ms=(time.perf_counter() - t0) * 1000,cached=True,@@ -330,7 +382,7 @@ async def get_answer(else "Fall back to search_codebase or Grep."),"fallback_targets": fallback_targets,- "retrieval": hits[:_GATED_RETURN_HITS],+ "retrieval": _serialize_hits(hits, limit=_GATED_RETURN_HITS),"note": ("Multiple plausible candidates — synthesis skipped to ""avoid anchoring on a wrong frame. Each best_guess entry "@@ -352,6 +404,42 @@ async def get_answer(# dominant relational questions and pushes cost back onto the agent's# own reasoning loop.+ # --- Value-extraction fast path ----------------------------------------+ # Value-shaped question + a question-matched constant in the top hits →+ # the verbatim assignment line (read live by the hydrator) IS the+ # answer. Today this class of question costs a multi-call drill-down+ # chain and synthesis sometimes invents the number; the fast path is one+ # call, zero LLM cost, and cannot hallucinate. Not cached: extraction is+ # cheap and must always reflect the current source.+ if _is_value_question(question) and question_ids:+ extraction = _extract_value_answer(hits, question_ids)+ if extraction is not None:+ top_score_fp = hits[0].get("score", 0.0) if hits else 0.0+ answer_text = extraction["answer"]+ if extraction.get("value_source"):+ answer_text += "\n\n" + extraction["value_source"]+ return {+ "answer": answer_text,+ "citations": [extraction["file"]],+ "confidence": "high",+ "retrieval_quality": (+ "high" if top_score_fp >= _HIGH_CONFIDENCE_SCORE_FLOOR else "partial"+ ),+ "grounding": "extracted",+ "fallback_targets": fallback_targets,+ "retrieval": [],+ "note": (+ "Extracted verbatim from the live source line — no LLM "+ "synthesis involved. Cite directly; no verification "+ "Read needed."+ ),+ "_meta": _build_meta(+ timing_ms=(time.perf_counter() - t0) * 1000,+ hint=_answer_hint("high", len(hits)),+ repository=repository,+ ),+ }+# --- Synthesis (LLM) ---------------------------------------------------provider = _resolve_provider_for_answer(getattr(ctx, "path", None))if provider is None:@@ -362,7 +450,7 @@ async def get_answer("citations": [],"confidence": "low","fallback_targets": fallback_targets,- "retrieval": hits,+ "retrieval": _serialize_hits(hits),"note": ("No LLM provider configured (set REPOWISE_PROVIDER + API key). ""Returning retrieval hits only — Read the listed files to answer."@@ -412,7 +500,7 @@ async def get_answer("citations": [],"confidence": "low","fallback_targets": fallback_targets,- "retrieval": hits,+ "retrieval": _serialize_hits(hits),"note": f"LLM synthesis failed ({type(exc).__name__}). Read the listed files to answer.","_meta": _build_meta(timing_ms=(time.perf_counter() - t0) * 1000,@@ -428,6 +516,36 @@ async def get_answer(# Fall back to top-2 retrieval paths so the agent always has something to verify.citations = fallback_targets[:2]+ # Line-grounded quotes: for symbols the answer actually names, attach the+ # verbatim source line(s) the hydrator read live from disk. An agent can+ # publish a cited claim backed by a quote without any verification Read —+ # the quote IS the verification.+ quotes: list[dict] = []+ for h in hits[:_ENRICH_TOP_N_HITS]:+ for s in h.get("symbols") or []:+ name = s.get("name")+ # Require a name long enough that substring containment is+ # meaningful — a 1-2 char constant (``T``, ``e``) would "appear"+ # in almost any answer and attach an irrelevant quote.+ if not name or len(name) < 3 or name not in answer_text:+ continue+ src = s.get("source_excerpt") or s.get("signature") or ""+ if not src:+ continue+ quote_lines = src.splitlines()[:3]+ start = s.get("start_line") or 0+ quotes.append(+ {+ "path": h.get("target_path"),+ "lines": [start, start + len(quote_lines) - 1],+ "quote": "\n".join(quote_lines),+ }+ )+ if len(quotes) >= 5:+ break+ if len(quotes) >= 5:+ break+# Compute confidence from the dominance ratio (top hit vs second hit).# The dominance ratio is a more reliable separator than absolute BM25# thresholds, which tend to label most retrievals "high" indiscriminately.@@ -471,6 +589,27 @@ async def get_answer(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 at low and say why.+ ungrounded_values: list[str] = []+ if not hedged and _is_value_question(question):+ ungrounded_values = _ungrounded_numbers(answer_text, hits)+ if ungrounded_values:+ 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.+ 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"+# retrieval_quality is a separate signal from confidence. Where confidence# says "how much should you trust the synthesised text", retrieval_quality# says "how good was the retrieval that fed it". The agent uses confidence@@ -489,7 +628,6 @@ async def get_answer(# synthesis doesn't help them, and keeping it in the response bloats# every follow-up turn's prompt cache.payload = {- "_schema_version": _ANSWER_SCHEMA_VERSION,"answer": answer_text,"citations": citations,"confidence": "low",@@ -502,16 +640,45 @@ async def get_answer(),}else:+ # 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 the full+ # block — that's when routing material earns its bytes.+ if confidence == "high":+ retrieval_view: list[dict] = []+ elif confidence == "medium":+ retrieval_view = _serialize_hits(+ hits, limit=2, summary_chars=160, symbols_for_expanded=False+ )+ else:+ retrieval_view = _serialize_hits(hits)payload = {- "_schema_version": _ANSWER_SCHEMA_VERSION,"answer": answer_text,"citations": citations,"confidence": confidence,"retrieval_quality": retrieval_quality,"fallback_targets": fallback_targets,- "retrieval": hits,+ "retrieval": retrieval_view,}- if confidence == "high":+ if quotes:+ payload["quotes"] = quotes+ if ungrounded_values:+ payload["note"] = (+ f"Value-grounding gate: the answer asserts {ungrounded_values} "+ "but none of these appear in any retrieved excerpt — the "+ "value(s) may be synthesised. Read "+ f"{fallback_targets[0] if fallback_targets else 'the cited file'} "+ "to confirm before citing a number."+ )+ if fallback_targets:+ payload["next_action_hint"] = (+ f"Read {fallback_targets[0]} and verify the asserted value(s) "+ f"{ungrounded_values} against the live source."+ )+ elif confidence == "high":payload["note"] = ("High confidence: top retrieval result clearly dominates "f"(dominance ratio {_ratio:.2f}x, top score {_top_score:.2f}) "@@ -520,21 +687,39 @@ async def get_answer("is missing.")- # Persist to cache. Best-effort: cache failures must NEVER block the- # response (we already have the answer in hand).+ # Persist to cache (upsert). Best-effort: cache failures must never block+ # the response — but they must be LOGGED, not suppressed. A plain INSERT+ # under a blanket suppress violated uq_answer_cache_q on every+ # bypass-and-resynthesize round and failed silently, so hedged/stale rows+ # were never upgraded. Delete-then-insert in one transaction is the+ # dialect-agnostic upsert; the stamped _indexed_commit drives the+ # read-side freshness check.if answer_text:- with contextlib.suppress(Exception):+ cache_payload = dict(payload)+ cache_payload["_schema_version"] = _ANSWER_SCHEMA_VERSION+ commit_now = getattr(repository, "head_commit", None)+ if commit_now:+ cache_payload["_indexed_commit"] = commit_now+ try:async with get_session(ctx.session_factory) as session:+ await session.execute(+ delete(AnswerCache).where(+ AnswerCache.repository_id == repo_id,+ AnswerCache.question_hash == qhash,+ )+ )row = AnswerCache(repository_id=repo_id,question_hash=qhash,question=question.strip(),- payload_json=_json.dumps(payload),+ payload_json=_json.dumps(cache_payload, default=_json_default),provider_name=getattr(provider, "provider_name", "") or "",model_name=getattr(provider, "model_name", "") or "",)session.add(row)await session.commit()+ except Exception as exc:+ _log.warning("get_answer cache write failed: %s", exc)payload["_meta"] = _build_meta(timing_ms=(time.perf_counter() - t0) * 1000,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 21dd56c6c..6edabb6c2 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@@ -8,6 +8,8 @@ answer — is a pure predicate and lives here.from __future__ import annotations+import re+from repowise.server.mcp_server.tool_answer.config import _HEDGE_MARKERS@@ -21,3 +23,68 @@ def _answer_is_hedged(answer_text: str) -> bool:"""low = (answer_text or "").lower()return any(marker in low for marker in _HEDGE_MARKERS)+++# Question shapes that ask for a specific value: defaults, thresholds,+# limits, counts. These are the questions where a confidently-asserted+# number that retrieval never contained is a factual error, not a nuance.+_VALUE_QUESTION_RE = re.compile(+ r"\b(default|threshold|constant|limit|cap|max|min|value|timeout|"+ r"how many|how much|how large|how big|how long)\b",+ re.IGNORECASE,+)++# file.py:123 / file.py:123-145 — line refs the LLM adds for citations are+# not value assertions and must not feed the grounding check.+_FILE_LINE_REF_RE = re.compile(r"[\w./-]+:\d+(?:-\d+)?")++# Standalone numbers (int or decimal). Lookarounds keep version-ish and+# identifier-embedded digits (v2, utf-8, sha256, 2.5.1) out while still+# 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.+_THOUSANDS_SEP_RE = re.compile(r"(?<=\d)[,_](?=\d)")+++def _numbers_in(text: str) -> set[str]:+ """Standalone numbers in *text*, with digit-grouping separators removed."""+ return set(_NUMBER_RE.findall(_THOUSANDS_SEP_RE.sub("", text or "")))+++def _is_value_question(question: str) -> bool:+ """True when the question asks for a concrete value."""+ return bool(_VALUE_QUESTION_RE.search(question or ""))+++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).+ """+ text = _FILE_LINE_REF_RE.sub(" ", answer_text or "")+ asserted = _numbers_in(text)+ if not asserted:+ return []++ corpus_parts: list[str] = []+ for h in hits or []:+ for key in ("title", "summary", "snippet", "excerpt"):+ v = h.get(key)+ if v:+ corpus_parts.append(str(v))+ for s in h.get("symbols") or []:+ for key in ("name", "signature", "docstring", "source_excerpt"):+ v = s.get(key)+ if v:+ corpus_parts.append(str(v))+ grounded = _numbers_in("\n".join(corpus_parts))+ return sorted(asserted - grounded)diff --git a/packages/server/src/repowise/server/mcp_server/tool_answer/config.py b/packages/server/src/repowise/server/mcp_server/tool_answer/config.pyindex 2f9bd7ecb..3e0ded736 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@@ -58,6 +58,19 @@ _HEDGE_MARKERS = ("does not contain","is not contained","are not contained",+ "do not include",+ "does not include",+ "not included in the",+ "can't enumerate",+ "cannot enumerate",+ "can't determine",+ "i can't",+ "i cannot",+ "not shown in",+ "not shown here",+ "material shown",+ "not visible in",+ "unable to determine","not contain sufficient","not contain enough","is not covered",@@ -180,7 +193,16 @@ _HIGH_CONFIDENCE_SCORE_FLOOR = 1.5# 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.-_ANSWER_SCHEMA_VERSION = 3+# 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.+_ANSWER_SCHEMA_VERSION = 4++# 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.+_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-entitydiff --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 c5426f24c..eb17fcb1f 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@@ -29,6 +29,50 @@ from repowise.server.mcp_server.tool_answer.config import ()+def serialize_hits(+ hits: list[dict],+ *,+ limit: int | None = None,+ summary_chars: int | None = None,+ symbols_for_expanded: bool = True,+) -> list[dict]:+ """Agent-facing view of retrieval hits — content only, no plumbing.++ Internal scoring fields (``_coverage``, ``_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).+ """+ out: list[dict] = []+ for h in hits[: limit if limit is not None else len(hits)]:+ entry: dict[str, Any] = {"path": h.get("target_path")}+ if h.get("title"):+ entry["title"] = h["title"]+ summary = h.get("summary") or ""+ if summary_chars is not None and len(summary) > summary_chars:+ summary = summary[: summary_chars - 1].rstrip() + "…"+ if summary:+ entry["summary"] = summary+ for key in ("snippet", "excerpt"):+ if h.get(key):+ entry[key] = h[key]+ if h.get("score") is not None:+ entry["score"] = round(h["score"], 3)+ expanded = "graph_expand" in (h.get("_sources") or ())+ if h.get("symbols") and (symbols_for_expanded or not expanded):+ entry["key_symbols"] = [+ {k: v for k, v in s.items() if not k.startswith("_")} for s in h["symbols"]+ ]+ out.append(entry)+ return out++def _question_terms(question: str) -> list[str]:"""Extract content terms from a question. Lowercase, alnum-tokenized,stopwords + length<3 dropped. Used by the term-coverage re-ranker."""diff --git a/packages/server/src/repowise/server/mcp_server/tool_answer/symbols.py b/packages/server/src/repowise/server/mcp_server/tool_answer/symbols.pyindex 1669fbf5b..b929b829a 100644--- a/packages/server/src/repowise/server/mcp_server/tool_answer/symbols.py+++ b/packages/server/src/repowise/server/mcp_server/tool_answer/symbols.py@@ -139,6 +139,45 @@ def _read_signature_from_source(return " ".join(sig_lines)+def _extract_value_answer(hits: list[dict], question_ids: set[str]) -> dict | None:+ """Verbatim-assignment answer for value-shaped questions (the C1 fast path).++ When a question names an identifier and the hydrator matched a+ constant/variable symbol in the top hits, the symbol's signature IS the+ answer — the verbatim assignment line read from live source. No LLM+ call, nothing to hedge, nothing to invent. Exact name matches win over+ substring matches.+ """+ qids_lower = {q.lower() for q in question_ids}+ candidates: list[dict] = []+ for h in hits[:_ENRICH_TOP_N_HITS]:+ path = h.get("target_path")+ if not path:+ continue+ for s in h.get("symbols") or []:+ if not s.get("_matched") or s.get("kind") not in ("constant", "variable"):+ continue+ sig = s.get("signature") or ""+ if "=" not in sig:+ continue+ entry = {+ "name": s.get("name"),+ "signature": sig,+ "file": path,+ "line": s.get("start_line"),+ "answer": f"{sig} ({path}:{s.get('start_line')})",+ }+ # Multi-line values (dicts/arrays): the hydrator attached the+ # live body — include it so the agent never needs a follow-up.+ excerpt = s.get("source_excerpt")+ if excerpt and excerpt.strip() != sig.strip():+ entry["value_source"] = excerpt+ if (s.get("name") or "").lower() in qids_lower:+ return entry+ candidates.append(entry)+ return candidates[0] if candidates else None++async def _hydrate_symbols_for_hits(session,repo_id: str,@@ -188,7 +227,13 @@ async def _hydrate_symbols_for_hits(by_file: dict[str, list[dict]] = {}repo_root = Path(str(ctx.path)) if ctx and ctx.path else Nonefor row in res.scalars().all():- rich_sig = _read_signature_from_source(repo_root, row.file_path, row.start_line)+ # Constants/variables: the stored signature IS the verbatim assignment+ # line. The disk re-read below walks forward looking for a ":"-closed+ # def line and would join unrelated following lines for assignments.+ if row.kind in ("constant", "variable"):+ rich_sig = None+ else:+ rich_sig = _read_signature_from_source(repo_root, row.file_path, row.start_line)# Does the symbol name match any identifier from the question?name_lower = (row.name or "").lower()qname_lower = (row.qualified_name or "").lower()diff --git a/packages/server/src/repowise/server/mcp_server/tool_context/context.py b/packages/server/src/repowise/server/mcp_server/tool_context/context.pyindex e269a53bc..a70ba1c20 100644--- a/packages/server/src/repowise/server/mcp_server/tool_context/context.py+++ b/packages/server/src/repowise/server/mcp_server/tool_context/context.py@@ -54,42 +54,18 @@ async def get_context() -> dict:"""Triage card for files / modules / symbols — relationships, not source bytes.- Returns a compact card the agent can use to decide its next move: title,- summary, signatures, hotspot bit, top callers, and pointers (decision_record- titles, symbol_ids) into the deeper tools. For the actual source body of a- symbol, call ``get_symbol("path/to/file.py::Name")`` — it is cheaper than- Read and returns bounded bytes with exact line numbers.-- Batch multiple targets in one call. In workspace mode responses are- auto-enriched with cross-repo co-change partners and API contract links.-- Include options (everything outside defaults is opt-in):- - "full_doc": full wiki markdown content for the target- - "ownership": primary owner, bus factor, contributor count- - "last_change":last commit date and author- - "callers": who calls this symbol (symbol targets only)- - "callees": what this symbol calls (symbol targets only)- - "metrics": PageRank, betweenness centrality, percentile ranks- - "community": architectural community membership + neighbors- - "decisions": full decision records (default returns titles only)- - "skeleton": the file with bodies elided — every signature kept, the- bodies of the highest-PageRank symbols inlined under a- token budget. A fraction of the cost of Read for- structure-level questions (file targets only).- DEFAULT for file targets above ~80 lines: the skeleton- replaces the bare symbol list (strictly better per- token). Pass compact=False for the symbol-list card.- A ``mostly_full`` flag marks files where a direct Read- costs little more.-- Example: get_context(["src/auth/service.py", "src/auth/middleware.py"])- Example: get_context(["src/auth/service.py::verify_token"], include=["callers"])+ Returns title, summary, signatures, hotspot bit, decision_record titles,+ and symbol_ids to pipe into get_symbol (cheaper than Read for bodies).+ Batch targets in one call. File targets above ~80 lines default to a+ skeleton (every signature + top-PageRank bodies, with a verified flag —+ a fraction of Read cost); ``mostly_full`` marks files where a direct+ Read costs little more.Args:- targets: file paths, module paths, or qualified symbol IDs.- include: list of optional data blocks (defaults are always returned).- compact: default True (signatures only; large file targets auto-upgrade- to skeleton). False adds structure+imports+docstrings instead.+ targets: file paths, module paths, or "path::Symbol" ids.+ include: opt-in blocks: full_doc | ownership | last_change | callers+ | callees | metrics | community | decisions | skeleton.+ compact: default True; False adds structure+imports+docstrings.repo: usually omitted."""if repo == "all":diff --git a/packages/server/src/repowise/server/mcp_server/tool_context/enrichment.py b/packages/server/src/repowise/server/mcp_server/tool_context/enrichment.pyindex 26fee7162..92b21afb5 100644--- a/packages/server/src/repowise/server/mcp_server/tool_context/enrichment.py+++ b/packages/server/src/repowise/server/mcp_server/tool_context/enrichment.py@@ -69,7 +69,14 @@ async def _resolve_call_graph(node = next((r for r in rows if r.file_path == file_hint), rows[0])if node is None or node.node_type != "symbol":- # For file targets, return empty with explanation — callers/callees is symbol-only+ # File targets get the rolled-up view instead of an empty block —+ # an empty callers list forced a second round-trip per orientation+ # pass for no reason; the graph has the answer at file granularity.+ if node is not None and node.node_type == "file" and want_callers:+ await _resolve_file_level_callers(session, repo_id, node, result_data, exclude_spec)+ if want_callees:+ result_data["callees"] = []+ returnif want_callers:result_data["callers"] = []if want_callees:@@ -144,6 +151,80 @@ async def _resolve_call_graph(result_data["callees"] = callees+async def _resolve_file_level_callers(+ session: AsyncSession,+ repo_id: str,+ node: GraphNode,+ result_data: dict[str, Any],+ exclude_spec: Any = None,+) -> None:+ """File-target callers: importing files + inbound symbol-call rollup.++ Two granularities merged per caller file: ``imports: true`` when the+ file imports this one, ``inbound_calls`` counting cross-file call edges+ into any symbol defined here.+ """+ from repowise.core.persistence.models import GraphEdge++ # Who imports this file (file-node inbound import edges).+ import_edges = await get_graph_edges_for_node(+ session, repo_id, node.node_id, direction="callers", edge_types=["imports"], limit=50+ )+ importer_ids = [e.source_node_id for e in import_edges if e.target_node_id == node.node_id]+ importer_nodes = await get_graph_nodes_by_ids(session, repo_id, importer_ids)+ # For file nodes the node_id IS the path; file_path may be unset.+ importer_files = {+ (n.file_path or n.node_id)+ for n in importer_nodes.values()+ if n is not None and (n.file_path or n.node_id)+ }++ # Cross-file calls into any symbol defined in this file, rolled up by+ # the calling file.+ target_file = node.file_path or node.node_id+ sym_res = await session.execute(+ select(GraphNode.node_id).where(+ GraphNode.repository_id == repo_id,+ GraphNode.node_type == "symbol",+ GraphNode.file_path == target_file,+ )+ )+ sym_ids = [row[0] for row in sym_res.all()]+ calls_by_file: dict[str, int] = {}+ if sym_ids:+ edge_res = await session.execute(+ select(GraphEdge.source_node_id, GraphEdge.confidence).where(+ GraphEdge.repository_id == repo_id,+ GraphEdge.target_node_id.in_(sym_ids),+ GraphEdge.edge_type == "calls",+ )+ )+ for src_id, confidence in edge_res.all():+ if (confidence or 0) < _MIN_CALL_CONFIDENCE:+ continue+ src_file = src_id.split("::")[0] if "::" in src_id else src_id+ if src_file == target_file:+ continue # intra-file calls are not "callers" of the file+ calls_by_file[src_file] = calls_by_file.get(src_file, 0) + 1++ entries: list[dict[str, Any]] = []+ for f in sorted(importer_files | set(calls_by_file)):+ entry: dict[str, Any] = {"file": f}+ if f in importer_files:+ entry["imports"] = True+ if calls_by_file.get(f):+ entry["inbound_calls"] = calls_by_file[f]+ entries.append(entry)+ entries = filter_dicts_by_key(entries, "file", exclude_spec)+ entries.sort(key=lambda x: -(x.get("inbound_calls") or 0))++ result_data["callers"] = entries[:20]+ result_data["_call_graph_note"] = (+ "File-level rollup: importing files plus inbound cross-file call "+ "counts. For symbol-precise callers pass 'file.py::Symbol'."+ )++async def _resolve_metrics(session: AsyncSession,repository: Repository,@@ -426,6 +507,10 @@ async def _resolve_skeleton("pct_of_full": round(result.pct_of_full, 1),"bodies_kept": list(result.bodies_kept),"text": result.text,+ # The skeleton is rendered from the live source file read above —+ # its text is fresh by construction. Part of the trust contract:+ # a verified response never needs a follow-up Read.+ "verified": True,}if result.mode == "raw":result_data["skeleton"]["note"] = (diff --git a/packages/server/src/repowise/server/mcp_server/tool_context/targets.py b/packages/server/src/repowise/server/mcp_server/tool_context/targets.pyindex f7b6f1416..129cd215e 100644--- a/packages/server/src/repowise/server/mcp_server/tool_context/targets.py+++ b/packages/server/src/repowise/server/mcp_server/tool_context/targets.py@@ -329,6 +329,24 @@ async def _resolve_one_target(result_data["target"] = targetresult_data["type"] = target_type+ # Tombstone redirect: the page documents a file deleted or renamed since+ # indexing. A "fresh" card here is an active trap — return the redirect+ # instead of the card.+ if page is not None and getattr(page, "freshness_status", "") == "tombstone":+ import json as _json_ts++ try:+ successors = _json_ts.loads(page.metadata_json or "{}").get("successor_paths") or []+ except (ValueError, TypeError):+ successors = []+ result_data["error"] = (+ f"'{target}' was deleted or renamed after indexing — this page is a tombstone."+ )+ if successors:+ result_data["successor_paths"] = successors+ result_data["hint"] = f"Content moved; call get_context on {successors[0]!r} instead."+ return result_data+want_skeleton = bool(include and "skeleton" in include)auto_skeleton = Falsediff --git a/packages/server/src/repowise/server/mcp_server/tool_dead_code.py b/packages/server/src/repowise/server/mcp_server/tool_dead_code.pyindex 5ea724e40..36441bf44 100644--- a/packages/server/src/repowise/server/mcp_server/tool_dead_code.py+++ b/packages/server/src/repowise/server/mcp_server/tool_dead_code.py@@ -1,4 +1,4 @@-"""MCP Tool 7: get_dead_code — tiered refactor plan for unused code."""+"""MCP Tool 7: get_dead_code — tiered refactor plan for unused code."""from __future__ import annotations@@ -46,55 +46,26 @@ async def get_dead_code(no_unreachable: bool = False,no_unused_exports: bool = False,) -> dict:- """Unused exports, unreachable files, zombie packages — what grep cannot tell you.-- Static reachability analysis the agent cannot derive from imports alone.- Returns findings tiered by confidence (high = zero refs; medium = likely- unused; low = check first) with per-directory and per-owner rollups so a- cleanup sprint can prioritise. In workspace mode, cross-repo consumer- detection lowers confidence on findings that other repos import.-- Use group_by="directory" for a directory-level overview, or- group_by="owner" to see who owns the most dead code. Use tier- to focus on a single confidence band.-- Scan scope flags (mirror the DeadCodeAnalyzer.analyze config):- - Use ``min_confidence=0.7`` for high-confidence cleanups — filters out- speculative findings and surfaces only code with zero references that- hasn't been touched in months. Ideal before a release or refactor sprint.- - Use ``include_internals=True`` for aggressive scans of private symbols- (functions/variables prefixed with _ or declared without exports). This- has a higher false-positive rate and is off by default; enable it when- doing a thorough dead-code purge of a stable, well-tested module.- - Use ``no_unreachable=True`` to skip file-level reachability checks and- focus only on symbol-level findings (unused exports/internals).- - Use ``no_unused_exports=True`` to skip public-export checks, e.g. when- you know the repo exposes a public API consumed externally.- - Use ``include_zombie_packages=False`` to suppress monorepo package- findings, useful in repos where cross-package imports are intentionally- absent during development.+ """Unused exports, unreachable files, zombie packages — tiered by confidence.++ Run before a cleanup sprint, not a targeted fix. Findings tier+ high/medium/low with per-directory and per-owner rollups; workspace+ mode lowers confidence on findings other repos import.Args:- repo: Repository path, name, or ID.- kind: Filter by kind (unreachable_file, unused_export, unused_internal, zombie_package).- min_confidence: Minimum confidence threshold (default 0.5). Use 0.7 for high-confidence- cleanups only.- safe_only: Only return deletion-ready findings — high confidence with no runtime-load- risk factors (config/bootstrap/database/environment/script files are excluded even- when persisted as safe). Default false.- limit: Maximum findings per tier (default 20). Clamped to 25 because larger- payloads exceed MCP transport token caps; paginate by tier/directory/owner- for deeper exploration.- tier: Focus on a single tier: "high" (>=0.8), "medium" (0.5-0.8), or "low" (<0.5).- directory: Filter findings to a specific directory prefix.- owner: Filter findings by primary owner name.- group_by: "directory" for per-directory rollup, "owner" for ownership hotspots.- include_internals: Include unused private/internal symbol findings (default false).- Enable for aggressive scans of private symbols.- include_zombie_packages: Include zombie-package findings for monorepo packages with- no external importers (default true).- no_unreachable: Suppress unreachable-file findings (default false).- no_unused_exports: Suppress unused-export findings (default false).+ repo: usually omitted.+ kind: unreachable_file | unused_export | unused_internal | zombie_package.+ min_confidence: floor, default 0.5 (0.7 = cleanup-ready only).+ safe_only: deletion-ready findings only (no runtime-load risk).+ limit: max findings per tier (clamped to 25).+ tier: "high" (>=0.8) | "medium" | "low".+ directory: path-prefix filter.+ owner: primary-owner filter.+ group_by: "directory" | "owner" rollup.+ include_internals: also scan private symbols (more false positives).+ include_zombie_packages: monorepo package findings (default true).+ no_unreachable: skip file-level reachability findings.+ no_unused_exports: skip public-export findings."""# MCP transport rejects payloads above ~25k tokens. A single serialized# finding is ~400 chars, so 3 tiers x ~25 findings keeps us under budgetdiff --git a/packages/server/src/repowise/server/mcp_server/tool_overview.py b/packages/server/src/repowise/server/mcp_server/tool_overview.pyindex cf11bd2f4..f8b62d5ca 100644--- a/packages/server/src/repowise/server/mcp_server/tool_overview.py+++ b/packages/server/src/repowise/server/mcp_server/tool_overview.py@@ -330,9 +330,7 @@ async def get_overview(repo: str | None = None) -> dict:GitMetadata.repository_id == repository.id,))- all_git = filter_rows_by_attr(- list(git_res.scalars().all()), "file_path", exclude_spec- )+ all_git = filter_rows_by_attr(list(git_res.scalars().all()), "file_path", exclude_spec)git_health: dict[str, Any] = {}if all_git:@@ -469,9 +467,7 @@ async def get_overview(repo: str | None = None) -> dict:if p.lower() not in generic_labels and p not in ("src",):dir_counts[p] += 1break- display_label = (- dir_counts.most_common(1)[0][0] if dir_counts else f"cluster_{cid}"- )+ display_label = dir_counts.most_common(1)[0][0] if dir_counts else f"cluster_{cid}"community_summary.append({@@ -712,6 +708,25 @@ async def get_overview(repo: str | None = None) -> dict:if ws_footer:result["workspace"] = ws_footer+ # Composition recipes live HERE (one overview call per session) so+ # the per-tool docstrings — paid on every fresh agent — stay terse.+ result["tool_guide"] = {+ "first_call": "get_answer for any how/where/why question; trust "+ "confidence=high directly (it is content-grounded).",+ "reading_code": "get_context skeleton (≈37% of a full Read) → "+ "get_symbol for bodies (verified: true = no re-read needed). "+ "Raw Read only for files marked mostly_full or unservable.",+ "recipes": [+ "get_answer low confidence → Read best_guesses[0].file",+ "get_context hotspot: true → get_risk before editing",+ "get_context decision_records → get_why(targets=[...]) for rationale",+ "PR review → get_risk(targets, changed_files) and read directive first",+ "search_codebase grep_hint present → prefer Grep for those identifiers",+ ],+ "reread_triggers": "Only re-read source on bounds: approximate, "+ "stale_warning in _meta, or search_method: bm25.",+ }+result["_meta"] = _build_meta(repository=repository)collector.attach(result)return resultdiff --git a/packages/server/src/repowise/server/mcp_server/tool_risk.py b/packages/server/src/repowise/server/mcp_server/tool_risk.pyindex bda0c0a8e..e4d07dc73 100644--- a/packages/server/src/repowise/server/mcp_server/tool_risk.py+++ b/packages/server/src/repowise/server/mcp_server/tool_risk.py@@ -452,34 +452,18 @@ async def get_risk(repo: str | None = None,changed_files: list[str] | None = None,) -> dict:- """What history says about touching these files — hotspot, churn, owners, blast radius.+ """What history says about touching these files — churn, owners, blast radius.- The only tool that fuses git temporal signals (churn percentile, trend,- bus factor) with graph topology (dependents, co-changes, impact surface)- and security findings into one decision-shaped payload. Consult before- editing any file in the 95th+ churn percentile or before merging a- multi-file PR.-- Per-file fields: ``hotspot_score``, ``trend``, ``risk_type``,- ``impact_surface`` (top 3), ``dependents_count``, ``co_change_partners``,- ``primary_owner``, ``bus_factor``, ``test_gap``, ``security_signals``.-- Pass ``changed_files`` for PR-blast-radius mode. The response then carries- a ``directive`` block — three short lists the caller can read in one- glance (``will_break``, ``missing_cochanges``, ``missing_tests``) — plus- the trimmed full ``pr_blast_radius`` dossier for deeper review. Global- hotspots are omitted in PR mode (irrelevant to the diff) and re-included- when ``changed_files`` is absent.-- In workspace mode, cross-repo consumers and API contract links bump the- dependents count and appear in ``cross_repo_impact``.-- Example: get_risk(["src/auth/service.py"], changed_files=["src/auth/service.py"])+ Fuses git temporal signals (churn percentile, trend, bus factor) with+ graph topology (dependents, co-changes, impact surface) and security+ findings. Consult before editing 95th+ churn-percentile files. Pass+ changed_files for PR mode: the response leads with a directive block+ (will_break, missing_cochanges, missing_tests) — read it first.Args:- targets: List of file paths to assess (standard per-file risk).- repo: Repository path, name, or ID.- changed_files: Optional list of files changed in a PR for blast-radius analysis.+ targets: file paths to assess.+ repo: usually omitted.+ changed_files: PR-changed files for blast-radius mode."""if repo == "all":return _unsupported_repo_all("get_risk")diff --git a/packages/server/src/repowise/server/mcp_server/tool_search.py b/packages/server/src/repowise/server/mcp_server/tool_search.pyindex d6341a468..f4d1262a0 100644--- a/packages/server/src/repowise/server/mcp_server/tool_search.py+++ b/packages/server/src/repowise/server/mcp_server/tool_search.py@@ -1,4 +1,4 @@-"""MCP Tool 5: search_codebase — semantic search over the wiki."""+"""MCP Tool 5: search_codebase — semantic search over the wiki."""from __future__ import annotations@@ -46,6 +46,19 @@ def _looks_like_exact_token(query: str) -> bool:return bool(_IDENT_QUERY_RE.match(stripped))+# Identifier-shaped tokens inside a longer query: snake_case of any casing+# (≥1 underscore, incl. _UPPER_SNAKE constants) or CamelCase (≥2 humps).+# Plain English words never match.+_IDENT_TOKEN_RE = re.compile(+ r"\b(?:_*[A-Za-z0-9]+_[A-Za-z0-9_]+|[A-Z][a-z][a-z0-9]*(?:[A-Z][a-z0-9]+)+)\b"+)+++def _embedded_identifiers(query: str) -> list[str]:+ """Identifier-shaped tokens carried inside a natural-language query."""+ return _IDENT_TOKEN_RE.findall(query)++# Decision records are short, dense title-statements; they win cosine# similarity against long file-page embeddings on any query containing# design nouns ("store", "SQLite", "cap", "prune") and crowd file pages@@ -72,9 +85,81 @@ def _downweight_decisions(output: list[dict], query: str) -> None:returnfor item in output:if item.get("page_type") == "decision_record" and item.get("relevance_score"):- item["relevance_score"] = round(- item["relevance_score"] * _DECISION_DOWNWEIGHT, 4- )+ item["relevance_score"] = round(item["relevance_score"] * _DECISION_DOWNWEIGHT, 4)+++def _sort_demoting_decisions(output: list[dict], query: str) -> None:+ """Sort by relevance, ranking decision records below every file-backed+ page on non-why queries.++ The multiplicative down-weight alone is washed out when decision scores+ dominate (short dense titles win cosine similarity by a margin > the+ 0.6 factor) — observed live as 5/5 irrelevant decisions for a plain+ implementation query. For non-why queries a decision record is never a+ better first Read than a file page, so the demotion is absolute; the+ down-weighted score still orders decisions among themselves.+ """+ why = _is_why_shaped(query)++ def key(item: dict) -> tuple:+ demoted = (not why) and item.get("page_type") == "decision_record"+ return (1 if demoted else 0, -(item.get("relevance_score") or 0.0))++ output.sort(key=key)+++async def _non_decision_fallback(ctx, query: str, fetch_limit: int) -> list[dict]:+ """Wider re-fetch keeping only non-decision pages.++ Guard for the window-saturation failure: when the entire over-fetched+ window is decision records, demotion has nothing to promote and a+ non-why query returns zero implementation pages. Fetch 4x wider, drop+ decisions, and let the caller merge the survivors.+ """+ results = []+ with contextlib.suppress(TimeoutError, Exception):+ results = await asyncio.wait_for(+ ctx.vector_store.search(query, limit=fetch_limit * 4),+ timeout=8.0,+ )+ if not results:+ with contextlib.suppress(Exception):+ results = await ctx.fts.search(query, limit=fetch_limit * 4)++ out = []+ for r in results:+ if r.page_type == "decision_record":+ continue+ if r.score < _MIN_RELEVANCE_SCORE:+ continue+ out.append(+ {+ "page_id": r.page_id,+ "title": r.title,+ "page_type": r.page_type,+ "snippet": r.snippet,+ "relevance_score": r.score,+ }+ )+ return out+++async def _rescue_all_decision_window(+ ctx, output: list[dict], query: str, fetch_limit: int+) -> list[dict]:+ """Merge non-decision pages into an all-decision result window.++ No-op unless the query is non-why AND every current hit is a decision+ record. Deduplicates by page_id.+ """+ if not output or _is_why_shaped(query):+ return output+ if not all(item.get("page_type") == "decision_record" for item in output):+ return output+ fallback = await _non_decision_fallback(ctx, query, fetch_limit)+ seen = {item["page_id"] for item in output}+ output.extend(item for item in fallback if item["page_id"] not in seen)+ return outputdef _fetch_limit_for(limit: int, kind: str | None) -> int:@@ -94,9 +179,22 @@ def _fetch_limit_for(limit: int, kind: str | None) -> int:# ``other`` and is dropped only when the caller asked for a specific kind._TEST_PATH_TOKENS = ("/test/", "/tests/", "/__tests__/", "test_", "_test.", ".spec.", ".test.")_CONFIG_PATH_TOKENS = (- "pyproject.toml", "package.json", "tsconfig", "setup.py", "setup.cfg",- "/.github/", "dockerfile", ".yml", ".yaml", ".toml", ".ini", ".cfg",- "lockfile", "package-lock", "uv.lock", "poetry.lock",+ "pyproject.toml",+ "package.json",+ "tsconfig",+ "setup.py",+ "setup.cfg",+ "/.github/",+ "dockerfile",+ ".yml",+ ".yaml",+ ".toml",+ ".ini",+ ".cfg",+ "lockfile",+ "package-lock",+ "uv.lock",+ "poetry.lock",)@@ -160,16 +258,19 @@ async def _search_single_repo(continueif r.score < _MIN_RELEVANCE_SCORE:continue- output.append({- "page_id": r.page_id,- "title": r.title,- "page_type": r.page_type,- "snippet": r.snippet,- "relevance_score": r.score,- })+ output.append(+ {+ "page_id": r.page_id,+ "title": r.title,+ "page_type": r.page_type,+ "snippet": r.snippet,+ "relevance_score": r.score,+ }+ )_downweight_decisions(output, query)- output.sort(key=lambda x: x.get("relevance_score", 0), reverse=True)+ output = await _rescue_all_decision_window(ctx, output, query, fetch_limit)+ _sort_demoting_decisions(output, query)# Attach target_path and drop excluded hits per repo (so federated search# honours each repo's own exclude_patterns) before aggregation. Runs on@@ -178,16 +279,22 @@ async def _search_single_repo(page_ids = [item["page_id"] for item in output]async with get_session(ctx.session_factory) as session:res = await session.execute(- select(Page.id, Page.target_path).where(Page.id.in_(page_ids))+ select(Page.id, Page.target_path, Page.freshness_status).where(+ Page.id.in_(page_ids)+ ))- page_info = {row[0]: row[1] for row in res.all()}+ rows = res.all()+ page_info = {row[0]: row[1] for row in rows}+ tombstoned = {row[0] for row in rows if row[2] == "tombstone"}+ output = [item for item in output if item["page_id"] not in tombstoned]for item in output:item["target_path"] = page_info.get(item["page_id"], "")output = filter_dicts_by_key(output, "target_path", _get_exclude_spec(ctx.path))if kind:output = [- item for item in output+ item+ for item in outputif _classify_hit_kind(item.get("target_path", ""), item.get("page_type", "")) == kind]@@ -233,25 +340,18 @@ async def search_codebase() -> dict:"""Find pages by concept — semantic search across the wiki.- The right tool when ``get_answer`` punted and you need candidate files for- a conceptual query ("authentication flow", "rate limiting", "where do we- handle webhooks"). For exact identifiers or token matches, use Grep — it- is faster and never drifts thematically. This tool will surface a Grep- hint when the query looks like a bare identifier.-- Each result carries ``search_method`` (``"embedding"`` or ``"bm25"``) so- the caller can tell whether semantic retrieval succeeded or fell back to- keyword scoring; BM25 hits warrant more verification than embedding hits.+ For conceptual queries ("rate limiting", "where do we handle webhooks")+ when you don't know the file. For exact identifiers use Grep —+ identifier-bearing queries get a grep_hint. Results carry search_method+ ("embedding", or "bm25" fallback: verify those). Decision records rank+ below file pages unless the query is why-shaped.Args:- query: natural-language search query.- limit: maximum number of results to return (default 5).- page_type: filter on page kind (``file_page``, ``module_page``,- ``symbol_spotlight``).- kind: filter by file role: ``"implementation"`` | ``"test"`` |- ``"config"`` | ``"doc"``. Path-prefix heuristic; trims the result- list rather than rewriting the query.- repo: repository alias, or ``"all"`` for workspace-wide search.+ query: natural-language query.+ limit: max results (default 5).+ page_type: file_page | module_page | symbol_spotlight.+ kind: implementation | test | config | doc.+ repo: alias, or "all" for workspace-wide."""grep_hint: str | None = Noneif _looks_like_exact_token(query):@@ -260,6 +360,13 @@ async def search_codebase("literal usages faster and without thematic drift. This tool ran ""the search anyway — verify before relying on the results.")+ elif idents := _embedded_identifiers(query):+ shown = ", ".join(repr(t) for t in idents[:3])+ grep_hint = (+ f"Query names identifier(s) {shown} — for their exact "+ "definition/usages, Grep is faster and never drifts "+ "thematically. Semantic results below are concept-level."+ )if repo == "all":# kind is filtered per-repo inside _search_single_repo, before each@@ -316,15 +423,28 @@ async def search_codebase()_downweight_decisions(output, query)+ rescued = await _rescue_all_decision_window(ctx, output, query, fetch_limit)+ if len(rescued) > len(output):+ # Fallback entries enter after the method was determined; they came+ # from the same backend.+ for item in rescued:+ item.setdefault("search_method", search_method)+ output = rescued# Batch-lookup page target paths for the kind filter + git freshness boostif output:page_ids = [item["page_id"] for item in output]async with get_session(ctx.session_factory) as session:res = await session.execute(- select(Page.id, Page.target_path).where(Page.id.in_(page_ids))+ select(Page.id, Page.target_path, Page.freshness_status).where(+ Page.id.in_(page_ids)+ ))- page_info = {row[0]: row[1] for row in res.all()}+ rows = res.all()+ page_info = {row[0]: row[1] for row in rows}+ tombstoned = {row[0] for row in rows if row[2] == "tombstone"}+ # Tombstoned pages document deleted/renamed files — never results.+ output = [item for item in output if item["page_id"] not in tombstoned]# Build git freshness map for result file paths — once for the# whole batch, not per item.@@ -358,14 +478,15 @@ async def search_codebase(recency = 0.0item["relevance_score"] = round(item["relevance_score"] * (1 + 0.2 * recency), 4)- # Re-sort by boosted relevance- output.sort(key=lambda x: x.get("relevance_score", 0), reverse=True)+ # Re-sort by boosted relevance, decisions hard-demoted on non-why queries+ _sort_demoting_decisions(output, query)# Kind filter runs on the over-fetched list BEFORE the limit cut so the# caller still gets up to ``limit`` results of the requested kind.if kind:output = [- item for item in output+ item+ for item in outputif _classify_hit_kind(item.get("target_path", ""), item.get("page_type", "")) == kind]diff --git a/packages/server/src/repowise/server/mcp_server/tool_symbol.py b/packages/server/src/repowise/server/mcp_server/tool_symbol.pyindex f3086e3e3..62ec536e8 100644--- a/packages/server/src/repowise/server/mcp_server/tool_symbol.py+++ b/packages/server/src/repowise/server/mcp_server/tool_symbol.py@@ -1,4 +1,4 @@-"""MCP Tool: get_symbol — byte-precise source retrieval for a single symbol.+"""MCP Tool: get_symbol — byte-precise source retrieval for a single symbol.This is the structural counterpart to get_context. Where get_context returnsfile-level narrative (summary, symbol list, importers), get_symbol returns@@ -11,8 +11,10 @@ Why a separate tool instead of "include source" on get_context?cached prompt prefix by ~10x when the agent only needs one symbol.* Predictability: response size is bounded by the symbol size, never thefile size — no surprise 50 KB payloads.- * No reparsing: the bytes come straight from disk via the persisted line- range. Tree-sitter never runs at retrieval time.+ * Verified bounds: the persisted line range is checked against the live+ file before serving (name-on-definition-line gate); on mismatch the+ file is re-parsed once, the bounds corrected and healed in the DB. A+ ``verified: true`` response never needs a follow-up Read.The tool is intentionally additive — get_context remains the right call for"explain this file" or "what's the relationship between A and B" questions.@@ -56,6 +58,7 @@ from repowise.server.mcp_server._helpers import ()from repowise.server.mcp_server._meta import build_meta as _build_metafrom repowise.server.mcp_server._meta import symbol_hint as _symbol_hint+from repowise.server.mcp_server._verify import check_symbol_bounds, heal_symbol_row_log = __import__("logging").getLogger("repowise.mcp.symbol")@@ -67,6 +70,21 @@ _MAX_SOURCE_LINES = 400# "{path}::{name}" symbol_id. Also tolerates a pasted whole marker._OMISSION_REF_RE = re.compile(r"^repowise#([0-9a-f]{12})$")+# Range-read dispatch: "path/to/file.py:140-180". A single colon followed by+# a numeric range never collides with "{path}::{name}" (double colon) or an+# omission ref. The escape hatch for everything not indexed as a symbol —+# imports, module docstrings, decorators between symbols — without falling+# back to a whole-file Read.+_RANGE_ID_RE = re.compile(r"^(?P<path>.+?):(?P<start>\d+)-(?P<end>\d+)$")++# Range reads are bounded tighter than symbol reads: the caller names exact+# lines, so a large range is a deliberate choice to cap.+_MAX_RANGE_LINES = 200++# Dead-end recovery: max grep matches returned when a symbol lookup misses+# but the file exists on disk.+_MAX_FALLBACK_MATCHES = 8+def _extract_omission_ref(symbol_id: str) -> str | None:"""Return the 12-hex omission ref when *symbol_id* is ref-shaped, else None."""@@ -144,6 +162,97 @@ def _resolve_omission_ref(return response+async def _resolve_range_read(+ symbol_id: str, path: str, start: int, end: int, context_lines: int, ctx: Any, t0: float+) -> dict:+ """Serve a live, bounded line-range read: "path/to/file.py:140-180".++ Always ``verified: true`` — the bytes come straight from the live file+ at the requested lines. Bounded to _MAX_RANGE_LINES; the full-file token+ count is declared as the counterfactual (the Read this call replaced).+ """+ repository = None+ async with get_session(ctx.session_factory) as session:+ repository = await _get_repo(session)++ def _err(msg: str) -> dict:+ return {+ "symbol_id": symbol_id,+ "error": msg,+ "_meta": _build_meta(+ timing_ms=(time.perf_counter() - t0) * 1000, repository=repository+ ),+ }++ if is_excluded(path, _get_exclude_spec(ctx.path)):+ return _err(f"'{path}' is excluded from indexing.")+ if not ctx.path:+ return _err("MCP server has no repo path configured")++ text = _read_file_text(Path(str(ctx.path)), path)+ if text is None:+ return _err(f"File could not be read: {path!r}")++ from repowise.core.distill.budget import estimate_tokens++ full_tokens = estimate_tokens(text)++ if end < start:+ start, end = end, start+ requested_truncated = (end - start + 1) > _MAX_RANGE_LINES+ if requested_truncated:+ end = start + _MAX_RANGE_LINES - 1++ # Cap the served span at _MAX_RANGE_LINES *including* context expansion —+ # the docstring promises ≤200 lines, so context_lines must not push past+ # it. Truncated reflects either an oversized request or a context-clipped+ # span.+ source, s, e, total = _slice_text(text, start, end, context_lines, max_lines=_MAX_RANGE_LINES)+ range_truncated = requested_truncated or (e - s + 1) >= _MAX_RANGE_LINES++ response = {+ "symbol_id": symbol_id,+ "file": path,+ "kind": "range",+ "start_line": s,+ "end_line": e,+ "total_lines": total,+ "source": source,+ "truncated": range_truncated,+ "verified": True,+ "_meta": _build_meta(timing_ms=(time.perf_counter() - t0) * 1000, repository=repository),+ }+ from repowise.server.mcp_server._savings import declare_replaced++ declare_replaced(response, full_tokens)+ return response+++def _live_grep_fallback(repo_root: Path, file_path: str, name: str) -> list[dict]:+ """Find ``name`` in the live file when the symbol index misses.++ Turns a dead-end call (pure cost) into an answer: constants, imports,+ aliases, and decorators live between indexed symbols, and the line that+ defines them is usually all the agent needs. ±2 lines of context per+ match, capped at _MAX_FALLBACK_MATCHES.+ """+ text = _read_file_text(repo_root, file_path)+ if text is None:+ return []+ bare = _bare_name(name)+ if not bare:+ return []+ lines = text.splitlines()+ matches: list[dict] = []+ for i, line in enumerate(lines, 1):+ if bare in line:+ lo, hi = max(1, i - 2), min(len(lines), i + 2)+ matches.append({"line": i, "context": "\n".join(lines[lo - 1 : hi])})+ if len(matches) >= _MAX_FALLBACK_MATCHES:+ break+ return matches++def _parse_symbol_id(symbol_id: str) -> tuple[str | None, str | None]:"""Split a "{path}::{name}" id. Either side may be None if missing.@@ -224,9 +333,7 @@ def _bare_name(name: str) -> str:return tail-def _pick_canonical(- rows: list[WikiSymbol], queried_file_path: str | None-) -> WikiSymbol | None:+def _pick_canonical(rows: list[WikiSymbol], queried_file_path: str | None) -> WikiSymbol | None:"""Deterministically select one row from a candidate list.Priority:@@ -243,7 +350,7 @@ def _pick_canonical(rows = matching# Deterministic: lowest id wins. (No confidence column today; leaving# room to add one without changing the fallback.)- rows_sorted = sorted(rows, key=lambda r: (r.id or ""))+ rows_sorted = sorted(rows, key=lambda r: r.id or "")if len(rows) > 1:_log.warning("get_symbol: %d duplicate rows for lookup (file=%s); picked id=%s",@@ -254,9 +361,7 @@ def _pick_canonical(return rows_sorted[0]-async def _resolve_symbol(- session, repo_id: str, symbol_id: str-) -> WikiSymbol | None:+async def _resolve_symbol(session, repo_id: str, symbol_id: str) -> WikiSymbol | None:"""Look up a symbol by id, qualified_name, or bare name. None if absent.Language-agnostic: the qualified-name portion of the symbol_id is@@ -324,19 +429,8 @@ async def _resolve_symbol(return None-def _slice_source(- repo_path: Path, file_path: str, start_line: int, end_line: int, context_lines: int-) -> tuple[str, int, int, int | None, int]:- """Read the file and return (source, actual_start, actual_end, total_lines, full_tokens).-- ``full_tokens`` is the token cost of the *whole* file — the counterfactual- a single-symbol slice replaces (the agent would have Read the file to find- it). Returns ("", start, end, None, 0) on read failure. Lines are 1-indexed- in the inputs and outputs to match WikiSymbol storage. Honors- _MAX_SOURCE_LINES.- """- from repowise.core.distill.budget import estimate_tokens-+def _read_file_text(repo_path: Path, file_path: str) -> str | None:+ """Read a repo file's live text, or None when unreadable/outside the root."""abs_path = (repo_path / file_path).resolve()# Defense in depth: never read outside the repo root, even if the# WikiSymbol.file_path was somehow tampered with.@@ -344,33 +438,42 @@ def _slice_source(abs_path.relative_to(repo_path.resolve())except ValueError:_log.warning("get_symbol path escape attempt: %s", file_path)- return "", start_line, end_line, None, 0+ return Nonetry:- text = abs_path.read_text(encoding="utf-8", errors="replace")+ return abs_path.read_text(encoding="utf-8", errors="replace")except OSError as exc:_log.warning("get_symbol read failed for %s: %s", abs_path, exc)- return "", start_line, end_line, None, 0+ return None- full_tokens = estimate_tokens(text)++def _slice_text(+ text: str,+ start_line: int,+ end_line: int,+ context_lines: int,+ max_lines: int = _MAX_SOURCE_LINES,+) -> tuple[str, int, int, int]:+ """Slice ``text`` to (source, actual_start, actual_end, total_lines).++ Lines are 1-indexed inclusive to match WikiSymbol storage; the range is+ expanded by ``context_lines`` on both sides and capped at ``max_lines``+ (truncating from the tail — the head carries the signature, which is what+ the agent needs to ground itself). The cap is applied AFTER context+ expansion so the returned span never exceeds it.+ """lines = text.splitlines()total = len(lines)- # 1-indexed inclusive range, then expand by context_lines on both sides.s = max(1, min(start_line, total))e = max(s, min(end_line, total))if context_lines > 0:s = max(1, s - context_lines)e = min(total, e + context_lines)- span = e - s + 1- if span > _MAX_SOURCE_LINES:- # Truncate from the tail; the head usually has the signature- # which is what the agent needs to ground itself.- e = s + _MAX_SOURCE_LINES - 1- span = _MAX_SOURCE_LINES+ if (e - s + 1) > max_lines:+ e = s + max_lines - 1- sliced = "\n".join(lines[s - 1 : e])- return sliced, s, e, total, full_tokens+ return "\n".join(lines[s - 1 : e]), s, e, total@mcp.tool()@@ -380,25 +483,22 @@ async def get_symbol(repo: str | None = None,query: str | None = None,) -> dict:- """Read one function/class with exact line bounds — cheaper and safer than Read+math.+ """Read one function/class/constant with live-verified line bounds.- The only tool that returns the raw source bytes of a single indexed symbol- without the agent having to compute offsets or guess at file structure.- Bounded to ~400 lines (hard cap) so a misconfigured row can never blow up- the context window. Pass the canonical ``"path/to/file.py::Name"`` that- appears in ``get_context``'s symbol list. Also resolves omission refs:- pass ``"repowise#<12-hex>"`` from a ``[repowise#...]`` truncation marker- to retrieve the omitted content (``query`` filters it to matching lines).-- Returns {file, name, kind, signature, start_line, end_line, source,- truncated}. On miss returns {error: "Symbol not found …"}.+ Raw source of one indexed symbol, bounded (~400 lines) — cheaper than+ Read+offset math. ``verified: true`` = bounds checked (or corrected)+ against the live file: no follow-up Read needed. ``bounds:+ "approximate"`` = the symbol moved and re-location failed. Also serves+ live range reads ("path.py:140-180", ≤200 lines, always verified) and+ omission refs ("repowise#<12-hex>"). Index misses grep the live file+ and return fallback_lines instead of a dead end.Args:- symbol_id: "path/to/file.py::SymbolName" (canonical id from get_context),- or "repowise#<12-hex>" from an omission marker.- context_lines: extra source lines before/after (0-50, default 0).+ symbol_id: "path/to/file.py::Name" (from get_context),+ "path/to/file.py:140-180" for a live range, or an omission ref.+ context_lines: extra lines before/after (0-50).repo: usually omitted.- query: omission refs only — regex (or substring) returning matching lines.+ query: omission refs only — regex/substring filter on lines."""if repo == "all":return _unsupported_repo_all("get_symbol")@@ -416,6 +516,20 @@ async def get_symbol(if omission_ref is not None:return _resolve_omission_ref(symbol_id, omission_ref, query, ctx.path, t0)+ # Range read: "path/to/file.py:140-180" (single colon + numeric range —+ # never collides with "{path}::{name}").+ range_match = _RANGE_ID_RE.match(symbol_id.strip())+ if range_match and "::" not in symbol_id:+ return await _resolve_range_read(+ symbol_id,+ range_match.group("path"),+ int(range_match.group("start")),+ int(range_match.group("end")),+ max(0, min(50, context_lines)),+ ctx,+ t0,+ )+repository = Noneif context_lines < 0 or context_lines > 50:# Bound context_lines to a sane range — runaway values would@@ -426,7 +540,33 @@ async def get_symbol(repository = await _get_repo(session)row = await _resolve_symbol(session, repository.id, symbol_id)- if row is None or is_excluded(getattr(row, "file_path", None), _get_exclude_spec(ctx.path)):+ exclude_spec = _get_exclude_spec(ctx.path)+ if row is None or is_excluded(getattr(row, "file_path", None), exclude_spec):+ # Dead-end recovery: constants/imports/aliases between indexed+ # symbols miss the index but live in the file — grep the live file+ # for the name and serve the matching lines instead of a pure error.+ if row is None and ctx.path:+ file_part, name_part = _parse_symbol_id(symbol_id)+ if file_part and name_part and not is_excluded(file_part, exclude_spec):+ matches = _live_grep_fallback(Path(str(ctx.path)), file_part, name_part)+ if matches:+ return {+ "symbol_id": symbol_id,+ "file": file_part,+ "resolution": "live_grep",+ "fallback_lines": matches,+ "verified": True,+ "note": (+ "Not an indexed symbol, but the name matches these "+ "live-file lines (likely a constant, import, or "+ "alias). For surrounding source use a range read: "+ f'"{file_part}:<start>-<end>".'+ ),+ "_meta": _build_meta(+ timing_ms=(time.perf_counter() - t0) * 1000,+ repository=repository,+ ),+ }return {"symbol_id": symbol_id,"error": (@@ -451,11 +591,9 @@ async def get_symbol(}repo_root = Path(str(ctx.path))- source, start, end, _total, full_tokens = _slice_source(- repo_root, row.file_path, row.start_line, row.end_line, context_lines- )+ text = _read_file_text(repo_root, row.file_path)- if not source:+ if text is None:return {"symbol_id": symbol_id,"file": row.file_path,@@ -472,8 +610,22 @@ async def get_symbol(),}+ from repowise.core.distill.budget import estimate_tokens++ full_tokens = estimate_tokens(text)++ # Trust contract: verify the stored bounds against the live file before+ # serving a single byte. Stale bounds get corrected via a one-file+ # re-parse (and healed in the DB); un-relocatable symbols are served as+ # the indexed guess, explicitly tagged approximate.+ check = check_symbol_bounds(row, text)+ if check.corrected:+ await heal_symbol_row(ctx.session_factory, row, check.start_line, check.end_line)++ source, start, end, _total = _slice_text(text, check.start_line, check.end_line, context_lines)+truncated = (end - start + 1) >= _MAX_SOURCE_LINES and (- row.end_line - row.start_line + 1 + 2 * context_lines+ check.end_line - check.start_line + 1 + 2 * context_lines) > _MAX_SOURCE_LINESresponse = {@@ -486,16 +638,26 @@ async def get_symbol("language": row.language,"start_line": start,"end_line": end,- "symbol_start_line": row.start_line,- "symbol_end_line": row.end_line,+ "symbol_start_line": check.start_line,+ "symbol_end_line": check.end_line,"source": source,"truncated": truncated,+ "verified": check.verified,"_meta": _build_meta(timing_ms=(time.perf_counter() - t0) * 1000,- hint=_symbol_hint(row.symbol_id, row.end_line, row.start_line),+ hint=_symbol_hint(row.symbol_id, check.end_line, check.start_line),repository=repository,),}+ if check.approximate:+ response["bounds"] = "approximate"+ response["note"] = (+ "The live file no longer contains this symbol at its indexed "+ "location and it could not be re-located by name — it may have "+ "been renamed or removed since indexing. The served slice is "+ "the indexed line range from the current file contents; verify "+ "before citing."+ )# Declare the exact counterfactual: serving one symbol replaced Reading the# whole file. The savings instrumentation prefers this over its estimator.from repowise.server.mcp_server._savings import declare_replaceddiff --git a/packages/server/src/repowise/server/mcp_server/tool_why.py b/packages/server/src/repowise/server/mcp_server/tool_why.pyindex 49850e5af..7dc9bd49e 100644--- a/packages/server/src/repowise/server/mcp_server/tool_why.py+++ b/packages/server/src/repowise/server/mcp_server/tool_why.py@@ -38,29 +38,18 @@ async def get_why(targets: list[str] | None = None,repo: str | None = None,) -> dict:- """Why this code looks the way it does — decision archaeology git log cannot answer.+ """Why this code is shaped this way — decision records + evidence commits.- The only tool that surfaces architectural decision records, their status- (active / proposed / deprecated / superseded), and the commits that are- evidence for them. ``git log`` tells you *what* changed; this tells you- *why we chose this design* — call it before any architectural change,- refactor of an owned module, or pattern divergence in a community.-- Four modes:- 1. ``get_why("why is auth using JWT?")`` — keyword + semantic decision search.- 2. ``get_why("src/auth/service.py")`` — decisions governing the file plus- origin story and an alignment score (does this file follow its own ADRs?).- 3. ``get_why("why was caching added?", targets=["src/auth/cache.py"])`` —- target-anchored search; decisions touching the targets get boosted.- 4. ``get_why()`` — health dashboard (stale, proposed, ungoverned hotspots).-- When no decisions exist for a path, falls back to git archaeology- (significant commits + cross-file references) so the call is never empty.+ Call before refactors or pattern divergences. Query modes: a question+ ("why is auth using JWT?"), a file path (governing decisions + origin+ story + alignment score), a question anchored to targets, or no query+ (decision health dashboard). Falls back to git archaeology when no+ decisions exist for a path — never empty.Args:- query: Natural language question, file/module path, or omit for health dashboard.- targets: Optional file paths to anchor the search.- repo: Repository path, name, or ID.+ query: question, file/module path, or omit for the dashboard.+ targets: optional file paths to anchor the search.+ repo: usually omitted."""# --- repo="all": search decisions across ALL repos ---if repo == "all":diff --git a/tests/unit/ingestion/parser/test_commonjs_require.py b/tests/unit/ingestion/parser/test_commonjs_require.pyindex a520d4a64..cd9bcf68d 100644--- a/tests/unit/ingestion/parser/test_commonjs_require.py+++ b/tests/unit/ingestion/parser/test_commonjs_require.py@@ -110,3 +110,20 @@ def test_member_pick_require_is_extracted(parser: ASTParser) -> None:# pattern never matched it.result = _parse(parser, "var normalizeType = require('./utils').normalizeType;\n")assert any(i.module_path == "./utils" for i in result.imports)+++def test_top_level_js_constants_extracted_but_requires_are_not(parser: ASTParser) -> None:+ result = _parse(+ parser,+ "const svc = require('./svc');\n"+ "const TIMEOUT_MS = 5000;\n"+ "let counter = 0;\n"+ "function h() { const local = 1; return local; }\n",+ )+ by_name = {s.name: s for s in result.symbols}+ assert by_name["TIMEOUT_MS"].kind == "constant"+ assert by_name["TIMEOUT_MS"].signature == "TIMEOUT_MS = 5000"+ assert by_name["counter"].kind == "variable"+ # require() declarators are imports, not symbols+ assert "svc" not in by_name+ assert "local" not in by_namediff --git a/tests/unit/ingestion/parser/test_python.py b/tests/unit/ingestion/parser/test_python.pyindex 22fb3b58d..12406a468 100644--- a/tests/unit/ingestion/parser/test_python.py+++ b/tests/unit/ingestion/parser/test_python.py@@ -232,3 +232,83 @@ class TestPythonParser:# Public top-level symbols should be in exportsassert "add" in result.exportsassert "Calculator" in result.exports+++PYTHON_CONSTANTS_SOURCE = b'''"""Module with constants."""++import os++_DEFAULT_CO_CHANGE_MIN_COUNT = 2+MAX_RETRIES: int = 5+app = create_app()+_TABLE = {+ "a": 1,+}+++def f(x):+ local_var = 3+ return x+++class C:+ class_attr = 7++ def m(self):+ inner = 1+ return inner+'''+++class TestPythonModuleConstants:+ """Module-level assignments are indexed as constant/variable symbols."""++ def _symbols(self, parser: ASTParser):+ fi = _make_file_info("pkg/consts.py", "python")+ return parser.parse_file(fi, PYTHON_CONSTANTS_SOURCE).symbols++ def test_screaming_case_assignment_is_constant(self, parser: ASTParser) -> None:+ syms = self._symbols(parser)+ const = next(s for s in syms if s.name == "_DEFAULT_CO_CHANGE_MIN_COUNT")+ assert const.kind == "constant"+ assert const.signature == "_DEFAULT_CO_CHANGE_MIN_COUNT = 2"++ def test_typed_assignment_keeps_annotation_in_signature(self, parser: ASTParser) -> None:+ syms = self._symbols(parser)+ const = next(s for s in syms if s.name == "MAX_RETRIES")+ assert const.kind == "constant"+ assert const.signature == "MAX_RETRIES: int = 5"++ def test_lowercase_assignment_is_variable(self, parser: ASTParser) -> None:+ syms = self._symbols(parser)+ var = next(s for s in syms if s.name == "app")+ assert var.kind == "variable"+ assert var.signature == "app = create_app()"++ def test_multiline_value_signature_is_first_line(self, parser: ASTParser) -> None:+ syms = self._symbols(parser)+ table = next(s for s in syms if s.name == "_TABLE")+ assert table.kind == "constant"+ assert table.signature == "_TABLE = {"+ assert table.end_line > table.start_line++ def test_function_local_assignment_not_extracted(self, parser: ASTParser) -> None:+ syms = self._symbols(parser)+ assert not any(s.name == "local_var" for s in syms)+ assert not any(s.name == "inner" for s in syms)++ def test_class_attribute_not_extracted(self, parser: ASTParser) -> None:+ syms = self._symbols(parser)+ assert not any(s.name == "class_attr" for s in syms)++ def test_no_letter_names_are_variables_not_constants(self, parser: ASTParser) -> None:+ # ``__all__`` and ``_`` have no cased letters; ``name == name.upper()``+ # would mislabel them constants. ``str.isupper()`` correctly yields+ # variable.+ src = b'__all__ = ["a"]\n_ = compute()\nDunder = 1\n'+ fi = _make_file_info("pkg/dunder.py", "python")+ syms = parser.parse_file(fi, src).symbols+ assert next(s for s in syms if s.name == "__all__").kind == "variable"+ assert next(s for s in syms if s.name == "_").kind == "variable"+ # Mixed-case still resolves to variable (only SCREAMING_CASE is const).+ assert next(s for s in syms if s.name == "Dunder").kind == "variable"diff --git a/tests/unit/ingestion/parser/test_typescript.py b/tests/unit/ingestion/parser/test_typescript.pyindex c62955d74..3a7eb8208 100644--- a/tests/unit/ingestion/parser/test_typescript.py+++ b/tests/unit/ingestion/parser/test_typescript.py@@ -219,3 +219,56 @@ def test_cts_file_uses_typescript_parser(parser: ASTParser) -> None:fi = _make_file_info("src/module.cts", "typescript")parsed = parser.parse_file(fi, b"export function load(): number { return 1; }\n")assert any(s.name == "load" for s in parsed.symbols)+++class TestTypeScriptModuleConstants:+ """Top-level const/let with literal values are indexed as constants."""++ TS_CONST_SOURCE = b"""+import { x } from "./x";+export const MAX_ITEMS = 100;+const apiBase = "https://api.example.com";+export const CONFIG = {+ retries: 3,+};+export const handler = () => {+ const inner = 1;+ return inner;+};+function g() {+ const localConst = 2;+ return localConst;+}+"""++ def _symbols(self, parser: ASTParser):+ fi = _make_file_info("pkg/consts.ts", "typescript")+ return parser.parse_file(fi, self.TS_CONST_SOURCE).symbols++ def test_exported_screaming_const_is_constant(self, parser: ASTParser) -> None:+ syms = self._symbols(parser)+ const = next(s for s in syms if s.name == "MAX_ITEMS")+ assert const.kind == "constant"+ assert const.signature == "MAX_ITEMS = 100"++ def test_camel_case_const_is_variable(self, parser: ASTParser) -> None:+ syms = self._symbols(parser)+ var = next(s for s in syms if s.name == "apiBase")+ assert var.kind == "variable"++ def test_object_const_signature_is_first_line(self, parser: ASTParser) -> None:+ syms = self._symbols(parser)+ config = next(s for s in syms if s.name == "CONFIG")+ assert config.kind == "constant"+ assert config.signature == "CONFIG = {"++ def test_arrow_function_const_stays_function(self, parser: ASTParser) -> None:+ syms = self._symbols(parser)+ handler = next(s for s in syms if s.name == "handler")+ assert handler.kind == "function"++ def test_function_local_const_not_extracted(self, parser: ASTParser) -> None:+ syms = self._symbols(parser)+ names = {s.name for s in syms}+ assert "localConst" not in names+ assert "inner" not in namesdiff --git a/tests/unit/server/mcp/test_answer_cache.py b/tests/unit/server/mcp/test_answer_cache.pynew file mode 100644index 000000000..f95c1acb1--- /dev/null+++ b/tests/unit/server/mcp/test_answer_cache.py@@ -0,0 +1,193 @@+"""Answer-cache lifecycle: upsert on re-synthesis, commit/TTL invalidation.++Regression coverage for the silent-failure mode where the cache write was a+plain INSERT under ``suppress(Exception)``: every bypass-and-resynthesize+round (hedged rows, schema bumps) violated ``uq_answer_cache_q`` and failed+silently, so a bad cached row was permanent. The write is now a+delete-then-insert upsert, and reads invalidate on indexed-commit change or+hard TTL.+"""++from __future__ import annotations++import json as _json+from datetime import UTC, datetime, timedelta+from types import SimpleNamespace++import pytest+from sqlalchemy import select++from repowise.core.persistence.models import AnswerCache, Repository++QUESTION = "how does the auth service work"++# Top score >= 3.0 with an absolute gap >= 0.5 → dominant → synthesis runs.+_HITS = [+ {"page_id": "file_page:src/auth/service.py", "score": 5.0},+ {"page_id": "file_page:src/auth/middleware.py", "score": 4.0},+]+++def _patch_retrieval(monkeypatch, answer_mod):+ async def _fake_retrieve(question, ctx):+ return [dict(h) for h in _HITS]++ async def _fake_hydrate(hits, ctx, *, scope=None):+ for h in hits:+ h["target_path"] = h["page_id"].removeprefix("file_page:")+ h["title"] = h["target_path"]+ h["summary"] = ""+ h["snippet"] = ""+ h["page_type"] = "file_page"+ return hits++ monkeypatch.setattr(answer_mod, "_hybrid_retrieve", _fake_retrieve)+ monkeypatch.setattr(answer_mod, "_hydrate_hits", _fake_hydrate)+++class _Provider:+ provider_name = "mock"+ model_name = "mock-1"++ def __init__(self, content: str) -> None:+ self.content = content+ self.calls = 0++ async def generate(self, **kwargs):+ self.calls += 1+ return SimpleNamespace(content=self.content)+++def _patch_provider(monkeypatch, answer_mod, provider: _Provider) -> None:+ monkeypatch.setattr(answer_mod, "_resolve_provider_for_answer", lambda _p: provider)+++async def _cache_rows(factory) -> list[AnswerCache]:+ from repowise.core.persistence.database import get_session++ async with get_session(factory) as session:+ res = await session.execute(select(AnswerCache))+ return list(res.scalars().all())+++async def test_hedged_row_is_upgraded_on_resynthesis(setup_mcp, factory, monkeypatch):+ """Hedged cached answer → bypass → re-synthesis → row UPGRADED, not orphaned."""+ import repowise.server.mcp_server.tool_answer.answer as answer_mod+ from repowise.server.mcp_server import get_answer++ _patch_retrieval(monkeypatch, answer_mod)++ hedged = _Provider("The provided excerpts do not contain the implementation details.")+ _patch_provider(monkeypatch, answer_mod, hedged)+ first = await get_answer(QUESTION)+ assert first["confidence"] == "low"++ rows = await _cache_rows(factory)+ assert len(rows) == 1+ assert "do not contain" in _json.loads(rows[0].payload_json)["answer"]++ direct = _Provider("Auth flows through src/auth/service.py via AuthService.check().")+ _patch_provider(monkeypatch, answer_mod, direct)+ second = await get_answer(QUESTION)+ assert direct.calls == 1, "hedged cache entry must be bypassed, not returned"+ assert "AuthService.check" in second["answer"]++ rows = await _cache_rows(factory)+ assert len(rows) == 1, "upsert must replace the hedged row, not duplicate or fail"+ upgraded = _json.loads(rows[0].payload_json)+ assert "AuthService.check" in upgraded["answer"], "row must carry the upgraded answer"++ # Third call: the upgraded row is a normal cache hit — no synthesis.+ third = await get_answer(QUESTION)+ assert direct.calls == 1, "upgraded row must serve from cache"+ assert third["_meta"].get("cached") is True+ assert "_indexed_commit" not in third+++async def test_cache_bypassed_when_indexed_commit_changes(setup_mcp, factory, session, monkeypatch):+ """A row stamped at commit A is bypassed once the repo is indexed at B."""+ import repowise.server.mcp_server.tool_answer.answer as answer_mod+ from repowise.server.mcp_server import get_answer++ _patch_retrieval(monkeypatch, answer_mod)++ repo = (await session.execute(select(Repository))).scalars().first()+ repo.head_commit = "a" * 40+ await session.commit()++ v1 = _Provider("Answer synthesised at commit A (src/auth/service.py).")+ _patch_provider(monkeypatch, answer_mod, v1)+ await get_answer(QUESTION)+ assert v1.calls == 1++ # Same commit → cache hit, no new synthesis.+ await get_answer(QUESTION)+ assert v1.calls == 1++ repo.head_commit = "b" * 40+ await session.commit()++ v2 = _Provider("Answer synthesised at commit B (src/auth/service.py).")+ _patch_provider(monkeypatch, answer_mod, v2)+ result = await get_answer(QUESTION)+ assert v2.calls == 1, "commit change must bypass the cached row"+ assert "commit B" in result["answer"]++ rows = await _cache_rows(factory)+ assert len(rows) == 1+ assert _json.loads(rows[0].payload_json)["_indexed_commit"] == "b" * 40+++async def test_cache_row_past_ttl_is_bypassed(setup_mcp, factory, session, monkeypatch):+ """Rows older than the hard TTL re-synthesise even without commit metadata."""+ import repowise.server.mcp_server.tool_answer.answer as answer_mod+ from repowise.server.mcp_server import get_answer++ _patch_retrieval(monkeypatch, answer_mod)++ v1 = _Provider("Original answer (src/auth/service.py).")+ _patch_provider(monkeypatch, answer_mod, v1)+ await get_answer(QUESTION)++ rows = await _cache_rows(factory)+ assert len(rows) == 1+ from repowise.core.persistence.database import get_session++ async with get_session(factory) as s:+ row = (await s.execute(select(AnswerCache))).scalars().one()+ row.created_at = datetime.now(UTC) - timedelta(days=30)+ await s.commit()++ v2 = _Provider("Fresh answer (src/auth/service.py).")+ _patch_provider(monkeypatch, answer_mod, v2)+ result = await get_answer(QUESTION)+ assert v2.calls == 1, "expired row must be bypassed"+ assert "Fresh answer" in result["answer"]+++async def test_cache_write_failure_logs_instead_of_silencing(setup_mcp, monkeypatch, caplog):+ """A failing cache write must not block the response — and must be logged."""+ import repowise.server.mcp_server.tool_answer.answer as answer_mod+ from repowise.server.mcp_server import get_answer++ _patch_retrieval(monkeypatch, answer_mod)+ _patch_provider(monkeypatch, answer_mod, _Provider("Answer text (src/auth/service.py)."))++ real_dumps = answer_mod._json.dumps++ def _boom(obj, *a, **k):+ if isinstance(obj, dict) and "_schema_version" in obj:+ raise RuntimeError("simulated serialization failure")+ return real_dumps(obj, *a, **k)++ monkeypatch.setattr(answer_mod._json, "dumps", _boom)++ with caplog.at_level("WARNING", logger="repowise.mcp.answer"):+ result = await get_answer(QUESTION)++ assert result["answer"], "response must survive a cache-write failure"+ assert any("cache write failed" in r.message for r in caplog.records)diff --git a/tests/unit/server/mcp/test_answer_calibration.py b/tests/unit/server/mcp/test_answer_calibration.pynew file mode 100644index 000000000..e36341622--- /dev/null+++ b/tests/unit/server/mcp/test_answer_calibration.py@@ -0,0 +1,281 @@+"""Confidence calibration gates for get_answer.++Covers the three A-series gates that ground confidence in answer *content*+rather than retrieval scores alone:++ * expanded hedge markers ("do not include", "can't enumerate", …)+ * value-grounding gate — numbers asserted on value-shaped questions must+ appear in the retrieved material, else confidence caps at low+ * citation-source gate — high confidence requires ≥1 cited page that+ contributed actual source (hydrated symbols), not just summaries+"""++from __future__ import annotations++from types import SimpleNamespace++import pytest++from repowise.server.mcp_server.tool_answer.confidence import (+ _answer_is_hedged,+ _is_value_question,+ _ungrounded_numbers,+)++# ---------------------------------------------------------------------------+# Pure-predicate unit tests+# ---------------------------------------------------------------------------+++class TestHedgeMarkers:+ def test_do_not_include_detected(self) -> None:+ assert _answer_is_hedged("The provided wiki excerpts do not include the source body.")++ def test_cannot_enumerate_detected(self) -> None:+ assert _answer_is_hedged("I can't enumerate the exact callers from the excerpts.")++ def test_unable_to_determine_detected(self) -> None:+ assert _answer_is_hedged("The exact default is unable to determine from this material.")++ def test_marker_late_in_answer_detected(self) -> None:+ long_preamble = "The module handles ingestion. " * 40+ assert _answer_is_hedged(long_preamble + "However, the excerpts do not include the value.")++ def test_direct_answer_not_hedged(self) -> None:+ assert not _answer_is_hedged("The default is 2, set in git_indexer/_constants.py.")+++class TestValueQuestionShape:+ def test_default_question_is_value_shaped(self) -> None:+ assert _is_value_question("What is the default value of _MIN_COUNT?")++ def test_threshold_question_is_value_shaped(self) -> None:+ assert _is_value_question("what threshold gates the dominance ratio")++ def test_how_many_is_value_shaped(self) -> None:+ assert _is_value_question("How many retrieval hits are returned?")++ def test_mechanism_question_is_not(self) -> None:+ assert not _is_value_question("How does the ingestion pipeline parse imports?")+++class TestUngroundedNumbers:+ HITS = [+ {+ "title": "constants",+ "summary": "Co-change tuning constants.",+ "snippet": "",+ "symbols": [+ {+ "name": "_DEFAULT_CO_CHANGE_MIN_COUNT",+ "signature": "_DEFAULT_CO_CHANGE_MIN_COUNT = 2",+ "docstring": "",+ }+ ],+ }+ ]++ def test_invented_number_is_ungrounded(self) -> None:+ assert _ungrounded_numbers("The default minimum count is 3.", self.HITS) == ["3"]++ def test_number_present_in_signature_is_grounded(self) -> None:+ assert _ungrounded_numbers("The default minimum count is 2.", self.HITS) == []++ def test_file_line_citations_are_not_value_assertions(self) -> None:+ text = "The default is 2 (git_indexer/_constants.py:114)."+ assert _ungrounded_numbers(text, self.HITS) == []++ def test_no_numbers_in_answer_is_grounded(self) -> None:+ assert _ungrounded_numbers("It reads the tuning constant from config.", self.HITS) == []++ def test_underscore_separated_constant_is_grounded(self) -> None:+ # Source ``MAX = 100_000`` and an answer that says "100000" are the+ # same value — the digit-separator strip must keep this grounded.+ hits = [{"symbols": [{"name": "MAX", "signature": "MAX = 100_000", "docstring": ""}]}]+ assert _ungrounded_numbers("The cap is 100000 tokens.", hits) == []++ def test_comma_grouped_answer_is_grounded(self) -> None:+ # Prose commas (``100,000``) must not split into 100 and 000 and read+ # as ungrounded against ``100_000`` in source.+ hits = [{"symbols": [{"name": "MAX", "signature": "MAX = 100_000", "docstring": ""}]}]+ assert _ungrounded_numbers("The cap is 100,000 tokens.", hits) == []+++# ---------------------------------------------------------------------------+# End-to-end gate behaviour through get_answer+# ---------------------------------------------------------------------------++_SYMBOL = {+ "name": "MIN_COUNT",+ "kind": "constant",+ "signature": "MIN_COUNT = 2",+ "docstring": "",+ "start_line": 10,+ "end_line": 10,+ "_matched": True,+}++# Function-kind variant: matched, but not extractable by the C1 fast path —+# used by tests that must reach the synthesis gates on value questions.+_FN_SYMBOL = {+ "name": "min_count_policy",+ "kind": "function",+ "signature": "def min_count_policy() -> int",+ "docstring": "Returns the default minimum count, 2.",+ "start_line": 10,+ "end_line": 14,+ "_matched": True,+}+++def _patch_pipeline(monkeypatch, answer_mod, *, with_symbols: bool, symbol: dict | None = None):+ async def _fake_retrieve(question, ctx):+ return [+ {"page_id": "file_page:pkg/alpha/one.py", "score": 5.0},+ {"page_id": "file_page:pkg/alpha/two.py", "score": 4.0},+ ]++ async def _fake_hydrate(hits, ctx, *, scope=None):+ for i, h in enumerate(hits):+ h["target_path"] = h["page_id"].removeprefix("file_page:")+ h["title"] = h["target_path"]+ h["summary"] = "Auth service summary."+ h["snippet"] = ""+ h["page_type"] = "file_page"+ if with_symbols and i == 0:+ h["symbols"] = [dict(symbol or _SYMBOL)]+ return hits++ monkeypatch.setattr(answer_mod, "_hybrid_retrieve", _fake_retrieve)+ monkeypatch.setattr(answer_mod, "_hydrate_hits", _fake_hydrate)+++def _patch_provider(monkeypatch, answer_mod, content: str):+ class _Provider:+ provider_name = "mock"+ model_name = "mock-1"++ async def generate(self, **kwargs):+ return SimpleNamespace(content=content)++ monkeypatch.setattr(answer_mod, "_resolve_provider_for_answer", lambda _p: _Provider())+++async def test_ungrounded_value_caps_confidence_low(setup_mcp, monkeypatch):+ import repowise.server.mcp_server.tool_answer.answer as answer_mod+ from repowise.server.mcp_server import get_answer++ _patch_pipeline(monkeypatch, answer_mod, with_symbols=True, symbol=_FN_SYMBOL)+ _patch_provider(+ monkeypatch,+ answer_mod,+ "The default of min_count_policy is 3 (pkg/alpha/one.py).",+ )++ result = await get_answer("What is the default value of min_count_policy?")+ assert result["confidence"] == "low"+ assert "3" in result["note"]+ assert "next_action_hint" in result+++async def test_grounded_value_keeps_high_confidence(setup_mcp, monkeypatch):+ import repowise.server.mcp_server.tool_answer.answer as answer_mod+ from repowise.server.mcp_server import get_answer++ _patch_pipeline(monkeypatch, answer_mod, with_symbols=True, symbol=_FN_SYMBOL)+ _patch_provider(+ monkeypatch,+ answer_mod,+ "The default of min_count_policy is 2 (pkg/alpha/one.py).",+ )++ result = await get_answer("What is the default value of min_count_policy?")+ assert result["confidence"] == "high"+ assert "High confidence" in result["note"]+++async def test_high_confidence_requires_source_backed_citation(setup_mcp, monkeypatch):+ """No cited page contributed symbols → high is downgraded to medium."""+ import repowise.server.mcp_server.tool_answer.answer as answer_mod+ from repowise.server.mcp_server import get_answer++ _patch_pipeline(monkeypatch, answer_mod, with_symbols=False)+ _patch_provider(+ monkeypatch,+ answer_mod,+ "Auth flows through middleware into the service (pkg/alpha/one.py).",+ )++ result = await get_answer("how does the auth flow work end to end")+ assert result["confidence"] == "medium"+++async def test_expanded_hedge_marker_downgrades_through_pipeline(setup_mcp, monkeypatch):+ import repowise.server.mcp_server.tool_answer.answer as answer_mod+ from repowise.server.mcp_server import get_answer++ _patch_pipeline(monkeypatch, answer_mod, with_symbols=True, symbol=_FN_SYMBOL)+ _patch_provider(+ monkeypatch,+ answer_mod,+ "The provided excerpts do not include the body of min_count_policy.",+ )++ result = await get_answer("What is the default value of min_count_policy?")+ assert result["confidence"] == "low"+ assert result["retrieval"] == []+++async def test_value_question_uses_extraction_fast_path(setup_mcp, monkeypatch):+ """C1: matched constant + value question → verbatim line, no LLM call."""+ import repowise.server.mcp_server.tool_answer.answer as answer_mod+ from repowise.server.mcp_server import get_answer++ _patch_pipeline(monkeypatch, answer_mod, with_symbols=True)++ def _no_provider(_p):+ raise AssertionError("fast path must not resolve a provider")++ monkeypatch.setattr(answer_mod, "_resolve_provider_for_answer", _no_provider)++ result = await get_answer("What is the default value of MIN_COUNT?")+ assert result["grounding"] == "extracted"+ assert result["confidence"] == "high"+ assert "MIN_COUNT = 2" in result["answer"]+ assert "pkg/alpha/one.py:10" in result["answer"]+ assert result["citations"] == ["pkg/alpha/one.py"]+ assert result["retrieval"] == []+++async def test_mechanism_question_skips_fast_path(setup_mcp, monkeypatch):+ import repowise.server.mcp_server.tool_answer.answer as answer_mod+ from repowise.server.mcp_server import get_answer++ _patch_pipeline(monkeypatch, answer_mod, with_symbols=True)+ _patch_provider(monkeypatch, answer_mod, "MIN_COUNT gates retries (pkg/alpha/one.py).")++ result = await get_answer("How does MIN_COUNT influence the retry loop?")+ assert "grounding" not in result+++async def test_synthesized_answer_carries_grounded_quotes(setup_mcp, monkeypatch):+ """C2: symbols named in the answer attach {path, lines, quote}."""+ import repowise.server.mcp_server.tool_answer.answer as answer_mod+ from repowise.server.mcp_server import get_answer++ _patch_pipeline(monkeypatch, answer_mod, with_symbols=True)+ _patch_provider(monkeypatch, answer_mod, "Retries are gated by MIN_COUNT (pkg/alpha/one.py).")++ result = await get_answer("How does the retry gating mechanism work here?")+ assert result.get("quotes"), "answer naming MIN_COUNT must carry a quote"+ [q] = result["quotes"]+ assert q["path"] == "pkg/alpha/one.py"+ assert q["lines"][0] == 10+ assert "MIN_COUNT = 2" in q["quote"]diff --git a/tests/unit/server/mcp/test_answer_payload.py b/tests/unit/server/mcp/test_answer_payload.pynew file mode 100644index 000000000..cd003f280--- /dev/null+++ b/tests/unit/server/mcp/test_answer_payload.py@@ -0,0 +1,194 @@+"""Payload diet for get_answer (B1/B2).++* serialize_hits strips internal scoring fields — zero plumbing reaches+ the agent (path/title/summary/snippet/excerpt/score/key_symbols only)+* the retrieval block is confidence-conditional: high → none, medium →+ top-2 truncated, low/gated → full serialized block+* regression guard: no response key may start with "_" except _meta+"""++from __future__ import annotations++from types import SimpleNamespace++import pytest++from repowise.server.mcp_server.tool_answer.retrieval import serialize_hits++# ---------------------------------------------------------------------------+# serialize_hits unit tests+# ---------------------------------------------------------------------------++RAW_HIT = {+ "page_id": "file_page:pkg/mod.py",+ "target_path": "pkg/mod.py",+ "title": "mod",+ "summary": "A module that does things. " * 20,+ "snippet": "def f(): ...",+ "score": 4.321987,+ "_coverage": 0.4,+ "_raw_score": 3.9,+ "_intersection": True,+ "_pagerank": 0.002,+ "_pagerank_bias": 1.01,+ "_sources": {"fts", "vector"},+ "_domain_penalty": None,+ "symbols": [+ {"name": "f", "kind": "function", "signature": "def f()", "_matched": True},+ ],+}+++class TestSerializeHits:+ def test_internal_fields_stripped(self) -> None:+ [entry] = serialize_hits([dict(RAW_HIT)])+ assert not [k for k in entry if k.startswith("_")]+ assert "page_id" not in entry+ assert entry["path"] == "pkg/mod.py"+ assert entry["score"] == 4.322++ def test_symbol_internal_fields_stripped(self) -> None:+ [entry] = serialize_hits([dict(RAW_HIT)])+ [sym] = entry["key_symbols"]+ assert "_matched" not in sym+ assert sym["signature"] == "def f()"++ def test_summary_truncation(self) -> None:+ [entry] = serialize_hits([dict(RAW_HIT)], summary_chars=160)+ assert len(entry["summary"]) <= 160++ def test_limit(self) -> None:+ hits = [dict(RAW_HIT), dict(RAW_HIT), dict(RAW_HIT)]+ assert len(serialize_hits(hits, limit=2)) == 2++ def test_graph_expanded_hit_loses_symbols_when_asked(self) -> None:+ expanded = dict(RAW_HIT, _sources={"graph_expand"})+ [entry] = serialize_hits([expanded], symbols_for_expanded=False)+ assert "key_symbols" not in entry+ [kept] = serialize_hits([expanded], symbols_for_expanded=True)+ assert "key_symbols" in kept+++# ---------------------------------------------------------------------------+# Confidence-conditional retrieval through get_answer+# ---------------------------------------------------------------------------+++def _assert_no_underscore_keys(obj, path="root"):+ if isinstance(obj, dict):+ for k, v in obj.items():+ assert not (str(k).startswith("_") and k != "_meta"), (+ f"internal key {k!r} leaked at {path}"+ )+ if k != "_meta":+ _assert_no_underscore_keys(v, f"{path}.{k}")+ elif isinstance(obj, list):+ for i, v in enumerate(obj):+ _assert_no_underscore_keys(v, f"{path}[{i}]")+++def _patch_pipeline(monkeypatch, answer_mod, scores=(5.0, 4.0)):+ async def _fake_retrieve(question, ctx):+ return [+ {"page_id": "file_page:pkg/beta/one.py", "score": scores[0], "_sources": {"fts"}},+ {"page_id": "file_page:pkg/beta/two.py", "score": scores[1], "_sources": {"fts"}},+ ]++ async def _fake_hydrate(hits, ctx, *, scope=None):+ for i, h in enumerate(hits):+ h["target_path"] = h["page_id"].removeprefix("file_page:")+ h["title"] = h["target_path"]+ h["summary"] = "Summary text for the page. " * 12+ h["snippet"] = ""+ h["page_type"] = "file_page"+ if i == 0:+ h["symbols"] = [+ {+ "name": "go",+ "kind": "function",+ "signature": "def go()",+ "docstring": "",+ "start_line": 3,+ "end_line": 9,+ "_matched": True,+ }+ ]+ return hits++ monkeypatch.setattr(answer_mod, "_hybrid_retrieve", _fake_retrieve)+ monkeypatch.setattr(answer_mod, "_hydrate_hits", _fake_hydrate)+++def _patch_provider(monkeypatch, answer_mod, content):+ class _Provider:+ provider_name = "mock"+ model_name = "mock-1"++ async def generate(self, **kwargs):+ return SimpleNamespace(content=content)++ monkeypatch.setattr(answer_mod, "_resolve_provider_for_answer", lambda _p: _Provider())+++async def test_high_confidence_drops_retrieval_block(setup_mcp, monkeypatch):+ import repowise.server.mcp_server.tool_answer.answer as answer_mod+ from repowise.server.mcp_server import get_answer++ _patch_pipeline(monkeypatch, answer_mod, scores=(5.0, 4.0))+ _patch_provider(monkeypatch, answer_mod, "The go() function drives it (pkg/beta/one.py).")++ result = await get_answer("how does the beta module go function work")+ assert result["confidence"] == "high"+ assert result["retrieval"] == []+ assert result["fallback_targets"], "routing targets survive the diet"+ _assert_no_underscore_keys(result)+++async def test_medium_confidence_keeps_two_truncated_hits(setup_mcp, monkeypatch):+ import repowise.server.mcp_server.tool_answer.answer as answer_mod+ from repowise.server.mcp_server import get_answer++ # ratio 1.27 >= 1.2 but top score < 1.5 floor → medium.+ _patch_pipeline(monkeypatch, answer_mod, scores=(1.4, 1.1))+ _patch_provider(monkeypatch, answer_mod, "The go() function drives it (pkg/beta/one.py).")++ result = await get_answer("how does the beta module go function work")+ assert result["confidence"] == "medium"+ assert 0 < len(result["retrieval"]) <= 2+ for entry in result["retrieval"]:+ assert len(entry.get("summary", "")) <= 160+ _assert_no_underscore_keys(result)+++async def test_gated_path_serves_clean_retrieval(setup_mcp, monkeypatch):+ import repowise.server.mcp_server.tool_answer.answer as answer_mod+ from repowise.server.mcp_server import get_answer++ # 2.0 vs 1.9: top < 3.0 and ratio 1.05 < 1.2 → gated, no synthesis.+ _patch_pipeline(monkeypatch, answer_mod, scores=(2.0, 1.9))+ _patch_provider(monkeypatch, answer_mod, "unused")++ result = await get_answer("how does the beta module go function work")+ assert result["confidence"] == "low"+ assert result["best_guesses"]+ for entry in result["retrieval"]:+ assert "page_id" not in entry+ assert entry.get("path")+ _assert_no_underscore_keys(result)+++async def test_cached_response_carries_no_internal_keys(setup_mcp, monkeypatch):+ import repowise.server.mcp_server.tool_answer.answer as answer_mod+ from repowise.server.mcp_server import get_answer++ _patch_pipeline(monkeypatch, answer_mod, scores=(5.0, 4.0))+ _patch_provider(monkeypatch, answer_mod, "The go() function drives it (pkg/beta/one.py).")++ await get_answer("how does the beta module go function work")+ cached = await get_answer("how does the beta module go function work")+ assert cached["_meta"].get("cached") is True+ _assert_no_underscore_keys(cached)diff --git a/tests/unit/server/mcp/test_context.py b/tests/unit/server/mcp/test_context.pyindex 54694f636..68e9ccc5e 100644--- a/tests/unit/server/mcp/test_context.py+++ b/tests/unit/server/mcp/test_context.py@@ -452,3 +452,18 @@ async def test_batch_isolation_one_target_errors(setup_mcp, monkeypatch):assert "boom" in targetsassert "error" in targets["boom"]assert targets["boom"]["target"] == "boom"+++async def test_file_target_callers_rolls_up_importers(setup_mcp):+ """B5: include=["callers"] on a FILE target returns the import rollup+ instead of an empty list (which forced a second round-trip)."""+ from repowise.server.mcp_server import get_context++ result = await get_context(["src/auth/service.py"], include=["callers"], compact=False)+ t = result["targets"]["src/auth/service.py"]+ callers = t.get("callers")+ assert callers, "file-level callers must not be empty when importers exist"+ [middleware] = [c for c in callers if c["file"] == "src/auth/middleware.py"]+ assert middleware.get("imports") is True+ assert "rollup" in t.get("_call_graph_note", "")diff --git a/tests/unit/server/mcp/test_counterfactual.py b/tests/unit/server/mcp/test_counterfactual.pyindex 5cfd68543..600fa6f1a 100644--- a/tests/unit/server/mcp/test_counterfactual.py+++ b/tests/unit/server/mcp/test_counterfactual.py@@ -42,7 +42,7 @@ def test_search_codebase_no_results_returns_zero() -> None:def test_unknown_tool_returns_zero() -> None:- assert cf.replaced_tokens_for("get_risk", {"anything": 1}) == 0+ assert cf.replaced_tokens_for("list_repos", {"anything": 1}) == 0def test_non_dict_result_returns_zero() -> None:@@ -59,3 +59,56 @@ def test_malformed_skeleton_does_not_raise() -> None:}}assert cf.replaced_tokens_for("get_context", result) == 0+++def test_get_answer_counts_search_plus_cited_reads() -> None:+ result = {+ "answer": "The default is 2 (pkg/a.py).",+ "citations": ["pkg/a.py"],+ "fallback_targets": ["pkg/a.py", "pkg/b.py"],+ }+ expected = cf.ANSWER_SEARCH_FLOOR + 2 * cf.ANSWER_READ_FLOOR_PER_FILE+ assert cf.replaced_tokens_for("get_answer", result) == expected+++def test_get_answer_empty_answer_claims_nothing() -> None:+ # Gated/low responses tell the agent to go read — those reads still+ # happen, so claiming them as saved repeats the E11 miscalibration.+ result = {"answer": "", "best_guesses": [{"file": "pkg/a.py"}]}+ assert cf.replaced_tokens_for("get_answer", result) == 0+++def test_fixed_floor_tools_credit_successful_calls_only() -> None:+ assert cf.replaced_tokens_for("get_risk", {"targets": ["a.py"]}) == cf.RISK_FLOOR+ assert cf.replaced_tokens_for("get_risk", {"error": "nope"}) == 0+ assert cf.replaced_tokens_for("get_why", {"decisions": []}) == cf.WHY_FLOOR+ assert cf.replaced_tokens_for("get_overview", {"architecture": {}}) == cf.OVERVIEW_FLOOR+ assert cf.replaced_tokens_for("get_health", {"summary": {}}) == cf.HEALTH_FLOOR+++def test_dead_end_records_debit_row(tmp_path, monkeypatch) -> None:+ """An error response writes raw=0/distilled=N — a negative net at+ aggregation, so the ledger stops only ever crediting (E11)."""+ from repowise.core.distill.store import (+ OMISSIONS_DB_FILENAME,+ OMISSIONS_DIRNAME,+ OmissionStore,+ )+ from repowise.server.mcp_server._savings.recorder import record_mcp_dead_end++ db_dir = tmp_path / ".repowise" / OMISSIONS_DIRNAME+ db_dir.mkdir(parents=True)+ db_path = db_dir / OMISSIONS_DB_FILENAME+ OmissionStore(db_path).close() # create the sidecar++ assert record_mcp_dead_end(tmp_path, "get_symbol", 350) is True++ store = OmissionStore(db_path)+ try:+ summary = store.savings_summary()+ per = summary["per_filter"]["get_symbol"]+ assert per["raw_tokens"] == 0+ assert per["distilled_tokens"] == 350+ assert per["saved_tokens"] == -350+ finally:+ store.close()diff --git a/tests/unit/server/mcp/test_search.py b/tests/unit/server/mcp/test_search.pyindex c4d665d79..c54dddda6 100644--- a/tests/unit/server/mcp/test_search.py+++ b/tests/unit/server/mcp/test_search.py@@ -76,8 +76,11 @@ class TestDecisionDownweight:return [_mk_result("decision:d1", "Use repo-local SQLite", "decision_record", "", 0.57),_mk_result(- "file_page:src/auth/service.py", "Auth Service", "file_page",- "src/auth/service.py", 0.42,+ "file_page:src/auth/service.py",+ "Auth Service",+ "file_page",+ "src/auth/service.py",+ 0.42,),]@@ -97,8 +100,11 @@ class TestDecisionDownweight:return [_mk_result("decision:d1", "Use repo-local SQLite", "decision_record", "", 0.57),_mk_result(- "file_page:src/auth/service.py", "Auth Service", "file_page",- "src/auth/service.py", 0.42,+ "file_page:src/auth/service.py",+ "Auth Service",+ "file_page",+ "src/auth/service.py",+ 0.42,),]@@ -120,8 +126,11 @@ class TestDecisionDownweight:]flood.append(_mk_result(- "file_page:src/auth/service.py", "Auth Service", "file_page",- "src/auth/service.py", 0.35,+ "file_page:src/auth/service.py",+ "Auth Service",+ "file_page",+ "src/auth/service.py",+ 0.35,))@@ -148,8 +157,11 @@ class TestDecisionDownweight:]flood.append(_mk_result(- "file_page:src/auth/service.py", "Auth Service", "file_page",- "src/auth/service.py", 0.35,+ "file_page:src/auth/service.py",+ "Auth Service",+ "file_page",+ "src/auth/service.py",+ 0.35,))@@ -199,3 +211,109 @@ class TestClassifyHitKind:from repowise.server.mcp_server.tool_search import _classify_hit_kindassert _classify_hit_kind("src/auth", "module_page") == "doc"+++class TestDecisionDemotionAndRescue:+ """B4: absolute demotion of decisions on non-why queries + window rescue."""++ @pytest.mark.asyncio+ async def test_decision_outscoring_file_page_still_ranks_below(self, setup_mcp):+ # The 0.6 down-weight alone is washed out when the decision score+ # margin exceeds it (0.9 * 0.6 = 0.54 > 0.42). Demotion must be+ # absolute for non-why queries.+ import repowise.server.mcp_server as mcp_mod+ from repowise.server.mcp_server import search_codebase++ async def fake_search(query, limit=10):+ return [+ _mk_result("decision:d1", "Cache prompts as SWR", "decision_record", "", 0.9),+ _mk_result(+ "file_page:src/auth/service.py",+ "Auth Service",+ "file_page",+ "src/auth/service.py",+ 0.42,+ ),+ ]++ mcp_mod._vector_store.search = fake_search+ result = await search_codebase("answer cache invalidation schema version")+ types = [r["page_type"] for r in result["results"]]+ assert types[0] == "file_page"++ @pytest.mark.asyncio+ async def test_all_decision_window_is_rescued_with_file_pages(self, setup_mcp):+ # E6 live failure: 5/5 decision records, zero file pages. The wider+ # re-fetch must surface non-decision pages.+ import repowise.server.mcp_server as mcp_mod+ from repowise.server.mcp_server import search_codebase++ decisions = [+ _mk_result(f"decision:d{i}", f"Decision {i}", "decision_record", "", 0.8 - i * 0.01)+ for i in range(20)+ ]+ wide = decisions + [+ _mk_result(+ "file_page:src/auth/service.py",+ "Auth Service",+ "file_page",+ "src/auth/service.py",+ 0.3,+ )+ ]++ async def fake_search(query, limit=10):+ # Narrow window: only decisions. Wide window: includes the file.+ return decisions[:limit] if limit <= 20 else wide[:limit]++ mcp_mod._vector_store.search = fake_search+ result = await search_codebase("answer cache invalidation schema version", limit=5)+ types = [r["page_type"] for r in result["results"]]+ assert "file_page" in types, "rescue must inject non-decision pages"+ assert types[0] == "file_page", "rescued file page ranks above demoted decisions"++ @pytest.mark.asyncio+ async def test_why_query_skips_rescue_and_demotion(self, setup_mcp):+ import repowise.server.mcp_server as mcp_mod+ from repowise.server.mcp_server import search_codebase++ async def fake_search(query, limit=10):+ return [+ _mk_result("decision:d1", "Use SQLite", "decision_record", "", 0.9),+ _mk_result(+ "file_page:src/auth/service.py",+ "Auth Service",+ "file_page",+ "src/auth/service.py",+ 0.42,+ ),+ ]++ mcp_mod._vector_store.search = fake_search+ result = await search_codebase("why did we choose SQLite?")+ assert result["results"][0]["page_type"] == "decision_record"+++class TestIdentifierGrepHint:+ @pytest.mark.asyncio+ async def test_multiword_query_with_identifier_gets_hint(self, setup_mcp):+ from repowise.server.mcp_server import search_codebase++ result = await search_codebase("where is _DEFAULT_CO_CHANGE_MIN_COUNT defined")+ assert "grep_hint" in result+ assert "_DEFAULT_CO_CHANGE_MIN_COUNT" in result["grep_hint"]++ @pytest.mark.asyncio+ async def test_camelcase_identifier_gets_hint(self, setup_mcp):+ from repowise.server.mcp_server import search_codebase++ result = await search_codebase("how does LanguageRegistry resolve specs")+ assert "grep_hint" in result+ assert "LanguageRegistry" in result["grep_hint"]++ @pytest.mark.asyncio+ async def test_plain_english_query_gets_no_hint(self, setup_mcp):+ from repowise.server.mcp_server import search_codebase++ result = await search_codebase("authentication flow for the service")+ assert "grep_hint" not in resultdiff --git a/tests/unit/server/mcp/test_symbol_range_and_recovery.py b/tests/unit/server/mcp/test_symbol_range_and_recovery.pynew file mode 100644index 000000000..d7ffb1afd--- /dev/null+++ b/tests/unit/server/mcp/test_symbol_range_and_recovery.py@@ -0,0 +1,112 @@+"""Range reads and dead-end recovery in get_symbol (C3/C4).++* "path/to/file.py:140-180" serves a live, bounded, always-verified slice+* an index miss greps the live file and returns fallback_lines instead of+ a pure-cost dead end+"""++from __future__ import annotations++import pytest++MODULE_SOURCE = '''"""A module."""++import os++_DEFAULT_MIN_COUNT = 2+MAX_RETRIES = 5+++def alpha(x):+ return x + 1+++def beta(y):+ return y * 2+'''+++def repo_on_disk(tmp_path, monkeypatch):+ """Point the MCP repo path at a tmp dir with a real source file."""+ import repowise.server.mcp_server as mcp_mod++ (tmp_path / "pkg").mkdir()+ (tmp_path / "pkg" / "mod.py").write_text(MODULE_SOURCE)+ big = "\n".join(f"line_{i} = {i}" for i in range(1, 401))+ (tmp_path / "pkg" / "big.py").write_text(big)+ monkeypatch.setattr(mcp_mod, "_repo_path", str(tmp_path))+ return tmp_path+++async def test_range_read_serves_verified_slice(setup_mcp, repo_on_disk):+ from repowise.server.mcp_server import get_symbol++ result = await get_symbol("pkg/mod.py:5-6")+ assert result.get("error") is None+ assert result["verified"] is True+ assert result["kind"] == "range"+ assert result["start_line"] == 5+ assert result["end_line"] == 6+ assert "_DEFAULT_MIN_COUNT = 2" in result["source"]+ assert "MAX_RETRIES = 5" in result["source"]+++async def test_range_read_caps_at_200_lines(setup_mcp, repo_on_disk):+ from repowise.server.mcp_server import get_symbol++ result = await get_symbol("pkg/big.py:1-400")+ assert result["truncated"] is True+ assert result["end_line"] - result["start_line"] + 1 <= 200+++async def test_range_read_context_does_not_exceed_cap(setup_mcp, repo_on_disk):+ from repowise.server.mcp_server import get_symbol++ # 161-line request + 50 lines of context each side would be 261 lines —+ # the ≤200 contract must hold after context expansion, not just before.+ result = await get_symbol("pkg/big.py:100-260", context_lines=50)+ assert result["verified"] is True+ assert result["end_line"] - result["start_line"] + 1 <= 200+ assert result["truncated"] is True+++async def test_range_read_swaps_reversed_bounds(setup_mcp, repo_on_disk):+ from repowise.server.mcp_server import get_symbol++ result = await get_symbol("pkg/mod.py:6-5")+ assert result.get("error") is None+ assert result["start_line"] == 5+++async def test_double_colon_id_is_not_a_range(setup_mcp, repo_on_disk):+ from repowise.server.mcp_server import get_symbol++ # "::" forces symbol resolution even though the tail looks numeric-ish.+ result = await get_symbol("pkg/mod.py::alpha")+ assert result.get("kind") != "range"+++async def test_unindexed_constant_recovers_via_live_grep(setup_mcp, repo_on_disk):+ from repowise.server.mcp_server import get_symbol++ result = await get_symbol("pkg/mod.py::_DEFAULT_MIN_COUNT")+ assert result.get("resolution") == "live_grep"+ assert result["verified"] is True+ [match] = [m for m in result["fallback_lines"] if m["line"] == 5]+ assert "_DEFAULT_MIN_COUNT = 2" in match["context"]+ assert "range read" in result["note"]+++async def test_missing_file_still_errors(setup_mcp, repo_on_disk):+ from repowise.server.mcp_server import get_symbol++ result = await get_symbol("pkg/ghost.py::nothing")+ assert "error" in resultdiff --git a/tests/unit/server/mcp/test_tombstones.py b/tests/unit/server/mcp/test_tombstones.pynew file mode 100644index 000000000..863e48f01--- /dev/null+++ b/tests/unit/server/mcp/test_tombstones.py@@ -0,0 +1,132 @@+"""Tombstone pages for deleted/renamed files (A4).++A ``freshness_status="fresh"`` page for a file that no longer exists is an+active trap: retrieval serves it, agents cite it. These tests cover the+marking helper and every serving surface that must skip or redirect.+"""++from __future__ import annotations++import json+from types import SimpleNamespace++import pytest+from sqlalchemy import select++from repowise.core.persistence.models import Page+from repowise.core.pipeline.persist import mark_tombstone_pages, tombstone_candidates+++class TestTombstoneCandidates:+ def test_deleted_file_has_no_successor(self) -> None:+ fd = SimpleNamespace(status="deleted", path="src/old.py", old_path=None)+ assert tombstone_candidates([fd]) == [("src/old.py", [])]++ def test_renamed_file_points_to_new_path(self) -> None:+ fd = SimpleNamespace(status="renamed", path="src/new.py", old_path="src/old.py")+ assert tombstone_candidates([fd]) == [("src/old.py", ["src/new.py"])]++ def test_modified_and_added_ignored(self) -> None:+ fds = [+ SimpleNamespace(status="modified", path="a.py", old_path=None),+ SimpleNamespace(status="added", path="b.py", old_path=None),+ ]+ assert tombstone_candidates(fds) == []+++async def test_mark_tombstone_pages_sets_status_and_successors(setup_mcp, session):+ repo_id = setup_mcp+ page = (+ (await session.execute(select(Page).where(Page.target_path == "src/auth/service.py")))+ .scalars()+ .first()+ )+ assert page is not None, "fixture must seed a page for src/auth/service.py"++ marked = await mark_tombstone_pages(+ session, repo_id, [("src/auth/service.py", ["src/auth/service_v2.py"])]+ )+ await session.commit()++ assert marked == 1+ await session.refresh(page)+ assert page.freshness_status == "tombstone"+ assert json.loads(page.metadata_json)["successor_paths"] == ["src/auth/service_v2.py"]+++async def test_get_context_returns_tombstone_redirect(setup_mcp, session):+ repo_id = setup_mcp+ from repowise.server.mcp_server import get_context++ await mark_tombstone_pages(+ session, repo_id, [("src/auth/service.py", ["src/auth/service_v2.py"])]+ )+ await session.commit()++ result = await get_context(["src/auth/service.py"], include=["docs"])+ t = result["targets"]["src/auth/service.py"]+ assert "tombstone" in t["error"]+ assert t["successor_paths"] == ["src/auth/service_v2.py"]+ assert "service_v2" in t["hint"]+++async def test_search_drops_tombstoned_pages(setup_mcp, session, monkeypatch):+ repo_id = setup_mcp+ import repowise.server.mcp_server as mcp_mod+ from repowise.core.persistence.search import SearchResult+ from repowise.server.mcp_server import search_codebase++ await mark_tombstone_pages(session, repo_id, [("src/auth/service.py", [])])+ await session.commit()++ async def fake_search(query, limit=10):+ return [+ SearchResult(+ page_id="file_page:src/auth/service.py",+ title="Auth Service",+ page_type="file_page",+ target_path="src/auth/service.py",+ score=0.9,+ snippet="auth",+ search_type="vector",+ ),+ SearchResult(+ page_id="file_page:src/db/models.py",+ title="DB Models",+ page_type="file_page",+ target_path="src/db/models.py",+ score=0.5,+ snippet="models",+ search_type="vector",+ ),+ ]++ mcp_mod._vector_store.search = fake_search+ result = await search_codebase("auth service")+ ids = [r["page_id"] for r in result["results"]]+ assert "file_page:src/auth/service.py" not in ids+ assert "file_page:src/db/models.py" in ids+++async def test_answer_hydration_drops_tombstoned_pages(setup_mcp, session):+ repo_id = setup_mcp+ from repowise.server.mcp_server._answer_pipeline import hydrate_hits++ await mark_tombstone_pages(session, repo_id, [("src/auth/service.py", [])])+ await session.commit()++ import repowise.server.mcp_server as mcp_mod++ ctx = SimpleNamespace(session_factory=mcp_mod._session_factory)+ hits = [+ {"page_id": "file_page:src/auth/service.py", "score": 5.0},+ {"page_id": "file_page:src/db/models.py", "score": 4.0},+ ]+ out = await hydrate_hits(hits, ctx)+ paths = [h["target_path"] for h in out]+ assert "src/auth/service.py" not in paths+ assert "src/db/models.py" in pathsdiff --git a/tests/unit/server/mcp/test_verify_bounds.py b/tests/unit/server/mcp/test_verify_bounds.pynew file mode 100644index 000000000..d62229e6a--- /dev/null+++ b/tests/unit/server/mcp/test_verify_bounds.py@@ -0,0 +1,208 @@+"""Serve-time bounds verification for get_symbol (the trust contract).++WikiSymbol line bounds are written at index time; the file may have changed+since. These tests cover the two-tier check: cheap name-on-line gate, then+one-file re-parse with bound correction, then the approximate fallback.+"""++from __future__ import annotations++import pytest++from repowise.core.persistence.models import WikiSymbol, _new_uuid+from repowise.server.mcp_server._verify import (+ check_symbol_bounds,+ end_anchor_holds,+ heal_symbol_row,+ name_at_line,+ relocate_symbol,+)++FRESH_SOURCE = '''"""Module."""+++def alpha(x):+ return x + 1+++class Service:+ def handle(self, req):+ return req+'''++# alpha's body grew by two lines but its definition line is unchanged — the+# stored end (5) now truncates the body (real end is 7). The start gate alone+# would pass and serve a short slice marked verified.+GROWN_SOURCE = '''"""Module."""+++def alpha(x):+ y = x + 1+ z = y + 1+ return z+++class Service:+ def handle(self, req):+ return req+'''++# Same file with 4 lines inserted above alpha — every stored bound is stale.+SHIFTED_SOURCE = '''"""Module."""++import os+import sys+++NEW_CONSTANT = 7+++def alpha(x):+ return x + 1+++class Service:+ def handle(self, req):+ return req+'''+++def _row(**overrides) -> WikiSymbol:+ defaults = dict(+ id=_new_uuid(),+ repository_id="repo-1",+ file_path="pkg/mod.py",+ symbol_id="pkg/mod.py::alpha",+ name="alpha",+ qualified_name="pkg.mod.alpha",+ kind="function",+ signature="def alpha(x)",+ start_line=4,+ end_line=5,+ language="python",+ )+ defaults.update(overrides)+ return WikiSymbol(**defaults)+++class TestNameAtLine:+ def test_name_on_stored_line_passes(self) -> None:+ assert name_at_line(FRESH_SOURCE.splitlines(), "alpha", 4)++ def test_moved_definition_fails(self) -> None:+ assert not name_at_line(SHIFTED_SOURCE.splitlines(), "alpha", 4)++ def test_out_of_range_line_fails(self) -> None:+ assert not name_at_line(FRESH_SOURCE.splitlines(), "alpha", 999)++ def test_qualified_name_uses_bare_segment(self) -> None:+ assert name_at_line(FRESH_SOURCE.splitlines(), "Service::handle", 9)+++class TestCheckSymbolBounds:+ def test_fresh_bounds_verified_without_reparse(self) -> None:+ check = check_symbol_bounds(_row(), FRESH_SOURCE)+ assert check.verified+ assert not check.corrected+ assert (check.start_line, check.end_line) == (4, 5)++ def test_stale_bounds_corrected_via_reparse(self) -> None:+ check = check_symbol_bounds(_row(), SHIFTED_SOURCE)+ assert check.verified+ assert check.corrected+ # alpha moved from line 4 to line 10 in the shifted source.+ assert check.start_line == 10+ slice_lines = SHIFTED_SOURCE.splitlines()[check.start_line - 1 : check.end_line]+ assert "def alpha(x):" in slice_lines[0]++ def test_deleted_symbol_is_approximate(self) -> None:+ row = _row(name="ghost", symbol_id="pkg/mod.py::ghost", qualified_name="ghost")+ check = check_symbol_bounds(row, SHIFTED_SOURCE)+ assert not check.verified+ assert check.approximate++ def test_method_relocated_by_name_and_parent(self) -> None:+ row = _row(+ name="handle",+ symbol_id="pkg/mod.py::Service::handle",+ qualified_name="Service::handle",+ kind="method",+ parent_name="Service",+ start_line=9,+ end_line=10,+ )+ check = check_symbol_bounds(row, SHIFTED_SOURCE)+ assert check.verified+ assert check.corrected+ assert "def handle" in SHIFTED_SOURCE.splitlines()[check.start_line - 1]++ def test_interior_body_growth_forces_correction(self) -> None:+ # Definition line unchanged, but the body grew — the start gate passes+ # yet the stored end (5) truncates the symbol. The end anchor must+ # catch it and re-parse to the true end (7), not serve a short slice.+ check = check_symbol_bounds(_row(), GROWN_SOURCE)+ assert check.verified+ assert check.corrected+ assert (check.start_line, check.end_line) == (4, 7)++ def test_short_name_skips_cheap_gate(self) -> None:+ # "db" is a substring of "dbquery()" but isn't this symbol. A 1-2 char+ # name must not be rubber-stamped by substring containment; with no+ # real symbol to relocate, the result is approximate, not verified.+ src = "result = self.dbquery()\n"+ row = _row(+ name="db", symbol_id="pkg/mod.py::db", qualified_name="db", start_line=1, end_line=1+ )+ check = check_symbol_bounds(row, src)+ assert not check.verified+ assert check.approximate+++class TestEndAnchor:+ def test_eof_after_symbol_holds(self) -> None:+ assert end_anchor_holds(FRESH_SOURCE.splitlines(), 8, 10)++ def test_blank_line_after_symbol_holds(self) -> None:+ assert end_anchor_holds(FRESH_SOURCE.splitlines(), 4, 5)++ def test_deeper_indent_after_stored_end_fails(self) -> None:+ # Line 6 (" z = y + 1") is still body — stored end of 5 is wrong.+ assert not end_anchor_holds(GROWN_SOURCE.splitlines(), 4, 5)++ def test_out_of_range_end_fails(self) -> None:+ assert not end_anchor_holds(FRESH_SOURCE.splitlines(), 4, 0)+++class TestRelocateSymbol:+ def test_relocate_finds_exact_symbol_id(self) -> None:+ located = relocate_symbol(_row(), SHIFTED_SOURCE)+ assert located is not None+ assert located[0] == 10++ def test_relocate_returns_none_for_missing_symbol(self) -> None:+ row = _row(name="ghost", symbol_id="pkg/mod.py::ghost")+ assert relocate_symbol(row, SHIFTED_SOURCE) is None++ def test_relocate_handles_unparseable_language(self) -> None:+ row = _row(language="no-such-language")+ assert relocate_symbol(row, SHIFTED_SOURCE) is None+++async def test_heal_symbol_row_persists_corrected_bounds(setup_mcp, factory, session):+ from sqlalchemy import select++ from repowise.core.persistence.models import Repository++ repo = (await session.execute(select(Repository))).scalars().first()+ row = _row(repository_id=repo.id)+ session.add(row)+ await session.commit()++ await heal_symbol_row(factory, row, 42, 57)++ from repowise.core.persistence.database import get_session++ async with get_session(factory) as s:+ healed = (await s.execute(select(WikiSymbol).where(WikiSymbol.id == row.id))).scalar_one()+ assert (healed.start_line, healed.end_line) == (42, 57)