@saulwade/swl-ses 1.1.3 → 1.2.0

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.

package/scripts/mcp-server/handlers.js

@@ -0,0 +1,206 @@
+'use strict';
+
+/**
+ * handlers.js — Handlers para los 3 endpoints MCP stub de swl-ses.
+ *
+ * **EXPERIMENTAL** — no producción. Sin auth, sin rate limiting, sin
+ * tests robustos. Ver `scripts/mcp-server/README.md` para limitaciones.
+ *
+ * Los handlers leen el estado file-based de swl-ses (APRENDIZAJES.md,
+ * .planning/sessions/, instintos/proyecto.yaml) y devuelven datos
+ * estructurados al cliente MCP. NO escriben — solo lectura.
+ *
+ * @module scripts/mcp-server/handlers
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+const memorySearch       = require('../../hooks/lib/memory-search');
+const scoringInstintos   = require('../lib/scoring-instintos');
+
+// ── handler: swl_memory_search ────────────────────────────────────────────────
+
+/**
+ * Búsqueda hybrid sobre memoria SWL (aprendizajes + sesiones + instintos).
+ *
+ * @param {object} args - { query: string, limit?: number, tipo?: string }
+ * @returns {object} { results: Array, count: number }
+ */
+function swlMemorySearch(baseDir, args) {
+  if (!args || typeof args.query !== 'string' || !args.query.trim()) {
+    return { error: 'query (string) requerido', results: [] };
+  }
+
+  const filtros = {};
+  if (typeof args.limit === 'number' && args.limit > 0) filtros.limit = Math.min(args.limit, 50);
+  if (typeof args.tipo === 'string') filtros.tipo = args.tipo;
+
+  const results = memorySearch.search(baseDir, args.query, filtros);
+  return {
+    results: results.map(r => ({
+      id: r.id,
+      tipo: r.tipo,
+      titulo: r.titulo,
+      fecha: r.fecha,
+      relevancia: r.relevancia,
+      combinedScore: r.combinedScore,
+    })),
+    count: results.length,
+  };
+}
+
+// ── handler: swl_aprendizajes_recientes ───────────────────────────────────────
+
+/**
+ * Devuelve los N aprendizajes más recientes de APRENDIZAJES.md.
+ *
+ * @param {object} args - { limit?: number (default 10) }
+ * @returns {object} { results, count }
+ */
+function swlAprendizajesRecientes(baseDir, args = {}) {
+  const limit = (typeof args.limit === 'number' && args.limit > 0)
+    ? Math.min(args.limit, 50)
+    : 10;
+
+  const ruta = path.join(baseDir, '.planning', 'APRENDIZAJES.md');
+  if (!fs.existsSync(ruta)) {
+    return { error: 'APRENDIZAJES.md no encontrado', results: [] };
+  }
+
+  let contenido;
+  try {
+    contenido = fs.readFileSync(ruta, 'utf8');
+  } catch (err) {
+    return { error: 'Error de lectura: ' + err.message, results: [] };
+  }
+
+  const bloques = contenido.split(/^## /m).filter(b => b.trim().length > 0);
+  // Los más recientes están al FINAL del archivo (append-only por convención)
+  const recientes = bloques.slice(-limit).reverse();
+
+  return {
+    results: recientes.map((b, i) => {
+      const primeraLinea = b.split('\n')[0].trim();
+      const cuerpoTrim = b.split('\n').slice(1).join('\n').trim().slice(0, 500);
+      return {
+        index: bloques.length - i,
+        titulo: primeraLinea,
+        contenido: cuerpoTrim,
+      };
+    }),
+    count: recientes.length,
+    total: bloques.length,
+  };
+}
+
+// ── handler: swl_instintos_activos ────────────────────────────────────────────
+
+/**
+ * Devuelve instintos con effective_confidence ≥ umbral.
+ *
+ * @param {object} args - { minConfidence?: number (default 0.5), limit?: number }
+ * @returns {object} { results, count }
+ */
+function swlInstintosActivos(baseDir, args = {}) {
+  const minConfidence = (typeof args.minConfidence === 'number')
+    ? args.minConfidence : 0.5;
+  const limit = (typeof args.limit === 'number' && args.limit > 0)
+    ? Math.min(args.limit, 100) : 20;
+
+  const ruta = path.join(baseDir, 'instintos', 'proyecto.yaml');
+  if (!fs.existsSync(ruta)) {
+    return { error: 'instintos/proyecto.yaml no encontrado', results: [] };
+  }
+
+  let contenido;
+  try {
+    contenido = fs.readFileSync(ruta, 'utf8');
+  } catch (err) {
+    return { error: 'Error de lectura: ' + err.message, results: [] };
+  }
+
+  // Parser simple sin dep YAML (mismo patrón que memory-search.js)
+  const instinto_re = /- id:\s*(\S+)[\s\S]*?pattern:\s*"([^"]+)"[\s\S]*?confidence:\s*([\d.]+)[\s\S]*?status:\s*(\w+)/g;
+  const results = [];
+  let match;
+  const ahora = new Date();
+
+  while ((match = instinto_re.exec(contenido)) !== null) {
+    const [, id, pattern, confidenceStr, status] = match;
+    const confidence = parseFloat(confidenceStr);
+    if (status !== 'active') continue;
+
+    // Construir objeto mínimo para scoring
+    const instinto = {
+      id,
+      pattern,
+      confidence,
+      status,
+      // Sin más metadata, effective_confidence ≈ confidence
+    };
+    const effective = scoringInstintos.effectiveConfidence(instinto, ahora);
+    if (effective < minConfidence) continue;
+
+    results.push({
+      id,
+      pattern,
+      confidence,
+      effective_confidence: Math.round(effective * 1000) / 1000,
+      status,
+    });
+  }
+
+  results.sort((a, b) => b.effective_confidence - a.effective_confidence);
+  return {
+    results: results.slice(0, limit),
+    count: Math.min(results.length, limit),
+    total: results.length,
+  };
+}
+
+// ── exports ───────────────────────────────────────────────────────────────────
+
+const HANDLERS = {
+  swl_memory_search: {
+    description: 'Búsqueda hybrid sobre memoria SWL (aprendizajes + sesiones + instintos) con RRF fusion.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: { type: 'string', description: 'Texto libre de búsqueda' },
+        limit: { type: 'number', description: 'Máximo de resultados (default 20, max 50)' },
+        tipo:  { type: 'string', enum: ['aprendizaje', 'sesion', 'instinto'], description: 'Filtrar por tipo' },
+      },
+      required: ['query'],
+    },
+    handler: swlMemorySearch,
+  },
+  swl_aprendizajes_recientes: {
+    description: 'Últimos N aprendizajes de .planning/APRENDIZAJES.md (más recientes primero).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        limit: { type: 'number', description: 'Cuántos retornar (default 10, max 50)' },
+      },
+    },
+    handler: swlAprendizajesRecientes,
+  },
+  swl_instintos_activos: {
+    description: 'Instintos con effective_confidence ≥ umbral. Default 0.5.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        minConfidence: { type: 'number', description: 'Umbral mínimo (default 0.5)' },
+        limit: { type: 'number', description: 'Máximo (default 20, max 100)' },
+      },
+    },
+    handler: swlInstintosActivos,
+  },
+};
+
+module.exports = {
+  HANDLERS,
+  swlMemorySearch,
+  swlAprendizajesRecientes,
+  swlInstintosActivos,
+};

package/scripts/run-eval.js

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * run-eval.js — CLI para ejecutar evaluaciones del eval framework.
+ *
+ * Uso:
+ *   node scripts/run-eval.js <ruta-eval.json>
+ *
+ * Formato del archivo JSON de eval:
+ * {
+ *   "functionId": "memoria-busqueda::search",
+ *   "schemaName": "MEMORY_SEARCH_RESULT_SCHEMA",   // opcional, valida output
+ *   "qualityScorer": "scoreObservacion",           // opcional, calcula calidad
+ *   "input":  { ... },                              // datos de entrada
+ *   "expectedKeys": ["id", "tipo", "titulo"],       // opcional, valida presencia
+ *   "output": { ... }                               // output a evaluar
+ * }
+ *
+ * Exit codes:
+ *   0 - eval pasa (valid: true)
+ *   1 - eval falla (valid: false) o error de I/O
+ *   2 - error de uso (argumentos inválidos)
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+const schemas         = require('./lib/eval-schemas');
+const validator       = require('./lib/eval-validator');
+const quality         = require('./lib/eval-quality');
+const metricsStore    = require('./lib/eval-metrics-store');
+
+function uso() {
+  console.error('Uso: node scripts/run-eval.js <ruta-eval.json>');
+  console.error('     node scripts/run-eval.js --rebuild-aggregate');
+  process.exit(2);
+}
+
+function ejecutarEval(ruta) {
+  if (!fs.existsSync(ruta)) {
+    console.error(`Archivo no existe: ${ruta}`);
+    return 1;
+  }
+
+  let definicion;
+  try {
+    definicion = JSON.parse(fs.readFileSync(ruta, 'utf8'));
+  } catch (err) {
+    console.error(`Error parseando ${ruta}: ${err.message}`);
+    return 1;
+  }
+
+  const { functionId, schemaName, qualityScorer, output } = definicion;
+  if (!functionId || typeof functionId !== 'string') {
+    console.error('functionId requerido en el archivo de eval');
+    return 1;
+  }
+
+  const inicio = Date.now();
+  let valid = true;
+  let errors = [];
+  let qualityScore = null;
+
+  // Validar contra schema si se especifica
+  if (schemaName) {
+    const schema = schemas[schemaName];
+    if (!schema) {
+      console.error(`Schema desconocido: ${schemaName}. Disponibles: ${Object.keys(schemas).filter(k => k.endsWith('_SCHEMA')).join(', ')}`);
+      return 1;
+    }
+    const r = validator.validar(output, schema);
+    valid = valid && r.valid;
+    if (!r.valid) errors.push(...r.errors);
+  }
+
+  // Validar campos esperados si se especifican
+  if (Array.isArray(definicion.expectedKeys)) {
+    for (const key of definicion.expectedKeys) {
+      if (!output || !(key in output)) {
+        valid = false;
+        errors.push(`expectedKey faltante: ${key}`);
+      }
+    }
+  }
+
+  // Calcular quality score si se especifica
+  if (qualityScorer) {
+    const scorer = quality[qualityScorer];
+    if (typeof scorer !== 'function') {
+      console.error(`Quality scorer desconocido: ${qualityScorer}. Disponibles: ${Object.keys(quality).join(', ')}`);
+      return 1;
+    }
+    qualityScore = scorer(output);
+  }
+
+  const latencyMs = Date.now() - inicio;
+  const exito = valid;
+
+  // Persistir resultado
+  const baseDir = process.cwd();
+  metricsStore.registrar(baseDir, {
+    functionId,
+    latencyMs,
+    success: exito,
+    qualityScore,
+    metadata: { schemaName, qualityScorer, evalFile: path.basename(ruta) },
+  });
+
+  // Reportar
+  console.log(JSON.stringify({
+    functionId,
+    valid,
+    errors: errors.length > 0 ? errors : undefined,
+    qualityScore,
+    latencyMs,
+  }, null, 2));
+
+  return valid ? 0 : 1;
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  if (args.length === 0) uso();
+
+  if (args[0] === '--rebuild-aggregate') {
+    const r = metricsStore.reconstruirAgregado(process.cwd());
+    console.log(`Agregado reconstruido: ${r.rebuilt} eventos, ${r.functions} funciones únicas.`);
+    process.exit(0);
+  }
+
+  process.exit(ejecutarEval(args[0]));
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = {
+  ejecutarEval,
+};