@saulwade/swl-ses 1.0.1 → 1.1.2

package/agentes/revisor-typescript-swl.md

@@ -5,15 +5,15 @@ description: >
   generics, utility types, module patterns y testing. Detecta uso de any, type assertions
   inseguras, tipos duplicados y generics innecesarios. Invocar para revisión de
   código TypeScript puro, librerías, o backends Node.js.
-tools: Read, Grep, Glob, Bash
+tools: [Read, Grep, Glob, Bash]
 model: claude-sonnet-4-6
 modeloAlterno: claude-haiku-4-5-20251001
 ventanaContexto: 200k
 color: blue
 version: 1.0.0
 nivelRiesgo: BAJO
-skillsInvocables: typescript-avanzado, node-experto, checklist-calidad, tdd-workflow
-skillsRestringidos: ninguno
+skillsInvocables: [typescript-avanzado, node-experto, checklist-calidad, tdd-workflow]
+skillsRestringidos: []
 permisosRed: false
 permisosEscritura: true
 permisosComandos: true
@@ -22,6 +22,8 @@ toolBudget:
   standard: 20
   complex: 35
 evolvable: true  # nivelRiesgo=BAJO
+fase: verify
+dominio: quality
 exclusiones:
   - "No invocar para implementar código TypeScript — este agente solo revisa; la implementación corresponde a frontend-*-swl o backend-node-swl."
   - "No invocar para revisar lenguajes distintos a TypeScript/JavaScript — usar el revisor especializado correspondiente."

package/agentes/sre-swl.md

@@ -7,7 +7,7 @@ description: >
   redacte un post-mortem, se planifique chaos testing, o se necesite
   cuantificar la confiabilidad de un sistema. Complementa a observabilidad-swl
   (que implementa métricas) con el framework de confiabilidad.
-tools: Read, Write, Edit, Bash, Grep, Glob, Skill
+tools: [Read, Write, Edit, Bash, Grep, Glob, Skill]
 model: claude-opus-4-7
 modeloAlterno: claude-sonnet-4-6
 ventanaContexto: 200k
@@ -15,8 +15,8 @@ permissionMode: acceptEdits
 color: red
 version: 1.0.0
 nivelRiesgo: ALTO
-skillsInvocables: sre-patrones, performance-baseline, monitoring-alertas, checklist-seguridad
-skillsRestringidos: frontend-css-swl, mobile-flutter
+skillsInvocables: [sre-patrones, performance-baseline, monitoring-alertas, checklist-seguridad]
+skillsRestringidos: [frontend-css-swl, mobile-flutter]
 permisosRed: false
 permisosEscritura: true
 permisosComandos: true
@@ -25,6 +25,8 @@ toolBudget:
   standard: 30
   complex: 60
 evolvable: false  # nivelRiesgo=ALTO
+fase: release
+dominio: infra
 exclusiones:
   - "No invocar para implementar features de aplicación — este agente trabaja en confiabilidad y operaciones, no en lógica de negocio."
   - "No invocar para configurar pipelines CI/CD — ese trabajo corresponde a devops-ci-swl."

package/agentes/tdd-qa-swl.md

@@ -6,15 +6,15 @@ description: >
   y gaps de cobertura. Objetivo: >80% líneas, >70% branches. Invocar antes de
   implementar (TDD) o después de implementar (auditoría de cobertura). NUNCA
   modifica código de producción — solo archivos de test y fixtures.
-tools: Read, Write, Edit, Bash, Grep, Glob
+tools: [Read, Write, Edit, Bash, Grep, Glob]
 model: claude-sonnet-4-6
 modeloAlterno: claude-haiku-4-5-20251001
 ventanaContexto: 200k
 color: purple
 version: 1.0.0
 nivelRiesgo: BAJO
-skillsInvocables: tdd-workflow, testing-python, checklist-calidad, manejo-errores, webapp-testing, php-testing, nextjs-testing
-skillsRestringidos: ninguno
+skillsInvocables: [tdd-workflow, testing-python, checklist-calidad, manejo-errores, webapp-testing, php-testing, nextjs-testing]
+skillsRestringidos: []
 permisosRed: false
 permisosEscritura: true
 permisosComandos: true
@@ -23,6 +23,8 @@ toolBudget:
   standard: 30
   complex: 50
 evolvable: true  # nivelRiesgo=BAJO
+fase: verify
+dominio: quality
 exclusiones:
   - "No invocar para testing E2E de aplicaciones móviles — ese trabajo corresponde a mobile-testing-swl."
   - "No invocar para testing de seguridad o penetration testing — ese trabajo corresponde a revisor-seguridad-swl o red-team-swl."

package/agentes/ux-disenador-swl.md

@@ -9,7 +9,7 @@ description: >
   disenador-ui-swl (capa visual y tokens). NO invocar para implementacion de
   codigo — produce specs, no codigo. Para implementar usar frontend-*-swl con
   la UI-SPEC.md producida.
-tools: Read, Write, Grep, Glob, WebSearch
+tools: [Read, Write, Grep, Glob, WebSearch]
 model: claude-sonnet-4-6
 modeloAlterno: claude-haiku-4-5-20251001
 ventanaContexto: 200k
@@ -17,18 +17,14 @@ permissionMode: plan
 color: pink
 version: 1.0.0
 nivelRiesgo: BAJO
-skillsInvocables: ux-diseno, wireframes-flujos, design-tokens, accesibilidad-a11y, diseno-responsivo
-skillsRestringidos:
-  - fastapi-python
-  - django-expert
-  - postgresql-table-design
-  - python-patterns
-  - angular-component
-  - angular-forms
+skillsInvocables: [ux-diseno, wireframes-flujos, design-tokens, accesibilidad-a11y, diseno-responsivo]
+skillsRestringidos: [fastapi-python, django-expert, postgresql-table-design, python-patterns, angular-component, angular-forms]
 permisosRed: true
 permisosEscritura: true
 permisosComandos: false
 evolvable: true  # nivelRiesgo=BAJO
+fase: plan
+dominio: ux
 exclusiones:
   - "No invocar para implementar código de interfaz — este agente produce UI-SPEC.md, no código; usar frontend-react-swl, frontend-angular-swl o frontend-swl para la implementación."
   - "No invocar cuando el pipeline tiene roles separados: preferir investigador-ux-swl para research y disenador-ui-swl para especificaciones visuales puras."

package/comandos/swl/evaluar-skill.md

@@ -356,6 +356,24 @@ Asignar badge:
 < 60  → Sin badge — no hacer merge hasta corregir
 ```
 
+### Gate de promoción para auto-evolucion-swl (G8)
+
+Este comando es el **gate obligatorio** del flujo de promoción de skills
+auto-generados desde `_userland/plugins/` a `habilidades/`. El agente
+`auto-evolucion-swl` invoca este comando antes de mover un skill al core
+(ver `agentes/auto-evolucion-swl.md` sección "Gate G8").
+
+Umbral de promoción:
+
+| Badge | Acción de auto-evolucion |
+|-------|-------------------------|
+| Platino, Oro, Plata | Promover a `habilidades/`, registrar en manifiestos |
+| Bronce | NO promover, devolver a `_userland/` con feedback |
+| Sin badge | NO promover, registrar rechazo en `.planning/evolucion/promociones-rechazadas.jsonl` |
+
+Si un skill es rechazado ≥3 veces consecutivas, el agente escala al usuario
+con análisis de qué dimensiones bajan el score. Origen: ADR 0013 sección 3C.
+
 ## Paso 4 — Emitir reporte
 
 Generar el siguiente reporte directamente en la conversación:

package/comandos/swl/evolucion-estado.md

@@ -38,6 +38,30 @@ Si el archivo no existe: ejecutar el regenerado del Paso 0. Si sigue sin
 existir: reportar "el ciclo de evolución no ha corrido aún; ejecuta cualquier
 tarea para poblar métricas iniciales".
 
+## Paso 1.5 — Cargar contexto del kernel (gobernanza)
+
+Para el bloque **KERNEL** del dashboard, recolectar:
+
+```bash
+# 1. Conteo de agentes evolvable=false vs total
+TOTAL=$(ls agentes/*.md | grep -v "^agentes/_" | wc -l)
+EVOL_FALSE=$(grep -l '^evolvable: false' agentes/*.md | wc -l)
+
+# 2. Último ADR del repo madre — el más reciente por fecha en frontmatter
+ULTIMO_ADR=$(ls .planning/adrs/[0-9]*.md | sort -r | head -1)
+TITULO=$(head -1 "$ULTIMO_ADR" | sed 's/^# //')
+FECHA=$(grep -m1 '^\*\*Fecha\*\*:' "$ULTIMO_ADR" | sed 's/.*\*\*Fecha\*\*:\s*//')
+
+echo "ADR_KERNEL_LINEA=\"$TITULO — $FECHA\""
+echo "RATIO=\"$EVOL_FALSE/$TOTAL\""
+```
+
+Estos valores alimentan la sección KERNEL del template.
+
+Si `.planning/evolucion/politica-evolvable.md` no existe, reportar como
+hallazgo crítico: el kernel SIN política documentada es violación de
+`reglas/gobernanza.md`.
+
 ## Paso 2 — Emitir el dashboard (formato humano)
 
 Template de salida:
@@ -74,6 +98,26 @@ Template de salida:
     Aplicadas ............. <n>
     Revertidas ............ <n>
     Neta .................. <n>
+    Rollback ratio ........ <%>   (N/A si aplicadas == 0)
+
+  CALIDAD CONDUCTUAL (14d)
+    Fallos por tipo:
+      bad_output_format   <n>
+      tool_error          <n>
+      timeout             <n>
+      schema_violation    <n>
+      task_incomplete     <n>
+      unknown             <n>
+    Reintentos consecutivos
+      Total ............... <n>   (mismo agente, misma task, ≤30 min)
+      Top agente .......... <agente>: <n>
+    Latencia top agente
+      Mediana ............. <ms>
+      p95 ................. <ms>
+    Sin instrumentación todavía:
+      • precision_routing_fase_dominio
+      • utilidad_memoria_recuperada
+      • violaciones_formato_post_ejecucion
 
   ALERTAS PERSISTENTES
     <si alertasActivas.length === 0>
@@ -82,6 +126,11 @@ Template de salida:
       [!] kind=X target=Y count=Z (primera: fecha)
       ...
 
+  KERNEL (gobernanza)
+    Política evolvable .... .planning/evolucion/politica-evolvable.md
+    Último ADR kernel ..... <ADR-NNNN — título — fecha>
+    Agentes evolvable=false <n>/<total>
+
 ═══════════════════════════════════════════════════════════════
 ```
 

package/comandos/swl/release.md

@@ -120,7 +120,57 @@ Actualiza la versión en TODOS los archivos que la contienen. Para proyectos SWL
 
 Para proyectos no-SWL: actualiza los archivos detectados en Paso 1 (package.json, pyproject.toml, VERSION).
 
-En ambos casos, verificar consistencia después de actualizar con `grep -r "versión-anterior" .` para detectar referencias olvidadas.
+### Tres capas de versionado — NO confundir
+
+El sistema SWL versiona en tres capas independientes. El bump de versión del SISTEMA toca SOLO la capa 1:
+
+| Capa | Qué versiona | Cuándo cambia | Tocar en `/swl:release`? |
+|------|--------------|---------------|--------------------------|
+| **1. Sistema** | El paquete `@saulwade/swl-ses` como conjunto | En cada release | **SÍ — los 15 archivos del checklist arriba** |
+| **2. Componente individual** | Frontmatter `version:` de cada agente o skill (`agentes/*.md`, `habilidades/*/SKILL.md`) | Cuando el componente específico cambia (ver `/swl:aprender` Paso 6 acción 2) | **NO — cada componente versiona independiente** |
+| **3. Histórico** | Referencias a versiones pasadas en `CHANGELOG.md`, `CHANGELOG-LEGACY.md`, ADRs, RELEASE-NOTES, comentarios `Histórico: hasta vX.Y...` | Nunca (son inmutables por definición) | **NO — son registros históricos** |
+
+Verificación post-bump con `grep -rn "<versión-anterior>"` revelará decenas o cientos de matches en capas 2 y 3 — eso es esperado y correcto. Filtrar ruido para confirmar que las únicas líneas modificadas son de la capa 1:
+
+```bash
+# Después del bump, validar consistencia SOLO en archivos canónicos del sistema
+node -e "
+const p=require('./package.json'),l=require('./plugin.json');
+const lock=require('./package-lock.json');
+const ok = p.version===l.version && l.version===lock.version;
+console.log(ok ? 'OK consistente: '+p.version : 'INCONSISTENTE');
+"
+```
+
+Si el chequeo del nodo arriba dice OK pero `grep` aún muestra matches de la versión anterior, esos matches son **capa 2 (frontmatter)** o **capa 3 (histórico)** y son legítimos — no tocarlos.
+
+### Republish-only entre registries (caso especial)
+
+Si el publish dual falla en uno de los 2 registries (typically npmjs o GitHub
+Packages) pero el otro queda publicado, **NO se puede reintentar la misma versión**
+— ningún registry permite sobreescribir versiones. Ejecutar inmediatamente un bump
+PATCH (1.X.Y → 1.X.(Y+1)) siguiendo el checklist arriba, y publicar solo al
+registry faltante con `node scripts/publicar.js --solo-npmjs` o `--solo-github`.
+
+Documentar el republish exclusivamente como "republish de coordinación entre
+registries" en CHANGELOG, sin atribuirle cambios funcionales que no existen.
+
+Ver `Skill("release-semver")` sección "Publish a múltiples registries" para detalles.
+
+## Paso 6.5 — Regenerar skills-lock.json
+
+Antes del CHANGELOG, regenerar el lock de skills para capturar el estado de
+los 151 SKILL.md de la release:
+
+```bash
+node scripts/generar-skills-lock.js
+git add manifiestos/skills-lock.json
+```
+
+El lock contiene SHA256 de cada SKILL.md y permite que `/swl:salud` detecte
+drift silencioso entre releases. Si el lock no cambió respecto al anterior,
+el commit lo refleja como no-op (idempotente). El archivo es pequeño (~37KB)
+y debe versionarse.
 
 ## Paso 7 — Generar CHANGELOG
 
@@ -178,6 +228,32 @@ Resultado: 13/15 OK, 2 FALLA(S) obligatoria(s)
 
 Esta gate existe porque el agente `release-manager-swl` ha omitido archivos en 3 releases consecutivos (5.10.3, 5.10.4, 5.10.5 — ver APRENDIZAJES.md) pese a tener la checklist documentada en su frontmatter. Un checklist textual no basta: se necesita ejecución.
 
+### 10.1.1 Gate de cobertura por lenguaje (regeneración obligatoria)
+
+Tras el verificar-release.js, regenerar la matriz lenguaje × cobertura SWL:
+
+```bash
+node scripts/generar-matriz-lenguajes.js
+```
+
+El script reescribe `.planning/cobertura-lenguajes.md` con el estado actual.
+Comparar contra el commit anterior:
+
+```bash
+git diff .planning/cobertura-lenguajes.md
+```
+
+Si algún lenguaje **bajó de status** (completo → parcial, parcial → faltante)
+sin ADR documentado en `.planning/adrs/` justificando la regresión, **NO hacer
+release**. La regresión silenciosa de cobertura erosiona la promesa "polyglot"
+del repo.
+
+Si el cambio es esperado (eliminación deliberada de un componente), el ADR
+debe existir con número y fecha y referenciarse en el commit del release.
+
+Lo mismo aplica para releases con incremento de cobertura: la nueva matriz se
+commitea junto al release y se menciona en RELEASE-NOTES.
+
 ### 10.2 Verificación manual post-gate
 
 ```bash

package/comandos/swl/salud.md

@@ -286,6 +286,29 @@ Si `SWL_AUDIT_AGENTES` no está definida, este paso se omite — los reportes
 son opt-in por diseño (CLAUDE.md: "Variables de entorno opt-in para
 integraciones enterprise").
 
+## Paso 5e — Verificación de drift de skills (skills-lock)
+
+Si existe `manifiestos/skills-lock.json`, comparar el hash actual de cada
+`habilidades/*/SKILL.md` contra el lock. Detecta ediciones silenciosas de
+skills entre release y release.
+
+```bash
+node scripts/generar-skills-lock.js --check
+```
+
+Estados posibles:
+
+| Salida | Significado | Acción |
+|--------|-------------|--------|
+| `✓ skills-lock OK: N skills sin drift` | Todos los hashes coinciden | Continuar |
+| `✗ skills-lock DRIFT detectado` | Skills modificados, nuevos o faltantes | Listar diferencias y proponer regenerar |
+
+Si NO existe el lock (proyecto fresco o pre-1.1.0), este paso se omite y
+emite advertencia sugerente: `node scripts/generar-skills-lock.js`.
+
+El lock se regenera automáticamente como parte de `/swl:release`. Drift
+fuera de release indica ediciones manuales no committed.
+
 ## Paso 6b — Formato de salida enriquecido (HealthRow)
 
 El módulo `scripts/lib/health-row.js` genera filas de salud con formato visual enriquecido

package/habilidades/checklist-seguridad/SKILL.md

@@ -1,7 +1,12 @@
 ---
 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.0.0"
+version: "1.1.1"
+evolved: true
+evolved-from: "1.1.0"
+evolved-at: "2026-05-04"
+evolved-by: "aprender"
+evolved-note: "Corregir contradicción interna en ejemplo BIEN de IDOR pre-side-effect: el detail exponía UUID interno violando el gotcha 'vocabulario interno' de fastapi-experto v1.1.1. Detail al cliente ahora es genérico (Recurso no encontrado); UUID y tenant solo en logger.info para auditoría."
 herramientasPermitidas: [Read, Grep]
 evolvable: true  # default para skill estandar
 nist_csf: [PR.PS-01, PR.DS-02, PR.DS-10, DE.CM-09, RS.MI-01]
@@ -58,6 +63,57 @@ grep -rn "user_id.*Query\|owner_id.*Query" --include="*.py" | head -20
 **Señal de vulnerabilidad**: endpoint que filtra por `user_id` recibido como
 parámetro de URL sin compararlo con el `user_id` del token JWT.
 
+### IDOR pre-side-effect: validar pertenencia ANTES de operaciones costosas
+
+Un endpoint que sube/cifra/procesa material antes de validar que el recurso pertenece al
+tenant del usuario es un IDOR amplificado: aunque RLS o el FK rechacen la operación al
+final, los **side-effects intermedios** (lectura de bytes del cliente, cifrado AES-GCM,
+upload a MinIO/S3 bajo un namespace, llamada costosa a API externa) **ya ocurrieron** y
+pueden contaminar storage, agotar recursos o filtrar PII bajo el namespace incorrecto.
+
+```python
+# MAL — IDOR pre-side-effect: el upload ocurre antes del check RLS
+async def subir_evidencia(entrega_id: UUID, archivo: UploadFile, ...):
+    contenido = await archivo.read()                    # side-effect: bytes leídos
+    cifrado = aes_gcm_encrypt(contenido, master_key)    # side-effect: PII cifrada
+    object_key = f"tenant_{usuario.tenant_id}/{entrega_id}/{uuid4()}"
+    await minio.put_object(object_key, cifrado)         # side-effect: subido a MinIO
+    # AHORA el INSERT corre con RLS — si entrega_id es de otro tenant, falla con 404,
+    # pero el PII ya quedó cifrado bajo el namespace de tenant_A para entrega_B.
+    await repo.insert_evidencia(entrega_id, object_key, ...)
+```
+
+```python
+# BIEN — validar pertenencia ANTES de cualquier side-effect costoso
+async def subir_evidencia(entrega_id: UUID, archivo: UploadFile, ...):
+    if await repo_entrega.obtener_por_id(entrega_id) is None:
+        # RLS filtra el SELECT — None significa "no existe en este tenant".
+        # Detail genérico al cliente; UUID + tenant solo en log interno.
+        # (Ver gotcha "vocabulario interno en detail" de fastapi-experto.)
+        logger.info(
+            "IDOR check fallido: recurso %s no accesible para tenant %s",
+            entrega_id, usuario.tenant_id,
+        )
+        raise HTTPException(404, "Recurso no encontrado.")
+
+    contenido = await archivo.read()                    # solo si validación pasó
+    cifrado = aes_gcm_encrypt(contenido, master_key)
+    ...
+```
+
+**Cuándo aplicar**: cualquier endpoint que combine path-param de recurso (`{recurso_id}`)
+con uno o más de estos side-effects: `archivo.read()`, cifrado, upload a storage externo,
+llamada a API costosa de PSP/proveedor, generación de PDF, envío de email/SMS. Antes
+del primer side-effect, ejecutar `repo.obtener_por_id(recurso_id)` y retornar 404 si None.
+
+**Mecanismos que NO son suficientes por sí solos**:
+- RLS DENY-by-default: protege el INSERT/UPDATE/SELECT, pero NO los side-effects intermedios.
+- FK constraint: protege la integridad referencial, pero el side-effect ya ocurrió.
+- `require_permiso`: valida que el usuario tiene permiso de la acción, NO que el recurso
+  específico pertenezca a su tenant.
+
+La validación pre-side-effect es **defensa en profundidad**: complementa RLS/FK, no las reemplaza.
+
 ---
 
 ## A02 — Cryptographic Failures (Exposición de datos sensibles)

package/habilidades/extractor-de-aprendizajes/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: extractor-de-aprendizajes
 description: Convertir errores y patrones descubiertos durante la implementación en nuevas habilidades o reglas. Ciclo de mejora continua del sistema SWL.
-version: "1.0.2"
+version: "1.0.3"
 herramientasPermitidas: [Read]
 exclusiones:
   - "No cargar para actualizar el perfil del usuario — las correcciones explícitas del usuario van a `instintos/perfil-usuario.yaml` vía `perfilador-usuario-swl`, no a APRENDIZAJES.md."
@@ -10,10 +10,10 @@ exclusiones:
   - "No cargar si el aprendizaje no tiene causa raíz identificada — documentar síntoma sin causa produce reglas que no previenen el error real."
 evolvable: true  # default para skill estandar
 evolved: true
-evolved-from: "5.12.3"
-evolved-at: "2026-04-25"
+evolved-from: "1.1.1"
+evolved-at: "2026-05-02"
 evolved-by: "aprender"
-evolved-note: "2 gotchas nuevos: Explore sobreestima papers + hooks calidad falsos positivos"
+evolved-note: "Extender gotcha Explore (papers → papers+repos) tras confirmación x4 — sync desde skill global"
 ---
 # Extractor de Aprendizajes
 
@@ -296,7 +296,17 @@ Durante `/swl:aprender`, aplicar estas reglas:
 - **`rating: HIGH` asignado sin verificar criterio de irreversibilidad**: el agente promueve a CLAUDE.md un aprendizaje "MEDIUM" por el entusiasmo del momento. Causa: no se aplicó el criterio de "decisión irreversible o bug crítico". Solución: antes de asignar HIGH, verificar: ¿cambiar esto en el futuro requeriría refactorizar múltiples archivos o migrar datos? Si no, mantener MEDIUM.
 - **Regla incompleta sobre registro de hooks**: una entrada en memoria dice "registrar en modulos.json" pero omite `hooks-config.json`, y en la siguiente iteración se repite el fallo en CI porque ambos manifiestos son obligatorios. Causa: la regla de la lección anterior no cubrió todos los manifiestos afectados. Solución: al documentar una regla sobre registro en manifiestos, listar EXPLÍCITAMENTE cada manifiesto con su responsabilidad distinta (`modulos.json` = qué copiar; `hooks-config.json` = cómo registrar evento). Evidencia: tres incidentes históricos del mismo patrón incompleto (v5.7.1, v5.7.2/3, v5.11.0).
 - **Inventario estimado a mano en vez de regenerar**: el agente cuenta "28 hooks" visualmente y propaga la cifra a 5 archivos (CLAUDE/README/package/plugin/SALUD); al regenerar con `scripts/generar-inventario.js` el número real es 30. Causa: confiar en la observación directa en vez de la fuente de verdad determinista. Solución: antes de modificar cualquier contador en documentación oficial, ejecutar el script de inventario y usar su salida como ground truth.
-- **Sub-agente Explore sobreestima costos al analizar papers académicos**: cuando se delega análisis de un paper (arXiv, MIT, etc.) al sub-agente Explore, el reporte propone implementar **todas** las contribuciones del paper sin filtrar por restricciones del sistema destino. Casos observados (sesión 2026-04-25): sub-agente propuso 50h+ para implementar SPRT + Lyapunov + compositionality theorem del paper Bhardwaj 2026; costo real validado fue ~5h (solo Drift Score + Recovery Catalog). Causa: el Explore evalúa portabilidad técnica sin aplicar filtro de "datos disponibles" ni "infraestructura zero-deps". Solución: antes de aceptar el plan del Explore para implementar contribuciones de un paper, aplicar **3 filtros críticos**: (1) ¿requiere SMT solver / SPRT / Lyapunov / DTMC / formal verification? → descartar (rompe zero-deps); (2) ¿requiere N>100 sesiones de campo para validación estadística? → descartar (SWL no tiene los datos); (3) ¿genera valor accionable HOY o solo elegancia matemática? → solo implementar si HOY. Evidencia: 3 papers analizados (evolver, Bhardwaj 2026, Zhang et al. 2026) con descarte sistemático ~70-90% del contenido propuesto.
+- **Sub-agente Explore sobreestima al analizar fuentes externas (papers + repos)** [CONFIRMADO x4]: cuando se delega análisis de una fuente externa (paper arXiv, repositorio GitHub, documentación de framework) al sub-agente Explore, el reporte propone implementar contribuciones sin filtrar por restricciones del sistema destino Y, peor, sin verificar qué de eso ya existe en el proyecto. **Dos modos de falla observados**:
+
+  **Modo A — papers académicos** (sesión 2026-04-25): sub-agente propuso 50h+ para implementar SPRT + Lyapunov + compositionality theorem del paper Bhardwaj 2026; costo real validado fue ~5h (solo Drift Score + Recovery Catalog). Causa: el Explore evalúa portabilidad técnica sin aplicar filtro de "datos disponibles" ni "infraestructura zero-deps". Evidencia: 3 papers analizados (evolver, Bhardwaj 2026, Zhang et al. 2026) con descarte sistemático ~70-90% del contenido propuesto.
+
+  **Modo B — repositorios externos** (sesión 2026-05-02 cosecha-temp/ EMAIA): sub-agente analizando `temp/docetl-main` (UC Berkeley, arXiv:2410.12189) afirmó dos cosas FALSAS verificables contra el código del proyecto destino: (1) "EMAIA ya usa LiteLLM" — verificación contra `pyproject.toml` + `grep -r litellm core/` mostró que EMAIA tiene clientes propios (`OllamaClient`/`NIMClient`/`vLLMClient`) y NO usa LiteLLM en absoluto; (2) recomendó portar Gleaning como patrón nuevo, cuando `core/learning/evaluator_optimizer.py` y `core/llm/quality_judge.py` YA implementan Anthropic Evaluator-Optimizer + LLM-as-judge. El fix real era WIRING (~30 LOC), no porting. Costo "MEDIO" del agente quedó como BAJO real. Causa: el Explore evalúa el repo externo en aislamiento, sin leer paths del proyecto destino para verificar qué mecanismos ya existen.
+
+  **Solución unificada — aplicar filtros antes de aceptar propuesta del Explore**:
+
+  *Para papers académicos (Modo A)*: 3 filtros críticos: (1) ¿requiere SMT solver / SPRT / Lyapunov / DTMC / formal verification? → descartar (rompe zero-deps); (2) ¿requiere N>100 sesiones de campo para validación estadística? → descartar; (3) ¿genera valor accionable HOY o solo elegancia matemática? → solo implementar si HOY.
+
+  *Para repos externos (Modo B)*: 4 filtros críticos: (1) ¿qué % es teoría/código no-portable vs portable? — si >70% no-portable, recortar; (2) **¿la propuesta reescribe mecanismos existentes en el proyecto destino?** — VERIFICAR con `Grep`/`Read` 2-3 afirmaciones concretas del agente contra el código real ANTES de aceptar (ej: agente dice "X usa Y" → `grep -l Y` para confirmar); (3) ¿LOC nuevas estimadas vs reutilizar lo existente? — si la propuesta supera 500 LOC para un solo patrón, hay sobre-ingeniería; (4) ¿el alcance reducido cubre 80% del valor? — Pareto: identificar el patrón mínimo que captura la mayor parte del beneficio. **Patrón de validación obligatorio**: extraer 2-3 afirmaciones factuales del reporte del Explore (ej: "X usa LiteLLM", "no existe Gleaning en el proyecto") y verificar cada una con `Grep`/`Read` antes de aceptar el plan.
 - **Hooks de calidad pre-commit bloquean fixtures de tests como falsos positivos**: el hook `calidad-pre-commit.js` aplica regex `\b(api_key|password|token|secret)\s*[=:]\s*["'][^"'\s]{4,}["']` que matchea fixtures legítimos en archivos de test. Caso real: test que valida que la función `sanitizar()` redacta `api_key="abc12345xyz"` se bloquea. Causa: el hook no distingue contexto de test vs producción. Solución: en archivos de test, construir fixtures con concatenación de strings (`'api' + '_key'`, `'pass' + 'word'`) o agregar marcador placeholder reconocido por el hook (`fake_`, `dummy_`, `placeholder`, `example`, `os.environ`). NUNCA bypassear el hook con `--no-verify` — el detector cumple su función; ajustar el fixture es lo correcto.
 
 ## Anti-patrones del proceso de extracción

package/habilidades/fastapi-experto/SKILL.md

@@ -5,7 +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.1.0"
+version: "1.1.2"
+evolved: true
+evolved-from: "1.1.1"
+evolved-at: "2026-05-04"
+evolved-by: "aprender"
+evolved-note: "Fix lógica del gotcha endswith asyncpg: el formato 'INSERT oid N' tiene 3 partes (no 2), len(partes) == 2 fallaba para INSERT. Solución correcta: int(partes[-1]) — siempre el count, sea con o sin oid."
 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."
@@ -210,6 +215,10 @@ class Factura(Base):
 - **El endpoint GET hace `db.commit()` y el test pasa, pero en producción los datos se modifican inesperadamente**: un GET que comitea no es idempotente — herramientas de monitoreo, crawlers de SEO o retries del cliente pueden ejecutar el GET múltiples veces. Causa: `db.commit()` en un GET activa transacciones que modifican estado. Solución: según la regla del skill, los endpoints GET NUNCA deben hacer `db.commit()` — si el endpoint necesita registrar que se accedió al recurso, usar una tarea async en background con `BackgroundTasks`.
 - **Pydantic v2 `model_validator(mode='before')` silencia errores de tipo al recibir None donde se espera un dict**: Pydantic v2 convierte `None` a `{}` en algunos contextos de validación `before`, produciendo un modelo con todos los campos como `None` en lugar de fallar con `ValidationError`. Causa: el `mode='before'` recibe el valor crudo antes de la coerción de tipos; si el validator retorna el valor sin verificar, Pydantic intenta instanciar el modelo con datos inválidos. Solución: en el `model_validator(mode='before')`, verificar explícitamente que el valor no es `None` antes de procesarlo: `if values is None: raise ValueError("...")`.
 - **Baseline Alembic con `create_all()` genera deuda estructural en toda la cadena de migraciones posterior**: si el baseline `0001_initial.py` usa `Base.metadata.create_all(bind=op.get_bind())` en lugar de `op.create_table(...)` explícito, cada migración posterior (0002, 0003, ...) debe asumir que el estado real del schema puede diverger del árbol de modelos declarado y volverse idempotente con helpers tipo `_column_if_missing`, `_index_if_missing`. Causa: `create_all` refleja el estado actual de los modelos Python, no un snapshot explícito del schema — si el schema de producción diverge (índices agregados a mano, columnas con defaults distintos), las migraciones posteriores fallan con errores de "already exists" o no ejecutan acciones que asumen que el estado previo era el declarado. Solución: **nunca** usar `create_all()` en migraciones de Alembic. Baseline debe tener `op.create_table(...)` explícito por cada tabla del schema inicial. Si el proyecto ya tiene esta deuda, dos opciones: (a) migraciones posteriores 100% idempotentes con `IF NOT EXISTS` y helpers, (b) regenerar baseline con `alembic revision --autogenerate` tras un `alembic stamp head` a una base limpia y squash del historial.
+- **`tag.endswith("1")` para parsear count de asyncpg DELETE/UPDATE matchea falsos positivos**: `conn.execute("DELETE FROM ...")` retorna un string `"DELETE N"` donde N es el número de filas afectadas. Usar `tag.endswith("1")` para verificar "exactamente 1 fila afectada" matchea **incorrectamente** `"DELETE 10"`, `"DELETE 11"`, `"DELETE 21"`, `"DELETE 100"`. Aunque el query actual sea `WHERE id = $1` (PK, máximo 1 fila), un refactor futuro a `WHERE programa_id = $1` haría que el método retornara True silenciosamente para 10+ filas. Causa: `endswith` opera sobre sufijo textual, no parsea el número. **El formato del tag varía por comando**: `"UPDATE N"` y `"DELETE N"` tienen 2 partes, pero `"INSERT oid N"` tiene 3 partes (asyncpg/PostgreSQL siempre incluye el oid en INSERT, generalmente `0` en tablas modernas sin OIDs). Usar `len(partes) == 2` falla para INSERT. Solución portable que cubre los tres casos: leer el **último** componente, que siempre es el count: `partes = tag.split(); afectadas = int(partes[-1]) if len(partes) >= 2 and partes[-1].isdigit() else 0`. Para verificar "exactamente 1": `afectadas == 1`. Aplicable a UPDATE, DELETE e INSERT por igual.
+- **`return result or {}` después de UPDATE/INSERT enmascara errores de BD silenciosamente**: patrón típico `result = await repo.actualizar_estatus(...); return result or {}` devuelve `{}` al cliente cuando el UPDATE no encontró la fila (race condition, RLS, FK violado). El cliente recibe HTTP 200 con body vacío en lugar del 404/500 esperado, los bugs quedan invisibles en monitoring. Causa: `or {}` trata `None` como "datos no disponibles" cuando en realidad significa "el UPDATE falló post-INSERT". Solución: explicit None check con raise — usar `if result is None: raise HTTPException(404, "Recurso no encontrado")` cuando el ID viene del cliente, o `raise HTTPException(500, "Error interno...")` cuando es un invariante post-INSERT (la fila acaba de crearse, debe existir).
+- **`detail=str(exc)` en HTTPException — solo aceptable cuando la excepción es de DOMINIO con mensaje diseñado para usuario**: las excepciones de capa externa (MinIO/S3, BD driver, HTTP client de un PSP, parser PDF) tienen mensajes que pueden contener bucket/host/paths/credenciales parciales/stack traces. Pasar `str(exc)` directo al `detail` los expone al cliente. Causa: tratar todas las excepciones igual sin distinguir dominio (controlado) de capa externa (no controlado). Solución: dos patrones distintos. Para excepciones de dominio (`MIMENoPermitidoError("MIME 'X' no permitido")`, `EmailDuplicadoError`): `except DominioError as exc: raise HTTPException(422, detail=str(exc))` OK. Para capa externa (`ErrorEvidencia`, `boto3.ClientError`, `httpx.RequestError`): `except CapaExternaError as exc: logger.exception("contexto"); raise HTTPException(502, detail="Error genérico al cliente")`. La diferencia es que el mensaje de DominioError fue diseñado para el usuario; el de CapaExternaError no.
+- **Vocabulario interno (nombres de funciones PL/pgSQL, schemas, tablas, "RLS", "transaccional") en `detail` al cliente fuga arquitectura**: detail genérico al cliente y detail con detalles de infraestructura para diagnóstico **no son lo mismo**. Patrones de fuga típicos: `detail=f"fn_evaluar_X no retornó resultado"` (revela nombre de función PL/pgSQL), `detail="Posible inconsistencia transaccional o RLS"` (revela motor + capa de seguridad), `detail=f"Recurso {id} no encontrado en activacion tras INSERT"` (revela UUID interno y secuencia de operaciones). Causa: el desarrollador escribe el mensaje pensando en debug, no en exposición. Solución: detail al cliente = mensaje genérico orientado al recurso ("Error interno al activar el recurso. Contacte al administrador."); detalles internos solo en `logger.error("contexto detallado %s %s", uuid, programa_id, ...)` con format strings estructurados (NO concatenación con `+`). Aplica a todos los HTTPException 500/503; el 404/422 puede ser más específico si el mensaje es del dominio.
 
 ## Referencias especializadas
 

package/habilidades/manejo-errores/.evolved.json

@@ -1,9 +1,9 @@
-{
-  "SKILL.md": {
-    "evolved": true,
-    "evolvedFrom": "5.10.4",
-    "evolvedAt": "2026-04-20",
-    "evolvedBy": "aprender",
-    "evolvedNote": "throttle adaptativo ante fallo transitorio"
-  }
+{
+  "SKILL.md": {
+    "evolved": true,
+    "evolvedFrom": "1.1.0",
+    "evolvedAt": "2026-05-02",
+    "evolvedBy": "aprender",
+    "evolvedNote": "Gotcha nueva: try/catch require para módulos opcionales (15 archivos migrados)"
+  }
 }

package/habilidades/manejo-errores/SKILL.md

@@ -4,12 +4,12 @@ description: >
   Patrones de manejo de errores en Python y TypeScript. Jerarquía de excepciones,
   excepciones personalizadas, códigos de error, logging estructurado, error boundaries,
   degradación elegante, patrones de reintento y circuit breakers.
-version: "1.1.0"
+version: "1.2.0"
 evolved: true
-evolved-from: "1.0.2"
-evolved-at: "2026-04-24"
+evolved-from: "1.1.1"
+evolved-at: "2026-05-04"
 evolved-by: "aprender"
-evolved-note: "Sección nueva: except Exception: pass en cleanup es válido, pero con logger.debug para trazabilidad"
+evolved-note: "+sección anti-patrón except Exception con isinstance interno — usar excepts planos por tipo (sync desde global tras sesión SIGM Fase 5b). Preserva gotcha try/catch require de v1.1.1."
 herramientasPermitidas: [Read]
 exclusiones:
   - "No cargar para monitoreo y alertas en producción (Prometheus, Grafana, PagerDuty) — para observabilidad cargar `monitoring-alertas` o `sre-patrones`."
@@ -76,6 +76,50 @@ class ErrorExterno(ErrorAplicacion):
 
 ---
 
+## Anti-patrón: `except Exception` con `isinstance` interno
+
+**Problema**: capturar todo con `except Exception` y luego despachar por tipo con
+`isinstance` enmascara excepciones futuras del módulo y dificulta seguir el flujo
+de control.
+
+```python
+# MAL — except genérico con isinstance interno
+try:
+    registro = await ev_svc.subir_evidencia(...)
+except (MIMENoPermitidoError, TamanoExcedidoError) as exc:
+    raise HTTPException(422, detail=...) from exc
+except Exception as exc:  # ← captura TODO lo que no caía arriba
+    if isinstance(exc, ErrorEvidencia):
+        raise HTTPException(502, detail="MinIO error") from exc
+    raise  # cualquier otra excepción se re-lanza
+```
+
+Problemas:
+1. Si en el futuro `ev_svc` lanza una nueva excepción `EvidenciaCorruptaError` que debería
+   ser 422, queda capturada por `except Exception` y se re-lanza como 500 silenciosamente.
+2. La intención del código no es clara: ¿qué tipos esperamos? ¿qué hace fallback?
+3. Auditores de seguridad no pueden verificar fácilmente qué excepciones están manejadas.
+
+```python
+# BIEN — except plano por tipo, sin isinstance interno
+try:
+    registro = await ev_svc.subir_evidencia(...)
+except (MIMENoPermitidoError, TamanoExcedidoError) as exc:
+    raise HTTPException(422, detail=str(exc)) from exc
+except ErrorEvidencia as exc:
+    logger.exception("Error MinIO al subir evidencia")
+    raise HTTPException(502, detail="Error genérico al cliente") from exc
+# Cualquier otra excepción se propaga al handler global — explícito.
+```
+
+Reglas:
+- Un `except` por tipo (o tupla de tipos relacionados) que requiera tratamiento distinto.
+- NO usar `except Exception` salvo en handlers globales explícitos (FastAPI exception_handler).
+- Si necesitas distinguir múltiples tipos en un mismo handler, usa `except (A, B, C)` no
+  `except Exception` + `isinstance`.
+
+---
+
 ## Python — Encadenamiento de Excepciones
 
 SIEMPRE usar `raise ... from exc` para preservar la cadena de errores:
@@ -238,6 +282,21 @@ function debeVerificar() {
 
 Aplica a: health checks periódicos, verificación de nuevas versiones, consultas de cuota/rate-limit de APIs externas, chequeos de certificados, polling de colas. La línea divisoria es "¿el resultado anterior fue información real o fue ausencia de información?".
 
+**Patrón `try { require } catch` para módulos opcionales en Node con fallback noop**: un hook o lib en `hooks/lib/` requiere de otra lib del mismo directorio (ej. `atomic-write.js`) que puede o no existir según la versión instalada del sistema o si el archivo se ejecuta standalone (CLI ad-hoc, test aislado). Importar con `require('./atomic-write')` directo lanza `MODULE_NOT_FOUND` y el hook crashea, bloqueando cualquier operación que lo invoque. Causa: `require` es síncrono y propaga la excepción al caller. Fix: envolver el require en try/catch y proveer un fallback que cumpla el mismo contrato de la dependencia, sin garantías adicionales (atomicidad, persistencia, etc.):
+
+```js
+let atomicWriteSync, atomicWriteJSON;
+try {
+  ({ atomicWriteSync, atomicWriteJSON } = require('./atomic-write'));
+} catch {
+  // Fallback no-atómico — funciona pero pierde la garantía de write atómico
+  atomicWriteSync = (p, c, e) => fs.writeFileSync(p, c, e);
+  atomicWriteJSON = (p, o) => fs.writeFileSync(p, JSON.stringify(o, null, 2), 'utf8');
+}
+```
+
+Aplica a: módulos en `hooks/lib/` que se cargan desde otros hooks pero también pueden ejecutarse vía `node -e` o tests aislados, libs que dependen de otras libs del mismo paquete pero queremos que el lib funcione si alguien la copia sola, scripts de mantenimiento que viven en `scripts/` y referencian utilidades de `hooks/lib/`. NO aplica a dependencias del package.json (esas SÍ deben fallar si no están — son contratos firmes); aplica solo a dependencias internas del propio repositorio cuya disponibilidad no es garantizada en todos los contextos de ejecución. Evidencia: 15 archivos críticos de `hooks/` y `scripts/` migraron a este patrón en sesión 2026-05-02.
+
 ## Gotcha — Retry con cliente HTTP interno: propagar el timeout
 
 ### NUNCA: wrapper de retry que promete N segundos sobre cliente HTTP con timeout M << N

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.0"
+version: "1.3.1"
 evolved: true
-evolved-from: "1.2.0"
-evolved-at: "2026-04-27"
+evolved-from: "1.3.0"
+evolved-at: "2026-05-04"
 evolved-by: "aprender"
-evolved-note: "3 secciones nuevas (regex multi-pattern al extender scope, tracer/replicador con marca SYNC, fixtures crudos vs condensados) + refinamiento de la sección caché content-addressable (sharding, bypass env var, key multi-dimensión, tests obligatorios). Preserva F401 en soft imports. Patrones avanzados extraídos a recursos/patrones-avanzados.md para respetar el límite de 300 líneas de SKILL.md."
+evolved-note: "+1 gotcha: assert se elimina con PYTHONOPTIMIZE=1 — usar if/raise para invariantes (sync desde global tras sesión SIGM Fase 5b)"
 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."
@@ -204,6 +204,7 @@ ver [recursos/referencia-completa.md](recursos/referencia-completa.md).
 - **Decorator que usa `functools.wraps` pero no preserva type hints si la función decorada tiene anotaciones genéricas**: el `@wraps` copia `__wrapped__`, `__doc__` y `__name__`, pero el tipo de retorno inferido por `mypy` es el del wrapper, no el del wrapped. Causa: `functools.wraps` no puede preservar el tipado estático del wrapped — mypy ve el tipo del wrapper `Callable[..., Any]`. Solución: usar `TypeVar` y tipado genérico en el decorator con `ParamSpec` (Python 3.10+): `P = ParamSpec('P'); T = TypeVar('T')` y tipar el wrapper como `Callable[P, T]`.
 - **`__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`.
 
 ---