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
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.pyindex 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 structlogfrom ....ingestion.models import SYMBOL_USE_EDGE_TYPESfrom ...entry_points import orientation_entry_points+from ...page_generator.helpers import rank_decisionsfrom ..registry import SubkindSpec, registerfrom ..signals import OnboardingSignals, file_layer_mapfrom ..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.pyindex 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":+ continuepayload = {"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.pyindex 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.pyindex 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():+ continueif not first_promotion and observations <= r[8]:continueout.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.pyindex 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 == 1assert 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 lanerows = 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.pyindex 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 annotationsimport refrom pathlib import Path+from types import SimpleNamespacefrom 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.pyindex 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() == []