@saulwade/swl-ses 1.0.0

package/habilidades/auto-evolucion-protocolo/SKILL.md

@@ -0,0 +1,276 @@
+---
+name: auto-evolucion-protocolo
+description: >
+  Protocolo de auto-evolución del sistema SWL. Cómo los agentes aprenden y se mejoran,
+  proponen cambios, versionado semántico de agentes, changelog, métricas de evolución,
+  governance de cambios, parser de señales de fricción y safety checks.
+version: "1.1.1"
+herramientasPermitidas: [Read, Bash, Grep]
+evolvable: false  # bloqueado por lista (skill de seguridad/privacidad)
+exclusiones:
+  - "No cargar para evolución del código de aplicación del usuario (migración de APIs de frameworks, refactors de módulos propios) — para eso cargar el skill del framework correspondiente (`angular-moderno`, `react-optimizacion`, backend-*) o invocar `implementador-swl`."
+  - "No cargar para migraciones de schema de base de datos o datos en reposo — para migraciones de persistencia cargar `postgresql-experto` y usar `migrador-swl`."
+  - "No cargar para aplicar automáticamente cambios sobre skills o agentes con `evolvable: false` — estos artefactos requieren ADR explícito y decisión humana fuera del ciclo AGP."
+  - "No cargar para evoluciones de dependencias externas (bumps de versión, deprecación de librerías) — para eso cargar `dependencias-auditoria` + `deprecacion-migracion`."
+---
+# Protocolo de Auto-Evolución del Sistema SWL
+
+## Cuándo NO cargar
+
+- La evolución es sobre código de aplicación del usuario (API de un framework cambió, hay que actualizar componentes): cargar el skill del framework (`angular-moderno`, `react-optimizacion`, backend-*) o invocar `implementador-swl`. Este skill es para evolución de artefactos del sistema SWL (agentes, skills, reglas), no del producto.
+- La tarea es migrar schemas de base de datos o datos en producción: cargar `postgresql-experto` y delegar a `migrador-swl`. La auto-evolución no cubre migraciones de persistencia — son irreversibles y requieren plan propio.
+- El artefacto objetivo tiene `evolvable: false`: este skill NO se auto-aplica sobre artefactos bloqueados. Requiere ADR explícito y edición manual por decisión humana.
+- La evolución es un bump de versión de dependencia externa (npm, pip): cargar `dependencias-auditoria` y `deprecacion-migracion`. Este skill cubre evolución de conocimiento interno del sistema, no del árbol de deps.
+
+## ¿Por qué auto-evolución?
+
+El sistema SWL es una colección de agentes y skills que guían la implementación
+de software. Con el tiempo, estos artefactos envejecen:
+- Los frameworks cambian sus APIs.
+- Los equipos descubren nuevos anti-patrones.
+- Los errores recurrentes revelan gaps en los skills.
+- Los workflows ineficientes se vuelven visibles a través de la práctica.
+
+La auto-evolución es el proceso sistemático por el cual el sistema actualiza su propio
+conocimiento de forma controlada, versionada y auditable.
+
+---
+
+## Anatomía de un Cambio Evolutivo
+
+Todo cambio al sistema SWL pasa por este ciclo:
+
+```
+Observación → Diagnóstico → Propuesta → Revisión → Aplicación → Verificación → Registro
+```
+
+### 1. Observación — ¿Qué triggerea un cambio?
+
+| Trigger | Ejemplo | Prioridad |
+|---------|---------|-----------|
+| Error recurrente en producción | `MissingGreenlet` en SQLAlchemy aparece 3+ veces | ALTA |
+| Nueva versión mayor de framework | Angular v20 cambia la Resource API | ALTA |
+| Patrón nuevo identificado | `satisfies` operator mejora type safety | MEDIA |
+| Deprecación de API | `*ngIf` eliminado en Angular v21 | ALTA |
+| Feedback de desarrollador | "Este skill no cubre migrations con datos" | MEDIA |
+
+### 2. Diagnóstico — ¿Qué está desactualizado exactamente?
+
+Documentar: fecha, observador, error recurrente, síntoma, causa raíz,
+artefacto afectado (archivo + línea), severidad del gap.
+
+---
+
+## Versionado Semántico de Agentes y Skills
+
+```
+MAYOR.MENOR.PARCHE
+
+MAYOR: cambio que rompe compatibilidad backward con proyectos existentes
+       Requiere: aprobación de revisor humano
+
+MENOR: nueva funcionalidad o cobertura de nuevos casos
+       Requiere: revisión del plan-checker
+
+PARCHE: corrección de error, clarificación, ejemplo mejorado
+        Requiere: auto-aplicable por el verificador
+```
+
+---
+
+## Protocolo de Propuesta de Cambio
+
+Formato estándar:
+
+```markdown
+# PROPUESTA-EVOLUCION-NNN
+
+## Metadatos
+- **Fecha**: YYYY-MM-DD
+- **Proponente**: agente
+- **Tipo**: PARCHE | MENOR | MAYOR
+- **Artefacto**: ruta/al/archivo
+- **Urgencia**: Alta | Media | Baja
+
+## Problema Observado
+Descripción del error o gap.
+
+## Evidencia
+- PR/sesión donde se observó (mínimo 2 instancias)
+
+## Cambio Propuesto
+Diff o descripción del cambio.
+
+## Impacto Estimado
+Breaking changes, estimación de mejora.
+
+## Verificación Post-Cambio
+Cómo verificar que el cambio resolvió el problema.
+```
+
+---
+
+## Governance — Quién Puede Cambiar Qué
+
+```yaml
+cambios_autonomos:
+  - tipo: PARCHE
+    condicion: "corrección de ejemplo de código erróneo"
+  - tipo: PARCHE
+    condicion: "agregar anti-patrón observado 3+ veces"
+
+cambios_con_revision:
+  - tipo: MENOR
+    condicion: "nueva sección temática en un skill"
+    aprobadores: ["planificador"]
+  - tipo: MENOR
+    condicion: "nuevo skill creado desde cero"
+    aprobadores: ["planificador", "revisor"]
+
+cambios_con_aprobacion_humana:
+  - tipo: MAYOR
+    condicion: "cambio de convención que afecta código existente"
+  - tipo: cualquiera
+    condicion: "modificar agentes (no skills)"
+  - tipo: cualquiera
+    condicion: "cambiar reglas en CLAUDE.md"
+```
+
+---
+
+## Safety Checks — Antes de Aplicar un Cambio
+
+Todo agente que proponga modificar un artefacto del sistema DEBE verificar:
+
+1. **Consistencia**: Un PARCHE no modifica más de 50 líneas
+2. **Scope**: Modificar agentes requiere aprobación humana
+3. **Evidencia**: Mínimo 2 instancias de evidencia para un cambio
+4. **Reversibilidad**: Todo cambio tiene un plan de rollback documentado
+5. **No contradicciones**: El cambio no contradice otros skills o reglas
+
+---
+
+## Formato de Commit Evolutivo
+
+```
+evolucion(nombre-artefacto): descripción [TIPO v.anterior→v.nueva]
+```
+
+Rollback: `git revert <hash-del-commit-evolutivo>`
+
+---
+
+## Escalera de Adquisición de Capacidades
+
+Cuando se identifica un patrón útil, la tentación es saltar de "lo resolví una vez"
+a "crear un skill". Pero la maduración tiene niveles intermedios. Saltar niveles
+produce skills frágiles que no se activan, workflows sin verificación y automatizaciones
+que fallan silenciosamente.
+
+| Nivel | Nombre | Qué implica | Criterio para avanzar al siguiente |
+|-------|--------|-------------|-----------------------------------|
+| 1 | **Solución ad hoc** | Se resolvió el problema una vez, en una sesión | El mismo problema aparece en otra sesión |
+| 2 | **Repetible** | Pasos documentados en ESTADO.md o DECISIONS.md | Se ejecutó 3+ veces con éxito siguiendo los pasos |
+| 3 | **Skill** | Codificado en SKILL.md con gotchas y restricciones | El skill se activa correctamente y cambia comportamiento (3-arm test) |
+| 4 | **Workflow** | Orquestación multi-agente con delegación definida | Los agentes completan el flujo sin intervención manual en 70%+ |
+| 5 | **Harness determinista** | Scripts en `scripts/` que validan output automáticamente | La validación detecta 90%+ de los errores conocidos |
+| 6 | **Cobertura evaluativa** | Métricas pass@k registradas en EVALUACION.md | pass@1 ≥ objetivo del tipo de agente durante 10+ ejecuciones |
+| 7 | **Automatizado** | Hook o cron que dispara la capacidad sin invocación manual | El hook se ejecuta sin errores en 95%+ de las veces |
+| 8 | **Monitoreado** | Métricas observables: latencia, tasa de error, drift | Dashboards activos y alertas configuradas |
+| 9 | **Autónomo con evidencia** | El sistema decide cuándo usar la capacidad basado en métricas, no en heurísticas | Decisiones autónomas acertadas en 85%+ |
+| 10 | **Empaquetado** | Reutilizable entre proyectos como plugin o módulo independiente | Funciona en 2+ proyectos distintos sin modificación |
+
+**Cómo usar**: Al proponer una evolución, identificar en qué nivel está la capacidad
+actual y proponer avanzar **un solo nivel**. Saltar niveles requiere justificación
+explícita en la propuesta de evolución — la mayoría de las veces es síntoma de
+optimismo injustificado.
+
+Para métricas de evolución, plantilla de changelog, proceso de retroalimentación
+del verificador y checklist completo de revisión,
+ver [recursos/referencia-completa.md](recursos/referencia-completa.md).
+
+---
+
+## Parser de señales de fricción (v1.1)
+
+El hook `hooks/auto-evolucion.js` (SubagentStop) alimenta el log
+`.planning/auto-evolucion/agentes.jsonl` y emite *nudges* hacia
+`auto-evolucion-swl` cuando detecta umbrales cruzados. Este skill define
+**qué cuenta como fricción** para que el agente tenga criterio uniforme al
+interpretar el log.
+
+### Categorías de fricción
+
+| Categoría | Fuente | Fuerza | Contraseña en el log |
+|-----------|--------|--------|----------------------|
+| **Fallo duro** | Subagente terminó con `is_error:true` o excepción | Alta | `status: "failed"` |
+| **Run vacío** | Subagente terminó sin producir cambios útiles (0 Edit/Write) | Media | `toolCalls < 3` en agente de implementación |
+| **Trivial recurrente** | 10+ runs triviales (≤5 tool calls) del mismo agente | Baja | `trivial: true` |
+| **Corrección del usuario** | Mensaje del usuario con keywords de corrección en el turno posterior al run | Alta | detectada por `actualizar-perfil-usuario.js` |
+| **Repetición de error** | Mismo tipo de error documentado ya en `APRENDIZAJES.md` | Alta | cruzar log con grep |
+| **Reintento manual** | Usuario vuelve a invocar el mismo agente con instrucciones ajustadas | Media | comparar `session_id` + `agente` consecutivos |
+
+### Keywords de corrección (es-MX)
+
+Reutilizar la lista definida en `hooks/actualizar-perfil-usuario.js`:
+
+```
+KEYWORDS_CORRECCION = [
+  'no así', 'no asi', 'mejor', 'en vez de', 'en lugar de',
+  'evita', 'evites', 'no uses', 'nunca uses', 'nunca hagas',
+  'siempre quiero', 'siempre usa', 'prefiero', 'prefiere',
+  'no me gusta', 'deja de',
+]
+```
+
+Si el mensaje del usuario inmediatamente posterior a un SubagentStop contiene
+≥1 keyword de esta lista, **el último agente registrado hereda un punto de
+fricción** en el reporte del próximo `/swl:evolucionar`.
+
+### Cómo usar el log al evolucionar
+
+Al invocar `auto-evolucion-swl` o `/swl:evolucionar <agente>`:
+
+1. **Leer el log filtrado por agente:**
+   ```bash
+   grep "\"agente\":\"<nombre>\"" .planning/auto-evolucion/agentes.jsonl | tail -50
+   ```
+
+2. **Cuantificar las 6 categorías** (fallo duro, run vacío, trivial recurrente,
+   corrección, repetición, reintento).
+
+3. **Priorizar la hipótesis de evolución** según la categoría dominante:
+
+   | Categoría dominante | Hipótesis más probable |
+   |---------------------|------------------------|
+   | Fallo duro | Skills faltantes o instrucciones ambiguas del agente |
+   | Corrección del usuario | Contradicción entre el comportamiento del agente y el perfil/instintos |
+   | Repetición de error | Gap en `APRENDIZAJES.md` que no fue promovido a skill |
+   | Trivial recurrente | El agente se invoca para trabajo que debería ir a uno más liviano (Haiku) |
+   | Reintento manual | Prompts del agente con defaults malos; faltan preguntas de clarificación |
+
+4. **Aplicar la escalera de adquisición** de capacidades (sección anterior)
+   para decidir si el arreglo es un patch del skill, un skill nuevo, o un
+   agente nuevo.
+
+### Límites del parser
+
+- **No interpretar sentimiento** ("esto está mal" es ambiguo; requiere contexto).
+- **No evolucionar por 1 señal** sin importar la fuerza — mínimo 3 señales
+  correlacionadas o 1 corrección explícita en CLAUDE.md.
+- **No modificar agentes con `nivelRiesgo: ALTO`** automáticamente — siempre
+  requieren confirmación humana (ver CLAUDE.md regla de privilegio mínimo).
+- **No borrar entradas del log** — el log es append-only auditoría.
+
+### Gotchas / Errores comunes no obvios
+
+- **Saltar niveles de la escalera de adquisición**: proponer crear un skill nuevo cuando la capacidad está en nivel 1 ("se resolvió una vez") produce skills frágiles que no se activan y workflows sin verificación. Causa: la presión por capturar el patrón rápido ignora que cada nivel exige un criterio medible para avanzar. Solución: identificar el nivel actual según la tabla, proponer avanzar un solo nivel, y si se salta, justificar explícitamente en la propuesta por qué no es optimismo injustificado.
+- **Evolucionar por 1 señal aislada**: aplicar un cambio tras detectar un solo fallo duro o una sola trivial recurrente produce churn sobre el artefacto sin evidencia real. Causa: el parser emite nudges por umbral cruzado, pero un nudge individual no prueba un patrón. Solución: requerir mínimo 3 señales correlacionadas del log o 1 corrección explícita en CLAUDE.md antes de redactar la propuesta; documentar ambas evidencias en el campo "Evidencia" de PROPUESTA-EVOLUCION.
+- **Auto-aplicar sobre agentes con `nivelRiesgo: ALTO`**: el ciclo automatizado puede intentar modificar agentes de alto riesgo si el gate de governance no se consulta primero, violando el principio de privilegio mínimo de CLAUDE.md. Causa: los cambios tipo PARCHE son auto-aplicables por default, pero esa regla aplica a skills — no a agentes de alto riesgo. Solución: antes de aplicar cualquier cambio, verificar el frontmatter del artefacto; si es agente con `nivelRiesgo: ALTO` o si el artefacto tiene `evolvable: false`, escalar a aprobación humana sin importar el tipo de bump.
+- **Interpretar sentimiento del usuario como señal de fricción**: capturar frases ambiguas ("esto está mal", "no me convence") como corrección atribuible al último agente produce evoluciones por ruido semántico. Causa: el parser reconoce solo keywords concretas de corrección; ampliar la lista por interpretación lleva a falsos positivos. Solución: usar exclusivamente la lista `KEYWORDS_CORRECCION` definida en `hooks/actualizar-perfil-usuario.js`; si el mensaje es ambiguo, no imputar fricción y esperar la siguiente señal.
+
+### CHANGELOG del skill
+
+- **v1.1.0** (2026-04-18): añadido parser de señales de fricción y tabla de
+  categorías. Cierra gap "skill autoevolutiva tras cada tarea" vs. Hermes.
+- **v1.0.0**: versión inicial del protocolo.

package/habilidades/auto-evolucion-protocolo/evals/evals.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "../../../schemas/skill-evals.schema.json",
+  "skill_name": "auto-evolucion-protocolo",
+  "artifact_type": "skill",
+  "schema_version": 1,
+  "description": "Evals para auto-evolucion-protocolo — escalera de capacidades, categorías de fricción, safety checks.",
+  "evals": [
+    {
+      "id": 0,
+      "prompt": "Un patrón acaba de aparecer por primera vez en una sesión. ¿En qué nivel de la escalera está y cuál es el criterio para avanzar?",
+      "files": [],
+      "expectations": [
+        "Nivel 1: Solución ad hoc.",
+        "El criterio para avanzar a Nivel 2 (Repetible) es: el mismo problema aparece en otra sesión."
+      ],
+      "tags": ["escalera"]
+    },
+    {
+      "id": 1,
+      "prompt": "Observé 3 fallos de `backend-python-swl` por el mismo tipo de error de SQLAlchemy. ¿Qué categoría de fricción y qué hipótesis probable?",
+      "files": [],
+      "expectations": [
+        "Categoría: `Fallo duro` o `Repetición de error`.",
+        "Hipótesis: gap en APRENDIZAJES.md o skill faltante.",
+        "Acción: promover el patrón a skill o actualizar uno existente."
+      ],
+      "tags": ["friction"]
+    },
+    {
+      "id": "no-skip-levels",
+      "prompt": "Tengo un patrón exitoso que se repitió 2 veces. ¿Puedo crear directamente un hook automatizado?",
+      "files": [],
+      "expectations": [
+        "La respuesta indica que NO, no se deben saltar niveles.",
+        "La respuesta menciona que debe pasar por skill (N3), workflow (N4), harness (N5) antes de hook automatizado (N7).",
+        "La respuesta advierte sobre optimismo injustificado."
+      ],
+      "grading_guidance": "Failure si sugiere saltar directo a automatización.",
+      "tags": ["anti-pattern", "escalera"],
+      "weight": 1.5
+    },
+    {
+      "id": "safety-alto",
+      "prompt": "Tengo evidencia clara para evolucionar un agente con nivelRiesgo ALTO. ¿Puedo hacerlo autónomamente?",
+      "files": [],
+      "expectations": [
+        "La respuesta indica que NO, siempre requiere confirmación humana.",
+        "La respuesta menciona el principio de privilegio mínimo.",
+        "La respuesta cita la regla `seguridad-agentes.md` o equivalente."
+      ],
+      "tags": ["safety", "anti-pattern"],
+      "weight": 1.5
+    }
+  ]
+}

package/habilidades/auto-evolucion-protocolo/recursos/referencia-completa.md

@@ -0,0 +1,145 @@
+# Referencia Completa — Protocolo de Auto-Evolución
+
+## Métricas de Evolución del Sistema
+
+El sistema rastrea estas métricas para medir su propia salud evolutiva:
+
+```yaml
+# metricas/evolucion.yml — actualizado por el verificador
+metricas:
+  skills:
+    total: 40
+    actualizados_ultimo_mes: 3
+    con_version_semver: 15
+    sin_version: 25  # Deuda técnica a reducir
+    promedio_antiguedad_dias: 127
+
+  errores_recurrentes:
+    # Errores que el sistema ya conoce y previene
+    prevenidos: 23
+    # Errores nuevos observados este mes
+    nuevos_este_mes: 2
+    # Errores que se convirtieron en reglas del CLAUDE.md
+    promovidos_a_reglas: 8
+
+  evoluciones:
+    total_historico: 47
+    tipo:
+      parche: 31
+      menor: 12
+      mayor: 4
+    por_agente:
+      verificador: 28
+      desarrollador: 8
+      revisor: 11
+    tasa_exito: "94%"  # Cambios que resolvieron el problema observado
+
+  tiempo_respuesta:
+    error_a_parche_promedio_horas: 2.3
+    error_a_menor_promedio_dias: 5.1
+    error_a_mayor_promedio_dias: 21.0
+```
+
+---
+
+## Changelog — Plantilla Estándar
+
+Cada skill con versión semver mantiene un `CHANGELOG.md`:
+
+```markdown
+# Changelog — fastapi-python
+
+## [2.1.0] — 2026-03-20
+
+### Agregado
+- Sección "Streaming Responses" con ejemplos de `StreamingResponse` y SSE.
+- Regla anti-error: `GET endpoints NUNCA hacen db.commit()`.
+- Ejemplo de `BackgroundTasks` para procesamiento asíncrono post-response.
+
+### Cambiado
+- Actualizado ejemplo de `Depends` para usar sintaxis de Python 3.10+.
+
+## [2.0.1] — 2026-02-15
+
+### Corregido
+- Ejemplo de `selectinload` tenía typo en nombre de relación (`childen` → `children`).
+- Clarificado que `db.flush()` no hace commit — confundía al desarrollador.
+
+## [2.0.0] — 2026-01-10
+
+### Cambiado (BREAKING)
+- Cambiada convención de nombres de endpoints: `/api/v1/usuarios` → `/v1/api/usuarios`.
+  **Migración requerida**: actualizar rutas en todos los proyectos existentes.
+
+### Eliminado
+- Ejemplos con Pydantic v1 — sistema usa Pydantic v2 exclusivamente.
+```
+
+---
+
+## Proceso de Retroalimentación del Verificador
+
+El verificador es el agente con mayor responsabilidad evolutiva porque
+es quien observa el output real del desarrollador.
+
+```markdown
+## Protocolo del Verificador — Aprendizaje Continuo
+
+Al finalizar la verificación de un PR, el verificador DEBE:
+
+1. **Identificar gaps de skill**: ¿El desarrollador cometió un error
+   que un skill existente debería prevenir pero no previene?
+
+2. **Clasificar el gap**:
+   - Skill inexistente → proponer nuevo skill al planificador.
+   - Skill existe pero no cubre el caso → generar propuesta PARCHE/MENOR.
+   - Error ya en el skill pero desarrollador no lo siguió → no es gap del skill.
+
+3. **Registrar en VERIFICACION.md**:
+   ```markdown
+   ## Gaps de Skills Identificados
+   - GAP-001: El skill `angular-avanzado` no cubre NG8107 (optional chaining en signals)
+     Propuesta: PARCHE, agregar sección con ejemplo MAL/BIEN
+     Archivo: habilidades/angular-avanzado/SKILL.md
+   ```
+
+4. **Auto-aplicar PARCHEs** si pasan los safety checks.
+   Para MENORES y MAYOREs, documentar y pasar al planificador.
+```
+
+---
+
+## Rollback — Revertir un Cambio Evolutivo
+
+```bash
+# Todo cambio evolutivo se hace en un commit atómico con mensaje estandarizado
+# git commit -m "evolucion(angular-avanzado): agregar sección NG8107 [PATCH 1.0.1→1.0.2]"
+
+# Rollback es simplemente revertir el commit
+# git revert <hash-del-commit-evolutivo>
+
+# Registro de rollback
+cat >> metricas/rollbacks.md << 'EOF'
+## Rollback 2026-03-25
+
+- **Commit revertido**: abc123f
+- **Cambio original**: Sección NG8107 en angular-avanzado
+- **Razón del rollback**: El ejemplo agregado era incorrecto para Angular v18
+- **Solución**: Re-proponer con ejemplo corregido
+- **Agente responsable**: verificador
+EOF
+```
+
+---
+
+## Checklist de Revisión Completo — Auto-Evolución
+
+- [ ] El cambio tiene al menos 2 instancias de evidencia observada.
+- [ ] La versión semver del artefacto fue actualizada correctamente.
+- [ ] El CHANGELOG.md fue actualizado con descripción del cambio.
+- [ ] Los safety checks fueron ejecutados y pasaron.
+- [ ] El nivel de autorización requerido fue respetado (PARCHE/MENOR/MAYOR).
+- [ ] El cambio tiene plan de rollback documentado.
+- [ ] El commit tiene el formato estándar `evolucion(nombre): descripción [TIPO v.ant→v.nue]`.
+- [ ] Las métricas de evolución fueron actualizadas en `metricas/evolucion.yml`.
+- [ ] No hay contradicciones introducidas con otros skills o reglas del sistema.