Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

MCP get_answer/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.py
index 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 Any
import structlog
from 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 each
sub-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-hallucination
substring 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 descend
dirnames[:] = [
@@ -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 fpath
def _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.py
index 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 harvest
diff --git a/packages/core/src/repowise/core/analysis/decisions/rationale_comments.py b/packages/core/src/repowise/core/analysis/decisions/rationale_comments.py
new file mode 100644
index 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.j2
index 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.py
index 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 = 8
if 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.py
new file mode 100644
index 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.py
index 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.py
index 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 Read
to 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 contextlib
import json as _json
import logging
import time
+from pathlib import Path
from 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_rationale
from 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 returns
best_guesses with one-line justifications instead of an empty answer.
retrieval_quality separately rates the retrieval that fed synthesis.
+ When the answer names a function/method/class, ``symbol_bodies`` carries
+ 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_bodies
if 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.py
index 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 primary
diff --git a/packages/server/src/repowise/server/mcp_server/tool_answer/symbols.py b/packages/server/src/repowise/server/mcp_server/tool_answer/symbols.py
index 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 select
from repowise.core.persistence.models import WikiSymbol
from 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 | No
return 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:
continue
diff --git a/packages/server/src/repowise/server/mcp_server/tool_context/enrichment.py b/packages/server/src/repowise/server/mcp_server/tool_context/enrichment.py
index 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 json
from dataclasses import asdict
from typing import Any
-from sqlalchemy import select
+from sqlalchemy import distinct, func, select
from sqlalchemy.ext.asyncio import AsyncSession
from 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_path
if other_node
else (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"] = True
async def _resolve_file_level_callers(
@@ -458,7 +502,14 @@ async def _resolve_skeleton(
a symbol's "skeleton" is just its signature, which the triage card
already 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."}
return
if 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.py
index 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.py
index 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 = end
requested_truncated = (end - start + 1) > _MAX_RANGE_LINES
if 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_replaced
declare_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 than
Read+offset math. ``verified: true`` = bounds checked (or corrected)
against the live file: no follow-up Read needed. ``bounds:
"approximate"`` = the symbol moved and re-location failed. Also serves
live range reads ("path.py:140-180", ≤200 lines, always verified) and
omission refs ("repowise#<12-hex>"). Index misses grep the live file
- and return fallback_lines instead of a dead end.
+ 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.py
index 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_rationale
from 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"] = rationale
result_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"] = rationale
result_data["_meta"] = _build_meta(repository=repository)
return result_data
diff --git a/tests/unit/analysis/test_decision_rationale_comments.py b/tests/unit/analysis/test_decision_rationale_comments.py
new file mode 100644
index 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 files
diff --git a/tests/unit/server/mcp/test_answer_calibration.py b/tests/unit/server/mcp/test_answer_calibration.py
index 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, monkeypatch
assert q["path"] == "pkg/alpha/one.py"
assert q["lines"][0] == 10
assert "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.py
new file mode 100644
index 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) <= 6
diff --git a/tests/unit/server/mcp/test_context.py b/tests/unit/server/mcp/test_context.py
index 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 True
assert "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.py
index 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.asyncio
async def test_skeleton_missing_source_file(setup_mcp, tmp_path, monkeypatch):
from repowise.server.mcp_server import _state, get_context
diff --git a/tests/unit/server/mcp/test_symbol_range_and_recovery.py b/tests/unit/server/mcp/test_symbol_range_and_recovery.py
index 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.asyncio
async def test_range_read_swaps_reversed_bounds(setup_mcp, repo_on_disk):
from repowise.server.mcp_server import get_symbol
diff --git a/tests/unit/server/mcp/test_why.py b/tests/unit/server/mcp/test_why.py
index 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.asyncio
async 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.py
index 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_context
result = 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 t
titles = t["decision_records"]
assert isinstance(titles, list)
- assert len(titles) >= 1
+ assert 1 <= len(titles) <= 3
assert "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 present
assert "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_context
rid = "repo1"
@@ -540,10 +519,10 @@ async def test_get_context_governing_decisions_capped_at_five(setup_mcp_decision
session.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)}"
# ---------------------------------------------------------------------------