Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
fix(why): stop claiming a ruling the store does not hold (#2280)
Raghav Chamadiyad6261e12f999
diff --git a/packages/cli/src/repowise/cli/commands/why_cmd.py b/packages/cli/src/repowise/cli/commands/why_cmd.pyindex 7598220ff..2a39517a8 100644--- a/packages/cli/src/repowise/cli/commands/why_cmd.py+++ b/packages/cli/src/repowise/cli/commands/why_cmd.py@@ -96,6 +96,13 @@ def _project_target_entry(entry: dict) -> dict:``git_archaeology`` the same three capped layers."""out: dict = {"governing_decisions": entry.get("governing_decisions") or []}+ # Both authority lanes. Dropping the candidate one here would print an+ # empty card for every repository with no acceptances, which is most of+ # them: the tool moved unaccepted records out of ``governing_decisions``+ # precisely so they stop reading as rules, not so they stop being shown.+ for key in ("candidate_decisions", "candidate_decisions_omitted"):+ if entry.get(key):+ out[key] = entry[key]origin = entry.get("origin") or {}if origin:out["origin"] = {@@ -374,6 +381,19 @@ def _render(projected: dict) -> None:console.print(f" {governing.get('title', '')} [dim]({governing.get('status', '')})[/dim]")+ for candidate in entry.get("candidate_decisions") or []:+ # Labelled, never printed beside the rules unmarked. Nobody has+ # accepted these, so they are a review request and not a rule.+ console.print(+ f" [dim]candidate:[/dim] {candidate.get('title', '')} "+ f"[dim]({candidate.get('status', '')})[/dim]"+ )+ omitted = entry.get("candidate_decisions_omitted") or {}+ if omitted.get("suppressed"):+ console.print(+ f" [dim]{omitted['suppressed']} candidate(s) not matching the "+ f"question. {omitted.get('recover_with', '')}[/dim]"+ )origin = entry.get("origin") or {}if origin.get("summary"):# Only set when there is no git history — the short "No git historydiff --git a/packages/server/src/repowise/server/mcp_server/_why_evidence.py b/packages/server/src/repowise/server/mcp_server/_why_evidence.pyindex 3da1a49c1..4692a3fe5 100644--- a/packages/server/src/repowise/server/mcp_server/_why_evidence.py+++ b/packages/server/src/repowise/server/mcp_server/_why_evidence.py@@ -560,8 +560,13 @@ def annotate_response_evidence(for context in (result.get("target_context") or {}).values():if not isinstance(context, dict):continue- for row in context.get("governing_decisions") or []:- if isinstance(row, dict):+ # Both authority lanes. A candidate is the row a reader is most likely+ # to want the provenance of, because deciding whether to accept it is+ # the whole reason it is on the page.+ for lane in ("governing_decisions", "candidate_decisions"):+ for row in context.get(lane) or []:+ if not isinstance(row, dict):+ continuecandidates = records_by_title.get(str(row.get("title") or ""), [])if len(candidates) == 1:row["id"] = candidates[0].iddiff --git a/packages/server/src/repowise/server/mcp_server/_why_relevance.py b/packages/server/src/repowise/server/mcp_server/_why_relevance.pyindex 20377a118..4a4eb7f25 100644--- a/packages/server/src/repowise/server/mcp_server/_why_relevance.py+++ b/packages/server/src/repowise/server/mcp_server/_why_relevance.py@@ -18,6 +18,7 @@ anything.from __future__ import annotationsimport math+from collections.abc import Callablefrom typing import Anyfrom repowise.server.mcp_server._query_terms import content_terms@@ -153,6 +154,36 @@ def clears_floor(score: float) -> bool:return score >= RELEVANCE_FLOOR+def query_scorer(query: str, corpus: list[str]) -> Callable[[str], float]:+ """A ``text -> relevance`` function bound to *query* and *corpus*'s rarity.++ The same judgement the decision ranker makes, exposed for the blocks a+ target-anchored call carries beside the ranked records. Those blocks are+ built from a path and never saw the question, so on this repo two unrelated+ questions about one file returned byte-identical governing decisions, origin+ stories and episodes — and at 13,397 of a 20,000-char response they crowded+ out the mined comment that actually answered both.++ *corpus* supplies the rarity half, so pass the whole population a block is+ drawn from rather than the survivors: idf computed over three episodes makes+ every word one of them happens to share look ordinary.+ """+ terms = question_terms(query)+ idf = term_idf(terms, corpus)+ return lambda text: relevance(text.lower(), idf)+++def recovery_note(total: int, recall: str) -> dict[str, Any]:+ """What a block reduces to when a query is present and nothing bears on it.++ A count and the exact call that returns the block in full. Silence would be+ a lie by omission — the reader cannot tell "this file has no history" from+ "none of its history mentions what you asked" — and the full block is the+ padding that teaches an agent the tool is not worth calling.+ """+ return {"suppressed": total, "reason": "query-irrelevant", "recover_with": recall}++# --- Redirect ---------------------------------------------------------------## What to return when nothing clears the floor. The premise of the whole tool is@@ -196,3 +227,31 @@ def redirect_for(query: str) -> dict[str, Any]:"carrying its terms, and the closest ones would be noise."),}+++def redirect_when_served(lanes: list[str], recall: str) -> dict[str, Any]:+ """The redirect for a call that missed the store but *answered anyway*.++ Once the relevance floor started rejecting target-anchored records, the+ branch that used to serve three unrelated decisions began serving this+ file's mined rationale comments instead — and on the two questions this was+ measured with, that lane carried the exact docstring each one was asking+ about, where ``get_answer`` scoped to the same file returned "No wiki hits"+ and unscoped returned a hedge that said its excerpts did not include the+ symbol.++ So the plain redirect is withdrawn here. Naming another tool beside a+ correct answer is worse than naming none: the agent pays for a second call+ to reach something weaker, and learns from that trade that this tool's+ answers are not to be acted on. What is left is the true and narrower+ statement — the *decision store* was silent, these other lanes were not.+ """+ served = " and ".join(lanes)+ return {+ "reason": (+ f"No decision record covers this question. This file's {served} "+ "carry what the store does not. Read them here, as evidence from "+ "the code rather than as a ruling. For this file's full history, "+ f"unfiltered by the question: {recall}."+ )+ }diff --git a/packages/server/src/repowise/server/mcp_server/tool_why.py b/packages/server/src/repowise/server/mcp_server/tool_why.pyindex ed925a102..2b9f6ddf4 100644--- a/packages/server/src/repowise/server/mcp_server/tool_why.py+++ b/packages/server/src/repowise/server/mcp_server/tool_why.py@@ -14,6 +14,7 @@ from sqlalchemy import selectfrom repowise.core.analysis.decision_semantic_match import DECISION_VECTOR_PREFIXfrom repowise.core.analysis.decisions.lifecycle import is_governing, status_rankfrom repowise.core.persistence.crud.authority import (+ accepted_decision_ids,decision_currencies,resolve_decision_id,)@@ -59,8 +60,11 @@ from repowise.server.mcp_server._why_evidence import ()from repowise.server.mcp_server._why_relevance import (clears_floor,+ query_scorer,question_terms,+ recovery_note,redirect_for,+ redirect_when_served,relevance,term_idf,)@@ -79,13 +83,40 @@ def _has_archaeology(archaeology: Any) -> bool:)+def _is_accepted_row(row: Any) -> bool:+ """Whether an emitted decision row rests on an acceptance.++ Reads the ``authority`` key this module stamps rather than ``status``, for+ the reason ``decision_currencies`` gives: the column is a projection every+ writer keeps in step, and it agrees right up until something writes it+ without an acceptance. A row with no ``authority`` at all is a semantic hit+ projected from the vector store, which carries no record to join on and so+ cannot be claimed as accepted either.+ """+ return isinstance(row, dict) and row.get("authority") == "accepted"++def _stamp_answer_basis(result: dict) -> dict:"""Name the strongest lane the response actually rests on.This tool serves commit messages and mined comments beside decision- records. Only a decision is a ruling; the rest are evidence a reader has to- weigh. Per-row ``provenance`` answers that one row at a time, which is no- help in deciding how much of the whole response to trust.+ records. Only an *accepted* decision is a ruling; the rest are evidence a+ reader has to weigh. Per-row ``provenance`` answers that one row at a time,+ which is no help in deciding how much of the whole response to trust.++ ``decision`` requires an acceptance, not a record. A ``DecisionRecord`` is a+ candidate until a ``DecisionAcceptance`` row exists for it, and accepting is+ a deliberate manual step, so a store of nothing but candidates is the state+ every user who has not worked through the acceptance UI is in — the common+ case, not an edge one. Stamping ``decision`` off the mere presence of a+ record therefore claimed a ruling on most calls this tool ever serves, and+ it did so beside titles like "Do not ship UI components yet": session+ artifacts nobody confirmed, presented as governing.++ ``candidate`` sits *below* every evidence lane rather than above them for+ the same reason. A mined comment or a commit message is something a reader+ can weigh; an unconfirmed candidate is a guess about what somebody once+ meant, so it must not outrank the lanes that carry real evidence.Absent when nothing was served, so a refusal cannot read as an answer.Re-derived after the budget pass has shed, so the claim cannot outlive the@@ -95,7 +126,15 @@ def _stamp_answer_basis(result: dict) -> dict:entries = [e for e in (result.get("target_context") or {}).values() if isinstance(e, dict)]- if result.get("decisions") or any(e.get("governing_decisions") for e in entries):+ decision_rows = [+ *(result.get("decisions") or []),+ *(r for e in entries for r in (e.get("governing_decisions") or [])),+ ]+ candidate_rows = [+ *(r for e in entries for r in (e.get("candidate_decisions") or [])),+ *(r for r in decision_rows if not _is_accepted_row(r)),+ ]+ if any(_is_accepted_row(r) for r in decision_rows):result["answer_basis"] = "decision"elif result.get("episodes"):result["answer_basis"] = "episode"@@ -107,6 +146,8 @@ def _stamp_answer_basis(result: dict) -> dict:result["answer_basis"] = "archaeology"elif result.get("related_documentation"):result["answer_basis"] = "documentation"+ elif candidate_rows:+ result["answer_basis"] = "candidate"return result@@ -150,10 +191,12 @@ async def get_why((decision health dashboard). Falls back to git archaeology when nodecisions exist for a path — never empty. Evidence-bearing rows carry anexplicit ``provenance`` and self-contained ``evidence_refs``; matching ids- mean shared evidence, not independent corroboration. ``answer_basis`` names- the strongest lane the response rests on (decision, episode, rationale,- archaeology, documentation); only a decision is a ruling, the rest are- evidence to weigh.+ mean shared evidence, not independent corroboration. Every decision row+ carries ``authority``: ``accepted`` means somebody signed it, ``candidate``+ means nobody has yet. ``answer_basis`` names the strongest lane the response+ rests on (decision, episode, rationale, archaeology, documentation,+ candidate); only ``decision`` is a ruling, and ``candidate`` is the weakest+ -- it means nothing cleared that bar.Args:query: question, file/module path, or omit for the dashboard.@@ -212,7 +255,7 @@ async def _why_reference() -> dict[str, Any]:"""Resolve one emitted decision/evidence id without relevance search."""- ctx, repository, records, _target_git = await _load_corpus(repo, None)+ ctx, repository, records, _target_git, accepted = await _load_corpus(repo, None)async with get_session(ctx.session_factory) as session:await _attach_decision_evidence(session, records)# This tool tells callers to hold onto the ids it emits, so an id quoted@@ -234,6 +277,7 @@ async def _why_reference(_get_exclude_spec(ctx.path),),[],+ accepted=accepted,)for record in records]@@ -613,6 +657,18 @@ _MAX_HEALTH_PROPOSED = 5_MAX_HEALTH_UNGOVERNED = 8+def _authority_of(decision_id: str, accepted: set[str]) -> str:+ """``"accepted"`` when an acceptance binds this record, else ``"candidate"``.++ The one test that separates the two entities, per+ :func:`~repowise.core.persistence.crud.authority.decision_currencies`:+ membership of the acceptance set, never ``status``. Stamped on every row+ this tool emits so a reader — and :func:`_stamp_answer_basis` — can tell a+ ruling from a guess without a second call.+ """+ return "accepted" if decision_id in accepted else "candidate"++def _path_decision_sort_key(d: Any) -> tuple[int, float, float]:return (status_rank(d.status),@@ -626,12 +682,14 @@ def _governing_decision_entry(affected_files: list,lineage: list[dict],collector: OmissionCollector | None = None,+ accepted: set[str] | None = None,) -> dict:"""Serialize a decision that governs a path, including its lineage chain."""entry = {"id": d.id,"title": d.title,"status": d.status,+ "authority": _authority_of(d.id, accepted or set()),"context": d.context,"decision": _decision_body(d),"rationale": d.rationale,@@ -969,6 +1027,7 @@ async def _why_path(query: str, repo: str | None) -> dict:)currency = currencies.get(d.id)if currency is None:+ entry["authority"] = "candidate"# Never accepted. It goes in its own lane, labelled, rather# than into the list an agent reads as the rules for this file.entry["review_state"] = "open"@@ -976,8 +1035,12 @@ async def _why_path(query: str, repo: str | None) -> dict:continueentry["currency"] = currencyif is_governing(currency):+ entry["authority"] = "accepted"governing.append(entry)else:+ # Accepted once, withdrawn since: not a ruling any more, so it+ # must not read as one to ``_stamp_answer_basis`` either.+ entry["authority"] = "withdrawn"# Accepted once and withdrawn since. Not a rule and not a# review request, so it gets a third lane rather than being# dropped: on a file whose only record was superseded, dropping@@ -1140,15 +1203,6 @@ async def _load_target_git(return target_git-def _governs_any(d: Any, targets: set[str]) -> bool:- """Whether *d* names any of *targets* among its files or modules."""- if not targets:- return False- affected = set(json.loads(d.affected_files_json))- modules = json.loads(d.affected_modules_json)- return any(t in affected or any(t.startswith(m + "/") for m in modules) for t in targets)--def _score_keyword_matches(all_decisions: list, query: str, target_set: set[str]) -> list[tuple[tuple[float, float, int], Any]]:@@ -1169,11 +1223,22 @@ def _score_keyword_matches(scored_decisions: list[tuple[float, float, int, Any]] = []for d in all_decisions:- # A record governing a file the caller named is relevant by- # construction: they pointed at it instead of describing it, so it owes- # the question no vocabulary.- governs = _governs_any(d, target_set)- score = 1.0 if governs else relevance(texts[id(d)], idf)+ # Naming a file used to be a floor bypass: a record governing a target+ # scored 1.0 outright, on the reasoning that a caller who pointed at a+ # file instead of describing it left the record owing the question no+ # vocabulary. That reasoning holds for a call with *no* query, and this+ # function is never reached without one. With a query it meant the same+ # store, the same question and the same second refused without targets+ # and answered with them — measured on this repo, "why does+ # changed_lines() drop deletion-only files" came back led by "Move risk+ # scale reference metadata behind opt-in inclusion", whose only claim to+ # the question was appearing in the same directory.+ #+ # So every record is scored on what it says about the question. Naming a+ # target stays worth 5.0 in the ``_score_decision`` tie-break below, so a+ # governing record still outranks an equally relevant stranger; it just+ # no longer enters on a file path alone.+ score = relevance(texts[id(d)], idf)if not clears_floor(score):continuescored_decisions.append(@@ -1417,6 +1482,7 @@ def _merge_decisions(decision_results: list,lineage_by_id: dict[str, list[dict]],collector: OmissionCollector | None = None,+ accepted: set[str] | None = None,) -> list[dict]:"""Project collapsed keyword hits, then append semantic hits not already in.@@ -1435,6 +1501,7 @@ def _merge_decisions("id": d.id,"title": d.title,"status": d.status,+ "authority": _authority_of(d.id, accepted or set()),"decision": _decision_body(d),"rationale": d.rationale,"context": d.context,@@ -1472,6 +1539,7 @@ def _merge_decisions("title": r.title,"snippet": r.snippet,"relevance_score": r.score,+ "authority": _authority_of(real_id, accepted or set()),})return merged_decisions@@ -1484,8 +1552,21 @@ async def _build_target_context(target_git: dict[str, Any],targets: list[str],collector: OmissionCollector | None = None,+ accepted: set[str] | None = None,) -> dict[str, Any]:- """Per-target governing decisions + origin story, with archaeology fallback."""+ """Per-target governing decisions + origin story, with archaeology fallback.++ ``governing_decisions`` holds only records an acceptance binds; unaccepted+ ones go to ``candidate_decisions`` under the name they have earned. The two+ lanes were one, and on a store with no acceptances — the state of every+ repository whose maintainer has not worked through the acceptance UI — that+ one lane presented candidates as governing the file.++ The archaeology fallback is therefore keyed on the *accepted* lane. A file+ whose only records are candidates is a file no decision governs, which is+ exactly the case the fallback exists for, and its commits are stronger+ evidence than an unconfirmed candidate is.+ """async with get_session(ctx.session_factory) as session2:# Load all git metadata for cross-file searchall_git_res = await session2.execute(@@ -1504,15 +1585,19 @@ async def _build_target_context(if t in affected or any(t.startswith(m + "/") for m in affected_mods):governing_records.append(d)governing_records.sort(key=_path_decision_sort_key)- t_governing = [+ accepted_ids = accepted or set()+ rows = [{"id": d.id,"title": d.title,"status": d.status,"source": d.source,+ "authority": _authority_of(d.id, accepted_ids),}for d in governing_records]+ t_governing = [r for r in rows if r["authority"] == "accepted"]+ t_candidates = [r for r in rows if r["authority"] != "accepted"]git_m = target_git.get(t)origin = (_build_origin_story(t, git_m, t_governing)@@ -1526,7 +1611,9 @@ async def _build_target_context("governing_decisions": t_governing,"origin": origin,}- # Git archaeology fallback when no decisions found+ if t_candidates:+ ctx_entry["candidate_decisions"] = t_candidates+ # Git archaeology fallback when no *accepted* decision governsif not t_governing:ctx_entry["git_archaeology"] = await _git_archaeology_fallback(t,@@ -1539,23 +1626,125 @@ async def _build_target_context(return target_context+def _focus_target_context(+ target_context: dict[str, Any],+ query: str,+ targets: list[str],+ corpus: list[str],+) -> None:+ """Drop from each target card whatever does not bear on *query*, in place.++ A target card is built from a path, so without this it answers the same+ bytes to every question asked about that file. Measured on this repo, two+ unrelated questions about ``changed_lines.py`` returned byte-identical+ ``candidate_decisions``, ``origin`` and ``git_archaeology``, together 13,397+ of a 20,000-char response, while the mined comment that answered both sat+ below them.++ Only when a query is present. A call with targets and no query *is* the+ dashboard for those files, and there is nothing to be relevant to.++ Each block reduces to a count and the call that recovers it in full, never+ to silence: "no history mentions what you asked" and "no history" are+ different answers and the reader has to be able to tell them apart.+ """+ recall = f"get_why(targets={json.dumps(targets)})"+ # One scorer for the whole response, built from the decision corpus — the+ # same vocabulary the ranked lane is judged against, so one question gets+ # one set of term weights everywhere in the answer.+ #+ # Deriving rarity from the card's own handful of strings was tried first and+ # is the degeneracy ``term_idf`` warns about: over three short rows, a word+ # none of them happens to contain outweighs the two that identify the+ # answer, and "why is JWT used for authentication" scored the row titled+ # "Use JWT for authentication" at 0.489 — under the floor, on the strength+ # of the word "used".+ score = query_scorer(query, corpus)+ for entry in target_context.values():+ if not isinstance(entry, dict):+ continue++ # ``governing_decisions`` is exempt. An accepted decision binds this+ # file whatever the question was, so a reader asking anything about it+ # is owed the rules — suppressing one for sharing no vocabulary with the+ # question would hide a ruling from the person about to edit the file.+ # A candidate binds nothing, so it has to earn its place like any other+ # unranked text.+ rows = entry.get("candidate_decisions")+ if isinstance(rows, list) and rows:+ kept = [r for r in rows if clears_floor(score(json.dumps(r, default=str)))]+ if kept:+ entry["candidate_decisions"] = kept+ else:+ entry.pop("candidate_decisions", None)+ entry["candidate_decisions_omitted"] = recovery_note(+ len(rows), recall+ )++ # Only the origin story's decision lane, not the story. Reducing the+ # whole block was tried and was the wrong cut: it saved ~700 of the+ # 13,397 chars at issue while costing ``primary_author`` and the first+ # commit — facts a reader wants whatever they asked, and cheap. The+ # lane inside it is the query-blind part, because it is decisions again.+ origin = entry.get("origin")+ if isinstance(origin, dict):+ linked = origin.get("linked_decisions")+ if isinstance(linked, list) and linked:+ kept = [+ d for d in linked if clears_floor(score(json.dumps(d, default=str)))+ ]+ if kept:+ origin["linked_decisions"] = kept+ else:+ origin.pop("linked_decisions", None)+ origin["linked_decisions_omitted"] = recovery_note(+ len(linked), recall+ )++ arch = entry.get("git_archaeology")+ if isinstance(arch, dict):+ _focus_archaeology(arch, score, recall)+++def _focus_archaeology(+ arch: dict[str, Any], score: Any, recall: str+) -> None:+ """Keep the commits that carry the question's terms, count the rest.++ Filtered rather than dropped, unlike the decision lanes. A commit message is+ prose somebody wrote about this file, so "which of these commits mention+ what I asked about" is a question it can actually answer — and on the branch+ this block is reached from, no decision cleared the floor, which makes these+ commits the best evidence left.+ """+ for lane in ("file_commits", "cross_references", "git_log"):+ rows = arch.get(lane)+ if not isinstance(rows, list) or not rows:+ continue+ kept = [r for r in rows if clears_floor(score(json.dumps(r, default=str)))]+ if kept:+ arch[lane] = kept+ else:+ arch.pop(lane, None)+ arch[f"{lane}_omitted"] = recovery_note(len(rows), recall)++def _cap_target_context(target_context: dict[str, Any], collector: OmissionCollector) -> None:"""Cap evidence-enriched per-target decision lanes independently."""for target, entry in target_context.items():- decisions = entry.get("governing_decisions")- if isinstance(decisions, list):- cap_collection(- entry,- "governing_decisions",- decisions,- _MAX_PATH_DECISIONS,- collector,- label=(- f"{target} :: governing_decisions beyond cap={_MAX_PATH_DECISIONS}"- ),- )+ for lane in ("governing_decisions", "candidate_decisions"):+ decisions = entry.get(lane)+ if isinstance(decisions, list):+ cap_collection(+ entry,+ lane,+ decisions,+ _MAX_PATH_DECISIONS,+ collector,+ label=f"{target} :: {lane} beyond cap={_MAX_PATH_DECISIONS}",+ )async def _why_no_match(@@ -1565,6 +1754,7 @@ async def _why_no_match(repository: Any,all_decisions: list,target_git: dict[str, Any],+ accepted: set[str] | None = None,) -> dict[str, Any]:"""The whole response when no record clears the relevance floor.@@ -1595,7 +1785,7 @@ async def _why_no_match(if targets:collector = OmissionCollector("get_why", repo_root=ctx.path)result["target_context"] = await _build_target_context(- ctx, repository, all_decisions, target_git, targets, collector+ ctx, repository, all_decisions, target_git, targets, collector, accepted)rationale = _mine_rationale(ctx.path, targets, query, max_results=1000, truncate_blocks=False@@ -1607,8 +1797,35 @@ async def _why_no_match(result, ctx.alias, all_decisions, repo_root=ctx.path)if collector is not None:+ _focus_target_context(+ result["target_context"],+ query,+ list(targets or []),+ [_record_text(d) for d in all_decisions],+ )_cap_supporting_lanes(result, collector, label=query)_cap_target_context(result["target_context"], collector)+ # The redirect is stapled on before the target lanes are built, because+ # without targets there is nothing else this branch can serve. With them+ # there often is, and pointing away from an answer it is holding is the+ # padding-by-another-name the redirect exists to prevent.+ served = [+ label+ for key, label in (+ ("code_rationale", "rationale comments"),+ ("git_archaeology", "commit history"),+ )+ if result.get(key)+ or any(+ isinstance(e, dict) and _has_archaeology(e.get(key))+ for e in (result.get("target_context") or {}).values()+ )+ ]+ if served:+ result.pop("try_instead", None)+ result.update(+ redirect_when_served(served, f"get_why(targets={json.dumps(targets)})")+ )result["_meta"] = _build_meta(repository=repository, targets=targets if targets else None)if collector is not None:collector.attach(result)@@ -1696,7 +1913,7 @@ async def _hydrate_response_decision_evidence(async def _load_corpus(repo: str | None, targets: list[str] | None) -> tuple:- """Repo context, the rankable decision corpus, and git metadata for targets.+ """Repo context, corpus, git metadata for targets, and the acceptance set.The prologue both target-aware modes open with. Shared so the corpus isfiltered once: a record anchored entirely in excluded paths is noise for@@ -1707,9 +1924,14 @@ async def _load_corpus(repo: str | None, targets: list[str] | None) -> tuple:async with get_session(ctx.session_factory) as session:repository = await _get_repo(session)all_decisions = await _decision_corpus(session, repository.id, _get_exclude_spec(ctx.path))+ # ``governing_only`` drops the ones whose authority was withdrawn, so+ # what comes back is what still binds rather than what was ever signed.+ accepted = await accepted_decision_ids(+ session, repository.id, governing_only=True+ )# Load git metadata for targets (for origin context in results)target_git = await _load_target_git(session, repository.id, targets)- return ctx, repository, all_decisions, target_git+ return ctx, repository, all_decisions, target_git, acceptedasync def _why_targets(targets: list[str], repo: str | None) -> dict:@@ -1725,13 +1947,15 @@ async def _why_targets(targets: list[str], repo: str | None) -> dict:if len(targets) == 1:return await _why_path(targets[0], repo)- ctx, repository, all_decisions, target_git = await _load_corpus(repo, targets)+ ctx, repository, all_decisions, target_git, accepted = await _load_corpus(+ repo, targets+ )collector = OmissionCollector("get_why", repo_root=ctx.path)result_data = {"mode": "path","paths": targets,"target_context": await _build_target_context(- ctx, repository, all_decisions, target_git, targets, collector+ ctx, repository, all_decisions, target_git, targets, collector, accepted),"_meta": _build_meta(repository=repository, targets=targets),}@@ -1747,14 +1971,18 @@ async def _why_targets(targets: list[str], repo: str | None) -> dict:async def _why_search(query: str, targets: list[str] | None, repo: str | None) -> dict:"""Mode 3: natural-language, target-aware decision + documentation search."""- ctx, repository, all_decisions, target_git = await _load_corpus(repo, targets)+ ctx, repository, all_decisions, target_git, accepted = await _load_corpus(+ repo, targets+ )target_set = set(targets) if targets else set()# Rank wide, collapse restatements, then cap — so the cap spends its slots on# distinct decisions — and only walk lineage for what survives.ranked = _rank_keyword_matches(all_decisions, query, target_set)if not ranked:- return await _why_no_match(query, targets, ctx, repository, all_decisions, target_git)+ return await _why_no_match(+ query, targets, ctx, repository, all_decisions, target_git, accepted+ )collector = OmissionCollector("get_why", repo_root=ctx.path)collapsed = _collapse_restatements(ranked)decision_results, doc_results = await _semantic_lanes(ctx, query)@@ -1762,7 +1990,7 @@ async def _why_search(query: str, targets: list[str] | None, repo: str | None) -ctx, [d for d, _ in collapsed], all_decisions)merged_decisions = _merge_decisions(- collapsed, decision_results, lineage_by_id, collector+ collapsed, decision_results, lineage_by_id, collector, accepted)# No further slice: the cap is on *bodies*, applied to ``collapsed`` above.@@ -1788,7 +2016,7 @@ async def _why_search(query: str, targets: list[str] | None, repo: str | None) -# If targets provided, include target contextif targets:result_data["target_context"] = await _build_target_context(- ctx, repository, all_decisions, target_git, targets, collector+ ctx, repository, all_decisions, target_git, targets, collector, accepted)# The comment-mining fallback that used to sit here was gated on# ``not merged_decisions``, which nothing ever reached. It now lives in@@ -1804,6 +2032,22 @@ async def _why_search(query: str, targets: list[str] | None, repo: str | None) -query=None if targets else query,full_population=episode_population,)+ if episodes and targets:+ # ``episode_evidence`` takes *either* a scope or a query, and a scope+ # wins, so the targeted lane never saw the question: the same three+ # episodes came back for every question asked about a file. Scoping is+ # still the right retrieval — these are the episodes bound to the file+ # asked about — but what survives has to bear on what was asked.+ score = query_scorer(query, [_record_text(d) for d in all_decisions])+ kept = [+ e+ for e in episode_population+ if clears_floor(score(json.dumps(e, default=str)))+ ]+ if len(kept) != len(episode_population):+ episodes = [e for e in episodes if e in kept]+ episode_population[:] = kept+ pending = [t for t in pending if t[0] in kept]if episodes:collector = _prepare_episode_bodies(episode_population, len(episodes), pending, collector, ctx.path@@ -1815,6 +2059,12 @@ async def _why_search(query: str, targets: list[str] | None, repo: str | None) -result_data, ctx.alias, all_decisions, repo_root=ctx.path)if targets:+ _focus_target_context(+ result_data["target_context"],+ query,+ list(targets),+ [_record_text(d) for d in all_decisions],+ )_cap_supporting_lanes(result_data, collector, label=query)_cap_target_context(result_data["target_context"], collector)else:@@ -1863,8 +2113,8 @@ def _weighted_fields(d: Any) -> list[tuple[float, str]]:occur somewhere in 83 paths, and it became the top hit for three of fiveprobe questions including one about ruff. A scope is not question text.The legitimate use of that field — does this record govern the file the- caller named — is the exact set membership in :func:`_governs_any` and in- the target boost inside :func:`_score_decision`.+ caller named — is the exact set membership in the target boost inside+ :func:`_score_decision`."""return [(3.0, d.title.lower()),diff --git a/tests/unit/server/mcp/test_recoverable_caps_wire_contracts.py b/tests/unit/server/mcp/test_recoverable_caps_wire_contracts.pyindex 667e9a3ba..e10e97f61 100644--- a/tests/unit/server/mcp/test_recoverable_caps_wire_contracts.py+++ b/tests/unit/server/mcp/test_recoverable_caps_wire_contracts.py@@ -635,11 +635,19 @@ async def test_why_real_adversarial_wire_recovers_decisions_docs_and_episodes(population: list[dict[str, Any]] = []pending: list[tuple[dict[str, Any], str, str]] = []for i in range(8):- body = f"EPISODE_SENTINEL_{i}_START_" + "e" * 1100 + f"_END_{i}"+ # Bodies carry the question's terms. Search mode ranks a+ # target-scoped episode against the query now, so filler would be+ # dropped as irrelevant before it ever reached the cap this test is+ # about — and then there would be nothing capped to recover.+ body = (+ f"EPISODE_SENTINEL_{i}_START_ why use sealed response contract "+ + "e" * 1100+ + f"_END_{i}"+ )entry = {"tier": "git","kind": "sealed",- "subject": f"Episode {i}",+ "subject": f"Episode {i} sealed response contract","recorded": body[:900],"evidence": {"commit": f"{i:040x}"},"scope": ["src/auth/service.py"],@@ -666,7 +674,9 @@ async def test_why_real_adversarial_wire_recovers_decisions_docs_and_episodes(assert result["related_documentation_total"] == 8assert result["episodes_total"] == 8context = result["target_context"]["src/auth/service.py"]- assert context["governing_decisions_total"] >= 9+ # Nobody accepted the seeded records, so the card's populated lane is the+ # candidate one and the rules lane is empty.+ assert context["candidate_decisions_total"] >= 9recovered = await _recover_one(result,@@ -783,8 +793,10 @@ async def test_why_health_and_targets_only_modes_are_bounded_and_recoverable()_assert_wire(targets_only, "mode", DEFAULT_RESPONSE_CHARS)context = targets_only["target_context"]["src/auth/service.py"]- assert context["governing_decisions_total"] >= 9- assert context["governing_decisions_emitted"] == 8+ # Nobody accepted the seeded records, so the card's populated lane is the+ # candidate one and the rules lane is empty.+ assert context["candidate_decisions_total"] >= 9+ assert context["candidate_decisions_emitted"] == 8recovered = await _recover_one(targets_only, "sealed-why-8")assert "sealed-why-8" in recoveredassert '"evidence_refs"' in recovereddiff --git a/tests/unit/server/mcp/test_why.py b/tests/unit/server/mcp/test_why.pyindex 782195361..beeff0979 100644--- a/tests/unit/server/mcp/test_why.py+++ b/tests/unit/server/mcp/test_why.py@@ -75,9 +75,10 @@ async def test_get_why_file_path_commit_decision_linkage(setup_mcp):async def test_get_why_natural_language_with_targets(setup_mcp):from repowise.server.mcp_server import get_why- # Search with targets — decisions governing service.py should be boosted+ # Search with targets — a record governing service.py and carrying the+ # question's words is boosted above one that only carries the words.result = await get_why(- "authentication approach",+ "why is JWT used for authentication",targets=["src/auth/service.py"],)assert result["mode"] == "search"@@ -86,9 +87,13 @@ async def test_get_why_natural_language_with_targets(setup_mcp):# target_context should be presentassert "target_context" in resultctx = result["target_context"]["src/auth/service.py"]- assert len(ctx["governing_decisions"]) >= 1assert ctx["origin"]["available"] is Trueassert ctx["origin"]["primary_author"] == "Alice"+ # Nobody has accepted the fixture's records, so they are candidates and the+ # rules lane is empty. Claiming otherwise is what this split exists to stop.+ assert ctx["governing_decisions"] == []+ assert ctx["candidate_decisions"]+ assert result["answer_basis"] != "decision"@pytest.mark.asynciodiff --git a/tests/unit/server/mcp/test_why_evidence_contract.py b/tests/unit/server/mcp/test_why_evidence_contract.pyindex d595b5809..4a28f0030 100644--- a/tests/unit/server/mcp/test_why_evidence_contract.py+++ b/tests/unit/server/mcp/test_why_evidence_contract.py@@ -28,6 +28,14 @@ def _row_by_id(result: dict, decision_id: str) -> dict:for row in result.get(lane) or []:if row["id"] == decision_id:return row+ # Search mode splits a target's card the same way path mode splits the+ # response, and a record that misses the question's vocabulary is reachable+ # only there.+ for entry in (result.get("target_context") or {}).values():+ for lane in ("governing_decisions", "candidate_decisions"):+ for row in entry.get(lane) or []:+ if row["id"] == decision_id:+ return rowraise AssertionError(f"{decision_id} is in no lane of {sorted(result)}")@@ -449,17 +457,30 @@ def test_evidence_ids_are_order_independent_and_repository_scoped(def test_target_governing_record_ranks_before_unrelated_standing_decision(sealed_evidence_fixture,) -> None:+ """Naming a target breaks a tie. It no longer creates one.++ Both records carry the whole of this question's vocabulary, so relevance+ scores them identically and the target boost in ``_score_decision`` is the+ only thing left to separate them — which is the rule this pins.++ The question used to be "why is the cache guidance bounded", which+ ``standing`` carries two thirds of and ``governing`` one sixth. ``governing``+ won it anyway, because governing a named target was a floor bypass worth a+ flat 1.0. That bypass is gone, so the question had to become one both+ records actually answer.+ """records, _ = sealed_evidence_fixtureby_id = {record.id: record for record in records}ranked = _rank_keyword_matches([by_id["standing"], by_id["governing"]],- "why is the cache guidance bounded",+ "why the cache",{"src/cache.py"},)assert ranked[0].id == "governing"+@pytest.mark.asyncioasync def test_every_single_repository_query_mode_keeps_the_exact_public_reference(setup_mcp,@@ -478,8 +499,11 @@ async def test_every_single_repository_query_mode_keeps_the_exact_public_referen}calls = [await get_why("why is JWT used for authentication"),+ # Anchored to a target *and* carrying the record's vocabulary. A+ # target-anchored question the record does not answer is withheld now,+ # and a row that is not emitted has no public reference to hold.await get_why(- "authentication approach",+ "why is JWT used for authentication",targets=["src/auth/service.py"],),await get_why("src/auth/service.py"),@@ -496,13 +520,16 @@ async def test_every_single_repository_query_mode_keeps_the_exact_public_referentargets=["src/auth/service.py", "src/auth/middleware.py"])target_decision = multi_target["target_context"]["src/auth/service.py"][- "governing_decisions"+ "candidate_decisions"][0]assert target_decision == {"id": "dec1","title": "Use JWT for authentication","status": "proposed","source": "readme_mining",+ # The lane already says it, and the row says it again: no acceptance+ # binds this record, so it is not a rule about this file.+ "authority": "candidate","provenance": "historical","evidence_refs": [expected],}diff --git a/tests/unit/server/mcp/test_why_relevance_floor.py b/tests/unit/server/mcp/test_why_relevance_floor.pyindex bb5a6c100..cbeb8472d 100644--- a/tests/unit/server/mcp/test_why_relevance_floor.py+++ b/tests/unit/server/mcp/test_why_relevance_floor.py@@ -281,14 +281,21 @@ async def test_the_redirect_names_a_tool_that_fits_the_question(@pytest.mark.asyncio-async def test_a_record_governing_a_named_target_is_served_without_matching_words(+async def test_an_unaccepted_record_naming_a_target_is_not_an_answer(session, setup_mcp):- """Naming a file is a stronger handle than describing it.-- A caller who passes ``targets`` has pointed at the thing, so a record- governing it owes the question no vocabulary and must not be refused for- sharing none.+ """Naming a file is a handle on the file, not an answer to the question.++ This pinned the opposite until the floor bypass was measured: a record+ governing a named target scored 1.0 outright and entered the ranked lane+ owing the question no vocabulary. On the real store that served "Move risk+ scale reference metadata behind opt-in inclusion" as the answer to "why does+ changed_lines() drop deletion-only files", whose whole claim to the question+ was sharing a directory with it.++ Nothing is lost, which is the other half of the contract: the record is+ still reachable through the target's own card, as a candidate, with the call+ that recovers it in full."""await _seed(session,@@ -306,7 +313,14 @@ async def test_a_record_governing_a_named_target_is_served_without_matching_wordtargets=["src/app/handler.py"],)- assert "governs" in [d["id"] for d in result["decisions"]]+ assert "governs" not in [d["id"] for d in result["decisions"]]+ assert result.get("answer_basis") != "decision"+ context = result["target_context"]["src/app/handler.py"]+ assert not context["governing_decisions"]+ reachable = [d["id"] for d in context.get("candidate_decisions") or []]+ assert "governs" in reachable or "recover_with" in (+ context.get("candidate_decisions_omitted") or {}+ )async def get_why_search(query: str, targets: list[str] | None = None) -> dict: