# 🕸️ RECLUSE

[![npm](https://img.shields.io/npm/v/recluse-mcp)](https://www.npmjs.com/package/recluse-mcp)

**An autonomous detect→fix→verify loop for the bugs that hide in your system's seams.** MCP server + GitHub Action + a shared bug-corpus.

> The recluse bites the bugs that hide in the seams.

When you vibe-code, writing is fast but debugging is slow — you didn't write the code, so you don't know where it broke. And the bugs that actually bite in production usually aren't in one file; they live in the **seams** between subsystems: a value written in cents and read as dollars, an auth check that passes on NULL, an RLS policy that leaks every row, a SECURITY DEFINER function anyone can call because the grant went to PUBLIC.

RECLUSE traces those seams (producer → store → consumer), catches the mismatch with **live evidence**, dispatches a fixer, re-verifies — then pools every caught pattern into a shared corpus so the next project catches the same trap at round-zero.

→ **Live page & corpus:** https://eduverse-ai.app/recluse

---

## What it does — a closed loop

```
WEB (detect) → CATCH (contract mismatch) → SPIDER (autonomous fix) → RE-WEAVE (verify) → loop until 🔴 = 0
```

- **WEB** — fan out read-only QC agents with different viewpoints (security, data/payment, integration contracts). One reviewer's blind spot is another's catch.
- **CATCH** — where a producer/consumer contract tears, report it with the exact coordinate (`file:line`, constraint, RLS policy) and a severity.
- **SPIDER** — dispatch a fixer agent per finding into an isolated git worktree; several fix in parallel without collision. Only the orchestrator merges — detectors stay read-only.
- **RE-WEAVE** — re-run the fixed strand *and its neighbors* to prove no regression. Loop until clean.

The orchestration (fan-out, dedup, dispatch, re-weave) is deterministic code — a plain loop, not model-driven. Only the spiders (detect/fix) are LLM calls.

### What it caught (real, on a live app)

Run against a production Next.js + Supabase/Postgres app, it found privilege-escalation bugs a static review had passed:

- a **SECURITY DEFINER function callable by anon**, because `REVOKE EXECUTE ... FROM anon` is a no-op when the grant is to PUBLIC;
- a **plpgsql guard bypassed by NULL three-valued logic** — `NULL OR false` is NULL, which `IF NOT` treats as false, so the guard's exception never fired;
- a **SECURITY DEFINER view** that let anon write through it, bypassing RLS on the base table.

All three only reproduced against a live endpoint — reading the source called them safe.
Each is now a built-in detection **signal** (`spider_signals`) with the exact query to
reproduce it — alongside curriculum order-integrity (band inversion / cyclic
prerequisites), per-user-limit anonymous farming, stream-budget 502s, and
event producer↔consumer contract drift.

---

## Quickstart

### ① MCP server — for your editor (Claude, Cursor, any MCP client)

One line, no clone — published on npm:

```json
{ "mcpServers": { "recluse": {
  "command": "npx",
  "args": ["-y", "recluse-mcp"],
  "env": { "SPIDER_CORPUS_API": "https://eduverse-ai.app/api/corpus" }
} } }
```

**Tools:** `spider_plan` · `spider_classify_tier` · `spider_checklist` · `spider_signals` (detection query/grep per bug class) · `spider_record_pattern` (local + shared contribution) · `spider_pull_corpus` (collective pull, verified-first).
**Resources:** `spider://checklist` · `spider://queries` · `spider://corpus` · `spider://blackbox`.

Knowledge is **built into the server** — the checklist, contract queries, and a seed
corpus of live-verified bug classes ship inside the package, so it works standalone. If
you also run the [spiderweb-qc skill](https://eduverse-ai.app/recluse), its richer
reference files are picked up automatically (set `SPIDER_REF_DIR`).

### ② GitHub Action — gate every PR (blocks on 🔴)

```yaml
# .github/workflows/recluse.yml
name: RECLUSE
on:
  pull_request:
    branches: [main]
jobs:
  weave:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - uses: vinsenzo83/recluse@v1.1
        with: { base: origin/${{ github.base_ref }} }
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
```

Without a key it runs in **advisory** mode (known-trap checklist, non-blocking). With `ANTHROPIC_API_KEY` it does a real weave on the diff, blocks on 🔴, and contributes new patterns to the corpus.

---

## Spider tiers — resource by criticality

Not every path deserves Opus. Tier by risk:

| Spider | Model | Scope | Verification |
|---|---|---|---|
| 🕷️ King | Opus | payments · auth · GDPR · data loss · secrets | adversarial multi-vote + re-weave |
| 🕸️ Mid | Sonnet | business logic · contracts · i18n · gating | single + one refute pass |
| 🐜 Baby | Haiku | docs · dead code · lint | single pass |

So you're not paying Opus rates to check a comment — and the paths where a false negative is expensive get the most scrutiny.

---

## The shared corpus

Every caught bug is distilled into a stack-keyed pattern (**detection signal + fix principle**) and pooled. A new project checks known traps at round-zero — the more it's used, the thicker the net.

- **Scrub-first:** file paths, code literals, secrets (keys / JWT / high-entropy), emails, URLs, IPs are stripped before anything is shared; anything still suspicious is **rejected**. Only the generalized *technique* leaves your machine.
- **Anonymous:** contributors/projects are stored as irreversible hashes — no identity, no raw text.
- **Consensus:** a pattern needs **3 independent contributors** before it's marked `verified`.

### Corpus API (base = `SPIDER_CORPUS_API`)

- `POST /patterns` `{klass,name,signal,fix,tags?,severity?,tier?}` → scrub · dedup · trust accrual (rate-limited per IP)
- `GET  /patterns?tags=postgres,payment&class=unit&verified=1&limit=50` → pull the corpus (`verified=1` = consensus-verified only, for production use)

Contributing is open — pick a contributor token, POST. No signup, no key required (the token is your anonymous identity, not a credential).

---

## Honest limitations

- **Early (v0.1.1)**, best-tested on Next.js / Supabase / Postgres — other stacks have thinner coverage until the corpus fills in.
- **Running it costs tokens.** The tool is free to use, but a full weave spawns model calls (Opus on critical paths). It's not free to *run*.
- **Not open-source.** The MCP client is on npm and the repo is source-available, but not OSI-licensed; the corpus backend is a hosted, closed service. A free tool, not an open one.
- **"Live evidence only" is the rule, not a proof.** The model can still be wrong — the re-verify step is the guard, not a guarantee.

---

## Principles

No fabrication (live evidence only) · scrub-first (zero code/secret leakage) · opt-in & anonymous · detection = read-only, fixes = isolated spiders.

## Repo layout

```
src/index.js       # MCP server (stdio)
cli/recluse.mjs    # CI weave CLI
action.yml         # GitHub Action
```

The shared corpus is a hosted service (https://eduverse-ai.app/api/corpus); its backend (schema, scrub pipeline, ingestion) is closed-source.

## License

UNLICENSED (proprietary). Free to use; not open-source.