composto-ai 0.4.1 → 0.6.0

package/README.md

@@ -46,15 +46,84 @@ composto index --status
 
 ### MCP plugin (Claude Code, Cursor, Claude Desktop)
 
-The MCP server is bundled inside `composto-ai`. Install the package globally first, then register the server:
+The MCP server is bundled inside `composto-ai`. Install the package globally first, then register the server with your client:
 
 ```bash
 npm install -g composto-ai
+```
+
+**Claude Code:**
+
+```bash
 claude mcp add composto -- composto-mcp
 ```
 
+**Cursor** — add to `~/.cursor/mcp.json` (or project-local `.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "composto": {
+      "command": "composto-mcp"
+    }
+  }
+}
+```
+
+Then restart Cursor and verify under Settings → MCP that `composto` is green.
+
+**Claude Desktop** — add the same block to `~/Library/Application Support/Claude/claude_desktop_config.json`.
+
 Composto adds 5 tools to your AI assistant: `composto_ir`, `composto_benchmark`, `composto_context`, `composto_scan`, and `composto_blastradius` (the last one gated by `COMPOSTO_BLASTRADIUS=1` during beta).
 
+#### Cursor: one-command setup
+
+Registering the MCP server only *exposes* the tools — Cursor's agent often defaults to its built-in `read_file` / `codebase_search`. To configure both the MCP server **and** a project rule that tells the agent when to call Composto, run:
+
+```bash
+cd your-project
+composto init
+```
+
+This writes `.cursor/mcp.json` (project-local MCP registration) and `.cursor/rules/composto.mdc` (an `alwaysApply: true` rule that gets injected into every conversation). Existing files are merged, never overwritten. Restart Cursor and check Settings → MCP that `composto` is green.
+
+Without the rule, hit rate is ~30-50%; with it, ~85-95%. The rule template is embedded in [`src/cli/init.ts`](src/cli/init.ts) (`CURSOR_RULES_MDC`) — open the generated `.cursor/rules/composto.mdc` to customize per-project.
+
+#### Hook-enforced injection (v0.6.0+)
+
+Instead of asking the agent to remember to call `composto_blastradius`, wire a hook so it gets consulted **automatically** before every Edit / Write / MultiEdit. The agent receives a `<composto_blastradius>` context block in-line when verdict is `medium` or `high` — you don't do anything, the warning just shows up where it's needed.
+
+```bash
+cd your-project
+composto init --client=claude-code    # or cursor, or gemini-cli
+```
+
+This writes:
+- The platform's MCP config (same as before)
+- A **`PreToolUse` hook** (Claude Code / Gemini CLI) that invokes `composto hook <platform> pretooluse` on every file-targeting tool call. The hook extracts the target file, runs `composto_blastradius`, and injects the verdict as `additionalContext`. Passthrough on `low` verdict — no noise.
+- For Cursor: a `.cursor/hooks.json` entry that **denies** the tool call on `verdict: high` (Cursor's `additional_context` is dropped per [forum #155689](https://forum.cursor.com/t/...), so hybrid strategy — the existing `.cursor/rules/composto.mdc` rule carries `medium`/`low`, the hook only interrupts on `high`).
+
+Existing settings are merged, never overwritten. Re-running `composto init` is idempotent — no duplicate hook entries.
+
+**Observe what's happening:**
+
+```bash
+composto stats            # hook invocations, verdict distribution, p50/p95 latency
+composto stats --json     # machine-readable
+composto stats --disable  # opt out (writes .composto/telemetry-disabled marker)
+```
+
+Telemetry is **local-only** — writes to `.composto/memory.db` in your repo, nothing leaves your machine. No user ID, no cloud sync, no account.
+
+**Platform matrix:**
+
+| Platform | MCP | Hook | Strategy |
+|---|:---:|:---:|---|
+| Claude Code | ✅ | ✅ `PreToolUse` | `additionalContext` on medium\|high\|unknown, passthrough on low |
+| Cursor | ✅ | ✅ `preToolUse` | Deny-on-high via `permissionDecision`; medium/low via `.mdc` rule |
+| Gemini CLI | ✅ | ✅ `BeforeTool` | `additionalContext` on medium\|high\|unknown |
+| Claude Desktop | ✅ | — | MCP-only (no hook API yet) |
+
 ---
 
 ## How It Works
@@ -108,9 +177,9 @@ composto index --status        # diagnostics: schema, freshness, calibration
 
 ## BlastRadius (beta)
 
-Beyond compression, Composto indexes your repo's git history into a local SQLite graph and exposes it as a queryable risk surface. Before your agent edits a file, it can ask: *"has this region been reverted? does it have a fix cluster? is the last author still around?"* — signals no LLM can infer from current code alone.
+Beyond compression, Composto indexes your repo's git history into a local SQLite graph and exposes it as a queryable risk surface. Before your agent edits a file, it can ask: *"has this region been reverted? who fixed the last similar bug? is the last author still around?"* — signals no LLM can infer from current code alone.
 
-Five signals per query: `revert_match`, `hotspot`, `fix_ratio`, `coverage_decline`, `author_churn`. Verdict is `low` / `medium` / `high` / `unknown`; when confidence is low the tool returns `unknown` rather than guessing. Precision is repo-calibrated (self-validation on every N=500 commits).
+Four signals per query: `revert_match`, `hotspot`, `fix_ratio`, `author_churn`. Verdict is `low` / `medium` / `high` / `unknown`; when confidence is low the tool returns `unknown` rather than guessing. Precision is repo-calibrated (self-validation over the repo's own fix history).
 
 ```
 verdict:    high
@@ -122,7 +191,9 @@ signals:
   ...
 ```
 
-**v1 ship gate** on this repo: precision 93.9%, recall 100% on the `medium|high` band. Multi-repo validation pending. See [docs/blastradius-proof.md](docs/blastradius-proof.md) for the method + honest caveats.
+**Where we are, honestly.** The v2.1 time-travel backtest (rewinds the DB to each pre-fix snapshot) shows `revert_match` carrying most of the product's value — it clears the ship gate on picomatch (precision 0.65, recall 0.78 on the `medium|high` band). Signal-attributed precision (excluding `revert_match`) is weaker: the three non-revert signals are alive but need calibration work. See [docs/blastradius-proof-v2.md](docs/blastradius-proof-v2.md) for numbers on all four band combinations across two public repos + the per-signal diagnostic behind them.
+
+The honest framing: **BlastRadius is a bug-history memory layer that agents query before editing.** "This file was reverted three weeks ago" is the primary promise v1 delivers. The other signals expand the query surface — calibration work on `hotspot` and `fix_ratio` is the open follow-on.
 
 Feature-flagged via `COMPOSTO_BLASTRADIUS=1` during the beta. Available as both CLI (`composto impact`, `composto index`) and MCP tool (`composto_blastradius`).
 
@@ -227,9 +298,10 @@ Overall compression: 89.2%
 L0 compression:      97.5%
 AST engine:          51/51 files (0 regex fallback)
 Languages:           TypeScript, JavaScript, Python, Go, Rust
-Tests:               224 passing
-BlastRadius v1:      precision 90-96%, recall 99-100% on 3 repos
-                     (composto, picomatch, zod; medium|high band)
+Tests:               251 passing
+BlastRadius v2.1:    precision 0.65, recall 0.78 (picomatch, time-travel,
+                     medium|high band). Honest signal-attributed numbers
+                     in docs/blastradius-proof-v2.md.
 ```
 
 ---