# 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
