@saulwade/swl-ses 2.2.4 → 2.3.1

package/reglas/monitor-ci.md

@@ -1,309 +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).
+---
+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,9 +1,9 @@
----
-paths:
-  - "**/*.tsx"
-  - "**/*.jsx"
-  - "**/next.config.{js,mjs,ts}"
----
+---
+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.