Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
fix(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.mdindex 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.mdindex 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.mdindex 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.pyindex 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.pyindex 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 theverbatim source span are dropped, and evidence-less decisions are rejected.@@ -43,7 +50,6 @@ from repowise.core.analysis.decisions.gate import apply_substring_gatefrom .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.pyindex 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.pyindex 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 annotationsimport 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 notdiff --git a/packages/core/src/repowise/core/analysis/decisions/rationale_comments.py b/packages/core/src/repowise/core/analysis/decisions/rationale_comments.pyindex 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.pyindex 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 structlogfrom sqlalchemy import case, delete, func, or_, selectfrom 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_linksfrom ..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.pyindex 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):# Provenancesource: 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 | clievidence_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.pyindex 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_SOURCESfrom 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.pyindex 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.pyindex 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") == 6diff --git a/tests/unit/analysis/test_decision_sources.py b/tests/unit/analysis/test_decision_sources.pyindex 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 sourcesadr = 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_NAMESassert 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 enabledassert "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_NAMESassert enabled_source_names({"decisions": {"sources": "nope"}}) == SOURCE_NAMESdiff --git a/tests/unit/persistence/test_decision_source_rank_backfill.py b/tests/unit/persistence/test_decision_source_rank_backfill.pynew file mode 100644index 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.pyindex 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.mdindex 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 |