@saulwade/swl-ses 2.3.0 → 2.4.1

package/reglas/sesiones-paralelas.md

@@ -1,180 +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
+# 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