@saulwade/swl-ses 1.7.4 → 1.9.0

package/habilidades/changelog-generator/scripts/parse-commits.js

@@ -51,7 +51,7 @@ const { execSync } = require('node:child_process');
  *   refactor(hooks/lib): split evolution-tracker
  *   chore(release): bump version
  */
-const RE_CONVENTIONAL = /^(feat|fix|perf|refactor|docs|style|test|ci|build|chore|revert|evolucion)(?:\(([^)]+)\))?(!)?:\s*(.+)$/;
+const RE_CONVENTIONAL = /^(feat|fix|perf|refactor|docs|style|test|ci|build|chore|revert|evolucion|evolve)(?:\(([^)]+)\))?(!)?:\s*(.+)$/;
 
 /** Mapa tipo CC → categoría Keep a Changelog en es-MX. */
 const CATEGORIAS = Object.freeze({
@@ -61,6 +61,7 @@ const CATEGORIAS = Object.freeze({
   refactor:  'Cambios internos',
   revert:    'Reversiones',
   evolucion: 'Evoluciones de skills/agentes',
+  evolve:    'Evoluciones de skills/agentes',
   docs:      'Mantenimiento',
   style:     'Mantenimiento',
   test:      'Mantenimiento',

package/habilidades/checklist-seguridad/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: checklist-seguridad
 description: Checklist de seguridad basado en OWASP Top 10 + seguridad de agentes autónomos (A11). Cubre inyección, autenticación, exposición de datos, control de acceso, configuración insegura, XSS, deserialización, componentes vulnerables, logging y agencia excesiva de IA. Produce reporte con hallazgos y remediaciones.
-version: "1.1.1"
+version: "1.2.0"
 evolved: true
 evolved-from: "1.1.0"
 evolved-at: "2026-05-04"
@@ -297,6 +297,34 @@ grep -rn "\.env\|credentials\|secret" --include="*.md" agentes/ | head -10
 
 ---
 
+## Modo cobertura — STRIDE + score compuesto (auditorías iterativas)
+
+Para auditorías en profundidad (no el checklist de un solo PR), complementar
+el barrido OWASP con el modelo **STRIDE** y medir la auditoría con un **score
+compuesto de cobertura** — convierte "auditamos seguridad" en un número
+verificable y permite usar la auditoría como loop iterativo:
+
+```
+score = (categorías_OWASP_auditadas / 10) × 50
+      + (categorías_STRIDE_auditadas / 6) × 30
+      + min(hallazgos_únicos, 20)
+```
+
+Score perfecto = 100 (OWASP completo + STRIDE completo + 20 hallazgos). Cada
+hallazgo se etiqueta con AMBAS taxonomías (`OWASP: A03, STRIDE: T`). Reportar
+la cobertura cada 5 iteraciones:
+
+```
+OWASP: [A01✓ A02✓ A03✗ ...] 4/10 | STRIDE: [S✓ T✓ R✗ I✓ D✗ E✗] 3/6 | Score: 48
+```
+
+Tabla STRIDE→OWASP, qué buscar por categoría, y rotación de personas red-team
+(Adversario, Supply Chain, Insider, Infra — definidas en
+`habilidades/proceso-debate-adversarial/recursos/personas.md`) en
+[recursos/stride-cobertura.md](recursos/stride-cobertura.md). Registrar las
+iteraciones de la auditoría con `hooks/lib/loop-telemetry.js` (tipo
+`seguridad`, direccion `higher_is_better`, métrica = score compuesto).
+
 ## Gotchas / Errores comunes no obvios
 
 **El grep de búsqueda de secrets hardcodeados devuelve cero resultados pero hay credenciales en archivos de configuración YAML**: el patrón de búsqueda usa `password\s*=` (sintaxis Python), pero los archivos YAML usan `password:` (sin signo igual). Causa: las búsquedas de código están optimizadas para un lenguaje y pierden variantes de otro formato. Fix: expandir el patrón de búsqueda a `password[\s=:]+['\"][^'\"]{4,}` para capturar asignaciones en Python, YAML y JSON simultáneamente. Verificar también `docker-compose.yml`, `.env.example` y archivos de configuración de CI.

package/habilidades/checklist-seguridad/recursos/stride-cobertura.md

@@ -0,0 +1,60 @@
+# STRIDE — modelo de amenazas para el modo cobertura
+
+Complemento del checklist OWASP de `SKILL.md`. STRIDE clasifica por **tipo de
+amenaza** (qué quiere lograr el atacante); OWASP por **tipo de debilidad**
+(qué error del código lo permite). Auditar con ambas taxonomías cierra los
+huecos que cada una deja sola: repudio y DoS casi no aparecen en OWASP Top 10;
+componentes desactualizados (A06) no mapean limpio a STRIDE.
+
+## Las 6 categorías
+
+| Letra | Amenaza | Qué buscar | OWASP relacionadas |
+|-------|---------|-----------|--------------------|
+| **S**poofing | Suplantación de identidad | Auth débil, tokens predecibles, session fixation, falta de MFA | A07 |
+| **T**ampering | Modificación de datos | Input sin validar, falta de checks de integridad, inyección SQL/NoSQL, deserialización insegura | A03, A08 |
+| **R**epudiation | Acciones negables | Audit logs faltantes, transacciones sin firma, logs mutables, cambios de privilegio sin registro | A09 |
+| **I**nformation Disclosure | Fuga de información | Stack traces al cliente, logging verboso con PII, env vars expuestas, mensajes de error que revelan existencia de recursos | A01, A02, A05 |
+| **D**enial of Service | Ataques a disponibilidad | Queries sin cota ni paginación, rate limits faltantes, regex DoS (ReDoS), uploads sin límite de tamaño | A04 |
+| **E**levation of Privilege | Acceso no autorizado | Checks de authz faltantes, IDOR, rutas de escalación admin, confusión autenticación/autorización | A01, A04 |
+
+## Protocolo de auditoría iterativa con cobertura
+
+1. **Reconocimiento (una vez)**: mapear superficie de ataque — manifest de
+   dependencias, `.env.example`, Dockerfile, rutas de API, módulos de auth,
+   schemas de BD, configuración de CI/CD. Producir threat model inicial:
+   qué activos, qué trust boundaries, qué entry points.
+2. **Por iteración**: elegir el vector MENOS cubierto (OWASP sin auditar →
+   STRIDE sin auditar → profundizar en hallazgos existentes). Adoptar la
+   persona red-team que corresponde al vector (rotación: Adversario de
+   Seguridad → Supply Chain → Insider → Infraestructura — definiciones en
+   `habilidades/proceso-debate-adversarial/recursos/personas.md`).
+3. **Validar cada hallazgo**: evidencia archivo:línea + escenario de ataque
+   concreto + reproducción. Sin escenario de ataque no es hallazgo, es
+   especulación (regla `verificar-citas-normativas.md § Familia 2`).
+4. **Registrar**: fila en la corrida de `loop-telemetry` (columnas sugeridas:
+   `iteracion, timestamp, hallazgo, severidad, owasp, stride, archivo_linea`)
+   y recalcular el score compuesto.
+5. **Salida**: OWASP 10/10 + STRIDE 6/6 cubiertos, o max iteraciones (default
+   15), o plateau de hallazgos (3 iteraciones sin hallazgo nuevo).
+
+## Formato de hallazgo (obligatorio, 7 campos)
+
+```markdown
+### [Título de una línea]
+- **Severidad**: Crítico | Alto | Medio | Bajo | Informativo
+- **OWASP**: A01-A10
+- **STRIDE**: S | T | R | I | D | E
+- **Evidencia**: archivo:línea + escenario de ataque (sin especulación teórica)
+- **Reproducción**: pasos para disparar el problema
+- **Remediación**: fix concreto para ESTE código
+```
+
+## Severidad — criterios
+
+| Severidad | Criterio | Ejemplos |
+|-----------|----------|----------|
+| Crítico | Explotable remoto, sin auth, brecha de datos | RCE, SQL injection, bypass de auth |
+| Alto | Requiere algún acceso, impacto severo | XSS almacenado, IDOR, escalación de privilegios |
+| Medio | Impacto limitado o requiere interacción | CSRF, XSS reflejado, divulgación de info |
+| Bajo | Impacto mínimo | Headers faltantes, errores verbosos |
+| Informativo | Recomendación de hardening | Defensa en profundidad |

package/habilidades/css-moderno/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: css-moderno
 description: CSS moderno 2024+. Cubre Container Queries, CSS Layers (@layer), Nesting nativo, Custom Properties avanzadas, funciones min/max/clamp/color-mix, propiedades lógicas (block/inline), View Transitions API, animaciones performantes solo-compositor, dark mode patterns y anti-patrones críticos.
-version: "1.0.0"
+version: "1.1.0"
 herramientasPermitidas: [Read, Grep]
 exclusiones:
   - "No cargar para Tailwind CSS (clases utilitarias, @theme, cva, responsive) — para Tailwind cargar `tailwind-experto`."
@@ -164,3 +164,5 @@ Para ejemplos completos de Container Queries, CSS Layers, Nesting, Custom Proper
 **`container-type: inline-size` en un elemento con `position: absolute/fixed` puede no funcionar como contenedor de queries en algunos navegadores**: el contenedor crea un nuevo stacking context y en ciertos casos la query no se propaga correctamente a hijos con posicionamiento absoluto en Safari <17. Causa: bug de implementación en Safari relacionado con contenedores posicionados. Fix: en elementos con posicionamiento absoluto dentro de container queries, probar en Safari y usar un wrapper div sin posicionamiento como contenedor si hay problemas.
 
 **`clamp()` con `vw` en la función intermedia no escala correctamente en pantallas muy anchas si no se acota con `max()`**: `font-size: clamp(1rem, 2vw, 2rem)` en un monitor de 2560px da `2vw = 51.2px`, que es mayor que el máximo de `2rem = 32px` — el clamp lo atrapa pero el cálculo puede ser confuso al depurar. Causa: el valor de `vw` crece sin límite. Fix: entender que `clamp(min, preferido, max)` garantiza que el resultado siempre está entre min y max — el valor preferido puede ser cualquier expresión, incluso mayor que max, y el clamp simplemente retorna max en ese caso. Verificar los tres valores en los tamaños de viewport objetivo.
+
+**`var(--token)` NO resuelve cuando el valor lo consume JavaScript pintando a `<canvas>`**: las librerías que renderizan a canvas (Chart.js, OpenLayers, three.js/WebGL, o `ctx.fillStyle`/`strokeStyle`/`ctx.font` directos) NO reciben el contexto CSS del documento → el color sale negro o invisible **sin error en consola**. Causa: el canvas es un buffer de píxeles fuera del árbol CSS; la cascada y `getComputedStyle` no aplican al contexto 2D/WebGL — `var()` queda como string literal que el motor de canvas no interpreta. La frontera es: un color es `var(--x)` SOLO si lo consume CSS (`.css`/`.module.scss` o `style={{}}` sobre HTML); si lo consume JS pintando a canvas, debe ser hex/rgb concreto. Fix: pasar hex/rgb literal a esos objetos, con comentario anti-recurrencia (`// canvas: NO resuelve var()`). Si el color debe ser theme-aware, resolverlo primero en JS — `getComputedStyle(document.documentElement).getPropertyValue('--color-x').trim()` — y pasar el valor ya resuelto al canvas, re-leyéndolo al cambiar de tema.

package/habilidades/drift-detection/SKILL.md

@@ -135,7 +135,7 @@ const resultado = ejecutarDriftReflect(
 ```
 
 Cuando `estado_global === 'critico'`, el módulo emite automáticamente un nudge
-a `.planning/evolucion/nudges.jsonl`:
+a `.planning/evolution/nudges.jsonl`:
 
 ```json
 {
@@ -167,7 +167,7 @@ El agente `auto-evolucion-swl` consume estos nudges para proponer mejoras.
 
 - **Timestamps inválidos en eventos JSONL provocan líneas ignoradas silenciosamente**: el módulo es permisivo con los campos pero si ningún campo de timestamp (`timestamp`, `ts`, `inicio`, `created_at`) tiene una fecha ISO válida, el evento se descarta del cálculo. Causa: eventos generados con timestamps de formato local (ej. `"19/04/2026"`) no pasan la validación. Solución: verificar que todos los eventos JSONL del trace tengan al menos un campo de timestamp en formato ISO 8601 — si el baseline aparece como 0, es el primer síntoma de eventos descartados.
 - **Estado `critico` emitido por baseline con muy pocos eventos**: si el baseline de 4 semanas tiene solo 3 eventos y la ventana de 7 días tiene 8, el `driftPct` de tokens se dispara al 166% cuando en realidad el agente está más activo, no degradado. Causa: el módulo no valida que el baseline tenga suficientes eventos para ser estadísticamente válido. Solución: antes de interpretar un estado `critico`, verificar que el baseline tiene al menos 20 eventos — si no, marcar el resultado como `insufficient-data` en lugar de accionar.
-- **Nudge duplicado en `.planning/evolucion/nudges.jsonl` por falta de deduplicación**: el hook se ejecuta dos veces en el mismo `SubagentStop` (por bug de throttle) y emite el mismo nudge dos veces. Causa: el throttle `SWL_DRIFT_THROTTLE_H` no validó correctamente el timestamp del último run. Solución: el archivo `nudges.jsonl` es append-only — antes de emitir un nudge, verificar si el último evento del mismo `agente_o_skill` y `metrica` tiene un timestamp dentro de la ventana de throttle.
+- **Nudge duplicado en `.planning/evolution/nudges.jsonl` por falta de deduplicación**: el hook se ejecuta dos veces en el mismo `SubagentStop` (por bug de throttle) y emite el mismo nudge dos veces. Causa: el throttle `SWL_DRIFT_THROTTLE_H` no validó correctamente el timestamp del último run. Solución: el archivo `nudges.jsonl` es append-only — antes de emitir un nudge, verificar si el último evento del mismo `agente_o_skill` y `metrica` tiene un timestamp dentro de la ventana de throttle.
 - **`atomicWriteJSON` usado para escribir en nudges.jsonl**: escribir el archivo completo en lugar de hacer append corrompe el historial de nudges previos. Causa: confusión entre archivos de estado mutable (usan `atomicWriteJSON`) y archivos de eventos de alta frecuencia (usan `fs.appendFileSync`). Solución: `nudges.jsonl` es un JSONL de alta frecuencia — siempre usar `fs.appendFileSync(ruta, JSON.stringify(nudge) + '\n')`, nunca reescribir el archivo completo.
 
 ## Referencia cruzada
@@ -175,5 +175,5 @@ El agente `auto-evolucion-swl` consume estos nudges para proponer mejoras.
 - Módulo: `scripts/lib/drift-detector.js`
 - Tests: `tests/lib/drift-detector.test.js`
 - Operador Reflect: `hooks/lib/reflect-classifier.js`
-- Ciclo AGP: `.planning/evolucion/nudges.jsonl`
+- Ciclo AGP: `.planning/evolution/nudges.jsonl`
 - Origen (adaptado de): `temp/mission-control-main/src/lib/agent-evals.ts` — MIT

package/habilidades/eval-framework/SKILL.md

@@ -24,7 +24,7 @@ evolvable: true  # default para skill estandar
   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`).
+  agregadas en `.planning/evolution/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

package/habilidades/fastapi-experto/SKILL.md

@@ -5,12 +5,12 @@ description: >
   testing con httpx. Incluye el anti-patrón crítico MissingGreenlet (lazy loading
   en async). Cargar cuando se implementen endpoints FastAPI, schemas Pydantic v2,
   queries SQLAlchemy async, WebSockets, SSE o tests de integración con httpx.
-version: "1.3.0"
+version: "1.3.1"
 evolved: true
-evolved-from: "1.2.0"
-evolved-at: "2026-05-20"
-evolved-by: "aprender"
-evolved-note: "2 gotchas nuevos SIGAF 2026-05-15: setattr con strings inventados en whitelist bypassea persistencia silenciosamente (extiende gotcha getattr); ClassVar[frozenset] como patrón positivo para whitelists de PATCH endpoints"
+evolved-from: "1.3.0"
+evolved-at: "2026-06-04"
+evolved-by: "evolucionar"
+evolved-note: "3 patrones nuevos OIC v1.5 2026-06-04: handler logging defensivo con sesión SQLAlchemy desacoplada (PE-001); tests pytest cuelgan si handler abre engine con pool_pre_ping al startup sin BD + receta conftest (PE-002); tests de endpoint sin BD con dependency_overrides[get_db]=lambda:None + monkeypatch del service (PE-008)"
 herramientasPermitidas: [Read]
 exclusiones:
   - "No cargar para proyectos Django o Flask — los patrones de ORM sync, Class-Based Views y middleware difieren fundamentalmente; cargar `django-experto` o el skill del framework correspondiente."
@@ -267,6 +267,57 @@ Beneficios:
 
 Regla: para cualquier whitelist usada en `setattr` ciego (PATCH endpoints, factory methods, deserializadores manuales), declarar como `ClassVar[frozenset[str]]` de la clase del service. NUNCA como variable local del método. NUNCA como módulo-level constant fuera de la clase (pierde el namespacing).
 
+- **Handler logging que persiste en BD durante manejo de excepciones — SIEMPRE usar sesión SQLAlchemy desacoplada + silenciar fallos** (patrón portable; caso real OIC v1.5 BitacoraErrorHandler 2026-06-04): si un `logging.Handler` custom (audit trail, Sentry-style, métricas async, observabilidad) usa la sesión del request para persistir el evento, durante una excepción HTTP la sesión está en estado roto y `session.add()` falla, perdiendo la excepción original. Patrón correcto:
+```python
+# Engine PROPIO independiente del pool del request (pool=2 suficiente).
+engine = create_engine(settings.DATABASE_URL, pool_pre_ping=True, pool_size=2, max_overflow=2)
+session_factory = sessionmaker(bind=engine, autocommit=False, autoflush=False)
+
+class MiHandler(logging.Handler):
+    def emit(self, record):
+        try:
+            self._emit_unsafe(record)
+        except Exception:  # noqa: BLE001 — silencio defensivo intencional
+            # NUNCA loggear con `logging` desde aquí (riesgo de recursión infinita).
+            pass
+
+    def _emit_unsafe(self, record):
+        sess = session_factory()  # sesión NUEVA, no la del request
+        try:
+            sess.add(entry); sess.commit()
+        finally:
+            sess.close()
+```
+Reglas clave: (a) engine propio; (b) `try/except: pass` agresivo en `emit()`; (c) NUNCA emitir a logger propio; (d) filtrar loggers ruidosos por nombre (`sqlalchemy.*`, `uvicorn.access`, `httpx`, `httpcore`, `asyncio`, `urllib3`); (e) idempotente: verificar si ya está en `root.handlers` antes de registrar. Aplicable a Sentry-style integrations, audit handlers, métricas async, alertas.
+
+- **Tests pytest se cuelgan al importar `app.main` cuando un handler abre engine BD con `pool_pre_ping=True` al startup** (gotcha crítico OIC v1.5 2026-06-04): si un handler de logging custom se instala en `setup_logging()` y construye un engine con `pool_pre_ping=True`, sin PostgreSQL corriendo SQLAlchemy intenta una query de verificación en `socket.connect()` infinito. El test no falla — se cuelga sin output (ni siquiera el header de pytest). Causa: el bloqueo ocurre en la **importación** del módulo `app.main` (que llama `setup_logging()`), no en el test mismo. Síntoma típico: 3+ invocaciones de `pytest` en background sin output, requiere matar `python.exe` manualmente. Solución obligatoria en `backend/tests/conftest.py`:
+```python
+# ANTES de importar app.main
+os.environ.setdefault("ENV", "test")
+os.environ.setdefault("SKIP_DB_HEALTHCHECK", "true")
+# Por CADA handler del proyecto que abre engine al startup:
+os.environ.setdefault("SWL_BITACORA_ERRORES_ENABLED", "false")
+# (sustituir por la env var real del proyecto)
+```
+Regla: cualquier handler con `pool_pre_ping=True` en su engine debe tener un kill-switch env var, y el conftest debe deshabilitarlo. Sin esto, los tests del proyecto serán inviables sin BD real.
+
+- **Tests de endpoint sin BD con `dependency_overrides[get_db]=lambda:None` + monkeypatch del service** (patrón portable validado OIC v1.5 Slice 4 2026-06-04): para tests de endpoint que verifican contrato HTTP (auth, validación de query params, estructura de respuesta, rate-limit, headers de export CSV) sin requerir PostgreSQL. 25 tests en 0.23s.
+```python
+@pytest.fixture
+def client_admin(monkeypatch: pytest.MonkeyPatch) -> TestClient:
+    app.dependency_overrides[requiere_admin] = _fake_admin  # stub user
+    app.dependency_overrides[get_db] = lambda: None  # type: ignore[return-value]
+    # Mock del service: el endpoint llama service.metodo(db, ...) pero `db` es None;
+    # el service no debe ejecutarse — se reemplaza con fake que devuelve schema válido.
+    from app.services import mi_service
+    monkeypatch.setattr(mi_service, "listar_paginado",
+        lambda db, filtros, page, per_page: SchemaPage(items=[], total=0, ...))
+    with TestClient(app) as c:
+        yield c
+    app.dependency_overrides.clear()
+```
+Aplicabilidad: cualquier endpoint que dependa de `get_db` + service mockeable. NO requiere BD real ni fixtures de datos. Tests de integración con BD viven aparte (`@pytest.mark.integration`).
+
 ## Referencias especializadas
 
 | Tema | Archivo |

package/habilidades/guardrail-semantico/SKILL.md

@@ -38,7 +38,7 @@ si se justifica el costo del modelo seleccionado.
 - Al diseñar hooks `PreToolUse` que evalúan prompts antes de invocar un subagente.
 - Al implementar degradación de modelo basada en complejidad de tarea.
 - Al revisar si `guardrail-modelo.js` necesita nuevos criterios de tripwire.
-- Al analizar logs de `.planning/evolucion/guardrail-observaciones.jsonl`.
+- Al analizar logs de `.planning/evolution/guardrail-observaciones.jsonl`.
 
 ---
 
@@ -199,7 +199,7 @@ Pasar de modo `observational` a `blocking` sin revisar las observaciones acumula
 es una fuente garantizada de falsos positivos. El ciclo correcto:
 
 1. Deploy en modo `observational` (exit 0 siempre).
-2. Revisar `.planning/evolucion/guardrail-observaciones.jsonl` tras ≥50 activaciones.
+2. Revisar `.planning/evolution/guardrail-observaciones.jsonl` tras ≥50 activaciones.
 3. Calcular tasa de falsos positivos. Si < 5%, considerar `run_in_parallel`.
 4. Solo con tasa < 2% y aprobación manual, activar `blocking`.
 
@@ -240,14 +240,14 @@ if (tripwire) {
   process.stderr.write(
     `[guardrail-modelo] El agente '${agenteNombre}' podría ejecutarse con 'haiku' ` +
     `(menos costoso). Razón: prompt corto sin keywords críticas (${prompt.length} chars). ` +
-    `Ver .planning/evolucion/guardrail-observaciones.jsonl\n`
+    `Ver .planning/evolution/guardrail-observaciones.jsonl\n`
   );
 }
 // exit 0 siempre — modo observacional
 process.exit(0);
 ```
 
-**Evento JSONL resultante** en `.planning/evolucion/guardrail-observaciones.jsonl`:
+**Evento JSONL resultante** en `.planning/evolution/guardrail-observaciones.jsonl`:
 
 ```jsonl
 {"timestamp":"2026-04-19T14:23:01.000Z","agente":"notificador-swl","modelo_actual":"sonnet","modelo_sugerido":"haiku","razon_tripwire":"prompt-corto-sin-keywords-criticas","prompt_length":87}

package/habilidades/patrones-python/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: patrones-python
 description: Idiomas pythonicos, PEP 8, type hints modernos, dataclasses, async/await, context managers, decorators y generators. Patrones de código limpio en Python.
-version: "1.3.1"
+version: "1.4.2"
 evolved: true
-evolved-from: "1.3.0"
-evolved-at: "2026-05-04"
-evolved-by: "aprender"
-evolved-note: "+1 gotcha: assert se elimina con PYTHONOPTIMIZE=1 — usar if/raise para invariantes (sync desde global tras sesión SIGM Fase 5b)"
+evolved-from: "1.4.1"
+evolved-at: "2026-06-05"
+evolved-by: "evolucionar"
+evolved-note: "+gotcha PEP 758: except A,B: sin paréntesis es válido en Python >=3.14, no SyntaxError; cubre efecto colateral de ruff format (target py314) reformateando archivo completo. Origen: falso positivo reproducible en sistema-verificacion-oic (requires-python >=3.14)"
 herramientasPermitidas: [Read, Glob, Grep]
 exclusiones:
   - "No cargar para patrones de un framework específico (FastAPI, Django, Celery) — los idiomas generales de este skill aplican, pero los patrones de framework tienen restricciones adicionales; cargar el skill del framework correspondiente."
@@ -205,6 +205,9 @@ ver [recursos/referencia-completa.md](recursos/referencia-completa.md).
 - **`__slots__` en clase Python produce `TypeError: multiple bases have instance lay-out conflict`** al heredar de otra clase con `__slots__`: las subclases con `__slots__` requieren que todos los ancestros también tengan `__slots__`, o que el ancestro directo sea `object`. Causa: si `ClaseBase` no tiene `__slots__`, tiene un `__dict__` implícito; si `ClaseHija` tiene `__slots__`, hay conflicto de layout de memoria. Solución: o agregar `__slots__ = ()` vacío a la clase base, o eliminar `__slots__` de la subclase — no mezclar clases con y sin `__slots__` en la misma jerarquía.
 - **`property` setter que modifica un campo privado no refleja el cambio en `__repr__` generado por dataclass**: el `@property` en un dataclass crea un campo de clase que conflictúa con el campo de instancia del dataclass. Causa: `@dataclass` genera `__repr__` basado en los campos declarados en `__init__` — si el setter modifica un atributo con nombre diferente (ej: `_valor`), `__repr__` muestra el campo original sin la modificación. Solución: usar `field(init=False, repr=False)` para el campo interno y exponer solo la `property` en la interfaz pública.
 - **`assert` no es guard de invariantes en producción con `PYTHONOPTIMIZE=1` o `python -O`**: el bytecode optimizado **elimina** todos los `assert` del módulo, por lo que `assert x is not None; return x` puede retornar `None` violando el contrato `-> dict` en producción aunque pase tests en desarrollo. El test runner por defecto NO usa `-O`, por lo que el bug es invisible hasta que alguien despliega con `PYTHONOPTIMIZE=1` (configuración común para reducir memoria en imágenes Docker production). Causa: `assert` está documentado en Python como herramienta de **debugging**, no de validación. Solución: para invariantes que DEBEN cumplirse en producción, usar guard explícito con raise: `if x is None: raise HTTPException(500, "Invariante violado")` o `if x is None: raise RuntimeError(...)`. Reservar `assert` solo para tests, scripts, o pre-condiciones triviales en código de desarrollo. Regla rápida: si el assert protege un caso que activa una respuesta del usuario o un side-effect, NO es assert — es validación y debe ser `if/raise`.
+- **Pasar `None` explícito a un parámetro NO activa su valor por defecto en el callee**: si una función declara `def listar(activa: bool = True)` y el caller hace `listar(activa=valor)` donde `valor` puede ser `None` (típico con parámetros opcionales que viajan entre capas: `activa: bool | None = None`), el callee recibe `None`, NO `True`. Python aplica el default SOLO cuando el argumento se **omite literalmente** en la llamada, no cuando recibe `None` explícito. Causa: el binding del parámetro usa el valor pasado, sea cual sea — el default es fallback de *ausencia*, no de *nulidad*. El bug es silencioso: pasa los tests donde el caller omite el parámetro y falla en producción cuando el cliente omite el valor y una capa intermedia lo traduce a `None` antes de propagarlo. Caso real: un endpoint que documentaba "omitir devuelve solo activos" retornaba inactivos porque el router pasaba `activa=None` al service cuyo default era `True`. Solución: normalizar en la frontera — en el caller (`listar(activa=True if valor is None else valor)`) o tratando `None` como sentinel en el callee (`if activa is None: activa = True`). Regla: cuando un valor opcional cruza de una capa a otra y el callee tiene un default distinto de `None`, convertir `None → default` explícitamente en el punto de cruce.
+- **`getattr(obj, "attr", default)` tampoco aplica `default` si el atributo existe con valor `None`**: misma raíz que el gotcha anterior, otra manifestación. `getattr` usa `default` SOLO cuando el atributo **no existe**; si existe con valor `None` (caso típico: campos opcionales de Pydantic/SQLAlchemy inicializados a `None`), devuelve `None`, no `default`. Así `getattr(modelo, "campo_opcional", "X")` retorna `None` cuando `campo_opcional is None`, no `"X"`. Solución sin ambigüedad: `raw = getattr(modelo, "campo_opcional", None); valor = raw if raw is not None else "X"` (el atajo `getattr(...) or "X"` solo sirve si `""` y `0` son aceptables como falsy). Regla unificada para ambos casos: en Python el `default` —de parámetro o de `getattr`— es fallback de **ausencia**, nunca de **nulidad**; si `None` es un valor posible, normalízalo en la frontera.
+- **`except A, B:` sin paréntesis es sintaxis válida en Python ≥3.14 (PEP 758), NO un SyntaxError**: desde 3.14 los paréntesis en `except`/`except*` con múltiples tipos son opcionales (`except ValueError, TypeError:` ≡ `except (ValueError, TypeError):`). Bajo intérpretes <3.14 esa forma SÍ es SyntaxError, lo que confunde a herramientas y revisores que juzgan la sintaxis contra su conocimiento general del lenguaje en vez de contra la versión objetivo del proyecto (`requires-python`/`tool.ruff.target-version` en `pyproject.toml`). Causa: la validez de la sintaxis depende de la versión, no es absoluta. Efecto colateral a vigilar: `ruff format` con `target-version = "py314"` **quita** los paréntesis redundantes y, además, reformatea el archivo COMPLETO — puede tocar `except` ajenos a tu cambio (churn no intencional); `ruff check` (lo único que suele correr el CI) conserva la forma que encuentre. Solución: antes de marcar cualquier `except A, B:` como error, leer la versión objetivo del proyecto y verificar con evidencia ejecutable (`python -c "import <módulo>"` + `ruff check`). Si se prefieren los paréntesis por portabilidad/Pyright, restaurarlos a mano y NO correr `ruff format` sobre esas líneas. Caso real (2026-06-05): un proyecto con `requires-python >=3.14` recibió un falso positivo de SyntaxError CRÍTICO por esta forma; refutado con import + ruff + CI verde.
 
 ---
 

package/habilidades/proceso-ddia-streaming/SKILL.md

@@ -22,7 +22,7 @@ streams locales. Los patrones del Cap 11 aplican directamente.
 ## Cuándo cargar
 
 - Crear un hook que persiste eventos en JSONL (telemetría, audit, evolución).
-- Diseñar un consumidor de `.planning/evolucion/*.jsonl`,
+- Diseñar un consumidor de `.planning/evolution/*.jsonl`,
   `.planning/audit.jsonl`, `.planning/comms/nudges.jsonl`.
 - Diagnosticar duplicación de eventos en JSONL.
 - Decidir si un hook debe ser idempotente o si basta con append.
@@ -80,9 +80,9 @@ fuente).
 
 | Archivo | Productor | Consumidores | ¿Es event source? |
 |---|---|---|---|
-| `.planning/evolucion/evoluciones.jsonl` | `/swl:evolucionar`, hook `evolucion-detector` | `/swl:evolucion-estado`, dashboard | Sí |
-| `.planning/evolucion/nudges.jsonl` | hooks varios | `/swl:salud`, `red-team-swl` | Sí |
-| `.planning/evolucion/agentes.jsonl` | hook `telemetria-agentes` | `/swl:metricas` | Sí |
+| `.planning/evolution/evoluciones.jsonl` | `/swl:evolucionar`, hook `evolucion-detector` | `/swl:evolucion-estado`, dashboard | Sí |
+| `.planning/evolution/nudges.jsonl` | hooks varios | `/swl:salud`, `red-team-swl` | Sí |
+| `.planning/evolution/agentes.jsonl` | hook `telemetria-agentes` | `/swl:metricas` | Sí |
 | `.planning/audit.jsonl` | hook `audit-trail` | auditorías, post-mortems | Sí (con Merkle) |
 | `.planning/comms/*.jsonl` | `notificador-swl` | inbox, gateway | Sí |
 

package/habilidades/proceso-debate-adversarial/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: proceso-debate-adversarial
+description: >
+  Protocolo de debate adversarial con jueces ciegos para decisiones técnicas
+  subjetivas: dos autores en frío generan candidatos, un crítico forzosamente
+  adversarial los ataca, un sintetizador produce un híbrido y un panel de jueces
+  ciegos con etiquetas aleatorizadas elige al ganador hasta convergencia.
+  Cargar cuando una decisión de arquitectura, diseño o estrategia no tiene
+  métrica objetiva y el riesgo de sycophancy (auto-aprobarse) es alto; también
+  cuando arquitecto-swl evalúa alternativas o /swl:predecir necesita el
+  protocolo de personas en frío.
+version: "1.0.0"
+herramientasPermitidas: [Read, Agent, Skill]
+exclusiones:
+  - "No cargar para decisiones con métrica objetiva verificable — ahí aplica el loop de autoresearch (Verify numérico), no un debate."
+  - "No cargar para revisión de código post-implementación — eso es revisor-codigo-swl / nemesis-auditor-swl."
+  - "No cargar para decisiones triviales o de preferencia personal sin impacto técnico — el costo de 5+ invocaciones de agente no se justifica."
+evolvable: true
+---
+# Debate Adversarial con Jueces Ciegos
+
+Protocolo para decidir entre alternativas técnicas **sin métrica objetiva**
+eliminando los dos sesgos que arruinan las auto-evaluaciones de un LLM:
+**sycophancy** (el agente aprueba lo que él mismo generó) y **position bias**
+(el juez prefiere la opción presentada primero). Patrón adoptado del análisis
+de autoresearch v2.1 (`reason-judge-protocol`), adaptado al ecosistema SWL.
+
+**Principio**: el que genera nunca juzga, el que juzga nunca sabe quién generó.
+
+## Cuándo cargar este skill
+
+- Decisión de arquitectura con 2+ alternativas viables sin benchmark objetivo
+  (ej: event sourcing vs CRUD+audit, monolito modular vs microservicios).
+- `arquitecto-swl` necesita justificar un ADR con alternativas evaluadas de
+  forma no sesgada.
+- `/swl:predecir` requiere el protocolo de aislamiento de personas.
+- Decisión de producto/estrategia donde el usuario pide "dame la mejor opción"
+  y una sola pasada produciría la primera idea plausible, no la mejor.
+
+## Los 5 roles — aislamiento obligatorio (COLD START)
+
+| Rol | Recibe | Produce | Regla dura |
+|-----|--------|---------|------------|
+| **Autor-A** | tarea | candidato A | No ve crítica ni candidato B |
+| **Crítico** | tarea + candidato A | ≥3 debilidades con evidencia + qué haría un candidato superior | NUNCA elogia — rol puramente adversarial |
+| **Autor-B** | tarea + candidato A + crítica | candidato B que resuelve la crítica preservando fortalezas de A | No ve al sintetizador |
+| **Sintetizador** | tarea + A + B | candidato híbrido AB | Fusiona lo mejor de ambos, no promedia |
+| **Panel de jueces** (3 default) | tarea + 3 candidatos con **etiquetas aleatorizadas** (X, Y, Z) | ranking 1°/2°/3° + justificación de un párrafo c/u | "Todos están bien" NO es veredicto válido |
+
+**COLD START**: cada rol se ejecuta como invocación independiente del Agent
+tool **sin contexto compartido de sesión** — recibe SOLO los insumos de su fila.
+Pasar el historial completo a un juez invalida el protocolo (sabría quién
+escribió qué).
+
+**Aleatorización de etiquetas**: antes de invocar a los jueces, mapear
+A/B/AB → X/Y/Z con orden aleatorio distinto por juez. Previene position bias.
+
+## El loop de convergencia
+
+```
+Ronda N:
+  1. Autor-A genera candidato (ronda 1) o presenta al incumbente (ronda N>1)
+  2. Crítico ataca → ≥3 debilidades con evidencia
+  3. Autor-B genera candidato alternativo
+  4. Sintetizador produce híbrido AB
+  5. Panel ciego vota → ganador por mayoría (empate → gana el híbrido)
+  6. ¿Ganador == incumbente? → convergencia++ ; si no → convergencia = 1,
+     el ganador se vuelve incumbente
+```
+
+| Condición | Acción |
+|-----------|--------|
+| Mismo incumbente gana 3 rondas consecutivas | **CONVERGIDO** — terminar |
+| Ronda ≥ max (default 8) | **ACOTADO** — reportar mejor candidato actual |
+| Incumbente cambió >5 veces en las últimas 8 rondas | **OSCILACIÓN** — detener y reportar: la tarea está mal planteada o las alternativas son equivalentes |
+
+Registrar cada ronda con `hooks/lib/loop-telemetry.js` (tipo `debate`,
+columnas `ronda, timestamp, etiqueta_ganadora, veredicto, convergencia,
+descripcion`) para que la trayectoria sea auditable y `/swl:metricas` la lea.
+
+## Anti-herd check — obligatorio
+
+Si TODOS los jueces coinciden en la primera ronda, el sintetizador DEBE
+producir al menos un contraargumento antes de aceptar el consenso. Unanimidad
+inmediata en un debate de alternativas reales es señal de herd bias, no de
+calidad — las alternativas genuinas siempre tienen tradeoffs defendibles.
+
+## Criterios de juez por dominio
+
+| Dominio | Criterios de evaluación |
+|---------|------------------------|
+| Arquitectura de software | escalabilidad, mantenibilidad, rendimiento, seguridad, simplicidad |
+| Estrategia de producto | encaje de mercado, factibilidad, diferenciación, riesgo, tiempos |
+| Decisión de negocio | ROI, riesgo, alineación, recursos requeridos, reversibilidad |
+| Enfoque de seguridad | cobertura, tasa de falsos positivos, practicidad, cumplimiento |
+| Hipótesis de investigación | testabilidad, novedad, soporte de evidencia, poder explicativo |
+
+El juez evalúa CADA candidato contra TODOS los criterios del dominio y
+produce ranking con justificación — nunca un score suelto sin comparación.
+
+## Personas para análisis predictivo
+
+Cuando el objetivo es **predecir problemas de un cambio propuesto** (no
+elegir entre alternativas), usar el modo personas: 5 expertos analizan EN FRÍO
+el mismo cambio y un sintetizador deduplica y rankea. Definiciones completas,
+preguntas guía y red flags por persona en
+[recursos/personas.md](recursos/personas.md). Set default: Arquitecto de
+Software, Analista de Seguridad, Ingeniero de Rendimiento, Ingeniero de
+Confiabilidad, Abogado del Diablo. Set adversarial (`--adversarial`): El
+Rompedor, El Tramposo, El Escalador, El Novato, El Insider Malicioso.
+
+Ranking de hallazgos del sintetizador:
+`severidad × confianza promedio × número de personas que coinciden`.
+
+## Integración con el ecosistema SWL
+
+| Componente | Uso del protocolo |
+|-----------|-------------------|
+| `arquitecto-swl` | Debate para la sección "Alternativas consideradas" de un ADR |
+| `/swl:predecir` | Modo personas pre-implementación |
+| `/swl:nemesis` | El evaluator puede pedir un debate cuando dos remediaciones compiten |
+| `hooks/lib/loop-telemetry.js` | Registro de rondas + handoff para encadenar |
+| `/swl:metricas` | Lectura de trayectorias de debates en `.planning/loops/` |
+
+## Cuándo NO cargar
+
+- La decisión tiene métrica objetiva (latencia, cobertura, bundle size) — usar
+  el loop autoresearch con Verify numérico; un debate es más caro y menos
+  preciso que medir.
+- El usuario ya tomó la decisión y está documentada en ADR/vault — aplicar
+  `consultar-vault-primero`, no reabrir con un debate.
+- Hay restricción dura que elimina las alternativas (compliance, presupuesto,
+  stack fijo) — verificar restricciones ANTES de armar el debate.
+
+## Gotchas / Errores comunes no obvios
+
+- **Jueces con contexto contaminado**: invocar a los jueces en la misma
+  conversación donde se generaron los candidatos les revela la autoría por el
+  historial. Causa: usar el contexto principal en vez del Agent tool con
+  prompt acotado. Solución: cada juez es una invocación Agent independiente
+  cuyo prompt contiene SOLO tarea + candidatos etiquetados.
+- **Crítico que "equilibra"**: el crítico señala 3 debilidades pero cierra con
+  "en general es un buen enfoque" — eso re-introduce sycophancy y debilita al
+  Autor-B. Solución: el prompt del crítico prohíbe explícitamente elogios y
+  exige proponer qué haría un candidato superior.
+- **Sintetizador que promedia en vez de fusionar**: produce un candidato
+  "tibio" que toma la mitad de cada uno y pierde la coherencia interna de
+  ambos. Solución: el híbrido debe tener una tesis propia — tomar la
+  arquitectura dominante de uno e injertar mecanismos puntuales del otro.
+- **Convergencia falsa por candidatos idénticos**: si Autor-B produce
+  esencialmente el mismo candidato que A, el panel "converge" en ronda 2 sin
+  exploración real. Solución: el prompt de Autor-B exige divergencia
+  estructural, no cosmética; si la crítica fue débil, regenerar la crítica.
+
+## Anti-patrones
+
+- **Debate de 1 ronda presentado como consenso** — sin convergencia ×3 no hay
+  veredicto, hay una primera impresión cara.
+- **Saltarse la aleatorización de etiquetas** "porque los jueces son
+  imparciales" — el position bias es estadístico, no intencional.
+- **Usar el debate para decisiones ya cerradas** — teatro de proceso que
+  quema tokens para justificar lo decidido.
+- **Panel de 1 juez** — un juez único reintroduce el sesgo individual que el
+  panel existe para diluir; mínimo 3, número impar.

package/habilidades/proceso-debate-adversarial/recursos/personas.md

@@ -0,0 +1,105 @@
+# Personas para análisis predictivo y debate adversarial
+
+Definiciones operativas de las personas que consume `proceso-debate-adversarial`
+(modo personas) y `/swl:predecir`. Cada persona se invoca EN FRÍO (COLD START):
+recibe la descripción del cambio + conocimiento del codebase + sus criterios —
+nunca el análisis de otra persona.
+
+Formato de hallazgo obligatorio por persona:
+
+```markdown
+| # | Hallazgo | Severidad | Confianza (0-100%) | archivo:línea | Recomendación |
+```
+
+Presupuesto: `max_hallazgos_por_persona = presupuesto_total / num_personas`
+(default presupuesto 40 → 8 por persona). Obliga a priorizar, no a enumerar.
+
+---
+
+## Set default (análisis predictivo estándar)
+
+### 1. Arquitecto de Software
+- **Enfoque**: diseño sistémico, fronteras de componentes, flujo de datos, escalabilidad.
+- **Preguntas guía**: ¿Escala? ¿Los límites entre módulos son limpios? ¿El acoplamiento está minimizado? ¿Sobrevive un crecimiento 10x?
+- **Evidencia exigida**: archivo:línea, grafo de dependencias, métricas de acoplamiento.
+- **Red flags**: god classes, dependencias circulares, abstracciones con fugas, estado mutable compartido.
+
+### 2. Analista de Seguridad
+- **Enfoque**: superficies de ataque, autenticación/autorización, protección de datos, vectores de inyección.
+- **Preguntas guía**: ¿Es explotable? ¿Los trust boundaries se aplican? ¿El input se sanitiza? ¿Los secretos están protegidos?
+- **Evidencia exigida**: archivo:línea + escenario de ataque concreto (no especulación teórica).
+- **Red flags**: SQL crudo, authz faltante, secretos hardcodeados, input sin sanitizar.
+
+### 3. Ingeniero de Rendimiento
+- **Enfoque**: latencia, throughput, uso de recursos, complejidad algorítmica.
+- **Preguntas guía**: ¿Es suficientemente rápido? ¿Cuál es el peor caso? ¿Dónde están los cuellos de botella? ¿El caching es efectivo?
+- **Evidencia exigida**: archivo:línea, análisis de complejidad, estimaciones de recursos.
+- **Red flags**: queries N+1, loops sin cota, índices faltantes, I/O síncrono en hot paths.
+
+### 4. Ingeniero de Confiabilidad
+- **Enfoque**: manejo de errores, modos de falla, observabilidad, recuperación.
+- **Preguntas guía**: ¿Qué pasa cuando falla? ¿Podemos detectarlo? ¿Hay camino de recuperación? ¿Es observable?
+- **Evidencia exigida**: archivo:línea, escenarios de falla, rutas de recuperación.
+- **Red flags**: errores tragados, retries faltantes, sin circuit breakers, fallas silenciosas.
+
+### 5. Abogado del Diablo
+- **Enfoque**: asunciones, casos límite, complejidad oculta, mantenibilidad.
+- **Preguntas guía**: ¿Qué asunciones son falsas? ¿Qué rompe esto? ¿Está sobre-ingenierizado?
+- **Evidencia exigida**: contraejemplos concretos, escenarios de caso límite.
+- **Red flags**: diseño solo-happy-path, asunciones sin probar, complejidad sin justificación.
+
+---
+
+## Set adversarial (`--adversarial`)
+
+Reemplaza al set default cuando el objetivo es estresar el cambio como atacante,
+no como revisor.
+
+### 1. El Rompedor
+Intenta crashear o corromper el sistema. Busca: estados imposibles, inputs
+malformados, condiciones de carrera, límites de recursos.
+
+### 2. El Tramposo
+Busca formas de saltarse reglas y abusar de features. Busca: validaciones solo
+en frontend, límites evadibles, flujos alternos sin guards.
+
+### 3. El Escalador
+Imagina carga 1000x y encuentra qué se rompe primero. Busca: queries sin
+paginación, locks globales, colas sin backpressure, costos lineales ocultos.
+
+### 4. El Novato
+Usa mal cada API esperando que funcione. Busca: defaults peligrosos, errores
+crípticos, documentación que asume contexto, footguns de la interfaz.
+
+### 5. El Insider Malicioso
+Tiene credenciales válidas y quiere exfiltrar. Busca: permisos excesivos,
+auditoría faltante, datos sensibles accesibles lateralmente.
+
+---
+
+## Set red-team de seguridad (para `checklist-seguridad` modo cobertura)
+
+Rotación de mentalidades para auditoría STRIDE/OWASP iterativa:
+
+| Persona | Foco | Mentalidad |
+|---------|------|-----------|
+| Adversario de Seguridad | auth, crypto, inyección | atacante externo con browser + proxy de intercepción |
+| Atacante de Supply Chain | dependencias, CI/CD, build pipeline | comprometer vía código de terceros |
+| Amenaza Interna | acceso a datos, abuso de privilegios, exfiltración | usuario autenticado con intención maliciosa |
+| Atacante de Infraestructura | red, configuración cloud, contenedores | apuntar a misconfigurations de infra |
+
+---
+
+## Protocolo de síntesis (tras el análisis individual)
+
+1. **Deduplicar**: mismo archivo:línea + mismo problema → fusionar, conservar la severidad más alta.
+2. **Resolver conflictos**: si dos personas discrepan → registrar el disenso, no silenciarlo.
+3. **Anti-herd check**: si TODAS las personas coinciden → el sintetizador DEBE producir ≥1 contraargumento.
+4. **Rankear**: `severidad × confianza promedio × número de personas que coinciden`.
+
+Output del sintetizador:
+
+```markdown
+### Consenso — [N hallazgos tras dedup]
+| # | Hallazgo | Severidad | Acuerdo | Personas origen | Acción |
+```