---
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).
