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(why): cap git_log at five and state history provenance once per block (#3655)

Swati Ahuja32f9da9e5e7a
diff --git a/docs/reference/MCP_RESPONSE_FIELDS.md b/docs/reference/MCP_RESPONSE_FIELDS.md
index 4f6744086..87893e2ef 100644
--- a/docs/reference/MCP_RESPONSE_FIELDS.md
+++ b/docs/reference/MCP_RESPONSE_FIELDS.md
@@ -286,8 +286,8 @@ Every float is rounded to 4 significant digits. Direct rows' `structural_score`
| `authority` | Per row: `accepted` or `candidate` |
| `currency` | On accepted records: `active`, `needs_review` (files moved, still binds), `uncheckable` (names nothing), `superseded`, `dismissed`. Candidates carry `review_state: "open"` instead |
| `alignment` | Path mode: `active_count`, `deprecated_count`, `uncheckable_count`, `candidate_count`, summing to `governing_count`. `score` comes from `active_count` alone |
-| `git_archaeology` | Present when no decision governs the path |
-| `provenance`, `evidence_refs` | Self-contained evidence references. Matching ids mean shared evidence, not independent corroboration |
+| `git_archaeology` | Present when no decision governs the path. `git_log` keeps its first five rows (the file's newest commits); the rest are recoverable through the omission marker |
+| `provenance`, `evidence_refs` | Self-contained evidence references. Matching ids mean shared evidence, not independent corroboration. Commit rows under `git_archaeology` and `origin_story.key_commits` inherit the block's `provenance` rather than repeating it per row |
Read the lane, not `status`: a record can carry `status: "active"` with no acceptance behind it. Only `repowise decision confirm` or a committed ADR marked accepted produces an acceptance.
diff --git a/packages/server/src/repowise/server/mcp_server/_why_evidence.py b/packages/server/src/repowise/server/mcp_server/_why_evidence.py
index 4692a3fe5..8dba17f10 100644
--- a/packages/server/src/repowise/server/mcp_server/_why_evidence.py
+++ b/packages/server/src/repowise/server/mcp_server/_why_evidence.py
@@ -451,20 +451,26 @@ def _annotate_commit_row(
resolved_commits: Mapping[str, str],
*,
channel: str,
+ inherited: bool = False,
) -> None:
commit = row.get("commit") or row.get("sha") or row.get("subject")
- row["provenance"] = "historical"
ref = commit_reference(
repository,
commit,
resolved_commits=resolved_commits,
- fallback={"channel": channel, "row": row},
+ # Hashed as the row always read, provenance included, so ids hold.
+ fallback={"channel": channel, "row": {**row, "provenance": "historical"}},
)
+ row["evidence_refs"] = [ref]
+ if inherited:
+ # The enclosing block states the provenance once and the lane key
+ # names the channel, so neither repeats per row.
+ return
+ row["provenance"] = "historical"
ref["provenance"] = "historical"
ref["source"] = channel
ref["source_kind"] = channel
ref["verification_basis"] = "historical"
- row["evidence_refs"] = [ref]
def _annotate_origin(
@@ -474,11 +480,14 @@ def _annotate_origin(
records_by_id: Mapping[str, Any],
records_by_title: Mapping[str, list[Any]],
) -> None:
- if origin.get("available"):
+ available = bool(origin.get("available"))
+ if available:
origin["provenance"] = "historical"
for row in origin.get("key_commits") or []:
if isinstance(row, dict):
- _annotate_commit_row(row, repository, resolved_commits, channel="origin")
+ _annotate_commit_row(
+ row, repository, resolved_commits, channel="origin", inherited=available
+ )
for linked in origin.get("linked_decisions") or []:
if not isinstance(linked, dict):
continue
@@ -652,5 +661,9 @@ def _annotate_archaeology(
for row in archaeology.get(key) or []:
if isinstance(row, dict):
_annotate_commit_row(
- row, repository, resolved_commits, channel=f"archaeology:{key}"
+ row,
+ repository,
+ resolved_commits,
+ channel=f"archaeology:{key}",
+ inherited=True,
)
diff --git a/packages/server/src/repowise/server/mcp_server/tool_why/caps.py b/packages/server/src/repowise/server/mcp_server/tool_why/caps.py
index 72b1b6f4b..77173365b 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_why/caps.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_why/caps.py
@@ -111,7 +111,9 @@ def _cap_archaeology(
archaeology: dict[str, Any], collector: OmissionCollector, *, label: str
) -> None:
"""Cap fully annotated archaeology lanes without discarding their tails."""
- for key, cap in (("file_commits", 10), ("cross_references", 10), ("git_log", 20)):
+ # git_log at five, like origin key_commits: its head is the file's own
+ # newest commits, and the tail stays recoverable through the collector.
+ for key, cap in (("file_commits", 10), ("cross_references", 10), ("git_log", 5)):
rows = archaeology.get(key)
if isinstance(rows, list):
cap_collection(
diff --git a/tests/unit/server/mcp/test_why_evidence_contract.py b/tests/unit/server/mcp/test_why_evidence_contract.py
index 5f3089e0b..a029372ee 100644
--- a/tests/unit/server/mcp/test_why_evidence_contract.py
+++ b/tests/unit/server/mcp/test_why_evidence_contract.py
@@ -593,3 +593,46 @@ async def test_no_decision_and_unsupported_modes_remain_compatible(
"Specify a repo alias instead. Available: []"
)
}
+
+
+def test_history_blocks_state_provenance_once_not_per_row() -> None:
+ """Archaeology and origin commits inherit their block's provenance."""
+ sha = "c" * 40
+ payload = {
+ "origin_story": {"available": True, "key_commits": [{"sha": sha}]},
+ "git_archaeology": {
+ "file_commits": [{"sha": sha}],
+ "cross_references": [{"sha": sha}],
+ "git_log": [{"sha": sha, "source": "git_log_follow"}],
+ },
+ "episodes": [{"subject": sha}],
+ }
+ result = annotate_response_evidence(payload, "Repo-A")
+
+ assert result["origin_story"]["provenance"] == "historical"
+ assert result["git_archaeology"]["provenance"] == "historical"
+ rows = [result["origin_story"]["key_commits"][0]] + [
+ result["git_archaeology"][lane][0]
+ for lane in ("file_commits", "cross_references", "git_log")
+ ]
+ for row in rows:
+ assert "provenance" not in row
+ (ref,) = row["evidence_refs"]
+ assert {"provenance", "source", "source_kind", "verification_basis"}.isdisjoint(ref)
+ assert ref["kind"] == "commit"
+ # The row's own git-log channel is data, not a repeated label.
+ assert result["git_archaeology"]["git_log"][0]["source"] == "git_log_follow"
+ # Episodes sit in a bare list with no block to inherit from.
+ assert result["episodes"][0]["evidence_refs"][0]["provenance"] == "historical"
+
+
+def test_git_log_is_capped_at_five_with_the_tail_recoverable(tmp_path) -> None:
+ from repowise.server.mcp_server._budget import OmissionCollector
+ from repowise.server.mcp_server.tool_why.caps import _cap_archaeology
+
+ archaeology = {"git_log": [{"sha": f"{i:012x}"} for i in range(20)]}
+ collector = OmissionCollector("get_why", repo_root=tmp_path)
+ _cap_archaeology(archaeology, collector, label="a.py")
+
+ assert len(archaeology["git_log"]) == 5
+ assert archaeology["git_log_total"] == 20