sparda-mcp 0.7.1 → 0.8.1

package/README.md

@@ -107,6 +107,9 @@ What we *don't* promise: the honest limits in [docs/SECURITY.md](./docs/SECURITY
 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
 

package/SKILL.md

@@ -84,6 +84,16 @@ 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:
@@ -136,6 +146,8 @@ 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.
+- **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.7.1",
+  "version": "0.8.1",
   "mcpName": "io.github.zyx77550/sparda-mcp",
   "description": "Turn any codebase into an MCP server with one command. Express & FastAPI → Claude-ready in 3 minutes.",
   "type": "module",

package/src/commands/doctor.js

@@ -3,6 +3,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { detectStack } from '../detect.js';
 import { buildNegentropy, renderNegentropy } from './negentropy.js';
+import { resolveSpardaKey } from '../generator/manifest.js';
 
 // Returns { healthy } so the CLI can exit non-zero on any ✗ — scripts/CI can
 // gate on `sparda doctor` (E-012). Informational '·' lines never fail it.
@@ -55,18 +56,19 @@ export async function runDoctor(opts) {
       );
 
       if (stack) {
-        const headers = { 'x-sparda-key': m.localKey };
+        const key = resolveSpardaKey(opts.cwd, m);
+        const headers = { 'x-sparda-key': key };
         try {
           const r = await fetch(`http://127.0.0.1:${m.port}/mcp/tools`, {
             headers,
-            signal: AbortSignal.timeout(1500),
+            signal: AbortSignal.timeout(5000),
           });
           if (!r.ok) {
             fail(`  ✗ Host app on :${m.port} answered ${r.status}`);
           } else {
             const s = await fetch(`http://127.0.0.1:${m.port}/mcp/stats`, {
               headers,
-              signal: AbortSignal.timeout(1500),
+              signal: AbortSignal.timeout(5000),
             })
               .then((x) => (x.ok ? x.json() : null))
               .catch(() => null);

package/src/commands/evolve.js

@@ -0,0 +1,151 @@
+// commands/evolve.js — R3.4, Darwin/Baldwin: mutate candidate chains from the
+// grammar's hypotheses, trial them against the TWIN (never the host — ADR-021
+// §5), and let the survivors land as SUGGESTIONS: `labs.circuits` entries with
+// `seen: 0` and `evolved: true`. They are not composites and never become one
+// here — crystallization still demands the real observation threshold. An
+// emergent capability is a suggestion until reality confirms it (survival §1).
+import fs from 'node:fs';
+import path from 'node:path';
+import { buildGrammar } from './grammar.js';
+import { createTwinServer, twinFilePath } from './twin.js';
+import { findByKey } from '../server/crystallize.js';
+import { mergeManifestKeySync } from '../server/persistence.js';
+import { resolveSpardaKey } from '../generator/manifest.js';
+
+const MAX_CANDIDATES_PER_RUN = 10;
+
+// pure: hypothesis edges that no observed circuit already covers → candidates
+export function candidateChains(grammar, circuits = {}) {
+  const out = [];
+  for (const e of grammar.edges ?? []) {
+    if (e.source !== 'hypothesis') continue;
+    const key = `${e.from}>${e.to}`;
+    if (circuits[key]) continue; // reality (or a past run) got there first
+    if (out.some((c) => c.key === key)) continue;
+    out.push({
+      key,
+      steps: [e.from, e.to],
+      links: [{ from: e.from, to: e.to, arg: e.arg, fromKey: e.fromKey }],
+    });
+    if (out.length >= MAX_CANDIDATES_PER_RUN) break;
+  }
+  return out;
+}
+
+// trial one candidate against a running twin: A answers, the linked key is
+// really there, B accepts the fed value. All against the ghost, never the host.
+export async function trialCandidate(candidate, { port, localKey }) {
+  const invoke = async (tool, args) => {
+    const res = await fetch(`http://127.0.0.1:${port}/mcp/invoke`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', 'x-sparda-key': localKey },
+      body: JSON.stringify({ tool, args }),
+      signal: AbortSignal.timeout(5000),
+    });
+    return res.json();
+  };
+  const [a, b] = candidate.steps;
+  const link = candidate.links[0];
+  const first = await invoke(a, {});
+  if (first?.upstreamStatus !== 200)
+    return { ok: false, why: `${a} answered ${first?.upstreamStatus}` };
+  const fed = findByKey(first.data, link.fromKey);
+  if (fed === undefined)
+    return { ok: false, why: `'${link.fromKey}' not found in ${a}'s exemplar` };
+  if (typeof fed === 'object')
+    return { ok: false, why: `'${link.fromKey}' is not a scalar` };
+  const second = await invoke(b, { [link.arg]: fed });
+  if (second?.upstreamStatus !== 200)
+    return { ok: false, why: `${b} answered ${second?.upstreamStatus}` };
+  return { ok: true, fedValueType: typeof fed };
+}
+
+export async function runEvolve(opts) {
+  const manifestPath = path.join(opts.cwd, 'sparda.json');
+  if (!fs.existsSync(manifestPath)) {
+    throw Object.assign(new Error('sparda.json not found.'), {
+      code: 'USER',
+      hint: 'run `npx sparda-mcp init` first',
+    });
+  }
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+
+  const twinPath = twinFilePath(opts.cwd);
+  if (!fs.existsSync(twinPath)) {
+    throw Object.assign(
+      new Error(
+        'no twin memory (.sparda/twin.json) — evolution needs the ghost to practice on.',
+      ),
+      {
+        code: 'USER',
+        hint: 'run `npx sparda-mcp twin --learn` against the live app first',
+      },
+    );
+  }
+  let exemplars = {};
+  try {
+    exemplars = JSON.parse(fs.readFileSync(twinPath, 'utf8')).exemplars ?? {};
+  } catch {
+    throw Object.assign(new Error('.sparda/twin.json is not valid JSON.'), {
+      code: 'USER',
+      hint: 're-run `npx sparda-mcp twin --learn`',
+    });
+  }
+
+  const grammar = buildGrammar(manifest, exemplars);
+  const candidates = candidateChains(grammar, manifest.labs?.circuits ?? {});
+  if (!candidates.length) {
+    console.log(
+      '· Nothing to evolve — no untested hypothesis chains (grammar has no new guesses).',
+    );
+    return { survivors: [], failed: [] };
+  }
+
+  // the practice arena: an in-process twin on an ephemeral port
+  const localKey = resolveSpardaKey(opts.cwd, manifest);
+  const server = createTwinServer(manifest, localKey, exemplars);
+  const port = await new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', () => resolve(server.address().port));
+  });
+
+  const survivors = [];
+  const failed = [];
+  try {
+    for (const c of candidates) {
+      const verdict = await trialCandidate(c, { port, localKey });
+      if (verdict.ok) survivors.push(c);
+      else failed.push({ key: c.key, why: verdict.why });
+    }
+  } finally {
+    server.close();
+  }
+
+  if (survivors.length) {
+    manifest.labs ??= {};
+    manifest.labs.circuits ??= {};
+    const now = new Date().toISOString();
+    for (const c of survivors) {
+      manifest.labs.circuits[c.key] = {
+        steps: c.steps,
+        links: c.links,
+        seen: 0, // heredity without confirmation: reality still has to speak
+        evolved: true,
+        firstSeen: now,
+        lastSeen: now,
+      };
+    }
+    mergeManifestKeySync(manifestPath, 'labs', manifest.labs);
+  }
+
+  console.log(
+    `✓ Evolution run: ${candidates.length} candidate(s) trialed against the twin — ${survivors.length} survivor(s), ${failed.length} culled`,
+  );
+  for (const c of survivors)
+    console.log(
+      `  + suggested circuit: ${c.steps.join(' → ')} (seen: 0 — crystallizes only after real observations)`,
+    );
+  for (const f of failed) console.log(`  - culled ${f.key}: ${f.why}`);
+  console.log('  The host was never touched: every trial ran against the ghost.');
+  return { survivors, failed };
+}

package/src/commands/grammar.js

@@ -0,0 +1,138 @@
+// commands/grammar.js — R3.3, the Rosetta stone: which call sequences MEAN
+// something in this app. Derived, deterministic, never authoritative
+// (ADR-021 §4): observed edges come from Labs circuits (real data flows seen
+// N times); hypothesis edges come from twin exemplar response keys matching
+// another tool's param names — always labelled, never acted on by themselves.
+// The artifact lives in .sparda/grammar.json (regenerable, never committed).
+import fs from 'node:fs';
+import path from 'node:path';
+import { walkPayload } from '../server/condenser.js';
+import { atomicWriteFileSync as atomicWrite } from '../server/persistence.js';
+import { twinFilePath } from './twin.js';
+
+const MAX_HYPOTHESES = 50;
+const GRAMMAR_VERSION = 'sparda-grammar/v1';
+
+// bounded key harvest — same walk the condenser trusts, so what the grammar
+// hypothesizes is exactly what a composite could later re-feed
+export function responseKeysOf(exemplarData) {
+  const keys = new Set();
+  walkPayload(exemplarData, (k) => {
+    keys.add(k);
+    if (keys.size >= 40) return false;
+  });
+  return keys;
+}
+
+// pure: (manifest, exemplars|null) → the grammar
+export function buildGrammar(manifest, exemplars = null) {
+  const tools = manifest.tools ?? {};
+  const edges = [];
+  const seenEdge = new Set();
+  const edgeKey = (e) => `${e.from}>${e.to}:${e.arg}`;
+
+  // observed: the circuits ARE the sentences reality already spoke
+  const phrases = [];
+  for (const [key, cir] of Object.entries(manifest.labs?.circuits ?? {})) {
+    phrases.push({
+      key,
+      steps: cir.steps ?? [],
+      seen: cir.seen ?? 0,
+      crystallized: Boolean(cir.composite),
+      ...(cir.evolved ? { evolved: true } : {}),
+    });
+    for (const l of cir.links ?? []) {
+      const e = {
+        from: l.from,
+        to: l.to,
+        fromKey: l.fromKey,
+        arg: l.arg,
+        source: 'observed',
+      };
+      if (!seenEdge.has(edgeKey(e))) {
+        seenEdge.add(edgeKey(e));
+        edges.push(e);
+      }
+    }
+  }
+
+  // hypotheses: an exemplar of A answers with a key another tool B takes as a
+  // param → maybe A feeds B. A guess, said out loud as a guess.
+  if (exemplars) {
+    for (const [from, ex] of Object.entries(exemplars)) {
+      if (!tools[from] || ex?.data === undefined) continue;
+      const keys = responseKeysOf(ex.data);
+      for (const [to, t] of Object.entries(tools)) {
+        if (to === from || !t.enabled || t.method !== 'GET') continue;
+        for (const p of t.params ?? []) {
+          if (edges.length >= MAX_HYPOTHESES + seenEdge.size) break;
+          if (!keys.has(p.name)) continue;
+          const e = { from, to, fromKey: p.name, arg: p.name, source: 'hypothesis' };
+          if (seenEdge.has(edgeKey(e))) continue; // reality already confirmed it
+          seenEdge.add(edgeKey(e));
+          edges.push(e);
+        }
+      }
+    }
+  }
+
+  return {
+    version: GRAMMAR_VERSION,
+    builtAt: new Date().toISOString(),
+    nodes: Object.keys(tools),
+    edges,
+    phrases,
+  };
+}
+
+export async function runGrammar(opts) {
+  const manifestPath = path.join(opts.cwd, 'sparda.json');
+  if (!fs.existsSync(manifestPath)) {
+    throw Object.assign(new Error('sparda.json not found.'), {
+      code: 'USER',
+      hint: 'run `npx sparda-mcp init` first',
+    });
+  }
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+
+  let exemplars = null;
+  const twinPath = twinFilePath(opts.cwd);
+  if (fs.existsSync(twinPath)) {
+    try {
+      exemplars = JSON.parse(fs.readFileSync(twinPath, 'utf8')).exemplars ?? null;
+    } catch {
+      exemplars = null;
+    }
+  }
+
+  const grammar = buildGrammar(manifest, exemplars);
+  const outPath = path.join(opts.cwd, '.sparda', 'grammar.json');
+  fs.mkdirSync(path.dirname(outPath), { recursive: true });
+  atomicWrite(outPath, JSON.stringify(grammar, null, 2) + '\n');
+
+  const observed = grammar.edges.filter((e) => e.source === 'observed');
+  const hypotheses = grammar.edges.filter((e) => e.source === 'hypothesis');
+  console.log(`✓ Grammar written: .sparda/grammar.json — ${grammar.nodes.length} tools`);
+  if (grammar.phrases.length) {
+    console.log(`  Sentences reality has spoken (${grammar.phrases.length}):`);
+    for (const p of grammar.phrases.slice(0, 10))
+      console.log(
+        `    ${p.steps.join(' → ')} ×${p.seen}${p.crystallized ? ' (crystallized)' : ''}${p.evolved ? ' (evolved, unconfirmed)' : ''}`,
+      );
+  } else
+    console.log(
+      '  · no sentences observed yet — enable labs.recordSequences and use the app',
+    );
+  if (observed.length) console.log(`  Observed data flows: ${observed.length}`);
+  if (hypotheses.length) {
+    console.log(
+      `  Hypotheses from twin exemplars (${hypotheses.length}) — guesses, said as guesses:`,
+    );
+    for (const e of hypotheses.slice(0, 10))
+      console.log(`    ${e.from} —'${e.fromKey}'→ ${e.to}`);
+  } else if (!exemplars)
+    console.log(
+      '  · no hypotheses — run `sparda twin --learn` first to give the grammar eyes',
+    );
+  return { grammar };
+}

package/src/commands/negentropy.js

@@ -7,6 +7,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import crypto from 'node:crypto';
+import { resolveSpardaKey } from '../generator/manifest.js';
 
 // same fingerprint the generators stamp into sparding.toolFingerprints —
 // method|path|params, sha256/8. Divergence = the route's shape changed.
@@ -191,17 +192,17 @@ export function buildNegentropy({ manifest, currentRoutes, live, detectedPort, c
         `${f} is recorded in sparda.json but absent on disk — the organism has a memory of a body it no longer has`,
         'npx sparda-mcp init --yes (regenerates; carry-over keeps your state)',
       );
-    } else if (
-      manifest.localKey &&
-      !fs.readFileSync(abs, 'utf8').includes(manifest.localKey)
-    ) {
-      add(
-        'zombie',
-        'high',
-        'router/manifest key mismatch',
-        `${f} does not carry the manifest's localKey — a stale router from an older init is still wired in`,
-        'npx sparda-mcp init --yes',
-      );
+    } else {
+      const key = resolveSpardaKey(cwd, manifest);
+      if (key && !fs.readFileSync(abs, 'utf8').includes(key)) {
+        add(
+          'zombie',
+          'high',
+          'router/manifest key mismatch',
+          `${f} does not carry the manifest's localKey — a stale router from an older init is still wired in`,
+          'npx sparda-mcp init --yes',
+        );
+      }
     }
   }
 

package/src/commands/report.js

@@ -6,6 +6,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { c, gradient } from '../ui/style.js';
+import { resolveSpardaKey } from '../generator/manifest.js';
 
 // ── pure: manifest (+ optional live stats) → report data ──────────────────
 
@@ -342,9 +343,10 @@ export async function runReport(opts) {
   }
 
   let live = null;
-  if (manifest.port && manifest.localKey) {
+  const key = resolveSpardaKey(opts.cwd, manifest);
+  if (manifest.port && key) {
     live = await fetch(`http://127.0.0.1:${manifest.port}/mcp/stats`, {
-      headers: { 'x-sparda-key': manifest.localKey },
+      headers: { 'x-sparda-key': key },
       signal: AbortSignal.timeout(1500),
     })
       .then((x) => (x.ok ? x.json() : null))

package/src/commands/seed.js

@@ -272,6 +272,26 @@ export async function runSeed(opts, args) {
     console.log(
       '  Local knowledge always wins; keys, policies and enabled flags were never read.',
     );
+    // R4.5 full — germination: the derived organs regrow from the imported
+    // structure on THIS machine (values never travelled; they never do).
+    if (opts.germinate) {
+      const { buildGrammar } = await import('./grammar.js');
+      const { twinFilePath } = await import('./twin.js');
+      let exemplars = null;
+      try {
+        exemplars =
+          JSON.parse(fs.readFileSync(twinFilePath(opts.cwd), 'utf8')).exemplars ?? null;
+      } catch {
+        exemplars = null; // no local twin memory yet — grammar grows from structure alone
+      }
+      const grammar = buildGrammar(merged, exemplars);
+      const outPath = path.join(opts.cwd, '.sparda', 'grammar.json');
+      fs.mkdirSync(path.dirname(outPath), { recursive: true });
+      atomicWrite(outPath, JSON.stringify(grammar, null, 2) + '\n');
+      console.log(
+        `✓ Germinated: grammar regrown from the imported genome (${grammar.phrases.length} phrases, ${grammar.edges.length} edges) → .sparda/grammar.json`,
+      );
+    }
     return { report };
   }
 

package/src/commands/twin.js

@@ -0,0 +1,266 @@
+// commands/twin.js — R3.2, the holographic principle: reconstruct a living
+// mock of the app from its boundary (manifest structure + observed I/O).
+//
+// Two verbs, one value boundary (ADR-021):
+//   sparda twin --learn   asks the LIVE router once per eligible GET tool and
+//                         stores capped exemplars in .sparda/twin.json —
+//                         machine-local, gitignored, never the manifest.
+//   sparda twin           serves the clone: same routes, same /mcp surface,
+//                         answered from exemplars. Writes return 202 echoes
+//                         and touch nothing. Stop the app, run the twin, and
+//                         every agent exercises a ghost instead of the truth.
+import fs from 'node:fs';
+import path from 'node:path';
+import http from 'node:http';
+import { atomicWriteFileSync as atomicWrite } from '../server/persistence.js';
+import { resolveSpardaKey } from '../generator/manifest.js';
+
+const EXEMPLAR_CAP = 16384; // 16KB per exemplar — a shape, not an archive
+
+export function twinFilePath(cwd) {
+  return path.join(cwd, '.sparda', 'twin.json');
+}
+
+// ── learn: one real call per eligible tool, through the live router ────────
+
+export function eligibleForLearning(tool) {
+  return tool.enabled && tool.method === 'GET' && (tool.pathParams ?? []).length === 0;
+}
+
+export async function learnExemplars(manifest, localKey, fetchFn = fetch) {
+  let key = localKey;
+  if (typeof localKey === 'function') {
+    fetchFn = localKey;
+    key = undefined;
+  }
+  key = key ?? manifest.localKey ?? resolveSpardaKey(process.cwd(), manifest);
+
+  const exemplars = {};
+  const skipped = [];
+  for (const [name, t] of Object.entries(manifest.tools ?? {})) {
+    if (!eligibleForLearning(t)) {
+      skipped.push({
+        tool: name,
+        reason: !t.enabled
+          ? 'disabled'
+          : t.method !== 'GET'
+            ? 'write tool — a twin never learns from side effects'
+            : 'required path params — no observed values to fill them (v0.1)',
+      });
+      continue;
+    }
+    try {
+      const res = await fetchFn(`http://127.0.0.1:${manifest.port}/mcp/invoke`, {
+        method: 'POST',
+        headers: {
+          'content-type': 'application/json',
+          'x-sparda-key': key,
+        },
+        body: JSON.stringify({ tool: name, args: {} }),
+        signal: AbortSignal.timeout(10_000),
+      });
+      const payload = await res.json();
+      if (payload?.upstreamStatus === 200 && payload.data !== undefined) {
+        const raw = JSON.stringify(payload.data);
+        if (raw.length <= EXEMPLAR_CAP) {
+          exemplars[name] = { data: payload.data, learnedAt: new Date().toISOString() };
+        } else {
+          skipped.push({ tool: name, reason: `response over ${EXEMPLAR_CAP}B cap` });
+        }
+      } else {
+        skipped.push({
+          tool: name,
+          reason: `live call answered ${payload?.upstreamStatus ?? res.status}`,
+        });
+      }
+    } catch (err) {
+      skipped.push({ tool: name, reason: `unreachable: ${err.message}` });
+    }
+  }
+  return { exemplars, skipped };
+}
+
+// ── serve: the ghost — same routes, same /mcp surface, zero side effects ───
+
+function matchTool(manifest, method, pathname) {
+  for (const [name, t] of Object.entries(manifest.tools ?? {})) {
+    if (t.method !== method) continue;
+    const pattern = t.path.replace(/:(\w+)/g, '([^/]+)');
+    if (new RegExp(`^${pattern}$`).test(pathname)) return { name, tool: t };
+  }
+  return null;
+}
+
+export function createTwinServer(manifest, localKeyOrExemplars, maybeExemplars) {
+  let localKey = localKeyOrExemplars;
+  let exemplars = maybeExemplars;
+  if (
+    maybeExemplars === undefined &&
+    localKeyOrExemplars &&
+    typeof localKeyOrExemplars === 'object'
+  ) {
+    exemplars = localKeyOrExemplars;
+    localKey = resolveSpardaKey(process.cwd(), manifest);
+  }
+  const json = (res, status, obj) => {
+    res.writeHead(status, { 'content-type': 'application/json' });
+    res.end(JSON.stringify(obj));
+  };
+  const answerFor = (name) =>
+    (exemplars ?? {})[name]?.data !== undefined
+      ? exemplars[name].data
+      : {
+          __sparda_twin__: true,
+          tool: name,
+          note: 'no exemplar learned — run `sparda twin --learn` against the live app',
+        };
+
+  return http.createServer(async (req, res) => {
+    const url = new URL(req.url, 'http://127.0.0.1');
+    const pathname = url.pathname;
+
+    // the /mcp surface, so the unchanged bridge drives the ghost
+    if (pathname.startsWith('/mcp')) {
+      if (req.headers['x-sparda-key'] !== localKey)
+        return json(res, 401, { error: 'unauthorized' });
+      if (pathname === '/mcp/tools') return json(res, 200, manifest.tools ?? {});
+      if (pathname === '/mcp/stats')
+        return json(res, 200, {
+          twin: true,
+          uptimeSec: Math.round(process.uptime()),
+          stats: {},
+          quarantine: {},
+          recycle: { servedByCircle: 0, paidFull: 0, ratePct: 0 },
+          purity: {},
+        });
+      if (pathname === '/mcp/events')
+        return json(res, 200, { seq: 0, events: [], twin: true });
+      if (pathname === '/mcp/invoke' && req.method === 'POST') {
+        let body = '';
+        for await (const chunk of req) {
+          body += chunk;
+          if (body.length > 65536) return json(res, 413, { error: 'payload too large' });
+        }
+        let parsed;
+        try {
+          parsed = JSON.parse(body || '{}');
+        } catch {
+          return json(res, 400, { error: 'invalid JSON body' });
+        }
+        const spec = manifest.tools?.[parsed.tool];
+        if (!spec)
+          return json(res, 404, { error: `unknown tool: ${parsed.tool}`, twin: true });
+        if (spec.method !== 'GET')
+          return json(res, 200, {
+            upstreamStatus: 202,
+            data: {
+              __sparda_twin__: true,
+              echo: parsed.args ?? {},
+              note: 'twin: write acknowledged, nothing was touched',
+            },
+            twin: true,
+          });
+        return json(res, 200, {
+          upstreamStatus: 200,
+          data: answerFor(parsed.tool),
+          twin: true,
+        });
+      }
+      return json(res, 404, { error: 'not found', twin: true });
+    }
+
+    // the plain routes themselves, for anything that talks HTTP directly
+    const hit = matchTool(manifest, req.method, pathname);
+    if (!hit)
+      return json(res, 404, {
+        __sparda_twin__: true,
+        error: 'route not in the manifest',
+      });
+    if (hit.tool.method !== 'GET')
+      return json(res, 202, {
+        __sparda_twin__: true,
+        note: 'twin: write acknowledged, nothing was touched',
+      });
+    return json(res, 200, answerFor(hit.name));
+  });
+}
+
+// ── the command ─────────────────────────────────────────────────────────────
+
+export async function runTwin(opts, args) {
+  const manifestPath = path.join(opts.cwd, 'sparda.json');
+  if (!fs.existsSync(manifestPath)) {
+    throw Object.assign(new Error('sparda.json not found.'), {
+      code: 'USER',
+      hint: 'run `npx sparda-mcp init` first',
+    });
+  }
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  const localKey = resolveSpardaKey(opts.cwd, manifest);
+  const twinPath = twinFilePath(opts.cwd);
+
+  if (args.includes('--learn') || opts.learn) {
+    console.error(
+      '[sparda] twin: learning from the LIVE app (one call per eligible GET)...',
+    );
+    const { exemplars, skipped } = await learnExemplars(manifest, localKey);
+    const learned = Object.keys(exemplars).length;
+    if (!learned && skipped.every((s) => s.reason.startsWith('unreachable'))) {
+      throw Object.assign(
+        new Error(
+          `host unreachable on :${manifest.port} — the twin learns from the living.`,
+        ),
+        {
+          code: 'USER',
+          hint: 'start the app, then re-run `npx sparda-mcp twin --learn`',
+        },
+      );
+    }
+    fs.mkdirSync(path.dirname(twinPath), { recursive: true });
+    atomicWrite(
+      twinPath,
+      JSON.stringify(
+        { version: 'sparda-twin/v1', learnedAt: new Date().toISOString(), exemplars },
+        null,
+        2,
+      ),
+    );
+    console.log(
+      `✓ Twin learned ${learned} exemplar(s) → .sparda/twin.json (local only, never committed, never seeded)`,
+    );
+    for (const s of skipped) console.log(`  · skipped ${s.tool}: ${s.reason}`);
+    return { learned, skipped };
+  }
+
+  let exemplars = {};
+  if (fs.existsSync(twinPath)) {
+    try {
+      exemplars = JSON.parse(fs.readFileSync(twinPath, 'utf8')).exemplars ?? {};
+    } catch {
+      /* corrupt twin file → shape-only ghost, stated per answer */
+    }
+  }
+  const port = Number(opts.port) || manifest.port;
+  const server = createTwinServer(manifest, localKey, exemplars);
+  await new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(port, '127.0.0.1', resolve);
+  }).catch((err) => {
+    throw Object.assign(
+      new Error(
+        `cannot listen on :${port} — ${err.code === 'EADDRINUSE' ? 'the real app is still running there' : err.message}`,
+      ),
+      {
+        code: 'USER',
+        hint: 'stop the app first (the twin replaces it), or pass --port <n>',
+      },
+    );
+  });
+  console.log(
+    `✓ Twin serving on :${port} — ${Object.keys(exemplars).length} exemplar(s), writes are 202 echoes, the real app is untouched`,
+  );
+  console.log(
+    '  Connect the bridge as usual (`npx sparda-mcp dev`) — it cannot tell the ghost from the flesh.',
+  );
+  return { server, port };
+}

package/src/generator/express.js

@@ -5,7 +5,7 @@ import crypto from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 import { parse } from '@babel/parser';
 import { toolNameFor } from '../parser/express.js';
-import { carryOverManifest, defaultSpardingMemory } from './manifest.js';
+import { carryOverManifest, defaultSpardingMemory, ensureSpardaKey } from './manifest.js';
 import { atomicWriteFileSync as atomicWrite } from '../server/persistence.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -58,7 +58,7 @@ export function generateExpress({ cwd, entryFile, moduleType, port, routes }) {
   sparding.toolFingerprints = newFingerprints;
 
   // stable across re-runs so a running bridge/host pair never desyncs
-  const localKey = prev?.localKey ?? crypto.randomUUID();
+  const localKey = ensureSpardaKey(cwd, prev);
   const entryAbs = path.resolve(cwd, entryFile);
   const entryDir = path.dirname(entryAbs);
   const ext = entryFile.endsWith('.ts')
@@ -111,7 +111,10 @@ export function generateExpress({ cwd, entryFile, moduleType, port, routes }) {
     )
     .replace('__JSON_MW__', "express.json({ limit: '64kb' })")
     .replace('__TOOLS_JSON__', JSON.stringify(tools, null, 2))
-    .replace('__LOCAL_KEY__', localKey)
+    .replace(
+      '__FS_IMPORT__',
+      isESM ? "import spardaFs from 'node:fs';" : "const spardaFs = require('node:fs');",
+    )
     .replace('__PORT__', String(port))
     .replace(/__REQ_TYPE__/g, reqType)
     .replace(/__RES_TYPE__/g, resType)
@@ -150,7 +153,15 @@ export function generateExpress({ cwd, entryFile, moduleType, port, routes }) {
     ...(prev?.labs ? { labs: prev.labs } : {}),
     sparding,
   };
-  atomicWrite(path.join(cwd, 'sparda.json'), JSON.stringify(manifest, null, 2) + '\n');
+  // ADR-022: the disk copy NEVER carries the key — it lives in .sparda/key
+  // (written by ensureSpardaKey above). The in-memory return keeps it for
+  // this process only.
+  const manifestOnDisk = { ...manifest };
+  delete manifestOnDisk.localKey;
+  atomicWrite(
+    path.join(cwd, 'sparda.json'),
+    JSON.stringify(manifestOnDisk, null, 2) + '\n',
+  );
 
   return {
     tools,

package/src/generator/fastapi.js

@@ -5,7 +5,7 @@ import crypto from 'node:crypto';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { toolNameFor } from '../parser/express.js';
-import { carryOverManifest, defaultSpardingMemory } from './manifest.js';
+import { carryOverManifest, defaultSpardingMemory, ensureSpardaKey } from './manifest.js';
 import { atomicWriteFileSync as atomicWrite } from '../server/persistence.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -65,7 +65,7 @@ export function generateFastAPI({
   sparding.toolFingerprints = newFingerprints;
 
   // stable across re-runs so a running bridge/host pair never desyncs
-  const localKey = prev?.localKey ?? crypto.randomUUID();
+  const localKey = ensureSpardaKey(cwd, prev);
   const entryAbs = path.resolve(cwd, entryFile);
   const entryDir = path.dirname(entryAbs);
   const routerFileName = 'sparda_router.py';
@@ -84,7 +84,6 @@ export function generateFastAPI({
       '__SPARDING_POLICIES__',
       JSON.stringify(JSON.stringify(sparding.policies ?? {})),
     )
-    .replace('__LOCAL_KEY__', localKey)
     .replace('__PORT__', String(port));
 
   atomicWrite(routerAbs, tpl);
@@ -124,7 +123,15 @@ export function generateFastAPI({
     sparding,
   };
 
-  atomicWrite(path.join(cwd, 'sparda.json'), JSON.stringify(manifest, null, 2) + '\n');
+  // ADR-022: the disk copy NEVER carries the key — it lives in .sparda/key
+  // (written by ensureSpardaKey above). The in-memory return keeps it for
+  // this process only.
+  const manifestOnDisk = { ...manifest };
+  delete manifestOnDisk.localKey;
+  atomicWrite(
+    path.join(cwd, 'sparda.json'),
+    JSON.stringify(manifestOnDisk, null, 2) + '\n',
+  );
 
   return {
     tools,

package/src/generator/manifest.js

@@ -1,6 +1,40 @@
 // generator/manifest.js — carry user state across re-runs of `sparda init`
 import fs from 'node:fs';
 import path from 'node:path';
+import crypto from 'node:crypto';
+
+export function resolveSpardaKey(cwd, prevManifest = null) {
+  if (process.env.SPARDA_LOCAL_KEY) {
+    return process.env.SPARDA_LOCAL_KEY;
+  }
+  const spardaDir = path.join(cwd, '.sparda');
+  const keyFile = path.join(spardaDir, 'key');
+  if (fs.existsSync(keyFile)) {
+    try {
+      const key = fs.readFileSync(keyFile, 'utf8').trim();
+      if (key) return key;
+    } catch {}
+  }
+  if (prevManifest && prevManifest.localKey) {
+    try {
+      fs.mkdirSync(spardaDir, { recursive: true });
+      fs.writeFileSync(keyFile, prevManifest.localKey, 'utf8');
+    } catch {}
+    return prevManifest.localKey;
+  }
+  return null;
+}
+
+export function ensureSpardaKey(cwd, prevManifest = null) {
+  let key = resolveSpardaKey(cwd, prevManifest);
+  if (!key) {
+    key = crypto.randomUUID();
+    const spardaDir = path.join(cwd, '.sparda');
+    fs.mkdirSync(spardaDir, { recursive: true });
+    fs.writeFileSync(path.join(spardaDir, 'key'), key, 'utf8');
+  }
+  return key;
+}
 
 // Re-running init must not wipe what the user (or the semantic/immune/Labs
 // passes) wrote into sparda.json: per-tool `enabled` overrides, the cached

package/src/generator/nextjs.js

@@ -9,7 +9,7 @@ import crypto from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 import { toolNameFor } from '../parser/express.js';
 import { ensureGitignore } from './express.js';
-import { carryOverManifest, defaultSpardingMemory } from './manifest.js';
+import { carryOverManifest, defaultSpardingMemory, ensureSpardaKey } from './manifest.js';
 import { atomicWriteFileSync as atomicWrite } from '../server/persistence.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -60,7 +60,7 @@ export function generateNext({ cwd, appDir, port, routes }) {
   sparding.toolFingerprints = newFingerprints;
 
   // stable across re-runs so a running bridge/host pair never desyncs
-  const localKey = prev?.localKey ?? crypto.randomUUID();
+  const localKey = ensureSpardaKey(cwd, prev);
 
   // .js on purpose: Next enables allowJs in the tsconfig it manages, so the
   // generated handler compiles untouched inside TS projects too.
@@ -75,7 +75,6 @@ export function generateNext({ cwd, appDir, port, routes }) {
   tpl = tpl
     .replace('__TOOLS_JSON__', JSON.stringify(tools, null, 2))
     .replace('__SPARDING_POLICIES__', JSON.stringify(sparding.policies ?? {}))
-    .replace('__LOCAL_KEY__', localKey)
     .replace('__PORT__', String(port));
   atomicWrite(routerAbs, tpl);
 
@@ -102,7 +101,15 @@ export function generateNext({ cwd, appDir, port, routes }) {
     ...(prev?.labs ? { labs: prev.labs } : {}),
     sparding,
   };
-  atomicWrite(path.join(cwd, 'sparda.json'), JSON.stringify(manifest, null, 2) + '\n');
+  // ADR-022: the disk copy NEVER carries the key — it lives in .sparda/key
+  // (written by ensureSpardaKey above). The in-memory return keeps it for
+  // this process only.
+  const manifestOnDisk = { ...manifest };
+  delete manifestOnDisk.localKey;
+  atomicWrite(
+    path.join(cwd, 'sparda.json'),
+    JSON.stringify(manifestOnDisk, null, 2) + '\n',
+  );
 
   return {
     tools,

package/src/index.js

@@ -21,6 +21,8 @@ const opts = {
   html: flags.has('--html'),
   json: flags.has('--json'),
   app: flags.has('--app'),
+  learn: flags.has('--learn'),
+  germinate: flags.has('--germinate'),
   port: getOpt('port', null),
   out: getOpt('out', null),
   cwd: process.cwd(),
@@ -77,6 +79,21 @@ try {
       );
       break;
     }
+    case 'twin': {
+      const { runTwin } = await import('./commands/twin.js');
+      await runTwin(opts, rest);
+      break;
+    }
+    case 'grammar': {
+      const { runGrammar } = await import('./commands/grammar.js');
+      await runGrammar(opts);
+      break;
+    }
+    case 'evolve': {
+      const { runEvolve } = await import('./commands/evolve.js');
+      await runEvolve(opts);
+      break;
+    }
     default:
       console.log(`SPARDA v${VERSION} — Turn any codebase into an MCP server.
 
@@ -89,7 +106,10 @@ Usage:
   npx sparda-mcp remove    Remove SPARDA from this project (clean git diff)
   npx sparda-mcp doctor    Diagnose your setup (--app: negentropy scan — drift, dead routes, rot)
   npx sparda-mcp report    The black box: what AI agents did to this app
-  npx sparda-mcp seed      Export/import the learned genome (export [--out f] | import <f>)
+  npx sparda-mcp seed      Export/import the learned genome (export [--out f] | import <f> [--germinate])
+  npx sparda-mcp twin      The living mock (--learn from the live app, then serve the ghost)
+  npx sparda-mcp grammar   Which call sequences mean something (observed + hypotheses)
+  npx sparda-mcp evolve    Trial hypothesis chains against the twin; survivors become suggestions
 
 Flags: --yes (skip prompts)  --port <n>  --quiet  --verbose
        --probe (init: also run the app to discover dynamic routes the AST missed)

package/src/server/stdio.js

@@ -25,6 +25,7 @@ import { writeManifestSync, mergeManifestKeySync } from './persistence.js';
 import { createSpardaEngine } from './engine.js';
 import { initiateWrite, preapproveWrite, confirmWrite } from './confirmation.js';
 import { resolveContext, injectContext, fingerprintContext } from './context-carrier.js';
+import { resolveSpardaKey } from '../generator/manifest.js';
 
 const EVENT_POLL_MS = Number(process.env.SPARDA_EVENT_POLL_MS ?? 5000);
 // the sampling budgets below are also what the recycling gauge counts as "avoided"
@@ -61,11 +62,11 @@ export async function startStdioBridge({ cwd, portOverride }) {
   }
   const port = Number(portOverride ?? manifest.port);
   const framework = manifest.framework;
-  const key = manifest.localKey;
+  const key = resolveSpardaKey(cwd, manifest);
   if (!key) {
-    throw Object.assign(new Error('localKey missing from sparda.json.'), {
+    throw Object.assign(new Error('localKey missing or not configured.'), {
       code: 'USER',
-      hint: 'Re-run `npx sparda-mcp init` to regenerate it.',
+      hint: 'Re-run `npx sparda-mcp init` to generate it, or set SPARDA_LOCAL_KEY.',
     });
   }
 

package/templates/express-router.txt

@@ -7,7 +7,21 @@ __IMPORT_LINE__
 const SPARDA_TOOLS = __TOOLS_JSON__;
 const SPARDA_POLICIES = __SPARDING_POLICIES__;
 
-const SPARDA_LOCAL_KEY = "__LOCAL_KEY__";
+// ADR-022: the key is NEVER baked into this committed file. It resolves at
+// runtime — env first, then the gitignored .sparda/key — and fails CLOSED:
+// no key, no /mcp surface. A deploy that ships without .sparda/ is inert.
+__FS_IMPORT__
+let SPARDA_LOCAL_KEY = process.env.SPARDA_LOCAL_KEY || null;
+if (!SPARDA_LOCAL_KEY) {
+  try {
+    for (const p of ['.sparda/key', '../.sparda/key', '../../.sparda/key']) {
+      if (spardaFs.existsSync(p)) {
+        SPARDA_LOCAL_KEY = spardaFs.readFileSync(p, 'utf8').trim() || null;
+        if (SPARDA_LOCAL_KEY) break;
+      }
+    }
+  } catch { /* stays null -> fail closed */ }
+}
 const SPARDA_PORT = __PORT__;
 
 const SPARDA_STATS__STATS_TYPE__ = {};
@@ -299,6 +313,9 @@ async function spardaExecute(tool__ANY_TYPE__, spec__ANY_TYPE__, args__ANY_TYPE_
 __ROUTER_DECL__
 
 spardaRouter.use((req__REQ_TYPE__, res__RES_TYPE__, next__NEXT_TYPE__) => {
+  if (!SPARDA_LOCAL_KEY) {
+    return res.status(503).json({ error: 'key not configured' });
+  }
   if (req.headers['x-sparda-key'] !== SPARDA_LOCAL_KEY) {
     return res.status(401).json({ error: 'unauthorized' });
   }

package/templates/fastapi-router.txt

@@ -19,7 +19,20 @@ import threading
 # json.loads, not a Python literal: JSON true/false/null are not valid Python (E-009)
 SPARDA_TOOLS = json.loads(__TOOLS_JSON__)
 SPARDA_POLICIES = json.loads(__SPARDING_POLICIES__)
-SPARDA_LOCAL_KEY = "__LOCAL_KEY__"
+# ADR-022: the key is NEVER baked into this committed file. It resolves at
+# runtime — env first, then the gitignored .sparda/key — and fails CLOSED:
+# no key, no /mcp surface. A deploy that ships without .sparda/ is inert.
+SPARDA_LOCAL_KEY = os.environ.get("SPARDA_LOCAL_KEY") or None
+if not SPARDA_LOCAL_KEY:
+    try:
+        for p in [".sparda/key", "../.sparda/key", "../../.sparda/key"]:
+            if os.path.exists(p):
+                with open(p, "r", encoding="utf-8") as f:
+                    SPARDA_LOCAL_KEY = f.read().strip() or None
+                if SPARDA_LOCAL_KEY:
+                    break
+    except Exception:
+        pass  # stays None -> fail closed
 SPARDA_PORT = __PORT__
 
 SPARDA_STATS = {}
@@ -363,18 +376,24 @@ async def sparda_read_json(request):
 
 @sparda_router.get("/tools")
 async def get_tools(request: Request):
+    if not SPARDA_LOCAL_KEY:
+        return JSONResponse(status_code=503, content={"error": "key not configured"})
     if request.headers.get("x-sparda-key") != SPARDA_LOCAL_KEY:
         return JSONResponse(status_code=401, content={"error": "unauthorized"})
     return SPARDA_TOOLS
 
 @sparda_router.get("/stats")
 async def get_stats(request: Request):
+    if not SPARDA_LOCAL_KEY:
+        return JSONResponse(status_code=503, content={"error": "key not configured"})
     if request.headers.get("x-sparda-key") != SPARDA_LOCAL_KEY:
         return JSONResponse(status_code=401, content={"error": "unauthorized"})
     return {"uptimeSec": round(time.time() - SPARDA_START), "stats": SPARDA_STATS, "quarantine": SPARDA_QUARANTINE, "recycle": {**SPARDA_RECYCLE, "ratePct": sparda_recycle_rate()}, "purity": sparda_purity_snapshot()}
 
 @sparda_router.get("/events")
 async def get_events(request: Request):
+    if not SPARDA_LOCAL_KEY:
+        return JSONResponse(status_code=503, content={"error": "key not configured"})
     if request.headers.get("x-sparda-key") != SPARDA_LOCAL_KEY:
         return JSONResponse(status_code=401, content={"error": "unauthorized"})
     try:
@@ -388,6 +407,8 @@ async def gossip(request: Request):
     # peer-to-peer convergence (Brief #2), behind the same x-sparda-key as every route.
     # Absorbs a peer's grow-only counts via CRDT max-merge; 204 on success. An unknown tool
     # or malformed count is silently dropped (bounded, no injection).
+    if not SPARDA_LOCAL_KEY:
+        return JSONResponse(status_code=503, content={"error": "key not configured"})
     if request.headers.get("x-sparda-key") != SPARDA_LOCAL_KEY:
         return JSONResponse(status_code=401, content={"error": "unauthorized"})
     body, err = await sparda_read_json(request)
@@ -398,6 +419,8 @@ async def gossip(request: Request):
 
 @sparda_router.post("/invoke")
 async def invoke_tool(request: Request):
+    if not SPARDA_LOCAL_KEY:
+        return JSONResponse(status_code=503, content={"error": "key not configured"})
     if request.headers.get("x-sparda-key") != SPARDA_LOCAL_KEY:
         return JSONResponse(status_code=401, content={"error": "unauthorized"})
 
@@ -543,6 +566,8 @@ async def invoke_tool(request: Request):
 
 @sparda_router.post("/invoke/confirm")
 async def confirm_tool_invocation(request: Request):
+    if not SPARDA_LOCAL_KEY:
+        return JSONResponse(status_code=503, content={"error": "key not configured"})
     if request.headers.get("x-sparda-key") != SPARDA_LOCAL_KEY:
         return JSONResponse(status_code=401, content={"error": "unauthorized"})
     

package/templates/nextjs-router.txt

@@ -8,7 +8,21 @@
 const SPARDA_TOOLS = __TOOLS_JSON__;
 const SPARDA_POLICIES = __SPARDING_POLICIES__;
 
-const SPARDA_LOCAL_KEY = "__LOCAL_KEY__";
+// ADR-022: the key is NEVER baked into this committed file. It resolves at
+// runtime — env first, then the gitignored .sparda/key — and fails CLOSED:
+// no key, no /mcp surface. A Vercel deploy that ships without .sparda/ is inert.
+import spardaFs from 'node:fs';
+let SPARDA_LOCAL_KEY = process.env.SPARDA_LOCAL_KEY || null;
+if (!SPARDA_LOCAL_KEY) {
+  try {
+    for (const p of ['.sparda/key', '../.sparda/key', '../../.sparda/key']) {
+      if (spardaFs.existsSync(p)) {
+        SPARDA_LOCAL_KEY = spardaFs.readFileSync(p, 'utf8').trim() || null;
+        if (SPARDA_LOCAL_KEY) break;
+      }
+    }
+  } catch { /* stays null -> fail closed */ }
+}
 const SPARDA_PORT = __PORT__;
 
 // never statically optimized, always on the Node.js runtime (process, timers)
@@ -336,6 +350,9 @@ async function spardaConfirm(request) {
 
 async function spardaHandle(request, ctx) {
   try {
+    if (!SPARDA_LOCAL_KEY) {
+      return spardaJson(503, { error: 'key not configured' });
+    }
     if (request.headers.get('x-sparda-key') !== SPARDA_LOCAL_KEY) {
       return spardaJson(401, { error: 'unauthorized' });
     }