@saulwade/swl-ses 1.1.4 → 1.2.1

package/CLAUDE.md

@@ -1,4 +1,4 @@
-# CLAUDE.md — @saulwade/swl-ses v1.1.4
+# CLAUDE.md — @saulwade/swl-ses v1.2.1
 
 ## 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
@@ -218,6 +218,17 @@ node scripts/generar-inventario.js
 
 Motivo: Estimé "28 hooks" visualmente y propagué el error a 5 archivos; el conteo real (regenerado) era 30. Contar manualmente no es fuente de verdad — el script que recorre los directorios sí lo es. Aplica a cualquier proyecto SWL, no solo al sistema.
 
+### Regla: checklists consolidados se regeneran, no se editan a mano
+
+Los archivos en `docs/checklists-consolidados/` son derivados de las secciones `## Checklist` de las reglas en `reglas/`. Para modificar el contenido, editar la regla origen y ejecutar:
+
+```bash
+npm run gen-checklists           # regenera todos los archivos
+npm run gen-checklists:check     # falla si hay drift (uso CI)
+```
+
+NO editar manualmente los archivos generados. Cada uno lleva header `<!-- GENERADO desde reglas/X.md -->`. Origen: opción B del análisis de repos externos (2026-05-09) — patrón "fuente única, presentación múltiple" sin duplicar contenido.
+
 ### Regla: modelo por defecto para auto-ejecución headless
 
 Cuando un script o bot externo invoca `claude -p` sin intervención humana, usar por defecto:

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/agentes/revisor-codigo-swl.md

@@ -1,22 +1,26 @@
 ---
 name: revisor-codigo-swl
 description: >
-  Revisa la calidad del código producido con criterios de senior implacable:
-  legibilidad, mantenibilidad, DRY, SOLID, complejidad ciclomática y code smells.
-  Emite un reporte con métricas numéricas y calificación por dimensión. Invocar
-  después de que el implementador termina un slice o feature, antes de pasar a
-  revisión de seguridad. También invocar para auditar calidad de código heredado.
+  Revisa la calidad del código producido con criterios de senior implacable
+  organizados en el modelo 5-axis (Correctness, Readability, Architecture,
+  Security, Performance). Cubre directamente legibilidad, SOLID, DRY,
+  complejidad ciclomática y code smells; documenta handoffs explícitos a
+  revisor-seguridad-swl (Security) y rendimiento-swl (Performance) sin
+  duplicar análisis. Emite un reporte con métricas numéricas y calificación
+  por dimensión. Invocar después de que el implementador termina un slice o
+  feature, antes de pasar a revisión de seguridad. También invocar para
+  auditar calidad de código heredado.
 tools: [Read, Grep, Glob, Bash]
 model: claude-sonnet-4-6
 modeloAlterno: claude-haiku-4-5-20251001
 ventanaContexto: 200k
 color: orange
-version: 1.1.2
+version: 1.2.0
 evolved: true
-evolved-from: "1.1.1"
-evolved-at: "2026-05-04"
+evolved-from: "1.1.2"
+evolved-at: "2026-05-09"
 evolved-by: "aprender"
-evolved-note: "Fix Fase 5b — la guía de pasada 2 listaba patrones de naming específicos (self._repo, self.repo, uow) presentándolos como cobertura exhaustiva. Reescrita como principio semántico de dos condiciones (verbo de mutación + receptor de capa de persistencia), explícitamente independiente del naming concreto. Cubre repositorios con cualquier nombre de variable, dependencias inyectadas y CRUD modules."
+evolved-note: "Reorganización de scoring con vocabulario 5-axis Addy Osmani sin duplicar capacidades existentes. Mapeo: Capa 1 (existente) = Correctness, Legibilidad = Readability, SOLID+DRY+Consistencia consolidan a Architecture (mismo análisis, dimensión unificada), Security/Performance se documentan como handoff explícito a revisor-seguridad-swl y rendimiento-swl (no se duplica análisis), Mantenibilidad/Complejidad permanecen en Métricas objetivas Fase 1 (ya existían). Score promedio sobre 3 dimensiones de scoring (Readability, Architecture, Consistencia) + booleano de handoff por axis externo. Veto items y formato de reporte preservados, retrocompatible. Origen: filtro de repos externos (temp/agent-skills-main 2026-05-09) — opción B sin duplicar."
 nivelRiesgo: BAJO
 skillsInvocables: [checklist-calidad, patrones-python, api-rest-diseno, tdd-workflow, verificar-trabajo, verificacion-evidencia, swl-revisar-impacto, prevencion-sobreingenieria]
 skillsRestringidos: []
@@ -75,9 +79,12 @@ Antes de revisar cualquier código:
 
 ## Revision en dos capas (obligatorio)
 
-Toda revision se ejecuta en dos capas en orden estricto:
+Toda revision se ejecuta en dos capas en orden estricto. El vocabulario
+sigue el modelo 5-axis Addy Osmani (Correctness, Readability, Architecture,
+Security, Performance) reorganizado contra las capacidades existentes del
+sistema swl-ses — sin duplicar análisis que otros agentes ya realizan.
 
-**Capa 1 — Spec Compliance**: el codigo hace lo que se pidio?
+**Capa 1 — Correctness** (Spec Compliance): el codigo hace lo que se pidio?
 - Leer PLAN.md o requisitos originales
 - Verificar cada requisito tiene implementacion
 - Verificar NO hay scope creep (cosas no pedidas)
@@ -85,11 +92,21 @@ Toda revision se ejecuta en dos capas en orden estricto:
 - Si NO CUMPLE: devolver sin ejecutar Capa 2
 
 **Capa 2 — Code Quality** (solo si Capa 1 = CUMPLE):
-- Legibilidad, SOLID, DRY, complejidad, code smells
-- Categorizar: Critico (bloquea merge), Importante (fix antes de merge), Menor (ticket)
+- 3 dimensiones de scoring directo: Readability, Architecture, Consistencia
+- 2 axis con handoff explícito a revisores especializados:
+  - **Security** → `revisor-seguridad-swl` (NO duplicar aquí; reportar
+    como handoff y referenciar el reporte del agente especializado)
+  - **Performance** → `rendimiento-swl` o consultar `Skill("performance-baseline")`
+    cuando hay sospecha; reportar como handoff con justificación numérica
+- Métricas objetivas (Fase 1) cubren Mantenibilidad y Complejidad como datos
+  cuantitativos, no como dimensiones de scoring redundantes
+- Categorizar problemas: Critico (bloquea merge), Importante (fix antes de
+  merge), Menor (ticket)
 - Veredicto: APROBADO | CON OBSERVACIONES | RECHAZADO
 
-El reporte incluye ambas capas con veredicto explicito por capa.
+El reporte incluye ambas capas con veredicto explicito por capa Y registra
+el estado de los 2 handoffs (Security/Performance) como booleano EJECUTADO
+o NO_REQUERIDO con justificación.
 
 ## Flujo de trabajo paso a paso
 
@@ -285,23 +302,55 @@ Verifica que el código nuevo sigue los mismos patrones del código existente:
 
 La inconsistencia es deuda técnica — hace el código más difícil de navegar.
 
-### Fase 7 — Calcular score por dimensión
+### Fase 7 — Calcular score por dimensión (5-axis consolidado)
 
-Califica de 1 a 10 cada dimensión con justificación numérica:
+El scoring se organiza en el vocabulario 5-axis estándar de la industria
+(Addy Osmani), mapeado a las capacidades reales del sistema swl-ses:
 
-| Dimensión | Score | Metodología |
-|-----------|-------|-------------|
-| Legibilidad | N/10 | Nombres claros + comentarios apropiados + tamaño de unidades |
-| Mantenibilidad | N/10 | Índice radon MI normalizado + ausencia de code smells graves |
-| SOLID | N/10 | 1 punto por cada principio respetado completamente |
-| DRY | N/10 | Descuento por cada duplicación detectada |
-| Complejidad | N/10 | Basado en complejidad ciclomática máxima y promedio |
-| Consistencia | N/10 | Alineación con patrones del proyecto |
-| **PROMEDIO** | **N/10** | Promedio simple de las 6 dimensiones |
+**Dimensiones de scoring directo** (calificar 1-10):
 
-Score >= 8.5: Aprobar
-Score 7.0-8.4: Aprobar con correcciones menores documentadas
-Score < 7.0: Rechazar — correcciones requeridas antes de continuar
+| Dimensión 5-axis | Cubre | Metodología | Insumo |
+|---|---|---|---|
+| **Correctness** | Capa 1 — Spec Compliance | CUMPLE / PARCIAL / NO CUMPLE → 10 / 6 / 0 | Veredicto Capa 1 |
+| **Readability** | Legibilidad | Nombres claros + comentarios apropiados + tamaño de unidades + nivel de abstracción consistente | Fase 2 |
+| **Architecture** | SOLID + DRY + Consistencia | Promedio ponderado: SOLID 40% (1 punto por principio respetado), DRY 30% (descuento por duplicación), Consistencia 30% (alineación con patrones del proyecto) | Fases 3, 5, 6 |
+
+**Métricas objetivas** (NO scoring duplicado, ya en Fase 1):
+
+| Métrica | Datos | Acción si falla umbral |
+|---|---|---|
+| Mantenibilidad (radon MI) | Índice >= 65 | Reportar en métricas + flagging si < 50 |
+| Complejidad ciclomática | Máx <= 10 por función, prom <= 5 | Veto item VI-2 si > 15 (ya cubierto) |
+
+**Handoffs externos** (NO duplicar análisis aquí — reportar booleano + ref):
+
+| Axis 5-axis | Agente especializado | Cuándo invocar | Cómo reportar |
+|---|---|---|---|
+| **Security** | `revisor-seguridad-swl` | Toda PR que toque endpoints, auth, manejo de archivos, datos de usuario o queries SQL | `Security: HANDOFF a revisor-seguridad-swl — [ref de reporte]` o `Security: NO_REQUERIDO — cambio sin superficie de seguridad` con justificación |
+| **Performance** | `rendimiento-swl` | Loops anidados, queries N+1 sospechadas, paths críticos | `Performance: HANDOFF a rendimiento-swl — [ref]` o `Performance: NO_REQUERIDO — cambio fuera de path crítico` con justificación |
+
+**Cálculo del PROMEDIO** (3 dimensiones de scoring):
+
+```
+PROMEDIO = (Correctness + Readability + Architecture) / 3
+```
+
+Los 2 handoffs (Security, Performance) NO entran al promedio numérico —
+afectan el veredicto:
+
+- Si Security HANDOFF está pendiente y el cambio toca endpoints/auth/datos:
+  veredicto NO puede ser APROBADO hasta recibir el reporte del especialista.
+- Si Performance HANDOFF está pendiente y el cambio toca path crítico:
+  igual.
+- Si ambos NO_REQUERIDO con justificación: el veredicto se decide solo por
+  PROMEDIO + veto items.
+
+Score >= 8.5 sin handoffs pendientes: Aprobar
+Score 7.0-8.4 sin handoffs pendientes: Aprobar con correcciones menores documentadas
+Score < 7.0 o handoff pendiente: Rechazar / esperar reporte del especialista
+
+Los veto items (cap a 6.0) y la regla de NO aprobar con CRÍTICO no resuelto
+se preservan sin cambios.
 
 ## Clasificación de problemas
 
@@ -396,16 +445,19 @@ Si no se detecta ninguno: `### VETO ITEMS DETECTADOS\n- Ninguno`.
 | Líneas por función (máx) | X | <= 30 | OK/ALERTA |
 | Violaciones linter | X | 0 | OK/ALERTA |
 
-### Score por dimensión
+### Score por dimensión (5-axis)
 | Dimensión | Score | Justificación breve |
 |-----------|-------|---------------------|
-| Legibilidad | N/10 | [razón] |
-| Mantenibilidad | N/10 | [razón] |
-| SOLID | N/10 | [razón] |
-| DRY | N/10 | [razón] |
-| Complejidad | N/10 | [razón] |
-| Consistencia | N/10 | [razón] |
-| **PROMEDIO** | **N/10** | |
+| Correctness (Capa 1 — Spec) | N/10 | CUMPLE/PARCIAL/NO CUMPLE → 10/6/0 |
+| Readability | N/10 | [Legibilidad: nombres + comentarios + tamaño] |
+| Architecture | N/10 | [SOLID 40% + DRY 30% + Consistencia 30%] |
+| **PROMEDIO** | **N/10** | (Correctness + Readability + Architecture) / 3 |
+
+### Handoffs externos (no duplicar análisis)
+| Axis | Estado | Ref/Justificación |
+|------|--------|-------------------|
+| Security | EJECUTADO / NO_REQUERIDO / PENDIENTE | [ref reporte revisor-seguridad-swl o "cambio sin superficie de seguridad"] |
+| Performance | EJECUTADO / NO_REQUERIDO / PENDIENTE | [ref reporte rendimiento-swl o "cambio fuera de path crítico"] |
 
 ### Problemas encontrados
 

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.