@saulwade/swl-ses 1.1.4 → 1.2.0

package/CLAUDE.md

@@ -1,4 +1,4 @@
-# CLAUDE.md — @saulwade/swl-ses v1.1.4
+# CLAUDE.md — @saulwade/swl-ses v1.2.0
 
 ## Reglas de máxima prioridad (aplican SIEMPRE, sin excepción)
 
@@ -23,7 +23,7 @@ El Read tool sigue siendo correcto para `.pdf` (≤20 páginas), `.md`, `.txt` y
 ## Qué es este repositorio
 
 Sistema de ingeniería de software auto-evolutivo multi-runtime polyglot (SDLC completo).
-11 lenguajes, 5 runtimes, 59 agentes, 151 skills, 42 comandos, 64 reglas, 39 hooks.
+11 lenguajes, 5 runtimes, 59 agentes, 153 skills, 42 comandos, 64 reglas, 40 hooks.
 **Idioma**: 100% español (México) para componentes SWL y skills Anthropic en inglés.
 
 ## Estructura del repositorio

package/README.md

@@ -1,4 +1,4 @@
-# swl-ses v1.1.4
+# swl-ses v1.2.0
 
 > El paquete anterior `@saulwadeleon/swl-software-engineering-system` está deprecado. Migrar a `@saulwade/swl-ses` (npmjs.org canónico) o `@saul-wade/swl-ses` (mirror en GitHub Packages) — el CLI `swl-ses` no cambia.
 
@@ -177,7 +177,7 @@ claude
 | `mobile` | Android + iOS + React Native/Flutter + UX |
 | `devops` | CI/CD + cloud + observabilidad + releases + seguridad |
 | `polyglot` | Todos los lenguajes: 11 lenguajes + revisores + build resolvers |
-| `completo` | Todo: 59 agentes + 151 habilidades + 42 comandos + 64 reglas + 39 hooks |
+| `completo` | Todo: 59 agentes + 153 habilidades + 42 comandos + 64 reglas + 40 hooks |
 
 ### Targets soportados
 
@@ -478,7 +478,7 @@ swl-ses/
       seguridad.js          # Validaciones de seguridad
   manifiestos/              # Perfiles y módulos de instalación
   agentes/                  # 59 agentes especializados
-  habilidades/              # 151 habilidades modulares
+  habilidades/              # 153 habilidades modulares
   comandos/swl/             # 42 comandos slash
   reglas/                   # 20 reglas base + 40 por lenguaje
   hooks/                    # 39 hooks + 62 librerías en hooks/lib/

package/bin/swl-mcp-server.js

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * swl-mcp-server — Servidor MCP **EXPERIMENTAL** para exponer la memoria
+ * de swl-ses a clientes MCP externos (Cursor, Gemini CLI, OpenCode, etc.).
+ *
+ * **NO PRODUCCIÓN — STUB EXPERIMENTAL**.
+ * Ver `scripts/mcp-server/README.md` para limitaciones detalladas.
+ *
+ * Modo de transporte: stdio (JSON-RPC sobre stdin/stdout).
+ * No HTTP, no auth, no rate limiting.
+ *
+ * Uso (cliente MCP):
+ *   - Configurar el cliente para ejecutar `node /path/to/swl-ses/bin/swl-mcp-server.js`
+ *     con stdio.
+ *   - Los handlers leen el cwd del proceso para localizar `.planning/`,
+ *     `instintos/`, `APRENDIZAJES.md`. Por defecto usa `process.cwd()`.
+ *   - Override con env var `SWL_MCP_BASE_DIR` si el cliente arranca el server
+ *     desde otro directorio.
+ *
+ * Protocolo MCP soportado (subset):
+ *   - initialize / initialized
+ *   - tools/list
+ *   - tools/call
+ *
+ * NO soporta:
+ *   - resources/list, prompts/list
+ *   - logging, sampling
+ *   - cancellation, progress
+ *   - HTTP transport
+ *
+ * Trigger documentado para implementación completa: "uso ≥2 runtimes
+ * diferentes (Cursor + Claude Code o similar) consistentemente por
+ * ≥1 mes". Hoy: 0 instalaciones reportadas.
+ */
+
+const path = require('path');
+
+const { HANDLERS } = require('../scripts/mcp-server/handlers');
+
+const SERVER_NAME = 'swl-mcp-server';
+const SERVER_VERSION = '0.1.0-experimental';
+const PROTOCOL_VERSION = '2024-11-05';
+
+const baseDir = process.env.SWL_MCP_BASE_DIR || process.cwd();
+
+// ── logging ───────────────────────────────────────────────────────────────────
+
+// Stderr para evitar contaminar stdout (que es JSON-RPC).
+function log(level, msg, data) {
+  const linea = JSON.stringify({
+    timestamp: new Date().toISOString(),
+    level,
+    msg,
+    ...(data ? { data } : {}),
+  });
+  process.stderr.write(linea + '\n');
+}
+
+// ── JSON-RPC helpers ──────────────────────────────────────────────────────────
+
+function respuesta(id, result) {
+  return JSON.stringify({ jsonrpc: '2.0', id, result });
+}
+
+function errorResp(id, code, message) {
+  return JSON.stringify({ jsonrpc: '2.0', id, error: { code, message } });
+}
+
+// ── routing ───────────────────────────────────────────────────────────────────
+
+function manejarInitialize(request) {
+  return respuesta(request.id, {
+    protocolVersion: PROTOCOL_VERSION,
+    capabilities: {
+      tools: { listChanged: false },
+    },
+    serverInfo: {
+      name: SERVER_NAME,
+      version: SERVER_VERSION,
+    },
+  });
+}
+
+function manejarToolsList(request) {
+  const tools = Object.entries(HANDLERS).map(([name, def]) => ({
+    name,
+    description: def.description,
+    inputSchema: def.inputSchema,
+  }));
+  return respuesta(request.id, { tools });
+}
+
+function manejarToolsCall(request) {
+  const { name, arguments: args } = request.params || {};
+  const def = HANDLERS[name];
+  if (!def) {
+    return errorResp(request.id, -32601, `Tool no encontrado: ${name}`);
+  }
+  try {
+    const result = def.handler(baseDir, args || {});
+    return respuesta(request.id, {
+      content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+    });
+  } catch (err) {
+    log('error', `Excepción en handler ${name}`, { error: err.message });
+    return errorResp(request.id, -32603, `Error interno: ${err.message}`);
+  }
+}
+
+function rutear(request) {
+  switch (request.method) {
+    case 'initialize':
+      return manejarInitialize(request);
+    case 'initialized':
+    case 'notifications/initialized':
+      return null; // notification — sin respuesta
+    case 'tools/list':
+      return manejarToolsList(request);
+    case 'tools/call':
+      return manejarToolsCall(request);
+    case 'ping':
+      return respuesta(request.id, {});
+    default:
+      return errorResp(request.id, -32601, `Método no soportado: ${request.method}`);
+  }
+}
+
+// ── loop principal ────────────────────────────────────────────────────────────
+
+function arrancar() {
+  log('warn', '⚠ swl-mcp-server stub experimental — NO usar en producción');
+  log('info', `Server iniciando`, { name: SERVER_NAME, version: SERVER_VERSION, baseDir });
+
+  let buffer = '';
+
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (chunk) => {
+    buffer += chunk;
+
+    // Cada mensaje JSON-RPC termina con \n
+    let nlIndex;
+    while ((nlIndex = buffer.indexOf('\n')) >= 0) {
+      const linea = buffer.slice(0, nlIndex).trim();
+      buffer = buffer.slice(nlIndex + 1);
+
+      if (!linea) continue;
+
+      let request;
+      try {
+        request = JSON.parse(linea);
+      } catch (err) {
+        log('error', 'JSON inválido recibido', { error: err.message, linea: linea.slice(0, 100) });
+        process.stdout.write(errorResp(null, -32700, 'Parse error') + '\n');
+        continue;
+      }
+
+      const respuestaStr = rutear(request);
+      if (respuestaStr) {
+        process.stdout.write(respuestaStr + '\n');
+      }
+    }
+  });
+
+  process.stdin.on('end', () => {
+    log('info', 'stdin cerrado, server termina');
+    process.exit(0);
+  });
+
+  // Manejo de errores no capturados — nunca crashear silenciosamente
+  process.on('uncaughtException', (err) => {
+    log('error', 'uncaughtException', { error: err.message, stack: err.stack });
+  });
+}
+
+if (require.main === module) {
+  arrancar();
+}
+
+module.exports = {
+  rutear,
+  arrancar,
+  SERVER_NAME,
+  SERVER_VERSION,
+  PROTOCOL_VERSION,
+};

package/habilidades/benchmark-memoria/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: benchmark-memoria
+description: >
+  Benchmark de retrieval para `hooks/lib/memory-search` que mide R@5, R@10,
+  MRR y nDCG@10 contra un dataset de queries con respuestas conocidas
+  (gold_ids). Útil para detectar regresión de calidad de búsqueda al cambiar
+  RRF weights, scoring o fuentes. Cargar cuando se modifique
+  `memory-search.js`, `rrf-fusion.js` o `session-fts.js` para verificar que
+  no degrada retrieval. NO cargar para uso operacional ni para evaluar
+  outputs de agentes (eso es `eval-framework`).
+version: "1.0.0"
+herramientasPermitidas: [Read, Bash]
+exclusiones:
+  - "No cargar para evaluar outputs de agentes (aprendizajes, observaciones, resúmenes); eso es `eval-framework`."
+  - "No cargar como gate de release sin un dataset ≥30 entries con status='real' — las métricas con dataset placeholder no son estadísticamente significativas."
+  - "No cargar para benchmark de performance (latencia, throughput); eso es `performance-baseline`."
+  - "No cargar si el repo no tiene `.planning/APRENDIZAJES.md` ni sesiones — sin contenido no hay nada que recuperar."
+evolvable: true  # default para skill estandar
+---
+# Benchmark de Memoria — LongMemEval-S adaptado a SWL
+
+## Cuándo cargar esta skill
+
+- Tras modificar `hooks/lib/memory-search.js`, `scripts/lib/rrf-fusion.js`,
+  pesos de fusión o algoritmo de scoring de relevancia.
+- Tras agregar fuentes de búsqueda nuevas (ej. evals, instintos globales).
+- Antes de un release que toque la capa de memoria, para confirmar que no
+  hay regresión en R@5.
+- Como parte opcional de `/swl:salud` cuando `SWL_BENCHMARK_MEMORIA=1`.
+
+---
+
+## Componentes del benchmark
+
+| Módulo | Propósito |
+|---|---|
+| `scripts/lib/benchmark-metrics.js` | Funciones puras: `recallAt`, `precisionAt`, `mrr`, `ndcgAt`, `dcg`, `calcularMetricas`, `promediar`. |
+| `scripts/lib/longmemeval-runner.js` | Adapter que ejecuta queries contra `memory-search` y compara con gold. |
+| `scripts/benchmark-memoria.js` | CLI runner principal. |
+| `.planning/benchmark/dataset.jsonl` | Dataset (placeholder por defecto, debe expandirse). |
+
+---
+
+## Estado del dataset (CRÍTICO leer antes de usar)
+
+El dataset por defecto en `.planning/benchmark/dataset.jsonl` es **placeholder**
+con 10 entries marcadas explícitamente como `"status": "placeholder"`. Las
+métricas calculadas con este dataset son **indicativas, no estadísticamente
+significativas**.
+
+### Limitaciones del dataset placeholder
+
+1. **IDs volátiles**: los `gold_ids` referencian `apr-N` (índice de entrada en
+   `APRENDIZAJES.md`). Si se agregan/borran entradas, los índices cambian y
+   el dataset queda desincronizado. Para dataset real considerar IDs estables
+   (sesiones tienen timestamp; instintos tienen `id` propio).
+2. **N=10 es ruido estadístico**: para que R@5=80% sea significativo
+   estadísticamente (vs 70% baseline), se requieren al menos 30 queries
+   con N=10 random. Por debajo, las métricas reflejan suerte.
+3. **Cobertura limitada**: el placeholder cubre solo categorías técnicas
+   (patrones, gotchas, decisiones). Falta cobertura de:
+   - Bug fixes históricos
+   - Workflow questions ("qué hicimos antes de X")
+   - Cross-session ("cuándo se decidió Y")
+   - Negative queries (preguntas cuya respuesta es "no aplica")
+
+### Cómo expandir a dataset real
+
+```bash
+# 1. Identifica una pregunta real de uso
+QUERY="qué hicimos sobre force push a main protegida"
+
+# 2. Ejecuta búsqueda y anota top-5 IDs
+node -e "console.log(require('./hooks/lib/memory-search').search('.', '$QUERY').slice(0, 5).map(r => r.id + ' / ' + r.titulo).join('\n'))"
+
+# 3. Verifica manualmente qué IDs son CORRECTOS (revisión humana,
+#    no se inventa). Solo esos van en gold_ids.
+
+# 4. Agrega la entry al dataset:
+cat >> .planning/benchmark/dataset.jsonl << 'EOF'
+{"question_id": "q-real-001", "question": "qué hicimos sobre force push a main protegida", "gold_ids": ["apr-313"], "category": "decision", "status": "real"}
+EOF
+```
+
+Repetir hasta tener ≥30 entries con `status: "real"`. Solo entonces el
+benchmark es gate de release.
+
+---
+
+## Uso
+
+### CLI básico
+
+```bash
+# Ejecutar benchmark con dataset por defecto
+node scripts/benchmark-memoria.js
+
+# Output esperado:
+#   Recall @ 5:     85.0%
+#   Recall @ 10:    92.0%
+#   MRR:            0.741
+#   nDCG @ 10:      0.812
+#   Precision @ 5:  41.3%
+```
+
+### Opciones
+
+```bash
+# Dataset alternativo
+node scripts/benchmark-memoria.js --dataset .planning/benchmark/custom.jsonl
+
+# Top-k personalizado (default 20)
+node scripts/benchmark-memoria.js --limit 30
+
+# Output JSON (para scripts)
+node scripts/benchmark-memoria.js --json
+
+# Detalle por query (útil para debugging)
+node scripts/benchmark-memoria.js --verbose
+```
+
+### Tracking histórico opcional
+
+Si se setea `SWL_BENCHMARK_PERSIST=1`, el benchmark escribe el resumen
+agregado a `.planning/evolucion/benchmark-memoria.jsonl` (append-only)
+para detectar regresión entre releases:
+
+```bash
+SWL_BENCHMARK_PERSIST=1 node scripts/benchmark-memoria.js
+```
+
+Comparar entre releases:
+```bash
+tail -5 .planning/evolucion/benchmark-memoria.jsonl | jq -c '{ts: .timestamp, r5: .promedio.recall_at_5}'
+```
+
+---
+
+## Métricas explicadas
+
+| Métrica | Significado | Rango |
+|---|---|---|
+| **Recall @ k** | ¿El sistema recuperó al menos un gold ID en los primeros k? | 0 o 1 por query, promediado en [0, 1] |
+| **Precision @ k** | ¿Qué porcentaje de los primeros k son gold? | [0, 1] |
+| **MRR** | 1 / posición del primer gold encontrado | [0, 1] — alto = gold cerca del top |
+| **nDCG @ k** | DCG normalizado: penaliza gold en posiciones bajas | [0, 1] — mide ranking quality |
+
+**Interpretación**:
+- R@5 alto + MRR bajo → encuentra gold pero no en posición 1.
+- R@5 bajo + R@10 alto → necesita expandir top-k para alcanzar.
+- nDCG@10 alto → ranking respeta orden de relevancia.
+
+---
+
+## Anti-patrones (qué NO hacer)
+
+- **Usar el dataset placeholder como gate de CI**: no significativo, da
+  falsa sensación de seguridad. Marcar el job como informativo solamente
+  hasta tener dataset real ≥30.
+- **Inventar gold_ids "que se ven correctos"**: el dataset SOLO sirve si
+  los gold_ids son verificados manualmente como correctos por un humano
+  con conocimiento del proyecto.
+- **Optimizar el algoritmo solo para que las métricas suban**: si el
+  dataset es placeholder, "mejorar" R@5 puede ser overfitting al
+  placeholder. Dataset real primero, optimización después.
+- **Borrar entries que dan métricas bajas**: una query con R@5=0 puede
+  estar revelando un bug real del sistema de búsqueda, no un problema
+  del dataset. Debug antes de borrar.
+
+---
+
+## Gotchas / Errores comunes no obvios
+
+- **Dataset JSONL acepta comentarios `//`**: las líneas que empiezan con
+  `//` son ignoradas. Útil para documentar inline. NO es JSON estándar
+  pero el parser de `longmemeval-runner` lo respeta.
+- **Si la query no matchea ningún token mínimo (<= 3 chars), `search()`
+  devuelve `[]`**: las stop words están filtradas en
+  `hooks/lib/memory-search.js`. Asegurar que cada query tenga ≥2
+  términos significativos.
+- **Los `gold_ids` deben usar el formato `apr-N`/`ses-YYYYMMDD-HHmm`/etc.
+  EXACTO** que devuelve `memory-search`. Si se anota `apr-14` cuando el
+  search devuelve `apr-014`, el match falla silenciosamente.
+- **El benchmark mide `memory-search` específicamente, no toda la memoria
+  SWL**: instintos globales no entran si solo se buscan locales; sesiones
+  archivadas no entran. Documentar el scope de cada query.

package/habilidades/contenedores-docker/SKILL.md

@@ -1,7 +1,12 @@
 ---
 name: contenedores-docker
 description: Docker y containerización. Dockerfiles optimizados con multi-stage builds, docker-compose, volúmenes, networking, health checks, security scanning, build caching, distroless images. Anti-patrones comunes.
-version: "1.0.0"
+version: "1.0.1"
+evolved: true
+evolved-from: "1.0.0"
+evolved-at: "2026-05-05"
+evolved-by: "aprender"
+evolved-note: "Gotcha de la sesión SIGM 2026-05-05 (L6): scripts en /docker-entrypoint-initdb.d con dependencias externas (mc, aws, etc.) abortan initdb"
 herramientasPermitidas: [Read]
 exclusiones:
   - "No cargar para orquestación Kubernetes (Deployments, Services, Helm, HPA) — para Kubernetes cargar `kubernetes-orquestacion`."
@@ -135,3 +140,5 @@ Para ejemplos completos de multi-stage Node.js/Angular, .dockerignore, docker-co
 **Secrets pasados como `ARG` en el Dockerfile son visibles en `docker history` aunque se eliminen en una capa posterior**: `ARG SECRET_KEY` seguido de `RUN rm -f /app/.env` no elimina el valor del ARG del historial de la imagen — `docker history --no-trunc imagen` muestra los valores de los ARG. Causa: `docker history` registra los comandos de cada capa, incluyendo los valores de ARG usados. Fix: NUNCA pasar secretos como `ARG` o `ENV` en el Dockerfile; para secrets en build-time usar `--secret` de Docker BuildKit: `RUN --mount=type=secret,id=api_key cat /run/secrets/api_key`.
 
 **`.dockerignore` mal configurado incluye archivos `.env` o `node_modules` en el contexto de build, ralentizando el daemon y exponiendo secretos**: si `.dockerignore` no existe o no excluye `node_modules`, el contexto de build puede ser de cientos de MB — todo se transfiere al daemon antes del build. Causa: el contexto de build incluye todo el directorio por defecto. Fix: crear `.dockerignore` con al menos `.git`, `node_modules`, `__pycache__`, `.env*`, `*.pyc`, `dist`, `build`, y verificar el tamaño del contexto con `docker build` mirando la línea "Sending build context to Docker daemon X.XX MB".
+
+**Scripts en `database/init/` (mounted a `/docker-entrypoint-initdb.d`) no pueden depender de binarios fuera de la imagen base**: un script con `set -e` que invoca `mc` (cliente MinIO), `aws`, `gh`, `kubectl` o cualquier binario no presente en la imagen `postgres`/`postgis` aborta el initdb con `command not found` (exit 127). El contenedor sale con error y los scripts SQL que iban después (incluido schemas/seeds completos) NUNCA se ejecutan. Caso real (SIGM 2026-05-04): `02-crear-buckets-minio.sh` con `mc alias set` aborta `postgis/postgis:17-3.5` antes de cargar el schema; ningún schema se aplicaba aunque el archivo init.sh estaba bien. Causa: el directorio `/docker-entrypoint-initdb.d` ejecuta todos los archivos `.sh` y `.sql` en orden alfabético; cualquier fallo aborta toda la cadena. Fix: scripts que invocan binarios externos van en `scripts/setup/` o `scripts/init-deps/` y se ejecutan manualmente o via `docker compose run --rm --entrypoint /scripts/setup/X.sh <servicio_que_tiene_el_binario>`. Solo SQL puro o bash que use `psql` pueden vivir en `database/init/`.

package/habilidades/datos-etl/SKILL.md

@@ -4,7 +4,12 @@ description: >
   Ingeniería de datos y ETL: diseño de pipelines, calidad de datos, evolución de esquemas,
   CDC (change data capture), validación de datos, linaje de datos, procesamiento batch vs
   streaming, patrones dbt, patrones de data lake.
-version: "1.0.0"
+version: "1.0.1"
+evolved: true
+evolved-from: "1.0.0"
+evolved-at: "2026-05-05"
+evolved-by: "aprender"
+evolved-note: "Gotcha de la sesión SIGM 2026-05-05 (L9): seeds con check constraint fecha_vencimiento >= fecha_emision violan al usar emision única para todas las tuplas"
 herramientasPermitidas: [Read, Grep]
 evolvable: true  # default para skill estandar
 exclusiones:
@@ -127,3 +132,15 @@ esquemas (Avro), patrones dbt (modelos incrementales), y linaje de datos, ver
 **Validación con Great Expectations pasa en staging pero falla en producción con el mismo schema**: los expectations se definen sobre una muestra de datos de staging que puede no tener todos los valores posibles del dominio. Causa: un expectation de tipo `expect_column_values_to_be_in_set(["A","B","C"])` falla en producción cuando aparece un valor "D" válido que no existía en el sample de staging. Fix: para columnas con dominio abierto, usar `expect_column_values_to_not_be_null` en lugar de un set cerrado. Reservar sets cerrados solo para columnas con dominio verdaderamente finito y controlado (estados de máquina de estado, flags booleanos).
 
 **El job de Spark/pandas falla en producción por OOM aunque funcionó bien en staging con datos de muestra**: el procesamiento en memoria de un DataFrame completo escala linealmente con el volumen de datos. En staging con 10K registros todo cabe en RAM; en producción con 10M registros el proceso muere. Causa: operaciones como `groupby + apply` con funciones Python puras no se pueden paralelizar ni distribuir automáticamente. Fix: para transformaciones sobre datasets grandes, usar procesamiento por chunks (`chunksize` en pandas) o migrar a Spark/DuckDB para operaciones distribuidas. Medir el uso de memoria en staging con el volumen máximo esperado en producción, no con la muestra de desarrollo.
+
+**Seeds que simulan data histórica con check constraints de fechas relativas violan el constraint si se usa una sola fecha de emisión**: cuando un seed crea facturas/pagos demo con una mezcla de estatus (vencidas, vigentes, pagadas) y la tabla tiene check constraint del tipo `fecha_vencimiento >= fecha_emision`, generar `fecha_emision = '2025-12-10'` y luego asignar `fecha_vencimiento = '2025-10-31'` para vencidas viola el constraint. Caso real (SIGM 2026-05-04): seed `009-datos-operativos-demo.sql` con 500 facturas demo donde `n%10=0` representaba "vencidas" pero la fecha_emision común era posterior. Causa: la lógica genera dimensiones derivadas (vencimiento) sin re-derivar las fuente (emisión). Fix: separar fechas POR ESTATUS antes de generar tuplas:
+```sql
+-- Vencidas: emision en pasado profundo, vencimiento ya pasó
+CASE WHEN n % 10 = 0 THEN DATE '2025-09-30'
+     ELSE DATE '2025-12-10' + (n % 3)
+END AS fecha_emision,
+CASE WHEN n % 10 = 0 THEN DATE '2025-10-31'
+     ELSE DATE '2026-01-31'
+END AS fecha_vencimiento,
+```
+Generalización: cualquier check constraint que relacione columnas debe respetarse al SEEDEAR, no solo en INSERT productivo.

package/habilidades/eval-framework/SKILL.md

@@ -0,0 +1,212 @@
+---
+name: eval-framework
+description: >
+  Eval framework para validar y puntuar outputs estructurados de SWL
+  (aprendizajes, instintos, observaciones, resúmenes, contextos). Cargar
+  cuando un agente produzca un output estructurado y se quiera medir su
+  calidad antes de persistir, o cuando se audite la calidad histórica de
+  funciones críticas (extractor-de-aprendizajes, perfilador-usuario,
+  consolidador, planificador).
+version: "1.0.0"
+herramientasPermitidas: [Read, Bash]
+exclusiones:
+  - "No cargar para validación de input de usuario o request HTTP — eso es validación de boundary, usar Pydantic/Zod en el endpoint."
+  - "No cargar para auditoría de seguridad — usar `revisor-seguridad-swl` y `escaneo-secretos`."
+  - "No cargar para tests unitarios de código — usar `tdd-workflow` y Vitest."
+  - "No cargar cuando el output no tiene estructura definida (texto libre): el eval framework requiere schemas declarados o quality scorers específicos."
+evolvable: true  # default para skill estandar
+---
+# Eval Framework — Validación + Calidad de Outputs SWL
+
+## Cuándo cargar
+
+- Tras producir un output estructurado (observación, aprendizaje, resumen,
+  resultado de búsqueda) cuando se quiera puntuar su calidad antes de
+  persistir.
+- Para auditar histórico de calidad de una función crítica (ver métricas
+  agregadas en `.planning/evolucion/eval-metrics.json`).
+- En tests/CI cuando el contrato del output tenga campos obligatorios y
+  quality thresholds.
+- En loops de auto-corrección donde un output inválido debe regenerarse
+  con un prompt más estricto.
+
+---
+
+## Componentes del framework
+
+| Módulo | Propósito |
+|---|---|
+| `scripts/lib/eval-schemas.js` | Schemas JSON-lite para outputs (observación, resumen, search input, etc.). |
+| `scripts/lib/eval-validator.js` | Validador zero-deps de schemas (sin Zod). |
+| `scripts/lib/eval-quality.js` | Funciones de scoring: `scoreObservacion`, `scoreResumen`, `scoreAprendizaje`, `scoreInstinto`, `scoreRelevanciaContexto`. |
+| `scripts/lib/eval-self-correct.js` | Loop de retry con sufijo estricto cuando validador falla. |
+| `scripts/lib/eval-metrics-store.js` | Persistencia: JSONL append-only (`eval-results.jsonl`) + agregado JSON (`eval-metrics.json`). |
+| `scripts/run-eval.js` | CLI para evaluar un output desde archivo JSON. |
+
+---
+
+## Uso típico desde agente o test
+
+### Validar output contra schema
+
+```js
+const { validar } = require('./scripts/lib/eval-validator');
+const { COMPRESS_OUTPUT_SCHEMA } = require('./scripts/lib/eval-schemas');
+
+const observacion = {
+  type: 'discovery',
+  title: 'Detalle relevante',
+  facts: ['fact 1', 'fact 2'],
+  narrative: 'Narrativa con suficiente detalle para evaluar',
+  concepts: ['c1'],
+  files: ['ruta/al/archivo.js'],
+  importance: 7,
+};
+
+const r = validar(observacion, COMPRESS_OUTPUT_SCHEMA);
+if (!r.valid) {
+  console.error('Output inválido:', r.errors);
+} else {
+  // Persistir
+}
+```
+
+### Puntuar calidad (independiente de validez)
+
+```js
+const { scoreObservacion, scoreAprendizaje, scoreInstinto } = require('./scripts/lib/eval-quality');
+
+const score = scoreObservacion(observacion);
+// score ∈ [0, 100]. 100 = todos los campos óptimos.
+```
+
+### Loop de auto-corrección
+
+```js
+const { compresseConReintento } = require('./scripts/lib/eval-self-correct');
+
+const productor = async (sysPrompt, userPrompt) => {
+  // Llamar al LLM o ejecutar Skill que produzca el output
+  return await llamarClaude(sysPrompt, userPrompt);
+};
+
+const validador = (output) => {
+  const parsed = JSON.parse(output);
+  return validar(parsed, COMPRESS_OUTPUT_SCHEMA);
+};
+
+const r = await compresseConReintento({
+  productor, validador,
+  sysPrompt: '...', userPrompt: '...',
+  maxRetries: 2,
+});
+
+if (r.valid) {
+  // r.output es válido (puede haber requerido r.intentos retries)
+}
+```
+
+### Persistir métricas para auditoría histórica
+
+```js
+const ms = require('./scripts/lib/eval-metrics-store');
+
+ms.registrar(process.cwd(), {
+  functionId: 'extractor-de-aprendizajes::scorer',
+  latencyMs: 42,
+  success: true,
+  qualityScore: 85,
+});
+
+// Lectura agregada
+const m = ms.obtener(process.cwd(), 'extractor-de-aprendizajes::scorer');
+// → { totalCalls, successCount, failureCount, avgLatencyMs, avgQualityScore, ... }
+```
+
+### CLI desde Bash (para CI o manual)
+
+```bash
+# Crear archivo de eval
+cat > /tmp/eval.json << 'EOF'
+{
+  "functionId": "memoria-busqueda::search",
+  "schemaName": "MEMORY_SEARCH_RESULT_SCHEMA",
+  "qualityScorer": null,
+  "expectedKeys": ["id", "tipo", "titulo", "fecha", "relevancia"],
+  "output": { ... }
+}
+EOF
+
+# Ejecutar
+node scripts/run-eval.js /tmp/eval.json
+# Exit 0 si valid, 1 si inválido. Persiste métricas automáticamente.
+
+# Reconstruir agregado desde JSONL si se corrompe
+node scripts/run-eval.js --rebuild-aggregate
+```
+
+---
+
+## Schemas disponibles
+
+- `COMPRESS_OUTPUT_SCHEMA` — observación comprimida con type, title, facts,
+  narrative, concepts, files, importance.
+- `SUMMARY_OUTPUT_SCHEMA` — resumen de sesión con title, narrative,
+  keyDecisions, filesModified, concepts.
+- `SEARCH_INPUT_SCHEMA` — input de búsqueda { query, limit? }.
+- `REMEMBER_INPUT_SCHEMA` — input de "remember" { content, type?,
+  concepts?, files? }.
+- `EVAL_RESULT_SCHEMA` — resultado de evaluación { valid, errors?,
+  qualityScore, latencyMs, functionId, metadata? }.
+- `MEMORY_SEARCH_RESULT_SCHEMA` — resultado de `hooks/lib/memory-search`
+  con id, tipo, titulo, fecha, relevancia, combinedScore?, confidence?.
+
+Agregar más schemas en `scripts/lib/eval-schemas.js` siguiendo el formato
+JSON Schema-lite (subset documentado en `eval-validator.js`).
+
+---
+
+## Quality scorers disponibles
+
+- `scoreObservacion(obs)` — observación con type/title/facts/narrative/concepts/importance.
+- `scoreResumen(summary)` — resumen con title/narrative/keyDecisions/filesModified/concepts.
+- `scoreAprendizaje(aprendizaje)` — aprendizaje SWL con titulo/contenido/tipo (específico de SWL).
+- `scoreInstinto(instinto)` — instinto con pattern/confidence/status/source_*/evidence_count (específico de SWL).
+- `scoreRelevanciaContexto(context, project)` — contexto inyectado en sesión.
+
+Cada scorer devuelve un número en [0, 100]. Los criterios están documentados
+en cada función en `scripts/lib/eval-quality.js`.
+
+---
+
+## Diferencias con tests unitarios
+
+| Eval framework | Tests unitarios |
+|---|---|
+| Mide calidad subjetiva sobre estructura | Mide correctitud lógica |
+| Score graduado [0, 100] | Pass/fail binario |
+| Persiste histórico para auditoría | No persiste (corre en CI) |
+| Para outputs estructurados de agentes | Para funciones puras / API |
+| Permite retry con prompt estricto | No aplicable |
+
+Los dos son complementarios: tests unitarios para `scoring-instintos.js`,
+eval framework para "¿el aprendizaje que extrajo el hook es de calidad?".
+
+---
+
+## Gotchas / Errores comunes no obvios
+
+- **Validez estructural ≠ calidad**: un aprendizaje con `titulo: "X"` y
+  `contenido: "trivial"` puede pasar `expectedKeys` pero tener
+  `qualityScore: 0`. El framework los distingue. En CI gates, considerar
+  ambos: `valid && qualityScore >= 60`.
+- **Métricas agregadas se reescriben atómicamente**: si dos procesos
+  llaman `registrar()` en paralelo sobre el mismo `functionId`, el último
+  gana (race condition en agregado). Para alta concurrencia usar
+  `reconstruirAgregado()` periódicamente desde el JSONL append-only.
+- **`run-eval.js` exit code**: 0 = valid, 1 = inválido o error de I/O,
+  2 = error de uso. No confundir con quality threshold — el CLI no
+  bloquea por quality bajo, solo por validez.
+- **`compresseConReintento` no reintenta indefinidamente**: respeta
+  `maxRetries`. Tras agotar reintentos devuelve el último output con
+  `valid: false`. El caller decide qué hacer.