@saulwade/swl-ses 1.6.0 → 1.6.3

package/agentes/sre-swl.md

@@ -15,6 +15,7 @@ permissionMode: acceptEdits
 color: red
 version: 1.0.0
 nivelRiesgo: ALTO
+maxTurnos: 18  # incident response (diagnose → mitigate → verify) + post-mortem + runbooks
 skillsInvocables: [sre-patrones, performance-baseline, monitoring-alertas, checklist-seguridad]
 skillsRestringidos: [frontend-css-swl, mobile-flutter]
 permisosRed: false
@@ -31,6 +32,29 @@ 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."
   - "No invocar para implementar la capa de observabilidad (logs, métricas, trazas) — ese trabajo corresponde a observabilidad-swl."
+strategy: >
+  Confiabilidad como producto, no como overhead. Error budgets sobre 100% uptime
+  imposible. Aprender de incidentes (blameless post-mortems) sobre culpar individuos.
+  Toil ≤50% del trabajo SRE; el resto es ingeniería que elimina toil.
+healthMetrics:
+  - Error budget remanente del trimestre ≥0% (no consumido completo)
+  - Mean Time To Acknowledge (MTTA) de pages ≤5 min en horas críticas
+  - Cobertura de runbooks ≥80% para alertas que paginan
+  - Tasa de incidentes repetidos (mismo root cause en <30 días) <10%
+  - Toil documentado y medido ≤50% del tiempo del equipo SRE
+steering:
+  - "Skill('sre-patrones') antes de definir SLO/SLI nuevos."
+  - "@reglas/observabilidad.md — los SLOs requieren SLIs medibles, no inventados."
+  - "Post-mortems blameless con timeline factual y action items con dueño + fecha."
+  - "Cargar Skill('proceso-ddia-fundamentos') al evaluar tradeoffs Reliability/Scalability/Maintainability."
+hardGuardrails:
+  - "@reglas/seguridad-agentes.md § Recovery Catalog — escalar antes de modificar configuración de producción."
+  - "Chaos experiments en producción requieren plan de aborto y aprobación humana."
+  - "Cambios en alertas que paginan requieren on-call lead notificado."
+  - "Post-mortem de incidente SEV1/SEV2 obligatorio ≤72h del incidente."
+  - "@hooks/audit-trail.js — toda acción SRE sobre producción registrada en audit log."
+fragmentos:
+  - _intent-spec
 ---
 ## Cuándo NO invocarme
 

package/comandos/swl/brainstorm.md

@@ -1,4 +1,5 @@
 ---
+name: swl:brainstorm
 description: Inicia una sesión de brainstorming estructurado para diseñar una feature o solución
 ---
 

package/comandos/swl/compactar.md

@@ -24,7 +24,7 @@ Este comando es diferente de `/swl:checkpoint`: mientras checkpoint guarda estad
 Skill("compactacion-contexto")
 ```
 
-Si no existe, busca alternativas: `Skill("systematic-debugging")` para razonamiento estructurado. Documenta lo que cargaste.
+Si no existe, busca alternativas en `~/.claude/skills/` (skills oficiales de Anthropic) o procede sin skill auxiliar — el algoritmo de 5 fases es zero-deps. Documenta lo que cargaste o que procediste sin skill.
 
 ## Paso 1 — Auditoría del contexto activo
 

package/comandos/swl/discutir-fase.md

@@ -17,13 +17,27 @@ Eres un analista funcional y técnico experto. Tu trabajo es convertir los objet
 
 El argumento `<n>` es el número de la fase a discutir.
 
+## Discovery routing (5 paths) — primer paso antes del cuestionario
+
+Antes del cuestionario adaptativo completo, el agente clasifica la petición en uno de **5 rutas posibles** y ejecuta solo lo relevante. Origen: ADR-0020 sub-fase 1.
+
+| Ruta | Cuándo aplica | Acción |
+|------|--------------|--------|
+| **RUTA_A** — Extender fase existente | La petición agrega tareas a una fase ya planeada. | Saltar cuestionario; cargar el CONTEXTO.md existente y agregar tareas. |
+| **RUTA_B** — Sin fase formal | Fix trivial o tarea de <2 horas sin impacto cross-módulo. | Saltar cuestionario; proceder con `/swl:ejecutar-fase` directamente. |
+| **RUTA_C** — Nueva fase single-scope | Petición nueva, no encaja en fases existentes, single-domain. | Ejecutar cuestionario completo (Bloques 1-4). |
+| **RUTA_D** — Nueva fase multi-domain | Petición nueva, requiere decomposición en sub-tareas paralelas. | Cuestionario completo + planificación de paralelización. |
+| **RUTA_E** — Mixto | La petición combina: extensión + nueva fase + posiblemente fix trivial. | Presentar decomposición propuesta y confirmar antes de proceder. |
+
+El agente identifica la ruta en la primera respuesta al cargar `Skill("discutir-fase")` analizando: la petición textual, el estado de `.planning/HOJA-RUTA.md` y el último `RESUMEN.md`. Solo si la ruta es C o D se ejecuta el cuestionario completo descrito a continuación.
+
 ## Paso 0 — Carga de habilidades
 
 ```
 Skill("discutir-fase")
 ```
 
-Si no existe, intenta `Skill("planificador")` o `Skill("api-design-principles")`. Documenta qué cargaste.
+Si no existe, intenta `Skill("planear-fase")` o `Skill("api-rest-diseno")`. Documenta qué cargaste.
 
 ## Paso 1 — Lectura de contexto previo
 

package/comandos/swl/mapear-codebase.md

@@ -16,7 +16,7 @@ Carga la habilidad de análisis antes de comenzar:
 Skill("mapear-codebase")
 ```
 
-Si no existe en el proyecto, busca alternativas como `Skill("codebase-mapper")` o `Skill("systematic-debugging")`. Documenta qué habilidad cargaste.
+Si no existe en el proyecto, procede sin skill auxiliar — la lógica de mapeo del comando es zero-deps. Documenta que procediste sin skill.
 
 ## Paso 1 — Verificación del entorno
 

package/comandos/swl/nemesis.md

@@ -247,6 +247,35 @@ Cada `evaluacion.json` sigue el schema `nemesis-evaluacion-json` v1.0.0.
 El costo del modo `--remediar` es 3-5× el del modo solo auditar. Es opt-in
 deliberado del usuario, no default.
 
+### Calibración para módulos pequeños con alta densidad de control de flujo
+
+Aunque la tabla estima 12-18 turnos para `--remediar` sobre módulo pequeño
+(< 500 LOC), el valor agregado es desproporcionadamente alto cuando el
+módulo concentra **lógica de control de flujo** (event handlers,
+callbacks, `setTimeout`/`setInterval`, readline, promises, race conditions).
+La densidad de bugs latentes en este tipo de código es alta, y nemesis los
+detecta donde la revisión one-shot no.
+
+**Patrón confirmado en swl-ses v1.6.0** (sesión 2026-05-16): `--remediar`
+sobre `scripts/lib/ui.js` (~300 LOC con spinner + readline + prompts)
+convergió en iter-2 con 15 turnos totales. Iter-1 detectó dos hallazgos
+adicionales que el fix manual no había detectado:
+
+- **F-1 (ALTO)**: listener leak de `process.once('exit')` acumulándose
+  en loops que crean N spinners secuenciales → MaxListenersExceededWarning.
+- **F-2 (MEDIO)**: `preguntarOpcion` llamaba `_pausarSpinnersActivos()`
+  DESPUÉS del primer `console.log` del menú, dejando una ventana donde
+  el tick del spinner sobrescribía la primera línea.
+
+Iter-2 confirmó PASS tras aplicar ambos fixes. Ninguno habría sido
+detectado por `/swl:revisar` o `revisor-codigo-swl` solos — ambos
+requirieron el reasoning iterativo Feynman+State.
+
+**Regla operativa**: tras commits de fix-only en módulos con alta densidad
+de control de flujo (no en módulos CRUD puros), correr `--remediar`
+acotado al módulo. La inversión de 15 turnos típicamente detecta 1-2
+bugs adyacentes que el fix original no cubrió.
+
 ## Ejemplos de invocación
 
 ```bash

package/comandos/swl/planear-fase.md

@@ -21,10 +21,10 @@ Eres el coordinador de planeación SWL. Tu trabajo es orquestar la generación d
 Skill("planear-fase")
 ```
 
-Si no existe, carga `Skill("python-patterns")` si el stack es Python, o `Skill("angular-component")` si el stack es Angular/TS. Siempre carga también:
+Si no existe, carga `Skill("patrones-python")` si el stack es Python, o `Skill("angular-moderno")` si el stack es Angular/TS. Siempre carga también:
 
 ```
-Skill("api-design-principles")
+Skill("api-rest-diseno")
 ```
 
 ## Paso 1 — Verificación de prerrequisitos
@@ -42,6 +42,22 @@ Verifica también:
 - Lee `CLAUDE.md` del proyecto si existe — puede tener restricciones de implementación.
 - Si hay fases anteriores con PLAN.md o RESUMEN.md, léelas para entender patrones establecidos.
 
+### Reglas obligatorias sobre paths y listas en PLAN.md
+
+**Ubicación del PLAN.md** (aprendizaje HIGH 2026-05-18):
+
+- Iniciativas que califican como fase (cualquier trabajo cross-módulo, >50 LOC, multi-archivo, o que produce un release) van a `.planning/fases/0N-PLAN.md` donde N es el siguiente número libre.
+- `.planning/PLAN.md` raíz solo aceptable para hotfixes con un solo commit o ediciones triviales.
+- Al delegar al `planificador-swl`, instruir explícitamente: *"produce `.planning/fases/0N-PLAN.md` donde N es el siguiente número libre visible en `ls .planning/fases/`"*. NUNCA dejar la decisión de path al sub-agente sin esta instrucción.
+- Si la sesión arrancó libre (sin `/swl:discutir-fase`), crear retrospectivamente `0N-CONTEXTO.md` con tabla comparativa, 3 opciones presentadas y decisiones HITL — es válido si documenta honestamente lo que pasó en vivo.
+
+**Listas de agentes/componentes por campo de frontmatter** (aprendizaje HIGH 2026-05-18):
+
+- Cuando un PLAN.md liste componentes por algún campo de frontmatter (nivelRiesgo, evolvable, fase, dominio, etc.), DEBE generarse con `grep -l "^<campo>: <valor>" <dir>/*.md` con **ancla `^` al inicio de línea**.
+- Sin ancla, el grep matchea menciones en el cuerpo (ej: comentarios, secciones de revisión) y devuelve falsos positivos.
+- Si el CONTEXTO recibe la lista en el prompt del usuario, el planificador DEBE verificarla con grep anclado antes de incluirla en PLAN.md.
+- Precedente documentado: PR Opción B (2026-05-18) — CONTEXTO listaba 6 agentes ALTO; verificación real reveló 8 distintos (solo 1 solapamiento). Slice HITL de verificación de scope es OBLIGATORIO antes de F2 si la lista llega del prompt.
+
 ## Paso 2 — Análisis del contexto
 
 Antes de delegar, analiza el CONTEXTO.md de la fase y extrae:

package/comandos/swl/verificar.md

@@ -51,12 +51,12 @@ Skill("verificar-trabajo")
 
 Carga también:
 ```
-Skill("error-handling-patterns")
-Skill("code-review-excellence")
+Skill("manejo-errores")
+Skill("checklist-calidad")
 ```
 
-Si el stack tiene Python: `Skill("python-testing-patterns")`
-Si el stack tiene Angular: `Skill("javascript-testing-patterns")`
+Si el stack tiene Python: `Skill("testing-python")`
+Si el stack tiene Angular: usar `@angular/core/testing` directo (sin skill dedicado)
 
 ## Paso 1 — Determinación del alcance de verificación
 

package/habilidades/aprender-de-git-diff/SKILL.md

@@ -0,0 +1,288 @@
+---
+name: aprender-de-git-diff
+description: >
+  Extrae una lección dominante (máximo 2-3) desde git history — branch diff
+  contra main, últimos N commits, o un commit específico. Mapea los cambios
+  observados a principios de ingeniería catalogados en `~/.claude/rules/` y
+  `reglas/`. Cargar cuando el usuario pide "qué aprendimos aquí", "reflexión
+  sobre el código", "engineering takeaway", o tras un cierre de sesión
+  productiva donde valga capturar el patrón validado. Adaptación de
+  `lesson-learned` de agent-toolkit. NO escribe APRENDIZAJES.md por sí solo
+  — propone la entrada para que el usuario apruebe vía `/swl:aprender`.
+version: "1.0.0"
+herramientasPermitidas: [Read, Grep, Glob, Bash]
+exclusiones:
+  - "No cargar si el rango de análisis son <5 LOC o un solo commit de typo/rename/formato — no hay lección que extraer."
+  - "No cargar para extraer aprendizaje de feedback verbal del usuario; ese flujo es `/swl:aprender` (triggered por feedback, no por git)."
+  - "No cargar para análisis de codebase completo o auditoría — usar `mapear-codebase` o `revisor-codigo-swl`."
+  - "No cargar para sesiones sin commits realizados todavía; primero realizar el trabajo, luego analizarlo."
+evolvable: true
+---
+
+# Habilidad: Aprender desde git diff
+
+## Propósito
+
+Convertir el código que el usuario acaba de escribir en un espejo de los
+principios de ingeniería que ya está aplicando (o que omite). No es una
+lección abstracta — es la lectura del propio diff con vocabulario de
+principios. El skill triggered por git complementa `/swl:aprender`
+(triggered por feedback) cubriendo el vector "el código habla por sí
+mismo".
+
+## Cuándo cargar
+
+- Usuario pregunta "¿qué lección hay aquí?", "¿qué aprendimos?",
+  "engineering takeaway".
+- Tras un cierre de sesión con commits sustantivos donde valga reforzar el
+  patrón validado.
+- Al final de una rama de feature, antes del merge, para capturar el
+  principio dominante.
+- Para revisar el propio trabajo del agente al cierre de un PR.
+
+## Cuándo NO cargar
+
+Listado en `exclusiones` del frontmatter — incluye rangos triviales,
+feedback verbal sin código (esa es `/swl:aprender`), auditoría de codebase
+completo y sesiones sin commits.
+
+---
+
+## Fases del análisis
+
+### Fase 1 — Determinar scope
+
+Preguntar al usuario o inferir del contexto:
+
+| Scope | Comandos git | Cuándo aplicar |
+|---|---|---|
+| Branch feature | `git log main..HEAD --oneline` + `git diff main...HEAD` | Rama no-main (default) |
+| Últimos N commits | `git log --oneline -N` + `git diff HEAD~N..HEAD` | Usuario da rango, o estamos en main (N=5 default) |
+| Commit específico | `git show <sha>` | Usuario referencia commit |
+| Working changes | `git diff` + `git diff --cached` | Usuario dice "estos cambios" antes de commit |
+
+**Default**: si estamos en rama feature, analizar branch vs main. Si en
+main, últimos 5 commits.
+
+### Fase 2 — Recolectar cambios
+
+- `git log` para mensajes de commit (los mensajes contienen intent que el
+  diff puro pierde).
+- `git diff` para los cambios.
+- Si el diff supera 500 líneas: `git diff --stat` primero, luego leer
+  selectivamente los 3-5 archivos con más cambios.
+- **Solo leer archivos cambiados**. No expandir a todo el repo.
+
+### Fase 3 — Analizar y mapear a principios
+
+Identificar el **patrón dominante** — la cosa más instructiva sobre estos
+cambios. Buscar:
+
+- **Decisiones estructurales**: ¿cómo se organizó? ¿por qué esas
+  fronteras?
+- **Trade-offs hechos**: ¿qué se ganó vs sacrificó? (legibilidad vs
+  rendimiento, DRY vs claridad, velocidad vs corrección).
+- **Problemas resueltos**: ¿qué cambió del antes al después?
+- **Oportunidades perdidas**: ¿dónde podría mejorar? (presentar como
+  "la próxima vez, considera...").
+
+**Mapeo a catálogo de SWL** — usar como referencia:
+
+1. `~/.claude/rules/estilo-codigo.md` — DRY, KISS, funciones cortas,
+   early return, sin código muerto.
+2. `~/.claude/rules/arquitectura.md` — SOLID, módulos profundos, DI,
+   separación de concerns, patrones reconocidos.
+3. `~/.claude/rules/pruebas.md` — AAA, factories sobre fixtures, tests
+   deterministas, edge cases.
+4. `~/.claude/rules/seguridad.md`, `seguridad-agentes.md` — OWASP,
+   privilegio mínimo, anti-fallback.
+5. `~/.claude/rules/arreglar-al-detectar.md` — detectar→informar→
+   arreglar, anti-deuda silenciosa.
+6. `reglas/` del proyecto — convenciones locales.
+7. `.planning/APRENDIZAJES.md` — patrones ya validados (no repetir).
+
+Ser **específico**: citar archivo:línea concreto, no afirmaciones vagas.
+
+### Fase 4 — Presentar la lección
+
+Plantilla obligatoria:
+
+```markdown
+## Lección: [Nombre del principio]
+
+**Qué pasó en el código:**
+[2-3 oraciones describiendo el cambio específico, con archivos y commits]
+
+**El principio en acción:**
+[1-2 oraciones explicando el principio de ingeniería, citando la regla
+SWL si aplica: `reglas/X.md § sección`]
+
+**Por qué importa:**
+[1-2 oraciones sobre la consecuencia práctica — qué saldría mal sin esto,
+qué sale bien gracias a esto]
+
+**Para próxima vez:**
+[Una oración accionable y concreta]
+```
+
+Si hay una segunda lección que vale la pena (máximo 2 adicionales):
+
+```markdown
+---
+
+### También digno de mención: [Principio]
+
+**En el código:** [1 oración]
+**El principio:** [1 oración]
+**Para próxima vez:** [1 oración]
+```
+
+### Fase 5 — Propuesta de entrada en APRENDIZAJES.md
+
+Tras presentar la lección al usuario, ofrecer la entrada que se podría
+agregar a `.planning/APRENDIZAJES.md`:
+
+```markdown
+### [YYYY-MM-DD] <Título corto>
+
+**rating**: HIGH / MEDIUM / LOW
+**fuente**: git commits <sha-corto>..<sha-corto>
+**principio**: <referencia a regla SWL>
+
+**Contexto**: <qué hacíamos>
+**Lección aplicada**: <lo extraído>
+**Evidencia**: <archivo:línea principal>
+```
+
+El usuario decide si la entrada se añade vía `/swl:aprender`. Este skill
+**NO escribe directamente APRENDIZAJES.md** — propone, el usuario aprueba.
+
+---
+
+## Qué NO hacer
+
+| Evitar | Por qué | En su lugar |
+|---|---|---|
+| Listar cada principio que vagamente aplica | Abrumador y genérico | Elegir 1-2 más relevantes |
+| Analizar archivos no cambiados | Scope creep | Stick al diff |
+| Ignorar commit messages | Tienen intent que el diff pierde | Leerlos como contexto primario |
+| Consejo abstracto desconectado del código | No accionable | Siempre referenciar archivo:línea |
+| Feedback solo negativo | Desmoralizante | Liderar con qué funciona, luego sugerir |
+| Más de 3 lecciones | Diluye el insight | Una bien fundada vence siete vagas |
+
+---
+
+## Reglas obligatorias
+
+1. **Reflexivo, no prescriptivo**: usar el código del usuario como
+   evidencia primaria. **Por qué**: si el agente da consejo abstracto,
+   no usa el material que ya tiene a la vista — desperdicia la
+   especificidad del diff.
+
+2. **Nunca decir "deberías haber..."**: usar "el enfoque aquí muestra..."
+   o "la próxima vez que enfrentes esto, considera...". **Por qué**:
+   tono de auditor erosiona la conversación; el skill es espejo, no juez.
+
+3. **Si el código es bueno, decirlo**: no toda lección es sobre lo que
+   salió mal. Reconocer patrones buenos los refuerza. **Por qué**:
+   feedback solo negativo desmoraliza y oculta el valor del trabajo
+   completado.
+
+4. **Si los cambios son triviales, decirlo**: "Estos cambios son
+   directos — no hay lección profunda aquí, solo buen mantenimiento".
+   **Por qué**: forzar una lección donde no la hay es ruido.
+
+5. **Específico, no genérico**: cada claim apunta a un cambio concreto
+   de código con archivo:línea o sha. **Por qué**: consejo genérico ya
+   está en las reglas — el valor de este skill es la conexión con el
+   diff concreto.
+
+6. **Una lección dominante, máximo 3**: priorizar. **Por qué**: 7
+   lecciones tibias no equivalen a 1 lección con peso.
+
+7. **No escribir APRENDIZAJES.md directamente**: proponer la entrada,
+   el usuario aprueba vía `/swl:aprender`. **Por qué**: APRENDIZAJES.md
+   es memoria curada del usuario — escritura automática diluye su
+   calidad.
+
+---
+
+## Relación con otras herramientas SWL
+
+- **`/swl:aprender`**: triggered por feedback verbal del usuario.
+  Este skill es triggered por git history. Vectores complementarios.
+- **`revisor-codigo-swl`**: emite veredicto de calidad con score y
+  hallazgos. Este skill extrae **principios**, no hallazgos. Pueden
+  ejecutarse en secuencia.
+- **`/swl:compactar`** + **`/swl:checkpoint`**: cierran sesión preservando
+  estado. Este skill puede invocarse durante el cierre para capturar
+  el aprendizaje antes de compactar.
+- **Skill `meta-skills-estandar`**: catálogo de principios para crear
+  skills. Este skill consume principios para reportar; meta-skills los
+  define para producir.
+
+---
+
+## Ejemplo de uso
+
+Usuario tras una sesión con 4 commits: *"¿qué aprendimos aquí?"*.
+
+Agente carga este skill:
+
+```
+## Lección: Detección y prevención coordinadas
+
+**Qué pasó en el código:**
+Los 4 commits añadieron `tests/_helpers/sandbox.js` con auto-cleanup
+vía `node:test after()` y refactorizaron 16 tests existentes para
+usarlo (PR #35). El bug original — 5,800+ carpetas huérfanas en %TEMP%
+— era acumulación de `fs.mkdtempSync` sin `rmSync`.
+
+**El principio en acción:**
+Fix sistemático en lugar de fix por archivo, alineado con
+`reglas/arquitectura.md § Módulos profundos` (interfaz pequeña,
+implementación rica). El helper expone 3 funciones (`create`, `list`,
+`cleanup`) que ocultan la mecánica de `mkdtempSync`/`rmSync` y el
+registro automático de `after()`.
+
+**Por qué importa:**
+Sin el helper, el patrón se hubiera "olvidado" en el siguiente test
+nuevo — la misma causa raíz se hubiera reintroducido. Con el helper,
+el nuevo test simplemente llama `sandboxes.create()`; el cleanup es
+automático y no negociable.
+
+**Para próxima vez:**
+Al detectar un patrón roto en >3 archivos, pausar el fix por archivo
+y diseñar el helper que lo previene estructuralmente.
+
+---
+
+### También digno de mención: separación FIFO de teardowns
+
+**En el código:** `singleton-guard.test.js` y `nudge-tracker.test.js`
+añadieron `after(() => process.chdir(repoRoot))` ANTES de
+`setupSandboxes()` para que el restore de CWD ocurra antes del
+cleanup, evitando EBUSY en Windows.
+**El principio:** ordering explícito de teardowns donde el cleanup
+depende de estado externo. `node:test` ejecuta los `after()` en FIFO,
+así que el orden de declaración importa.
+**Para próxima vez:** cuando un test cambia CWD, restaurar CWD ANTES
+de cualquier cleanup de filesystem que dependa de ese CWD.
+
+---
+
+**Entrada propuesta para APRENDIZAJES.md** (aprueba con `/swl:aprender` o ignora):
+
+### [2026-05-17] Helper estructural para prevenir patrón roto
+
+**rating**: HIGH
+**fuente**: commits bff27bb..b431360 (PR #35-#36)
+**principio**: `reglas/arquitectura.md § Módulos profundos`
+
+**Contexto**: 16 tests usaban mkdtempSync sin cleanup, acumulando 5,800
+carpetas en %TEMP% tras ~76 corridas.
+**Lección aplicada**: cuando >3 archivos repiten un patrón roto,
+diseñar helper que lo prevenga estructuralmente en lugar de fix por archivo.
+**Evidencia**: `tests/_helpers/sandbox.js:14-30` (3 funciones públicas
+encapsulando 1 cleanup automático).
+```

package/habilidades/aprendizaje-continuo/SKILL.md

@@ -6,7 +6,12 @@ description: >
   tres scopes (proyecto/dominio/global), degradacion automatica por contradiccion,
   promocion a skills/comandos/agentes, evolucion (merge, split, deprecate) y
   proteccion contra contaminacion cross-proyecto.
-version: "1.0.0"
+version: "1.0.1"
+evolved: true
+evolved-from: "1.0.0"
+evolved-at: "2026-05-16"
+evolved-by: "aprender"
+evolved-note: "v1.0.1 (PATCH): nuevo gotcha 'Filtro de exclusión de hooks debe cubrir tests/'. Origen: H3 sesión 2026-05-16 — el extractor de aprendizajes capturaba comentarios JSDoc de un test recién escrito (palabras 'bug', 'patrón', 'fix') y los promovía como entradas truncadas a APRENDIZAJES.md porque PATRONES_ARCHIVO_SWL_EXCLUIDO no incluía tests/."
 herramientasPermitidas: [Read]
 exclusiones:
   - "No cargar para consultar instintos ya cargados en la sesión actual — si el perfil fue leído, re-cargarlo es desperdicio de contexto."
@@ -141,6 +146,7 @@ ver [recursos/referencia-instintos.md](recursos/referencia-instintos.md).
 - **Hooks de observación con exit code != 0 interrumpen la sesión**: el hook `observe-pre.js` lanza una excepción y Claude Code detiene la tarea en curso. Causa: violación de la regla "los hooks de observación NUNCA deben producir exit code != 0". Solución: envolver toda la lógica del hook en `try/catch` y loggear el error al stderr sin propagarlo — la observabilidad nunca debe bloquear el trabajo productivo.
 - **Duplicación de instintos entre `proyecto.yaml` y `APRENDIZAJES.md`**: el mismo anti-patrón existe en ambos canales con información inconsistente. Causa: el instinto se creó manualmente sin verificar si ya había una entrada en APRENDIZAJES.md. Solución: antes de crear un instinto nuevo, ejecutar `memoria-busqueda` para verificar si ya existe en otro canal; si existe, actualizar el canal correcto según `reglas/memoria-consolidada.md`.
 - **Confianza llegando a 0.95 sin revisión humana**: el algoritmo suma 0.1 por evento y el instinto llega a 0.95 sin que nadie lo revise antes de la promoción. Causa: no se aplicó la restricción del último 5% (requiere revisión explícita). Solución: al llegar a 0.90, el sistema debe emitir un checkpoint `human-verify` antes de superar ese umbral — automatizar la vigilancia en `session-end.js`.
+- **Filtro de exclusión de hooks de extracción no cubre `tests/`** [CONFIRMADO 2026-05-16]: el hook `hooks/extraccion-aprendizajes.js` capturaba comentarios JSDoc/docstring de tests recién escritos por el agente y los promovía como entradas truncadas a `APRENDIZAJES.md`. Caso real: al escribir `tests/lib/ui-spinner-prompt.test.js` con un comentario `/** Bug original: cuando un comando arrancaba un spinner y luego (dentro de la lógica...) */`, el hook detectaba la palabra "bug" y promovía una entrada con título cortado a mitad de frase. Causa: `PATRONES_ARCHIVO_SWL_EXCLUIDO` tenía `agentes/`, `habilidades/`, `comandos/swl/`, `hooks/`, `scripts/`, etc., pero **no incluía `tests/`**. Solución: cualquier filtro de exclusión que protege contra ruido auto-referente del agente DEBE incluir explícitamente todos los patrones de tests: `tests/`, `__tests__/`, `spec/`, `*.test.{js,ts,jsx,tsx,mjs,cjs}`, `test_*.py`, `_test.{py,go}`. Los comentarios de un test describen el SUT (System Under Test) — contienen las mismas keywords que un descubrimiento real ("bug", "patrón", "fix") pero NO son descubrimientos. Patrón general: al diseñar un filtro de exclusión para hooks de observación, listar **todas las convenciones de naming de tests del ecosistema target**, no solo los directorios. Verificado en commit `cb4332e` swl-ses v1.6.0.
 
 ## Anti-patrones
 

package/habilidades/diseno-herramientas-agente/SKILL.md

@@ -6,6 +6,7 @@ description: >
   description como prompt engineering, naming MCP y diseno de mensajes de error.
   Cargar cuando se disenan tools para agentes, se configura MCP, se definen
   toolBudget en agentes SWL, o se evalua la coleccion de herramientas de un agente.
+version: "1.1.0"
 herramientasPermitidas: [Read, Grep]
 exclusiones:
   - "No cargar para implementar el hook que ejecuta los tools — este skill diseña la interfaz, no el handler; para implementar PreToolUse o PostToolUse cargar `hooks` o el agente correspondiente."
@@ -197,3 +198,19 @@ Antes de agregar una herramienta nueva a un agente, verificar:
 - **Error `recovery` genérico ("intenta de nuevo")**: el agente reintenta la misma llamada idéntica y falla de nuevo. Causa: el campo `recovery` dice "Reintenta más tarde" sin indicar qué debe cambiar. Solución: el `recovery` debe describir la acción correctiva específica ("Verificar que el archivo existe antes de llamar", "Reducir el campo `limit` a menos de 100").
 - **Naming MCP sin prefijo de servidor**: la tool `buscar_documentos` de un MCP server colisiona con otra tool local del mismo nombre. Causa: no seguir el formato `ServidorMCP:nombre_tool`. Solución: en MCP servers siempre usar `NombreServidor:accion_sustantivo`; el `:` no es opcional aunque el servidor solo tenga una tool.
 - **toolBudget `complex: 35` ignorado porque el agente no lo valida**: el orquestador asigna una tarea simple a un agente que usó 42 tool calls. Causa: `toolBudget` solo es efectivo si el hook de validación o el agente lo respeta activamente; declararlo en frontmatter sin lógica que lo cumpla no tiene efecto. Solución: verificar que el agente o el hook de control de presupuesto lee el campo `toolBudget` del frontmatter antes de asumir que el límite se aplicará automáticamente.
+
+- **Parser YAML inline zero-deps no maneja CRLF / comentarios / comillas** [CONFIRMADO x2]: hooks que parsean frontmatter de Markdown con regex inline (`/^---\n([\s\S]+?)\n---/`) fallan silenciosamente en Windows con `autocrlf=true`. Caso 2026-04-20: `auditar-skills-gaps.js` reportaba 133/143 falsos positivos. Caso 2026-05-18: `validar-intent-spec.js` no detectaba ningún agente, exit 0 silent sin emitir nudges. Tres reglas obligatorias para parsers YAML inline en hooks/scripts SWL:
+  1. **Normalizar line endings**: `contenido = contenido.replace(/\r\n/g, '\n').replace(/\r/g, '\n')` ANTES del regex.
+  2. **Strip comentarios inline**: `nivelRiesgo: ALTO  # ejemplo` → extraer `"ALTO"`, no `"ALTO  # ejemplo"`. Helper `limpiarValorYaml(crudo)` que aplica `crudo.match(/^(.*?)(?:\s+#.*)?$/)[1]`.
+  3. **Strip comillas wrapping**: `nivelRiesgo: "ALTO"` → extraer `"ALTO"`, no `'"ALTO"'`. Helper aplica `slice(1,-1)` si empieza y termina con `"` o `'`.
+
+  Considerar centralizar `limpiarValorYaml()` en `hooks/lib/yaml-mini.js` para reutilización. Causa: hookear los 3 detalles uno por uno cuando aparecen bugs en producción es costoso; aplicar las tres reglas desde el inicio del parser inline.
+
+- **Hook validador no-funcional acumula bugs latentes silenciosamente**: cuando un hook PostToolUse warn-only (`blocking: false`) deja de funcionar por un bug interno (regex roto, parser incompleto, ruta excluida que matchea por error), no hay diferencia observable entre "hook OK, nada que reportar" y "hook roto, ningún reporte posible". Defensa en profundidad rota silenciosamente. Caso: F2 de PR #39 refactorizó 8 agentes ALTO bajo nueva regla obligatoria; 5 omitieron `maxTurnos`, hook debía emitirlos como `intent-spec-incomplete`, pero estaba roto por CRLF. Las 5 omisiones persistieron en main sin alarma.
+
+  Tres mitigaciones obligatorias al crear un hook nuevo de validación:
+  1. **Smoke test end-to-end tras creación**: alimentar input que debería emitir nudge → verificar que `nudges.jsonl` contiene la entrada esperada (no solo `exit 0`).
+  2. **Validador 1-shot tras refactor masivo**: si N componentes se refactorizan bajo nueva regla obligatoria, ejecutar el validador 1-shot contra cada uno antes de declarar completo.
+  3. **Canary mode opcional**: emitir 1 nudge inicial "hook activo, monitoreando" la primera vez que se ejecuta tras instalación/actualización, para confirmar que el hook corre en la plataforma del usuario.
+
+- **Smoke tests de hooks JSON-in en Windows con `echo` shell pierden escapes**: al debuguear hooks que reciben JSON en stdin, NUNCA construir el JSON con `echo` o heredoc desde Git Bash. Caso 2026-05-18: `echo '{"file_path":"D:\\Python\\swl-ses\\..."}'` producía JSON con `D:Python...` (sin backslashes) — los `\\` se comían en shell expansion. El hook recibía path inválido, no encontraba archivo, exit 0 silent. Tomó 3 intentos identificar que el problema era el shell, no el hook. **Patrón correcto**: escribir el JSON con un script Node standalone (`require('fs').writeFileSync('input.json', JSON.stringify({...}))`) y luego `node hook.js < input.json`. JSON correctamente escapado garantizado.