CLAUDE.md

1# CLAUDE.md — AI session entry point
2 
3SPARDA is **the trust layer for AI-written code** — "AI writes. SPARDA proves."
4(ADR-033). Under the hood it is a behavior compiler: backend (code + schema) →
5deterministic UBG → proofs (`review`, `apocalypse`), an executable mock
6(`mirror`), deterministic replay (`timeless`/`heal`). The MCP layer is the same
7trust story at runtime: it parses an Express/FastAPI/Next app (AST), injects a
8reversible `/mcp` router *inside the live process*, and bridges it to MCP
9clients over stdio. Zero infra, zero budget: compute from the host process,
10intelligence from the client's own LLM (MCP sampling), storage from
11`sparda.json` + git.
12 
13## Start here, every session
14 
151. Read `docs/HANDOFF.md` — current state: what is done, not done, and next.
162. Read the doc that matches your task (map in `docs/README.md`).
173. Before touching code that failed before, check `docs/ERRORS.md`.
184. Big-picture questions (tiers, rounds, monetization) → `ROADMAP.md`.
19 
20**🚢 PUBLISHING ANYTHING? Read `docs/MASTER-PLAN-RELEASE.md` first, in full.**
21npm, the VS Code Marketplace, the MCP registry, a tag — all four go through
22that playbook, in that order. Every step in it has already been done wrong
23once and carries the error number to prove it. Do not improvise a release.
24 
25**Offload, don't memorise.** Your context is finite and this project's history
26is not. Durable facts go INTO the docs (`ERRORS.md`, `DECISIONS.md`,
27`HANDOFF.md`, the Obsidian vault); old facts come OUT of them by grep, never
28by reconstruction. Do not read `DECISIONS.md` or `ERRORS.md` whole — they are
29100+ entries each, and saturating your own context is how confident wrong
30process decisions get made.
31 
32**Before ending a session that changed anything:** update `docs/HANDOFF.md`
33and append a session record in `docs/sessions/` (use `TEMPLATE.md`).
34This is how context survives between sessions — never skip it.
35 
36## Commands
37 
38```bash
39npm test                       # vitest, full suite — must be green before any push
40npm run mutation               # 128 mutants — all must die before any push (rule 12)
41npm run release:check          # the RELEASE gate (ADR-087) — green suite ≠ releasable
42                               # full procedure: docs/MASTER-PLAN-RELEASE.md
43npx vitest run -t "quarantine" # single test by name
44node src/index.js init|dev|sync|hook|remove|doctor   # the CLI, from a target app dir
45```
46 
47Tests need Node >= 18 and Python >= 3.9 (FastAPI parser fixtures).
48 
49## Architecture in one breath
50 
51`init`: `detect.js` (framework/entry/port) → `parser/` (routes via AST) →
52`security/sanitize.js` (docstring defense) → `generator/` (render
53`templates/*.txt` → router file, inject marked block into entry, write
54`sparda.json`). `dev`: `server/stdio.js` bridges MCP stdio ↔ the injected
55router's HTTP endpoints (`/mcp/tools|invoke|stats|events`). Details and the
56`sparda.json` schema: `docs/ARCHITECTURE.md`.
57 
58## Hard rules (violating these breaks the product — see docs/DECISIONS.md)
59 
601. **The host never pays for SPARDA's intelligence.** Nothing heavy on the
61   request path; ring buffers bounded; LLM only on surprise, never required.
622. **stdout is the MCP protocol.** Human logs go to stderr, always.
633. **Write tools are disabled by default** (write-safety); user opt-in only.
644. **`sparda remove` must leave a byte-for-byte clean diff.** Injection is
65   marked, idempotent, backed up, re-parsed after every modification.
665. **Carry-over is sacred:** `localKey`, per-tool `enabled`, `semantic`,
67   `immune`, and `labs` survive re-init. Never regenerate them.
686. **Templates must stay valid in all variants** (JS/TS × ESM/CJS, Python).
69   Placeholders like `__ANY_TYPE__` exist for TS — keep them consistent.
707. **Every LLM output is sanitized** (`sanitizeDescription`) before it is
71   stored or shown to a client. No exceptions.
728. **No new runtime dependency without an entry in `docs/DECISIONS.md`.**
73   Currently 4, exact-pinned — that is a selling point.
749. **A registration is MODELLED or DECLARED — never dropped.** Every `continue`
75   in a registration dispatch either registers something or emits an
76   `UnknownHandler` + a high-risk blind spot. Silence is how a real endpoint
77   earns a false PROVEN (ADR-079, SOUNDNESS Direction 3).
7810. **An oracle may not import an extractor.** `oracle-static.js` and the
79   sealing certificates check the analyser against a SECOND implementation;
80   one that reuses the analyser's walk is a mirror, and confirms bugs instead
81   of finding them (ADR-082).
8211. **A guarantee is universal or it is false.** ANY module that grades a compiled
83   graph MUST call `premiseFor` — a command, the MCP tool, a bench, the corpus
84   oracle. "Grades" means it calls anything in `GRADERS`
85   (`tests/premise-wired-everywhere.test.js`): `verdictOf`, `badgeFor`, **and
86   `buildCapsule`** — the capsule states `proven` in the artifact that TRAVELS.
87   An organ reachable from some consumers buys confidence it has not earned, and
88   a rule scoped to one directory — or to one function name — repeats the same
89   mistake one level up; both times the gap was the size of the scope
90   (ADR-083 + amendment, ADR-093).
9112. Tests green (`npm test`) **and** mutants dead (`npm run mutation`) before
92   commit; new behavior ships with tests, new soundness-critical lines ship
93   with a killing mutant.
9413. **Put the admission INSIDE the number, never beside it.** Anything a reader acts
95   on — a score, a verdict word, an `ok`, a percentage — must be able to say "I don't
96   know" IN ITSELF (`null`, never `0`/`false`/`1`-with-a-note). Five leaks had the
97   honest field present and the headline lying (SOUNDNESS 3d, ADR-092). New headline
98   field → new row in `tests/unmeasured-is-not-a-pass.test.js`, and the row owes TWO
99   assertions: EXPRESSIBLE (the field can hold `null`) **and REACHABLE** (a real call
100   path produces it). ADR-092 was tested and wired to nothing for a whole release
101   because only the first was checked (E-106, SOUNDNESS 3e).
10214. **A green suite licenses a COMMIT, never a RELEASE.** Publishing goes through
103   `npm run release:check` — which commit, which tag, which manifests, which
104   CHANGELOG entry are all unverified until something checks them, and v0.69.0
105   shipped a half-state with every test passing (ADR-087, E-096). No escape hatch.
106 
107## Conventions
108 
109- ESM everywhere, Node >= 18 compatible (no `??=` worries, but check vitest ^3).
110- User-facing errors: `Object.assign(new Error(msg), { code: 'USER', hint })`.
111- Comments explain *constraints*, not narration; match existing density.
112- Commit style: `feat(scope):`, `fix(scope):`, `docs:`, `chore:`.
113