feat(risk): add --exclude flag, .riskignore support, and get_change_r… (#867)

* feat(risk): add --exclude flag, .riskignore support, and get_change_risk MCP tool

* Add context to mcp output for agents to better understand the risk priority (percentile over raw corpus risk).

* Update docs & website tool counts.

* fixed benign ruff lint check

Author: barrcodes

docs/CHANGE_RISK.md

@@ -11,12 +11,23 @@ repowise risk                 # score HEAD
 repowise risk abc123          # score a single commit
 repowise risk main..HEAD      # score a branch / PR range as one change
 repowise risk main..HEAD --ext .py        # count only .py files
+repowise risk main..HEAD -x 'tests/' -x '*.spec.ts'  # omit matching paths
 repowise risk --format json               # machine-readable
 ```
 
 It runs in-process: pure `git` + learned constants. **No LLM, no network, and no
 blame at runtime**: SZZ labelling lives entirely in the offline calibration.
 
+## Excluding paths
+
+Use repeatable `--exclude` / `-x` flags with gitignore-style patterns to omit
+files from a score. The same filters apply to the requested change and the
+recent commits sampled for its percentile, so the comparison remains like for
+like. Put project-wide, risk-only rules in a repository-root `.riskignore`;
+those patterns apply automatically and are combined with any command-line
+flags. For example, `tests/` excludes that directory recursively, while
+`test_*.py` excludes matching test filenames anywhere in the repository.
+
 ## What it measures
 
 The model uses Kamei-style *change* metrics (Kamei et al., "A large-scale
@@ -81,6 +92,9 @@ live in `packages/core/src/repowise/core/analysis/change_risk/model.py`.
 
 ## Cross-repo change risk (workspace mode)
 
+> **Note:** This section describes `get_risk` in PR mode (`changed_files`). `get_change_risk` is
+> pure diff-shape scoring and does not access the workspace graph — it produces no cross-repo fields.
+
 In a workspace, a change rarely stops at the repo boundary. When `get_risk` is
 called in PR mode (`changed_files`), its `directive` block gains two cross-repo
 fields derived from the [system graph](WORKSPACES.md#system-graph):

docs/CLI_REFERENCE.md

@@ -386,13 +386,15 @@ to the model's baseline commit, not this repo.
 |------|-------------|
 | `--path` | Path to the git repository (default: current directory) |
 | `--ext` | Comma-separated file suffixes to count (e.g. `.py` or `.ts,.tsx`) |
+| `--exclude` / `-x` | Gitignore-style path pattern to omit. Repeatable; filters both the change and baseline. Root `.riskignore` patterns also apply. |
 | `--baseline` | Recent commits to sample for the repo-relative percentile (default 200; `0` shows only the absolute calibrated band) |
 | `--format` | Output format: `table` (default) or `json` |
 
 ```bash
 repowise risk                 # score HEAD
 repowise risk main..HEAD      # score a branch / PR range as one change
 repowise risk --ext .ts,.tsx  # restrict to specific suffixes
+repowise risk main..HEAD -x 'tests/' -x '*.spec.ts'  # omit tests from scoring
 ```
 
 See [`docs/CHANGE_RISK.md`](./CHANGE_RISK.md) for the scoring model.
@@ -844,7 +846,7 @@ If `PATH` is omitted, `repowise mcp` first walks upward from the current directo
 |------|-------------|
 | `--transport` | `stdio` (default, for editors), `streamable-http` (for HTTP clients), or `sse` (legacy) |
 | `--port` | Port for HTTP/SSE transports (default: 7338) |
-| `--tools` | Override which tools are exposed. A comma-separated list is an explicit allowlist; prefix names with `+`/`-` to adjust the default set (e.g. `+get_dependency_path,-get_dead_code`); `lean` selects the five-tool agent-lean profile. Overrides the `mcp.tools` config block. |
+| `--tools` | Override which tools are exposed. A comma-separated list is an explicit allowlist; prefix names with `+`/`-` to adjust the default set (e.g. `+get_dependency_path,-get_dead_code`); `lean` selects the six-tool agent-lean profile. Overrides the `mcp.tools` config block. |
 | `--all` | Expose every available tool, including opt-in and workspace tools |
 
 ```bash

docs/CONFIG.md

@@ -150,7 +150,7 @@ distill:
 ### The `mcp:` block
 
 Controls which tools the MCP server advertises. The default surface is curated
-(10 tools in single-repo mode, plus 2 workspace-only tools in workspace mode);
+(11 tools in single-repo mode, plus 2 workspace-only tools in workspace mode);
 this block lets you opt extra tools in or trim the set down. The `repowise mcp
 --tools` / `--all` flags override it for a single launch.
 
@@ -165,7 +165,7 @@ mcp:
 - `+name` / `-name` entries add to or remove from the default set; an
   unprefixed list is treated as an explicit allowlist.
 - `lean` selects the agent-lean profile: `get_answer`, `get_context`,
-  `get_symbol`, `search_codebase`, `get_risk` (plus `list_repos` in workspace
+  `get_symbol`, `search_codebase`, `get_risk`, `get_why` (plus `list_repos` in workspace
   mode), small enough that Claude Code can keep every schema always loaded.
 - Opt-in tools are `get_dependency_path`, `get_execution_flows`,
   `generate_refactoring_code`, and `get_conformance` (the last only usable in

docs/MCP_TOOLS.md

@@ -2,7 +2,7 @@
 
 repowise exposes a curated set of tools via the [Model Context Protocol](https://modelcontextprotocol.io) (MCP). These tools give AI coding assistants (Claude Code, Codex, Cursor, Cline, Windsurf) structured access to your codebase intelligence: dependency graph, git history, documentation, and architectural decisions.
 
-16 tools are registered in total. A single-repo server advertises 10 by default: the nine flagship tools below plus `list_repos`. Workspace mode adds 2 more automatically (`get_architecture`, `get_blast_radius`), for 12. Four further tools are off by default everywhere and must be opted in. The surface is configurable; see [Configuring the tool surface](#configuring-the-tool-surface).
+17 tools are registered in total. A single-repo server advertises 11 by default: the ten flagship tools below plus `list_repos`. Workspace mode adds 2 more automatically (`get_architecture`, `get_blast_radius`), for 13. Four further tools are off by default everywhere and must be opted in. The surface is configurable; see [Configuring the tool surface](#configuring-the-tool-surface).
 
 **Start the MCP server:**
 
@@ -16,7 +16,7 @@ repowise mcp --transport sse --port 7338 # legacy SSE transport
 
 ---
 
-## The nine flagship tools
+## The ten flagship tools
 
 | Tool | Purpose | Typical use |
 |------|---------|-------------|
@@ -26,6 +26,7 @@ repowise mcp --transport sse --port 7338 # legacy SSE transport
 | `get_symbol` | Raw source bytes for one symbol | When you need one function/class body |
 | `search_codebase` | Hybrid symbol / path / concept search | Finding a symbol or file, or discovering code by topic |
 | `get_risk` | Modification risk | Before changing hotspot files |
+| `get_change_risk` | Live commit or range risk | Before merging a commit or PR range |
 | `get_why` | Architectural decisions | Before structural changes |
 | `get_dead_code` | Unreachable code | Cleanup tasks |
 | `get_health` | Code-health marker scores | Before refactoring, find the worst files |
@@ -38,8 +39,8 @@ Also always on by default: `list_repos` (repo aliases). See [Supplementary tools
 
 The default surface is deliberately small: fewer, richer tools mean fewer round-trips and less schema overhead per task. What a server advertises is resolved from three things: each tool's `default`/`requires_workspace` metadata, whether the server is in workspace mode, and an optional override.
 
-- **Default (single-repo):** 10 tools, the nine flagship tools plus `list_repos`.
-- **Default (workspace):** those 10 plus `get_architecture` and `get_blast_radius`, added automatically when the server starts inside a workspace. They are never advertised outside one.
+- **Default (single-repo):** 11 tools, the ten flagship tools plus `list_repos`.
+- **Default (workspace):** those 11 plus `get_architecture` and `get_blast_radius`, added automatically when the server starts inside a workspace. They are never advertised outside one.
 - **Opt-in tools:** `get_dependency_path`, `get_execution_flows`, `generate_refactoring_code`, and `get_conformance` are registered but off by default. Turn them on per repo; `get_conformance` only does useful work in workspace mode (name it there).
 
 **Configure it in `.repowise/config.yaml`** under an `mcp.tools` key. Four shapes are supported:
@@ -332,6 +333,41 @@ get_risk(changed_files=["src/api/routes.ts", "src/middleware/cors.ts"])
 
 ---
 
+## `get_change_risk`
+
+Live risk scoring for one commit or a `base..head` range. Unlike `get_risk`,
+which evaluates indexed files and can report blast radius, this scores the
+shape of the live diff and needs no index refresh.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `revspec` | string | No | Commit or `base..head` range to score (default `"HEAD"`) |
+| `repo` | string | No | *(workspace only)* Target repo alias |
+| `extensions` | list[string] | No | File suffixes to count, such as `[".py", ".ts"]` |
+| `exclude_patterns` | list[string] | No | Gitignore-style paths to omit; combined with root `.riskignore` rules |
+| `baseline` | int | No | Recent commits to sample for percentile ranking (default `200`; `0` disables percentile ranking) |
+
+**Returns:** The corpus-calibrated `score`, `probability`, and `level`, plus a
+repo-relative `risk_percentile`, `review_priority`, and `classification`.
+`baseline_sample_size` reports how many filtered commits informed the percentile;
+`features`, `drivers`, and combined `exclude_patterns` make the result auditable.
+Use the percentile and review priority for triage; the raw score is secondary
+context when no repository baseline is available.
+
+**When to use:** Before merging a commit or PR range, especially when you need
+to assess the diff itself rather than the risk of an already-indexed file.
+
+**Example calls:**
+
+```
+get_change_risk()
+get_change_risk(revspec="main..HEAD", extensions=[".py"], exclude_patterns=["tests/"])
+```
+
+---
+
 ## `get_why`
 
 Architectural decision intelligence. Falls back to git archaeology when no decision records exist for a path, and further to a rationale comment mined live from the source when neither decisions nor git history explain the "why".

docs/QUICKSTART.md

@@ -228,7 +228,7 @@ REPOWISE_API_URL=http://localhost:7337 npm run dev --workspace packages/web
 
 - **[User Guide](USER_GUIDE.md)** — full CLI reference, web UI features, MCP setup, common workflows, and troubleshooting
 - **[CLI Reference](CLI_REFERENCE.md)** — every command with every flag
-- **[MCP Tools](MCP_TOOLS.md)** — all 9 MCP tools with parameters and examples
+- **[MCP Tools](MCP_TOOLS.md)** — full tool reference, configuration, parameters, and examples
 - **[Workspaces](WORKSPACES.md)** — multi-repo workspace setup and cross-repo intelligence
 - **[Auto-Sync](AUTO_SYNC.md)** — hooks, file watcher, webhooks, polling
 - **[Architecture](architecture/ARCHITECTURE.md)** — how repowise is built internally

docs/USER_GUIDE.md

@@ -377,7 +377,7 @@ This is how you connect repowise to Claude Code, Cursor, Cline, Windsurf, and ot
 | `--transport` | Protocol: `stdio` (default, for editors), `streamable-http` (for HTTP clients), or `sse` (legacy) |
 | `--port` | Port for HTTP/SSE transports (default: 7338) |
 
-**MCP tools exposed (9 tools):**
+**Default single-repo MCP tools (11 tools):**
 
 | Tool | What it does |
 |------|-------------|
@@ -387,9 +387,11 @@ This is how you connect repowise to Claude Code, Cursor, Cline, Windsurf, and ot
 | `get_symbol` | Raw source bytes for one indexed symbol with exact line bounds (cheaper/safer than `Read` + offset math) |
 | `search_codebase` | Semantic search over wiki with git freshness boosting. In workspace mode, searches across all repos. |
 | `get_risk` | Modification risk assessment, hotspot score, dependents, co-change partners, bus factor, blast radius, test gaps, 0–10 risk score |
+| `get_change_risk` | Live commit or range risk score, ranked against recent commits in the same repository |
 | `get_why` | Why code is structured the way it is, architectural decisions, git archaeology. Three modes: NL search, path-based, health dashboard. |
 | `get_dead_code` | Tiered dead code report grouped by confidence with cleanup impact estimates |
 | `get_health` | 25-marker code-health scores, dashboard KPIs + lowest-scoring files, or per-file findings; `include` for refactoring suggestions and trend alerts |
+| `list_repos` | Repository aliases served by this MCP server |
 
 In workspace mode, tools are workspace-aware, pass `repo="backend"` to target a specific repo or `repo="all"` to query across the entire workspace. The default repo is used when `repo` is omitted.
 

packages/cli/src/repowise/cli/commands/mcp_cmd.py

@@ -91,7 +91,7 @@ def _print_network_startup(
         "Override which tools are exposed. A comma-separated list is an "
         "explicit allowlist; prefix names with + or - to adjust the default "
         "set (e.g. '+get_dependency_path,-get_dead_code'); 'lean' selects "
-        "the five-tool agent-lean profile. Overrides the mcp.tools config "
+        "the six-tool agent-lean profile. Overrides the mcp.tools config "
         "block."
     ),
 )
@@ -112,9 +112,9 @@ def mcp_command(
     """Start the MCP server for editor integration.
 
     Exposes a curated set of tools for querying the repowise wiki via the MCP
-    protocol: ten in single-repo mode, plus three workspace-only tools in
-    workspace mode. Two more (get_dependency_path, get_execution_flows) are
-    opt-in via ``--tools`` or the ``mcp.tools`` config block. Supports stdio
+    protocol: eleven by default in single-repo mode, plus two more by default
+    in workspace mode. Four more are opt-in via ``--tools`` or the
+    ``mcp.tools`` config block. Supports stdio
     (for Claude Code, Codex, Cursor, Cline), streamable HTTP, and legacy SSE
     transports.
 
@@ -127,7 +127,7 @@ def mcp_command(
         repowise mcp                     # stdio, current directory
         repowise mcp /path/to/repo       # stdio, specific repo
         repowise mcp --tools +get_execution_flows  # default set plus one
-        repowise mcp --tools lean        # five-tool agent-lean profile
+        repowise mcp --tools lean        # six-tool agent-lean profile
         repowise mcp --all               # every available tool
         repowise mcp --transport streamable-http  # HTTP on port 7338
     """