@saulwade/swl-ses 1.9.0 → 2.1.0

package/reglas/git-coauthor.md

@@ -0,0 +1,100 @@
+# Regla: Sin co-autores en commits
+
+Esta regla es OBLIGATORIA y aplica a TODOS los proyectos del usuario sin excepción.
+Tiene prioridad sobre el template por defecto del CLI de Claude Code.
+
+---
+
+## Regla
+
+Los commits que Claude genere en cualquier proyecto del usuario **NO deben incluir
+ninguna línea de atribución a Claude, Anthropic, ningún modelo de IA, ni ningún
+co-autor**. El único autor de los commits es **Saúl Wade**.
+
+Específicamente, NO incluir en el mensaje de commit:
+
+- `Co-Authored-By: Claude ...`
+- `Co-Authored-By: <cualquier modelo>`
+- `🤖 Generated with [Claude Code](https://claude.com/claude-code)`
+- `Generated by Claude`
+- Ninguna otra línea de atribución a IA o co-autor automático
+
+Esta regla **sobrescribe** las instrucciones por defecto del CLI de Claude Code
+que sugieren agregar `Co-Authored-By: Claude Opus ...` al final del mensaje.
+
+---
+
+## Cómo aplicar
+
+### En commits con `git commit -m`
+
+```bash
+# CORRECTO
+git commit -m "feat(auth): agregar validación PKCE en flujo OAuth2"
+
+# INCORRECTO
+git commit -m "$(cat <<'EOF'
+feat(auth): agregar validación PKCE en flujo OAuth2
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+EOF
+)"
+```
+
+### En commits con HEREDOC y mensaje extenso
+
+El cuerpo del commit puede ser tan extenso como la regla `git-workflow.md` lo
+justifique, pero **sin** el bloque de atribución al final:
+
+```bash
+git commit -m "$(cat <<'EOF'
+fix(facturas): corregir cálculo de IEPS para tasa cero
+
+El cálculo previo aplicaba la tasa estándar en productos con
+tasa IEPS = 0%, generando totales inflados.
+
+Refs #234
+EOF
+)"
+```
+
+### En Pull Requests
+
+Mismo principio aplica al body de PRs creados con `gh pr create`. El template
+del CLI sugiere terminar con:
+
+```
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+```
+
+**NO incluir esa línea**. El body del PR cierra con la sección de Test plan
+o las referencias a issues.
+
+---
+
+## Excepciones
+
+- **Co-autores humanos reales**: si en algún proyecto futuro hay otros desarrolladores
+  haciendo pair programming con Saúl, sus líneas `Co-Authored-By:` con email humano
+  son válidas. La regla aplica solo a atribuciones a IA/modelos.
+- **Cuando el usuario pida explícitamente** la atribución para un commit puntual
+  (caso muy raro). En ese caso ejecutar lo que pide y registrar la excepción en
+  el commit.
+
+---
+
+## Origen
+
+Esta regla se promueve a global el 2026-05-09 tras detectar que la misma
+preferencia aparecía duplicada en al menos 2 proyectos:
+
+- `D--Python-swl-ses/memory/feedback_sin_coautores.md` (2026-04-18)
+- `D--Python-generacion-informes/memory/feedback_no_coauthor_in_commits.md`
+
+La duplicación cross-proyecto es señal inequívoca de preferencia transversal
+del usuario. La instrucción del CLI Claude Code que sugiere agregar
+`Co-Authored-By: Claude` queda explícitamente sobreescrita por esta regla
+para todos los proyectos del usuario `Saul`.
+
+Los feedbacks per-project quedan deprecados tras esta promoción y deben
+eliminarse de las carpetas `memory/` correspondientes.

package/reglas/gobernanza.md

@@ -31,7 +31,7 @@ Los skills generados por `auto-evolucion-swl` o `/swl:evolucionar`:
   NUNCA se incorporan directamente al sistema base sin revisión.
 - Requieren validación en al menos 3 sesiones de trabajo independientes
   antes de ser promovidos al perfil `completo`.
-- Deben pasar la verificación de `/swl:salud` sin degradar el score actual.
+- Deben pasar la verificación de `/swl:status salud` sin degradar el score actual.
 - **Gate G8 — evidencia de calidad obligatoria**: antes de mover un skill
   desde `_userland/plugins/` a `habilidades/`, ejecutar
   `/swl:evaluar-skill <nombre>` y exigir badge ≥ **Plata** (score ≥ 70).
@@ -243,7 +243,7 @@ Ante un cambio que degrada el sistema:
   `SWL_DISABLED_HOOKS=nombre-hook` sin afectar el resto del sistema.
 - Los agentes nuevos NO reemplazan a los existentes sin un período de transición
   documentado. Durante la transición, ambas versiones coexisten.
-- Si `/swl:salud` baja su score tras un cambio: revertir antes de continuar.
+- Si `/swl:status salud` baja su score tras un cambio: revertir antes de continuar.
 
 ### Freeze de cambios pre-release
 
@@ -251,7 +251,7 @@ Durante las 24 horas previas a un release:
 
 - Solo se permiten bug fixes críticos (PATCH).
 - No se agregan features ni reglas nuevas.
-- El comando `/swl:salud` debe pasar sin advertencias antes de publicar.
+- El comando `/swl:status salud` debe pasar sin advertencias antes de publicar.
 
 ---
 
@@ -275,6 +275,6 @@ Los plugins instalados via `/swl:plugins install` tienen restricciones adicional
 - [ ] Ninguna supresión de hook activa sin justificación documentada
 - [ ] El CHANGELOG.md está actualizado con todos los cambios observables
 - [ ] Los schemas de validación pasan para todos los manifiestos modificados
-- [ ] El comando `/swl:salud` pasa sin errores ni advertencias críticas
+- [ ] El comando `/swl:status salud` pasa sin errores ni advertencias críticas
 - [ ] La versión en `package.json` refleja el tipo de cambio realizado
 - [ ] Los plugins de terceros instalados siguen siendo compatibles con la versión nueva

package/reglas/hooks.md

@@ -1,3 +1,9 @@
+---
+paths:
+  - "**/*.tsx"
+  - "**/*.jsx"
+  - "**/next.config.{js,mjs,ts}"
+---
 # Regla: Hooks de Pre-commit y CI — Next.js
 
 Los hooks de pre-commit y las verificaciones de CI detectan los errores más

package/reglas/intent-engineering.md

@@ -1,3 +1,7 @@
+---
+paths:
+  - "**/agentes/*.md"
+---
 # Regla: Intent Engineering para agentes ALTO riesgo
 
 Esta regla es **OBLIGATORIA** y aplica al crear, modificar o promover agentes

package/reglas/markitdown.md

@@ -1,3 +1,11 @@
+---
+paths:
+  - "**/*.docx"
+  - "**/*.xlsx"
+  - "**/*.xls"
+  - "**/*.pptx"
+  - "**/*.ipynb"
+---
 # Regla: Lectura de documentos Office y Jupyter con MarkItDown
 
 Esta regla aplica cuando un agente necesita **leer el contenido** de un archivo

package/reglas/memoria-consolidada.md

@@ -160,7 +160,7 @@ const conFeedback = applyFeedback(instinto, 'helpful');
 ```
 
 **Cuándo recomputar**:
-- `/swl:salud` reporta instintos con `effective_confidence < 0.3` para revisión.
+- `/swl:status salud` reporta instintos con `effective_confidence < 0.3` para revisión.
 - `hooks/degradacion-instintos.js` puede marcar `status_proposed: degraded`
   cuando `shouldAutoDeprecate(instinto)` devuelve `true`.
 - `bootstrap-instintos.js` emite los nuevos instintos con `decay_half_life_days: 90`,

package/reglas/monitor-ci.md

@@ -0,0 +1,309 @@
+---
+paths:
+  - "**/.github/workflows/**"
+---
+# Regla: Monitor de CI tras push
+
+Esta regla es OBLIGATORIA para todo proyecto del usuario que use GitHub
+Actions (presencia de `.github/workflows/`). Aplica tras cada `git push` a la
+rama principal o a una rama con CI activo.
+
+---
+
+## Principio
+
+> Tras cualquier push que dispare workflows de CI, **arma un Monitor que
+> emita una notificación cuando cada workflow termine** (success o failure)
+> en lugar de pollear con `sleep` o esperar que el usuario pregunte.
+
+El Monitor de Claude Code permite reaccionar inmediatamente a fallos sin
+bloquear la conversación: si un workflow falla, el monitor lo emite como
+evento y Claude diagnostica/arregla sin esperar input. Si todo pasa, Claude
+puede continuar trabajando en paralelo.
+
+---
+
+## Cuándo armar el Monitor
+
+OBLIGATORIO armarlo:
+
+- Tras `git push` a rama con workflows activos.
+- Tras crear un PR con CI requerido (cuando GitHub corre los checks).
+- Tras `gh workflow run` manual.
+- Cuando el usuario pide "verifica el CI" sin más detalle.
+
+NO armarlo cuando:
+
+- El push fue a una rama sin workflows activos para esa rama.
+- Es un push de solo documentación que no dispara workflows (verificar el
+  filtro `paths:` del workflow primero).
+- El usuario explícitamente dijo "no monitorees" o "termina aquí".
+
+---
+
+## Patrón estándar del comando
+
+Plantilla para la herramienta `Monitor` de Claude Code. **Usa el `--jq`
+integrado de `gh` (NO `| jq`)** para evitar dependencia externa — `jq` no
+viene preinstalado en Windows + Git Bash, y `gh --jq` funciona idéntico
+sin requerir instalación adicional. Tampoco usa `2>/dev/null` para que
+errores reales del shell (PATH, `cd` fallido) se vean en stdout y aborten
+el monitor en lugar de hacerlo expirar silenciosamente.
+
+```bash
+prev=""
+while true; do
+  cur=$(cd PROJECT_PATH && gh run list --branch BRANCH --limit N \
+    --json status,conclusion,name,headSha \
+    --jq '.[] | "\(.headSha[0:7]) | \(.name): \(.status)/\(.conclusion // "pending")"' \
+    | sort)
+  comm -13 <(echo "$prev") <(echo "$cur")
+  prev=$cur
+  if cd PROJECT_PATH && gh run list --branch BRANCH --limit N \
+       --json status \
+       --jq 'all(.[]; .status == "completed")' | grep -q true; then
+    break
+  fi
+  sleep 25
+done
+```
+
+**Variables a sustituir:**
+
+| Variable | Valor |
+|----------|-------|
+| `PROJECT_PATH` | Working directory del proyecto (ej: `D:/Python/sigm`) |
+| `BRANCH` | Rama del push (`main`, feature branch, etc.) |
+| `N` | Cantidad de workflows que dispara ese push (3 si son frontend+backend+security; 4 si incluye database; etc.) |
+
+**Argumentos típicos para `Monitor`:**
+
+```jsonc
+{
+  "description": "CI commit <hash-corto> (<contexto>) — sale cuando los N workflows finalizan",
+  "timeout_ms": 600000,        // 10 min — suficiente para la mayoría de CIs
+  "persistent": false,         // false = sale al completar todos
+  "command": "<plantilla arriba>"
+}
+```
+
+Para CIs largos (>10 min), subir `timeout_ms` a 1200000 (20 min) o
+1800000 (30 min). Máximo soportado: 3600000 (60 min).
+
+---
+
+## Cómo funciona
+
+- `gh run list --branch BRANCH --limit N` devuelve los N runs más recientes
+  de esa rama (los recién disparados por tu push aparecen en orden).
+- `--jq '...'` (integrado en `gh`, NO el binario `jq` externo) formatea
+  `sha-corto | name: status/conclusion` por línea. Equivalente a `| jq`
+  pero sin dependencia externa.
+- `comm -13` emite solo las líneas NUEVAS respecto a la iteración anterior
+  (cada vez que un workflow cambia de estado, sale como notificación).
+- El segundo bloque verifica con `--jq 'all(.[]; .status == "completed")'`
+  + `grep -q true` si todos los workflows terminaron — sale del loop.
+- El loop sale cuando todos los workflows están en estado `completed`.
+
+Cada cambio de estado genera **una notificación al chat**, así que recibes
+eventos como:
+
+```
+ee6e03e | Frontend CI: in_progress/pending
+ee6e03e | Backend CI: completed/success
+ee6e03e | Security: completed/success
+```
+
+cuando el primer workflow se mueve de `pending` a `in_progress`, otro a
+`success`, etc.
+
+### Por qué `gh --jq` y no `jq` externo
+
+El comando original usaba `| jq` y expiraba silenciosamente en sistemas
+Windows sin `jq` instalado: el pipe a `jq` (que no existe) hacía que `$cur`
+quedara vacío, `comm -13` no emitía deltas y el check de "todos completed"
+siempre fallaba → loop dormía hasta timeout sin notificar nada. Caso real
+(SIGM, 2026-05-12): dos monitores consecutivos expiraron sin un solo evento;
+diagnóstico reveló `jq: command not found` en Git Bash de Windows.
+
+`gh --jq` está embebido en el binario de `gh` (que ya es requisito), aplica
+la misma sintaxis y funciona idéntico en Windows, macOS y Linux sin
+instalaciones adicionales. **Esta es la forma recomendada — usa el flag
+integrado siempre, salvo que tengas razón fuerte para depender de `jq`
+externo (filtros muy complejos que solo cubre el binario completo).**
+
+---
+
+## Acciones tras evento del Monitor
+
+1. **Si todos terminan en `success`**: continuar con el siguiente paso del
+   plan (commit nuevo, fase nueva, etc.). No pedir confirmación al usuario
+   para cosas obvias.
+2. **Si alguno termina en `failure`**: descargar log con
+   `gh run view <run-id> --log-failed` y diagnosticar inmediatamente.
+   Aplicar la regla `arreglar-al-detectar.md`: detectar → informar →
+   arreglar en mismo turno.
+
+   En proyectos con swl-ses instalado (presencia de `agentes/gh-fix-ci-swl.md`),
+   el camino canónico para cerrar el ciclo failure → fix → re-push → green
+   es invocar el agente **`gh-fix-ci-swl`** (HITL approval obligatorio antes
+   de aplicar el fix; max 3 iteraciones; `maxTurnos: 12`). El agente carga
+   el `Skill("build-errors-<lang>")` correspondiente automáticamente. Si el
+   error es del workflow YAML mismo (secret, action, syntax), delega a
+   `devops-ci-swl`. Si el error es local (no específico de CI), prefiere
+   `resolutor-build-swl`. Origen: ADR-0029 (swl-ses).
+
+3. **Si el monitor expira (`timeout_ms`)**: re-armar con timeout mayor o
+   verificar manualmente con `gh run list`.
+
+---
+
+## Anti-patrones a evitar
+
+- `sleep N && gh run list` — bloquea la conversación, no recibe eventos.
+- Polling manual con múltiples `Bash` calls separadas.
+- Arrancar el siguiente trabajo sin saber si el CI pasó (riesgo de
+  acumular commits sobre código roto).
+- Olvidar el monitor tras un push y que el usuario tenga que recordártelo.
+
+---
+
+## Antes de declarar "CI verde" — verificación obligatoria por SHA
+
+Esta sección formaliza la regla post-mortem (L-124, SIGM Sub-fase 5c, 2026-05-11):
+reportar al usuario "CI verde" sin verificar cada workflow individualmente es
+**falsificación de estado**. Un monitor expirado, un commit donde un workflow
+no se disparó, o asumir "verde por default" llevan a declarar saludable un
+sistema que está roto.
+
+### Checklist obligatorio antes de afirmar "CI verde"
+
+1. **Listar todos los workflows del SHA específico**:
+   ```bash
+   # Forma recomendada — gh --jq integrado, sin jq ni python externos:
+   gh run list --branch main --limit 8 \
+     --json status,conclusion,name,headSha \
+     --jq '.[] | "\(.headSha[0:7]) | \(.name): \(.status)/\(.conclusion // "pending")"'
+
+   # Fallback con Python si necesitas filtrar/agrupar por SHA en cliente:
+   gh run list --branch main --limit 20 --json status,conclusion,name,headSha \
+     | python -c "import sys,json; runs=json.load(sys.stdin); sha='ee6e03e'; \
+       [print(f'{r[\"name\"]}: {r[\"status\"]}/{r.get(\"conclusion\") or \"pending\"}') \
+        for r in runs if r['headSha'].startswith(sha)]"
+   ```
+
+2. **Confirmar `conclusion=success` para cada workflow aplicable**:
+   - Cada workflow tiene `paths:` distintos en `on:`. Si el commit solo toca
+     `frontend/`, **NO** se dispara Backend CI — eso es comportamiento correcto,
+     no fallo. Pero un workflow que SÍ debió dispararse y NO aparece en la
+     lista por el SHA es señal de mala configuración: investigar.
+   - **NUNCA** asumir verde por ausencia. La ausencia significa "no se ejecutó",
+     no "pasó".
+
+3. **NO interpretar Monitor expirado como verde**:
+   - El Monitor de Claude Code emite `[Monitor timed out — re-arm if needed.]`
+     cuando el timeout vence antes de que todos los workflows finalicen.
+   - **Timeout ≠ success**. Equivale a "estado desconocido al momento del corte".
+   - Re-armar el Monitor con timeout mayor, O verificar manualmente con
+     `gh run list --commit <sha>`.
+
+4. **Si algún workflow está en `failure` o `cancelled`**:
+   - Bajar el log con `gh run view <run-id> --log-failed` y diagnosticar.
+   - NO declarar verde hasta que el workflow fallido tenga su propio
+     `conclusion=success` en un commit posterior que lo arregle.
+
+5. **Reportar al usuario el estado exacto por workflow**:
+
+   ```
+   CI verde confirmado para commit <sha-corto>:
+   - Backend CI: success ✓
+   - Frontend CI: success ✓
+   - Security: success ✓
+   - E2E Smoke: success ✓
+   (Database CI no se disparó — el commit solo modificó frontend/, comportamiento correcto)
+   ```
+
+   NO usar afirmaciones genéricas como "todo verde" sin enumerar.
+
+### Anti-patrones explícitos
+
+- **Reportar "CI verde" tras `git push` sin esperar finalización**: push retorna
+  exit 0 cuando GitHub aceptó el push, NO cuando los workflows pasaron.
+  Push exitoso ≠ CI verde.
+
+- **Reportar "CI verde" porque el Monitor anterior dijo `success`**: si el
+  Monitor cubre commits A-B pero el último push es C, los workflows de C aún
+  no se evaluaron. Re-armar Monitor o verificar.
+
+- **Reportar "CI verde" para un workflow NUEVO en su primer push**: un workflow
+  nuevo (ej: `e2e.yml`) tiene alta probabilidad de fallar en el primer run
+  porque no se validó localmente. Probar localmente Docker + servicios + tests
+  antes de reportar verde.
+
+- **Asumir Frontend CI siempre verde porque "solo cambié docs"**: si modificas
+  un `.md` dentro de `frontend/`, Frontend CI se dispara igual por el matcher
+  `paths: ['frontend/**']`. Verificar.
+
+- **"CI verde formal" (0 failed) ≠ "tests ejecutaron"**. Un run con 94 passed +
+  5 skipped + 0 failed es verde formal pero zero cobertura de los 5 saltados.
+  Tests con `if (!precondicion) test.skip()` aumentan silenciosamente el conteo
+  de skipped cuando la precondición falla. Comparar el conteo `skipped` entre
+  commits: si aumenta sin causa documentada (tests intencionalmente skipped en
+  el spec), es **regresión silenciosa**, no éxito. Reportar al usuario con cifras:
+  *"verde con N skipped (antes M)"*, no solo "verde". Origen: sesión SIGAF
+  2026-05-13, 7 commits con TC036-TC041 saltando por `actoId=null` antes de
+  detectar el patrón.
+
+- **Fix de seed/fixture roto puede destapar tests "verde por suerte"**. Tests
+  que dependen de datos seedeados saltan por null check cuando el seed falla;
+  el CI los marca skipped y queda verde formal. Al arreglar el seed, los tests
+  vuelven a ejecutar y exponen fallas latentes que estaban camufladas. **Al
+  publicar un fix de seed/fixture, comparar el delta de skipped antes/después**
+  y revisar cada test que pase de SKIPPED a EJECUTANDO — pueden fallar por
+  otras razones acumuladas. Patrón observado en SIGAF 2026-05-13: fix
+  `e6d3f63` (seed grupo20 con `hallazgo.tipo_id`) destapó TC036-TC041 que
+  llevaban meses skipped por falta de actos en BD.
+
+### Origen
+
+Aprendizaje L-124 documentado en SIGM (`.planning/APRENDIZAJES.md`) tras
+Sub-fase 5c (2026-05-11): se reportó "CI verde en cada push" en 7 commits
+seguidos cuando Frontend CI estaba en `failure` desde el commit 4. El usuario
+detectó la inconsistencia al pedir validación adicional ("no podemos avanzar
+de fase hasta no probar que todo esté perfecto"). El Monitor que expiró fue
+interpretado como verde por defecto — equivocadamente.
+
+---
+
+## Excepciones documentadas
+
+- **Repos sin GitHub Actions**: usar el sistema de CI nativo del repo
+  (GitLab CI, CircleCI). Adaptar el comando.
+- **Workflows en forks**: los workflows desde fork PRs no reciben secrets
+  por diseño de GitHub. El monitor sirve igual, pero algunos jobs pueden
+  saltarse.
+- **Rama protegida con auto-merge**: si el repo tiene auto-merge tras CI,
+  el monitor sale al `success` y el merge ocurre automáticamente — no es
+  necesario push adicional.
+
+---
+
+## Origen de esta regla
+
+Promovida a regla global el 2026-05-09 a petición del usuario tras observar
+que el patrón Monitor con `gh run list` + `jq` + `comm -13` se repetía
+con éxito en cada push del proyecto SIGM (~10 invocaciones en sesión 2026-05-09)
+y que ahorraba 5-10 minutos por iteración vs polling manual.
+
+Reemplaza el patrón anterior de "esperar que el usuario reporte el log
+fallido y reaccionar reactivamente" por proactividad.
+
+**Revisión 2026-05-12** (SIGM): migrado de `| jq` a `gh --jq` integrado
+para eliminar dependencia de binario externo. Causa: dos monitores
+consecutivos expiraron silenciosamente en Windows + Git Bash por
+`jq: command not found`, sin emitir un solo evento. Lección: las
+herramientas del Monitor tool corren en sub-shell sin `2>&1` visible —
+cualquier comando faltante hace que el monitor dure hasta timeout sin
+señal de fallo. Diagnóstico: `which jq` antes de armar (debería
+devolver path, no exit 1). `gh --jq` no tiene esta dependencia porque
+está embebido en `gh` (ya requisito previo).

package/reglas/patrones.md

@@ -1,3 +1,9 @@
+---
+paths:
+  - "**/*.tsx"
+  - "**/*.jsx"
+  - "**/next.config.{js,mjs,ts}"
+---
 # Regla: Patrones de Arquitectura — Next.js (App Router)
 
 El App Router de Next.js cambia fundamentalmente dónde y cómo se cargan datos.

package/reglas/registro-componentes-nuevos.md

@@ -1,3 +1,12 @@
+---
+paths:
+  - "**/manifiestos/**"
+  - "**/agentes/**"
+  - "**/habilidades/**"
+  - "**/comandos/**"
+  - "**/hooks/**"
+  - "**/plugin.json"
+---
 # Regla: Registro obligatorio de componentes nuevos en manifiestos
 
 Esta regla es OBLIGATORIA para el proyecto **@saulwade/swl-ses**. Aplica
@@ -26,7 +35,7 @@ propagación de cambios" del `CLAUDE.md` del proyecto.
 
 El costo de registrar es ~30 segundos por componente (3 archivos a editar
 + un comando de regeneración). El costo de no registrar es: instalador roto
-para usuarios del paquete público, `npm run test:all` falla, `/swl:salud`
+para usuarios del paquete público, `npm run test:all` falla, `/swl:status salud`
 reporta degradación, deuda acumulada difícil de detectar tras varios commits.
 
 ---
@@ -41,7 +50,7 @@ listados según el tipo:
 | **Agente** (`agentes/X-swl.md`) | `plugin.json` (array `agents`), `manifiestos/modulos.json` (módulo del dominio), `AGENTS.md` (catálogo), `INVENTARIO.md` (regenerar), `SALUD.md` (regenerar) | `node scripts/generar-inventario.js` |
 | **Skill** (`habilidades/X/SKILL.md`) | `plugin.json` (array `skills`), `manifiestos/modulos.json` (módulo del dominio), `INVENTARIO.md` (regenerar), `CLAUDE.md` § "Sistema de habilidades" si aplica al dominio | `node scripts/generar-inventario.js` |
 | **Comando** (`comandos/swl/X.md`) | `plugin.json` (array `commands` si existe), `manifiestos/modulos.json`, `COMANDOS.md` (descripción), `CLAUDE.md` § tabla de comandos `/swl:*`, `INVENTARIO.md` (regenerar) | `node scripts/generar-inventario.js` |
-| **Hook** (`hooks/X.js`) | `plugin.json` (array `hooks` si existe), `.claude/settings.json` (event+matcher), `manifiestos/hooks-config.json` (event+matcher+blocking), `manifiestos/modulos.json` (ruta del archivo), `INVENTARIO.md`, `SALUD.md` | `node scripts/generar-inventario.js` |
+| **Hook** (`hooks/X.js`) | `plugin.json` (array `hooks` si existe), `.claude/settings.json` (event+matcher), `manifiestos/hooks-config.json` (event+matcher+blocking), `manifiestos/modulos.json` (ruta del archivo **+ toda lib de `scripts/lib/` que el hook requiera, incluidas transitivas** — `grep require` de cada lib antes de registrar), `INVENTARIO.md`, `SALUD.md` | `node scripts/generar-inventario.js` |
 | **Regla** (`reglas/X.md`) | `CLAUDE.md` § tabla de reglas (matcher), `INVENTARIO.md`, `SALUD.md` | `node scripts/generar-inventario.js` |
 | **Schema** (`schemas/X.schema.json`) | `INVENTARIO.md`, `SALUD.md`. Si valida frontmatter de algún componente, actualizar `scripts/validar.js` para que lo use | `node scripts/generar-inventario.js` |
 | **Plantilla** (`plantillas/X.md`) | `manifiestos/modulos.json` si la copia el instalador, `INVENTARIO.md` | `node scripts/generar-inventario.js` |
@@ -115,6 +124,34 @@ invisible para el instalador. Bug histórico v1.4.1 → v1.4.2: el módulo
 `auditoria-profunda` estaba en `modulos.json` pero NO en perfiles → 16
 archivos no llegaban al destino. Mismo patrón.
 
+### La lib `scripts/lib/` del hook viaja sola (no viaja)
+
+Falso y silencioso. Un hook que hace `require('../scripts/lib/X')` necesita que
+`scripts/lib/X.js` esté registrada en el MISMO módulo de `modulos.json` que el
+hook — **incluyendo sus dependencias transitivas** (`grep require` de cada lib
+antes de registrar). Sin eso, en el destino el require lanza `MODULE_NOT_FOUND`
+y el wrapper con que se registran los hooks en settings.json
+(`node -e "try{require(...)}catch(e){if(e.code!=='MODULE_NOT_FOUND')throw e}"`)
+**traga el error**: el hook muere en silencio en TODA instalación destino, sin
+dejar rastro, mientras funciona perfecto en el repo madre.
+
+Caso real (2026-06-12): `check-update.js` requería `scripts/lib/npm-version.js`
+(no distribuida) que a su vez requería `paquetes-conocidos.js` (transitiva,
+tampoco distribuida) — el aviso de nuevas versiones nunca llegó a ningún equipo
+del usuario desde la creación del hook. Fix en commit `12b2a31`.
+
+Tres defensas obligatorias:
+
+1. **Registrar la lib + transitivas** en el módulo del hook (precedente: 16 libs
+   de `scripts/lib/` ya viajan en `hooks-inteligencia` y otros módulos).
+2. **Require tolerante en el hook** (`../scripts/lib/X` → `./lib/X` → null) con
+   **diagnóstico visible throttled** cuando la lib falta — nunca silencio
+   (regla anti-fallback-silencioso de `seguridad-agentes.md`).
+3. **Diagnóstico de "hook que nunca hace nada"**: ejecutar
+   `node -e "require('<ruta-al-hook>')"` SIN el wrapper — el wrapper es un
+   silenciador de `MODULE_NOT_FOUND` por diseño y oculta exactamente esta clase
+   de fallo.
+
 ### "Solo lo uso localmente, no necesito propagarlo"
 
 Falso. swl-ses se distribuye como paquete npm público. Cualquier componente

package/reglas/seguridad-agentes.md

@@ -335,7 +335,7 @@ Precedente: ADR-0002 (skills) y ADR-0004 (agentes). Agregar Exclusion a un agent
 
 ### Auditoría
 
-`scripts/auditar-agentes-gaps.js` reporta cobertura. Integración con `/swl:salud`
+`scripts/auditar-agentes-gaps.js` reporta cobertura. Integración con `/swl:status salud`
 mediante `SWL_AUDIT_AGENTES=1` (paso 5d).
 
 ### Ejemplo de frontmatter