Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
MCP get_answer/get_context tuning + in-code rationale retrieval (#621)
Raghav Chamadiya168ae5be4719
diff --git a/packages/core/src/repowise/core/analysis/decisions/extractor.py b/packages/core/src/repowise/core/analysis/decisions/extractor.pyindex 9278f2f70..98667d2af 100644--- a/packages/core/src/repowise/core/analysis/decisions/extractor.py+++ b/packages/core/src/repowise/core/analysis/decisions/extractor.py@@ -7,7 +7,8 @@ Capture sources (see ``decision_provenance.SOURCE_RANK`` for the trust ladder):4. ADR auto-discovery (Nygard/MADR records — deterministic parse first)5. CHANGELOG mining (keep-a-changelog Changed/Removed/Deprecated)6. PR / squash-body mining (commit bodies captured in git indexing)- 7. Comment archaeology (rationale prose on high-centrality code)+ 7. Comment archaeology (LLM rationale prose on high-centrality code)+ 8. In-code rationale harvest (deterministic, repo-wide comment markers)+ CLI capture (manual entry)Determinism-first: ADR/CHANGELOG are parsed structurally before any LLM call.@@ -31,6 +32,10 @@ from typing import Anyimport structlogfrom repowise.core.analysis.decisions.gate import apply_substring_gate+from repowise.core.analysis.decisions.rationale_comments import (+ CODE_EXTENSIONS,+ harvest_file_rationale,+)from .prompts import (_SYSTEM_PROMPT,@@ -259,6 +264,20 @@ _COMMENT_RATIONALE_CUES = ()_MAX_COMMENT_NODES = 30+# Deterministic in-code rationale harvest (Source 8). Unlike comment+# archaeology (LLM, top-30 central files, leading prose only) this is a+# repo-wide, LLM-free scan of every comment block for rationale markers. It is+# the index-time complement to the MCP live-grep miner: the same heuristics,+# but harvested into the queryable decision corpus rather than mined per query.+# Capped hard so a verbose file (or repo) can't flood the corpus, and emitted+# at low confidence / ``proposed`` so these rank below real ADRs.+_MAX_RATIONALE_PER_FILE = 3+# Generous safety bound for a pathological repo — not a target. Causal-marker+# gating keeps a typical repo well under this; if it is ever hit we LOG the+# truncation rather than silently dropping the tail.+_MAX_RATIONALE_TOTAL = 1500+_RATIONALE_HARVEST_CONFIDENCE = 0.3+# ---------------------------------------------------------------------------# ---------------------------------------------------------------------------# Main extractor@@ -1096,6 +1115,159 @@ class DecisionExtractor:decisions.extend(result)return decisions+ # ------------------------------------------------------------------+ # Source 8: In-code rationale harvest (deterministic, repo-wide)+ # ------------------------------------------------------------------++ async def harvest_rationale_comments(self) -> list[ExtractedDecision]:+ """Harvest rationale-bearing code comments into proposed decisions.++ Deterministic (no LLM, no graph required): scans every indexed source+ file for comment blocks carrying a rationale marker (``because``,+ ``instead of``, ``workaround``, ``NOTE:`` …) and emits each as a+ low-confidence ``proposed`` ``code_comment`` decision grounded by the+ verbatim comment. Shares its heuristics with the MCP live-grep miner+ (:mod:`repowise.core.analysis.decisions.rationale_comments`) so the+ index-time and query-time paths never drift.++ Hard precision guardrails live in ``harvest_file_rationale`` (marker+ required, license / shebang headers dropped, commented-out code+ dropped, thin comments dropped, per-file cap). The records are emitted+ ``proposed`` at low confidence so they rank below real ADRs and stay+ opt-in on high-signal surfaces. The substring gate is a no-op here —+ every gated field is the verbatim comment — but the records still flow+ through it for uniform verification stamping.+ """+ symbol_index = self._build_symbol_index()+ decisions: list[ExtractedDecision] = []+ truncated = False++ for file_path in self._iter_source_files():+ if len(decisions) >= _MAX_RATIONALE_TOTAL:+ truncated = True+ break+ ext = file_path.suffix.lower().lstrip(".")+ if ext not in CODE_EXTENSIONS:+ continue+ if not file_path.is_file():+ continue+ try:+ text = file_path.read_text(encoding="utf-8", errors="replace")+ except (OSError, UnicodeDecodeError):+ continue++ # require_causal=False: the guardrail wants any causal/INTENT+ # connective (the broad RATIONALE_MARKERS set), not only textbook+ # causal connectives. The canonical T4 comment that motivated this+ # feature (tool_symbol.py "…can never blow up… round-trip count is+ # what dominates token cost") is phrased with an intent marker, not+ # "because"/"so that" — a causal-only gate would drop the very+ # comment this exists to catch. Precision is held by the structural+ # guardrails (no docstrings/license/code/thin + per-file cap).+ harvested = harvest_file_rationale(+ text,+ ext,+ max_per_file=_MAX_RATIONALE_PER_FILE,+ require_causal=False,+ )+ if not harvested:+ continue++ try:+ rel_path = str(file_path.relative_to(self._repo_path)).replace("\\", "/")+ except ValueError:+ rel_path = str(file_path)++ for hc in harvested:+ if len(decisions) >= _MAX_RATIONALE_TOTAL:+ truncated = True+ break+ symbol = self._enclosing_symbol(symbol_index, rel_path, hc.start_line)+ if symbol:+ context = f"In `{symbol}` ({rel_path}:{hc.start_line})"+ else:+ context = f"{rel_path}:{hc.start_line}"+ decisions.append(+ ExtractedDecision(+ # Title is the model-free one-line summary; ungated, so+ # always survives. decision/source_quote are the verbatim+ # comment, so the gate stamps them ``exact``.+ title=self._comment_title(hc.text),+ context=context,+ decision=hc.text,+ source="code_comment",+ status="proposed",+ confidence=_RATIONALE_HARVEST_CONFIDENCE,+ evidence_file=rel_path,+ evidence_line=hc.start_line,+ affected_files=[rel_path],+ affected_modules=self._infer_modules([rel_path]),+ tags=self._infer_tags(hc.text),+ source_quote=hc.text,+ source_text=hc.text,+ )+ )++ if truncated:+ logger.warning(+ "decision_extractor.code_comment_harvest_truncated",+ cap=_MAX_RATIONALE_TOTAL,+ note="rationale-comment harvest hit its safety cap; tail dropped",+ )+ return decisions++ @staticmethod+ def _comment_title(text: str) -> str:+ """A short, single-line title for a harvested comment."""+ first = text.strip().splitlines()[0] if text.strip() else text+ first = re.sub(r"\s+", " ", first).strip()+ return first[:100]++ def _build_symbol_index(self) -> dict[str, list[tuple[int, int, str]]]:+ """Map each file's rel path → its symbols' ``(start, end, label)``.++ Built once per harvest from ``parsed_files`` (empty when unavailable).+ ``label`` is the qualified name when present, else the bare name.+ """+ index: dict[str, list[tuple[int, int, str]]] = {}+ for pf in self._parsed_files:+ fi = getattr(pf, "file_info", None)+ path = getattr(fi, "path", None)+ symbols = getattr(pf, "symbols", None)+ if not path or not symbols:+ continue+ rel = str(path).replace("\\", "/")+ entries: list[tuple[int, int, str]] = []+ for sym in symbols:+ start = getattr(sym, "start_line", None)+ end = getattr(sym, "end_line", None)+ if not isinstance(start, int) or not isinstance(end, int):+ continue+ label = getattr(sym, "qualified_name", "") or getattr(sym, "name", "")+ if label:+ entries.append((start, end, label))+ if entries:+ index[rel] = entries+ return index++ @staticmethod+ def _enclosing_symbol(+ index: dict[str, list[tuple[int, int, str]]],+ rel_path: str,+ line: int,+ ) -> str | None:+ """Return the innermost symbol whose line range contains ``line``."""+ entries = index.get(rel_path)+ if not entries:+ return None+ best: tuple[int, str] | None = None # (span_width, label) — smallest wins+ for start, end, label in entries:+ if start <= line <= end:+ width = end - start+ if best is None or width < best[0]:+ best = (width, label)+ return best[1] if best else None+# Above this node count, skip the iterative PageRank solve and use degree# centrality (O(nodes)) instead — comment archaeology only needs a rough# "most depended-on files" ranking, not exact PageRank, and the iterative@@ -1354,8 +1526,8 @@ class DecisionExtractor:*on_step* is an optional callable invoked with the source name as eachsub-extractor finishes (``inline_marker``, ``git_archaeology``,- ``readme_mining``, ``adr``, ``changelog``, ``pr``, ``comment``). Used by- the CLI to surface per-source progress.+ ``readme_mining``, ``adr``, ``changelog``, ``pr``, ``comment``,+ ``code_comment``). Used by the CLI to surface per-source progress.Every extracted decision is then put through the anti-hallucinationsubstring gate (:meth:`_apply_substring_gate`) before being returned —@@ -1384,6 +1556,7 @@ class DecisionExtractor:("changelog", self.mine_changelog),("pr", self.mine_pr_bodies),("comment", self.mine_comment_archaeology),+ ("code_comment", self.harvest_rationale_comments),]logger.info("decision_extractor.extract_all_start")@@ -1414,14 +1587,53 @@ class DecisionExtractor:# Helpers# ------------------------------------------------------------------+ def _tracked_files(self) -> set[Path] | None:+ """Resolved paths git tracks under ``repo_path``, or ``None``.++ ``None`` means "no git scoping available" (not a git repo, git missing,+ or the command failed) — callers then fall back to walking the tree.+ Restricting to tracked files keeps untracked / gitignored / git-excluded+ working directories (``local-stash/``, vendored dumps, scratch folders)+ out of the harvest: their comments are not part of the indexed codebase+ and must not become decision records.+ """+ import subprocess++ try:+ proc = subprocess.run(+ ["git", "-C", str(self._repo_path), "ls-files", "-z"],+ capture_output=True,+ timeout=30,+ check=False,+ )+ except (OSError, subprocess.SubprocessError):+ return None+ if proc.returncode != 0 or not proc.stdout:+ return None+ out = proc.stdout.decode("utf-8", errors="replace")+ tracked: set[Path] = set()+ for rel in out.split("\0"):+ if not rel:+ continue+ try:+ tracked.add((self._repo_path / rel).resolve())+ except OSError:+ continue+ return tracked or None+def _iter_source_files(self):"""Yield source files under repo_path, skipping irrelevant dirs.Uses os.walk so we can prune entire subtrees (nested git repos,- node_modules, etc.) without descending into them.+ node_modules, etc.) without descending into them. When the repo is a git+ checkout, the walk is further restricted to git-tracked files so+ untracked / excluded working directories never contribute decisions;+ gitless indexes fall back to the full walk."""import os+ tracked = self._tracked_files()+for dirpath, dirnames, filenames in os.walk(self._repo_path):# Prune skip-listed directories in-place so os.walk won't descenddirnames[:] = [@@ -1440,8 +1652,15 @@ class DecisionExtractor:for fname in filenames:fpath = Path(dirpath) / fname- if fpath.suffix.lower() not in _BINARY_EXTENSIONS:- yield fpath+ if fpath.suffix.lower() in _BINARY_EXTENSIONS:+ continue+ if tracked is not None:+ try:+ if fpath.resolve() not in tracked:+ continue+ except OSError:+ continue+ yield fpathdef _get_neighbors(self, file_path: str) -> list[str]:"""Get 1-hop graph neighbors for a file."""diff --git a/packages/core/src/repowise/core/analysis/decisions/provenance.py b/packages/core/src/repowise/core/analysis/decisions/provenance.pyindex 43abbfe60..c6df4bf69 100644--- a/packages/core/src/repowise/core/analysis/decisions/provenance.py+++ b/packages/core/src/repowise/core/analysis/decisions/provenance.py@@ -43,8 +43,9 @@ SOURCE_RANK: dict[str, int] = {"git_archaeology": 6, # alias for commit-mined decisions"changelog": 5, # keep-a-changelog Changed/Removed/Deprecated"inline_marker": 4, # # WHY: / # DECISION: code markers- "comment": 3, # rationale prose in block comments / docstrings+ "comment": 3, # LLM-curated rationale prose on high-centrality code"readme_mining": 3, # implicit decisions in README/docs prose+ "code_comment": 2, # deterministic rationale-marker comment harvest (heuristic)"test_name": 2, # placeholder — behaviour asserted by a test name"inferred": 1, # placeholder — purely inferred, no verbatim source"llm_inferred": 1, # Phase 2 LLM-docs harvestdiff --git a/packages/core/src/repowise/core/analysis/decisions/rationale_comments.py b/packages/core/src/repowise/core/analysis/decisions/rationale_comments.pynew file mode 100644index 000000000..8c639e06e--- /dev/null+++ b/packages/core/src/repowise/core/analysis/decisions/rationale_comments.py@@ -0,0 +1,639 @@+"""Rationale-comment mining — the shared heuristics for recovering the "why"+that lives in ordinary source comments rather than in an ADR / decision record.++A large share of real architectural intent never becomes a decision record; it+sits in a code comment instead::++ # We retry on 429 here rather than in the client because the client is+ # shared across tenants and a global backoff would starve everyone.++Two consumers want exactly the same comment-extraction + rationale-marker+heuristics, so they live here once:++* the **index-time** decision-extractor pass+ (:meth:`repowise.core.analysis.decisions.extractor.DecisionExtractor.harvest_rationale_comments`)+ which harvests these into low-confidence ``proposed`` decision records so they+ enter the queryable corpus with full retrieval/ranking/citation treatment, and+* the **query-time** MCP live-grep miner (``mcp_server/_code_rationale.py``),+ the best-effort recall backstop for un-indexed / just-edited files.++Keeping one implementation here means the marker list and the comment tokenizer+never drift between the two paths.++This module is deliberately dependency-free (stdlib only) so both the core+ingestion pipeline and the server layer can import it without a cycle.+"""++from __future__ import annotations++import re+from dataclasses import dataclass, field++__all__ = [+ "RATIONALE_MARKERS",+ "CAUSAL_MARKERS",+ "LINE_PREFIXES",+ "C_BLOCK_EXTS",+ "CODE_EXTENSIONS",+ "CommentBlock",+ "HarvestedComment",+ "extract_comment_blocks",+ "has_rationale_marker",+ "has_causal_marker",+ "marker_strength",+ "is_license_or_boilerplate",+ "looks_like_commented_out_code",+ "harvest_file_rationale",+]++# ---------------------------------------------------------------------------+# Rationale markers+# ---------------------------------------------------------------------------+# A comment earns surfacing only if it reads like a *reason*, not a label.+# These are the causal / intent connectives and the well-known intent tags.+# Matched as lowercased substrings against the comment text. Curated to favor+# precision: a URL or a boilerplate header won't contain "because"/"instead".+RATIONALE_MARKERS: tuple[str, ...] = (+ "because",+ "instead of",+ "rather than",+ "in order to",+ "to avoid",+ "avoids ",+ "avoid ",+ "work around",+ "workaround",+ "so that",+ "otherwise",+ "due to",+ "to prevent",+ "prevents ",+ "the reason",+ "reason:",+ "intentional",+ "intentionally",+ "deliberate",+ "deliberately",+ "on purpose",+ "we use ",+ "we don't",+ "we do not",+ "we can't",+ "we cannot",+ "must not",+ "never ",+ "always ",+ "fall back",+ "fallback",+ "legacy",+ "historical",+ "backward compat",+ "backwards compat",+ "for performance",+ "perf:",+ "hot path",+ "deadlock",+ "race condition",+ "thread-safe",+ "thread safe",+ "this is why",+ "the trick",+ "subtle",+ "tricky",+ "gotcha",+ "caveat",+ "hack",+ "fixme",+ "xxx:",+ "note:",+ "nb:",+ "important:",+ "warning:",+ "defense in depth",+ "edge case",+ "do not remove",+ "don't remove",+)++# The strong subset: markers that state an actual *reason*, an alternative+# rejected, or a deliberate choice — as opposed to a bare intent label+# (``note:``, ``always``, ``we use``). The index-time decision harvest requires+# one of these so a ``code_comment`` record always carries a genuine rationale;+# the MCP recall miner uses the full ``RATIONALE_MARKERS`` set instead.+CAUSAL_MARKERS: tuple[str, ...] = (+ "because",+ "instead of",+ "rather than",+ "in order to",+ "to avoid",+ "avoids ",+ "avoid ",+ "work around",+ "workaround",+ "so that",+ "otherwise",+ "due to",+ "to prevent",+ "prevents ",+ "the reason",+ "reason:",+ "on purpose",+ "intentional",+ "intentionally",+ "deliberate",+ "deliberately",+ "for performance",+ "this is why",+ "do not remove",+ "don't remove",+)++# ---------------------------------------------------------------------------+# Comment syntax per file extension+# ---------------------------------------------------------------------------+# Line-comment prefixes keyed by extension. Kept pragmatic: covers the+# languages that make up the overwhelming majority of indexed source.+LINE_PREFIXES: dict[str, tuple[str, ...]] = {+ "py": ("#",),+ "pyi": ("#",),+ "sh": ("#",),+ "bash": ("#",),+ "rb": ("#",),+ "yaml": ("#",),+ "yml": ("#",),+ "toml": ("#",),+ "r": ("#",),+ "pl": ("#",),+ "js": ("//",),+ "jsx": ("//",),+ "ts": ("//",),+ "tsx": ("//",),+ "mjs": ("//",),+ "cjs": ("//",),+ "go": ("//",),+ "rs": ("//",),+ "c": ("//",),+ "h": ("//",),+ "cc": ("//",),+ "cpp": ("//",),+ "hpp": ("//",),+ "java": ("//",),+ "kt": ("//",),+ "kts": ("//",),+ "swift": ("//",),+ "scala": ("//",),+ "cs": ("//",),+ "php": ("//", "#"),+ "dart": ("//",),+ "sql": ("--",),+ "lua": ("--",),+ "hs": ("--",),+ "elm": ("--",),+}++# Extensions that use C-style /* ... */ block comments.+C_BLOCK_EXTS: frozenset[str] = frozenset(+ {+ "js",+ "jsx",+ "ts",+ "tsx",+ "mjs",+ "cjs",+ "go",+ "rs",+ "c",+ "h",+ "cc",+ "cpp",+ "hpp",+ "java",+ "kt",+ "kts",+ "swift",+ "scala",+ "cs",+ "php",+ "dart",+ }+)++# The set of extensions this module can mine — anything we know a comment+# syntax for. Markdown / RST / plain text are deliberately excluded: their+# prose is full of causal words ("because") that are not code rationale, and+# README / docs already feed the readme_mining source.+CODE_EXTENSIONS: frozenset[str] = frozenset(LINE_PREFIXES) | C_BLOCK_EXTS++# ---------------------------------------------------------------------------+# Boilerplate / commented-out-code detection+# ---------------------------------------------------------------------------+# License headers, SPDX tags, copyright notices — the dominant false-positive+# class for a top-of-file comment block.+_LICENSE_RE = re.compile(+ r"""(+ copyright+ | \(c\)\s*\d{4}+ | spdx-license-identifier+ | all\ rights\ reserved+ | licensed\ under+ | redistribution\ and\ use+ | permission\ is\ hereby\ granted+ | gnu\ (general|lesser)\ public\ license+ | mit\ license+ | apache\ license+ | bsd\ license+ | this\ (file|software|program)\ is\ (free\ software|distributed)+ )""",+ re.IGNORECASE | re.VERBOSE,+)++# Encoding / shebang / editor-mode lines that lead a file.+_FILE_PREAMBLE_RE = re.compile(+ r"(-\*-\s*coding|coding[:=]\s*[-\w.]+|!/usr/bin|!/bin/|vim:|emacs:)",+ re.IGNORECASE,+)++# A line that "reads like code" rather than prose. Heuristic, not a parser:+# used only to drop commented-out code blocks that slipped past the marker gate.+_CODE_LINE_RE = re.compile(+ r"""(+ [;{}]\s*$ # ends with ; { or }+ | ^\s*(def|class|return|import|from|if|elif|else|for|while|try+ |except|finally|with|raise|yield|async|await|public|private+ |protected|static|void|func|fn|impl|struct|enum|const|let+ |var|package|module|export|require)\b+ | => # arrow funcs / fat arrows+ | ^\s*@[\w.]+\s*\(? # decorators / annotations+ | ^\s*[\w.\[\]]+\s*=\s*\S # assignment+ | \w+\([^)]*\)\s*[:{;]?\s*$ # bare call / signature line+ )""",+ re.VERBOSE,+)++# A line carrying enough natural-language to count as prose: several word-ish+# tokens and no trailing code punctuation.+_WORD_RE = re.compile(r"[A-Za-z']{2,}")++# Bounds — keep a single harvested quote from flooding the corpus.+_MIN_COMMENT_CHARS = 25+_MIN_COMMENT_WORDS = 5+_MAX_COMMENT_CHARS = 600+_MAX_BLOCK_LINES = 12+++@dataclass(frozen=True)+class CommentBlock:+ """A contiguous comment span. 1-indexed, inclusive line bounds."""++ start_line: int+ end_line: int+ text: str # cleaned, single-spaced join of the comment body+ body_lines: tuple[str, ...] = field(default_factory=tuple) # per-line bodies+ kind: str = "line" # "line" | "block" (/* */) | "doc" (triple-quoted)+++@dataclass(frozen=True)+class HarvestedComment:+ """A rationale comment that passed every precision guardrail."""++ start_line: int+ end_line: int+ text: str+ strength: int # number of distinct rationale markers present+++# ---------------------------------------------------------------------------+# Comment tokenizer+# ---------------------------------------------------------------------------+++def _strip_comment_open(stripped: str, prefixes: tuple[str, ...]) -> str | None:+ """If ``stripped`` begins with a line-comment prefix, return the text after+ it; else None. Handles ``# x``, ``// x``, ``-- x`` and a bare ``#``."""+ for p in prefixes:+ if stripped.startswith(p):+ return stripped[len(p) :].lstrip()+ return None+++# A line that is only a divider rule (``# -------`` / ``// =====`` / ``***``).+# These delimit comment runs and must never be glued into the rationale text.+_SEPARATOR_CHARS = frozenset("-=*~_#/+.<> ")+++def _is_separator(body: str) -> bool:+ s = body.strip()+ return len(s) >= 3 and all(c in _SEPARATOR_CHARS for c in s)+++def _trailing_comment(line: str, prefixes: tuple[str, ...]) -> str | None:+ """Recover a trailing inline comment (``x = 1 # because ...``).++ Conservative: requires whitespace before the marker so we don't trip on+ ``//`` inside a URL or ``#`` inside a string literal. Only the query-time+ MCP recall miner enables this (``include_trailing=True``); the index-time+ harvest leaves it off because trailing comments are almost always labels.+ """+ best: str | None = None+ best_idx = len(line) + 1+ for p in prefixes:+ idx = line.find(" " + p + " ")+ if idx == -1:+ idx = line.find("\t" + p)+ if idx != -1 and idx < best_idx:+ head = line[:idx].strip()+ if head:+ best_idx = idx+ best = line[idx:].lstrip()[len(p) :].lstrip()+ return best+++def extract_comment_blocks(+ text: str, ext: str, *, include_trailing: bool = False+) -> list[CommentBlock]:+ """Return every comment block in ``text`` for a file of extension ``ext``.++ Consecutive full-line comments coalesce into one block (a multi-line+ rationale paragraph stays intact). Also recovers C-style ``/* */`` blocks+ and Python triple-quoted docstrings.++ Trailing inline comments (``x = 1 # because ...``) are captured only when+ ``include_trailing`` is set. At index time they are almost always labels,+ not rationale, so the decision harvest leaves it off (the default); the+ query-time MCP recall miner sets it ``True`` for maximum recall.+ Best-effort tokenizing, not a real parser.+ """+ ext = ext.lower()+ prefixes = LINE_PREFIXES.get(ext, ())+ lines = text.splitlines()+ blocks: list[CommentBlock] = []++ cur_start = 0+ cur_parts: list[str] = []++ def _flush() -> None:+ nonlocal cur_start, cur_parts+ if cur_parts:+ joined = " ".join(p for p in cur_parts if p).strip()+ if joined:+ blocks.append(+ CommentBlock(+ start_line=cur_start,+ end_line=cur_start + len(cur_parts) - 1,+ text=joined,+ body_lines=tuple(cur_parts),+ kind="line",+ )+ )+ cur_start = 0+ cur_parts = []++ in_c_block = False+ in_pydoc = False+ pydoc_delim = ""+ block_start = 0+ block_parts: list[str] = []+ has_c_block = ext in C_BLOCK_EXTS+ has_pydoc = ext in ("py", "pyi")++ for i, raw in enumerate(lines, start=1):+ stripped = raw.strip()++ # --- inside a /* ... */ block ---+ if in_c_block:+ end = stripped.find("*/")+ seg = stripped[: end if end != -1 else len(stripped)]+ block_parts.append(seg.lstrip("*").strip())+ if end != -1:+ in_c_block = False+ joined = " ".join(p for p in block_parts if p).strip()+ if joined:+ blocks.append(+ CommentBlock(block_start, i, joined, tuple(block_parts), "block")+ )+ block_parts = []+ continue++ # --- inside a python docstring ---+ if in_pydoc:+ end = stripped.find(pydoc_delim)+ seg = stripped[: end if end != -1 else len(stripped)]+ block_parts.append(seg.strip())+ if end != -1:+ in_pydoc = False+ joined = " ".join(p for p in block_parts if p).strip()+ if joined:+ blocks.append(+ CommentBlock(block_start, i, joined, tuple(block_parts), "doc")+ )+ block_parts = []+ continue++ # --- full-line comment ---+ body = _strip_comment_open(stripped, prefixes) if prefixes else None+ if body is not None:+ # A divider rule ends the current run and is itself discarded, so a+ # section banner never glues two unrelated comments together.+ if _is_separator(body):+ _flush()+ continue+ if not cur_parts:+ cur_start = i+ cur_parts.append(body)+ continue++ # not a full-line comment → flush any pending run+ _flush()++ # --- start of a /* ... */ block ---+ if has_c_block and "/*" in stripped:+ open_idx = stripped.find("/*")+ close_idx = stripped.find("*/", open_idx + 2)+ if close_idx != -1:+ seg = stripped[open_idx + 2 : close_idx].strip()+ if seg:+ blocks.append(CommentBlock(i, i, seg, (seg,), "block"))+ else:+ in_c_block = True+ block_start = i+ block_parts = [stripped[open_idx + 2 :].lstrip("*").strip()]+ continue++ # --- start of a python docstring (module / class / function doc) ---+ if has_pydoc:+ m = re.match(r'^[rbRB]?("""|\'\'\')', stripped)+ if m:+ pydoc_delim = m.group(1)+ rest = stripped[m.end() :]+ close = rest.find(pydoc_delim)+ if close != -1:+ seg = rest[:close].strip()+ if seg:+ blocks.append(CommentBlock(i, i, seg, (seg,), "doc"))+ else:+ in_pydoc = True+ block_start = i+ block_parts = [rest.strip()]+ continue++ # --- trailing inline comment (recall miner only) ---+ if include_trailing and prefixes:+ tail = _trailing_comment(raw, prefixes)+ if tail:+ blocks.append(CommentBlock(i, i, tail, (tail,), "line"))++ _flush()+ return blocks+++# ---------------------------------------------------------------------------+# Guardrails+# ---------------------------------------------------------------------------+++def has_rationale_marker(text: str) -> bool:+ """True if ``text`` carries any rationale / intent marker."""+ low = text.lower()+ return any(m in low for m in RATIONALE_MARKERS)+++def has_causal_marker(text: str) -> bool:+ """True if ``text`` states an actual reason / alternative / deliberate+ choice (the strong :data:`CAUSAL_MARKERS` subset)."""+ low = text.lower()+ return any(m in low for m in CAUSAL_MARKERS)+++def marker_strength(text: str) -> int:+ """Count of distinct rationale markers present — used to rank a file's+ comments so the strongest survive the per-file cap."""+ low = text.lower()+ return sum(1 for m in RATIONALE_MARKERS if m in low)+++def is_license_or_boilerplate(text: str) -> bool:+ """True for license headers, SPDX tags, copyright notices, shebang /+ encoding preambles — the dominant top-of-file false positives."""+ return bool(_LICENSE_RE.search(text) or _FILE_PREAMBLE_RE.search(text))+++def _is_prose_line(s: str) -> bool:+ """A line that reads like a sentence fragment, not a statement of code."""+ if _CODE_LINE_RE.search(s):+ return False+ return len(_WORD_RE.findall(s)) >= 3+++def looks_like_commented_out_code(body_lines: tuple[str, ...]) -> bool:+ """True when a comment block is disabled code, not a rationale paragraph.++ A genuine rationale carries at least one prose sentence; commented-out code+ is all statements. We drop a block that has no prose line, or whose code+ lines dominate prose by more than 2:1.+ """+ code = 0+ prose = 0+ for ln in body_lines:+ s = ln.strip()+ if not s:+ continue+ if _is_prose_line(s):+ prose += 1+ elif _CODE_LINE_RE.search(s):+ code += 1+ if code == 0:+ return False+ if prose == 0:+ return True+ return code > prose * 2+++def _too_thin(text: str) -> bool:+ """A comment too short / sparse to be a real rationale."""+ if len(text) < _MIN_COMMENT_CHARS:+ return True+ return len(_WORD_RE.findall(text)) < _MIN_COMMENT_WORDS+++# Leading comment cruft to strip from a surfaced quote (Sphinx ``#:`` markers,+# stray dividers, bullet glyphs) so the title/quote reads as prose.+_LEADING_JUNK_RE = re.compile(r"^[\s:#*/\-=.>•·]+")+++def _clean(text: str) -> str:+ return _LEADING_JUNK_RE.sub("", text).strip()+++def _truncate(text: str) -> str:+ if len(text) > _MAX_COMMENT_CHARS:+ return text[: _MAX_COMMENT_CHARS - 1].rstrip() + "…"+ return text+++def harvest_file_rationale(+ text: str,+ ext: str,+ *,+ max_per_file: int = 3,+ include_docstrings: bool = False,+ require_causal: bool = True,+) -> list[HarvestedComment]:+ """Mine the rationale-bearing comments from one file's text.++ Applies every precision guardrail (rationale marker required, license /+ preamble headers dropped, commented-out code dropped, thin comments+ dropped) and returns at most ``max_per_file`` blocks, strongest first.++ ``ext`` must name a known code extension; non-code files return ``[]``.++ ``include_docstrings`` is ``False`` for the index-time decision harvest:+ triple-quoted docstrings are the documented API surface (already mined by+ the page generator / readme sources) and would flood the decision corpus.+ The hidden rationale this targets lives in ``#`` / ``//`` / ``/* */``+ comments. The MCP live-grep miner sets it ``True`` for maximum recall.++ ``require_causal`` (index-time default) demands a strong+ :data:`CAUSAL_MARKERS` reason rather than any intent label, so every+ ``code_comment`` decision carries a genuine rationale. The MCP recall miner+ sets it ``False`` to surface any marker-bearing comment.+ """+ ext = ext.lower()+ if ext not in CODE_EXTENSIONS:+ return []+ try:+ blocks = extract_comment_blocks(text, ext)+ except Exception:+ # A tokenizer edge case must never break ingestion.+ return []++ marker_test = has_causal_marker if require_causal else has_rationale_marker+ kept: list[HarvestedComment] = []+ for b in blocks:+ if b.kind == "doc" and not include_docstrings:+ continue+ body = _clean(b.text)+ if _too_thin(body):+ continue+ if not marker_test(body):+ continue+ # License / SPDX / shebang preamble is the dominant false positive.+ if is_license_or_boilerplate(body):+ continue+ if looks_like_commented_out_code(b.body_lines):+ continue++ end = b.end_line+ if end - b.start_line + 1 > _MAX_BLOCK_LINES:+ end = b.start_line + _MAX_BLOCK_LINES - 1+ kept.append(+ HarvestedComment(+ start_line=b.start_line,+ end_line=end,+ text=_truncate(body),+ strength=marker_strength(body),+ )+ )++ # Strongest markers first; stable on ties (earlier in file wins).+ kept.sort(key=lambda h: h.strength, reverse=True)+ return kept[:max_per_file]diff --git a/packages/core/src/repowise/core/generation/templates/claude_md.j2 b/packages/core/src/repowise/core/generation/templates/claude_md.j2index 362a25f8e..4a8746eaa 100644--- a/packages/core/src/repowise/core/generation/templates/claude_md.j2+++ b/packages/core/src/repowise/core/generation/templates/claude_md.j2@@ -113,11 +113,11 @@ 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 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_answer(question)` | Synthesised answer with citations and a content-grounded `confidence`. First call for "how does X work" / "where is Y" / "why is Z" — and the one-shot for "explain function/method/class X": when the question names an indexed symbol, get_answer anchors its defining file (even when fuzzy retrieval would miss it) and returns the symbol's full live body in `symbol_bodies` — read that instead of a `get_symbol` follow-up. Value questions may return `grounding: "extracted"` (verbatim source line). On low confidence returns `best_guesses` with one-line justifications, plus `code_rationale` (rationale comments mined live from the candidate source) when the "why" lives in a code comment the wiki never captured. || `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, mode?, kind?, symbol_kind?)` | Hybrid code search. `mode="auto"` (default) routes by query shape: an identifier → indexed symbol hits (`symbol_id`/`file`/line bounds — pipe into `get_symbol`), a path → file pages (pipe into `get_context`), prose → wiki-semantic search, mixed → hybrid (symbols first). Force a branch with `mode=symbol\|path\|concept\|hybrid`. Concept hits carry `search_method` (`embedding` vs `bm25` fallback); decision records rank below file pages unless the query is why-shaped. |-| `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_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, and to `code_rationale` (rationale comments mined from the source) when neither decisions nor git history explain it. || `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_health(targets?, include?)` | Code-health scores + biomarker findings (defect / maintainability / performance pillars). Self-check before a PR — read the same signals the merge-gate judges your change on. Default is lean; opt in with `include`: `["accuracy"]` (does the score rank the buggy files first — precision@K + `lift`), `["signals"]` (per-file prior-defects / churn / owners / degree, targeted mode), `["churn_complexity"]` (volatile-and-complex danger-zone files), `["biomarkers"]` (all findings), and a dimension name `["performance"]` / `["defect"]` / `["maintainability"]` to filter findings to one pillar. || `get_dead_code(...)` | Tiered unreachable / unused-export / zombie-package findings. Run before a cleanup sprint, not before a targeted fix. |@@ -125,10 +125,12 @@ This repo has the Repowise MCP server configured. The tools below answer questio**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.+- `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. `symbol_bodies` entries `{path, name, lines, source}` are the full live body of a named definition — read that body, do not call `get_symbol` for the same symbol (a `continuation` token names the next range if it was truncated).+- `code_rationale` entries `{path, lines, comment}` (on a low-confidence `get_answer` or a fallen-back `get_why`) are rationale comments read live from the source. When the "why" you asked for is a code comment rather than an ADR, the comment is right there: cite it instead of opening the file to hunt for it.+- 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. On a **large file** `get_symbol("path::Name")` is the win — it serves one verified body instead of pulling the whole file into context.- 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).+- When a plain `Grep` is the right tool, use it: an exhaustive literal-token sweep (rename every call site, find all occurrences) is one grep and unbeatable on cost. MCP's edge there is not fewer tokens — it is the `callers_total`/`callers_truncated` honesty signal that tells you whether a list is complete; reach for `get_context(include=["callers"])` when silent incompleteness would bite.**Composition tips:**- `get_answer` → if `confidence` is `medium`/`low`, follow `best_guesses[0].file` or `fallback_targets[0]` into `get_context`, then `get_symbol` for bytes.diff --git a/packages/core/src/repowise/core/pipeline/phases/analysis.py b/packages/core/src/repowise/core/pipeline/phases/analysis.pyindex f6b25654b..0a7572037 100644--- a/packages/core/src/repowise/core/pipeline/phases/analysis.py+++ b/packages/core/src/repowise/core/pipeline/phases/analysis.py@@ -258,9 +258,9 @@ async def _run_decision_extraction(try:from repowise.core.analysis.decision_extractor import DecisionExtractor- # Seven sources run concurrently inside extract_all(); drive a+ # Eight sources run concurrently inside extract_all(); drive a# determinate bar so users see live progress.- decision_steps = 7+ decision_steps = 8if progress:progress.on_phase_start("decisions", decision_steps)@@ -293,6 +293,7 @@ async def _run_decision_extraction(f"{bs.get('pr', 0)} PR · "f"{bs.get('git_archaeology', 0)} git · "f"{bs.get('comment', 0)} comments · "+ f"{bs.get('code_comment', 0)} code-comments · "f"{bs.get('readme_mining', 0)} docs",)diff --git a/packages/server/src/repowise/server/mcp_server/_code_rationale.py b/packages/server/src/repowise/server/mcp_server/_code_rationale.pynew file mode 100644index 000000000..a5f86f5f4--- /dev/null+++ b/packages/server/src/repowise/server/mcp_server/_code_rationale.py@@ -0,0 +1,272 @@+"""In-code rationale mining — recover the "why" that lives in source comments.++The decision layer (ADRs / decision records) and the wiki page corpus only+capture rationale someone wrote DOWN as a decision. A large share of real+intent lives in ordinary code comments instead:++ # We retry on 429 here rather than in the client because the client+ # is shared across tenants and a global backoff would starve everyone.++`get_why` and `get_answer` both miss that: get_why searches decisions + git+archaeology, get_answer retrieves over wiki pages. Neither reads the source+comments. The unbiased A/B (task T4) confirmed the gap — when the rationale+was a code comment, get_answer returned low confidence and the agent fell+back to Read+Grep, losing on tokens AND round-trips.++This module is the **query-time recall backstop**. The durable fix is the+index-time decision harvest (Source 8,+:meth:`repowise.core.analysis.decisions.extractor.DecisionExtractor.harvest_rationale_comments`)+which lands these comments in the queryable decision corpus. This miner only+earns its keep for what the index can't cover: files edited since the last+index, and comment shapes the index-time gate drops (trailing inline comments,+intent-only markers, docstrings). The comment tokenizer and the rationale+marker list are shared with that harvest — both import from+:mod:`repowise.core.analysis.decisions.rationale_comments` so the two paths+never drift.++It is deliberately wired only into the LOW-confidence exits (get_answer's+gated / hedged paths, get_why's no-decision fallback): when the confident+corpus already answered, mining source comments buys nothing and only bloats+the payload. Reads are bounded and per-file failures are swallowed — this can+never break a tool response.+"""++from __future__ import annotations++import logging+import re+from pathlib import Path+from typing import Any++from repowise.core.analysis.decisions.rationale_comments import (+ RATIONALE_MARKERS,+ extract_comment_blocks,+)++_log = logging.getLogger("repowise.mcp.code_rationale")++# Stopwords stripped from the question before term overlap. Short, generic+# interrogatives that would match almost any comment.+_STOPWORDS: frozenset[str] = frozenset(+ {+ "the",+ "a",+ "an",+ "this",+ "that",+ "these",+ "those",+ "why",+ "how",+ "what",+ "when",+ "where",+ "which",+ "who",+ "is",+ "are",+ "was",+ "were",+ "be",+ "been",+ "being",+ "do",+ "does",+ "did",+ "for",+ "to",+ "of",+ "in",+ "on",+ "at",+ "by",+ "it",+ "its",+ "and",+ "or",+ "but",+ "with",+ "from",+ "into",+ "we",+ "you",+ "use",+ "used",+ "uses",+ "using",+ "work",+ "works",+ "code",+ "get",+ "set",+ "here",+ "there",+ "than",+ "then",+ "so",+ "as",+ "if",+ "not",+ "no",+ }+)++# Bounds — best-effort means cheap. Never scan a giant generated file, never+# return a wall of text.+_MAX_FILES = 6+_MAX_FILE_LINES = 8000+_MAX_BLOCK_LINES = 12+_MAX_BLOCK_CHARS = 800+_MAX_RESULTS = 6+_NEAR_LINE_WINDOW = 60+++def _content_terms(query: str | None) -> set[str]:+ """Lowercased alnum tokens from the query, stopwords + len<3 dropped."""+ if not query:+ return set()+ raw = re.findall(r"[a-zA-Z0-9_]+", query.lower())+ return {t for t in raw if len(t) >= 3 and t not in _STOPWORDS}+++def _score_block(comment: str, terms: set[str]) -> tuple[float, list[str], bool]:+ """Score a comment block. Returns (score, matched_terms, has_marker).++ Rationale marker = 2.0; each distinct query term present = 1.0. Uses the+ broad ``RATIONALE_MARKERS`` set (intent + causal) shared with the index-time+ harvest — recall mode, so intent-only markers ("never", "always") count.+ """+ low = comment.lower()+ has_marker = any(m in low for m in RATIONALE_MARKERS)+ matched = sorted(t for t in terms if t in low)+ score = (2.0 if has_marker else 0.0) + float(len(matched))+ return score, matched, has_marker+++def _keep(score: float, matched: list[str], has_marker: bool, has_terms: bool) -> bool:+ """Surfacing gate. With query terms: need a marker+term overlap, or a+ strong (>=2 terms) overlap on its own. Without query terms (path-mode+ "why is this file shaped this way"): a rationale marker is enough."""+ if not has_terms:+ return has_marker+ if has_marker and matched:+ return True+ return len(matched) >= 2+++def _read_text(repo_root: Path, file_path: str) -> str | None:+ """Read a repo file's live text, refusing paths outside the root."""+ try:+ abs_path = (repo_root / file_path).resolve()+ abs_path.relative_to(repo_root.resolve())+ except (ValueError, OSError):+ return None+ try:+ if abs_path.stat().st_size > _MAX_FILE_LINES * 400:+ return None+ return abs_path.read_text(encoding="utf-8", errors="replace")+ except OSError:+ return None+++def _truncate_block(comment: str) -> str:+ """Bound a single surfaced block so a long docstring can't flood the+ payload."""+ if len(comment) > _MAX_BLOCK_CHARS:+ return comment[: _MAX_BLOCK_CHARS - 1].rstrip() + "…"+ return comment+++def mine_rationale(+ repo_root: Any,+ file_paths: list[str],+ query: str | None,+ *,+ near_lines: dict[str, int] | None = None,+ max_files: int = _MAX_FILES,+ max_results: int = _MAX_RESULTS,+) -> list[dict]:+ """Mine in-code rationale comments from ``file_paths``.++ Args:+ repo_root: the repo root (ctx.path); when falsy, returns [].+ file_paths: already-relevant files to scan (deduped, capped).+ query: the question / context terms to overlap against. May be None+ (path-mode), in which case marker-bearing comments are returned.+ near_lines: optional {path: line} to boost comments near an anchored+ symbol (e.g. the definition the question named).++ Returns a ranked list of ``{path, lines: [start, end], comment,+ matched_terms}`` — at most ``max_results``. Best-effort: never raises.++ Recall mode: docstrings (``kind == "doc"``) and trailing inline comments+ are kept (``include_trailing=True``), using the broad ``RATIONALE_MARKERS``+ set. The index-time harvest deliberately drops both — this miner is the+ backstop for exactly that material.+ """+ if not repo_root or not file_paths:+ return []+ try:+ root = Path(str(repo_root))+ except Exception:+ return []++ terms = _content_terms(query)+ has_terms = bool(terms)+ near_lines = near_lines or {}++ # Dedupe while preserving order; cap the file fan-out.+ seen: set[str] = set()+ ordered: list[str] = []+ for p in file_paths:+ if p and p not in seen:+ seen.add(p)+ ordered.append(p)+ ordered = ordered[:max_files]++ scored: list[tuple[float, bool, dict]] = []+ for path in ordered:+ ext = path.rsplit(".", 1)[-1].lower() if "." in path else ""+ text = _read_text(root, path)+ if text is None or text.count("\n") > _MAX_FILE_LINES:+ continue+ near = near_lines.get(path)+ try:+ blocks = extract_comment_blocks(text, ext, include_trailing=True)+ except Exception as exc: # never let a tokenizer bug break a tool+ _log.debug("comment extraction failed for %s: %s", path, exc)+ continue+ for block in blocks:+ start, end, comment = block.start_line, block.end_line, block.text+ score, matched, has_marker = _score_block(comment, terms)+ if not _keep(score, matched, has_marker, has_terms):+ continue+ if near is not None and abs(start - near) <= _NEAR_LINE_WINDOW:+ score += 1.5+ # Coalesced runs longer than the cap are split at the head — the+ # lead lines carry the rationale; tail is usually elaboration.+ if end - start + 1 > _MAX_BLOCK_LINES:+ end = start + _MAX_BLOCK_LINES - 1+ scored.append(+ (+ score,+ has_marker,+ {+ "path": path,+ "lines": [start, end],+ "comment": _truncate_block(comment),+ "matched_terms": matched,+ },+ )+ )++ # Precision: a comment with an explicit rationale marker IS the "why". When+ # any survive, drop the marker-less blocks that only cleared the >=2-term+ # gate — on a query with generic terms (lines / source / one) those are+ # usually plain docstrings that read as noise next to the real rationale.+ # The term-only blocks remain the recall fallback when nothing has a marker.+ if any(m for _, m, _ in scored):+ scored = [t for t in scored if t[1]]++ scored.sort(key=lambda t: t[0], reverse=True)+ return [entry for _, _, entry in scored[:max_results]]diff --git a/packages/server/src/repowise/server/mcp_server/_meta.py b/packages/server/src/repowise/server/mcp_server/_meta.pyindex ab97f54e9..d245fd739 100644--- a/packages/server/src/repowise/server/mcp_server/_meta.py+++ b/packages/server/src/repowise/server/mcp_server/_meta.py@@ -122,10 +122,9 @@ def freshness_from_repo(repository: Any | None) -> dict[str, Any]:if live_full and indexed_full:if live_full != indexed_full:out["live_head"] = live_full[:12]- out["stale_warning"] = (- f"Index built at {indexed_full[:12]} but HEAD is at "- f"{live_full[:12]} — code has moved on. Run `repowise update`."- )+ # The two SHAs are already in ``indexed_commit`` / ``live_head`` —+ # don't repeat them in prose. Just the directive.+ out["stale_warning"] = "Index is behind live HEAD — run `repowise update`."# Match: deliberately emit nothing extra. Silence is the signal.elif live_full is None and age_days is not None and age_days > _STALE_AGE_FLOOR_DAYS:# No git signal available and the index is genuinely old.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 6c1d9bc6b..a222fb0ea 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@@ -10,6 +10,11 @@ search → context → read loop with one tool call that returns:"fallback_targets": list — top retrieval hits the agent should Readto verify (always present)"retrieval": list — raw top-N hits with snippets+ "symbol_bodies": list — full live body of each question-named+ definition (collapses the get_symbol+ follow-up); present only when the answer+ names a function/method/class that was+ hydrated}When no LLM provider is configured, the tool degrades to retrieval-only@@ -29,6 +34,7 @@ import contextlibimport json as _jsonimport loggingimport time+from pathlib import Pathfrom sqlalchemy import delete, select@@ -55,6 +61,7 @@ from repowise.server.mcp_server._answer_pipeline import (hybrid_retrieve as _hybrid_retrieve,)from repowise.server.mcp_server._answer_pipeline import hydrate_hits as _hydrate_hits+from repowise.server.mcp_server._code_rationale import mine_rationale as _mine_rationalefrom repowise.server.mcp_server._helpers import (_get_exclude_spec,_get_repo,@@ -77,6 +84,8 @@ from repowise.server.mcp_server.tool_answer.config import (_ENRICH_TOP_N_HITS,_GATED_RETURN_HITS,_HIGH_CONFIDENCE_SCORE_FLOOR,+ _INLINE_BODY_MAX_LINES,+ _INLINE_BODY_MAX_SYMBOLS,_SYSTEM_PROMPT,_USER_TEMPLATE,)@@ -91,9 +100,11 @@ from repowise.server.mcp_server.tool_answer.retrieval import (serialize_hits as _serialize_hits,)from repowise.server.mcp_server.tool_answer.symbols import (+ _anchor_symbol_hits,_extract_question_identifiers,_extract_value_answer,_hydrate_symbols_for_hits,+ _read_symbol_source,)from repowise.server.mcp_server.tool_answer.synthesis import (_hash_question,@@ -127,6 +138,77 @@ def _cache_entry_expired(created_at) -> bool:return (datetime.now(UTC) - ts) > timedelta(days=_ANSWER_CACHE_TTL_DAYS)+def _gather_code_rationale(ctx, hits: list[dict], fallback_targets: list[str], question: str):+ """Mine in-code rationale comments for a low-confidence answer.++ The wiki/decision corpus failed to ground the question; the "why" may be a+ plain code comment instead (the unbiased A/B's one durable loss). Scan the+ already-relevant files — anchored/matched-symbol files lead, with a near-+ line boost on their definition, then fallback_targets fill the rest — for+ comment blocks carrying a rationale marker overlapping the question.+ Best-effort: returns [] on any failure, never raises into the tool path.+ """+ repo_root = getattr(ctx, "path", None)+ if not repo_root:+ return []+ candidates: list[str] = []+ near_lines: dict[str, int] = {}+ for h in hits or []:+ path = h.get("target_path")+ if not path:+ continue+ for s in (h.get("_anchor_symbols") or []) + [+ s for s in (h.get("symbols") or []) if s.get("_matched")+ ]:+ candidates.append(path)+ sl = s.get("start_line")+ if sl and path not in near_lines:+ near_lines[path] = sl+ candidates.extend(p for p in (fallback_targets or []) if p)+ try:+ return _mine_rationale(repo_root, candidates, question, near_lines=near_lines)+ except Exception: # best-effort enrichment, never break the response+ return []+++def _drop_already_surfaced(rationale: list[dict], *surfaced: list[dict]) -> list[dict]:+ """Drop mined rationale comments already shown elsewhere in the response.++ Track B harvests rationale comments into ``code_comment`` decision records at+ index time; Track A mines them live here. Once both ship, the same comment+ can appear twice — once as material already in the payload (a ``symbol_bodies``+ block whose body contains the comment, a quote, or a line-ranged citation /+ decision) and once as a ``code_rationale`` entry. Suppress the duplicate:+ drop any mined comment whose ``(path, line-range)`` overlaps an entry already+ surfaced. Entries without a ``(path, lines)`` pair are ignored.+ """+ occupied: list[tuple[str, int, int]] = []+ for entries in surfaced:+ for e in entries or []:+ path = e.get("path")+ lines = e.get("lines")+ if path and isinstance(lines, (list, tuple)) and len(lines) == 2:+ occupied.append((path, lines[0], lines[1]))+ if not occupied:+ return rationale+ kept: list[dict] = []+ for r in rationale:+ path = r.get("path")+ lines = r.get("lines")+ if (+ path+ and isinstance(lines, (list, tuple))+ and len(lines) == 2+ and any(+ p == path and not (lines[1] < s or lines[0] > e)+ for p, s, e in occupied+ )+ ):+ continue+ kept.append(r)+ return kept++@mcp.tool()async def get_answer(question: str,@@ -140,6 +222,8 @@ async def get_answer(cite it directly, no verification Read needed. Low confidence returnsbest_guesses with one-line justifications instead of an empty answer.retrieval_quality separately rates the retrieval that fed synthesis.+ When the answer names a function/method/class, ``symbol_bodies`` carries+ its full live body — read that instead of a follow-up get_symbol.Args:question: developer question.@@ -266,6 +350,10 @@ async def get_answer(# they never enter ranking, citations, or fallback_targets.hits = filter_dicts_by_key(hits, "target_path", exclude_spec)+ # Identifiers the question names explicitly — drives symbol anchoring+ # (below) and question-aware symbol promotion (during hydration).+ question_ids = _extract_question_identifiers(question)+# Term-coverage re-rank before any graph-aware bias so conjunctive# matches survive the merge.hits = _rerank_by_coverage(hits, question)@@ -290,6 +378,15 @@ async def get_answer(# Re-filter: graph expansion can pull excluded neighbors back in (before the# cap, so an excluded neighbor can't occupy a top-5 slot).hits = filter_dicts_by_key(hits, "target_path", exclude_spec)+ # Symbol anchoring: when the question names an indexed function / method /+ # class, force its defining file into the candidate set as a dominant hit.+ # Fuzzy retrieval misses deep-path definitions even when the symbol is+ # indexed; this makes "explain X" one-shot-complete instead of degrading+ # to best_guesses on plausible-but-wrong neighbors.+ if question_ids:+ with contextlib.suppress(Exception):+ async with get_session(ctx.session_factory) as session:+ hits = await _anchor_symbol_hits(session, repo_id, question_ids, hits)# Always cap retrieval hits at 5 for the response payload.hits = hits[:5]@@ -297,7 +394,6 @@ async def get_answer(# aware: identifiers extracted from the question promote matching# symbols and attach a source-body excerpt — the difference between a# hedged answer on a specific-method question and a grounded one.- question_ids = _extract_question_identifiers(question)if hits:with contextlib.suppress(Exception):async with get_session(ctx.session_factory) as session:@@ -369,7 +465,10 @@ async def get_answer(for h in hits[:_GATED_RETURN_HITS]if h.get("target_path")]- return {+ # Mine source comments for rationale the wiki/decision corpus+ # missed — turns "go Read these 5 files" into a cited why.+ code_rationale = _gather_code_rationale(ctx, hits, fallback_targets, question)+ gated: dict = {"answer": "","citations": [],"confidence": "low",@@ -388,12 +487,19 @@ async def get_answer("avoid anchoring on a wrong frame. Each best_guess entry ""names why that file is in the running."),- "_meta": _build_meta(- timing_ms=(time.perf_counter() - t0) * 1000,- hint=_answer_hint("low", len(hits)),- repository=repository,- ),}+ if code_rationale:+ gated["code_rationale"] = code_rationale+ gated["note"] += (+ " code_rationale carries rationale comments mined from the "+ "candidate source — they may already answer the question."+ )+ gated["_meta"] = _build_meta(+ timing_ms=(time.perf_counter() - t0) * 1000,+ hint=_answer_hint("low", len(hits)),+ repository=repository,+ )+ return gated# Confidence is the only axis we gate on. We deliberately do NOT add a# second gate keyed on question shape (e.g. relational questions@@ -546,6 +652,83 @@ async def get_answer(if len(quotes) >= 5:break+ # Inline symbol bodies: for the multi-line definitions (function / method+ # / class) the answer actually names, surface the full body the hydrator+ # already read live for synthesis. This collapses the get_answer ->+ # get_symbol drill-down — the agent that asked "how does X work" gets X's+ # body in the same call instead of a follow-up read. Constants stay in+ # `quotes` (their body IS the one-line assignment); only definitions with+ # a real body earn a block. `source` is the live body sliced at the+ # indexed bounds; it is NOT bounds-verified, so the field stays distinct+ # from get_symbol's `verified` contract. When the indexed body is longer+ # than the hydrator's line cap, a `continuation` names the exact range+ # read for the remainder (mirrors get_symbol).+ # Gather eligible definitions across the top hits, ranked so the most+ # relevant body leads. Tier 0 = the exact symbol the question named, as+ # resolved by symbol anchoring (survives the fuzzy hydration cap that a+ # parent class name otherwise floods). Tier 1 = question-matched hydrated+ # symbols. Within a tier, a function/method outranks a class container, so+ # "explain the extract_all method of DecisionExtractor" serves extract_all,+ # not the 1,300-line class head. Then document order.+ _body_candidates: list[tuple[int, int, int, str, dict]] = []+ for h in hits[:_ENRICH_TOP_N_HITS]:+ path = h.get("target_path")+ if not path:+ continue+ for s in h.get("_anchor_symbols") or []:+ name = s.get("name")+ if not name or name not in answer_text:+ continue+ kind = s.get("kind")+ kind_rank = 0 if kind in ("function", "method") else 1+ _body_candidates.append((0, kind_rank, s.get("start_line") or 0, path, s))+ for s in h.get("symbols") or []:+ name = s.get("name")+ if not name or len(name) < 3 or not s.get("_matched"):+ continue+ if name not in answer_text:+ continue+ kind = s.get("kind")+ if kind not in ("function", "method", "class", "interface"):+ continue+ kind_rank = 0 if kind in ("function", "method") else 1+ _body_candidates.append((1, kind_rank, s.get("start_line") or 0, path, s))+ _body_candidates.sort(key=lambda t: (t[0], t[1], t[2]))++ symbol_bodies: list[dict] = []+ _seen_bodies: set[tuple[str, str]] = set()+ repo_root = Path(str(ctx.path)) if getattr(ctx, "path", None) else None+ for _tier, _kind_rank, start, path, s in _body_candidates:+ if len(symbol_bodies) >= _INLINE_BODY_MAX_SYMBOLS:+ break+ name = s["name"]+ if (path, name) in _seen_bodies:+ continue+ sym_end = s.get("end_line") or 0+ # Re-read a fuller body than the synthesis excerpt: this block is for+ # the agent, so a docstring-heavy def shouldn't spend its whole window+ # on docstring and truncate the logic the question asked about. Falls+ # back to the hydrator's excerpt if the re-read fails.+ body = _read_symbol_source(+ repo_root, path, start, sym_end, max_lines=_INLINE_BODY_MAX_LINES+ ) or s.get("source_excerpt")+ if not body:+ continue+ served = body.count("\n") + 1+ end_served = start + served - 1+ sym_end = sym_end or end_served+ entry: dict = {+ "path": path,+ "name": name,+ "lines": [start, end_served],+ "source": body,+ }+ if sym_end > end_served:+ entry["truncated"] = True+ entry["continuation"] = f"{path}:{end_served + 1}-{sym_end}"+ symbol_bodies.append(entry)+ _seen_bodies.add((path, name))+# 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.@@ -639,6 +822,27 @@ async def get_answer("the indexed wiki. Read one of fallback_targets to answer."),}+ # Even on a hedge, hand over any question-named symbol bodies we+ # resolved — the agent can read the body directly instead of the+ # fallback_targets file, which is the whole point of anchoring.+ if symbol_bodies:+ payload["symbol_bodies"] = symbol_bodies+ payload["note"] = (+ "Synthesis hedged, but symbol_bodies carries the live body of "+ "the symbol(s) you named — read that to answer."+ )+ # The hedge often means the rationale isn't in the wiki at all — it's a+ # code comment. Mine the candidate source for it before sending the+ # agent off to Read.+ code_rationale = _gather_code_rationale(ctx, hits, fallback_targets, question)+ # A comment already visible in symbol_bodies must not surface twice.+ code_rationale = _drop_already_surfaced(code_rationale, symbol_bodies)+ if code_rationale:+ payload["code_rationale"] = code_rationale+ payload["note"] += (+ " code_rationale carries rationale comments mined from the "+ "cited source — they may already answer the question."+ )else:# Confidence-conditional retrieval block: the block exists so the# agent can ground when the answer alone isn't trustworthy. At high@@ -665,6 +869,8 @@ async def get_answer(}if quotes:payload["quotes"] = quotes+ if symbol_bodies:+ payload["symbol_bodies"] = symbol_bodiesif ungrounded_values:payload["note"] = (f"Value-grounding gate: the answer asserts {ungrounded_values} "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 3e0ded736..d5be58b91 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@@ -28,6 +28,20 @@ _MAX_SYMBOLS_PER_HIT = 4_MATCHED_SYMBOL_DOC_CHARS = 400_MATCHED_SYMBOL_SOURCE_LINES = 40+# How many question-named symbol bodies get_answer inlines in `symbol_bodies`.+# The hydrator already reads these bodies live for synthesis; surfacing them+# in the response collapses the get_answer -> get_symbol drill-down on+# "how does X work" / "explain method Y" questions (the agent gets X's body in+# the same call). Bounded so the body block can't dominate the cached prefix.+_INLINE_BODY_MAX_SYMBOLS = 2+# Line cap for an inlined symbol_bodies block. Larger than the synthesis+# excerpt (_MATCHED_SYMBOL_SOURCE_LINES) because this body is for the agent,+# not the LLM prompt: a docstring-heavy definition (e.g. get_symbol) burns the+# 40-line synthesis cap on docstring and truncates the actual logic, forcing+# the get_symbol follow-up the field exists to remove. 120 serves the whole+# body of ~99% of symbols in one shot; the rest carry a continuation token.+_INLINE_BODY_MAX_LINES = 120+# Sort priority by symbol kind. Classes first because "what does X do" /# "which class inherits from Y" questions resolve at the class level. Then# top-level functions, then methods (which usually only matter once the@@ -196,7 +210,9 @@ _HIGH_CONFIDENCE_SCORE_FLOOR = 1.5# 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+# v5: `symbol_bodies` field — inline full bodies of question-named symbols so+# the consumer skips the get_symbol follow-up. Cached v4 payloads lack it.+_ANSWER_SCHEMA_VERSION = 5# Hard TTL on answer-cache rows. Commit-based invalidation (the payload's# stamped ``_indexed_commit`` vs the repo's current head) is the primarydiff --git a/packages/server/src/repowise/server/mcp_server/tool_answer/symbols.py b/packages/server/src/repowise/server/mcp_server/tool_answer/symbols.pyindex b929b829a..db33d4b15 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@@ -15,6 +15,7 @@ from sqlalchemy import selectfrom repowise.core.persistence.models import WikiSymbolfrom repowise.server.mcp_server.tool_answer.config import (_ENRICH_TOP_N_HITS,+ _HIGH_CONFIDENCE_SCORE_FLOOR,_MATCHED_SYMBOL_SOURCE_LINES,_MAX_RICH_SIG_LINES,_MAX_SYMBOLS_PER_HIT,@@ -178,6 +179,102 @@ def _extract_value_answer(hits: list[dict], question_ids: set[str]) -> dict | Noreturn candidates[0] if candidates else None+async def _anchor_symbol_hits(+ session,+ repo_id: str,+ question_ids: set[str],+ hits: list[dict],+) -> list[dict]:+ """Inject the defining file of a question-named indexed symbol into hits.++ BM25 / vector retrieval misses deep-path files even when the named symbol+ is indexed — "explain DecisionExtractor.extract_all" ranks the pipeline+ orchestrators above ``analysis/decisions/extractor.py`` and never surfaces+ the definition, so synthesis hedges and ``symbol_bodies`` can't fire. When+ a question identifier resolves to a single indexed function / method /+ class, prepend (or boost) its defining file as the dominant hit so the+ answer grounds in the actual definition. Homonyms are kept only when the+ question also names the parent (``DecisionExtractor``) — never guessed.++ Returns ``hits`` re-sorted by score (mutated in place).+ """+ if not question_ids:+ return hits+ qids_lower = {q.lower() for q in question_ids}+ res = await session.execute(+ select(WikiSymbol).where(+ WikiSymbol.repository_id == repo_id,+ WikiSymbol.name.in_(list(question_ids)),+ WikiSymbol.kind.in_(("function", "method", "class", "interface")),+ )+ )+ by_name: dict[str, list] = {}+ for row in res.scalars().all():+ by_name.setdefault(row.name, []).append(row)++ chosen: list = []+ for cands in by_name.values():+ if len(cands) == 1:+ chosen.append(cands[0])+ continue+ # Disambiguate a homonym only when the question names its parent or+ # the parent appears in the qualified name. Otherwise skip — a wrong+ # anchor is worse than no anchor.+ narrowed = [+ c+ for c in cands+ if (c.parent_name or "").lower() in qids_lower+ or any(+ q in (c.qualified_name or "").lower()+ for q in qids_lower+ if len(q) >= 4 and q != (c.name or "").lower()+ )+ ]+ if len(narrowed) == 1:+ chosen.append(narrowed[0])++ if not chosen:+ return hits++ by_path = {h.get("target_path"): h for h in hits}+ top_score = max((h.get("score", 0.0) for h in hits), default=0.0)+ # Above the current top so an exact symbol match dominates the dominance+ # gate (an exact name+parent hit is stronger evidence than a prose match).+ anchor_score = max(top_score + 2.0, _HIGH_CONFIDENCE_SCORE_FLOOR + 1.0)+ for sym in chosen:+ fp = sym.file_path+ target = by_path.get(fp)+ if target is None:+ target = {+ "page_id": f"file_page:{fp}",+ "target_path": fp,+ "title": fp,+ "summary": "",+ "snippet": "",+ "page_type": "file_page",+ "score": anchor_score,+ "_symbol_anchored": True,+ }+ hits.insert(0, target)+ by_path[fp] = target+ else:+ target["score"] = max(target.get("score", 0.0), anchor_score)+ target["_symbol_anchored"] = True+ # Stash the exact symbol the question named so symbol_bodies serves it+ # directly — the fuzzy hydration cap drops a far-down method when the+ # parent class name floods every sibling's qualified-name match.+ target.setdefault("_anchor_symbols", []).append(+ {+ "name": sym.name,+ "kind": sym.kind,+ "start_line": sym.start_line,+ "end_line": sym.end_line,+ }+ )+ hits.sort(key=lambda h: h.get("score", 0.0), reverse=True)+ return hits++async def _hydrate_symbols_for_hits(session,repo_id: str,@@ -274,9 +371,16 @@ async def _hydrate_symbols_for_hits(syms = by_file[path]syms.sort(key=lambda s: (not s["_matched"], s["start_line"]))cap = _MAX_SYMBOLS_TOP_HIT if i == 0 else _MAX_SYMBOLS_PER_HIT- # Guarantee at least one matched symbol survives the cap, even if- # the file has more than `cap` symbols before it.- kept: list[dict] = [s for s in syms if s["_matched"]][:cap]+ # Force-include the exact symbol the question named (via anchoring) so a+ # class-name flood — where every sibling method "matches" through the+ # parent's qualified name — can't evict the method the user asked about+ # from the synthesis context. Without this the LLM never sees the body+ # and hedges, which is exactly the failure anchoring exists to prevent.+ anchor_names = {a.get("name") for a in (h.get("_anchor_symbols") or [])}+ kept: list[dict] = [s for s in syms if s["name"] in anchor_names][:cap]+ # Then the rest of the matched symbols, then unmatched, up to the cap.+ kept.extend(s for s in syms if s["_matched"] and s not in kept)+ kept = kept[:cap]for s in syms:if s in kept:continuediff --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 ffaef4a05..574a7bf99 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@@ -12,7 +12,7 @@ import jsonfrom dataclasses import asdictfrom typing import Any-from sqlalchemy import select+from sqlalchemy import distinct, func, selectfrom sqlalchemy.ext.asyncio import AsyncSessionfrom repowise.core.analysis.health.signals import file_signals@@ -28,6 +28,7 @@ from repowise.core.persistence.crud import ()from repowise.core.persistence.models import (CoverageFile,+ GraphEdge,GraphNode,HealthFileMetric,HealthFinding,@@ -38,6 +39,30 @@ from repowise.server.mcp_server._helpers import filter_dicts_by_key, filter_path# Minimum confidence for call edges to filter false positives_MIN_CALL_CONFIDENCE = 0.7+# Edge types that count as a "caller"/"callee" relationship.+_CALL_EDGE_TYPES = ["calls", "extends", "implements"]+++async def _count_call_neighbors(+ session: AsyncSession, repo_id: str, node_id: str, *, inbound: bool+) -> int:+ """Count distinct caller (inbound) / callee (outbound) symbols above the+ confidence floor — the TRUE total, independent of the display limit.++ Without this the callers list capped silently at the limit and reported+ ``truncated: false``, which misled an agent doing a find-all-callers sweep+ on a high-fan-in symbol into thinking 20 was the whole set (S2 dogfood).+ """+ matched = GraphEdge.target_node_id if inbound else GraphEdge.source_node_id+ other = GraphEdge.source_node_id if inbound else GraphEdge.target_node_id+ stmt = select(func.count(distinct(other))).where(+ GraphEdge.repository_id == repo_id,+ matched == node_id,+ GraphEdge.edge_type.in_(_CALL_EDGE_TYPES),+ GraphEdge.confidence >= _MIN_CALL_CONFIDENCE,+ )+ return int((await session.execute(stmt)).scalar() or 0)+async def _resolve_call_graph(session: AsyncSession,@@ -52,7 +77,9 @@ async def _resolve_call_graph() -> None:"""Resolve callers/callees for a symbol and attach to result_data."""repo_id = repository.id- limit = 20+ # 99.56% of symbols have <=50 callers (p99=31); the rare hub gets an+ # explicit `*_truncated` + `*_total` signal below rather than a silent cut.+ limit = 50# Resolve to a graph node (symbol)node = await get_graph_node(session, repo_id, target)@@ -102,7 +129,7 @@ async def _resolve_call_graph(repo_id,node.node_id,direction=direction,- edge_types=["calls", "extends", "implements"],+ edge_types=_CALL_EDGE_TYPES,limit=limit,)@@ -133,6 +160,10 @@ async def _resolve_call_graph("file": other_node.file_pathif other_nodeelse (other_id.split("::")[0] if "::" in other_id else other_id),+ # Definition line of the other symbol — lets the agent jump+ # straight to the call-site neighbourhood instead of grepping+ # for it (the S1 dogfood's most common follow-up).+ "line": other_node.start_line if other_node else None,"confidence": e.confidence,"edge_type": e.edge_type,}@@ -150,8 +181,21 @@ async def _resolve_call_graph(if want_callers:result_data["callers"] = callers+ total = await _count_call_neighbors(session, repo_id, node.node_id, inbound=True)+ if total > len(callers):+ result_data["callers_total"] = total+ result_data["callers_truncated"] = True+ result_data["_callers_note"] = (+ f"Showing top {len(callers)} of {total} callers by confidence. The "+ f"graph view caps here; for the complete set (e.g. a signature change) "+ f"grep '{node.name}('."+ )if want_callees:result_data["callees"] = callees+ total = await _count_call_neighbors(session, repo_id, node.node_id, inbound=False)+ if total > len(callees):+ result_data["callees_total"] = total+ result_data["callees_truncated"] = Trueasync def _resolve_file_level_callers(@@ -458,7 +502,14 @@ async def _resolve_skeleton(a symbol's "skeleton" is just its signature, which the triage cardalready carries."""- if target_type != "file":+ # A "file.py::Symbol" target still has a useful skeleton — the file that+ # defines the symbol. Strip the suffix and skeleton that file rather than+ # failing on a literal path containing "::" (which surfaced as the opaque+ # "Source file could not be read" in the S2 dogfood). Module/other+ # non-file targets with no "::" have no file to render.+ is_symbol_target = "::" in target+ file_target = target.split("::", 1)[0] if is_symbol_target else target+ if not is_symbol_target and target_type != "file":result_data["skeleton"] = {"error": "skeleton requires a file target; pass the file path."}returnif not repo_root:@@ -474,7 +525,7 @@ async def _resolve_skeleton(res = await session.execute(select(WikiSymbol).where(WikiSymbol.repository_id == repo_id,- WikiSymbol.file_path == target,+ WikiSymbol.file_path == file_target,))rows = list(res.scalars().all())@@ -484,13 +535,13 @@ async def _resolve_skeleton(select(GraphNode.name, GraphNode.pagerank).where(GraphNode.repository_id == repo_id,GraphNode.node_type == "symbol",- GraphNode.file_path == target,+ GraphNode.file_path == file_target,))pagerank = {name: pr or 0.0 for name, pr in pr_res.all() if name}repo_path = Path(str(repo_root))- abs_path = (repo_path / target).resolve()+ abs_path = (repo_path / file_target).resolve()try:abs_path.relative_to(repo_path.resolve())source = abs_path.read_text(encoding="utf-8", errors="replace")@@ -529,6 +580,14 @@ async def _resolve_skeleton(# a verified response never needs a follow-up Read."verified": True,}+ if is_symbol_target:+ # The caller passed "file.py::Symbol"; tell them this is the whole+ # file's skeleton, and how to get just the symbol's body.+ result_data["skeleton"]["of_file"] = file_target+ result_data["skeleton"]["symbol_hint"] = (+ f"Skeleton of the file defining '{target.split('::', 1)[1]}'. For that "+ f"symbol's full body call get_symbol('{target}')."+ )if result.mode == "raw":result_data["skeleton"]["note"] = ("No usable symbol bounds for this file — returned source as-is."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 01ec8af8c..8675b5bfa 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@@ -574,36 +574,30 @@ async def _resolve_one_target(triage_meta = triage_meta_res.scalar_one_or_none()result_data["hotspot"] = bool(triage_meta) if triage_meta is not None else False- # Bounded graph-link query — replaces full Python scan over all rows.- governing: list[DecisionRecord] = []- seen_ids: set[str] = set()- for lookup_node in dict.fromkeys(- [triage_path, target] if triage_path != target else [triage_path]- ):- if not lookup_node:- continue- for dr in await get_governing_decisions(session, repo_id, lookup_node):- if dr.id not in seen_ids:- seen_ids.add(dr.id)- governing.append(dr)- if governing:- result_data["decision_records"] = [dr.title for dr in governing[:5]]- result_data["decision_records_hint"] = (- "Decisions touch this file. Call get_why(targets=[...]) for rationale."- )- # Compact enriched list — highest-confidence first, capped at 5.- governing_sorted = sorted(governing, key=lambda d: -(d.confidence or 0.0))- result_data["governing_decisions"] = [- {- "id": dr.id,- "title": dr.title,- "status": dr.status,- "staleness_score": dr.staleness_score,- "verification": dr.verification,- "stale": bool(dr.status == "active" and (dr.staleness_score or 0.0) >= 0.5),- }- for dr in governing_sorted[:5]- ]+ # Governing decisions — opt-in only (``include=["decisions"]``).+ # The default triage card omits them: the rich form+ # (id/staleness/verification) is low-signal for an agent's next move and+ # the per-call graph query isn't worth the latency or the cached-prefix+ # weight. Agents that want rationale call get_why directly; opting in+ # here returns a lightweight titles list (no enriched objects).+ if include and "decisions" in include:+ governing: list[DecisionRecord] = []+ seen_ids: set[str] = set()+ for lookup_node in dict.fromkeys(+ [triage_path, target] if triage_path != target else [triage_path]+ ):+ if not lookup_node:+ continue+ for dr in await get_governing_decisions(session, repo_id, lookup_node):+ if dr.id not in seen_ids:+ seen_ids.add(dr.id)+ governing.append(dr)+ if governing:+ governing_sorted = sorted(governing, key=lambda d: -(d.confidence or 0.0))+ result_data["decision_records"] = [dr.title for dr in governing_sorted[:3]]+ result_data["decision_records_hint"] = (+ "Decisions touch this file. Call get_why(targets=[...]) for rationale."+ )# --- Ownership ---if include is None or "ownership" in include:diff --git a/packages/server/src/repowise/server/mcp_server/tool_symbol.py b/packages/server/src/repowise/server/mcp_server/tool_symbol.pyindex 62ec536e8..66ecbda0c 100644--- a/packages/server/src/repowise/server/mcp_server/tool_symbol.py+++ b/packages/server/src/repowise/server/mcp_server/tool_symbol.py@@ -63,8 +63,13 @@ from repowise.server.mcp_server._verify import check_symbol_bounds, heal_symbol__log = __import__("logging").getLogger("repowise.mcp.symbol")# Safety cap so a misconfigured WikiSymbol row pointing at a giant file-# can never blow up the agent's context window. Tuned to ~12 KB of source.-_MAX_SOURCE_LINES = 400+# can never blow up the agent's context window. Set to ~18 KB of source:+# on a real index 99.93% of symbols are <600 lines, so a single get_symbol+# serves the WHOLE body in one call for all but a handful of monster+# functions — round-trip count, not payload size, is what dominates agent+# token cost (S1 dogfood). The rare overflow gets a clean `continuation`+# token rather than a guessed range read.+_MAX_SOURCE_LINES = 600# Omission-ref dispatch: "repowise#<12-hex>" never collides with a# "{path}::{name}" symbol_id. Also tolerates a pasted whole marker.@@ -199,6 +204,7 @@ async def _resolve_range_read(if end < start:start, end = end, start+ requested_end = endrequested_truncated = (end - start + 1) > _MAX_RANGE_LINESif requested_truncated:end = start + _MAX_RANGE_LINES - 1@@ -222,6 +228,15 @@ async def _resolve_range_read("verified": True,"_meta": _build_meta(timing_ms=(time.perf_counter() - t0) * 1000, repository=repository),}+ remainder_end = min(requested_end, total)+ if range_truncated and e < remainder_end:+ # Same clean-continuation contract as a truncated symbol read: name the+ # exact next range instead of leaving the agent to guess it.+ response["continuation"] = f"{path}:{e + 1}-{remainder_end}"+ response["note"] = (+ f"Range capped at {_MAX_RANGE_LINES} lines; served {s}-{e}. "+ f"Continue in one call: get_symbol({response['continuation']!r})."+ )from repowise.server.mcp_server._savings import declare_replaceddeclare_replaced(response, full_tokens)@@ -485,13 +500,15 @@ async def get_symbol() -> dict:"""Read one function/class/constant with live-verified line bounds.- Raw source of one indexed symbol, bounded (~400 lines) — cheaper than+ Raw source of one indexed symbol, bounded (~600 lines) — cheaper thanRead+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 serveslive range reads ("path.py:140-180", ≤200 lines, always verified) andomission refs ("repowise#<12-hex>"). Index misses grep the live file- and return fallback_lines instead of a dead end.+ and return fallback_lines instead of a dead end. When ``truncated`` is+ true the response carries a ``continuation`` token — the exact range read+ that fetches the remainder; pass it straight back to get_symbol.Args:symbol_id: "path/to/file.py::Name" (from get_context),@@ -649,6 +666,17 @@ async def get_symbol(repository=repository,),}+ if truncated and not check.approximate and end < check.end_line:+ # The body exceeds the serve cap. Hand back the exact range read that+ # fetches the remainder so the agent never has to guess the next span+ # (the S1 dogfood found it would otherwise grub-around with a guessed+ # range, doubling the call cost).+ response["continuation"] = f"{row.file_path}:{end + 1}-{check.end_line}"+ response["note"] = (+ f"Symbol body ({check.start_line}-{check.end_line}) exceeds the "+ f"{_MAX_SOURCE_LINES}-line serve cap; served {start}-{end}. Fetch "+ f"the remainder in one call: get_symbol({response['continuation']!r})."+ )if check.approximate:response["bounds"] = "approximate"response["note"] = (diff --git a/packages/server/src/repowise/server/mcp_server/tool_why.py b/packages/server/src/repowise/server/mcp_server/tool_why.pyindex 3096f10bd..7b6ae065f 100644--- a/packages/server/src/repowise/server/mcp_server/tool_why.py+++ b/packages/server/src/repowise/server/mcp_server/tool_why.py@@ -17,6 +17,7 @@ from repowise.core.persistence.models import (GitMetadata,)from repowise.core.registry import mcp_tool_registry as mcp+from repowise.server.mcp_server._code_rationale import mine_rationale as _mine_rationalefrom repowise.server.mcp_server._helpers import (_build_origin_story,_compute_alignment,@@ -234,6 +235,11 @@ async def _why_path(query: str, repo: str | None) -> dict:all_git_meta,repository,)+ # Decisions and git history both silent → the "why" may live in a+ # code comment. Mine this file's rationale comments directly.+ rationale = _mine_rationale(ctx.path, [query], None)+ if rationale:+ result_data["code_rationale"] = rationaleresult_data["_meta"] = _build_meta(repository=repository)return result_data@@ -464,6 +470,12 @@ async def _why_search(query: str, targets: list[str] | None, repo: str | None) -result_data["target_context"] = await _build_target_context(ctx, repository, all_decisions, target_git, targets)+ # When the decision corpus is thin, the rationale for the anchored+ # files may be in their comments — mine them against the question.+ if not merged_decisions:+ rationale = _mine_rationale(ctx.path, targets, query)+ if rationale:+ result_data["code_rationale"] = rationaleresult_data["_meta"] = _build_meta(repository=repository)return result_datadiff --git a/tests/unit/analysis/test_decision_rationale_comments.py b/tests/unit/analysis/test_decision_rationale_comments.pynew file mode 100644index 000000000..f4b3e47f4--- /dev/null+++ b/tests/unit/analysis/test_decision_rationale_comments.py@@ -0,0 +1,264 @@+"""In-code rationale harvest — the shared miner + the index-time extractor pass.++Source 8 (``code_comment``) mines rationale-bearing source comments into+low-confidence ``proposed`` decision records so the architectural intent that+lives in comments (not ADRs) enters the queryable corpus. These tests cover the+precision guardrails (the whole risk) and the extractor wiring.+"""++from __future__ import annotations++from types import SimpleNamespace++from repowise.core.analysis.decision_extractor import DecisionExtractor+from repowise.core.analysis.decisions.rationale_comments import (+ extract_comment_blocks,+ harvest_file_rationale,+ has_causal_marker,+ has_rationale_marker,+ is_license_or_boilerplate,+ looks_like_commented_out_code,+ marker_strength,+)++# A real rationale comment: prose, a causal marker, enclosing a function.+_RATIONALE_PY = '''\+"""Module docstring."""++import time+++def call_api():+ # We retry on 429 here rather than in the client because the client is+ # shared across tenants and a global backoff would starve everyone.+ return time.time()+'''++_LICENSE_PY = """\+# Copyright 2026 Acme Inc. All rights reserved.+# Licensed under the Apache License because the board said so.+import os+"""+++# ---------------------------------------------------------------------------+# Comment tokenizer+# ---------------------------------------------------------------------------+++def test_extract_comment_blocks_coalesces_consecutive_lines():+ blocks = extract_comment_blocks(_RATIONALE_PY, "py")+ # The two-line rationale run coalesces into one block.+ runs = [b for b in blocks if "we retry on 429" in b.text.lower()]+ assert len(runs) == 1+ b = runs[0]+ assert b.start_line < b.end_line # spans both comment lines+ assert "starve everyone" in b.text+++def test_extract_comment_blocks_handles_c_style_and_returns_empty_for_unknown():+ js = "/* we batch writes because the disk fsync dominates latency */\nx = 1;\n"+ blocks = extract_comment_blocks(js, "js")+ assert any("batch writes" in b.text for b in blocks)+ # Unknown / non-code extension yields nothing.+ assert extract_comment_blocks("plain prose because yes", "txt") == []+++# ---------------------------------------------------------------------------+# Guardrails+# ---------------------------------------------------------------------------+++def test_marker_detection_and_strength():+ assert has_rationale_marker("we do this because of X")+ assert not has_rationale_marker("just a plain label here")+ # Two distinct markers present → strength 2.+ assert marker_strength("because we must avoid the deadlock") >= 2+++def test_causal_marker_is_stricter_than_rationale_marker():+ # An intent label has a rationale marker but no causal reason.+ assert has_rationale_marker("NOTE: always flush before close")+ assert not has_causal_marker("NOTE: always flush before close")+ # A stated reason is causal.+ assert has_causal_marker("we batch writes because fsync dominates")+++def test_license_and_preamble_detected():+ assert is_license_or_boilerplate("Copyright 2026 Acme Inc. All rights reserved.")+ assert is_license_or_boilerplate("SPDX-License-Identifier: MIT")+ assert is_license_or_boilerplate("-*- coding: utf-8 -*-")+ assert not is_license_or_boilerplate("we cache this because it is hot")+++def test_commented_out_code_detected_but_prose_kept():+ assert looks_like_commented_out_code(("x = compute(y)", "return x"))+ assert not looks_like_commented_out_code(+ ("we avoid the global lock because it serializes every tenant",)+ )+++# ---------------------------------------------------------------------------+# Per-file harvest+# ---------------------------------------------------------------------------+++def test_harvest_keeps_rationale_drops_license():+ kept = harvest_file_rationale(_RATIONALE_PY, "py")+ assert len(kept) == 1+ assert "starve everyone" in kept[0].text++ # The license block carries "because" but is boilerplate → dropped.+ assert harvest_file_rationale(_LICENSE_PY, "py") == []+++def test_harvest_drops_thin_and_markerless_comments():+ src = "# hi\n# this is a plain comment with no causal marker at all here\nx = 1\n"+ assert harvest_file_rationale(src, "py") == []+++def test_harvest_respects_per_file_cap():+ parts = []+ for i in range(6):+ parts.append(f"def f{i}():")+ parts.append(f" # branch {i} exists because edge case {i} would otherwise crash")+ parts.append(f" return {i}")+ src = "\n".join(parts) + "\n"+ kept = harvest_file_rationale(src, "py", max_per_file=3)+ assert len(kept) == 3+++def test_harvest_non_code_extension_returns_empty():+ assert harvest_file_rationale("we did this because reasons", "md") == []+++def test_harvest_excludes_docstrings_by_default_but_keeps_line_comments():+ src = (+ '"""We pick gRPC because REST added latency on the hot path."""\n'+ "# we cache the token because the lookup is expensive\n"+ "x = 1\n"+ )+ # Default: docstring rationale is skipped, the line comment is kept.+ kept = harvest_file_rationale(src, "py")+ assert len(kept) == 1+ assert "cache the token" in kept[0].text+ # Opt in to docstrings (the MCP recall mode) → both surface.+ both = harvest_file_rationale(src, "py", include_docstrings=True)+ assert len(both) == 2+++def test_harvest_splits_and_drops_separator_rules():+ src = (+ "# ----------------------------------------------------------------\n"+ "# Section banner only\n"+ "# ----------------------------------------------------------------\n"+ "# we skip the cache here because the entry is already stale\n"+ "y = 2\n"+ )+ kept = harvest_file_rationale(src, "py")+ assert len(kept) == 1+ text = kept[0].text+ assert "skip the cache" in text+ assert "---" not in text # divider rule never glued in+ assert "Section banner" not in text # markerless run dropped+++def test_require_causal_false_admits_intent_labels():+ src = "# NOTE: always flush the buffer before closing the handle here\nz = 3\n"+ assert harvest_file_rationale(src, "py") == [] # no causal reason+ loose = harvest_file_rationale(src, "py", require_causal=False)+ assert len(loose) == 1+++# ---------------------------------------------------------------------------+# Extractor pass (Source 8)+# ---------------------------------------------------------------------------+++async def test_harvest_rationale_comments_emits_grounded_proposed_record(tmp_path):+ (tmp_path / "client.py").write_text(_RATIONALE_PY, encoding="utf-8")++ ex = DecisionExtractor(repo_path=tmp_path) # deterministic, no provider+ decisions = await ex.harvest_rationale_comments()++ assert len(decisions) == 1+ d = decisions[0]+ assert d.source == "code_comment"+ assert d.status == "proposed"+ assert d.confidence < 0.5 # ranks below real ADRs / inline markers+ # Verbatim grounding: decision + source_quote are the comment itself.+ assert "starve everyone" in d.decision+ assert d.source_quote == d.decision+ assert d.evidence_file == "client.py"+ assert d.affected_files == ["client.py"]+ assert d.title # never title-only-empty; title is the comment's first line+++async def test_harvest_resolves_enclosing_symbol_from_parsed_files(tmp_path):+ (tmp_path / "client.py").write_text(_RATIONALE_PY, encoding="utf-8")++ # The rationale comment sits inside call_api() (lines ~7-9). Provide a+ # parsed-file with that symbol so the harvest can attribute it.+ parsed = SimpleNamespace(+ file_info=SimpleNamespace(path="client.py"),+ symbols=[+ SimpleNamespace(+ start_line=6, end_line=10, name="call_api", qualified_name="client.call_api"+ )+ ],+ )+ ex = DecisionExtractor(repo_path=tmp_path, parsed_files=[parsed])+ decisions = await ex.harvest_rationale_comments()++ assert len(decisions) == 1+ assert "client.call_api" in decisions[0].context+++async def test_code_comment_records_pass_the_gate_in_extract_all(tmp_path):+ (tmp_path / "client.py").write_text(_RATIONALE_PY, encoding="utf-8")++ ex = DecisionExtractor(repo_path=tmp_path)+ report = await ex.extract_all()++ assert report.by_source["code_comment"] == 1+ cc = [d for d in report.decisions if d.source == "code_comment"]+ assert len(cc) == 1+ # Verbatim comment → the substring gate stamps it exact, never rejects it.+ assert cc[0].verification == "exact"+++async def test_harvest_skips_untracked_files_in_a_git_repo(tmp_path):+ """In a git checkout the harvest scopes to tracked files: untracked /+ excluded working dirs (local-stash, scratch dumps) must not produce records.+ Gitless repos fall back to the full walk (the tmp_path tests above)."""+ import subprocess++ def _git(*args: str) -> None:+ subprocess.run(+ ["git", "-C", str(tmp_path), *args],+ check=True,+ capture_output=True,+ )++ _git("init")+ _git("config", "user.email", "[email protected]")+ _git("config", "user.name", "t")++ (tmp_path / "tracked.py").write_text(_RATIONALE_PY, encoding="utf-8")+ _git("add", "tracked.py")+ _git("commit", "-m", "add tracked")++ # An untracked file carrying a textbook rationale comment.+ (tmp_path / "untracked.py").write_text(+ "def f():\n"+ " # We special-case this because the upstream API double-encodes.\n"+ " return 1\n",+ encoding="utf-8",+ )++ ex = DecisionExtractor(repo_path=tmp_path)+ decisions = await ex.harvest_rationale_comments()++ files = {d.evidence_file for d in decisions}+ assert "tracked.py" in files+ assert "untracked.py" not in filesdiff --git a/tests/unit/server/mcp/test_answer_calibration.py b/tests/unit/server/mcp/test_answer_calibration.pyindex e36341622..ddb07f37b 100644--- a/tests/unit/server/mcp/test_answer_calibration.py+++ b/tests/unit/server/mcp/test_answer_calibration.py@@ -279,3 +279,259 @@ async def test_synthesized_answer_carries_grounded_quotes(setup_mcp, monkeypatchassert q["path"] == "pkg/alpha/one.py"assert q["lines"][0] == 10assert "MIN_COUNT = 2" in q["quote"]+ # A constant's body IS its one-line assignment — it belongs in `quotes`,+ # never the `symbol_bodies` definition block.+ assert not result.get("symbol_bodies")+++_FN_BODY_SYMBOL = {+ "name": "min_count_policy",+ "kind": "function",+ "signature": "def min_count_policy() -> int",+ "docstring": "Returns the default minimum count.",+ "start_line": 10,+ "end_line": 12,+ "_matched": True,+ "source_excerpt": "def min_count_policy() -> int:\n # gate retries\n return MIN_COUNT",+}+++async def test_named_function_carries_inline_body(setup_mcp, monkeypatch):+ """A named function symbol surfaces its full body in symbol_bodies so the+ agent skips the get_symbol follow-up."""+ 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_BODY_SYMBOL)+ _patch_provider(+ monkeypatch,+ answer_mod,+ "min_count_policy gates the retry loop (pkg/alpha/one.py).",+ )++ result = await get_answer("How does min_count_policy work?")+ bodies = result.get("symbol_bodies")+ assert bodies, "a named function symbol must carry an inline body"+ [b] = bodies+ assert b["path"] == "pkg/alpha/one.py"+ assert b["name"] == "min_count_policy"+ assert "return MIN_COUNT" in b["source"]+ assert b["lines"] == [10, 12]+ # Body served whole → no continuation pointer.+ assert "truncated" not in b+++async def test_inline_body_truncation_emits_continuation(setup_mcp, monkeypatch):+ """When the indexed body is longer than the hydrated excerpt, the body+ block names the exact range read for the remainder."""+ import repowise.server.mcp_server.tool_answer.answer as answer_mod+ from repowise.server.mcp_server import get_answer++ big = dict(_FN_BODY_SYMBOL, end_line=60) # excerpt covers 10-12, body ends at 60+ _patch_pipeline(monkeypatch, answer_mod, with_symbols=True, symbol=big)+ _patch_provider(+ monkeypatch,+ answer_mod,+ "min_count_policy gates the retry loop (pkg/alpha/one.py).",+ )++ result = await get_answer("How does min_count_policy work?")+ [b] = result["symbol_bodies"]+ assert b["truncated"] is True+ assert b["continuation"] == "pkg/alpha/one.py:13-60"+++# ---------------------------------------------------------------------------+# Symbol anchoring — force the defining file of a question-named symbol into+# the candidate set when fuzzy retrieval missed it.+# ---------------------------------------------------------------------------+++class _Sym:+ def __init__(+ self,+ name,+ file_path,+ kind="method",+ parent_name=None,+ qualified_name=None,+ start_line=1,+ end_line=10,+ ):+ self.name = name+ self.file_path = file_path+ self.kind = kind+ self.parent_name = parent_name+ self.qualified_name = qualified_name or name+ self.start_line = start_line+ self.end_line = end_line+++class _FakeResult:+ def __init__(self, rows):+ self._rows = rows++ def scalars(self):+ return self++ def all(self):+ return self._rows+++class _FakeSession:+ def __init__(self, rows):+ self._rows = rows++ async def execute(self, *a, **k):+ return _FakeResult(self._rows)+++async def test_anchor_injects_defining_file_as_dominant_hit():+ from repowise.server.mcp_server.tool_answer.symbols import _anchor_symbol_hits++ rows = [+ _Sym(+ "extract_all",+ "core/decisions/extractor.py",+ parent_name="DecisionExtractor",+ qualified_name="DecisionExtractor.extract_all",+ )+ ]+ hits = [{"target_path": "core/pipeline/incremental.py", "score": 3.6}]+ out = await _anchor_symbol_hits(+ _FakeSession(rows), "repo1", {"extract_all", "DecisionExtractor"}, hits+ )+ assert out[0]["target_path"] == "core/decisions/extractor.py"+ assert out[0]["_symbol_anchored"] is True+ assert out[0]["score"] > 3.6 # dominates the fuzzy top hit+++async def test_anchor_skips_ambiguous_homonym():+ from repowise.server.mcp_server.tool_answer.symbols import _anchor_symbol_hits++ rows = [+ _Sym("extract_all", "a/x.py", parent_name="A", qualified_name="A.extract_all"),+ _Sym("extract_all", "b/y.py", parent_name="B", qualified_name="B.extract_all"),+ ]+ hits = [{"target_path": "c/z.py", "score": 2.0}]+ out = await _anchor_symbol_hits(_FakeSession(rows), "r", {"extract_all"}, hits)+ assert all(not h.get("_symbol_anchored") for h in out)+ assert out[0]["target_path"] == "c/z.py" # nothing injected+++async def test_anchor_disambiguates_homonym_by_named_parent():+ from repowise.server.mcp_server.tool_answer.symbols import _anchor_symbol_hits++ rows = [+ _Sym("extract_all", "a/x.py", parent_name="Alpha", qualified_name="Alpha.extract_all"),+ _Sym(+ "extract_all",+ "b/y.py",+ parent_name="DecisionExtractor",+ qualified_name="DecisionExtractor.extract_all",+ ),+ ]+ hits = [{"target_path": "c/z.py", "score": 2.0}]+ out = await _anchor_symbol_hits(+ _FakeSession(rows), "r", {"extract_all", "DecisionExtractor"}, hits+ )+ assert out[0]["target_path"] == "b/y.py"+++async def test_anchor_boosts_existing_hit_without_duplicating():+ from repowise.server.mcp_server.tool_answer.symbols import _anchor_symbol_hits++ rows = [_Sym("get_symbol", "mcp/tool_symbol.py", kind="function", qualified_name="get_symbol")]+ hits = [+ {"target_path": "mcp/tool_symbol.py", "score": 9.4},+ {"target_path": "other.py", "score": 7.9},+ ]+ out = await _anchor_symbol_hits(_FakeSession(rows), "r", {"get_symbol"}, hits)+ paths = [h["target_path"] for h in out]+ assert paths.count("mcp/tool_symbol.py") == 1 # boosted, not duplicated+ anchored = next(h for h in out if h["target_path"] == "mcp/tool_symbol.py")+ assert anchored["_symbol_anchored"] is True+ assert anchored["score"] >= 9.4+++# ---------------------------------------------------------------------------+# code_rationale — the T4 lever: in-code rationale recovered when the wiki /+# decision corpus could not ground the question (low-confidence exits).+# ---------------------------------------------------------------------------+++async def test_hedged_answer_surfaces_code_rationale(setup_mcp, monkeypatch, tmp_path):+ """Hedged synthesis → mine the cited source for the rationale comment."""+ import repowise.server.mcp_server as mcp_mod+ import repowise.server.mcp_server.tool_answer.answer as answer_mod+ from repowise.server.mcp_server import get_answer++ _patch_pipeline(monkeypatch, answer_mod, with_symbols=True, symbol=_FN_SYMBOL)+ _patch_provider(+ monkeypatch,+ answer_mod,+ "The provided excerpts do not include the body of min_count_policy.",+ )+ (tmp_path / "pkg" / "alpha").mkdir(parents=True)+ (tmp_path / "pkg" / "alpha" / "one.py").write_text(+ "# min_count_policy defaults to 2 because the retry budget assumes\n"+ "# at least two attempts before giving up.\n"+ "MIN_COUNT = 2\n",+ encoding="utf-8",+ )+ monkeypatch.setattr(mcp_mod, "_repo_path", str(tmp_path))++ result = await get_answer("What is the default value of min_count_policy?")+ assert result["confidence"] == "low"+ assert "code_rationale" in result+ assert any("retry budget" in r["comment"] for r in result["code_rationale"])+ assert result["code_rationale"][0]["path"] == "pkg/alpha/one.py"+++async def test_gated_answer_surfaces_code_rationale(setup_mcp, monkeypatch, tmp_path):+ """Ambiguous retrieval (gated, no synthesis) → still mine source rationale."""+ import repowise.server.mcp_server as mcp_mod+ import repowise.server.mcp_server.tool_answer.answer as answer_mod+ from repowise.server.mcp_server import get_answer++ # Two near-tied hits (4.0 vs 3.8) → dominance gate fails → best_guesses path.+ async def _fake_retrieve(question, ctx):+ return [+ {"page_id": "file_page:pkg/alpha/one.py", "score": 4.0},+ {"page_id": "file_page:pkg/alpha/two.py", "score": 3.8},+ ]++ 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"] = "Module 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)++ (tmp_path / "pkg" / "alpha").mkdir(parents=True)+ (tmp_path / "pkg" / "alpha" / "one.py").write_text(+ "# We chunk uploads at 8MB instead of streaming because the gateway\n"+ "# buffers the whole body and OOMs on larger payloads.\n"+ "CHUNK = 8\n",+ encoding="utf-8",+ )+ monkeypatch.setattr(mcp_mod, "_repo_path", str(tmp_path))++ result = await get_answer("why do uploads chunk at 8mb")+ assert result["confidence"] == "low"+ assert "best_guesses" in result # confirms we hit the gated path+ assert "code_rationale" in result+ assert any("OOMs" in r["comment"] for r in result["code_rationale"])diff --git a/tests/unit/server/mcp/test_code_rationale.py b/tests/unit/server/mcp/test_code_rationale.pynew file mode 100644index 000000000..790e154f0--- /dev/null+++ b/tests/unit/server/mcp/test_code_rationale.py@@ -0,0 +1,171 @@+"""Unit tests for the in-code rationale miner (`_code_rationale`).++The miner recovers the "why" that lives in source comments — the unbiased+A/B's one durable loss (task T4): rationale in a code comment that neither+get_why's decision/git search nor get_answer's wiki retrieval can find.+"""++from __future__ import annotations++from repowise.server.mcp_server._code_rationale import (+ extract_comment_blocks,+ mine_rationale,+)++PY_SOURCE = '''import os++# We set PYTHONIOENCODING here because the Windows console uses cp1252+# and the checkmark glyph crashes the CLI otherwise.+ENCODING = "utf-8"++def divide(a, b):+ denom = b or 1 # fall back to 1 to avoid a divide-by-zero downstream+ return a / denom++# TODO: refactor this later+LIMIT = 50++class Bar:+ """Bar exists instead of a dict because callers need attribute access."""+ pass++URL = "https://example.com/path" # not a comment, lives in a string+'''++TS_SOURCE = """import { x } from 'y';++// We debounce at 200ms rather than 100ms because the API rate-limits+// bursts and a tighter window trips the limiter.+const DEBOUNCE = 200;++/* This block is a workaround for a Safari layout bug: flex-basis must be+ set explicitly or the panel collapses. */+function layout() {}++// plain label+const z = 1;+"""+++def _write(tmp_path, name, content):+ p = tmp_path / name+ p.write_text(content, encoding="utf-8")+ return p+++def test_extract_coalesces_multiline_python_comment():+ # Shared core tokenizer returns CommentBlock dataclasses; trailing inline+ # comments are recall-only (include_trailing=True), matching mine_rationale.+ blocks = extract_comment_blocks(PY_SOURCE, "py", include_trailing=True)+ texts = [b.text for b in blocks]+ # The two-line # comment becomes one block spanning lines 3-4.+ enc = next(b for b in blocks if "PYTHONIOENCODING" in b.text)+ assert enc.start_line == 3 and enc.end_line == 4+ assert "checkmark glyph crashes" in enc.text+ # Trailing inline comment recovered.+ assert any("divide-by-zero" in t for t in texts)+ # Docstring recovered.+ assert any("attribute access" in t for t in texts)+++def test_extract_handles_c_style_block_and_line_comments():+ blocks = extract_comment_blocks(TS_SOURCE, "ts")+ texts = [b.text for b in blocks]+ assert any("debounce" in t.lower() and "rate-limits" in t.lower() for t in texts)+ assert any("workaround for a Safari layout bug" in t for t in texts)+++def test_mine_ranks_marker_plus_query_overlap_first(tmp_path):+ _write(tmp_path, "mod.py", PY_SOURCE)+ out = mine_rationale(str(tmp_path), ["mod.py"], "why PYTHONIOENCODING windows console")+ assert out, "expected at least one rationale block"+ top = out[0]+ assert "PYTHONIOENCODING" in top["comment"]+ assert top["lines"] == [3, 4]+ assert "windows" in top["matched_terms"]+++def test_mine_path_mode_returns_marker_comments_without_query(tmp_path):+ _write(tmp_path, "mod.py", PY_SOURCE)+ out = mine_rationale(str(tmp_path), ["mod.py"], None)+ comments = " ".join(r["comment"] for r in out)+ # All three rationale-marker comments surface...+ assert "PYTHONIOENCODING" in comments+ assert "divide-by-zero" in comments+ assert "attribute access" in comments+ # ...but the bare "TODO: refactor" label (no rationale marker) does not.+ assert "refactor this later" not in comments+++def test_mine_drops_non_rationale_comments_under_query(tmp_path):+ _write(tmp_path, "mod.ts", TS_SOURCE)+ out = mine_rationale(str(tmp_path), ["mod.ts"], "debounce rate limit")+ assert any("debounce" in r["comment"].lower() for r in out)+ # "plain label" has neither a marker nor query overlap.+ assert all("plain label" not in r["comment"] for r in out)+++def test_mine_url_in_string_is_not_mistaken_for_comment(tmp_path):+ _write(tmp_path, "mod.py", PY_SOURCE)+ out = mine_rationale(str(tmp_path), ["mod.py"], None)+ assert all("example.com" not in r["comment"] for r in out)+++def test_mine_near_line_boost_prefers_comment_by_named_symbol(tmp_path):+ src = (+ "# generic note because of history\n" * 1+ + "x = 1\n" * 50+ + "# special-cased because the loader needs it early\n"+ + "def loader():\n pass\n"+ )+ _write(tmp_path, "m.py", src)+ near = {"m.py": 52} # the loader comment sits at ~line 52+ out = mine_rationale(str(tmp_path), ["m.py"], "loader", near_lines=near)+ assert out[0]["lines"][0] >= 50 # the near-line comment wins the tie+++def test_mine_is_bounded_and_safe(tmp_path):+ # Path escape: a file outside the root is refused, not read.+ _write(tmp_path, "mod.py", PY_SOURCE)+ assert mine_rationale(str(tmp_path), ["../../etc/passwd"], None) == []+ # No repo root → empty, no raise.+ assert mine_rationale(None, ["mod.py"], "x") == []+ # Empty file list → empty.+ assert mine_rationale(str(tmp_path), [], "x") == []+++def test_mine_drops_markerless_docstrings_when_a_marker_block_wins(tmp_path):+ """Generic query terms (lines/source/one) drag in plain docstrings; once a+ real rationale-marker block is found, the marker-less ones are dropped."""+ src = (+ '"""Slice text to source lines; one indexed symbol per call."""\n'+ "MAX = 1\n"+ "# The source line cap is 600 because round-trip count, not payload\n"+ "# size, dominates agent token cost.\n"+ "LIMIT = 600\n"+ )+ p = tmp_path / "s.py"+ p.write_text(src, encoding="utf-8")+ out = mine_rationale(str(tmp_path), ["s.py"], "why source lines cap one")+ assert out, "expected the rationale block to survive"+ # The marker block (has 'because') is the only one kept.+ assert all("because" in r["comment"] for r in out)+ assert any("round-trip count" in r["comment"] for r in out)+++def test_mine_keeps_term_only_blocks_when_no_marker_exists(tmp_path):+ """Recall fallback: if nothing carries a marker, strong term overlap still+ surfaces (so a marker-less but on-topic comment isn't lost)."""+ src = "# configures the source line buffer for one pass\nBUF = 1\n"+ p = tmp_path / "s.py"+ p.write_text(src, encoding="utf-8")+ out = mine_rationale(str(tmp_path), ["s.py"], "source line buffer pass")+ assert any("source line buffer" in r["comment"] for r in out)+++def test_mine_caps_result_count(tmp_path):+ # Many rationale comments → result list is capped (<= _MAX_RESULTS=6).+ lines = [f"# reason {i}: we avoid path {i} because it deadlocks\n" for i in range(40)]+ _write(tmp_path, "big.py", "".join(lines))+ out = mine_rationale(str(tmp_path), ["big.py"], None)+ assert 0 < len(out) <= 6diff --git a/tests/unit/server/mcp/test_context.py b/tests/unit/server/mcp/test_context.pyindex 68e9ccc5e..4d2fc2d5c 100644--- a/tests/unit/server/mcp/test_context.py+++ b/tests/unit/server/mcp/test_context.py@@ -467,3 +467,122 @@ async def test_file_target_callers_rolls_up_importers(setup_mcp):[middleware] = [c for c in callers if c["file"] == "src/auth/middleware.py"]assert middleware.get("imports") is Trueassert "rollup" in t.get("_call_graph_note", "")+++async def test_symbol_callers_carry_definition_line(setup_mcp, session):+ """Symbol-level callers must carry the caller's definition line so the+ agent jumps to it instead of grepping for the call-site position."""+ from repowise.core.persistence.models import GraphEdge, GraphNode, Repository+ from repowise.server.mcp_server import get_context++ repo = (await session.execute(__import__("sqlalchemy").select(Repository))).scalars().first()+ target_id = "src/auth/service.py::login"+ caller_id = "src/auth/service.py::caller_fn"+ session.add_all(+ [+ GraphNode(+ id="sgn_login",+ repository_id=repo.id,+ node_id=target_id,+ node_type="symbol",+ name="login",+ file_path="src/auth/service.py",+ kind="method",+ start_line=20,+ end_line=40,+ created_at=_NOW,+ ),+ GraphNode(+ id="sgn_caller",+ repository_id=repo.id,+ node_id=caller_id,+ node_type="symbol",+ name="caller_fn",+ file_path="src/auth/service.py",+ kind="function",+ start_line=55,+ end_line=70,+ created_at=_NOW,+ ),+ GraphEdge(+ id="sge_call",+ repository_id=repo.id,+ source_node_id=caller_id,+ target_node_id=target_id,+ edge_type="calls",+ confidence=0.95,+ created_at=_NOW,+ ),+ ]+ )+ await session.flush()++ result = await get_context([target_id], include=["callers"], compact=False)+ t = result["targets"][target_id]+ [caller] = [c for c in t.get("callers", []) if c["symbol_id"] == caller_id]+ assert caller["line"] == 55+++async def test_high_fan_in_callers_signal_truncation(setup_mcp, session):+ """A symbol with more callers than the display cap must report the TRUE+ total + a truncation flag, so a find-all-callers sweep is not silently+ misled into thinking the partial list is complete (S2 dogfood bug)."""+ from repowise.core.persistence.models import GraphEdge, GraphNode, Repository+ from repowise.server.mcp_server import get_context++ repo = (await session.execute(__import__("sqlalchemy").select(Repository))).scalars().first()+ target_id = "src/db/util.py::hot"+ nodes = [+ GraphNode(+ id="hot_tgt",+ repository_id=repo.id,+ node_id=target_id,+ node_type="symbol",+ name="hot",+ file_path="src/db/util.py",+ kind="function",+ start_line=10,+ end_line=20,+ created_at=_NOW,+ )+ ]+ edges = []+ n_callers = 75 # > the cap of 50+ for i in range(n_callers):+ cid = f"src/callers/c{i}.py::caller_{i}"+ nodes.append(+ GraphNode(+ id=f"hot_caller_{i}",+ repository_id=repo.id,+ node_id=cid,+ node_type="symbol",+ name=f"caller_{i}",+ file_path=f"src/callers/c{i}.py",+ kind="function",+ start_line=i + 1,+ end_line=i + 5,+ created_at=_NOW,+ )+ )+ edges.append(+ GraphEdge(+ id=f"hot_edge_{i}",+ repository_id=repo.id,+ source_node_id=cid,+ target_node_id=target_id,+ edge_type="calls",+ confidence=0.95,+ created_at=_NOW,+ )+ )+ session.add_all(nodes + edges)+ await session.flush()++ result = await get_context([target_id], include=["callers"], compact=False)+ t = result["targets"][target_id]+ assert len(t["callers"]) == 50 # capped display+ assert t["callers_total"] == n_callers # true total surfaced+ assert t["callers_truncated"] is True+ assert "grep" in t["_callers_note"]diff --git a/tests/unit/server/mcp/test_context_skeleton.py b/tests/unit/server/mcp/test_context_skeleton.pyindex 817f0647b..2954d0174 100644--- a/tests/unit/server/mcp/test_context_skeleton.py+++ b/tests/unit/server/mcp/test_context_skeleton.py@@ -53,6 +53,45 @@ async def test_skeleton_requires_file_target(setup_mcp, tmp_path, monkeypatch):assert "file target" in sk["error"]+async def test_skeleton_for_symbol_target_renders_defining_file(+ setup_mcp, session, tmp_path, monkeypatch+):+ """A "file.py::Symbol" target must skeleton the DEFINING FILE, not fail+ with an opaque read error on the literal "::"-path (S2 dogfood bug)."""+ from repowise.core.persistence.models import GraphNode, Repository+ from repowise.server.mcp_server import _state, get_context++ _write_source(tmp_path)+ monkeypatch.setattr(_state, "_repo_path", str(tmp_path))++ # get_context resolves a "::Symbol" target via its symbol graph node; the+ # base fixture only has file nodes, so add one for login.+ repo = (await session.execute(__import__("sqlalchemy").select(Repository))).scalars().first()+ target_id = "src/auth/service.py::login"+ session.add(+ GraphNode(+ id="sk_login",+ repository_id=repo.id,+ node_id=target_id,+ node_type="symbol",+ name="login",+ file_path="src/auth/service.py",+ kind="method",+ start_line=20,+ end_line=40,+ )+ )+ await session.flush()++ result = await get_context([target_id], include=["skeleton"])+ sk = result["targets"][target_id]["skeleton"]+ assert "error" not in sk+ assert "class AuthService:" in sk["text"] # whole file, not just the symbol+ assert sk["of_file"] == "src/auth/service.py"+ assert "get_symbol" in sk["symbol_hint"]++@pytest.mark.asyncioasync def test_skeleton_missing_source_file(setup_mcp, tmp_path, monkeypatch):from repowise.server.mcp_server import _state, get_contextdiff --git a/tests/unit/server/mcp/test_symbol_range_and_recovery.py b/tests/unit/server/mcp/test_symbol_range_and_recovery.pyindex d7ffb1afd..242fd6c11 100644--- a/tests/unit/server/mcp/test_symbol_range_and_recovery.py+++ b/tests/unit/server/mcp/test_symbol_range_and_recovery.py@@ -74,6 +74,71 @@ async def test_range_read_context_does_not_exceed_cap(setup_mcp, repo_on_disk):assert result["truncated"] is True+async def test_truncated_range_emits_continuation_token(setup_mcp, repo_on_disk):+ from repowise.server.mcp_server import get_symbol++ # 400-line request caps at 200; the remainder must come back as an exact,+ # ready-to-replay range read so the agent never guesses the next span.+ result = await get_symbol("pkg/big.py:1-400")+ assert result["truncated"] is True+ assert result["continuation"] == f"pkg/big.py:{result['end_line'] + 1}-400"+ assert "get_symbol" in result["note"]+++async def test_untruncated_range_has_no_continuation(setup_mcp, repo_on_disk):+ from repowise.server.mcp_server import get_symbol++ result = await get_symbol("pkg/big.py:1-50")+ assert result["truncated"] is False+ assert "continuation" not in result+++async def test_truncated_symbol_emits_continuation_token(setup_mcp, repo_on_disk, session):+ from sqlalchemy import select++ from repowise.core.persistence.models import Repository, WikiSymbol+ from repowise.server.mcp_server import get_symbol++ # A whole-file function (def on line 1, body to EOF) that overruns the+ # serve cap. The served head must hand back the remaining span.+ body = "\n".join(f" a{i} = {i}" for i in range(1, 699))+ big_fn = f"def big_fn(x):\n{body}\n return x\n" # 700 lines, ends at EOF+ (repo_on_disk / "pkg" / "bigfn.py").write_text(big_fn)+ total = len(big_fn.splitlines())++ repo = (await session.execute(select(Repository))).scalars().first()+ session.add(+ WikiSymbol(+ id="bigfn1",+ repository_id=repo.id,+ file_path="pkg/bigfn.py",+ symbol_id="pkg/bigfn.py::big_fn",+ name="big_fn",+ qualified_name="pkg.bigfn.big_fn",+ kind="function",+ signature="def big_fn(x)",+ start_line=1,+ end_line=total,+ language="python",+ )+ )+ await session.flush()++ result = await get_symbol("pkg/bigfn.py::big_fn")+ assert result["truncated"] is True+ assert result["verified"] is True+ assert result["continuation"] == f"pkg/bigfn.py:{result['end_line'] + 1}-{total}"+ assert "get_symbol" in result["note"]+ # The continuation token round-trips to a clean range read of the tail.+ tail = await get_symbol(result["continuation"])+ assert tail.get("error") is None+ assert tail["kind"] == "range"+ assert "return x" in tail["source"]++@pytest.mark.asyncioasync def test_range_read_swaps_reversed_bounds(setup_mcp, repo_on_disk):from repowise.server.mcp_server import get_symboldiff --git a/tests/unit/server/mcp/test_why.py b/tests/unit/server/mcp/test_why.pyindex be6124917..53a66d7fc 100644--- a/tests/unit/server/mcp/test_why.py+++ b/tests/unit/server/mcp/test_why.py@@ -192,6 +192,53 @@ async def test_get_why_module_path(setup_mcp):assert any(d["title"] == "SQLAlchemy as ORM" for d in result["decisions"])+async def test_get_why_path_surfaces_code_rationale(setup_mcp, tmp_path):+ """Ungoverned file whose 'why' lives in a code comment → code_rationale."""+ import repowise.server.mcp_server as mcp_mod+ from repowise.server.mcp_server import get_why++ # Point the repo root at a real dir holding a rationale-bearing source file.+ (tmp_path / "src" / "other").mkdir(parents=True)+ (tmp_path / "src" / "other" / "widget.py").write_text(+ "# We poll every 5s instead of using a webhook because the upstream\n"+ "# service drops connections behind their proxy.\n"+ "POLL_INTERVAL = 5\n",+ encoding="utf-8",+ )+ mcp_mod._repo_path = str(tmp_path)++ result = await get_why("src/other/widget.py")+ assert result["mode"] == "path"+ assert len(result["decisions"]) == 0 # ungoverned → fallback fires+ assert "code_rationale" in result+ top = result["code_rationale"][0]+ assert "webhook" in top["comment"]+ assert top["path"] == "src/other/widget.py"+ assert top["lines"][0] == 1+++async def test_get_why_targets_surfaces_code_rationale(setup_mcp, tmp_path):+ """Search with a target lacking decisions → mine the target's comments."""+ import repowise.server.mcp_server as mcp_mod+ from repowise.server.mcp_server import get_why++ (tmp_path / "src" / "other").mkdir(parents=True)+ (tmp_path / "src" / "other" / "cache.py").write_text(+ "import time\n"+ "# TTL is 30s because shorter windows thrash the backing store\n"+ "TTL = 30\n",+ encoding="utf-8",+ )+ mcp_mod._repo_path = str(tmp_path)++ result = await get_why("why this ttl value", targets=["src/other/cache.py"])+ assert result["mode"] == "search"+ assert "code_rationale" in result+ assert any("thrash" in r["comment"] for r in result["code_rationale"])++@pytest.mark.asyncioasync def test_get_why_semantic_decision_namespace_filtering(setup_mcp):"""Mode 3 semantic path: over-fetch from page store, keep only decision: hits.diff --git a/tests/unit/server/test_mcp_decision_graph.py b/tests/unit/server/test_mcp_decision_graph.pyindex 2308dc885..7629b7055 100644--- a/tests/unit/server/test_mcp_decision_graph.py+++ b/tests/unit/server/test_mcp_decision_graph.py@@ -414,96 +414,75 @@ async def setup_mcp_decisions(factory, fts, vector_store, decision_db):# ----------------------------------------------------------------------------# Task 1: get_context — governing_decisions field+# Task 1: get_context — decisions are opt-in (include=["decisions"])# ---------------------------------------------------------------------------@pytest.mark.asyncio-async def test_get_context_governing_decisions_present(setup_mcp_decisions):- """governing_decisions is populated via bounded graph query, not full scan."""+async def test_get_context_decisions_omitted_by_default(setup_mcp_decisions):+ """The default triage card carries no decision fields — they're opt-in.++ The enriched ``governing_decisions`` form (id/staleness/verification) was+ dropped entirely; an agent that wants rationale calls get_why directly.+ """from repowise.server.mcp_server import get_contextresult = await get_context(["src/auth/service.py"], include=["docs", "freshness"])t = result["targets"]["src/auth/service.py"]- # Backward-compat field still present+ assert "decision_records" not in t+ assert "decision_records_hint" not in t+ assert "governing_decisions" not in t+++async def test_get_context_decisions_opt_in_titles(setup_mcp_decisions):+ """include=["decisions"] returns a lightweight titles list + hint only."""+ from repowise.server.mcp_server import get_context++ result = await get_context(["src/auth/service.py"], include=["docs", "decisions"])+ t = result["targets"]["src/auth/service.py"]+assert "decision_records" in ttitles = t["decision_records"]assert isinstance(titles, list)- assert len(titles) >= 1+ assert 1 <= len(titles) <= 3assert "Use JWT for authentication" in titles-- # New governing_decisions field- assert "governing_decisions" in t- govs = t["governing_decisions"]- assert isinstance(govs, list)- assert len(govs) >= 1-- # Check dict shape- for gd in govs:- assert "id" in gd- assert "title" in gd- assert "status" in gd- assert "staleness_score" in gd- assert "verification" in gd- assert "stale" in gd- assert isinstance(gd["stale"], bool)-- # dec_stale is active with staleness_score=0.8 → stale=True- stale_entries = [g for g in govs if g["id"] == "dec_stale"]- assert stale_entries, "dec_stale should appear in governing_decisions"- assert stale_entries[0]["stale"] is True-- # dec_active has staleness_score=0.1 → stale=False- active_entries = [g for g in govs if g["id"] == "dec_active"]- assert active_entries- assert active_entries[0]["stale"] is False-- # hint presentassert "decision_records_hint" in t+ # The heavy enriched objects are no longer emitted.+ assert "governing_decisions" not in t+@pytest.mark.asyncio-async def test_get_context_governing_decisions_sorted_by_confidence(setup_mcp_decisions):- """governing_decisions is sorted highest-confidence first."""+async def test_get_context_decision_titles_sorted_by_confidence(setup_mcp_decisions):+ """decision_records titles are highest-confidence first."""from repowise.server.mcp_server import get_context- result = await get_context(["src/auth/service.py"], include=["docs"])+ result = await get_context(["src/auth/service.py"], include=["decisions"])t = result["targets"]["src/auth/service.py"]- govs = t.get("governing_decisions", [])- if len(govs) > 1:- confidences = []- for g in govs:- # Find confidence from dec records- if g["id"] == "dec_active":- confidences.append(0.9)- elif g["id"] == "dec_stale":- confidences.append(0.5)- elif g["id"] == "dec_superseded":- confidences.append(0.4)- # Ensure non-increasing order- for i in range(len(confidences) - 1):- assert confidences[i] >= confidences[i + 1], (- f"governing_decisions not sorted by confidence at index {i}"- )+ titles = t.get("decision_records", [])+ # dec_active (conf 0.9) outranks dec_stale (0.5) and dec_superseded (0.4),+ # so its title leads when all three govern the file.+ if "Use JWT for authentication" in titles and len(titles) > 1:+ assert titles[0] == "Use JWT for authentication"@pytest.mark.asyncio-async def test_get_context_no_governing_decisions_for_ungoverned_file(setup_mcp_decisions):- """Files with no decision node links produce no governing_decisions field."""+async def test_get_context_decision_titles_for_governed_file(setup_mcp_decisions):+ """A file governed by a decision link surfaces its title under include=["decisions"]."""from repowise.server.mcp_server import get_context- result = await get_context(["src/db/models.py"], include=["docs"])+ result = await get_context(["src/db/models.py"], include=["decisions"])t = result["targets"]["src/db/models.py"]- # dec_db governs src/db/models.py via link — should appear- govs = t.get("governing_decisions", [])- assert any(g["id"] == "dec_db" for g in govs)+ # dec_db governs src/db/models.py via DecisionNodeLink — titles must be present.+ assert t.get("decision_records")@pytest.mark.asyncio-async def test_get_context_governing_decisions_capped_at_five(setup_mcp_decisions, session):- """governing_decisions is capped at 5 entries."""+async def test_get_context_decision_titles_capped_at_three(setup_mcp_decisions, session):+ """decision_records titles are capped at 3 entries."""from repowise.server.mcp_server import get_contextrid = "repo1"@@ -540,10 +519,10 @@ async def test_get_context_governing_decisions_capped_at_five(setup_mcp_decisionsession.add(lnk)await session.flush()- result = await get_context(["src/auth/service.py"], include=["docs"])+ result = await get_context(["src/auth/service.py"], include=["decisions"])t = result["targets"]["src/auth/service.py"]- govs = t.get("governing_decisions", [])- assert len(govs) <= 5, f"governing_decisions should be capped at 5, got {len(govs)}"+ titles = t.get("decision_records", [])+ assert len(titles) <= 3, f"decision_records should be capped at 3, got {len(titles)}"# ---------------------------------------------------------------------------