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.

feat(decisions): promote a candidate that states a reason, not one seen twice (#2426)

Raghav Chamadiya876cad6063bb
diff --git a/packages/core/src/repowise/core/generation/onboarding/subkinds/key_concepts.py b/packages/core/src/repowise/core/generation/onboarding/subkinds/key_concepts.py
index a93b82cfe..3abd9af09 100644
--- a/packages/core/src/repowise/core/generation/onboarding/subkinds/key_concepts.py
+++ b/packages/core/src/repowise/core/generation/onboarding/subkinds/key_concepts.py
@@ -29,6 +29,7 @@ import structlog
from ....ingestion.models import SYMBOL_USE_EDGE_TYPES
from ...entry_points import orientation_entry_points
+from ...page_generator.helpers import rank_decisions
from ..registry import SubkindSpec, register
from ..signals import OnboardingSignals, file_layer_map
from ..slots import SLOT_KEY_CONCEPTS, SLOT_TITLES
@@ -631,7 +632,7 @@ def _build(signals: OnboardingSignals) -> KeyConceptsContext | None:
community_labels = sorted(set(labels_by_cid.values()))[:_MAX_COMMUNITY_LABELS]
decision_titles = [
str(d.get("title", "")).strip()
- for d in signals.decisions_all[:_MAX_DECISION_RECORDS]
+ for d in rank_decisions(signals.decisions_all)[:_MAX_DECISION_RECORDS]
if d.get("title")
]
diff --git a/packages/core/src/repowise/core/generation/page_generator/helpers.py b/packages/core/src/repowise/core/generation/page_generator/helpers.py
index 0c1aa0836..90597a1df 100644
--- a/packages/core/src/repowise/core/generation/page_generator/helpers.py
+++ b/packages/core/src/repowise/core/generation/page_generator/helpers.py
@@ -252,15 +252,27 @@ def _decision_confidence(payload: dict) -> float:
return 0.0
-def rank_decisions(decisions: Iterable[dict]) -> list[dict]:
- """Most confident first, ties in discovery order (the sort is stable).
+def _is_governing(payload: dict) -> bool:
+ """Whether a person accepted this decision. ``active`` is that projection."""
+ return str(payload.get("status") or "") == "active"
+
- A page has room for a handful, so which handful matters -- the list is both
- rendered and fed to the model as context. Taking a raw slice showed whichever
- happened to be written first.
+def rank_decisions(decisions: Iterable[dict]) -> list[dict]:
+ """Accepted first, then most confident, ties in discovery order.
+
+ A page has room for a handful, so which handful matters -- the list is
+ both rendered and fed to the model as context. Taking a raw slice showed
+ whichever happened to be written first.
+
+ Authority leads confidence because the two measure different things. A
+ confidence score says how well a candidate is grounded in what it was
+ mined from; an acceptance says a person read it and agreed it binds. A
+ page with room for three should spend them on the rules before the
+ proposals, and the promotion bar admits several times as many proposals
+ as it used to, which is what would otherwise crowd them out.
"""
ranked = list(decisions)
- ranked.sort(key=lambda payload: -_decision_confidence(payload))
+ ranked.sort(key=lambda payload: (not _is_governing(payload), -_decision_confidence(payload)))
return ranked
@@ -288,11 +300,27 @@ def decisions_for_files(
def build_decision_maps(
decision_report: Any | None,
) -> tuple[dict[str, list[dict]], list[dict]]:
- """Index decision records by file path and as a flat list."""
+ """Index decision records by file path and as a flat list.
+
+ Every page's decisions section is built from these two, and until now they
+ carried no authority at all: a proposal nobody had read was indexed beside
+ a rule somebody accepted, and a dismissed record beside both. The status
+ rides along so :func:`rank_decisions` can lead with what governs.
+ """
decisions_by_file: dict[str, list[dict]] = {}
decisions_all: list[dict] = []
if decision_report is not None and getattr(decision_report, "decisions", None):
for d in decision_report.decisions:
+ status = str(getattr(d, "status", "") or "proposed")
+ # A tombstone is the one thing that must not reach a page. It is
+ # what stops re-extraction re-proposing something already
+ # rejected, and publishing it as a decision says the opposite of
+ # what the dismissal meant. Everything else is carried, with its
+ # status, rather than filtered: this store holds no acceptances at
+ # all, so an accepted-only filter empties the decisions section of
+ # every page rather than making it more honest.
+ if status == "dismissed":
+ continue
payload = {
"title": d.title,
"decision": d.decision,
@@ -300,6 +328,7 @@ def build_decision_maps(
"source": d.source,
"confidence": d.confidence,
"evidence_file": d.evidence_file,
+ "status": status,
}
decisions_all.append(payload)
for fp in d.affected_files or []:
diff --git a/packages/core/src/repowise/core/pipeline/resume/rehydrate.py b/packages/core/src/repowise/core/pipeline/resume/rehydrate.py
index cd3194873..2ce8c7fed 100644
--- a/packages/core/src/repowise/core/pipeline/resume/rehydrate.py
+++ b/packages/core/src/repowise/core/pipeline/resume/rehydrate.py
@@ -129,6 +129,10 @@ async def rehydrate_decision_report(session: Any, repo_id: str) -> Any:
confidence=r.confidence,
evidence_file=r.evidence_file,
affected_files=affected,
+ # Carried so the resumed run ranks and filters decisions the
+ # same way a fresh one does. Without it every rehydrated
+ # record read as a proposal, including the accepted ones.
+ status=r.status,
)
)
return SimpleNamespace(decisions=decisions)
diff --git a/packages/core/src/repowise/core/sessions/staging.py b/packages/core/src/repowise/core/sessions/staging.py
index 5b249c644..80921dee7 100644
--- a/packages/core/src/repowise/core/sessions/staging.py
+++ b/packages/core/src/repowise/core/sessions/staging.py
@@ -507,12 +507,35 @@ class SessionStagingStore:
def promotable(self) -> list[dict[str, Any]]:
"""Decisions that qualify for (re-)emission into decision_records.
- Qualifies when 2+ distinct sessions observed it, or on a single
- observation for a user correction (the fast path). Emits only when
- there is something new to say: never promoted before, or observed by
- more sessions than the last emission. A promoted decision is therefore not
- re-upserted (and can never resurrect a human status change) on every
- update.
+ Qualifies on a stated reason: the row carries a non-empty rationale.
+ That is the whole bar, and it replaces "two sessions saw it, or it was
+ a user correction". The recurrence half of that had never fired. The
+ observation distribution over the dogfood store is ``{1: 406}`` -- no
+ staged row has ever been seen twice -- so ``user_correction`` was the
+ entire promotion path and recurrence was rejecting 256 rows on a
+ condition nothing could satisfy. Waiting for a second sighting is not
+ a quality bar when a second sighting never comes.
+
+ A rationale is a bar that measures the record rather than the corpus:
+ it is the difference between a choice somebody explained and a
+ sentence that merely sounded like one, and it admits 224 of 406.
+
+ The bar gates the *first* promotion only. It is not a superset of the
+ old one: 124 of the 150 rows the old bar promoted are corrections
+ carrying no rationale, and they are already in the store. Applying the
+ bar to re-emission would not withdraw any of them, it would only stop
+ them accreting the evidence of a later sighting, which is information
+ about a record that exists either way. A bar admits a record; it does
+ not retract one already admitted.
+
+ Safe to widen only because promoted records land in the labelled
+ ``candidates`` lane under its own cap rather than as rules an agent
+ follows. Nothing here creates authority; a person still accepts.
+
+ Emits only when there is something new to say: never promoted before,
+ or observed by more sessions than the last emission. A promoted
+ decision is therefore not re-upserted (and can never resurrect a human
+ status change) on every update.
"""
rows = self._conn.execute(
"SELECT key, kind, title, structured, sessions, quotes, files, "
@@ -522,10 +545,10 @@ class SessionStagingStore:
for r in rows:
sessions = json.loads(r[4])
observations = max(1, len(sessions))
- qualifies = observations >= 2 or r[1] == "user_correction"
- if not qualifies:
- continue
+ structured = json.loads(r[3])
first_promotion = r[7] is None
+ if first_promotion and not str(structured.get("rationale") or "").strip():
+ continue
if not first_promotion and observations <= r[8]:
continue
out.append(
@@ -533,7 +556,7 @@ class SessionStagingStore:
"key": r[0],
"kind": r[1],
"title": r[2],
- "structured": json.loads(r[3]),
+ "structured": structured,
"sessions": sessions,
"quotes": json.loads(r[5]),
"files": json.loads(r[6]),
diff --git a/tests/unit/analysis/test_decision_discovery.py b/tests/unit/analysis/test_decision_discovery.py
index 0eb9ad503..4717887eb 100644
--- a/tests/unit/analysis/test_decision_discovery.py
+++ b/tests/unit/analysis/test_decision_discovery.py
@@ -344,6 +344,9 @@ async def test_grounded_candidates_persist_and_rerunning_is_idempotent(tmp_path)
)
assert first.report.candidates_grounded == 1
assert first.report.candidates_new == 1
+ # Promoted on this sighting: the bar is a stated reason, and a grounded
+ # discovery candidate carries one. It used to take a second session.
+ assert len(first.decisions) == 1
# Spans are spent once read, so a second update has nothing left to send.
second = await run_update_discovery(
tmp_path, provider=provider, policy=preset_policy("balanced"), now=300.0
@@ -354,11 +357,20 @@ async def test_grounded_candidates_persist_and_rerunning_is_idempotent(tmp_path)
with SessionStagingStore.open_default(tmp_path) as store:
assert store.pending_raws(10) == [] # never fed to the deterministic lane
rows = store.promotable()
- assert rows == [] # one observation is not enough to propose anything
+ # Already emitted on the first run, and no new session has observed it, so
+ # there is nothing new to say. This is re-emission being idempotent, not
+ # the promotion bar holding it back.
+ assert rows == []
@pytest.mark.asyncio
-async def test_a_second_session_promotes_the_candidate_as_proposed(tmp_path):
+async def test_a_second_session_re_emits_the_candidate_with_its_evidence(tmp_path):
+ """A second sighting is accretion, not admission.
+
+ It was admission until the promotion bar became a stated reason: the
+ candidate is already proposed after the first session, and what the second
+ adds is another evidence row on the record it already has.
+ """
provider = FakeProvider(json.dumps(_payload(_candidate())))
_queue(tmp_path, [_span(1, "s1")], now=100.0)
await run_update_discovery(
@@ -389,7 +401,12 @@ async def test_discovery_never_promotes_the_deterministic_lanes_backlog(tmp_path
"det1",
kind="user_correction",
title="A deterministic gate hit",
- structured={"decision": "Do the thing", "verification": "exact"},
+ structured={
+ "decision": "Do the thing",
+ # Promotion needs a stated reason; this test is about lanes.
+ "rationale": "because the alternative was measured slower",
+ "verification": "exact",
+ },
quotes=[QUOTE],
files=["packages/core/a.py"],
session_id="s9",
@@ -503,7 +520,11 @@ def test_discovery_and_deterministic_titles_never_share_a_staging_row(tmp_path):
"det1",
kind="user_correction",
title="Never run ruff format",
- structured={"decision": "the deterministic text", "verification": "exact"},
+ structured={
+ "decision": "the deterministic text",
+ "rationale": "because the alternative was measured slower",
+ "verification": "exact",
+ },
quotes=[QUOTE],
files=[],
session_id="s9",
@@ -517,7 +538,11 @@ def test_discovery_and_deterministic_titles_never_share_a_staging_row(tmp_path):
"dis1",
kind=DISCOVERY_KIND,
title="Never run ruff format",
- structured={"decision": "the discovery text", "verification": "exact"},
+ structured={
+ "decision": "the discovery text",
+ "rationale": "because the alternative was measured slower",
+ "verification": "exact",
+ },
quotes=[QUOTE],
files=[],
session_id="s8",
@@ -529,7 +554,11 @@ def test_discovery_and_deterministic_titles_never_share_a_staging_row(tmp_path):
rows = {row["key"]: row for row in store.promotable()}
assert rows[det_key]["kind"] == "user_correction"
assert rows[det_key]["structured"]["decision"] == "the deterministic text"
- assert dis_key not in rows # one discovery observation does not promote
+ # The other lane kept its own row, its own kind and its own text rather
+ # than overwriting this one. Which lane may emit it is decided by the
+ # caller, on the kind, not by holding it out of this list.
+ assert rows[dis_key]["kind"] == DISCOVERY_KIND
+ assert rows[dis_key]["structured"]["decision"] == "the discovery text"
def test_pending_spans_are_never_pruned_before_they_are_read(tmp_path):
diff --git a/tests/unit/generation/test_decision_scoping.py b/tests/unit/generation/test_decision_scoping.py
index 98f1db5aa..e4e62bc4a 100644
--- a/tests/unit/generation/test_decision_scoping.py
+++ b/tests/unit/generation/test_decision_scoping.py
@@ -10,8 +10,10 @@ from __future__ import annotations
import re
from pathlib import Path
+from types import SimpleNamespace
from repowise.core.generation.page_generator.helpers import (
+ build_decision_maps,
decisions_for_files,
rank_decisions,
)
@@ -28,6 +30,19 @@ def _decision(title: str, *, confidence: float | None = 1.0, evidence: str = "e.
return payload
+def _record(title: str, *, status: str = "proposed", confidence: float = 0.5) -> SimpleNamespace:
+ return SimpleNamespace(
+ title=title,
+ decision=f"{title}: do the thing",
+ rationale="because the alternative was measured slower",
+ source="session",
+ confidence=confidence,
+ evidence_file="e.py",
+ affected_files=["src/app.py"],
+ status=status,
+ )
+
+
def test_module_decisions_are_scoped_to_the_modules_files():
a1 = _decision("a1", confidence=0.4, evidence="a/x.py")
a2 = _decision("a2", confidence=0.9, evidence="a/y.py")
@@ -89,3 +104,70 @@ def test_no_page_type_slices_the_repo_wide_decision_list_unranked():
assert not offenders, "slice a ranked list, or scope it with decisions_for_files: " + "; ".join(
offenders
)
+
+
+# ---------------------------------------------------------------------------
+# Authority: a page has room for a handful, and a proposal is not a rule
+# ---------------------------------------------------------------------------
+
+
+def test_an_accepted_decision_outranks_a_more_confident_proposal():
+ """A confidence score and an acceptance measure different things.
+
+ Confidence says how well a candidate is grounded in what it was mined
+ from. An acceptance says a person read it and agreed it binds. The
+ promotion bar admits several times as many proposals as it used to, and
+ without this they crowd the rules off the page.
+ """
+ ranked = rank_decisions(
+ [
+ {"title": "proposal", "confidence": 0.99, "status": "proposed"},
+ {"title": "rule", "confidence": 0.10, "status": "active"},
+ ]
+ )
+ assert [d["title"] for d in ranked] == ["rule", "proposal"]
+
+
+def test_a_payload_with_no_status_still_ranks_by_confidence():
+ """Every pre-existing caller passed no status at all."""
+ ranked = rank_decisions(
+ [{"title": "low", "confidence": 0.1}, {"title": "high", "confidence": 0.9}]
+ )
+ assert [d["title"] for d in ranked] == ["high", "low"]
+
+
+def test_a_dismissed_record_never_reaches_a_page():
+ """A tombstone is what stops re-extraction re-proposing something.
+
+ Publishing it as a decision says the opposite of what the dismissal meant.
+ """
+ report = SimpleNamespace(
+ decisions=[
+ _record("Kept"),
+ _record("Rejected on review", status="dismissed"),
+ ]
+ )
+
+ by_file, all_decisions = build_decision_maps(report)
+
+ assert [d["title"] for d in all_decisions] == ["Kept"]
+ assert [d["title"] for d in by_file["src/app.py"]] == ["Kept"]
+
+
+def test_the_status_reaches_the_payload_so_ranking_can_read_it():
+ report = SimpleNamespace(decisions=[_record("A rule", status="active")])
+
+ _, all_decisions = build_decision_maps(report)
+
+ assert all_decisions[0]["status"] == "active"
+
+
+def test_a_record_that_carries_no_status_reads_as_a_proposal():
+ """Not as a rule: the absence of an acceptance is not an acceptance."""
+ record = _record("Unknown")
+ del record.status
+ report = SimpleNamespace(decisions=[record])
+
+ _, all_decisions = build_decision_maps(report)
+
+ assert all_decisions[0]["status"] == "proposed"
diff --git a/tests/unit/sessions/test_staging.py b/tests/unit/sessions/test_staging.py
index 7f31935ab..e3af39e30 100644
--- a/tests/unit/sessions/test_staging.py
+++ b/tests/unit/sessions/test_staging.py
@@ -83,7 +83,13 @@ def test_upsert_structured_merges_sessions_and_kind(store):
assert sorted(row["files"]) == ["a.py", "b.py"]
-def test_single_choice_observation_does_not_promote(store):
+def test_a_single_choice_promotes_when_it_states_a_reason(store):
+ """The recurrence bar rejected every one of these and never fired.
+
+ No staged row in the dogfood store has been observed twice, so waiting
+ for a second sighting rejected 256 rows on a condition nothing could
+ satisfy. A stated reason measures the record instead of the corpus.
+ """
_raw(store, hash_="r1")
store.upsert_structured(
"r1",
@@ -94,6 +100,87 @@ def test_single_choice_observation_does_not_promote(store):
files=[],
session_id="s1",
)
+ assert [row["key"] for row in store.promotable()] == [title_key(STRUCTURED["title"])]
+
+
+def test_a_choice_with_no_reason_does_not_promote(store):
+ _raw(store, hash_="r1")
+ store.upsert_structured(
+ "r1",
+ kind="explicit_choice",
+ title=STRUCTURED["title"],
+ structured={**STRUCTURED, "rationale": ""},
+ quotes=["q"],
+ files=[],
+ session_id="s1",
+ )
+ assert store.promotable() == []
+
+
+def test_a_reason_of_only_whitespace_is_no_reason(store):
+ _raw(store, hash_="r1")
+ store.upsert_structured(
+ "r1",
+ kind="explicit_choice",
+ title=STRUCTURED["title"],
+ structured={**STRUCTURED, "rationale": " \n "},
+ quotes=["q"],
+ files=[],
+ session_id="s1",
+ )
+ assert store.promotable() == []
+
+
+def test_a_row_already_promoted_keeps_accreting_without_a_reason(store):
+ """The bar admits a record; it does not retract one already admitted.
+
+ 124 of the 150 rows the old bar promoted are corrections carrying no
+ rationale. They are in the store either way, so refusing their later
+ evidence would only make an existing record worse informed.
+ """
+ _raw(store, hash_="r1", kind="user_correction")
+ key = store.upsert_structured(
+ "r1",
+ kind="user_correction",
+ title=STRUCTURED["title"],
+ structured={**STRUCTURED, "rationale": ""},
+ quotes=["q"],
+ files=[],
+ session_id="s1",
+ )
+ assert store.promotable() == []
+
+ # Promoted once, under whatever bar was in force at the time.
+ store.mark_emitted(key, observations=1, now=1.0)
+ store.upsert_structured(
+ "r1",
+ kind="user_correction",
+ title=STRUCTURED["title"],
+ structured={**STRUCTURED, "rationale": ""},
+ quotes=["q"],
+ files=[],
+ session_id="s2",
+ )
+
+ assert [row["key"] for row in store.promotable()] == [key]
+
+
+def test_a_correction_with_no_reason_does_not_promote_either(store):
+ """The bar is the record, not the lane that raised it.
+
+ ``user_correction`` used to be the entire promotion path, on the strength
+ of its kind alone. A correction nobody explained is still unexplained.
+ """
+ _raw(store, hash_="r1", kind="user_correction")
+ store.upsert_structured(
+ "r1",
+ kind="user_correction",
+ title=STRUCTURED["title"],
+ structured={**STRUCTURED, "rationale": None},
+ quotes=["q"],
+ files=[],
+ session_id="s1",
+ )
assert store.promotable() == []