@saulwade/swl-ses 1.1.4 → 1.2.0

package/scripts/lib/jaccard-similarity.js

@@ -0,0 +1,98 @@
+'use strict';
+
+/**
+ * jaccard-similarity.js — Métrica de Jaccard sobre conjuntos de tokens.
+ *
+ * Patrón adoptado de `temp/agentmemory-main/src/functions/auto-forget.ts`
+ * para detectar memorias contradictorias/duplicadas con vocabulario compartido.
+ *
+ * Jaccard(A, B) = |A ∩ B| / |A ∪ B|
+ *
+ * Propiedades:
+ *   - Rango [0, 1]: 0 = sin overlap, 1 = idénticos.
+ *   - Simétrico: J(A, B) = J(B, A).
+ *   - Independiente de longitudes absolutas (ambos cortos pueden ser 1.0).
+ *
+ * Sin dependencias — Node stdlib only. Funciones puras.
+ *
+ * @module scripts/lib/jaccard-similarity
+ */
+
+// ── constantes ────────────────────────────────────────────────────────────────
+
+/** Longitud mínima de un token para ser considerado significativo. */
+const MIN_TOKEN_LENGTH = 3;
+
+/** Stop words en español que se excluyen del análisis. */
+const STOP_WORDS = new Set([
+  'que', 'los', 'las', 'del', 'una', 'por', 'con', 'para', 'como',
+  'sin', 'mas', 'sus', 'lo', 'le', 'la', 'el', 'al', 'no', 'es',
+  'se', 'de', 'en', 'un', 'a', 'y', 'o', 'pero', 'cuando',
+  'donde', 'porque', 'desde', 'hasta', 'sobre', 'bajo', 'entre',
+  'esta', 'este', 'esto', 'esa', 'ese', 'eso', 'tras', 'durante',
+  'mediante', 'segun', 'asi', 'tan', 'ya', 'aun', 'aunque',
+  // English equivalents (frequently mixed in technical text)
+  'the', 'and', 'for', 'with', 'this', 'that', 'have', 'from',
+  'are', 'was', 'will', 'not', 'has', 'had', 'but', 'can',
+]);
+
+// ── funciones puras ───────────────────────────────────────────────────────────
+
+/**
+ * Convierte un texto en un Set de tokens significativos (lowercase, sin stop
+ * words, longitud mínima). Preserva acentos.
+ *
+ * @param {string} text
+ * @returns {Set<string>}
+ */
+function tokenize(text) {
+  if (!text || typeof text !== 'string') return new Set();
+  return new Set(
+    String(text)
+      .toLowerCase()
+      .replace(/[`*_~\[\](){}<>#"'\-.,;:!?\/\\]/g, ' ')
+      .split(/\s+/)
+      .filter(t => t.length >= MIN_TOKEN_LENGTH && !STOP_WORDS.has(t)),
+  );
+}
+
+/**
+ * Jaccard similarity entre dos Sets.
+ *
+ * @param {Set} setA
+ * @param {Set} setB
+ * @returns {number} en [0, 1]
+ */
+function jaccard(setA, setB) {
+  if (!(setA instanceof Set) || !(setB instanceof Set)) return 0;
+  if (setA.size === 0 && setB.size === 0) return 0;
+  if (setA.size === 0 || setB.size === 0) return 0;
+
+  let intersection = 0;
+  for (const token of setA) {
+    if (setB.has(token)) intersection++;
+  }
+  const union = setA.size + setB.size - intersection;
+  return union === 0 ? 0 : intersection / union;
+}
+
+/**
+ * Conveniencia: jaccard sobre dos textos.
+ *
+ * @param {string} a
+ * @param {string} b
+ * @returns {number} en [0, 1]
+ */
+function similarity(a, b) {
+  return jaccard(tokenize(a), tokenize(b));
+}
+
+// ── exports ───────────────────────────────────────────────────────────────────
+
+module.exports = {
+  tokenize,
+  jaccard,
+  similarity,
+  MIN_TOKEN_LENGTH,
+  STOP_WORDS,
+};

package/scripts/lib/longmemeval-runner.js

@@ -0,0 +1,125 @@
+'use strict';
+
+/**
+ * longmemeval-runner.js — Adapter que ejecuta queries del benchmark contra
+ * `hooks/lib/memory-search` y devuelve métricas.
+ *
+ * Patrón adoptado de `temp/agentmemory-main/benchmark/longmemeval-bench.ts`.
+ * Adaptado: en lugar de cargar haystack desde el dataset, usa el estado
+ * actual del proyecto SWL (APRENDIZAJES.md, sesiones, instintos).
+ *
+ * El dataset es un JSONL donde cada línea es:
+ * {
+ *   "question_id":  "q-001",
+ *   "question":     "texto libre de la query",
+ *   "gold_ids":     ["apr-N", "ses-YYYY-MM-DD-HHMM"],
+ *   "category":     "decision" | "patron" | "anti-patron" | "gotcha" | ...,
+ *   "status":       "real" | "placeholder"
+ * }
+ *
+ * @module scripts/lib/longmemeval-runner
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+const memorySearch     = require('../../hooks/lib/memory-search');
+const benchmarkMetrics = require('./benchmark-metrics');
+
+// ── parser de dataset ─────────────────────────────────────────────────────────
+
+/**
+ * Parsea un archivo JSONL del dataset.
+ * @param {string} ruta
+ * @returns {object[]}
+ */
+function leerDataset(ruta) {
+  if (!fs.existsSync(ruta)) {
+    throw new Error(`Dataset no encontrado: ${ruta}`);
+  }
+  const contenido = fs.readFileSync(ruta, 'utf8');
+  const entries = [];
+  let lineNum = 0;
+  for (const linea of contenido.split('\n')) {
+    lineNum++;
+    if (!linea.trim()) continue;
+    if (linea.trim().startsWith('//')) continue; // comentarios
+    try {
+      entries.push(JSON.parse(linea));
+    } catch (err) {
+      throw new Error(`JSONL malformado en línea ${lineNum}: ${err.message}`);
+    }
+  }
+  return entries;
+}
+
+// ── ejecución de query individual ─────────────────────────────────────────────
+
+/**
+ * Ejecuta una query del benchmark contra memoria SWL y compara con gold.
+ *
+ * @param {string} baseDir - Raíz del proyecto.
+ * @param {object} entry - Una línea del dataset.
+ * @param {object} [opts]
+ * @param {number} [opts.limit=20] - Top-k a recuperar.
+ * @returns {object} Métricas + ids retrieved + entry original.
+ */
+function ejecutarEntry(baseDir, entry, opts = {}) {
+  const limit = opts.limit || 20;
+  const inicio = Date.now();
+  const resultados = memorySearch.search(baseDir, entry.question, { limit });
+  const latencyMs = Date.now() - inicio;
+
+  const retrievedIds = resultados.map(r => r.id);
+  const goldIds = Array.isArray(entry.gold_ids) ? entry.gold_ids : [];
+  const metricas = benchmarkMetrics.calcularMetricas(retrievedIds, goldIds);
+
+  return {
+    question_id: entry.question_id || 'unknown',
+    question: entry.question,
+    category: entry.category || null,
+    status: entry.status || 'unknown',
+    retrievedIds,
+    goldIds,
+    metricas,
+    latencyMs,
+  };
+}
+
+/**
+ * Ejecuta el dataset completo y devuelve resultados + métricas agregadas.
+ *
+ * @param {string} baseDir
+ * @param {string} datasetPath
+ * @param {object} [opts]
+ * @returns {{ entries: object[], promedio: object, dataset: object }}
+ */
+function ejecutarDataset(baseDir, datasetPath, opts = {}) {
+  const entries = leerDataset(datasetPath);
+  const resultados = entries.map(e => ejecutarEntry(baseDir, e, opts));
+  const promedio = benchmarkMetrics.promediar(resultados.map(r => r.metricas));
+
+  // Estadísticas del dataset
+  const placeholderCount = entries.filter(e => e.status === 'placeholder').length;
+  const realCount = entries.filter(e => e.status === 'real').length;
+  const datasetMeta = {
+    total: entries.length,
+    real: realCount,
+    placeholder: placeholderCount,
+    significativo: realCount >= 30,
+  };
+
+  return {
+    entries: resultados,
+    promedio,
+    dataset: datasetMeta,
+  };
+}
+
+// ── exports ───────────────────────────────────────────────────────────────────
+
+module.exports = {
+  leerDataset,
+  ejecutarEntry,
+  ejecutarDataset,
+};

package/scripts/lib/rrf-fusion.js

@@ -0,0 +1,175 @@
+'use strict';
+
+/**
+ * rrf-fusion.js — Reciprocal Rank Fusion para combinar streams de búsqueda.
+ *
+ * Patrón adoptado de `temp/agentmemory-main/src/state/hybrid-search.ts`. El
+ * algoritmo RRF combina rankings de múltiples sistemas de retrieval (BM25,
+ * vector, graph) sin requerir que sus scores sean comparables — solo importa
+ * la posición relativa (rank) en cada lista.
+ *
+ * Fórmula:
+ *
+ *     RRF(d) = Σ_i  w_i / (k + rank_i(d))
+ *
+ *   donde:
+ *     d         = un documento candidato
+ *     i         = índice del stream (BM25, vector, graph, ...)
+ *     w_i       = peso del stream i (default 1.0 si no se especifica)
+ *     rank_i(d) = posición 1-indexed de d en el stream i, o ∞ si no aparece
+ *     k         = constante de smoothing (default 60, estándar Cormack 2009)
+ *
+ * Propiedades:
+ *   - Robust frente a magnitudes de score heterogéneas — solo usa rank.
+ *   - Documentos que aparecen en múltiples streams reciben boost natural.
+ *   - Documentos que aparecen solo una vez no son penalizados — su rank ∞ en
+ *     otros streams contribuye 0.
+ *   - k ≈ 60 minimiza el peso de ranks bajos (< 60 efectivos).
+ *
+ * Versus suma simple de scores:
+ *   - No requiere normalización entre streams (BM25 vs vector cosine son
+ *     incomparables).
+ *   - Más resistente a outliers (un score muy alto en un stream no domina).
+ *
+ * Sin dependencias — Node stdlib only. Backward compatible: el caller puede
+ * mantener su lógica anterior y usar RRF solo cuando combine ≥2 streams.
+ *
+ * @module scripts/lib/rrf-fusion
+ */
+
+// ── constantes ────────────────────────────────────────────────────────────────
+
+/** Constante k del RRF estándar (Cormack et al., 2009). */
+const RRF_K_DEFAULT = 60;
+
+// ── funciones puras ───────────────────────────────────────────────────────────
+
+/**
+ * Construye un mapa `id → rank` desde un stream de resultados ordenados.
+ * Rank es 1-indexed: el primer elemento tiene rank 1.
+ * Si un id aparece varias veces, conserva el rank más bajo (mejor).
+ *
+ * @param {Array<{id: string}>} stream - Resultados ordenados (mejor primero).
+ * @returns {Map<string, number>} Mapa id → rank.
+ */
+function rankMap(stream) {
+  const map = new Map();
+  if (!Array.isArray(stream)) return map;
+  for (let i = 0; i < stream.length; i++) {
+    const item = stream[i];
+    if (!item || typeof item.id !== 'string') continue;
+    const rank = i + 1;
+    const previo = map.get(item.id);
+    if (previo === undefined || rank < previo) {
+      map.set(item.id, rank);
+    }
+  }
+  return map;
+}
+
+/**
+ * Score parcial del stream para un id dado.
+ * Si el id NO aparece en el stream, devuelve 0 (rank ∞).
+ *
+ * @param {Map<string, number>} map - Resultado de rankMap().
+ * @param {string} id
+ * @param {number} k
+ * @returns {number} contribución 1/(k + rank), o 0 si no aparece.
+ */
+function streamScore(map, id, k) {
+  const rank = map.get(id);
+  if (rank === undefined) return 0;
+  return 1 / (k + rank);
+}
+
+/**
+ * Reciprocal Rank Fusion: combina N streams de búsqueda en un ranking unificado.
+ *
+ * Cada stream es un array de objetos con al menos `{ id: string }`. La posición
+ * en el array determina el rank (1-indexed). Cualquier metadata extra (titulo,
+ * fecha, score, etc.) del primer stream donde aparece el id se preserva en el
+ * resultado.
+ *
+ * Si se proveen `weights`, se ponderan los streams. El array de pesos debe
+ * tener el mismo largo que `streams`. Si no se provee, todos los streams pesan
+ * 1.0. Pesos no positivos se tratan como 0 (efectivamente desactivan el stream).
+ *
+ * Si todos los pesos suman > 0, se normalizan a 1.0 para que el `combinedScore`
+ * resultante sea comparable entre invocaciones con distintos pesos.
+ *
+ * @param {Array<Array<object>>} streams - Lista de streams ordenados.
+ * @param {object} [opts]
+ * @param {number} [opts.k=60] - Constante k del RRF.
+ * @param {number[]} [opts.weights] - Pesos por stream (alineado con streams[]).
+ * @param {number} [opts.limit] - Limita la salida a N elementos top.
+ * @returns {Array<object>} Resultados combinados con `combinedScore`,
+ *   ordenados descendente. Conserva metadata del primer stream donde apareció
+ *   cada id.
+ */
+function rrfFusion(streams, opts = {}) {
+  if (!Array.isArray(streams) || streams.length === 0) return [];
+
+  const k = typeof opts.k === 'number' && opts.k > 0 ? opts.k : RRF_K_DEFAULT;
+
+  // Normalizar pesos
+  let weights;
+  if (Array.isArray(opts.weights) && opts.weights.length === streams.length) {
+    const positivos = opts.weights.map(w =>
+      typeof w === 'number' && w > 0 ? w : 0,
+    );
+    const total = positivos.reduce((a, b) => a + b, 0);
+    weights = total > 0 ? positivos.map(w => w / total) : positivos;
+  } else {
+    // Sin weights explícitos: todos iguales y normalizados (suman 1.0).
+    const efectivos = streams.filter(s => Array.isArray(s) && s.length > 0).length;
+    if (efectivos === 0) return [];
+    weights = streams.map(s =>
+      Array.isArray(s) && s.length > 0 ? 1 / efectivos : 0,
+    );
+  }
+
+  // Construir rankMap por stream + recolectar metadata por id
+  const maps = streams.map(rankMap);
+  const metadata = new Map(); // id → primer item visto
+
+  for (const stream of streams) {
+    if (!Array.isArray(stream)) continue;
+    for (const item of stream) {
+      if (!item || typeof item.id !== 'string') continue;
+      if (!metadata.has(item.id)) {
+        metadata.set(item.id, item);
+      }
+    }
+  }
+
+  // Calcular combinedScore para cada id
+  const combined = [];
+  for (const id of metadata.keys()) {
+    let score = 0;
+    for (let i = 0; i < streams.length; i++) {
+      score += weights[i] * streamScore(maps[i], id, k);
+    }
+    if (score > 0) {
+      combined.push({
+        ...metadata.get(id),
+        combinedScore: score,
+      });
+    }
+  }
+
+  combined.sort((a, b) => b.combinedScore - a.combinedScore);
+
+  if (typeof opts.limit === 'number' && opts.limit > 0) {
+    return combined.slice(0, opts.limit);
+  }
+  return combined;
+}
+
+// ── exports ───────────────────────────────────────────────────────────────────
+
+module.exports = {
+  rrfFusion,
+  rankMap,
+  streamScore,
+  RRF_K_DEFAULT,
+};

package/scripts/lib/scoring-instintos.js

@@ -39,6 +39,10 @@ const HARMFUL_PENALTY_WEIGHT       = 0.5;
 const PROVEN_CONFIDENCE_THRESHOLD  = 0.7;
 const ESTABLISHED_THRESHOLD        = 0.5;
 const PROVEN_EVIDENCE_THRESHOLD    = 3;
+// Modelo de reforzamiento por feedback positivo (estilo agentmemory/lessons.ts).
+// Cada feedback positivo cierra un (1 - REINFORCEMENT_DECAY) = 10% del gap
+// entre la confianza actual y 1.0 — diminishing returns naturales.
+const REINFORCEMENT_DECAY          = 0.9;
 
 // ── helpers ───────────────────────────────────────────────────────────────────
 
@@ -98,7 +102,38 @@ function harmfulRatio(instinto) {
 }
 
 /**
- * Confianza efectiva considerando decay temporal y feedback negativo.
+ * Confianza reforzada por feedback positivo acumulado.
+ *
+ * Aplica un modelo de diminishing returns inspirado en `lessons.ts` de
+ * agentmemory: cada feedback positivo cierra una fracción del gap entre la
+ * confianza actual y 1.0. Aplicado N veces sobre la confianza base:
+ *
+ *     c_N = 1 - REINFORCEMENT_DECAY^N · (1 - c_0)
+ *
+ * Con `REINFORCEMENT_DECAY = 0.9`:
+ *   - 1 feedback: c_0=0.5 → 0.55
+ *   - 5 feedback: c_0=0.5 → 0.705
+ *   - 10 feedback: c_0=0.5 → 0.826
+ *   - 50 feedback: c_0=0.5 → 0.997
+ *
+ * Si no hay `helpful_count` (o es 0), devuelve la confianza base sin tocar.
+ * Backward compatible: instintos sin el campo siguen comportándose igual.
+ *
+ * No persiste el resultado — se computa on-demand desde `helpful_count`. Eso
+ * preserva el invariante "confidence original es estática".
+ */
+function reinforcedConfidence(instinto) {
+  const baseConfidence = clamp(instinto.confidence || 0, 0, 1);
+  const helpful = instinto.helpful_count || 0;
+  if (helpful <= 0) return baseConfidence;
+  return 1 - Math.pow(REINFORCEMENT_DECAY, helpful) * (1 - baseConfidence);
+}
+
+/**
+ * Confianza efectiva considerando reforzamiento, decay temporal y feedback
+ * negativo.
+ *
+ *   effective = reinforced × decay − harmful_penalty
  *
  * @param {object} instinto
  * @param {string|Date} [currentDate=now] — fecha de referencia
@@ -111,10 +146,10 @@ function effectiveConfidence(instinto, currentDate) {
 
   const days = validatedAt ? daysBetween(validatedAt, now) : 0;
   const decay = decayFactor(days, halfLife);
-  const baseConfidence = clamp(instinto.confidence || 0, 0, 1);
+  const reinforced = reinforcedConfidence(instinto);
   const penalty = HARMFUL_PENALTY_WEIGHT * harmfulRatio(instinto);
 
-  return clamp(baseConfidence * decay - penalty, 0, 1);
+  return clamp(reinforced * decay - penalty, 0, 1);
 }
 
 /**
@@ -223,6 +258,7 @@ module.exports = {
   daysBetween,
   decayFactor,
   harmfulRatio,
+  reinforcedConfidence,
   effectiveConfidence,
   shouldAutoDeprecate,
   maturityState,
@@ -237,4 +273,5 @@ module.exports = {
   PROVEN_CONFIDENCE_THRESHOLD,
   ESTABLISHED_THRESHOLD,
   PROVEN_EVIDENCE_THRESHOLD,
+  REINFORCEMENT_DECAY,
 };

package/scripts/mcp-server/README.md

@@ -0,0 +1,128 @@
+# swl-mcp-server — STUB EXPERIMENTAL
+
+> ⚠ **NO USAR EN PRODUCCIÓN**. Este es un stub experimental que demuestra
+> el patrón de exponer la memoria de swl-ses a clientes MCP externos. La
+> implementación completa requiere trabajo adicional (auth, observabilidad,
+> tests de integración, schema migration). Ver sección "Limitaciones" más
+> abajo.
+
+## Qué hace
+
+`bin/swl-mcp-server.js` es un servidor MCP en modo stdio que expone 3
+endpoints de solo lectura:
+
+1. **`swl_memory_search`** — búsqueda hybrid sobre memoria SWL
+   (aprendizajes + sesiones + instintos) usando `hooks/lib/memory-search`
+   con RRF fusion.
+2. **`swl_aprendizajes_recientes`** — últimos N aprendizajes de
+   `.planning/APRENDIZAJES.md`.
+3. **`swl_instintos_activos`** — instintos con `effective_confidence ≥
+   umbral`.
+
+El server lee el estado file-based de swl-ses tal como existe en `cwd`
+(o el directorio especificado por `SWL_MCP_BASE_DIR`). NO escribe — solo
+lectura.
+
+## Cómo arrancar (para testing)
+
+```bash
+# Modo standalone (smoke test)
+echo '{"jsonrpc":"2.0","id":1,"method":"initialize"}' | node bin/swl-mcp-server.js
+
+# Output esperado en stdout:
+# {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{"listChanged":false}},"serverInfo":{"name":"swl-mcp-server","version":"0.1.0-experimental"}}}
+
+# Listar herramientas
+echo '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' | node bin/swl-mcp-server.js
+
+# Buscar memoria
+echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"swl_memory_search","arguments":{"query":"RRF fusion","limit":3}}}' | node bin/swl-mcp-server.js
+```
+
+## Cómo configurar en clientes MCP (NO recomendado en producción)
+
+### Cursor (~/.cursor/mcp.json)
+
+```json
+{
+  "mcpServers": {
+    "swl-memory": {
+      "command": "node",
+      "args": ["/ruta/absoluta/a/swl-ses/bin/swl-mcp-server.js"],
+      "env": {
+        "SWL_MCP_BASE_DIR": "/ruta/al/proyecto/que/quiero/recuperar"
+      }
+    }
+  }
+}
+```
+
+### Gemini CLI
+
+Similar, agregando el server a la config del cliente que soporte MCP stdio.
+
+### Claude Code (NO necesario)
+
+Claude Code ya tiene acceso directo a los archivos de swl-ses dentro de
+su propio runtime. NO usar el MCP server desde Claude Code en el mismo
+proyecto — sería redundante y agregaría latencia.
+
+## Limitaciones (lo que NO se hace en este stub)
+
+| Limitación | Impacto | Cuándo se debe arreglar |
+|---|---|---|
+| **Sin auth** | Cualquier proceso con acceso al stdio puede leer toda la memoria | Antes de exponer en redes públicas o multi-usuario |
+| **Sin rate limiting** | Cliente malicioso/buggy puede saturar lectura de archivos | Cuando se observen ≥1 incidentes de saturación |
+| **Sin HTTP transport** | Solo stdio; no se puede conectar remotamente | Cuando el caso de uso requiera servidor de red |
+| **Sin tests de integración** | Solo smoke tests manuales | Antes de v1.0 del MCP server |
+| **Sin observabilidad / métricas** | Logs JSON a stderr son lo único que hay | Cuando se use en >1 cliente simultáneo |
+| **Sin hot-reload** | Cambios en swl-ses no se reflejan hasta restart del server | Ya — el server lee files en cada call, así que SÍ se reflejan; documentado por completitud |
+| **Sin caching** | Cada call lee files de disco | Cuando latencia sea problema (~10ms hoy) |
+| **Sin schema versioning** | Si cambia formato de APRENDIZAJES.md, los handlers pueden romper | Cuando se introduzca breaking change en el formato |
+| **Sin support de resources/prompts** | Solo tools | Cuando el caso de uso lo demande |
+| **Sin paginación** | Resultados grandes se truncan a `limit` | Cuando se requiera browse de >50 entries |
+| **Single-tenant** | Asume un solo proyecto por instancia | Multi-tenancy necesita rediseño |
+
+## Trigger para implementación completa
+
+**Hoy**: 0 instalaciones reportadas. Mantener como stub.
+
+**Trigger para invertir esfuerzo en implementación robusta**: el usuario
+reporta uso real consistente de ≥2 runtimes distintos (Cursor + Claude
+Code, o Gemini + Claude Code, etc.) sobre el mismo proyecto SWL durante
+≥1 mes. Sin esto, la inversión de ~25 horas en hardening del server
+no se justifica.
+
+## Diseño futuro (cuando se implemente completo)
+
+1. **Auth**: API key estática + bearer token con scopes:
+   - `swl:memory:read` (búsqueda y lectura)
+   - `swl:memory:write` (crear aprendizajes desde MCP — requiere validación)
+   - `swl:instintos:write` (modificar confidence — alto riesgo)
+2. **HTTP transport opcional**: además de stdio, ofrecer servidor HTTP/SSE
+   con TLS y CORS configurable.
+3. **Telemetría**: requests por handler, latencia p50/p95, errores por
+   tipo. Persistir en `.planning/evolucion/mcp-metrics.jsonl`.
+4. **Caching invalidable**: caché en memoria de las lecturas de
+   APRENDIZAJES.md / instintos con `mtime`-based invalidation.
+5. **Schema versioning**: cada handler declara `schema_version`. El
+   cliente puede pedir un version range. Breaking changes bumpan major.
+6. **Tests de integración**: arrancar el server contra una fixture y
+   ejecutar 50+ scenarios. Smoke en CI.
+
+## Estado de seguridad (auditoría rápida del stub)
+
+- ✓ NO expone credenciales ni archivos fuera de `baseDir`.
+- ✓ NO ejecuta código (solo lee files y devuelve JSON).
+- ✓ NO modifica archivos.
+- ✗ NO valida que `baseDir` sea un proyecto SWL válido — un cliente
+  podría apuntarlo a un directorio arbitrario y leer cualquier
+  archivo `*.md` que llamemos `APRENDIZAJES.md`.
+- ✗ NO sanitiza queries de búsqueda (los regex en `instintos.yaml` parser
+  son seguros, pero falta hardening).
+- ✗ NO hay timeout — un proyecto enorme con miles de sesiones podría
+  hacer colgar el server.
+
+Estos puntos son ACEPTABLES para un stub experimental usado por el
+mantenedor en un proyecto propio. NO ACEPTABLES para uso multi-usuario
+o expuesto a la red.