@saulwade/swl-ses 2.0.0 → 2.1.0

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/registro-componentes-nuevos.md

@@ -1,12 +1,12 @@
----
-paths:
-  - "**/manifiestos/**"
-  - "**/agentes/**"
-  - "**/habilidades/**"
-  - "**/comandos/**"
-  - "**/hooks/**"
-  - "**/plugin.json"
----
+---
+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
@@ -50,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` |
@@ -124,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/sesiones-paralelas.md

@@ -0,0 +1,180 @@
+# Regla: Coordinación obligatoria al detectar sesión paralela
+
+Esta regla es OBLIGATORIA y aplica cuando Claude detecta — o el usuario
+informa — que **otra sesión de IA** (Claude Code, Codex CLI, Cursor, otro
+agente) está trabajando **simultáneamente** sobre el mismo repositorio /
+proyecto.
+
+---
+
+## Principio
+
+> Cuando detectes que otra sesión está activa sobre el mismo repo y los
+> cambios pueden colisionar en archivos compartidos, **DETÉN tu flujo
+> actual y presenta 4 opciones explícitas de coordinación al usuario antes
+> de proceder con cualquier escritura**. NUNCA decidas unilateralmente
+> continuar.
+
+El patrón opuesto (continuar y resolver conflictos al final) es costoso:
+resolución manual de merge conflicts en archivos canónicos del sistema
+(`package.json`, `plugin.json`, `CHANGELOG.md`, manifiestos) toma 30+
+minutos vs 2 minutos de coordinación previa.
+
+---
+
+## Cómo detectar sesión paralela
+
+Señales que disparan la regla:
+
+- El usuario lo informa explícitamente: *"hay otra sesión trabajando en
+  esto agregando X"*.
+- `git status` muestra archivos modificados que tú no modificaste en esta
+  sesión.
+- Commits aparecen en `git log --oneline` con timestamps muy recientes
+  cuyo autor o mensaje no coinciden con tu trabajo.
+- ADRs o PLAN.md aparecen en `.planning/` con números cercanos pero
+  contenido que no escribiste (`0019-X-completa.md` cuando tu trabajo era
+  ADR-0020).
+- Archivos `.swl-install-state.json` o lockfiles con mtime posterior al
+  inicio de tu sesión.
+
+Tras detectar cualquier señal: **pausar inmediatamente** antes de la
+siguiente escritura.
+
+---
+
+## Las 4 opciones obligatorias
+
+Presentar al usuario **literalmente** estas 4 opciones (sin inventar
+variantes hasta que el usuario las pida):
+
+| Opción | Estrategia | Cuándo conviene |
+|--------|-----------|-----------------|
+| **A — Ceder prioridad** | Pausar tu trabajo. Revertir cambios no commiteados. Esperar a que la otra sesión termine. Retomar después con `git pull` y rebase. | La otra sesión está cerca de terminar y tu trabajo es ortogonal o no urgente. |
+| **B — Avance no-conflictivo** | Continuar trabajando, pero SOLO en archivos que la otra sesión NO toca. Identificar y enumerar el subconjunto seguro. Diferir cambios en archivos compartidos hasta que la otra sesión cierre. | Tu trabajo cabe en archivos disjuntos (skills nuevos, scripts nuevos, tests). |
+| **C — Release combinada** | Coordinar con la otra sesión un cierre conjunto: mismo release, mismo PR, ambos trabajos integrados. Implica sincronización explícita en docs canónicas, CHANGELOG, versión. | Ambas líneas de trabajo apuntan al mismo bump de versión y los cambios son complementarios. |
+| **D — Continuar conflictivo** | Continuar todo tu plan. Resolver merge conflicts al final manualmente. **NO RECOMENDADO** salvo bloqueador urgente. | Solo si la coordinación es imposible (otra sesión inalcanzable) y el trabajo es bloqueante. |
+
+Tras presentar las opciones, **esperar la decisión del usuario** antes de
+escribir cualquier archivo. La excepción son lecturas (`Read`, `Grep`,
+`Glob`) que no modifican estado.
+
+---
+
+## Cómo presentar el reporte al usuario
+
+Formato mínimo del mensaje de detección:
+
+```markdown
+Pauso inmediatamente. Hay riesgo de conflicto crítico entre las dos sesiones.
+
+## Estado actual de las dos sesiones
+
+### Sesión actual (esta) — <descripción breve>
+**Cambios en disco**: <lista de archivos modificados por mí>
+**Pendiente**: <sub-fases restantes>
+
+### Sesión paralela — <descripción de qué hace>
+**Cambios detectados**: <archivos modificados por la otra sesión>
+
+## Archivos en colisión potencial al avanzar
+
+| Archivo | Mi necesidad | Otra sesión | Riesgo |
+|---------|-------------|-------------|--------|
+| package.json (versión) | bump vX → vY | bump probablemente también | ALTO |
+| plugin.json | +N skills | posiblemente +runtimes | Medio |
+| CHANGELOG.md | sección nueva | sección nueva | ALTO — conflict garantizado |
+| docs canónicas | docs feature X | docs feature Y | Medio |
+
+## Opciones
+
+[A/B/C/D con descripciones]
+
+## Recomendación
+
+[Opción recomendada con justificación en 1 párrafo]
+```
+
+---
+
+## Reglas duras
+
+- **NUNCA decidir unilateralmente** continuar tras detectar sesión paralela.
+- **NUNCA hacer commits** en archivos compartidos hasta que el usuario
+  confirme la estrategia de coordinación.
+- **NUNCA pushear** cambios sin saber el estado de la otra sesión.
+- Tras decidir Opción B (avance no-conflictivo): **mantener una lista
+  explícita** de archivos seguros vs archivos diferidos. Verificar antes
+  de cada `Write`/`Edit` que el archivo no está en la zona diferida.
+- Si durante el trabajo aparece un nuevo conflicto no anticipado, **pausar
+  de nuevo y reportar** — no resolver en silencio.
+- Tras decidir Opción C (release combinada): coordinar **versión y
+  ubicaciones canónicas** explícitamente (¿quién bumpea? ¿en qué orden se
+  mergean los PRs? ¿quién regenera INVENTARIO.md al final?).
+- **NUNCA revertir cambios pendientes en working tree de una sesión paralela
+  por interpretación errónea de una instrucción del usuario**. Si el usuario
+  dice "no cambies de versión", "no toques X", "deja Y como está" durante un
+  flujo del agente actual, esa instrucción **aplica al trabajo nuevo del
+  agente actual**, no al trabajo previo ya pendiente en working tree de
+  otra sesión. **Antes de revertir cualquier archivo modificado que no
+  modificó la sesión actual**, ejecutar:
+  ```bash
+  git diff HEAD -- <archivo>            # ver el cambio pendiente
+  git log --oneline -3 -- <archivo>      # ver historia del archivo
+  grep -l "<bump-keyword>" .planning/APRENDIZAJES.md   # buscar trazabilidad
+  ```
+  Si el cambio pendiente está documentado como trabajo de sesión previa
+  (entry en APRENDIZAJES.md, mensaje del usuario citándolo, evidencia en
+  `.planning/sessions/diary/`), **NO revertirlo**. Reportar al usuario:
+  *"Detecté cambio pendiente en X de sesión paralela (evidencia: Y). Mi
+  instrucción de no-cambiar-versión aplica solo a mi trabajo nuevo — ¿confirmas
+  que preserve los bumps previos?"*. La instrucción del usuario sobre
+  versiones se interpreta **a partir del momento en que se emite**, no
+  retroactivamente sobre el working tree.
+
+---
+
+## Excepciones legítimas
+
+NO aplicar la regla cuando:
+
+1. **La otra sesión es de lectura pura** (consulta, exploración) y no
+   modifica archivos del repo.
+2. **Las sesiones trabajan en branches distintas** y el merge a main será
+   por PR independiente (no hay riesgo de colisión hasta el merge final).
+3. **El usuario explícitamente autorizó** continuar sin coordinación.
+
+---
+
+## Origen de esta regla
+
+Sesión 2026-05-15 en swl-ses. Mientras una sesión analizaba `temp/cc-sdd-main`
+para absorber patrones SDD (Opción B aprobada por el usuario), otra sesión
+paralela trabajaba en agregar Codex y Cursor como targets de primera clase
+(ADR-0019). Ambas sesiones modificaban `scripts/instalador.js`,
+`manifiestos/modulos.json`, docs canónicas y planeaban bumpear a v1.5.0.
+
+El usuario informó la situación con: *"hay otra sesion trabajando en el mismo
+proyecto: 'Extension CLI' que esta agregando a swl-ses a codex y cursor como
+targets"*. La sesión actual pausó, reportó 4 opciones, esperó decisión. El
+usuario eligió Opción B (avance no-conflictivo en skills nuevos y scripts
+disjuntos; deferir docs y release a "modo D" cuando la otra sesión
+terminara). Resultado: **cero conflictos al cerrar v1.5.0** vía PR #25
+unificado.
+
+Sin esta regla, el patrón habitual hubiera sido continuar y resolver
+conflictos en cada `git pull` — costo estimado ~30 min de merge resolution
+en `CHANGELOG.md`, `plugin.json`, `package.json`, `manifiestos/modulos.json`
+y `INVENTARIO.md`.
+
+---
+
+## Checklist al detectar sesión paralela
+
+- [ ] Pausé mi escritura actual antes de la siguiente `Write`/`Edit`
+- [ ] Ejecuté `git status` y `git log --since="1 hour ago"` para mapear cambios
+- [ ] Identifiqué los archivos potencialmente compartidos
+- [ ] Presenté al usuario un reporte con las 4 opciones (A/B/C/D) y mi recomendación
+- [ ] Esperé decisión explícita antes de la siguiente escritura
+- [ ] Si elegimos B: mantengo lista de archivos diferidos visible
+- [ ] Si elegimos C: confirmé versión objetivo y orden de PRs