composto-ai 0.4.1 → 0.6.1

package/README.md

@@ -1,24 +1,23 @@
 # Composto
 
-**Send meaning to your LLM, not code. 89% fewer tokens, same understanding.**
+**Causal memory layer for coding agents. Catches the bug your agent is about to reintroduce.**
 
-Composto parses your code into an AST, classifies every node by importance, and drops the noise. Your LLM gets the signal — function signatures, control flow, dependencies — without the braces, semicolons, and string literals it already knows.
+Composto is a repo-local graph of your git history that your AI coding agent consults before every edit. When a file was reverted recently, has a fix cluster in its history, or was last touched by someone who left the team, Composto surfaces that signal as in-context guidance before the agent writes the code. Hook-enforced on Claude Code, Cursor, and Gemini CLI. Local-first, MIT.
 
 ```
-Raw source:  3,782 tokens    →    Composto IR:  663 tokens (82.5% savings)
-
-USE:[../types.js, ./structure.js, ./fingerprint.js, ./health.js]
-OUT FN:generateL0(code: string, filePath: string)
-    RET `${filePath}\n${declarations.join("\n")}`
-OUT ASYNC FN:generateL1(code: string, filePath: string, health: HealthAnnotation...)
-    IF:health → RET annotateIR(ir, health)
-    RET ir
-OUT FN:generateLayer(layer: IRLayer, options: {...})
-    SWITCH:layer
-        CASE:"L0" → RET generateL0(...)
-        CASE:"L1" → RET generateL1(...)
-        CASE:"L2" → RET generateL2(...)
-        CASE:"L3" → RET options.code
+$ composto impact src/memory/signals/hotspot.ts
+
+verdict:    medium
+score:      0.52
+confidence: 0.50
+signals:
+  revert_match       ■■■■■■■■■■ strength=1.00 precision=1.00
+  hotspot            ■          strength=0.10 precision=0.54
+  fix_ratio          ■          strength=0.07 precision=0.54
+  author_churn       ·          strength=0.00 precision=0.16
+
+# This file was touched by a Revert commit in history.
+# blastradius remembers. Your LLM couldn't.
 ```
 
 ---
@@ -29,32 +28,115 @@ OUT FN:generateLayer(layer: IRLayer, options: {...})
 # Install
 npm install -g composto-ai
 
-# See how much you save
-composto benchmark .
+# One-command setup, wires MCP + PreToolUse hook into your AI client
+cd your-project
+composto init --client=claude-code     # or cursor, or gemini-cli
 
-# Generate IR for a file
-composto ir src/app.ts
+# Restart your AI client. Hook fires on every Edit / Write / MultiEdit.
+# On medium|high|unknown verdicts, the agent gets a composto_blastradius
+# block in context before it acts. Passthrough on low.
 
-# Smart context within a token budget
-composto context src/ --budget 2000
+# Observe
+composto stats              # hook invocations, verdict distribution, latency
+composto stats --disable    # local-only opt-out (writes .composto/telemetry-disabled)
 
-# Historical blast radius for a file (beta, feature-flagged)
-COMPOSTO_BLASTRADIUS=1 composto index
+# Query on demand
 composto impact src/auth/login.ts
-composto index --status
+composto index --status     # diagnostics: schema, freshness, calibration
 ```
 
+### Also in the box: AST compression tools
+
+Composto also ships a tree-sitter based AST compressor (about 89% token savings) and a smart context packer for bug-fix tasks. These are separate from the causal layer but live in the same binary.
+
+```bash
+composto ir src/app.ts                 # compress a file to IR (L0/L1/L2/L3)
+composto context src/ --budget 2000    # smart context within a token budget
+composto benchmark .                   # see compression stats
+```
+
+See the [IR Layers](#ir-layers), [Health-Aware IR](#health-aware-ir), and [Context Budget](#context-budget) sections below for details.
+
 ### 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
@@ -106,11 +188,11 @@ composto index --status        # diagnostics: schema, freshness, calibration
 
 ---
 
-## BlastRadius (beta)
+## BlastRadius
 
-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 +204,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 +311,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.
 ```
 
 ---