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(decisions): rank a person above a document, and retire two sources that never landed (#1290)

Raghav Chamadiya39d030e212b6
diff --git a/docs/layers/DECISIONS.md b/docs/layers/DECISIONS.md
index 5650fb342..c49b51dfc 100644
--- a/docs/layers/DECISIONS.md
+++ b/docs/layers/DECISIONS.md
@@ -56,8 +56,6 @@ it is the only one that needs a provider.
| Inline markers | `inline_marker` | `# WHY:` / `# DECISION:` / `# TRADEOFF:` / `# ADR:` / `# RATIONALE:` / `# REJECTED:` | Any comment syntax (`#`, `//`, `--`, `/*`, `*`). Up to 5 continuation lines, plus 20 lines of surrounding context. Fenced code blocks in Markdown are skipped. |
| Git archaeology | `git_archaeology` | Commit messages | Gated on 19 decision verbs (migrate, switch to, replace, adopt, deprecate, drop, rewrite, split, revert, and the rest). |
| PR bodies | `pr` | Squash-merge and PR commit bodies | A body only qualifies when it looks like a PR description (`## Why`, `## Motivation`, `## Context`, `Closes #`, `Before:` / `After:`). Up to 25 bodies. |
-| CHANGELOG | `changelog` | `CHANGELOG` / `HISTORY` / `NEWS` / `CHANGES` / release notes | keep-a-changelog `Changed` / `Removed` / `Deprecated` / `Security` sections only. `Added` is deliberately excluded: a new feature is rarely a structural decision. Up to 15 versions. |
-| README and docs | `readme_mining` | README and docs prose | Implicit decisions stated in prose. |
| Code comments | `comment` | Block comments and docstrings on high-centrality files | Bounded to 30 nodes, and to prose carrying a rationale cue ("because", "instead of", "rather than", "trade-off", "we chose", "deliberately"). Centrality-bounded on purpose: comment archaeology across a whole repo is noise. |
| Doc generation | `llm_inferred` | The wiki generation pass | The page generator proposes decisions it inferred while writing a page. Every field must survive the grounding gate below. |
@@ -74,9 +72,7 @@ decisions:
comment: false # skip comment archaeology
# inline_marker: false
# git_archaeology: false
- # readme_mining: false
# adr: false
- # changelog: false
# pr: false
```
@@ -112,9 +108,13 @@ confidence = 0.4 + 0.5 * (best_source_rank / 9)
x verification penalty
```
-The rank ladder is `cli` 9, `adr` 8, `session` and `pr` 7, `commit` and
-`git_archaeology` 6, `changelog` 5, `inline_marker` 4, `comment` and
-`readme_mining` 3, and the heuristic tiers below that. The result is clamped to
+The rank ladder is `cli` 9, `session` 8, `adr` and `pr` 7, `commit` and
+`git_archaeology` 6, `inline_marker` 4, `comment` 3, and the heuristic tiers
+below that. `session` sits above `adr` because a transcript carries what a person
+actually said while deciding, and a document is someone's later write-up of it;
+with the order reversed the write-up overwrote the words. Retired sources keep
+their rungs (`changelog` 5, `readme_mining` 3) so rows written before their
+removal still rank instead of dropping to the unknown-source floor. The result is clamped to
`[0, 0.99]`: nothing is ever certain.
**Sources corroborate, they do not overwrite.** The same decision found in an ADR
@@ -244,7 +244,7 @@ the primary repo. Decision ids accept an 8-character prefix.
| Flag | Values |
|------|--------|
| `--status` | `proposed`, `active`, `deprecated`, `superseded`, `dismissed`, `all` (default) |
-| `--source` | `git_archaeology`, `inline_marker`, `readme_mining`, `cli`, `all` (default) |
+| `--source` | any source in the rank ladder except the retired ones, plus `all` (default) |
| `--proposed` | Shortcut for `--status proposed` |
| `--stale-only` | Only records with staleness at or above 0.5 |
diff --git a/docs/reference/CLI_REFERENCE.md b/docs/reference/CLI_REFERENCE.md
index cd6c05c3a..08f67c4d5 100644
--- a/docs/reference/CLI_REFERENCE.md
+++ b/docs/reference/CLI_REFERENCE.md
@@ -641,7 +641,7 @@ repowise decision health [PATH] # health dashboard
| Flag | Description |
|------|-------------|
| `--status` | `active`, `proposed`, `deprecated`, `superseded`, `all` |
-| `--source` | `git_archaeology`, `inline_marker`, `readme_mining`, `cli`, `all` |
+| `--source` | `adr`, `cli`, `comment`, `commit`, `git_archaeology`, `inline_marker`, `llm_inferred`, `pr`, `session`, `all` |
| `--proposed` | Shortcut for `--status proposed` |
| `--stale-only` | Only stale decisions |
diff --git a/docs/reference/CONFIG.md b/docs/reference/CONFIG.md
index 201642d37..99ea36229 100644
--- a/docs/reference/CONFIG.md
+++ b/docs/reference/CONFIG.md
@@ -317,8 +317,7 @@ decisions:
comment: false # LLM comment archaeology (top central files)
# inline_marker: false # WHY:/DECISION: markers
# git_archaeology: false
- # readme_mining: false
- # adr: false
+ # adr: false
# changelog: false
# pr: false
```
diff --git a/packages/cli/src/repowise/cli/commands/decision_cmd.py b/packages/cli/src/repowise/cli/commands/decision_cmd.py
index ded20f933..248ac98d8 100644
--- a/packages/cli/src/repowise/cli/commands/decision_cmd.py
+++ b/packages/cli/src/repowise/cli/commands/decision_cmd.py
@@ -15,6 +15,13 @@ from repowise.cli.helpers import (
resolve_command_target,
run_async,
)
+from repowise.core.analysis.decisions.provenance import LISTABLE_SOURCES
+
+#: The ladder's real sources plus the no-filter sentinel. Derived, because the
+#: hand-written copy had drifted: it offered ``readme_mining`` (since retired)
+#: while omitting ``session``, the source carrying a user's own words and the
+#: one you would most want to filter for.
+_SOURCE_CHOICES: tuple[str, ...] = (*LISTABLE_SOURCES, "all")
def _resolve_decision_repo(path: str | None):
@@ -157,7 +164,7 @@ def decision_add(path: str | None) -> None:
)
@click.option(
"--source",
- type=click.Choice(["git_archaeology", "inline_marker", "readme_mining", "cli", "all"]),
+ type=click.Choice(_SOURCE_CHOICES),
default="all",
)
@click.option("--proposed", is_flag=True, default=False, help="Show only proposed decisions.")
diff --git a/packages/core/src/repowise/core/analysis/decisions/extractor.py b/packages/core/src/repowise/core/analysis/decisions/extractor.py
index 21030113c..af13ada80 100644
--- a/packages/core/src/repowise/core/analysis/decisions/extractor.py
+++ b/packages/core/src/repowise/core/analysis/decisions/extractor.py
@@ -3,21 +3,28 @@
Capture sources (see ``decision_provenance.SOURCE_RANK`` for the trust ladder):
1. Inline markers (# WHY:, # DECISION:, etc.)
2. Git archaeology (significant commit messages)
- 3. README / docs mining (implicit decisions in prose)
- 4. ADR auto-discovery (Nygard/MADR records — deterministic parse first)
- 5. CHANGELOG mining (keep-a-changelog Changed/Removed/Deprecated)
- 6. PR / squash-body mining (commit bodies captured in git indexing)
- 7. Comment archaeology (LLM rationale prose on high-centrality code)
+ 3. ADR auto-discovery (Nygard/MADR records — deterministic parse first)
+ 4. PR / squash-body mining (commit bodies captured in git indexing)
+ 5. Comment archaeology (LLM rationale prose on high-centrality code)
+ CLI capture (manual entry)
Sources can be disabled per-repo via ``decisions.sources`` in
``.repowise/config.yaml`` (see :data:`SOURCE_NAMES` /
-:meth:`DecisionExtractor.extract_all`). The former Source 8 (repo-wide
-deterministic rationale-comment harvest, ``code_comment``) was removed: the
-query-time live-grep miner (``mcp_server/_code_rationale.py``) serves the same
-comments fresh, so persisting them only flooded the proposed queue (#751).
-
-Determinism-first: ADR/CHANGELOG are parsed structurally before any LLM call.
+:meth:`DecisionExtractor.extract_all`).
+
+Three sources have been retired, all for the same reason: they mined prose that
+describes a repo rather than evidence of a choice made in it, and the records
+they produced were never acted on. ``code_comment`` went first (#751) — the
+query-time live-grep miner serves the same comments fresh, so persisting them
+only flooded the proposed queue. ``readme_mining`` and ``changelog`` follow:
+between them they produced 153 records in this project's own store and **zero**
+that ever became active, while accounting for most of a 214-deep review queue.
+Retired source names are kept in ``SOURCE_RANK`` so rows written before the
+removal still rank, and :data:`RETIRED_SOURCES` drives the one-shot purge on the
+persist path. The ADR miner still borrows ``README_MINING_PROMPT`` for its
+unstructured-file fallback; that is the prompt, not the source.
+
+Determinism-first: ADRs are parsed structurally before any LLM call.
Every extracted decision passes an anti-hallucination substring gate
(:meth:`DecisionExtractor._apply_substring_gate`) — fields not grounded in the
verbatim source span are dropped, and evidence-less decisions are rejected.
@@ -43,7 +50,6 @@ from repowise.core.analysis.decisions.gate import apply_substring_gate
from .prompts import (
_SYSTEM_PROMPT,
- CHANGELOG_MINING_PROMPT,
COMMENT_ARCHAEOLOGY_PROMPT,
GIT_ARCHAEOLOGY_PROMPT,
INLINE_MARKER_PROMPT,
@@ -128,9 +134,7 @@ class DecisionExtractionReport:
SOURCE_NAMES: tuple[str, ...] = (
"inline_marker",
"git_archaeology",
- "readme_mining",
"adr",
- "changelog",
"pr",
"comment",
)
@@ -251,7 +255,7 @@ DECISION_SIGNAL_KEYWORDS = [
]
# ---------------------------------------------------------------------------
-# ADR / CHANGELOG / PR / comment source configuration (Phase 1B)
+# ADR / PR / comment source configuration
# ---------------------------------------------------------------------------
# Directories conventionally holding Architecture Decision Records, plus a
@@ -283,14 +287,6 @@ _ADR_STATUS_MAP = {
"superseded": "superseded",
}
-# CHANGELOG / HISTORY / NEWS filenames (case-insensitive match on the stem).
-_CHANGELOG_NAMES = frozenset(
- {"changelog", "history", "news", "changes", "releasenotes", "release-notes"}
-)
-# keep-a-changelog section headers that carry decision signal. "Added" is
-# excluded — additions are rarely *decisions* about structure, just features.
-_CHANGELOG_DECISION_SECTIONS = frozenset({"changed", "removed", "deprecated", "security"})
-_MAX_CHANGELOG_VERSIONS = 15
# PR/squash body markers — a body containing any of these reads like a PR
# description worth mining (vs an incidental multi-line commit message).
@@ -633,85 +629,7 @@ class DecisionExtractor:
return decisions
# ------------------------------------------------------------------
- # Source 3: README / docs mining
- # ------------------------------------------------------------------
-
- async def mine_readme_docs(self) -> list[ExtractedDecision]:
- """Extract decisions from documentation files."""
- if not self._provider:
- return []
-
- doc_patterns = [
- "README.md",
- "CLAUDE.md",
- "ARCHITECTURE.md",
- "CONTRIBUTING.md",
- "DESIGN.md",
- "DECISIONS.md",
- ]
- doc_files: list[Path] = []
-
- for pattern in doc_patterns:
- p = self._repo_path / pattern
- if p.is_file():
- doc_files.append(p)
-
- # Also check docs/ directory
- docs_dir = self._repo_path / "docs"
- if docs_dir.is_dir():
- for md_file in docs_dir.rglob("*.md"):
- if len(doc_files) >= 10:
- break
- doc_files.append(md_file)
-
- decisions: list[ExtractedDecision] = []
-
- for doc_path in doc_files[:10]:
- try:
- content = doc_path.read_text(encoding="utf-8", errors="replace")
- except (OSError, UnicodeDecodeError):
- continue
-
- # Skip very large files
- if len(content) > 50_000:
- continue
-
- # Strip fenced code blocks to avoid treating example markers
- # (e.g. `# WHY: ...` in code examples) as real decisions.
- content = self._strip_code_blocks(content)
-
- try:
- rel_path = str(doc_path.relative_to(self._repo_path))
- except ValueError:
- rel_path = str(doc_path)
-
- try:
- prompt = README_MINING_PROMPT.format(
- file_path=rel_path,
- content=content[:15_000], # Limit token usage
- )
- response = await self._provider.generate(
- _SYSTEM_PROMPT, prompt, max_tokens=3000, temperature=0.2
- )
- extracted = self._parse_decisions_json(response.content)
- for d in extracted:
- d.source = "readme_mining"
- d.status = "proposed"
- d.confidence = 0.60
- d.evidence_file = rel_path
- d.affected_modules = self._infer_modules_from_text(d.title + " " + d.decision)
- d.source_text = content
- decisions.extend(extracted)
- except Exception:
- logger.warning(
- "decision_extractor.readme_mining_failed",
- file=rel_path,
- )
-
- return decisions
-
- # ------------------------------------------------------------------
- # Source 4: ADR auto-discovery (deterministic-first)
+ # Source 3: ADR auto-discovery (deterministic-first)
# ------------------------------------------------------------------
async def discover_adrs(self) -> list[ExtractedDecision]:
@@ -875,138 +793,7 @@ class DecisionExtractor:
)
# ------------------------------------------------------------------
- # Source 5: CHANGELOG mining
- # ------------------------------------------------------------------
-
- async def mine_changelog(self) -> list[ExtractedDecision]:
- """Mine keep-a-changelog Changed/Removed/Deprecated sections."""
- path = self._find_changelog()
- if path is None:
- return []
- try:
- content = path.read_text(encoding="utf-8", errors="replace")
- except (OSError, UnicodeDecodeError):
- return []
- try:
- rel = str(path.relative_to(self._repo_path))
- except ValueError:
- rel = str(path)
-
- entries = self._parse_changelog(content)
- if not entries:
- return []
-
- if self._provider:
- return await self._structure_changelog_entries(entries, rel, content)
-
- # No LLM — emit raw decisions straight from the decision-y bullets.
- decisions: list[ExtractedDecision] = []
- for section, bullet in entries[:50]:
- decisions.append(
- ExtractedDecision(
- title=_truncate_title(bullet, 100),
- decision=bullet,
- context=f"CHANGELOG · {section.title()}",
- source="changelog",
- status="proposed",
- confidence=0.50,
- evidence_file=rel,
- source_quote=bullet,
- source_text=content,
- tags=self._infer_tags(bullet),
- )
- )
- return decisions
-
- def _find_changelog(self) -> Path | None:
- """Locate a CHANGELOG/HISTORY/NEWS file (any extension).
-
- Checks the repo root first, then the conventional documentation
- subdirectories (``docs/``, ``doc/``, ``.github/``). Many projects keep
- their changelog under ``docs/`` rather than at the root, so a root-only
- scan silently skips this source.
- """
- search_dirs = [
- self._repo_path,
- self._repo_path / "docs",
- self._repo_path / "doc",
- self._repo_path / ".github",
- ]
- for directory in search_dirs:
- if not directory.is_dir():
- continue
- for p in sorted(directory.glob("*")):
- if not p.is_file():
- continue
- stem = re.sub(r"[^a-z]", "", p.stem.lower())
- if stem in _CHANGELOG_NAMES:
- return p
- return None
-
- def _parse_changelog(self, content: str) -> list[tuple[str, str]]:
- """Return ``(section, bullet)`` pairs from decision-relevant sections."""
- entries: list[tuple[str, str]] = []
- version_count = 0
- current_section: str | None = None
- in_version = True
- for line in content.splitlines():
- h2 = re.match(r"^##\s+(.+)$", line)
- if h2:
- name = h2.group(1).strip().lower().strip("[]")
- base = name.split()[0] if name else ""
- if base in _CHANGELOG_DECISION_SECTIONS:
- # Some changelogs use H2 section headers directly.
- current_section = base
- else:
- version_count += 1
- in_version = version_count <= _MAX_CHANGELOG_VERSIONS
- current_section = None
- continue
- h3 = re.match(r"^###\s+(.+)$", line)
- if h3:
- current_section = h3.group(1).strip().lower()
- continue
- if not in_version or current_section not in _CHANGELOG_DECISION_SECTIONS:
- continue
- s = line.strip()
- if s.startswith(("-", "*", "+")):
- bullet = s[1:].strip()
- if bullet:
- entries.append((current_section, bullet))
- return entries
-
- async def _structure_changelog_entries(
- self, entries: list[tuple[str, str]], rel: str, content: str
- ) -> list[ExtractedDecision]:
- """LLM-structure the highest-signal changelog bullets into decisions."""
- signal = [
- (s, b)
- for (s, b) in entries
- if s in ("removed", "deprecated")
- or any(k in b.lower() for k in DECISION_SIGNAL_KEYWORDS)
- ]
- chosen = (signal or entries)[:40]
- block = "\n".join(f"- [{s.title()}] {b}" for s, b in chosen)
- prompt = CHANGELOG_MINING_PROMPT.format(entries_block=block)
- try:
- response = await self._provider.generate(
- _SYSTEM_PROMPT, prompt, max_tokens=2500, temperature=0.2
- )
- except Exception:
- logger.warning("decision_extractor.changelog_mining_failed", file=rel)
- return []
- extracted = self._parse_decisions_json(response.content)
- for d in extracted:
- d.source = "changelog"
- d.status = "proposed"
- d.confidence = 0.60
- d.evidence_file = rel
- d.source_text = content
- d.affected_modules = self._infer_modules_from_text(d.title + " " + d.decision)
- return extracted
-
- # ------------------------------------------------------------------
- # Source 6: PR / squash-body mining (consumes commit bodies from 1A)
+ # Source 4: PR / squash-body mining (consumes commit bodies from 1A)
# ------------------------------------------------------------------
async def mine_pr_bodies(self) -> list[ExtractedDecision]:
@@ -1090,7 +877,7 @@ class DecisionExtractor:
return decisions
# ------------------------------------------------------------------
- # Source 7: Comment archaeology (centrality-bounded)
+ # Source 5: Comment archaeology (centrality-bounded)
# ------------------------------------------------------------------
async def mine_comment_archaeology(self) -> list[ExtractedDecision]:
@@ -1464,9 +1251,7 @@ class DecisionExtractor:
all_sources: list[tuple[str, Any]] = [
("inline_marker", self.scan_inline_markers),
("git_archaeology", self.mine_git_archaeology),
- ("readme_mining", self.mine_readme_docs),
("adr", self.discover_adrs),
- ("changelog", self.mine_changelog),
("pr", self.mine_pr_bodies),
("comment", self.mine_comment_archaeology),
]
diff --git a/packages/core/src/repowise/core/analysis/decisions/prompts.py b/packages/core/src/repowise/core/analysis/decisions/prompts.py
index 8d5c44ccf..1a9a47ae9 100644
--- a/packages/core/src/repowise/core/analysis/decisions/prompts.py
+++ b/packages/core/src/repowise/core/analysis/decisions/prompts.py
@@ -85,29 +85,6 @@ Return a JSON array of decisions:
Only extract explicit decisions. Return [] if none found.
"""
-CHANGELOG_MINING_PROMPT = """\
-These are CHANGELOG entries from sections that usually record deliberate \
-changes (Changed / Removed / Deprecated). Extract any that represent an \
-architectural decision (a technology/pattern change, a removal, a deprecation \
-with a reason).
-
-{entries_block}
-
-Return a JSON array of decisions:
-{{
- "title": "short title",
- "context": "what prompted it (only if stated)",
- "decision": "what was changed/removed/deprecated",
- "rationale": "why (only if stated — do not invent)",
- "alternatives": [],
- "consequences": [],
- "tags": [],
- "source_quote": "the exact changelog line this came from"
-}}
-
-Skip pure feature additions and trivial fixes. Return [] if none qualify.
-"""
-
PR_BODY_MINING_PROMPT = """\
These are squash-merge / PR commit bodies. Extract any architectural decision \
described in them (technology choices, migrations, structural changes, things \
diff --git a/packages/core/src/repowise/core/analysis/decisions/provenance.py b/packages/core/src/repowise/core/analysis/decisions/provenance.py
index bc45168c0..27d9abb10 100644
--- a/packages/core/src/repowise/core/analysis/decisions/provenance.py
+++ b/packages/core/src/repowise/core/analysis/decisions/provenance.py
@@ -17,7 +17,10 @@ from __future__ import annotations
import re
__all__ = [
+ "LISTABLE_SOURCES",
"MAX_SOURCE_RANK",
+ "PLACEHOLDER_SOURCES",
+ "RETIRED_SOURCES",
"SOURCE_RANK",
"compute_confidence",
"normalize_text",
@@ -35,17 +38,30 @@ __all__ = [
# discarded). ``test_name`` and ``inferred`` are placeholders for later phases
# (LLM-docs harvest lands ``llm_inferred`` in Phase 2) but the full ladder is
# defined now so ranks are stable across phases.
+#
+# A person outranks a document. ``session`` sits above ``adr`` because a
+# transcript carries the user's own words about a choice they were making at the
+# time, corroborated by them in the moment; an ADR is someone's later write-up
+# of it. With ``session`` below ``adr`` the promotion branch in
+# ``crud.decisions`` (``>=``) never fired for a transcript, so a mined document
+# overwrote the headline a user had actually said.
+#
+# ``adr`` and ``pr`` deliberately tie at 7: both are written-up accounts of a
+# decision rather than the decision being made, and the ``>=`` comparison means
+# the later-arriving one takes the headline. The set of *values* is unchanged by
+# the session/adr swap, so ``MAX_SOURCE_RANK`` stays 9 and no other source's
+# confidence moves.
SOURCE_RANK: dict[str, int] = {
"cli": 9, # human-authored manual entry — most authoritative
- "adr": 8, # architecture decision records (structured, intentional)
- "session": 7, # mined from agent-session transcripts (user-corroborated)
+ "session": 8, # a user's own words in a transcript, corroborated by them
+ "adr": 7, # architecture decision records (structured, intentional)
"pr": 7, # PR / squash-merge body
"commit": 6, # individual commit message
"git_archaeology": 6, # alias for commit-mined decisions
- "changelog": 5, # keep-a-changelog Changed/Removed/Deprecated
+ "changelog": 5, # legacy rows from the removed changelog miner
"inline_marker": 4, # # WHY: / # DECISION: code markers
"comment": 3, # LLM-curated rationale prose on high-centrality code
- "readme_mining": 3, # implicit decisions in README/docs prose
+ "readme_mining": 3, # legacy rows from the removed README/docs miner
"code_comment": 2, # legacy rows from the removed comment harvest (#751)
"test_name": 2, # placeholder — behaviour asserted by a test name
"inferred": 1, # placeholder — purely inferred, no verbatim source
@@ -54,6 +70,28 @@ SOURCE_RANK: dict[str, int] = {
MAX_SOURCE_RANK: int = max(SOURCE_RANK.values())
+#: Sources that no longer extract, newest last. Their names stay in
+#: ``SOURCE_RANK`` so rows written before each removal still rank instead of
+#: falling to the unknown-source floor, but no extractor produces them and the
+#: persist path drains whatever they left ``proposed``. One list, because the
+#: purge, the ranking annotations and the extractor's own docs all have to agree
+#: about which sources are gone; three hand-maintained copies is how the #751
+#: drain ended up being the only one anybody remembered to wire.
+RETIRED_SOURCES: tuple[str, ...] = ("code_comment", "readme_mining", "changelog")
+
+#: Rungs defined ahead of the extractor that fills them, so the ladder's values
+#: stay stable across phases. No row in any store carries these, which is why
+#: anything offering the user a list of sources has to leave them out.
+PLACEHOLDER_SOURCES: tuple[str, ...] = ("test_name", "inferred")
+
+#: Sources a stored record can actually carry: the ladder minus the retired and
+#: the not-yet-real. Derived, because the hand-written copy behind
+#: ``decision list --source`` had drifted into offering a retired source while
+#: omitting ``session``.
+LISTABLE_SOURCES: tuple[str, ...] = tuple(
+ sorted(name for name in SOURCE_RANK if name not in (*RETIRED_SOURCES, *PLACEHOLDER_SOURCES))
+)
+
# Rank at/below which the only evidence is a heuristic rationale-comment harvest
# (``code_comment`` and the placeholder ``test_name``/``inferred`` tiers). A
# decision resting solely on a plain code comment is a weak signal and must not
diff --git a/packages/core/src/repowise/core/analysis/decisions/rationale_comments.py b/packages/core/src/repowise/core/analysis/decisions/rationale_comments.py
index 67eb17369..4326d0466 100644
--- a/packages/core/src/repowise/core/analysis/decisions/rationale_comments.py
+++ b/packages/core/src/repowise/core/analysis/decisions/rationale_comments.py
@@ -215,7 +215,7 @@ C_BLOCK_EXTS: frozenset[str] = frozenset(
# The set of extensions this module can mine — anything we know a comment
# syntax for. Markdown / RST / plain text are deliberately excluded: their
# prose is full of causal words ("because") that are not code rationale, and
-# README / docs already feed the readme_mining source.
+# README / docs are not mined for decisions any more (readme_mining retired).
CODE_EXTENSIONS: frozenset[str] = frozenset(LINE_PREFIXES) | C_BLOCK_EXTS
# ---------------------------------------------------------------------------
diff --git a/packages/core/src/repowise/core/persistence/crud/decisions.py b/packages/core/src/repowise/core/persistence/crud/decisions.py
index a379d112d..52fc1361f 100644
--- a/packages/core/src/repowise/core/persistence/crud/decisions.py
+++ b/packages/core/src/repowise/core/persistence/crud/decisions.py
@@ -14,7 +14,11 @@ import structlog
from sqlalchemy import case, delete, func, or_, select
from sqlalchemy.ext.asyncio import AsyncSession
-from repowise.core.analysis.decision_provenance import compute_confidence, rank_for_source
+from repowise.core.analysis.decisions.provenance import (
+ SOURCE_RANK,
+ compute_confidence,
+ rank_for_source,
+)
from ..decision_graph import sync_decision_node_links
from ..models import (
@@ -462,6 +466,103 @@ def _best_verification(values: list[str]) -> str:
return "unverified"
+def _rederive_headline(rec: DecisionRecord, evidence: list[DecisionEvidence]) -> None:
+ """Set a record's confidence + verification from its full evidence set.
+
+ The single definition of how a headline is scored. Both writers use it: the
+ upsert path after accreting a run's evidence, and ``reconcile_source_ranks``
+ after a ladder edit. Kept as one function because the two were briefly
+ copy-pasted and nothing would have forced the copies to stay equal.
+
+ Confidence rises with the best source rank and with the number of
+ *independent* corroborating sources, so it is derived from the whole set
+ rather than from whichever row happened to arrive last. No-op on empty
+ evidence: a record with nothing behind it keeps whatever it had.
+ """
+ if not evidence:
+ return
+ best_ver = _best_verification([e.verification for e in evidence])
+ rec.confidence = compute_confidence(
+ max(e.source_rank for e in evidence),
+ len({e.source for e in evidence}),
+ best_ver,
+ )
+ rec.verification = best_ver
+
+
+def _stale_rank_filter() -> Any:
+ """SQL matching evidence rows whose stored rank disagrees with the ladder.
+
+ Derived from ``SOURCE_RANK`` rather than hardcoded, so a future ladder edit
+ is picked up here automatically instead of needing a second place updated.
+ Bounded by the size of the ladder (a dozen terms), and it keeps the common
+ case — a store already on the current ladder — to an indexed match on
+ ``source`` that returns nothing, rather than hydrating the whole table.
+ """
+ return or_(
+ *[
+ (DecisionEvidence.source == name) & (DecisionEvidence.source_rank != rank)
+ for name, rank in SOURCE_RANK.items()
+ ]
+ )
+
+
+async def reconcile_source_ranks(session: AsyncSession) -> int:
+ """Re-stamp evidence rows whose stored rank predates a ``SOURCE_RANK`` edit.
+
+ ``DecisionEvidence.source_rank`` is written once at insert time, and two
+ ``ORDER BY`` clauses read it straight from the column, so it cannot simply be
+ derived on read. That makes the ladder a value copied into every row: editing
+ ``SOURCE_RANK`` leaves existing rows on the previous ladder, and because
+ headline confidence comes from ``max(source_rank)`` across a decision's
+ evidence, a store would end up scoring headlines off a mixture of two ladders
+ without anything looking wrong.
+
+ **This is the only repair path, deliberately.** An Alembic data migration was
+ written first and removed: hosted runs the same persist pipeline as a local
+ store, so the migration was redundant, and worse, it fixed the ranks *without*
+ re-deriving confidence — which made this function's own no-op check pass on
+ the next run and left hosted confidences on the old ladder permanently. One
+ path cannot disagree with itself.
+
+ Not repo-scoped, on purpose: the ladder is global, so in a workspace store
+ holding several repositories every one of them is on the same ladder and all
+ of them need the same repair.
+
+ Idempotent. Returns the number of evidence rows re-stamped (0 when already
+ reconciled, which is the steady state after the first run).
+ """
+ moved = (
+ (await session.execute(select(DecisionEvidence).where(_stale_rank_filter())))
+ .scalars()
+ .all()
+ )
+ if not moved:
+ return 0
+
+ for row in moved:
+ row.source_rank = rank_for_source(row.source)
+ await session.flush()
+
+ now = _now_utc()
+ for decision_id in {row.decision_id for row in moved}:
+ rec = await session.get(DecisionRecord, decision_id)
+ if rec is None:
+ continue
+ _rederive_headline(rec, await list_decision_evidence(session, decision_id))
+ rec.updated_at = now
+
+ # Flush the re-scored headlines too, not just the ranks. Without this the
+ # function returns with confidence still pending in the session, so whether
+ # the repair survives depends on what the caller does next.
+ await session.flush()
+
+ structlog.get_logger(__name__).info(
+ "decisions.source_ranks_reconciled", evidence_rows=len(moved)
+ )
+ return len(moved)
+
+
async def list_decision_evidence(
session: AsyncSession,
decision_id: str,
@@ -704,13 +805,7 @@ async def bulk_upsert_decisions(
# Re-derive headline confidence + verification from the FULL evidence
# set (existing + just-added), so corroboration accrues across runs.
- evidence = await list_decision_evidence(session, rec.id)
- if evidence:
- distinct_sources = {e.source for e in evidence}
- top_rank = max(e.source_rank for e in evidence)
- best_ver = _best_verification([e.verification for e in evidence])
- rec.confidence = compute_confidence(top_rank, len(distinct_sources), best_ver)
- rec.verification = best_ver
+ _rederive_headline(rec, await list_decision_evidence(session, rec.id))
rec.updated_at = _now_utc()
touched_ids.append(rec.id)
diff --git a/packages/core/src/repowise/core/persistence/models.py b/packages/core/src/repowise/core/persistence/models.py
index 40a5d8e58..76b5f3bf0 100644
--- a/packages/core/src/repowise/core/persistence/models.py
+++ b/packages/core/src/repowise/core/persistence/models.py
@@ -790,7 +790,7 @@ class DecisionRecord(Base):
# Provenance
source: Mapped[str] = mapped_column(
String(32), nullable=False, default="cli"
- ) # git_archaeology | inline_marker | readme_mining | cli
+ ) # git_archaeology | inline_marker | adr | pr | comment | session | cli
evidence_file: Mapped[str | None] = mapped_column(Text, nullable=True)
evidence_line: Mapped[int | None] = mapped_column(Integer, nullable=True)
confidence: Mapped[float] = mapped_column(Float, nullable=False, default=1.0)
diff --git a/packages/core/src/repowise/core/pipeline/persist.py b/packages/core/src/repowise/core/pipeline/persist.py
index 39c219bdc..112368293 100644
--- a/packages/core/src/repowise/core/pipeline/persist.py
+++ b/packages/core/src/repowise/core/pipeline/persist.py
@@ -1162,16 +1162,30 @@ async def persist_analysis(result: Any, session: Any, repo_id: str) -> None:
if harvested:
decision_dicts.extend(harvested)
- # One-shot drain of proposals from the removed code_comment harvest;
- # without this, DBs indexed before its removal keep a flooded review
- # queue forever (#751). Confirmed/dismissed rows are kept.
+ # One-shot drain of proposals left by retired extraction sources; without
+ # this, DBs indexed before a removal keep a flooded review queue forever
+ # (#751 for code_comment). Confirmed/dismissed rows are kept.
try:
+ from repowise.core.analysis.decision_provenance import RETIRED_SOURCES
from repowise.core.persistence.crud import purge_proposed_decisions_by_source
- await purge_proposed_decisions_by_source(session, repo_id, "code_comment")
+ for _retired in RETIRED_SOURCES:
+ await purge_proposed_decisions_by_source(session, repo_id, _retired)
except Exception as _purge_err:
logger.debug("decision_purge_skipped", error=str(_purge_err))
+ # Re-stamp evidence rows left on a previous SOURCE_RANK ladder. Local stores
+ # are created by ``init_db`` and never see Alembic, so the migration alone
+ # would only reach hosted; this is the same repair on the path every store
+ # takes. No-op scan once reconciled, and it runs whether or not this run
+ # produced decisions, because a store with nothing new still holds the rows.
+ try:
+ from repowise.core.persistence.crud import reconcile_source_ranks
+
+ await reconcile_source_ranks(session)
+ except Exception as _rank_err:
+ logger.debug("decision_rank_reconcile_skipped", error=str(_rank_err))
+
if decision_dicts:
# Reuse the run's shared vector store for semantic (paraphrase) dedup
# and to make decisions searchable; title dedup still runs when None.
diff --git a/packages/core/src/repowise/core/pipeline/phases/analysis.py b/packages/core/src/repowise/core/pipeline/phases/analysis.py
index e119dff34..715f10eab 100644
--- a/packages/core/src/repowise/core/pipeline/phases/analysis.py
+++ b/packages/core/src/repowise/core/pipeline/phases/analysis.py
@@ -28,11 +28,9 @@ DECISION_EXTRACTION_TIMEOUT_SECS = 300
_DECISION_SOURCE_LABELS: tuple[tuple[str, str], ...] = (
("inline_marker", "from inline markers"),
("adr", "from ADR files"),
- ("changelog", "from changelogs"),
("pr", "from pull requests"),
("git_archaeology", "from git history"),
("comment", "from comments"),
- ("readme_mining", "from docs"),
("session", "from agent sessions"),
)
diff --git a/tests/unit/analysis/test_decision_provenance.py b/tests/unit/analysis/test_decision_provenance.py
index 6ed57ed58..649b884d2 100644
--- a/tests/unit/analysis/test_decision_provenance.py
+++ b/tests/unit/analysis/test_decision_provenance.py
@@ -19,13 +19,50 @@ from repowise.core.analysis.decision_provenance import (
def test_source_rank_ladder_ordering():
- # adr > pr > commit > changelog > inline_marker > comment > test_name > inferred
- order = ["adr", "pr", "commit", "changelog", "inline_marker", "comment", "test_name", "inferred"]
+ # session > adr > commit > changelog > inline_marker > comment > test_name > inferred
+ order = [
+ "session",
+ "adr",
+ "commit",
+ "changelog",
+ "inline_marker",
+ "comment",
+ "test_name",
+ "inferred",
+ ]
ranks = [rank_for_source(s) for s in order]
assert ranks == sorted(ranks, reverse=True)
assert ranks == [8, 7, 6, 5, 4, 3, 2, 1]
+def test_session_outranks_adr():
+ """A user's own words beat a later write-up of them.
+
+ The promotion branch in ``crud.decisions`` compares with ``>=``, so with
+ ``session`` below ``adr`` a transcript could never take the headline and a
+ mined document overwrote what the user actually said.
+ """
+ assert rank_for_source("session") > rank_for_source("adr")
+
+
+def test_adr_and_pr_tie():
+ """Both are write-ups rather than the decision being made; later one wins."""
+ assert rank_for_source("adr") == rank_for_source("pr") == 7
+
+
+def test_swapping_session_and_adr_left_the_scale_intact():
+ """The ladder's value set is unchanged, so no other source's confidence moved.
+
+ ``compute_confidence`` divides by ``MAX_SOURCE_RANK``. Had the swap been done
+ by lifting ``session`` to a new top rank instead of trading places with
+ ``adr``, every source's confidence would have silently rescaled and every
+ stored value in every existing store would have been on a different scale
+ from every new one.
+ """
+ assert MAX_SOURCE_RANK == 9
+ assert compute_confidence(rank_for_source("commit")) == compute_confidence(6)
+
+
def test_git_archaeology_aliases_commit_rank():
assert rank_for_source("git_archaeology") == rank_for_source("commit") == 6
diff --git a/tests/unit/analysis/test_decision_sources.py b/tests/unit/analysis/test_decision_sources.py
index 3236c0f3e..4ebe9d5e8 100644
--- a/tests/unit/analysis/test_decision_sources.py
+++ b/tests/unit/analysis/test_decision_sources.py
@@ -1,4 +1,4 @@
-"""Deterministic (LLM-free) extraction from ADRs and CHANGELOGs (Phase 1B)."""
+"""Deterministic (LLM-free) extraction from ADRs (Phase 1B)."""
from __future__ import annotations
@@ -7,6 +7,7 @@ from repowise.core.analysis.decision_extractor import (
DecisionExtractor,
enabled_source_names,
)
+from repowise.core.analysis.decision_provenance import RETIRED_SOURCES
_NYGARD_ADR = """\
# 1. Use PostgreSQL for primary storage
@@ -96,55 +97,29 @@ async def test_discover_adrs_maps_superseded_status_from_frontmatter(tmp_path):
assert "Adopt gRPC" in d.decision
-async def test_mine_changelog_extracts_decision_sections(tmp_path):
- (tmp_path / "CHANGELOG.md").write_text(_CHANGELOG, encoding="utf-8")
-
- ex = DecisionExtractor(repo_path=tmp_path) # no provider → raw bullets
- decisions = await ex.mine_changelog()
-
- texts = [d.decision for d in decisions]
- assert any("Migrate the auth layer" in t for t in texts)
- assert any("Drop support for the legacy XML" in t for t in texts)
- # "Added" section is intentionally excluded — it is not a structural decision.
- assert not any("dashboard widget" in t for t in texts)
- assert all(d.source == "changelog" for d in decisions)
-
-
-async def test_mine_changelog_finds_changelog_under_docs(tmp_path):
- # Many projects keep the changelog under docs/ rather than at the root.
- docs = tmp_path / "docs"
- docs.mkdir()
- (docs / "CHANGELOG.md").write_text(_CHANGELOG, encoding="utf-8")
-
- ex = DecisionExtractor(repo_path=tmp_path) # no provider → raw bullets
- decisions = await ex.mine_changelog()
-
- texts = [d.decision for d in decisions]
- assert any("Migrate the auth layer" in t for t in texts)
- assert all(d.source == "changelog" for d in decisions)
-
async def test_extract_all_runs_deterministic_sources_and_gates(tmp_path):
adr_dir = tmp_path / "docs" / "adr"
adr_dir.mkdir(parents=True)
(adr_dir / "0001-use-postgres.md").write_text(_NYGARD_ADR, encoding="utf-8")
+ # A changelog the retired miner would once have mined; nothing reads it now.
(tmp_path / "CHANGELOG.md").write_text(_CHANGELOG, encoding="utf-8")
ex = DecisionExtractor(repo_path=tmp_path)
report = await ex.extract_all()
assert report.by_source["adr"] == 1
- assert report.by_source["changelog"] >= 2
# All survive the gate (deterministic fields are verbatim).
sources = {d.source for d in report.decisions}
assert "adr" in sources
- assert "changelog" in sources
adr = next(d for d in report.decisions if d.source == "adr")
assert adr.verification == "exact"
- # The repo-wide code_comment harvest was removed (#751); extract_all must
- # neither run it nor report it.
- assert "code_comment" not in report.by_source
- assert not any(d.source == "code_comment" for d in report.decisions)
+ # Retired sources must neither run nor be reported, however tempting the
+ # files sitting in the repo are. One list, so a fourth removal is covered
+ # here the day it lands.
+ for retired in RETIRED_SOURCES:
+ assert retired not in report.by_source
+ assert not any(d.source == retired for d in report.decisions)
async def test_extract_all_honors_enabled_sources(tmp_path):
@@ -163,8 +138,6 @@ async def test_extract_all_honors_enabled_sources(tmp_path):
assert set(seen) == {"adr", "inline_marker"}
assert set(report.by_source) == {"adr", "inline_marker"}
assert report.by_source["adr"] == 1
- # The changelog file exists but its source was disabled.
- assert not any(d.source == "changelog" for d in report.decisions)
def test_enabled_source_names_defaults_and_overrides():
@@ -172,16 +145,16 @@ def test_enabled_source_names_defaults_and_overrides():
assert enabled_source_names(None) == SOURCE_NAMES
assert enabled_source_names({}) == SOURCE_NAMES
- cfg = {"decisions": {"sources": {"comment": False, "changelog": False}}}
+ cfg = {"decisions": {"sources": {"comment": False, "pr": False}}}
enabled = enabled_source_names(cfg)
assert "comment" not in enabled
- assert "changelog" not in enabled
+ assert "pr" not in enabled
assert "adr" in enabled and "inline_marker" in enabled
- # Unknown / stale keys (e.g. the removed code_comment) are ignored.
- assert enabled_source_names({"decisions": {"sources": {"code_comment": False}}}) == (
- SOURCE_NAMES
- )
+ # Stale keys naming a retired source are ignored rather than breaking a
+ # config written before the removal.
+ for retired in RETIRED_SOURCES:
+ assert enabled_source_names({"decisions": {"sources": {retired: False}}}) == SOURCE_NAMES
# Malformed sections never break extraction.
assert enabled_source_names({"decisions": "nope"}) == SOURCE_NAMES
assert enabled_source_names({"decisions": {"sources": "nope"}}) == SOURCE_NAMES
diff --git a/tests/unit/persistence/test_decision_source_rank_backfill.py b/tests/unit/persistence/test_decision_source_rank_backfill.py
new file mode 100644
index 000000000..971c81b25
--- /dev/null
+++ b/tests/unit/persistence/test_decision_source_rank_backfill.py
@@ -0,0 +1,228 @@
+"""Phase 1 item 1: a transcript takes the headline, and old rows are re-stamped.
+
+Two halves of the same change. The ladder swap is what lets a user's own words
+win; ``reconcile_source_ranks`` is what stops a store from holding rows on both
+ladders at once, which would leave headline confidence derived from a mixture.
+"""
+
+from __future__ import annotations
+
+from sqlalchemy import select
+
+from repowise.core.analysis.decision_provenance import (
+ RETIRED_SOURCES,
+ compute_confidence,
+ rank_for_source,
+)
+from repowise.core.persistence.crud import (
+ bulk_upsert_decisions,
+ list_decision_evidence,
+ purge_proposed_decisions_by_source,
+ reconcile_source_ranks,
+)
+from repowise.core.persistence.models import DecisionEvidence, DecisionRecord
+from tests.unit.persistence.helpers import insert_repo
+
+_TITLE = "Use PostgreSQL for storage"
+
+
+def _adr_dict():
+ return {
+ "title": _TITLE,
+ "decision": "Use PostgreSQL as the primary datastore",
+ "rationale": "Strong transactional guarantees",
+ "source": "adr",
+ "status": "active",
+ "evidence_file": "docs/adr/0001-postgres.md",
+ "confidence": 0.9,
+ "verification": "exact",
+ "source_quote": "Use PostgreSQL as the primary datastore",
+ }
+
+
+def _session_dict():
+ return {
+ "title": _TITLE,
+ "decision": "Went with Postgres because we need real transactions",
+ "rationale": "the user said so, in their own words, mid-task",
+ "source": "session",
+ "status": "active",
+ "confidence": 0.8,
+ "verification": "exact",
+ "source_quote": "Went with Postgres because we need real transactions",
+ }
+
+
+async def _record(session, repo_id):
+ result = await session.execute(
+ select(DecisionRecord).where(DecisionRecord.repository_id == repo_id)
+ )
+ return result.scalars().one()
+
+
+async def test_session_takes_the_headline_from_an_adr(async_session):
+ """The bug this item exists for: the ADR landed first and used to keep it."""
+ repo = await insert_repo(async_session)
+
+ await bulk_upsert_decisions(async_session, repo.id, [_adr_dict()])
+ await bulk_upsert_decisions(async_session, repo.id, [_session_dict()])
+
+ rec = await _record(async_session, repo.id)
+ assert rec.source == "session"
+ assert rec.decision == "Went with Postgres because we need real transactions"
+
+ # The ADR is corroboration, never discarded.
+ sources = {e.source for e in await list_decision_evidence(async_session, rec.id)}
+ assert sources == {"adr", "session"}
+
+
+async def test_adr_does_not_take_the_headline_back(async_session):
+ """Re-harvesting the document on a later run must not undo the promotion."""
+ repo = await insert_repo(async_session)
+
+ await bulk_upsert_decisions(async_session, repo.id, [_session_dict()])
+ await bulk_upsert_decisions(async_session, repo.id, [_adr_dict()])
+
+ rec = await _record(async_session, repo.id)
+ assert rec.source == "session"
+
+
+async def test_reconcile_restamps_rows_left_on_the_old_ladder(async_session):
+ repo = await insert_repo(async_session)
+ await bulk_upsert_decisions(async_session, repo.id, [_session_dict()])
+ rec = await _record(async_session, repo.id)
+
+ # Simulate a store written before the swap: session evidence stamped 7, and
+ # the headline confidence derived from that stale rank.
+ row = (
+ await async_session.execute(
+ select(DecisionEvidence).where(DecisionEvidence.decision_id == rec.id)
+ )
+ ).scalars().one()
+ row.source_rank = 7
+ rec.confidence = compute_confidence(7, 1, "exact")
+ await async_session.flush()
+ stale_confidence = rec.confidence
+
+ moved = await reconcile_source_ranks(async_session)
+
+ assert moved == 1
+ await async_session.refresh(row)
+ await async_session.refresh(rec)
+ assert row.source_rank == rank_for_source("session") == 8
+ assert rec.confidence == compute_confidence(8, 1, "exact")
+ assert rec.confidence > stale_confidence
+
+
+async def test_reconcile_scores_a_headline_the_same_way_the_upsert_does(async_session):
+ """The two writers must not drift; they share ``_rederive_headline``.
+
+ Take a record scored by the upsert path, push its evidence back onto the old
+ ladder, reconcile, and the score has to land back on the same number. If the
+ two ever grow separate copies of the expression, this is what catches it.
+ """
+ repo = await insert_repo(async_session)
+ await bulk_upsert_decisions(async_session, repo.id, [_session_dict(), _adr_dict()])
+ rec = await _record(async_session, repo.id)
+ scored_by_upsert = rec.confidence
+
+ rows = (
+ await async_session.execute(
+ select(DecisionEvidence).where(DecisionEvidence.decision_id == rec.id)
+ )
+ ).scalars().all()
+ for row in rows:
+ row.source_rank = 7 if row.source == "session" else 8
+ rec.confidence = 0.123
+ await async_session.flush()
+
+ assert await reconcile_source_ranks(async_session) == len(rows)
+ await async_session.refresh(rec)
+ assert rec.confidence == scored_by_upsert
+
+
+async def test_reconcile_is_idempotent(async_session):
+ """A reconciled store pays one scan and writes nothing; it runs every persist."""
+ repo = await insert_repo(async_session)
+ await bulk_upsert_decisions(async_session, repo.id, [_session_dict(), _adr_dict()])
+
+ assert await reconcile_source_ranks(async_session) == 0
+ assert await reconcile_source_ranks(async_session) == 0
+
+
+async def test_every_retired_source_is_drained(async_session):
+ """Item 2: removing the extractor is half the job; the rows have to go too.
+
+ Driven off ``RETIRED_SOURCES`` rather than a literal list, so a fourth
+ removal is covered here the day it lands instead of the day someone notices
+ the queue never got shorter.
+ """
+ repo = await insert_repo(async_session)
+ for i, source in enumerate(RETIRED_SOURCES):
+ await bulk_upsert_decisions(
+ async_session,
+ repo.id,
+ [
+ {
+ "title": f"Retired record {i}",
+ "decision": f"something {source} once mined",
+ "source": source,
+ "status": "proposed",
+ "confidence": 0.6,
+ "verification": "exact",
+ "source_quote": f"something {source} once mined",
+ }
+ ],
+ )
+
+ for source in RETIRED_SOURCES:
+ assert await purge_proposed_decisions_by_source(async_session, repo.id, source) == 1
+
+ remaining = (
+ await async_session.execute(
+ select(DecisionRecord).where(DecisionRecord.repository_id == repo.id)
+ )
+ ).scalars().all()
+ assert remaining == []
+
+
+def test_persist_wires_both_repairs():
+ """Both repairs sit inside ``except Exception: logger.debug`` on the persist
+ path, so a bad import degrades to a silent no-op that no other test would
+ notice. Assert the names resolve from where ``persist_analysis`` imports
+ them: ``RETIRED_SOURCES`` in particular reaches it through a star-exporting
+ façade and is one missing ``__all__`` entry away from vanishing quietly.
+ """
+ from repowise.core.analysis import decision_provenance as facade
+ from repowise.core.persistence.crud import (
+ purge_proposed_decisions_by_source,
+ reconcile_source_ranks,
+ )
+
+ assert facade.RETIRED_SOURCES == RETIRED_SOURCES
+ assert callable(purge_proposed_decisions_by_source)
+ assert callable(reconcile_source_ranks)
+
+
+async def test_purge_keeps_what_a_human_confirmed(async_session):
+ """Only ``proposed`` rows drain. An active record survives its source's removal."""
+ repo = await insert_repo(async_session)
+ await bulk_upsert_decisions(
+ async_session,
+ repo.id,
+ [
+ {
+ "title": "Kept because someone confirmed it",
+ "decision": "mined from a changelog, then confirmed by a human",
+ "source": "changelog",
+ "status": "active",
+ "confidence": 0.6,
+ "verification": "exact",
+ "source_quote": "mined from a changelog, then confirmed by a human",
+ }
+ ],
+ )
+
+ assert await purge_proposed_decisions_by_source(async_session, repo.id, "changelog") == 0
+ rec = await _record(async_session, repo.id)
+ assert rec.status == "active"
diff --git a/tests/unit/sessions/test_session_decisions_e2e.py b/tests/unit/sessions/test_session_decisions_e2e.py
index 4c27069f5..30ae3c30d 100644
--- a/tests/unit/sessions/test_session_decisions_e2e.py
+++ b/tests/unit/sessions/test_session_decisions_e2e.py
@@ -224,6 +224,12 @@ async def test_init_pipeline_respects_session_mining_gate(tmp_path, monkeypatch)
assert "session" not in report.by_source
-def test_session_rank_sits_between_adr_and_commit():
- assert SOURCE_RANK["session"] == 7
- assert SOURCE_RANK["adr"] > SOURCE_RANK["session"] > SOURCE_RANK["commit"]
+def test_session_rank_sits_above_adr_and_below_cli():
+ """A transcript is the user speaking; an ADR is a write-up of it.
+
+ This used to assert ``adr > session``, which meant the ``>=`` promotion
+ branch in ``crud.decisions`` never fired for a transcript and a mined
+ document overwrote the user's own words.
+ """
+ assert SOURCE_RANK["session"] == 8
+ assert SOURCE_RANK["cli"] > SOURCE_RANK["session"] > SOURCE_RANK["adr"]
diff --git a/website/cli-reference.md b/website/cli-reference.md
index 50ce7e5fc..cbacbff2c 100644
--- a/website/cli-reference.md
+++ b/website/cli-reference.md
@@ -369,7 +369,7 @@ repowise decision SUBCOMMAND [OPTIONS]
| Flag | Type | Description |
|------|------|-------------|
| `--status` | choice | Filter by status: `proposed`, `active`, `deprecated`, `superseded`, `all` |
-| `--source` | choice | Filter by origin: `git_archaeology`, `inline_marker`, `readme_mining`, `cli`, `all` |
+| `--source` | choice | Filter by origin: `adr`, `cli`, `comment`, `commit`, `git_archaeology`, `inline_marker`, `llm_inferred`, `pr`, `session`, `all` |
| `--proposed` | flag | Show only proposed decisions |
| `--stale-only` | flag | Show only decisions with staleness score ≥ 0.5 |