<!-- mcp-name: io.github.Snehgabani/elite-reasoning-mcp -->

# Elite Reasoning MCP v8.1.0

**An evidence-gated verification, selection, and measurement layer for coding agents.**

<p align="center">
  <img src="https://raw.githubusercontent.com/Snehgabani/elite-reasoning-mcp/main/assets/hero-banner.png" alt="Elite Reasoning MCP v8.1.0" width="100%">
</p>

<p align="center">
  <strong>Every capability claim regenerates from committed raw data; retired claims are retracted, not deleted. The product compiles checkable task contracts, verifies drafts with a measured boundary verifier (0% false alarms at full recall on a 113-solution labeled corpus), selects among candidate drafts by execution agreement, and gates completion on digest-bound evidence.</strong>
</p>

<p align="center">
  <a href="https://github.com/Snehgabani/elite-reasoning-mcp/actions/workflows/ci.yml"><img src="https://github.com/Snehgabani/elite-reasoning-mcp/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="https://github.com/Snehgabani/elite-reasoning-mcp/actions/workflows/codeql.yml"><img src="https://github.com/Snehgabani/elite-reasoning-mcp/actions/workflows/codeql.yml/badge.svg" alt="CodeQL"></a>
  <a href="https://github.com/Snehgabani/elite-reasoning-mcp/actions/workflows/secret-scan.yml"><img src="https://github.com/Snehgabani/elite-reasoning-mcp/actions/workflows/secret-scan.yml/badge.svg" alt="Secret Scan"></a>
  <a href="https://scorecard.dev/viewer/?uri=github.com/Snehgabani/elite-reasoning-mcp"><img src="https://api.securityscorecards.dev/projects/github.com/Snehgabani/elite-reasoning-mcp/badge" alt="OpenSSF Scorecard"></a>
  <a href="https://pypi.org/project/elite-reasoning-mcp/"><img src="https://img.shields.io/pypi/v/elite-reasoning-mcp?style=flat-square&color=blue" alt="PyPI"></a>
  <a href="https://github.com/Snehgabani/elite-reasoning-mcp/blob/main/LICENSE"><img src="https://img.shields.io/github/license/Snehgabani/elite-reasoning-mcp?style=flat-square" alt="License"></a>
  <a href="https://github.com/Snehgabani/elite-reasoning-mcp/blob/main/SECURITY.md"><img src="https://img.shields.io/badge/security-policy-brightgreen?style=flat-square" alt="Security Policy"></a>
  <a href="https://github.com/Snehgabani/elite-reasoning-mcp/stargazers"><img src="https://img.shields.io/github/stars/Snehgabani/elite-reasoning-mcp?style=flat-square" alt="Stars"></a>
  <a href="https://raw.githubusercontent.com/Snehgabani/elite-reasoning-mcp/main/llms.txt"><img src="https://img.shields.io/badge/llms.txt-standard-purple?style=flat-square" alt="llms.txt"></a>
</p>

<p align="center">
  <a href="#-quick-start">Quick Start</a> •
  <a href="#-features">Features</a> •
  <a href="#who-this-is-for">Use Cases</a> •
  <a href="#%EF%B8%8F-architecture">Architecture</a> •
  <a href="#-core-tools-default">Core Tools</a> •
  <a href="#-configuration">Config</a> •
  <a href="#-security--trust">Security</a> •
  <a href="#-contributing">Contributing</a>
</p>

---

## Why Elite Reasoning?

Coding agents often miss one requirement in a long request, claim completion without evidence, or repeat a previously identified mistake. Elite Reasoning provides a local [Model Context Protocol](https://modelcontextprotocol.io/) workflow layer that makes requirements explicit, records execution state, retrieves scoped memory, and checks completion evidence.

The default product is intentionally narrow: it compiles a task contract, lets the host perform the work, and returns explicit verification results. Deterministic checks can establish only the behavior they inspect; they do not prove that generated code is correct or secure. Experimental reasoning techniques remain available through non-default profiles and are not part of the core product claim.

> **Install locally, connect an MCP-compatible client, and inspect exactly what was checked, what failed, and what remains unknown.**

<!-- BEGIN GENERATED CLAIMS -->
### Current evidence summary

> Claims below are generated from [`claims.json`](https://github.com/Snehgabani/elite-reasoning-mcp/blob/main/claims.json). Implementation checks describe covered behavior; the internal pilot is not evidence of broad model improvement.

- **Internal fixture pilot constraint pass rate** — A seven-case internal fixture pilot observed 5/7 treatment drafts and 0/7 baseline drafts passing all extracted constraints. The bundled drafts were hand-authored protocol fixtures—not live randomized model outputs—and the primary exact McNemar result (p=0.0625) was not significant at alpha=0.05. _Status: internal pilot; replication: not independently replicated._
- **Deterministic syntax and security checks** — Local deterministic checks cover Python syntax and selected unsafe patterns. Their scope is limited to implemented rules; passing them does not prove correctness or absence of vulnerabilities. _Status: implementation verified; replication: repository tests only._
- **Exact-quote grounding behavior** — The grounding path checks exact quote occurrence against retrieved evidence and exposes degraded or uncertain states. Quote matching alone does not prove source quality or full claim entailment. _Status: implementation verified; replication: repository tests only._
- **Boundary guard analysis catch rate on real code fixtures** — Against the bundled 22-fixture Python corpus (12 buggy, 10 clean), the boundary guard analysis (formerly labeled SMT solver) detected 11 of 12 buggy fixtures with 0 false positives — raw recall 91.67%, raw F1 95.65%, and 100% recall over the 11 bugs it is designed to catch. The one miss is a dynamic computed subscript the analyzer cannot detect. An earlier 19-fixture "v1" corpus measurement (66.67% raw recall) is retracted: that corpus is not recoverable from this repository's history and its numbers are superseded. This tests the verification machinery on hand-authored fixtures, not end-to-end model improvement. _Status: implementation verified; replication: repository tests only._
- **Diagnostic slicer token bound** — The diagnostic slicer compresses Python syntax errors into structured slices estimated under 50 tokens. Token count is approximate. Compact diagnostics do not guarantee improved model repair behavior. _Status: implementation verified; replication: repository tests only._
- **Zero false positive rate on clean code** — Zero false positives observed on all 10 clean Python fixtures in the bundled corpus, across the syntax, division, and array verifiers. An earlier version of this claim said 7 fixtures; the named test in fact covered only 3, and the corrected, fully-covering count is 10. Sample size is small; real-world false positive rate may differ. _Status: implementation verified; replication: repository tests only._
- **Function-call denominator detection (v3.2.0)** — v3.2.0 detects unguarded division by len/sum/count/size on 2 fixtures with 0 false positives on guarded code. Coverage is limited to direct function calls with ast.Name arguments. _Status: implementation verified; replication: repository tests only._
- **Negative constant index detection (v3.2.0)** — v3.2.0 detects items[-1] on potentially empty collections. 1 fixture, 0 false positives. Only constant negative indices detected. _Status: implementation verified; replication: repository tests only._
- **Import hallucination detection (v3.2.0)** — v3.2.0 detects 3/3 hallucinated Python imports with 0 false positives on stdlib. Cannot detect hallucinated submodules of real packages. PyPI allowlist is manually curated. _Status: implementation verified; replication: repository tests only._
- **SLM micro-diagnostic token bound and measured compression on 6 committed fixtures** — On the 6 traceback fixtures committed to this repository, v8.0.0 compresses tracebacks into single-line directives of 7-9 whitespace-delimited tokens (under the 15-token bound), reducing word count by 35.71%-77.50% (mean 56.85%). Those 6 fixtures are hand-written, not a sample of real-world tracebacks. Line number and primary exception cause are preserved. _Status: implementation verified; replication: repository tests only._
- **Best-of-8 dual-execution-agreement selection — E3 confirmatory replication** — In a preregistered confirmatory replication on Llama-3.2-1B-Instruct Q4_0 (28-task hidden-test suite, 140 fresh pairs), best-of-8 sampling with dual-execution-agreement selection passed the preregistered per-pair primary on all-hidden-tests-pass: 15 vs 7, exact McNemar p = 0.021484, at 14.9x token cost. Two caveats are published with it. The effect concentrates in 4 of the 28 tasks and does not survive a post-hoc task-level clustering test (sign-flip p = 0.125), though the continuous hidden-test-fraction secondary is cluster-robust (+5.1pp, task-cluster bootstrap 95% CI [+0.46pp, +10.57pp]). And part of the discordance reflects anchor re-draw rather than selection (drift-free p = 0.0625); Amendment 1's explanation of that drift is refuted, and process failures around the unblinding are recorded, in docs/E3_CONFIRMATORY_AMENDMENT_2.md. One model, one suite; not independently replicated. _Status: internal pilot; replication: not independently replicated._
- **Grammar-constrained decoding raises tool-call emission — E6b preregistered A/B (powered replication, one rep per task)** — In a preregistered A/B on llama3.2-1b-q4_0 (98 paired runs on 98 distinct tasks — one run per task — under a scripted host loop where the model chooses every MCP call), constraining decoding with a committed GBNF grammar whose root keeps free prose available raised per-run tool-call emission from 5/98 to 17/98 (exact McNemar p = 0.016901). One run per task means every pair is an independent cluster, so the test's independence assumption holds by construction and the result carries no clustering caveat. The grammar mechanically guarantees any attempted call parses — that part is construction, not measurement; the measured part is that the model still chose to call, and that calls executed. This is a tool-call-emission result on this loop only: not an adherence-quality, coding-quality, or IDE-host claim, and not comparable to the earlier E5 or E6 datasets (different suites and seeds; E6's 40 pairs were never pooled with these 98). One model, one suite; not independently replicated. _Status: internal pilot; replication: not independently replicated._
- **Best-of-8 sampling plus dual-execution-agreement selection raises hidden-test PASS FRACTION — E10 preregistered A/B (one rep per task)** — In a preregistered A/B on llama3.2-1b-q4_0 (198 paired runs on 198 distinct tasks — one run per task), a composite pipeline of best-of-8 sampling plus dual-execution-agreement selection raised the FRACTION of hidden tests the produced solution passes, from a mean of 0.2697 to 0.3071 (mean paired delta +0.0374; discordant 59:37; exact two-sided sign test p = 0.031548). One run per task means every pair is an independent cluster, so the test's independence assumption holds by construction and the result carries no clustering caveat. This is a partial-credit measure, not a task-completion one: on the same pairs, all-pass was 4/198 for the baseline and 3/198 for the treatment, so the pipeline did NOT produce more fully-correct solutions. The endpoint was chosen after seeing a descriptive secondary of an earlier null experiment on the same arms, and the design was powered at about 0.72 against a shrunk effect — below the 0.80 convention. The treatment costs 14.2x the tokens and 12.8x the wall-clock. One model, one suite, one budget; not independently replicated. MANDATORY CAVEAT (2026-08-29): 91.8% of this effect comes from tasks where the baseline draft did not even parse, and 37.6% of it from drafts truncated by the harness's own 1100-token generation cap. It may not be stated as evidence that the pipeline writes better code. See docs/E10_MECHANISM_AMENDMENT_1.md. _Status: internal pilot; replication: not independently replicated._

<!-- END GENERATED CLAIMS -->

### Who This Is For

- Developers using Cursor, Claude Desktop, Windsurf, or VS Code who want explicit requirement and completion checks.
- Teams evaluating lower-cost coding models that need auditable constraints and evidence rather than unsupported quality scores.
- AI engineers building agent loops that need a compact typed MCP workflow and local-first state.
- Maintainers who want scoped memory, release diagnostics, and transparent limitations.

### The Problem & The Solution

| Common agent failure | Core Elite behavior |
|:---|:---|
| A requirement is overlooked | Compiles explicit constraints linked to the task |
| Completion is claimed without validation | Requests test, syntax, grounding, or outcome evidence |
| A previous mistake is repeated | Retrieves approved, scoped anti-pattern memory |
| A citation cannot be supported | Returns degraded or uncertain grounding instead of inventing evidence |
| Multi-step work gets lost | Records an ordered, durable workflow when persistence is enabled |
| A check is outside the verifier's scope | Reports the limitation rather than treating it as proof of correctness |

---

## ⚡ Quick Start

### One-Line Install

```bash
pip install elite-reasoning-mcp
```

For an isolated CLI installation:

```bash
uv tool install elite-reasoning-mcp

# Verify the actual binary your IDE will run
elite-reasoning-mcp --version
elite-reasoning-mcp doctor --json

# Run an offline bad-draft → corrected-draft verification demo
elite-reasoning-mcp demo

# Preview, then atomically install, an IDE configuration
elite-reasoning-mcp init --ide cursor --dry-run
elite-reasoning-mcp init --ide cursor --yes

# Export redacted evidence from a durable workflow
elite-reasoning-mcp export-evidence <run_id> --json

# Preview a safe standalone upgrade command
elite-reasoning-mcp upgrade --dry-run
```

### Add to your IDE

**Antigravity / Gemini CLI** (`~/.gemini/config/mcp_config.json`):
```json
{
  "mcpServers": {
    "elite-reasoning": {
      "command": "elite-reasoning-mcp",
      "args": [],
      "env": {
        "ELITE_BRAIN_DIR": "~/.elite-reasoning/brain",
        "ELITE_TOOL_PROFILE": "core"
      }
    }
  }
}
```

**Cursor** (`.cursor/mcp.json`):
```json
{
  "mcpServers": {
    "elite-reasoning": {
      "command": "elite-reasoning-mcp",
      "env": {
        "ELITE_BRAIN_DIR": "~/.elite-reasoning/brain",
        "ELITE_TOOL_PROFILE": "core"
      }
    }
  }
}
```

**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
```json
{
  "mcpServers": {
    "elite-reasoning": {
      "command": "elite-reasoning-mcp",
      "args": [],
      "env": {
        "ELITE_BRAIN_DIR": "~/.elite-reasoning/brain",
        "ELITE_TOOL_PROFILE": "core"
      }
    }
  }
}
```

**Windsurf** (`~/.codeium/windsurf/mcp_config.json`):
```json
{
  "mcpServers": {
    "elite-reasoning": {
      "command": "elite-reasoning-mcp",
      "env": {
        "ELITE_BRAIN_DIR": "~/.elite-reasoning/brain",
        "ELITE_TOOL_PROFILE": "core"
      }
    }
  }
}
```

**VS Code + Continue** (`~/.continue/config.yaml`):
```yaml
mcpServers:
  - name: elite-reasoning
    command: elite-reasoning-mcp
    env:
      ELITE_BRAIN_DIR: ~/.elite-reasoning/brain
      ELITE_TOOL_PROFILE: core
```

**Zed** (`~/.config/zed/settings.json`):
```json
{
  "context_servers": {
    "elite-reasoning": {
      "command": {
        "path": "elite-reasoning-mcp",
        "args": [],
        "env": {
          "ELITE_BRAIN_DIR": "~/.elite-reasoning/brain",
          "ELITE_TOOL_PROFILE": "core"
        }
      }
    }
  }
}
```

### Activate the Continuous Pipeline

If your client exposes MCP prompts, start a task with `/goal <your objective>`. The `goal` prompt anchors a durable `run_id` and tells the host to follow the `continuation` object returned after every Elite call.

Add this to your IDE's system prompt (e.g., `~/.gemini/GEMINI.md` or Cursor Rules):

```markdown
## ⚡ RULE #0 — ELITE MCP PIPELINE

For every non-trivial prompt, call `elite_prepare(user_prompt="<exact message>", persist=true)` first and retain `run_id`.

After EVERY Elite response, inspect `continuation`:

- If `stop_final_response=true`, do not answer yet.
- Call `required_tool` with `required_args`, replacing placeholders with current code, repository root, tests, or final draft.
- Repair `FAIL`, `UNKNOWN`, `NOT_CHECKED`, `REPEAT`, and stale evidence; then follow the new continuation.
- If context becomes long or the next step is forgotten, call `elite_verify(check="status", run_id="<saved run id>")` to recover it.
- Answer only when `checkpoint="done"` and `stop_final_response=false`.

For coding tasks the normal sequence is prepare → syntax after the first edit → Git scope → executed tests → outcomes. Skip the pipeline only for trivial acknowledgements such as "ok" or "thanks".
```

> **Enforcement boundary:** MCP cannot make a host model issue another call after the model stops using tools. Continuation directives, `/goal`, IDE rules, durable recovery, final evidence gates, and optional repository hooks reduce omission risk in layers; they are not an absolute host-level guarantee.

Restart the IDE after changing its MCP configuration or host rules.

---

## 🚀 Features

> Feature claims below are scoped to what the measurement program (docs/PRODUCT_REVIEW_AND_MEASUREMENT.md, docs/E1–E3 results) supports. Where a capability is experimental or not on the shipped path, it says so.

### 🔍 Automated Evergreen Discoverability & AI Search Specs (v8.0.0)
Sub-millisecond CPython AST introspection extracts live tool contracts, docstrings, and schemas without executing the server runtime. Automatically keeps [`llms.txt`](https://raw.githubusercontent.com/Snehgabani/elite-reasoning-mcp/main/llms.txt), [`llms-full.txt`](https://raw.githubusercontent.com/Snehgabani/elite-reasoning-mcp/main/llms-full.txt), and RFC [`.well-known/mcp/server-card.json`](https://github.com/Snehgabani/elite-reasoning-mcp/blob/main/.well-known/mcp/server-card.json) permanently in sync with the codebase for instant indexing by AI search engines (Perplexity, ChatGPT Search, Claude).

### ⚡ Micro-Diagnostic Compressive Slicer (<15 Tokens) (v8.0.0)
Compresses verbose tracebacks into single-line pointers (`[L42] ZeroDivision: count -> Fix: guard count > 0`). Measured on the 6 traceback fixtures committed to this repository (Python, TypeScript, Go, Rust): directives of 7–9 whitespace-delimited tokens, under the 15-token bound, with 35.71%–77.50% word-count reduction (mean 56.85%) — reproduce with `.venv/bin/python evals/ab_harness/measure_slm_compression.py` (CLAIM-010). Those 6 fixtures are hand-written and were authored alongside the compressor; they are not a sample of real-world tracebacks, so the range above does not generalize. Compact diagnostics do not by themselves improve model repair behavior — in the E2 measurement, verifier-driven repair loops were harmful at 1B, which is why the shipped flow favors a single clean verification pass over retry churn.

### 🧬 Contract Requirement Extraction (v2)
Compiles the task prompt into checkable, verbatim requirements. The v2 extractor achieves 100% verbatim requirement recall on the labeled spec corpus (previously 46%; see docs/E3_CONTRACT_V2_AND_CEILING_FINDING.md). The earlier "3-rule distillation" prompt-shaping mechanism measured null in the E2 arms and carries no fidelity claim.

### 🎯 Best-of-N Draft Selection — `elite_verify(check="select")`
CodeT-style dual execution agreement (Chen et al. 2022): given N candidate drafts sampled by the host, the selector parse-filters, majority-votes on execution probes in sandboxed subprocesses, and screens unintended crashes — never consulting ground-truth tests. In a preregistered confirmatory replication on Llama-3.2-1B-Instruct Q4_0 (28-task hidden-test suite, 140 fresh pairs), best-of-8 sampling with dual-execution-agreement selection passed the preregistered per-pair primary on all-hidden-tests-pass: 15 vs 7, exact McNemar p = 0.021484, at 14.9x token cost. Two caveats are published with it. The effect concentrates in 4 of the 28 tasks and does not survive a post-hoc task-level clustering test (sign-flip p = 0.125), though the continuous hidden-test-fraction secondary is cluster-robust (+5.1pp, task-cluster bootstrap 95% CI [+0.46pp, +10.57pp]). And part of the discordance reflects anchor re-draw rather than selection (drift-free p = 0.0625); Amendment 1's explanation of that drift is refuted, and process failures around the unblinding are recorded, in docs/E3_CONFIRMATORY_AMENDMENT_2.md. One model, one suite; not independently replicated. (CLAIM-011)

### ⚡ Program Dependence Graph (PDG) Backward Slicing (experimental, not on shipped path)
A real def-use backward slicer exists in the codebase but is not wired into the shipped verification path, and there is no Control Dependence Graph. Treat it as experimental code, not a product capability.

### 📐 Dynamic Type Lattice & Range Inference
Infers variable types and numerical bounds across untyped Python code in <1ms without type annotations. Catches incompatible binary operations (`str - int`, `list * dict`) and propagates intervals through arithmetic expressions.

### 🔀 Deterministic Boundary Guard Analysis (formerly labeled "CEGIS/SMT")
Polarity- and alias-aware guard analysis over the AST that flags unguarded division, indexing, and boundary bugs. Measured: 0% false alarms at full recall on a 113-solution labeled corpus (previously 20.4%; see docs/E1_VERIFIER_FIX_RESULTS.md). There is no Craig interpolation and verdicts are AST-decided; engine labels now say so truthfully.

### 🛡️ Multi-Agent Capability Attenuation DAG (experimental, not on shipped path)
Least-privilege capability delegation code exists under `core/policy/`, but it is not reachable from the shipped MCP entry point. Treat it as experimental code, not a product capability.

### 🌐 Real-Time Interactive Telemetry & Discoverability Canvas
Built with Next.js 16 (Turbopack) and React 19. Features live interactive Program Dependence Graph slicing sliders, AST proof obligation canvases, SEO discoverability metrics, and real-time WebSocket state streaming with WCAG 2.1 AA accessibility.

### 🧠 Evidence-Gated Continuous Workflow
`elite_prepare` creates a durable contract and returns a `continuation` directive. Every later `elite_verify` response repeats the exact next checkpoint, so the instruction is refreshed after edits instead of appearing only at the beginning. Verification distinguishes `PASS`, `FAIL`, `UNKNOWN`, and `NOT_CHECKED`, binds evidence to exact subject/repository digests, and reopens stale checkpoints after post-verification edits.

### 🛡️ Anti-Pattern Memory
Past mistakes can be recorded with root-cause analysis and retrieved by scoped search. The associative-graph (HippoRAG-style) recall layer is wired on the live path (knowledge-graph edges are created on store and traversed on recall; measured memory-hit rate 1.0 in E4), and a preregistered planted-pitfall A/B (E4, 40 pairs, 20 families; docs/E4_MEMORY_PREREGISTRATION.md) found that persisting and recalling first-encounter failures did not produce the hypothesized positive discordance (CM:C discordants = 0:0); any per-encounter effect is below what N = 40 can detect, with a measured first-encounter pitfall rate of 0.525 and memory-hit rate of 1.0. No "learns from its errors" claim is made.

### 📊 Confidence Calibration & Honest Statistics
Track prediction accuracy with proper Brier scores, and paired-sample exact McNemar tests with Clopper-Pearson 95% confidence intervals in the A/B harness. The previously published "Double-Blind RCT" scorecard was fabricated and has been retracted (see docs/PRODUCT_REVIEW_AND_MEASUREMENT.md, section 3); anti-fabrication CI gates now reject simulated baselines and hardcoded significance strings.

### ⚖️ Decision Council (legacy catalog only — not functional in current builds)
The 5-perspective adversarial review tool belonged to the legacy catalog, which current builds do not expose (see "Legacy Catalog" below).

### 🔒 Prevention Rules & 8-Layer Middleware Chain
Custom auto-triggered rules for your workflow. Every tool call passes through usage logging, latency measurement, prevention rules, anti-pattern injection, cost tracking, fallback guidance, and real transient retries. Structured gateway responses retain a stable `warnings` field.

### 💾 Cryptographically Scrubbed Persistent Memory
Cross-session knowledge stays scoped, trust-weighted, and privacy-gated. Secret-like content is redacted before storage; low-trust, sensitive, expired, and remotely imported items remain quarantined until an explicit approval action promotes them.

### 🏥 Release Doctor & Self-Healing Janitor
`elite_verify(check="doctor")` checks runtime identity, protocol version, dependencies, DB schema, capability routing, exposed tool count, active IDE mismatch, and release blockers before shipping. Runs the full science-grade release gate in `scripts/release_check.py` — tests with a coverage floor, lint/format, focused typing plus a repo-wide typing-debt ratchet, baselined security scan, package hygiene, and wheel/MCP smokes.

---

## 🏗️ Architecture

```
Your Task
    ↓
elite_prepare  →  playbook + expected outcomes + allowed_tools
    ↓
host follows playbook (usually 1–2 elite_verify calls, then host_work)
    ↓
elite_verify(check="outcomes")  →  DONE or REPEAT
    ↓
if REPEAT: fix unmet items and verify again (do not answer yet)
    ↓
┌──────────────────────────────────────────────┐
│ Local-first telemetry and memory boundaries    │
│ Metadata by default; raw retention opt-in      │
│ Remote memory remains quarantined until review │
└──────────────────────────────────────────────┘
```

---

## 🔧 Core Tools (v3.0.0)

The v3 architecture exposes exactly **three** cohesive tools. A minimal tool surface keeps routing simple for smaller host models; no routing-precision figure is claimed.

| Tool | Parameters | Purpose |
|:-----|:-----------|:--------|
| `elite_prepare` | `user_prompt`, `persist` | Compiles checkable task contracts, explicit constraints, playbook, repository digest lock, and continuation directive. |
| `elite_verify` | `check`, `query`, `draft`, `run_id`, `code`, `language`, `command`, `project_root`, `step_index`, `allowed_files`, `forbid_dependency_changes` | Deterministic verification gateway supporting 19 check types: `doctor`, `capabilities`, `constraints`, `evidence`, `syntax`, `tests`, `grounding`, `outcomes`, `diff`, `cegis`, `select`, `diagnostics`, `types`, `outline`, `callgraph`, `status`, `progress`, `privacy`, `monitoring`. |
| `elite_memory` | `action`, `query`, `content`, `memory_type`, `scope`, `memory_id`, `trust_score`, `privacy_class`, `confirm` | Scoped episodic & semantic memory with trust scoring, quarantine isolation, and cryptographic secret scrubbing. Includes associative-graph (HippoRAG-style) recall via `action="associative"`. |

### Legacy Catalog (not functional in current builds)

Earlier releases advertised a 90+ tool legacy catalog behind `ELITE_TOOL_PROFILE=legacy`. In current builds that profile flag is parsed and stored but performs no branching, so the legacy catalog is not functional and none of those tools are exposed. The listing has been removed from this README to avoid advertising unavailable capability; the historical catalog remains in Git history.

---

## ⚙️ Configuration

### Environment Variables

| Variable | Default | Description |
|:---------|:--------|:------------|
| `ELITE_BRAIN_DIR` | `~/.elite-reasoning/brain` | Where to store persistent memory |
| `ELITE_TOOL_PROFILE` | `core` | `core` exposes the three typed gateway tools. The `legacy` value is parsed and stored but performs no branching in current builds (the legacy catalog is not functional). |
| `ELITE_TELEMETRY_MODE` | `metadata` | `off`, `metadata`, `summary`, or `raw`; raw requires a second opt-in. |
| `ELITE_ALLOW_RAW_TELEMETRY` | unset | Must be `1` before `ELITE_TELEMETRY_MODE=raw` is honored. |
| `ELITE_ALLOW_RAW_PROMPT_STORAGE` | unset | Must be `1` to retain redacted raw prompts; otherwise prompts are hashed and withheld. |
| `ELITE_SYNC_ALLOWED_HOSTS` | localhost only | Comma-separated approved sync hosts. |
| `ELITE_SYNC_ALLOW_NETWORK` | unset | Must be `1` for approved non-local sync hosts. |
| `ELITE_SYNC_ALLOW_OUTBOUND` | unset | Must be `1` before legacy sync can push local decisions or anti-patterns. |
| `ELITE_SYNC_BIND_ALL_INTERFACES` | unset | Required with a sync API key before the optional hub can bind beyond localhost. |
| `SYNC_USER_KEYS_JSON` | unset | Optional sync-hub JSON mapping of user IDs to distinct API keys for auditable multi-user attribution. |
| `SYNC_SINGLE_USER_ID` | `single-user` | Server-side actor label for a single-user hub using `SYNC_API_KEY`. |
| `ELITE_SYNC_ENABLE_LLM_JUDGE` | unset | Required with `GEMINI_API_KEY` before the hub sends submissions to an external LLM judge. |
| `ELITE_ENABLE_LEGACY_INTERCEPTOR` | `0` | Enable legacy monkey-patch interceptor |
| `ELITE_GEMINI_BASE_URL` | (built-in) | HTTPS Gemini endpoint; a non-Google host also requires `ELITE_ALLOW_CUSTOM_GEMINI_ENDPOINT=1`. |

The local profile is created with owner-only permissions at `~/.elite-reasoning/config.json`; it is not read from the repository checkout and must never be committed. Neutral configuration and team-memory shapes are available in [docs/examples/local-profile.example.json](https://github.com/Snehgabani/elite-reasoning-mcp/blob/main/docs/examples/local-profile.example.json) and [docs/examples/team-memory.example.json](https://github.com/Snehgabani/elite-reasoning-mcp/blob/main/docs/examples/team-memory.example.json). Keep credentials in process environment variables or an OS keychain, not in JSON.

### Development Setup

```bash
# Clone the repo
git clone https://github.com/Snehgabani/elite-reasoning-mcp.git
cd elite-reasoning-mcp

# Install with dev dependencies
uv sync --extra dev

# Run the release gate used by CI
uv run python scripts/release_check.py

# Build package
uv build
```

---

## 🧪 Testing

```bash
# Run all tests
ELITE_BRAIN_DIR=/tmp/elite-test uv run pytest tests/ -v --tb=short

# Run the full release gate: tests, lint, types, high-severity scan,
# package privacy/content inspection, wheel CLI, and MCP smoke
uv run python scripts/release_check.py

# Run with coverage
uv run pytest tests/ --cov=core --cov-report=html
```

The test suite covers:
- ✅ Persistent store (CRUD, FTS, graph, goals, benchmarks)
- ✅ Graph store (nodes, edges, temporal queries, hypotheses)
- ✅ Connection pooling and stale connection recovery
- ✅ FTS sanitization (injection prevention)
- ✅ Workflow flight recorder and MCP tool exposure
- ✅ stdio MCP protocol identity, structured output, and `isError=true` failures
- ✅ privacy-safe telemetry, secret migration, approved sync, and memory quarantine
- ✅ ordered workflow evidence, prevention events, retry, fallback, and local monitoring
- ✅ Quality-gated memory quarantine
- ✅ Release doctor and eval harness exporters

---

## 🔐 Security & Trust

Elite Reasoning MCP is local-first by default: memory is stored under `ELITE_BRAIN_DIR`, telemetry stores metadata rather than prompt content, and external API access is opt-in through environment configuration.

The default profile does not expose network sync tools. In the explicit legacy profile, every sync request requires `confirm=true`, an allowlisted endpoint, redirect blocking, and environment grants for external or outbound traffic. The optional sync hub binds to localhost by default; external binding needs configured credentials and `ELITE_SYNC_BIND_ALL_INTERFACES=1`. For multi-user deployments, configure distinct credentials with `SYNC_USER_KEYS_JSON`; the hub derives contributor attribution from the credential and never trusts a caller-supplied user ID. Imported remote records are stored as low-trust quarantined memory until an operator explicitly approves them. External LLM judging is disabled unless both `GEMINI_API_KEY` and `ELITE_SYNC_ENABLE_LLM_JUDGE=1` are set.

Public repository hardening includes:
- `SECURITY.md` with supported versions, private vulnerability reporting, and memory/privacy boundaries
- Dependabot for Python, GitHub Actions, and telemetry UI dependencies
- CodeQL scanning for Python security issues
- Dependency Review on pull requests
- OpenSSF Scorecard visibility for supply-chain posture
- Immutable GitHub Action pins, with Dependabot update coverage
- GitHub build provenance and PyPI digital attestations for release distributions
- An allowlisted source distribution plus a release gate that rejects local profiles, generated UI output, databases, and credential-like files
- A checksum-verified, read-only Gitleaks workflow that scans full Git history and the checked-out files with redacted findings
- Release-gate evidence via `scripts/release_check.py`

Security reports should use [GitHub private vulnerability reporting](https://github.com/Snehgabani/elite-reasoning-mcp/security/advisories/new), not public issues.

For the next tracking and monitoring layer, see the [Elite Telemetry Roadmap](https://github.com/Snehgabani/elite-reasoning-mcp/blob/main/docs/elite_telemetry_roadmap.md).

---

## 🤝 Contributing

Contributions are welcome. Start with [CONTRIBUTING.md](https://github.com/Snehgabani/elite-reasoning-mcp/blob/main/CONTRIBUTING.md), [GOVERNANCE.md](https://github.com/Snehgabani/elite-reasoning-mcp/blob/main/GOVERNANCE.md), and the security boundaries in [SECURITY.md](https://github.com/Snehgabani/elite-reasoning-mcp/blob/main/SECURITY.md).

1. **Fork** the repository
2. **Create** a feature branch (`git checkout -b feature/amazing-feature`)
3. **Run** the release gate (`uv run python scripts/release_check.py`)
4. **Document** MCP behavior, privacy impact, and validation evidence in your PR
5. **Commit** your changes (`git commit -m 'feat: add amazing feature'`)
6. **Push** to the branch (`git push origin feature/amazing-feature`)
7. **Open** a Pull Request

### Commit Convention

We use [Conventional Commits](https://www.conventionalcommits.org/):
- `feat:` — New features
- `fix:` — Bug fixes
- `chore:` — Maintenance
- `docs:` — Documentation

---

## 📄 License

MIT © [Sneh Gabani](https://github.com/Snehgabani)

---

<p align="center">
  <sub>Built for the AI-native developer workflow</sub>
</p>
<p align="center">
  <a href="https://github.com/Snehgabani/elite-reasoning-mcp/stargazers">Star us on GitHub</a> •
  <a href="https://pypi.org/project/elite-reasoning-mcp/">View on PyPI</a> •
  <a href="https://github.com/Snehgabani/elite-reasoning-mcp/issues">Report a Bug</a>
</p>