sparda-mcp 0.13.3 → 0.14.1

package/README.md

@@ -6,39 +6,115 @@
 
 <br/>
 
-> 🇫🇷 **Français** : Pour comprendre SPARDA en 10 minutes (douleur, architecture, vision), lisez le document du fondateur : [SPARDA-EXPLIQUE.md](docs/SPARDA-EXPLIQUE.md).
+<div align="center">
+
+## **AI writes. SPARDA proves.**
+
+</div>
+
+AI made writing code free. It made *trusting* code the bottleneck. Your agents open
+pull requests faster than any human can truly review them, and the industry's answer
+is to have another LLM skim the diff — an opinion grading an opinion.
+
+SPARDA is not an opinion. It's a **behavior compiler**: it compiles your backend
+(code + schema) into a deterministic behavior graph, and *proves* things against it —
+which guard a PR removed, which invariant a deploy dropped, whether a fix broke
+nothing else. Every finding is a **counterexample**, never a vibe. Zero spec to
+write, zero config, zero API key, nothing leaves your machine.
+
+One engine, four moves:
+
+| | Command | What it proves |
+|---|---|---|
+| 🔍 | `sparda review` | the **behavior diff** of a PR — guards dropped, blast radius grown, new endpoints |
+| 🛡️ | `sparda apocalypse` | a deploy can't break any declared guard, invariant, transaction or aggregate |
+| 🪞 | `sparda mirror` | a live mock **derived from the code** — enforces the real state machine, can never drift |
+| ⏪ | `sparda timeless` / `heal` | replay a production bug deterministically; gate the fix with proof, not hope |
+
+And because trust must extend to *runtime*, the same engine turns your app into a
+safe set of MCP tools for Claude & friends — writes gated, failures quarantined
+(see [Give your AI safe hands](#give-your-ai-safe-hands-the-mcp-layer)).
+
+## Review every PR's *behavior* — one file, zero config
 
----
+Every code-review tool diffs your **text**. None diff your **behavior**. SPARDA
+compiles the PR's base branch and your changes to the behavior graph and comments the
+difference — as one sticky comment that updates on every push:
 
-**A compiler for backend behavior. The LLVM of web applications.**
+<div align="center">
+  <img src="assets/pr-review-demo.svg" alt="SPARDA review bot commenting the behavior diff on a pull request: NOT PROVEN — GUARD_REMOVED on POST /pay, BLAST_RADIUS_GREW on POST /transfer, new endpoint POST /refund" width="740" />
+</div>
 
-For twenty years software communicated through APIs. Then AI agents arrived, and the industry's answer was to expose more endpoints (MCP). But an agent doesn't *understand* an application from a list of disconnected tools — and neither can a linter, a debugger, or a deploy gate reason about a codebase they only read line by line.
+<br/>
 
-SPARDA compiles your backend — routes, database queries, state mutations, permissions, side-effects — into one language-agnostic, mathematical graph: the **Unified Behavior Graph (UBG)**, serialized as `.sparda/ubg.json` under the **SBIR** specification ([SPARDA Behavior IR](docs/SBIR_SPEC_V1.1.md)). Compile once; then every tool is a simple pass over that graph.
+Drop this one file into `.github/workflows/sparda-review.yml` — no key, no account,
+no spec to write:
+
+```yaml
+name: SPARDA behavior review
+on: pull_request
+permissions:
+  contents: read
+  pull-requests: write
+jobs:
+  review:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }
+      - uses: zyx77550/sparda@main
+        with:
+          mode: review          # comment-only by default — never blocks a merge
+          # fail-on-severity: high   # uncomment to also gate the check
+```
 
-**What the graph unlocks — 100% local, deterministic, zero runtime dependencies, zero API key:**
+Every finding is a **counterexample from the code + schema**, not a pattern-match — so
+no false-positive noise to train your team to ignore. Same engine, as a hard CI gate:
+`mode: apocalypse` (the default) fails the job on any critical/high and can upload
+SARIF to the Security tab.
 
-| Command | What it does |
-|---|---|
-| **`ubg`** | Compile the codebase to its behavior graph (Express · FastAPI · Next.js natively; **any** stack via OpenAPI) |
-| **`apocalypse`** | *Prove the deploy* — no guard, invariant, transaction or aggregate boundary can be broken (SARIF + CI gate) |
-| **`timeless`** | *Time-travel* — record a production request, replay it byte-identically, export the bug as a test |
-| **`heal`** | *Self-heal, proven* — bug → fix → the machine proves the fix is correct and breaks nothing |
-| **`mirror`** | *Execute the graph* — serve the compiled behavior over HTTP with no framework and no source |
-| **`openapi`** | *Emit the standard* — produce an OpenAPI 3.1 spec from the graph |
-| **`verify`** | *Prove the compiler's own laws* (determinism, soundness, round-trip) on your app |
-| **`init` / `dev`** | Expose the graph to AI clients as a live MCP server (+ Twin, Immune, Evolution runtime layer) |
+## Prove the deploy
 
 ```bash
-npx sparda-mcp ubg          # compile your backend → .sparda/ubg.json
-npx sparda-mcp apocalypse   # prove the current tree is safe to deploy
+npx sparda-mcp apocalypse            # PROVEN, RISKY, or NOT PROVEN — with counterexamples
+npx sparda-mcp apocalypse --sarif    # findings land in GitHub's Security tab
 ```
 
-No cloud account. No server to host. Exposing raw APIs to AI is the old way — SPARDA compiles the whole system's behavior, then proves, replays, heals, and serves it.
+Five proof obligations discharged over the compiled graph — unguarded mutations,
+unvalidated constrained writes, non-atomic aggregate writes, irreversible external
+calls, aggregate bypasses — plus a diff against your saved baseline: no entrypoint
+silently removed, no guard dropped, no blast radius grown. Exit 1 gates the pipeline.
+
+## A mock that can never lie
+
+```bash
+npx sparda-mcp mirror                # the graph IS the server — no framework, no source
+```
 
-**Nomenclature:** **SBIR** is the specification (the format, like "JSON"); **UBG** is the compiled graph itself (the artifact, `ubg.json`). The MCP server is one *output* of the graph, not the product.
+The mirror serves your compiled behavior over HTTP: guards actually deny (401),
+responses come out typed, and the **inferred state machine is enforced** — `POST
+/orders` seeds `pending`, paying it moves it to `paid`, paying it *again* is refused
+`409`. Hand-written mocks drift; this one is derived from your code + schema, so it's
+synchronized by construction. Front-ends develop against backends that aren't
+deployed — or written — yet.
 
-## Quickstart
+## Give your AI safe hands (the MCP layer)
+
+Your AI can write code. It still can't *operate* your app — and giving it raw access
+usually means days of glue code and one prayer per `DELETE`. SPARDA deletes that work:
+
+```bash
+npx sparda-mcp init   # scan your Express/FastAPI/Next.js app, inject the MCP router — 3 minutes
+npx sparda-mcp dev    # connect Claude Desktop / Claude Code. Done.
+```
+
+No OpenAPI spec. No account. No API key. No server to host. And the same trust rules
+apply at runtime: **writes are disabled by default**, an enabled write needs an
+explicit human confirmation (two-phase, single-use token), and every write is followed
+by a proof-after-write read-back.
+
+<details>
+<summary><b>Quickstart — three steps</b></summary>
 
 1. **Scan + inject** — run once, from your app's directory:
    ```bash
@@ -68,130 +144,24 @@ No cloud account. No server to host. Exposing raw APIs to AI is the old way —
    Claude Code connects to the same bridge. That's it — your running app is now a set
    of MCP tools your AI can call.
 
+</details>
+
 ## Try the Standalone Demo
 
 To see SPARDA in action instantly without modifying your codebase:
 ```bash
 npx sparda-mcp demo
 ```
-This runs the entire MCP lifecycle (detect → parse → generate → inject → remove) on a bundled demo app in a temporary folder, in about 10 seconds. For the compiler itself, run `npx sparda-mcp ubg` then `apocalypse` on any Express/FastAPI app.
+This runs the entire lifecycle (detect → parse → generate → inject → remove) on a bundled demo app in a temporary folder, illustrating all six guarantees in 10 seconds.
 
 ## Black Box Report
 
 SPARDA is designed as a local organism. To see what it remembers and how much compute it has recycled:
 ```bash
-npx sparda-mcp report
-```
-This prints a terminal dashboard aggregating your exposed tools, write opt-ins, proof journal decisions, and crystallized composite tools.
-
-To write a self-contained, offline HTML dashboard at `.sparda/report.html`, append the `--html` flag:
-```bash
-npx sparda-mcp report --html
-```
-
-To output raw JSON for integration:
-```bash
-npx sparda-mcp report --json
-```
-
-## Deployment Proof: Apocalypse
-
-SPARDA's Behavior Graph is a formal model of your system. Instead of waiting for runtime failures or relying on static analysis vibes, you can statically prove the safety of your backend before any deployment:
-```bash
-npx sparda-mcp apocalypse
-```
-This command reads the compiled `.sparda/ubg.json` (with zero source code parsing at runtime) and discharges five static correctness obligations:
-* **Unguarded Mutation (Critical)**: Flags any mutation path that does not cross a security `guard`.
-* **Non-Atomic Aggregate Write (High)**: Flags when an API writes to multiple tables of the same Consistency Domain (Aggregate) outside a single transaction scope.
-* **Unvalidated Constrained Write (Medium)**: Flags writes into columns with declared invariants (CHECK, NOT NULL, UNIQUE — parsed from your `.sql` DDL **or `schema.prisma`**, Prisma enums included) without prior validation (Zod/Pydantic).
-* **Irreversible Observable Effect (High)**: Flags out-of-process actions (like Stripe charges) that happen alongside state writes without a structural compensation path (like a catch-refund).
-* **Aggregate Member Bypass (Info)**: Flags mutating a member table directly without routing through the aggregate root.
-
-To save your current graph as a safe baseline:
-```bash
-npx sparda-mcp apocalypse --save-baseline
+npx sparda-mcp report          # terminal dashboard
+npx sparda-mcp report --html   # self-contained offline dashboard at .sparda/report.html
+npx sparda-mcp report --json   # raw JSON for integration
 ```
-Subsequent runs will diff the candidate graph against this baseline to detect regression vectors:
-* Deletion of any security `guard` (Critical).
-* Deletion of a database SQL invariant (High).
-* API blast radius expansion (Medium).
-
-If any Critical or High finding is found, `apocalypse` exits with a non-zero code to block your CI pipeline.
-
-**One step in your workflow — findings land in the GitHub Security tab (SARIF):**
-```yaml
-- uses: zyx77550/sparda@main
-  with:
-    sarif: 'true'
-```
-
-## Time Travel: Timeless
-
-Every production request is deterministic between its effects — the compiler knows exactly where the nondeterminism lives (db, http, clock, random, uuid: the effect nodes of the graph). Timeless records only those points (a few KB per request) and replays the request **byte-identically** against your current code, with the database, webhooks and clock virtualized from the recording:
-
-```bash
-npx sparda-mcp timeless                # list recorded flights
-npx sparda-mcp timeless replay <id>    # re-fly it — byte-identical or loud divergence
-npx sparda-mcp timeless export <id>    # the production bug is now a vitest test
-```
-
-Recording is two lines in your app (ESM), with deterministic sampling and GDPR redaction built in:
-```js
-import { getFlightBox } from 'sparda-mcp/src/flight/box.js';
-const box = getFlightBox(); box.arm();
-app.use(box.middleware({ sample: 100 }));   // 1 request in 100; passwords/tokens redacted by default
-const db = box.wrapClient(pgPool);           // your query client, tapped
-```
-
-The closed loop nobody else has: **production bug → recorded flight → failing test → AI writes the fix → `apocalypse` proves the fix breaks no guard, invariant or transaction → deploy.** Replay is per-request (concurrent-race capture is out of scope for v1 — stated, not hidden).
-
-## Self-Healing, Proven: `sparda heal`
-
-The loop above, as **one gesture** — and the machine judges the fix, whoever wrote it:
-
-```bash
-npx sparda-mcp heal <flightId>                       # diagnose + write the fix brief
-# ...apply the fix (a human, or --agent "your-ai-cli")...
-npx sparda-mcp heal <flightId> --check --expect '{"status":404}'
-```
-
-The brief is built from the graph itself — it hands the fixer the handler's `file:line`, the capabilities the fix must not grow, and the guards it must not remove. Then the **gate** — the actual product — proves the fix on three axes at once:
-
-1. **Behavior** — lenient replay of the recorded flight (same deterministic inputs) now produces the *expected* response, not the recorded bug. The fix may reformulate a query (the tap is relabeled, allowed); it may **not** change the effect order or kinds.
-2. **Compiler laws** — `verify` still passes: the graph is still sound and deterministic.
-3. **No regression** — `apocalypse` diff against the frozen pre-fix graph: zero new critical/high findings, no guard removed, no blast radius grown.
-
-```
-✓ HEALED & PROVEN — same recorded inputs, correct output, zero law broken, zero protection lost. Ship it.
-```
-
-The gate is honest in both directions: an unfixed bug, or a "fix" that silently drops a guard, keeps it **closed** (exit 1). This is the difference between an AI that writes plausible code and a system that *proves* the code is correct — the trust layer the agent era is missing.
-
-## Any Backend On Earth: OpenAPI Lowering
-
-SPARDA parses Express, FastAPI and Next.js natively — and **every other stack through the format the industry already agreed on**. Go, Java, Rails, Laravel, .NET: if it has an OpenAPI spec, it compiles.
-
-```bash
-npx sparda-mcp ubg --openapi openapi.json
-```
-
-Security schemes become gating `guard` nodes, response schemas become typed returns, declared request bodies count as validated input. Pair the spec with your `.sql` or `schema.prisma` files and the full state layer — invariants, aggregates, state machines — fills in from declared truth. (JSON specs in v1; we refuse to half-parse YAML with zero dependencies.)
-
-## The Mirror VM: delete the framework, the app still answers
-
-The graph is not a diagram — it executes:
-
-```bash
-npx sparda-mcp mirror
-```
-
-```
-MIRROR — the graph is serving. 3 entrypoint(s) on http://127.0.0.1:4477
-  GET    /orders/{orderId}  → {amount, id, status}
-  POST   /orders  🔒 bearerAuth  → {amount, id, status}
-```
-
-No Express. No FastAPI. No source code — just `ubg.json` answering HTTP: guards actually deny (401), responses render the compiled return schemas, unknown paths 404 with the full route table. Front-end teams develop against backends that aren't deployed yet — or aren't written yet (point `mirror` at an OpenAPI spec). Every response carries `x-sparda-mirror: true`; the mirror serves declared behavior, it never invents business values.
 
 To undo everything: **`npx sparda-mcp remove`** restores your code byte-for-byte.
 
@@ -203,10 +173,10 @@ To undo everything: **`npx sparda-mcp remove`** restores your code byte-for-byte
 
 <br/>
 
-1. **Three minutes, one command.** AST scan, router generation, reversible injection — no config.
-2. **Try it for free, leave for free.** `npx sparda-mcp remove` restores your code **byte-for-byte** (tested on JS, TS, Python, even Windows CRLF files). No trace, no lock-in.
-3. **The AI cannot write until you say so.** Every POST/PUT/DELETE is disabled by default; you enable per tool, and your choice survives every re-run.
-4. **Your app defends itself.** A route failing 3 times in a row is quarantined — the AI can't hammer your broken production. Latency anomalies are flagged. Zero LLM needed.
+1. **Proof, not opinion.** Every review/apocalypse finding is a counterexample derived from your code + schema — deterministic, byte-identical run after run, machine after machine.
+2. **Three minutes, one command.** AST scan, router generation, reversible injection — no config.
+3. **Try it for free, leave for free.** `npx sparda-mcp remove` restores your code **byte-for-byte** (tested on JS, TS, Python, even Windows CRLF files). No trace, no lock-in.
+4. **The AI cannot write until you say so.** Every POST/PUT/DELETE is disabled by default; you enable per tool, and your choice survives every re-run.
 5. **Nothing leaves your machine.** No telemetry to us, no cloud, local key auth, 4 exact-pinned dependencies.
 6. **What it learns is never lost.** Diagnoses, descriptions, settings — versioned with your git, surviving every re-init.
 
@@ -214,23 +184,14 @@ What we *don't* promise: the honest limits in [docs/SECURITY.md](./docs/SECURITY
 
 ## How it works
 
-1. `npx sparda-mcp init` parses your codebase (AST), extracts every route, and injects a tiny marked router (`/mcp`) into your app — fully reversible with `npx sparda-mcp remove`.
-2. Tool calls run **inside your live app process** — warm DB pools, real auth chain, real data. SPARDA adds no infrastructure: compute comes from your host process, intelligence from your AI client's own model (MCP sampling), storage from `sparda.json` + git.
-3. Write tools (POST/PUT/DELETE) are **disabled by default**. You opt in per tool in `sparda.json` — your choices survive re-runs.
+1. **The compiler.** `sparda ubg` (run implicitly by `review`/`apocalypse`/`mirror`) parses your codebase and SQL/Prisma schema (AST — 100% local, zero LLM) into a deterministic behavior graph: entrypoints, guards, effects, state, invariants, state machines. `sparda verify` proves the compiler's own laws (determinism, soundness, round-trip) on your input.
+2. **The proofs.** `review` and `apocalypse` discharge proof obligations over that graph; `mirror` executes it; `timeless` records/replays real requests against it.
+3. **The MCP layer.** `init` injects a tiny marked router (`/mcp`) into your app — fully reversible with `remove`. Tool calls run **inside your live app process** — warm DB pools, real auth chain, real data. Zero infrastructure: compute from your host process, intelligence from your AI client's own model (MCP sampling), storage from `sparda.json` + git.
 4. Suspicious docstrings are sanitized before they ever reach the AI (prompt-injection defense).
-5. `npx sparda-mcp doctor --app` audits your codebase for drift: it detects stale tools (IA seeing ghosts), unsynced routes, schema drift via fingerprints, and zombie configurations. High severity issues trigger a non-zero exit code for your CI pipeline.
-6. `npx sparda-mcp seed export/import` lets you package and share your app's "genome" (semantic memory, workflows, antibodies) securely, transferring immune memory between environments or across similar stacks with zero data leak.
-7. `npx sparda-mcp twin` starts a safe, simulated mock server of your backend on the original port. It serves GET calls from learned exemplars (observed response shapes & mock data) and returns simulated 202 writes without ever touching your real database or production APIs. Learn exemplars by running `npx sparda-mcp twin --learn`.
-8. `npx sparda-mcp grammar` maps the graph of valid sequences of tool calls (observed circuits and candidate hypotheses) to prevent LLM hallucination of routes.
-9. `npx sparda-mcp evolve` mutates candidate chains and tests them against the twin in-memory, promoting successful chains to evolved workflow suggestions.
 
-## What SPARDA gives your AI
+## The living organism — what runtime trust looks like
 
-### Operate, not just read
-Every route becomes a tool that runs against your live process — real auth, real data,
-warm connections. One call to **`sparda_get_context`** hands the AI the whole living
-picture: enabled tools, suggested workflows, runtime telemetry, quarantine state, and
-immune memory — so every session resumes where the last one stopped.
+The proof gate covers what AI *writes*. These organs cover what AI *does*, live:
 
 ### Write-safety: the AI can't write until you say so
 - Writes (POST/PUT/DELETE) ship **disabled**. Enable them per tool in `sparda.json`; your choice survives every re-init.
@@ -262,9 +223,10 @@ step's real response. Write routes are never absorbed — their per-call confirm
 always stands.
 
 ### Living context & telemetry
-`GET /mcp/stats` (per-tool calls/errors, tool "purity", quarantine state) and
-`GET /mcp/events` (errors, latency anomalies, cached diagnoses) expose exactly what
-your app is doing — surfaced to the AI as live notifications.
+One call to **`sparda_get_context`** hands the AI the whole living picture: enabled
+tools, suggested workflows, runtime telemetry, quarantine state, and immune memory —
+so every session resumes where the last one stopped. `GET /mcp/stats` and
+`GET /mcp/events` expose the same live picture over HTTP.
 
 ## Built for AI clients: the bundled Skill
 SPARDA ships with an Agent Skill ([`SKILL.md`](./SKILL.md)) that teaches any compatible
@@ -279,10 +241,10 @@ runtime, so the guidance never goes stale.
 - **Next.js App Router (13/14/15)** — file-based injection. Since Next.js uses file-system routing, SPARDA simply creates a catch-all route handler under `app/mcp/[...sparda]/route.js`. **Nothing in your existing codebase's code is touched**; running `remove` simply deletes the generated file.
 - **Express 4/5** (JS/TS, ESM/CJS) — AST-based router injection.
 - **FastAPI** (Python >= 3.9) — AST-based router injection.
+- **Any backend with an OpenAPI spec** — `--openapi api.json` lowers the spec into the same behavior graph, so `review`, `apocalypse`, `mirror` and `openapi` work on Go, Rails, Java, .NET… without a parser.
 
 ## Security posture (honest)
 - 4 runtime dependencies, exact-pinned.
-- **Dynamic Local Key Resolution.** The generated router contains no baked secrets. It resolves authorization keys at runtime from the `SPARDA_LOCAL_KEY` environment variable or the local gitignored `.sparda/key` file, and fails closed (503) when neither is found. For custom production or staging setups, you can override this behavior by exposing `SPARDA_LOCAL_KEY` in your environment.
 - Local key on every router call; self-reference loop protection; 30s timeouts; 8 KB output truncation.
 - AST-positioned injection with backup and post-injection re-parse; `npx sparda-mcp remove` leaves a clean git diff.
 - Persistence is **value-free**: SPARDA records structure (tool names, field names, fingerprints), never your payloads.

package/SKILL.md

@@ -1,32 +1,42 @@
 ---
 name: sparda-mcp
 description: >-
-  Drive a SPARDA compiled Behavior Runtime to its full potential. Use this whenever
-  you are connected to a backend running the SPARDA Runtime (compiled into a Unified
-  Behavior Graph - UBG) — recognizable by the tools `sparda_get_context`, `sparda_info`,
-  `sparda_confirm`, or composite tools. It teaches the graph-context-first workflow,
-  how to exploit the response-recycling flywheel, the circuit-breaker, crystallized
-  circuits, offline Twin simulations, and the two-phase confirm protocol for writes.
+  Drive a SPARDA-generated MCP server to its full potential. Use this whenever
+  you are connected to an MCP server built by SPARDA (sparda-mcp) — recognizable
+  by the tools `sparda_get_context`, `sparda_info`, `sparda_confirm`, or composite
+  tools labelled "[Labs circuit]". It teaches the call-context-first workflow, how
+  to exploit the response-recycling flywheel, the circuit-breaker, crystallized
+  circuits and adaptive immunity, and the mandatory two-phase confirm protocol for
+  write tools. Reach for it before calling raw endpoints, before any write, or when
+  a tool returns 202 (awaiting confirmation) or 503 (quarantined).
 ---
 
-# Driving a SPARDA Behavior Runtime
+# Driving a SPARDA MCP server
 
-A SPARDA server is driven by a compiled **Unified Behavior Graph (UBG)** — the graph SPARDA's compiler produces from the host application's states, transitions, permissions, and side-effects, serialized under the **SBIR** specification. Instead of exposing raw, disconnected endpoints, SPARDA compiles the app into a deterministic behavioral model. The local **SPARDA Runtime** dynamically executes this graph inside the live host process, powering the MCP interface, the Twin simulation clone, and the Immune system offline.
-
-> This skill covers the **runtime** (driving a live MCP server). The same graph also powers dev-time compiler commands you run in the app's repo — `sparda ubg` (compile), `apocalypse` (prove the deploy), `timeless` (record/replay a request), `heal` (prove a fix), `mirror` (serve the graph), `verify` (prove the compiler's laws). Those are CLI, not MCP tools; see the project README.
+A SPARDA server is **not** a flat list of HTTP endpoints. SPARDA injected a live
+`/mcp` router *inside a real running app*, so its tools are that app's actual
+routes — wrapped in an intelligence layer that makes repeated use **cheaper** (it
+recycles stable answers from memory) and **safer** (it quarantines failing tools
+and gates writes behind human confirmation). This is the runtime half of SPARDA's
+trust layer — "AI writes. SPARDA proves." — the same engine that proves PRs and
+deploys (`sparda review` / `apocalypse`) also guards what you *do* to the live app.
+Used naively it's just an API. Used well, it gets faster and safer the more you
+call it. This skill is how to use it well.
 
 ## Rule 0 — call `sparda_get_context` first, every session
 
-Before anything else, call **`sparda_get_context`** (no params). It returns the *live* state of the SPARDA Behavior Graph:
+Before anything else, call **`sparda_get_context`** (no params). It returns the
+*live* picture, so you never guess the surface:
 
-- the active routes/tools, workflows, and type-propagated schemas;
-- `runtime` — current stats (calls, errors, quarantine states, Twin mode active);
-- the last ~20 **events** (errors, latency anomalies, immune alerts);
-- **immune memory** (cached antibodies and error diagnoses);
-- **recycling** metrics (flywheel memory hit rates);
-- a `behavior` snapshot of stable variables.
+- the enabled tools + their descriptions, and SPARDA's suggested **workflows**;
+- `runtime` — current `/mcp/stats` (per-tool call/error counts, tool "purity",
+  quarantine state);
+- the last ~20 **events** (errors, latency anomalies, immune diagnoses);
+- **immune memory** (known failure signatures + cached fixes);
+- **recycling** stats (how many calls were served from memory);
+- a `behavior` snapshot (which response fields are stable).
 
-Read it to orient yourself inside the graph. `sparda_info` gives a lighter summary of counts.
+Read it before acting. `sparda_info` gives a lighter summary if you only need counts.
 
 ## The tools you'll see
 
@@ -76,16 +86,6 @@ adapt — don't blindly retry the same call.
 **5. Latency anomalies.** A call far slower than a tool's own baseline surfaces as
 an `immune` event in `/mcp/events`. Treat it as a hint to back off or warn the user.
 
-**6. Twin Simulation Mode — practice safely on a clone.**
-When `/mcp/stats` or `sparda_get_context.runtime` contains `"twin": true`, you are connected to a safe, in-memory mock clone of the application.
-- All GET reads return learned exemplars (observed response shapes and mock values).
-- All write tools return simulated `202` echoes but do not write to database or external APIs.
-- Use this twin mode to practice multi-step workflows, debug tool sequences, and test your plans without touching the live production backend.
-
-**7. Grammar & Evolution — discover optimal workflows.**
-- You can query or contribute to the app's grammar (`.sparda/grammar.json`). The grammar maps valid sequences of tool calls (edges).
-- Running `sparda evolve` mutates and runs candidate chains against the twin. The successful evolved sequences are suggested as mid-session workflows.
-
 ## Writing safely — the mandatory two-phase protocol
 
 Writes are **disabled by default**. The protocol is not optional:
@@ -138,15 +138,6 @@ Writes are **disabled by default**. The protocol is not optional:
 - **General health** → `sparda doctor` checks Node version, framework detection,
   manifest validity, the semantic/immune cache, host reachability, and quarantine;
   it exits non-zero so it can gate CI.
-- **Formal Deployment Proof** → `sparda apocalypse` reads the compiled graph (`ubg.json`) and proves five correctness obligations: catches unguarded mutations, non-atomic aggregate writes, unvalidated writes to constrained tables, uncompensated observable effects, and aggregate root bypasses. Run `sparda apocalypse --save-baseline` to store the reference graph; subsequent runs diff against the baseline to catch dropped guards, dropped SQL invariants, or grown blast radiuses.
-- **OpenAPI Ingestion** → Run `sparda ubg --openapi <openapi_spec.json>` to compile any non-JS/Python backend (Go, Java, Rails, Laravel, .NET) into a Unified Behavior Graph by mapping security schemes into guards and request/response structures. (JSON specs only — convert YAML once with `npx -y js-yaml spec.yaml > spec.json`.)
-- **Executing the Graph (No code mock)** → Run `sparda mirror` to host a mock HTTP simulation server directly from `ubg.json` without any backend code. Enforces authentication guards, returns typed responses, and acts as a contract sandbox.
-- **Exporting OpenAPI 3.1 Spec** → Run `sparda openapi` to generate a valid, deterministic OpenAPI 3.1 spec dynamically from the compiled behavior graph.
-- **Self-Verification** → Run `sparda verify` to test the compiler's own invariants (byte-determinism, soundness, and spec round-trip) to guarantee trust.
-- **Time-Travel Debugging** → `sparda timeless` records a production request's nondeterminism (db, http, clock, random, uuid) and replays it byte-identically against current code. `sparda timeless replay <id>` re-flies it; `sparda timeless export <id>` turns the bug into a vitest test. Recording is opt-in in the app (deterministic sampling + GDPR redaction built in).
-- **Self-Healing, Proven** → `sparda heal <id>` builds a fix brief from the graph, then `--check --expect '{"status":200}'` gates a candidate fix on three axes at once: the recorded flight now returns the expected response (not the bug), `verify` still passes, and `apocalypse` finds no new critical/high and no removed guard. The gate is honest both ways — an unfixed bug keeps it closed (exit 1).
-- **Clone learning / Transfer sémantique** → Use `sparda seed export` to package your app's descriptions, workflows, and antibodies. Then `sparda seed import --germinate` in another clone to import the structure and germinate simulated twin instances.
-- **Learn exemplars** → Start your live app and run `sparda twin --learn` to fetch actual response data and construct `.sparda/twin.json` locally.
 
 ---
 *This skill ships with `sparda-mcp` and is regenerated from SPARDA's capability

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sparda-mcp",
-  "version": "0.13.3",
+  "version": "0.14.1",
   "mcpName": "io.github.zyx77550/sparda-mcp",
   "description": "Compile backends to behavior graphs. Statically prove security, simulate APIs, and replay bugs.",
   "type": "module",

package/src/commands/apocalypse.js

@@ -16,7 +16,7 @@ import { atomicWriteFileSync as atomicWrite } from '../server/persistence.js';
 const ICONS = { critical: '✗', high: '✗', medium: '⚠', info: '·' };
 
 export async function runApocalypse(opts) {
-  const { graph } = compileUBG(opts.cwd, { write: false });
+  const { graph, report } = compileUBG(opts.cwd, { write: false });
   const canonical = canonicalizeGraph(graph);
   const baselinePath = path.join(opts.cwd, '.sparda', 'ubg.baseline.json');
 
@@ -42,7 +42,7 @@ export async function runApocalypse(opts) {
   }
 
   const findings = [...staticFindings, ...diffFindings];
-  const verdict = verdictOf(findings);
+  const verdict = verdictOf(findings, canonical);
 
   if (opts.sarif) {
     const sarifPath = path.join(opts.cwd, '.sparda', 'apocalypse.sarif');
@@ -64,7 +64,21 @@ export async function runApocalypse(opts) {
       console.log(`  ${ICONS[f.severity]} [${f.severity}] ${f.rule} — ${f.message}`);
       if (opts.verbose) for (const ev of f.evidence) console.log(`      evidence: ${ev}`);
     }
-    if (verdict.clean) {
+    if (!verdict.provable) {
+      console.log(
+        `✗ NO PROOF — 0 routes reached. SPARDA could not see this app's surface (a parser-coverage gap, not a clean bill of health); an empty graph proves nothing. This is NOT a pass — run with --verbose to see what was skipped.`,
+      );
+      if (opts.verbose) {
+        console.log(`      detected: ${report.framework} · entry ${report.entry}`);
+        if (report.skipped?.length)
+          for (const s of report.skipped)
+            console.log(`      skipped: ${s.reason}${s.file ? ` (${s.file})` : ''}`);
+        else
+          console.log(
+            `      no route call sites reached — routes are likely registered indirectly (a loader / DI pattern the static walk can't follow).`,
+          );
+      }
+    } else if (verdict.clean) {
       console.log(
         `✓ PROVEN — ${obligations} obligation(s) discharged, zero violations. No declared guard, invariant, transaction or aggregate boundary can be broken by this tree.`,
       );

package/src/commands/mirror.js

@@ -29,14 +29,27 @@ export async function runMirror(opts) {
     server.listen(port, '127.0.0.1', resolve);
   });
 
+  const stateful = routes.filter((r) => r.transitions.length || r.reflect);
   console.log(
-    `MIRROR — the graph is serving. ${routes.length} entrypoint(s) on http://127.0.0.1:${port}`,
+    `MIRROR — the graph is serving. ${routes.length} entrypoint(s) on http://127.0.0.1:${port}` +
+      (stateful.length ? ` · ${stateful.length} live the inferred lifecycle` : ''),
   );
   for (const r of routes) {
-    console.log(
-      `  ${r.method.toUpperCase().padEnd(6)} ${r.path}${r.guarded ? '  🔒 ' + r.guards.join(',') : ''}${r.returns ? '  → {' + Object.keys(r.returns).join(', ') + '}' : ''}`,
-    );
+    const guard = r.guarded ? '  🔒 ' + r.guards.join(',') : '';
+    const shape = r.returns ? '  → {' + Object.keys(r.returns).join(', ') + '}' : '';
+    const life = r.transitions.length
+      ? '  ⟳ ' + r.transitions.map((t) => `${t.field}:${t.from}→${t.to}`).join(', ')
+      : r.reflect
+        ? `  ↩ reflects ${r.reflect.field}`
+        : '';
+    console.log(`  ${r.method.toUpperCase().padEnd(6)} ${r.path}${guard}${shape}${life}`);
   }
-  console.log('  (every response carries x-sparda-mirror: true — Ctrl+C to stop)');
+  console.log(
+    '  (every response carries x-sparda-mirror: true' +
+      (stateful.length
+        ? '; ⟳ routes enforce the state machine (409 on illegal moves)'
+        : '') +
+      ' — Ctrl+C to stop)',
+  );
   return { server, routes, port };
 }

package/src/commands/remove.js

@@ -54,6 +54,24 @@ export async function runRemove(opts) {
         `✗ Could not safely remove from ${r.file} — restore from .sparda/backup/`,
       );
   }
+
+  // Hard rule #4 safety: if any injected file could NOT be cleanly reverted, STOP before
+  // any destructive cleanup. Deleting `.sparda/` here would erase the very `.sparda/backup/`
+  // we just told the operator to restore from — so nothing is removed until the tree is
+  // known-clean. The manifest and backups stay put for a manual (or retried) recovery.
+  const failed = results.filter((r) => !r.ok);
+  if (failed.length) {
+    console.log(
+      `\n✗ ${failed.length} file(s) could not be reverted automatically. Nothing else was deleted —` +
+        ` sparda.json, generated files and .sparda/backup/ are preserved.`,
+    );
+    console.log(
+      '  Restore the file(s) above from .sparda/backup/, then re-run `npx sparda-mcp remove`.',
+    );
+    process.exitCode = 1;
+    return { removed: false, failed: failed.map((r) => r.file) };
+  }
+
   for (const f of manifest.generatedFiles ?? []) {
     const abs = path.resolve(opts.cwd, f);
     if (fs.existsSync(abs)) {
@@ -85,6 +103,7 @@ export async function runRemove(opts) {
   fs.rmSync(path.join(opts.cwd, '.sparda'), { recursive: true, force: true });
   console.log('✓ Deleted sparda.json and .sparda/');
   console.log('\nSPARDA removed. `git diff` should be clean.');
+  return { removed: true };
 }
 
 // Undo exactly what init's ensureGitignore did (recorded in the manifest),