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(change-risk): report what the change wrote, not what it weighs (#2452)

Raghav Chamadiya45e22d181523
diff --git a/docs/agent/MCP_TOOLS.md b/docs/agent/MCP_TOOLS.md
index 96c0fca70..d77d5d56b 100644
--- a/docs/agent/MCP_TOOLS.md
+++ b/docs/agent/MCP_TOOLS.md
@@ -629,16 +629,19 @@ ranking it against the same measure over the repo's own recent commits. It is
the part that separates a small edit to a fragile file from a large edit to a
safe one. `available` is false when the history walk could not run.
-`change_shape` carries the supporting diff-shape reading: `score`,
-`risk_percentile`, `review_priority`, `classification`, `fallback_band` and
-`is_fix`, which also stay at the top level. `score` is an offline-calibrated
-0-10 output measuring diff size and spread — not a probability, and not where
-the change lands. `fallback_band` appears only when no baseline was available.
+`diff_shape` is one sentence ranking the diff's size against the repo's recent
+commits, alongside the top-level `risk_percentile`, `review_priority`,
+`classification` and `is_fix`. It is size and spread, never a danger verdict.
`working_tree` says whether uncommitted work was the subject.
-`include=["diagnostics"]` adds the raw mechanics: `risk_authority`,
-`score_measures`, `score_unit`, `baseline_sample_size`, `features` and
-`drivers`. `include=["scales"]` adds each field's kind, unit, range,
+The raw 0-10 `score` is not on the wire by default. It ranks 0.99 against lines
+added on every repository measured, so the percentile beside it already carried
+the ranking while the number invited being read as a probability. It remains
+available, with `fallback_band`, behind `include=["diagnostics"]`.
+
+`include=["diagnostics"]` adds the raw mechanics: `score`, `fallback_band`,
+`risk_authority`, `score_measures`, `score_unit`, `baseline_sample_size`,
+`features` and `drivers`. `include=["scales"]` adds each field's kind, unit, range,
calibration and thresholds. Both are identical on every call, so ask once.
It also returns `impacted_tests`, whose `tests_to_run` names the tests the
@@ -677,13 +680,13 @@ followed, and `unresolved_detail` names what failed.
`is_fix` is the defect benchmark's keyword rule read over the commit subject,
not the conventional-commit type, so a `feat:` commit whose subject says it
fixes something reads true; the rule is frozen for comparability rather than
-tuned. `prior_fixes` below is the tuned view: it applies a diff-shape filter on
-top of that rule, counting only commits that actually edited production code.
-`fix_history` above runs the same unfiltered rule, and `prior_fixes` is the one
-block of the three that needs an index.
+tuned. `fix_history.overlap` is the tuned view: it applies a diff-shape filter
+on top of that rule, counting only commits that actually edited production
+code. `fix_history` itself runs the same unfiltered rule, and `overlap` is the
+one part of the three that needs an index.
-When the changed files carry counted bug fixes, the response also holds
-`prior_fixes`: per file, how many past bug-fix commits touched it
+When the changed files carry counted bug fixes, `fix_history.overlap` reports
+per file how many past bug-fix commits touched it
(`fix_count`), how many of the change's lines fall inside the ranges one of
those fixes replaced (`overlapping_lines`), and how long ago the most recent
was (`last_fix_days_ago`). `total_fixes` counts distinct commits, not rows,
@@ -746,7 +749,7 @@ different fact: it reports the branch scan bound, not a cap. The block is absent
no counted files, when no other branch edits a shared file, and when the scan
exceeds its 20-second ceiling or git cannot answer.
-`change_shape.independent_changes` says when the diff is several changes rather
+`independent_changes` says when the diff is several changes rather
than one. It groups the changed files by connectivity, over index edges (imports,
calls, type references, framework and dynamic edges), stored co-change pairs, and,
when `revspec` is a `base..head` range, the files each commit of that range
@@ -773,8 +776,8 @@ recoverable with `repowise expand <ref>`; nothing else in the block is capped. T
block needs an index and is absent without one, and it is absent whenever the diff
is one change: fewer than two changed files, fewer than two of them eligible to be
grouped, or fewer than two groups surviving. Under a response over budget it is
-the first thing shed, ahead of the rest of `change_shape`; `branch_overlap` sheds
-after `prior_fixes` and before `cross_repo`.
+the first thing shed, ahead of `diff_shape`; `branch_overlap` sheds after
+`fix_history` and before `cross_repo`.
The freshness envelope is scoped to the files this change edits, whether or not
the repo is indexed: `branch_overlap` reads files on other branches, and that
diff --git a/docs/layers/BUG_HISTORY.md b/docs/layers/BUG_HISTORY.md
index 4ea2964b7..da98e2eb2 100644
--- a/docs/layers/BUG_HISTORY.md
+++ b/docs/layers/BUG_HISTORY.md
@@ -204,7 +204,7 @@ That does silently reclassify some files: a high-traffic file with 3 fixes in
### `get_change_risk`
-A diff or commit range gains a `prior_fixes` block: per changed file, how many
+A diff or commit range gains a `fix_history.overlap` block: per changed file, how many
past fixes it carries and how many of the change's lines fall inside a past
fix's replaced ranges. The per-file counts are exact (counted by
`COUNT(DISTINCT fix_sha)`, so one commit fixing three files reports one fix, not
diff --git a/docs/layers/CHANGE_RISK.md b/docs/layers/CHANGE_RISK.md
index fa76a09d9..15321a497 100644
--- a/docs/layers/CHANGE_RISK.md
+++ b/docs/layers/CHANGE_RISK.md
@@ -180,7 +180,10 @@ Read the result in this order:
- **`fix_history`**: uncalibrated historical evidence about where the change
lands, reported separately rather than folded into a probability.
- **`score`** (0–10 normalized points): supporting diff size and spread,
- offline-calibrated and corpus-anchored to a single commit.
+ offline-calibrated and corpus-anchored to a single commit. It ranks 0.99
+ against lines added on every repository measured, so `get_change_risk` keeps
+ it behind `include=["diagnostics"]` rather than on the wire; the CLI and the
+ REST range endpoint still report it.
- **`fallback_band`**: the heuristic-thresholded absolute `low` / `moderate` /
`high` model-score band. Present
*only* when there was no baseline to rank against (a shallow repo, or
@@ -300,7 +303,7 @@ no report.
It surfaces in two places. `repowise risk` prints the groups under the driver
table, naming each group's files, its bridging files, and the first ten ungrouped
paths; `--format json` carries the same object under `independent_changes`. In
-`get_change_risk` it is `change_shape.independent_changes`, which needs an index
+`get_change_risk` it is `independent_changes`, which needs an index
and is absent without one.
## Calibration & accuracy
diff --git a/packages/core/src/repowise/core/analysis/change_health/service.py b/packages/core/src/repowise/core/analysis/change_health/service.py
index fba032e22..d6e5860a1 100644
--- a/packages/core/src/repowise/core/analysis/change_health/service.py
+++ b/packages/core/src/repowise/core/analysis/change_health/service.py
@@ -13,6 +13,7 @@ import time
from collections import OrderedDict
from dataclasses import dataclass
+from ...test_paths import is_test_related_path
from ..health import HEALTH_ANALYZER_VERSION, HealthFindingData
from ..health.perf.causal import PERFORMANCE_MODEL_VERSION
from ..health.scoring import ADVISORY_DIMENSION, is_advisory
@@ -51,6 +52,9 @@ _CLAIM_ATTEMPTS = 2
_DIMENSION_ORDER = {"defect": 0, "maintainability": 1, "performance": 2, ADVISORY_DIMENSION: 3}
+#: Bases that place a finding away from the lines the change wrote.
+_INCIDENTAL_BASES = {"file_change", "context_change", "unknown"}
+
@dataclass(frozen=True, slots=True)
class DeltaRequest:
@@ -267,9 +271,12 @@ class ChangeHealthDeltaService:
for f in base_run.findings
if rename.get(f.file_path, f.file_path) in subject
and not is_advisory(f.biomarker_type)
+ and not _is_test_perf(f)
]
head_findings = [
- f for f in head_run.findings_for(subject) if not is_advisory(f.biomarker_type)
+ f
+ for f in head_run.findings_for(subject)
+ if not is_advisory(f.biomarker_type) and not _is_test_perf(f)
]
match = matcher.match(base_findings, head_findings)
@@ -399,18 +406,43 @@ def _limits() -> list[str]:
]
+def _is_test_perf(finding: HealthFindingData) -> bool:
+ """A performance finding on test code.
+
+ The perf model reasons about request-reachable hot paths, which a test file
+ is not, so these are dropped from both sides rather than ranked. Other
+ dimensions still report on tests; only their ordering is demoted.
+ """
+ return finding.dimension == "performance" and is_test_related_path(finding.file_path)
+
+
+def _authorship(finding: ChangeFinding) -> tuple[bool, bool, bool]:
+ """How much of this finding the change actually wrote.
+
+ Ranked ahead of severity because a reader asked "what did I just do" and a
+ capped list answered with the worst thing in a file they only brushed. An
+ incidental basis means the finding sits away from the changed lines; test
+ scaffolding sorts last because it is the change's own noise.
+ """
+ return (
+ finding.attribution_basis in _INCIDENTAL_BASES,
+ is_test_related_path(finding.path),
+ finding.change_kind != "introduced",
+ )
+
+
def _priority(finding: ChangeFinding) -> tuple:
- """Severity first, then dimension, then reach — never defect impact for perf."""
+ """Authorship first, then severity, then dimension and reach."""
if finding.dimension == "performance":
return (
- 0,
+ *_authorship(finding),
-severity_rank(finding.severity),
-(finding.opportunity_rank or 0),
_DIMENSION_ORDER["performance"],
finding.path,
)
return (
- 0,
+ *_authorship(finding),
-severity_rank(finding.severity),
-int((finding.health_impact or 0.0) * 1000),
_DIMENSION_ORDER.get(finding.dimension, 9),
diff --git a/packages/server/src/repowise/server/mcp_server/_budget/contracts.py b/packages/server/src/repowise/server/mcp_server/_budget/contracts.py
index 6cff9f4f6..d83c5288c 100644
--- a/packages/server/src/repowise/server/mcp_server/_budget/contracts.py
+++ b/packages/server/src/repowise/server/mcp_server/_budget/contracts.py
@@ -131,12 +131,13 @@ _CONTRACTS: dict[str, ResponseBudgetContract] = {
# Cheapest loss first. Diff-shape context and history go before the
# delta and the tests, so what to do survives what the diff weighs.
"exclude_patterns",
- "change_shape.independent_changes",
- "change_shape",
+ "independent_changes",
+ "diff_shape",
+ "fix_history.overlap.files[]",
+ "fix_history.overlap",
"fix_history.files[]",
"fix_history.files",
"fix_history",
- "prior_fixes",
"branch_overlap",
"cross_repo",
"impacted_tests",
@@ -149,7 +150,6 @@ _CONTRACTS: dict[str, ResponseBudgetContract] = {
"health_delta",
"classification",
"risk_percentile",
- "score",
),
),
"get_answer": ResponseBudgetContract(
diff --git a/packages/server/src/repowise/server/mcp_server/tool_change_risk.py b/packages/server/src/repowise/server/mcp_server/tool_change_risk.py
index 5f1a2d647..15e3ffbc1 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_change_risk.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_change_risk.py
@@ -57,6 +57,7 @@ from repowise.server.mcp_server._helpers import (
resolve_enum_argument,
)
from repowise.server.mcp_server._meta import build_meta as _build_meta
+from repowise.server.mcp_server._meta import read_live_head
from repowise.server.mcp_server._test_impact import (
_norm,
cross_repo_tests,
@@ -105,6 +106,10 @@ _INCLUDE_BLOCKS = frozenset({"scales", "diagnostics", "findings"})
#: Score mechanics that are identical or near-identical on every call. Moved
#: behind ``include=["diagnostics"]`` so the action-first blocks lead.
+#: ``score`` and ``fallback_band`` sit here rather than on the wire: the score
+#: ranks 0.99 against lines added on every repository measured, so the
+#: percentile beside it already carries the ranking and the raw number only
+#: invited it being read as a danger verdict. Still recoverable, not deleted.
_DIAGNOSTIC_FIELDS = (
"risk_authority",
"score_measures",
@@ -112,16 +117,8 @@ _DIAGNOSTIC_FIELDS = (
"baseline_sample_size",
"features",
"drivers",
-)
-
-#: Compact supporting context: the ranked reading, not the model's workings.
-_CHANGE_SHAPE_FIELDS = (
"score",
- "risk_percentile",
- "review_priority",
- "classification",
"fallback_band",
- "is_fix",
)
@@ -143,21 +140,18 @@ async def get_change_risk(
"""Review a commit, ``base..head`` range, or uncommitted work.
Leads with ``directive`` (what to do) and ``health_delta`` (what this
- change newly made worse across defect, maintainability, and performance).
- Both sides are analysed from their own content, so a finding present at
- head is only reported when the diff explains it; every finding names its
- ``attribution`` basis and confidence.
+ change newly made worse). A finding is reported only when the diff explains
+ it, and each names its ``attribution`` basis; findings the change wrote
+ sort above pre-existing ones it only touched.
Trust ``health_delta.status``: ``partial`` means files were skipped and the
- change is not cleared. ``scope`` counts what was actually compared.
+ change is not cleared.
``impacted_tests`` keeps measured coverage and inferred candidates distinct.
- ``prior_fixes`` counts past fixes overlapping this diff. ``change_shape``
- ranks the diff's size and spread against recent commits.
-
- ``branch_overlap`` names other open branches editing the same files, each
- row stating its basis. ``change_shape.independent_changes`` says when the
- diff is several changes the index does not connect.
+ ``fix_history`` is the changed files' bug-fix record, ``overlap`` the past
+ fixes on these exact lines. ``branch_overlap`` names other branches editing
+ them. ``diff_shape`` is one line on size, not a danger verdict. An empty
+ diff returns ``status: "nothing_to_score"`` and names the tree it read.
Args:
revspec: Commit or ``base..head`` range. Omit to review uncommitted
@@ -203,10 +197,7 @@ async def get_change_risk(
else:
diagnostics = {}
if result.features.nf == 0:
- payload["warning"] = (
- f"No counted file changes in {payload['ref']!r} "
- "(check the revspec, extensions, or exclusion filters)."
- )
+ return await _nothing_to_score(ctx, payload["ref"], started)
# Changed lines over the SAME file universe the score counted (its
# extensions + riskignore + request excludes), so nothing downstream
# disagrees with the score about which files the change touches. Read once
@@ -239,7 +230,10 @@ async def get_change_risk(
)
prior_fixes = await _prior_fixes_block(ctx, changed)
if prior_fixes is not None:
- payload["prior_fixes"] = prior_fixes
+ # One fix record, not two. The blocks answered the same question
+ # with different arithmetic (decayed pressure vs raw count) and a
+ # reader had to work out which was which.
+ payload.setdefault("fix_history", {})["overlap"] = prior_fixes
alias = getattr(ctx, "alias", "")
# The join needs an open index per consumer repo, so it runs once for
# the whole change and the block distributes its rows.
@@ -263,8 +257,10 @@ async def get_change_risk(
await _attach_health_references(ctx, delta)
if finding_id is not None:
return _drill_down(payload, delta, finding_id, revspec)
+ payload["diff_shape"] = _diff_shape_sentence(payload, diagnostics)
+ if independent is not None:
+ payload["independent_changes"] = independent
_attach_health(payload, delta, revspec, expand="findings" in include_set)
- payload["change_shape"] = _change_shape(payload, diagnostics, independent)
# source: live_git marks that the *score* is computed from the working
# checkout's git. The two blocks above are index-backed, so the freshness
# fields do apply to them, scoped to the change's files. None (not []) when
@@ -424,18 +420,43 @@ def _attach_health(payload: dict, delta: Any, revspec: str | None, *, expand: bo
payload.update(ordered)
-def _change_shape(
- payload: dict, diagnostics: dict, independent: dict[str, Any] | None = None
-) -> dict[str, Any]:
- """The ranked diff-shape reading, kept compact and clearly supporting."""
- shape = {f: payload[f] for f in _CHANGE_SHAPE_FIELDS if f in payload}
- shape["measures"] = "diff size and spread, not danger"
- # How many changes this diff is belongs beside its size, not above it.
- if independent is not None:
- shape["independent_changes"] = independent
- if diagnostics:
- shape["diagnostics_via"] = "get_change_risk(include=['diagnostics'])"
- return shape
+async def _nothing_to_score(ctx: Any, ref: str, started: float) -> dict:
+ """An empty diff, reported as one rather than scored.
+
+ Scoring it anyway produced a real-looking "Below typical" verdict, which
+ read as a clean bill of health on a tree the caller had not in fact pointed
+ at. Naming the tree makes a worktree mismatch visible here.
+ """
+ return {
+ "ref": ref,
+ "status": "nothing_to_score",
+ "warning": (
+ f"No counted file changes in {ref!r} "
+ "(check the revspec, extensions, or exclusion filters)."
+ ),
+ "scored_repo": {"root": str(ctx.path), "head": read_live_head(str(ctx.path))},
+ "_meta": _build_meta(
+ timing_ms=(time.perf_counter() - started) * 1000,
+ repository=await _repository(ctx),
+ extra={"source": "live_git"},
+ ),
+ }
+
+
+def _diff_shape_sentence(payload: dict, diagnostics: dict) -> str:
+ """One line for what the diff-shape rank says, and what it does not.
+
+ It replaced a block that restated four fields already at the top level and
+ was read in 2 of 118 recorded calls.
+ """
+ pct = payload.get("risk_percentile")
+ where = (
+ f"bigger than {round(pct)}% of this repo's recent commits"
+ if pct is not None
+ else "unranked (no baseline to compare against)"
+ )
+ tail = " Mechanics: get_change_risk(include=['diagnostics'])." if diagnostics else ""
+ return f"Diff shape: {where}. Size and spread, not danger.{tail}"
def _drill_down(payload: dict, delta: Any, finding_id: str, revspec: str | None) -> dict:
@@ -944,7 +965,7 @@ async def _independent_changes_block(
_UNGROUPED_FILES_LIMIT,
collector,
label=(
- f"change_shape.independent_changes.ungrouped_files beyond cap={_UNGROUPED_FILES_LIMIT}"
+ f"independent_changes.ungrouped_files beyond cap={_UNGROUPED_FILES_LIMIT}"
),
)
return block
diff --git a/packages/types/src/chat.ts b/packages/types/src/chat.ts
index c5ed1f859..a7343ea57 100644
--- a/packages/types/src/chat.ts
+++ b/packages/types/src/chat.ts
@@ -272,15 +272,14 @@ export interface RiskReportArtifactData {
/** `get_change_risk` action-first blocks. */
directive?: ChangeRiskDirective;
health_delta?: ChangeHealthDeltaData;
- change_shape?: {
- independent_changes?: {
- count?: number;
- summary?: string;
- basis?: string;
- ungrouped_files?: string[];
- groups?: Array<{ files: string[]; bridging_files?: string[] }>;
- [k: string]: unknown;
- };
+ /** One line on diff size and spread; never a danger verdict. */
+ diff_shape?: string;
+ independent_changes?: {
+ count?: number;
+ summary?: string;
+ basis?: string;
+ ungrouped_files?: string[];
+ groups?: Array<{ files: string[]; bridging_files?: string[] }>;
[k: string]: unknown;
};
impacted_tests?: { tests_to_run?: string[]; status?: string; summary?: string };
@@ -288,8 +287,8 @@ export interface RiskReportArtifactData {
fix_history?: {
available?: boolean;
files?: Array<{ path: string; churn: number; fix_pressure: number }>;
+ overlap?: { files_with_fixes?: number; total_fixes?: number };
};
- prior_fixes?: { files_with_fixes?: number; total_fixes?: number };
/** Other open branches editing the files this change edits. */
branch_overlap?: {
base?: string;
diff --git a/packages/ui/__tests__/chat/change-risk-artifact.test.tsx b/packages/ui/__tests__/chat/change-risk-artifact.test.tsx
index d7df5bd94..7ed8ef8a0 100644
--- a/packages/ui/__tests__/chat/change-risk-artifact.test.tsx
+++ b/packages/ui/__tests__/chat/change-risk-artifact.test.tsx
@@ -23,7 +23,7 @@ const finding = {
const data: RiskReportArtifactData = {
ref: "HEAD",
- score: 6.4,
+ diff_shape: "Diff shape: bigger than 82% of this repo's recent commits.",
risk_percentile: 82,
review_priority: "Elevated",
classification: "Higher-risk than most recent commits",
@@ -96,15 +96,16 @@ describe("change risk artifact", () => {
expect(screen.getByText("42 changes")).toBeInTheDocument();
});
- it("demotes the diff-shape score behind progressive disclosure", () => {
+ it("states the diff shape in words, with no raw score", () => {
render(<RiskReportRenderer data={data} />);
// The ranked reading stays in the compact context row...
expect(screen.getByText("p82")).toBeInTheDocument();
- // ...while the raw model score is inside the collapsed section.
+ // ...and the sentence replaces the raw 0-10 the renderer used to show.
const disclosure = screen.getByText("More detail");
expect(disclosure.closest("details")).not.toBeNull();
- expect(screen.getByText("Diff-shape score")).toBeInTheDocument();
+ expect(screen.getByText(/bigger than 82%/)).toBeInTheDocument();
+ expect(screen.queryByText("Diff-shape score")).toBeNull();
});
it("announces a partial comparison as a live status, not a clean result", () => {
@@ -145,7 +146,7 @@ describe("change risk artifact", () => {
it("still renders a legacy payload that has no delta", () => {
render(
<RiskReportRenderer
- data={{ ref: "HEAD", score: 3.1, risk_percentile: 40, review_priority: "Normal" }}
+ data={{ ref: "HEAD", risk_percentile: 40, review_priority: "Normal" }}
/>,
);
diff --git a/packages/ui/src/chat/artifacts.tsx b/packages/ui/src/chat/artifacts.tsx
index c6796f063..55c463d2f 100644
--- a/packages/ui/src/chat/artifacts.tsx
+++ b/packages/ui/src/chat/artifacts.tsx
@@ -477,8 +477,10 @@ function ChangeRiskCard({ data }: { data: RiskReportArtifactData }) {
)}
</div>
)}
- {typeof data.score === "number" && (
- <StatRow label="Diff-shape score" value={data.score.toFixed(1)} />
+ {data.diff_shape && (
+ <p className="text-[10px] text-[var(--color-text-tertiary)]">
+ {String(data.diff_shape)}
+ </p>
)}
{data.classification && (
<p className="text-[10px] text-[var(--color-text-tertiary)]">
diff --git a/plugins/claude-code/skills/change-review/SKILL.md b/plugins/claude-code/skills/change-review/SKILL.md
index f08c97575..748ce629c 100644
--- a/plugins/claude-code/skills/change-review/SKILL.md
+++ b/plugins/claude-code/skills/change-review/SKILL.md
@@ -18,15 +18,14 @@ architectural decisions that govern the touched code.
Two complementary risk signals, use both:
- **`get_change_risk(revspec=…)` (MCP)** scores the *whole change as one unit* (a
- commit or a `base..head` range) from its diff shape: a single 0-10 defect-risk
- score with drivers (lines added/deleted, files, directories, subsystems,
- change entropy, author familiarity). No LLM, no network. Prefer this in-MCP
+ commit or a `base..head` range). No LLM, no network. Prefer this in-MCP
tool; it takes a revspec and diffs server-side, so you never shell out. Lead
with `directive` and `health_delta` — what the change actually made worse.
+ Findings the change wrote sort above pre-existing ones it only touched.
Then `risk_percentile` (this change ranked against sampled recent commits),
- summarized by `review_priority` and `classification`. `score` is calibrated
- per single commit, so a PR-sized change reads high by construction, and
- `fallback_band` appears only when there was no baseline to rank against.
+ summarized by `review_priority` and `classification`. The raw 0-10 `score`
+ ranks 0.99 against lines added, so it sits behind `include=["diagnostics"]`
+ rather than on the wire; `diff_shape` states the ranking in one line.
Omit `revspec` to score uncommitted work. This is the pre-merge gate: "how risky is this
change overall?" The `repowise risk <revspec>` CLI is the identical scorer for
when you are already in a terminal.
diff --git a/plugins/codex/skills/change-review/SKILL.md b/plugins/codex/skills/change-review/SKILL.md
index 923b19951..a1cd33a51 100644
--- a/plugins/codex/skills/change-review/SKILL.md
+++ b/plugins/codex/skills/change-review/SKILL.md
@@ -13,15 +13,14 @@ architectural decisions that govern the touched code.
Two complementary risk signals, use both:
- **`get_change_risk(revspec=…)` (MCP)** scores the *whole change as one unit* (a
- commit or a `base..head` range) from its diff shape: a single 0-10 defect-risk
- score with drivers (lines added/deleted, files, directories, subsystems,
- change entropy, author familiarity). No LLM, no network. Prefer this in-MCP
+ commit or a `base..head` range). No LLM, no network. Prefer this in-MCP
tool; it takes a revspec and diffs server-side, so you never shell out. Lead
with `directive` and `health_delta` — what the change actually made worse.
+ Findings the change wrote sort above pre-existing ones it only touched.
Then `risk_percentile` (this change ranked against sampled recent commits),
- summarized by `review_priority` and `classification`. `score` is calibrated
- per single commit, so a PR-sized change reads high by construction, and
- `fallback_band` appears only when there was no baseline to rank against.
+ summarized by `review_priority` and `classification`. The raw 0-10 `score`
+ ranks 0.99 against lines added, so it sits behind `include=["diagnostics"]`
+ rather than on the wire; `diff_shape` states the ranking in one line.
Omit `revspec` to score uncommitted work. This is the pre-merge gate: "how risky is this
change overall?" The `repowise risk <revspec>` CLI is the identical scorer for
when you are already in a terminal.
diff --git a/plugins/shared/skills/change-review.md b/plugins/shared/skills/change-review.md
index 9839bfdee..b9bdd4593 100644
--- a/plugins/shared/skills/change-review.md
+++ b/plugins/shared/skills/change-review.md
@@ -26,15 +26,14 @@ architectural decisions that govern the touched code.
Two complementary risk signals, use both:
- **`get_change_risk(revspec=…)` (MCP)** scores the *whole change as one unit* (a
- commit or a `base..head` range) from its diff shape: a single 0-10 defect-risk
- score with drivers (lines added/deleted, files, directories, subsystems,
- change entropy, author familiarity). No LLM, no network. Prefer this in-MCP
+ commit or a `base..head` range). No LLM, no network. Prefer this in-MCP
tool; it takes a revspec and diffs server-side, so you never shell out. Lead
with `directive` and `health_delta` — what the change actually made worse.
+ Findings the change wrote sort above pre-existing ones it only touched.
Then `risk_percentile` (this change ranked against sampled recent commits),
- summarized by `review_priority` and `classification`. `score` is calibrated
- per single commit, so a PR-sized change reads high by construction, and
- `fallback_band` appears only when there was no baseline to rank against.
+ summarized by `review_priority` and `classification`. The raw 0-10 `score`
+ ranks 0.99 against lines added, so it sits behind `include=["diagnostics"]`
+ rather than on the wire; `diff_shape` states the ranking in one line.
Omit `revspec` to score uncommitted work. This is the pre-merge gate: "how risky is this
change overall?" The `repowise risk <revspec>` CLI is the identical scorer for
when you are already in a terminal.
diff --git a/tests/fixtures/mcp/tool_response_shapes.json b/tests/fixtures/mcp/tool_response_shapes.json
index 41165444a..e2d065c25 100644
--- a/tests/fixtures/mcp/tool_response_shapes.json
+++ b/tests/fixtures/mcp/tool_response_shapes.json
@@ -125,15 +125,21 @@
"contract_version": null,
"embedder_degraded": null,
"index_age_days": null,
- "indexed_commit": null,
- "omitted": {
- "refs": [
- null
- ],
- "restore": null,
- "tokens": null
+ "index_behind": null,
+ "index_scope": {
+ "content_provenance": null,
+ "fingerprint": null,
+ "full": null,
+ "git_tier": null,
+ "projection": null,
+ "run_mode": null,
+ "status": null,
+ "version": null
},
+ "indexed_commit": null,
+ "live_head": null,
"source": null,
+ "stale_warning": null,
"timing_ms": null
},
"branch_overlap": {
@@ -146,8 +152,7 @@
"files": [
{
"basis": null,
- "file": null,
- "partner": null
+ "file": null
}
],
"last_commit": null
@@ -159,30 +164,17 @@
"total": null,
"truncated": null
},
- "change_shape": {
- "classification": null,
- "diagnostics_via": null,
- "independent_changes": null,
- "fallback_band": null,
- "is_fix": null,
- "measures": null,
- "review_priority": null,
- "risk_percentile": null,
- "score": null
- },
"classification": null,
+ "diff_shape": null,
"directive": {
"headline": null,
"next_actions": [
null
],
- "reasons": [
- null
- ],
+ "reasons": [],
"status": null
},
"exclude_patterns": [],
- "fallback_band": null,
"fix_history": {
"available": null,
"density": null,
@@ -193,6 +185,24 @@
"path": null
}
],
+ "overlap": {
+ "changed_lines_in_fixed_files": null,
+ "files": [
+ {
+ "changed_lines": null,
+ "file_path": null,
+ "fix_count": null,
+ "last_fix_days_ago": null,
+ "overlapping_lines": null,
+ "share_of_change": null
+ }
+ ],
+ "files_with_fixes": null,
+ "line_overlap": null,
+ "summary": null,
+ "total_fixes": null,
+ "truncated": null
+ },
"percentile": null
},
"health_delta": {
@@ -257,29 +267,9 @@
"truncated": null
},
"is_fix": null,
- "omission_marker": null,
- "prior_fixes": {
- "changed_lines_in_fixed_files": null,
- "files": [
- {
- "changed_lines": null,
- "file_path": null,
- "fix_count": null,
- "last_fix_days_ago": null,
- "overlapping_lines": null,
- "share_of_change": null
- }
- ],
- "files_with_fixes": null,
- "line_overlap": null,
- "summary": null,
- "total_fixes": null,
- "truncated": null
- },
"ref": null,
"review_priority": null,
"risk_percentile": null,
- "score": null,
"working_tree": null
},
"get_conformance": {
diff --git a/tests/unit/change_health/test_comparison.py b/tests/unit/change_health/test_comparison.py
index 148965514..a5d30a218 100644
--- a/tests/unit/change_health/test_comparison.py
+++ b/tests/unit/change_health/test_comparison.py
@@ -228,6 +228,76 @@ def test_findings_are_ordered_by_severity_not_by_dimension(make_repo):
assert severities == sorted(severities, key=lambda s: -ranks[s])
+def _finding(**kw):
+ from repowise.core.analysis.change_health.models import ChangeFinding
+
+ base = dict(
+ change_finding_id="id",
+ change_kind="introduced",
+ dimension="defect",
+ biomarker_type="complexity",
+ severity="low",
+ path="app.py",
+ symbol="f",
+ line_start=1,
+ line_end=2,
+ reason="r",
+ attribution_basis="added_lines",
+ attribution_confidence="high",
+ attribution_detail="d",
+ suggestion="",
+ follow_up="",
+ )
+ base.update(kw)
+ return ChangeFinding(**base)
+
+
+def test_what_the_change_wrote_outranks_what_it_only_touched():
+ """A capped list must not spend its slots on pre-existing problems."""
+ from repowise.core.analysis.change_health.service import _priority
+
+ mine = _finding(severity="low", attribution_basis="added_lines")
+ inherited = _finding(
+ severity="critical", attribution_basis="file_change", change_kind="worsened"
+ )
+ scaffolding = _finding(severity="high", path="tests/test_app.py")
+
+ assert sorted([inherited, mine], key=_priority) == [mine, inherited]
+ assert sorted([scaffolding, mine], key=_priority) == [mine, scaffolding]
+ assert sorted([inherited, scaffolding], key=_priority) == [scaffolding, inherited]
+
+
+def test_a_performance_finding_on_test_code_is_not_reported(make_repo):
+ """The perf model reasons about request-reachable paths; a test is not one."""
+ repo = make_repo()
+ repo.commit("seed", {"tests/test_app.py": python_io_in_loop(in_loop=False)})
+ repo.commit("loop", {"tests/test_app.py": python_io_in_loop(in_loop=True)})
+
+ delta = compare(repo)
+
+ assert not [f for f in delta.findings if f.dimension == "performance"], [
+ (f.path, f.biomarker_type) for f in delta.findings
+ ]
+
+
+def test_test_file_findings_sort_below_source_findings(make_repo):
+ repo = make_repo()
+ repo.commit("seed", {"app.py": "x = 1\n", "tests/test_app.py": "y = 1\n"})
+ repo.commit(
+ "add",
+ {
+ "app.py": python_complex("source", 14),
+ "tests/test_app.py": python_complex("scaffolding", 26),
+ },
+ )
+
+ delta = compare(repo)
+ in_tests = [f.path.startswith("tests/") for f in delta.findings]
+
+ assert any(in_tests) and not all(in_tests), "fixture must produce both kinds"
+ assert in_tests == sorted(in_tests), [(f.path, f.severity) for f in delta.findings]
+
+
# -- honesty ----------------------------------------------------------------
diff --git a/tests/unit/change_health/test_mcp_contract.py b/tests/unit/change_health/test_mcp_contract.py
index 1cae7bb6b..021d121f1 100644
--- a/tests/unit/change_health/test_mcp_contract.py
+++ b/tests/unit/change_health/test_mcp_contract.py
@@ -60,7 +60,7 @@ async def test_the_default_response_stays_small_and_omits_score_mechanics(tool,
assert len(json.dumps(result, default=str)) < 8000
for field in ("drivers", "risk_authority", "features", "score_measures", "score_unit"):
assert field not in result
- assert result["change_shape"]["diagnostics_via"] == ("get_change_risk(include=['diagnostics'])")
+ assert "get_change_risk(include=['diagnostics'])" in result["diff_shape"]
async def test_diagnostics_are_a_projection_not_a_removal(tool, make_repo):
@@ -68,7 +68,7 @@ async def test_diagnostics_are_a_projection_not_a_removal(tool, make_repo):
expanded = await module.get_change_risk("HEAD", baseline=0, include=["diagnostics"])
- for field in ("drivers", "risk_authority", "features", "score_measures"):
+ for field in ("drivers", "risk_authority", "features", "score_measures", "score"):
assert field in expanded
@@ -78,10 +78,21 @@ async def test_legacy_ranked_fields_stay_at_the_top_level(tool, make_repo):
result = await module.get_change_risk("HEAD", baseline=0)
- for field in ("ref", "score", "risk_percentile", "review_priority", "classification"):
+ for field in ("ref", "risk_percentile", "review_priority", "classification"):
assert field in result
+async def test_the_raw_score_is_not_on_the_wire_by_default(tool, make_repo):
+ """It ranks 0.99 against lines added, so the percentile already says it."""
+ module = tool(seeded(make_repo))
+
+ result = await module.get_change_risk("HEAD", baseline=0)
+
+ assert "score" not in result
+ assert "fallback_band" not in result
+ assert "change_shape" not in result
+
+
async def test_the_top_findings_cap_is_recoverable(tool, make_repo):
repo = make_repo()
repo.commit("seed", {"app.py": "x = 1\n"})
diff --git a/tests/unit/server/mcp/test_branch_overlap_block.py b/tests/unit/server/mcp/test_branch_overlap_block.py
index a705966f6..328c6cd84 100644
--- a/tests/unit/server/mcp/test_branch_overlap_block.py
+++ b/tests/unit/server/mcp/test_branch_overlap_block.py
@@ -218,9 +218,9 @@ def test_branch_overlap_participates_in_the_response_ceiling(tmp_path):
# Shed after the fix record and before the consumer list: who else is in
# these files outlives what the diff weighs and is cheaper than what breaks.
- assert _SHED_ORDER.index("prior_fixes") < _SHED_ORDER.index("branch_overlap")
+ assert _SHED_ORDER.index("fix_history") < _SHED_ORDER.index("branch_overlap")
assert _SHED_ORDER.index("branch_overlap") < _SHED_ORDER.index("cross_repo")
- assert _SHED_ORDER.index("change_shape.independent_changes") < _SHED_ORDER.index("change_shape")
+ assert _SHED_ORDER.index("fix_history.overlap") < _SHED_ORDER.index("fix_history")
payload = {
"score": 7.0,
@@ -248,7 +248,7 @@ async def test_get_change_risk_carries_the_block_end_to_end(tmp_path, monkeypatc
assert [e["branch"] for e in payload["branch_overlap"]["branches"]] == ["overlapping"]
# No index, so the diff is never split into changes the index cannot see.
- assert "independent_changes" not in payload["change_shape"]
+ assert "independent_changes" not in payload
async def test_reading_other_branches_does_not_widen_the_response_targets(tmp_path, monkeypatch):
diff --git a/tests/unit/server/mcp/test_change_risk.py b/tests/unit/server/mcp/test_change_risk.py
index bbc63deda..e84a56646 100644
--- a/tests/unit/server/mcp/test_change_risk.py
+++ b/tests/unit/server/mcp/test_change_risk.py
@@ -87,7 +87,7 @@ async def test_get_change_risk_honors_riskignore_and_request_filters(tmp_path, m
assert result["risk_percentile"] is None
assert result["review_priority"] is None
assert result["classification"] is None
- assert result["fallback_band"] in {"low", "moderate", "high"}
+ assert diagnostics["fallback_band"] in {"low", "moderate", "high"}
assert diagnostics["baseline_sample_size"] == 0
# The per-field dictionary is identical on every call, so it is opt-in.
assert "risk_scales" not in result
@@ -142,9 +142,10 @@ async def test_get_change_risk_empty_diff_warns(tmp_path, monkeypatch) -> None:
# Only a .py change exists; restricting to .md counts zero files.
result = await module.get_change_risk(extensions=["md"], baseline=0)
- assert result["change_shape"]["score"] is not None
- assert "warning" in result
+ assert result["status"] == "nothing_to_score"
+ assert "score" not in result
assert "no counted file changes" in result["warning"].lower()
+ assert result["scored_repo"]["root"] == str(repo)
@pytest.mark.asyncio
diff --git a/tests/unit/server/mcp/test_independent_changes_block.py b/tests/unit/server/mcp/test_independent_changes_block.py
index 93c9ee450..cd65fb219 100644
--- a/tests/unit/server/mcp/test_independent_changes_block.py
+++ b/tests/unit/server/mcp/test_independent_changes_block.py
@@ -1,4 +1,4 @@
-"""get_change_risk's change_shape.independent_changes block.
+"""get_change_risk's independent_changes block.
The block says a diff is several changes the index does not connect. It is
silent without an index, for a single changed file, and whenever the changed
@@ -16,7 +16,7 @@ from repowise.core.persistence.models import GraphEdge, GraphNode, Repository, _
from repowise.server.mcp_server._budget import OmissionCollector
from repowise.server.mcp_server.tool_change_risk import (
_UNGROUPED_FILES_LIMIT,
- _change_shape,
+ _diff_shape_sentence,
_independent_changes_block,
)
@@ -221,13 +221,12 @@ async def test_get_change_risk_carries_the_split_end_to_end(tmp_path, monkeypatc
monkeypatch.setattr(module, "_resolve_repo_context", _context)
payload = await module.get_change_risk("HEAD", baseline=0)
- split = payload["change_shape"]["independent_changes"]
+ split = payload["independent_changes"]
assert split["count"] == 2
assert sorted(g["files"] for g in split["groups"]) == [["a.py"], ["b.py"]]
-def test_change_shape_carries_the_block_only_when_there_is_one():
- payload = {"score": 3.0, "classification": "moderate"}
- assert "independent_changes" not in _change_shape(payload, {})
- shape = _change_shape(payload, {}, {"count": 2})
- assert shape["independent_changes"] == {"count": 2}
+def test_the_diff_shape_line_ranks_without_naming_a_raw_score():
+ assert "42%" in _diff_shape_sentence({"risk_percentile": 42.0}, {})
+ assert "unranked" in _diff_shape_sentence({"risk_percentile": None}, {})
+ assert "diagnostics" in _diff_shape_sentence({"risk_percentile": 42.0}, {"score": 3.0})
diff --git a/tests/unit/server/test_mcp_workspace.py b/tests/unit/server/test_mcp_workspace.py
index 08315e640..c70b826c5 100644
--- a/tests/unit/server/test_mcp_workspace.py
+++ b/tests/unit/server/test_mcp_workspace.py
@@ -954,7 +954,9 @@ async def test_list_repos_discovers_workspace_aliases(workspace_mcp):
assert probe in json.dumps(answer)
change = await get_change_risk("HEAD", repo=identity, baseline=0)
assert change.get("warning") is None
- assert change["score"] >= 0
+ # The raw score is behind include=["diagnostics"] now; the
+ # percentile is what the default payload ranks with.
+ assert change["risk_percentile"] is None or change["risk_percentile"] >= 0
expected_head = subprocess.run(
["git", "rev-parse", "--short=12", "HEAD"],
cwd=workspace_mcp.workspace_root / emitted["path"],
diff --git a/website/mcp-server.md b/website/mcp-server.md
index c957332ed..e2635166e 100644
--- a/website/mcp-server.md
+++ b/website/mcp-server.md
@@ -374,16 +374,14 @@ refresh.
the benchmarked, population-relative authority for live change review.
`fix_history` reports the recency-weighted bug-fix record of the
files touched, which is what distinguishes a small dangerous change from a large
-boring one. The supporting `score` is an offline-calibrated 0-10 diff-size and
-spread output, not a probability (see `score_measures`), with
-the `score_unit` it is calibrated on, repo-relative `risk_percentile` /
-`review_priority` / `classification` for that diff shape, a `fallback_band` when
-there was no baseline to rank against, plus `impacted_tests` when a per-test
-coverage map is ingested (`repowise coverage add`). `risk_authority` names the
-field to act on; `include=["scales"]` supplies the kind, units, range,
-calibration, authority, and shared thresholds for each value. `fallback_band`
-is an absolute per-commit classification, not the population-relative
-percentile classification.
+boring one. `diff_shape` is one sentence on size and spread, beside repo-relative
+`risk_percentile` / `review_priority` / `classification`, plus
+`impacted_tests` when a per-test coverage map is ingested
+(`repowise coverage add`). The raw 0-10 `score` and its absolute
+`fallback_band` sit behind `include=["diagnostics"]`: the score ranks 0.99
+against lines added, so the percentile already carries the ranking.
+`include=["scales"]` supplies the kind, units, range, calibration, authority
+and shared thresholds for each value.
**When to use:** Before merging a commit or PR range, or on work you have not
committed yet.