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
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.mdindex 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 isthe part that separates a small edit to a fragile file from a large edit to asafe 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 itfixes 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 ofthose fixes replaced (`overlapping_lines`), and how long ago the most recentwas (`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 absentno counted files, when no other branch edits a shared file, and when the scanexceeds 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 ratherthan 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. Tblock needs an index and is absent without one, and it is absent whenever the diffis one change: fewer than two changed files, fewer than two of them eligible to begrouped, 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 notthe repo is indexed: `branch_overlap` reads files on other branches, and thatdiff --git a/docs/layers/BUG_HISTORY.md b/docs/layers/BUG_HISTORY.mdindex 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 manypast fixes it carries and how many of the change's lines fall inside a pastfix's replaced ranges. The per-file counts are exact (counted by`COUNT(DISTINCT fix_sha)`, so one commit fixing three files reports one fix, notdiff --git a/docs/layers/CHANGE_RISK.md b/docs/layers/CHANGE_RISK.mdindex 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 changelands, 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 drivertable, naming each group's files, its bridging files, and the first ten ungroupedpaths; `--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 indexand is absent without one.## Calibration & accuracydiff --git a/packages/core/src/repowise/core/analysis/change_health/service.py b/packages/core/src/repowise/core/analysis/change_health/service.pyindex 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 timefrom collections import OrderedDictfrom dataclasses import dataclass+from ...test_paths import is_test_related_pathfrom ..health import HEALTH_ANALYZER_VERSION, HealthFindingDatafrom ..health.perf.causal import PERFORMANCE_MODEL_VERSIONfrom ..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.findingsif rename.get(f.file_path, f.file_path) in subjectand 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.pyindex 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.pyindex 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_headfrom 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_fixesalias = 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: bopayload.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 blockdiff --git a/packages/types/src/chat.ts b/packages/types/src/chat.tsindex 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.tsxindex 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.tsxindex 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.mdindex 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-MCPtool; it takes a revspec and diffs server-side, so you never shell out. Leadwith `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 thischange overall?" The `repowise risk <revspec>` CLI is the identical scorer forwhen you are already in a terminal.diff --git a/plugins/codex/skills/change-review/SKILL.md b/plugins/codex/skills/change-review/SKILL.mdindex 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-MCPtool; it takes a revspec and diffs server-side, so you never shell out. Leadwith `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 thischange overall?" The `repowise risk <revspec>` CLI is the identical scorer forwhen you are already in a terminal.diff --git a/plugins/shared/skills/change-review.md b/plugins/shared/skills/change-review.mdindex 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-MCPtool; it takes a revspec and diffs server-side, so you never shell out. Leadwith `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 thischange overall?" The `repowise risk <revspec>` CLI is the identical scorer forwhen you are already in a terminal.diff --git a/tests/fixtures/mcp/tool_response_shapes.json b/tests/fixtures/mcp/tool_response_shapes.jsonindex 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.pyindex 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.pyindex 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)) < 8000for 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.pyindex 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, monkeypatcassert [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 payloadasync 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.pyindex 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, massert result["risk_percentile"] is Noneassert result["review_priority"] is Noneassert 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 resultassert "no counted file changes" in result["warning"].lower()+ assert result["scored_repo"]["root"] == str(repo)@pytest.mark.asynciodiff --git a/tests/unit/server/mcp/test_independent_changes_block.py b/tests/unit/server/mcp/test_independent_changes_block.pyindex 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 issilent 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 OmissionCollectorfrom 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, monkeypatcmonkeypatch.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"] == 2assert 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.pyindex 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"] >= 0expected_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.mdindex 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 thefiles 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 notcommitted yet.