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.

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.py
index 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 history
diff --git a/packages/server/src/repowise/server/mcp_server/_why_evidence.py b/packages/server/src/repowise/server/mcp_server/_why_evidence.py
index 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):
+ continue
candidates = records_by_title.get(str(row.get("title") or ""), [])
if len(candidates) == 1:
row["id"] = candidates[0].id
diff --git a/packages/server/src/repowise/server/mcp_server/_why_relevance.py b/packages/server/src/repowise/server/mcp_server/_why_relevance.py
index 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 annotations
import math
+from collections.abc import Callable
from typing import Any
from 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.py
index 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 select
from repowise.core.analysis.decision_semantic_match import DECISION_VECTOR_PREFIX
from repowise.core.analysis.decisions.lifecycle import is_governing, status_rank
from 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 no
decisions exist for a path — never empty. Evidence-bearing rows carry an
explicit ``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:
continue
entry["currency"] = currency
if 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):
continue
scored_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 search
all_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 governs
if 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 is
filtered 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, accepted
async 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 context
if 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 five
probe 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.py
index 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"] == 8
assert result["episodes_total"] == 8
context = 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"] >= 9
recovered = 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"] == 8
recovered = await _recover_one(targets_only, "sealed-why-8")
assert "sealed-why-8" in recovered
assert '"evidence_refs"' in recovered
diff --git a/tests/unit/server/mcp/test_why.py b/tests/unit/server/mcp/test_why.py
index 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 present
assert "target_context" in result
ctx = result["target_context"]["src/auth/service.py"]
- assert len(ctx["governing_decisions"]) >= 1
assert ctx["origin"]["available"] is True
assert 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.asyncio
diff --git a/tests/unit/server/mcp/test_why_evidence_contract.py b/tests/unit/server/mcp/test_why_evidence_contract.py
index 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 row
raise 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_fixture
by_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.asyncio
async 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_referen
targets=["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.py
index 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_word
targets=["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: