Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

feat(decisions): rank agent-proposed decisions with session-mined ones (#4658)

Raghav Chamadiya5140fcde12eb
diff --git a/docs/architecture/decisions.md b/docs/architecture/decisions.md
index ec7520a5e..8ca91dacd 100644
--- a/docs/architecture/decisions.md
+++ b/docs/architecture/decisions.md
@@ -81,7 +81,8 @@ conf = (0.4 + earned + min(0.12, 0.04 * (corroborating_sources - 1)))
clamped to [0, 0.99]
```
-The rank ladder (`SOURCE_RANK`): `cli` 9, `session` 8, `adr` 7, `pr` 7,
+The rank ladder (`SOURCE_RANK`): `cli` 9, `session` 8, `agent` 8 (a coding
+agent's own proposal), `adr` 7, `pr` 7,
`commit` / `git_archaeology` / `conventions` 6, `inline_marker` 4, `comment` 3.
Retired sources keep their rungs (`changelog` 5, `readme_mining` 3,
`code_comment` 2) so old rows still rank. `session` sits above `adr` because a
diff --git a/docs/reference/CLI_REFERENCE.md b/docs/reference/CLI_REFERENCE.md
index ca29c2705..dde523945 100644
--- a/docs/reference/CLI_REFERENCE.md
+++ b/docs/reference/CLI_REFERENCE.md
@@ -1031,7 +1031,7 @@ Every subcommand takes `--format` (`table` default, or `json`) and an optional `
| Flag | What it does | Default |
|------|--------------|---------|
| `--status` | `active`, `proposed`, `deprecated`, `superseded`, `dismissed`, `all`. | `all` |
-| `--source` | `adr`, `cli`, `comment`, `commit`, `conventions`, `git_archaeology`, `inline_marker`, `llm_inferred`, `pr`, `session`, `all`. | `all` |
+| `--source` | `adr`, `agent`, `cli`, `comment`, `commit`, `conventions`, `git_archaeology`, `inline_marker`, `llm_inferred`, `pr`, `session`, `all`. | `all` |
| `--proposed` | `--status proposed`. | off |
| `--stale-only` | Only stale. | off |
| `--limit` | Max rows listed. | `100` |
diff --git a/packages/core/src/repowise/core/analysis/decisions/kinds.py b/packages/core/src/repowise/core/analysis/decisions/kinds.py
index f082d6022..daba3ddf2 100644
--- a/packages/core/src/repowise/core/analysis/decisions/kinds.py
+++ b/packages/core/src/repowise/core/analysis/decisions/kinds.py
@@ -31,8 +31,9 @@ __all__ = ["classify_kind"]
#: The sources that mine conversational prose, which is the only place an
#: agreement about conducting the work is ever stated. ``session_discovery``
#: reads the same transcripts through a broader gate, so it sees the same
-#: sentences.
-_PROSE_SOURCES: frozenset[str] = frozenset({"session", "session_discovery"})
+#: sentences. ``agent`` is a coding agent proposing a choice in its own words,
+#: which is where it states how the work is conducted too.
+_PROSE_SOURCES: frozenset[str] = frozenset({"session", "session_discovery", "agent"})
#: Acts of conducting work, grouped by what they name. Each is something a
#: person does to the repository or around it, never something the repository
diff --git a/packages/core/src/repowise/core/analysis/decisions/provenance.py b/packages/core/src/repowise/core/analysis/decisions/provenance.py
index 64b2c4ffd..800af1246 100644
--- a/packages/core/src/repowise/core/analysis/decisions/provenance.py
+++ b/packages/core/src/repowise/core/analysis/decisions/provenance.py
@@ -56,6 +56,7 @@ __all__ = [
SOURCE_RANK: dict[str, int] = {
"cli": 9, # human-authored manual entry — most authoritative
"session": 8, # a user's own words in a transcript, corroborated by them
+ "agent": 8, # proposed directly by a coding agent from its own reasoning
"adr": 7, # architecture decision records (structured, intentional)
"pr": 7, # PR / squash-merge body
"commit": 6, # individual commit message
diff --git a/packages/core/src/repowise/core/persistence/models.py b/packages/core/src/repowise/core/persistence/models.py
index 44840e652..a090471db 100644
--- a/packages/core/src/repowise/core/persistence/models.py
+++ b/packages/core/src/repowise/core/persistence/models.py
@@ -1222,7 +1222,7 @@ class DecisionRecord(Base):
# Provenance
source: Mapped[str] = mapped_column(
String(32), nullable=False, default=DEFAULT_DECISION_SOURCE
- ) # git_archaeology | inline_marker | adr | pr | comment | session | cli
+ ) # git_archaeology | inline_marker | adr | pr | comment | session | agent | cli
evidence_file: Mapped[str | None] = mapped_column(Text, nullable=True)
evidence_line: Mapped[int | None] = mapped_column(Integer, nullable=True)
#: The verbatim span this record's identity is keyed on, written once
diff --git a/packages/types/src/decisions.ts b/packages/types/src/decisions.ts
index 8e88bddd3..d33f12524 100644
--- a/packages/types/src/decisions.ts
+++ b/packages/types/src/decisions.ts
@@ -82,6 +82,7 @@ export function decisionStatusRank(status: string): number {
*/
export const DECISION_SOURCES = [
"adr",
+ "agent",
"cli",
"comment",
"commit",
@@ -122,6 +123,7 @@ export const DECISION_SOURCE_LABELS: Record<
string
> = {
adr: "ADR",
+ agent: "Agent",
cli: "Manual",
comment: "Comment",
commit: "Commit",
diff --git a/packages/ui/src/decisions/decision-detail.tsx b/packages/ui/src/decisions/decision-detail.tsx
index 14823c437..2405f2181 100644
--- a/packages/ui/src/decisions/decision-detail.tsx
+++ b/packages/ui/src/decisions/decision-detail.tsx
@@ -61,6 +61,7 @@ const SOURCE_LABEL: Record<string, string> = {
adr: "ADR",
changelog: "Changelog",
session: "Session",
+ agent: "Agent",
conventions: "Convention",
};
diff --git a/tests/fixtures/decision_vocabulary.json b/tests/fixtures/decision_vocabulary.json
index 763451478..34ed144ab 100644
--- a/tests/fixtures/decision_vocabulary.json
+++ b/tests/fixtures/decision_vocabulary.json
@@ -2,6 +2,7 @@
"_comment": "Generated from the Python decision vocabulary. Checked by tests/unit/analysis/test_decision_vocabulary_contract.py and by packages/types/__tests__/decisions-vocabulary.test.ts, so a source, status, currency, lane or preset added on one side fails on the other.",
"sources": [
"adr",
+ "agent",
"cli",
"comment",
"commit",
diff --git a/tests/unit/analysis/test_decision_provenance.py b/tests/unit/analysis/test_decision_provenance.py
index dc3332731..c834ce47c 100644
--- a/tests/unit/analysis/test_decision_provenance.py
+++ b/tests/unit/analysis/test_decision_provenance.py
@@ -47,6 +47,21 @@ def test_session_outranks_adr():
assert rank_for_source("session") > rank_for_source("adr")
+def test_agent_ranks_with_session():
+ """An agent's own proposal is first-hand reasoning, like a transcript."""
+ from repowise.core.analysis.decisions.provenance import LISTABLE_SOURCES
+
+ assert rank_for_source("agent") == rank_for_source("session") == 8
+ assert "agent" in LISTABLE_SOURCES
+
+
+def test_agent_proposal_is_not_self_authored():
+ """Only a typed ``cli`` record is its own evidence; an agent must cite some."""
+ from repowise.core.analysis.decisions.lifecycle import requirement
+
+ assert not requirement({"source": "agent"}, accepter="reviewer").self_authored
+
+
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
diff --git a/tests/unit/persistence/test_decision_kinds.py b/tests/unit/persistence/test_decision_kinds.py
index fbe58fb0e..c2403aef2 100644
--- a/tests/unit/persistence/test_decision_kinds.py
+++ b/tests/unit/persistence/test_decision_kinds.py
@@ -111,6 +111,7 @@ def test_only_a_prose_source_is_asked():
"""
title, decision = "Never stage all changes", "Do not use `git add -A`."
assert classify_kind(title, decision, source="session") == AGREEMENT_KIND
+ assert classify_kind(title, decision, source="agent") == AGREEMENT_KIND
assert classify_kind(title, decision, source="comment") == ARCHITECTURAL_KIND
assert classify_kind(title, decision, source="pr") == ARCHITECTURAL_KIND
# An unnamed caller gets the kind that keeps being checked, per the module's