@saulwade/swl-ses 2.4.2 → 2.5.1

package/reglas/sesiones-paralelas.md

@@ -1,180 +1,47 @@
 # 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.
-
----
+Regla OBLIGATORIA cuando Claude detecta — o el usuario informa — que otra sesión de IA
+(Claude Code, Codex CLI, Cursor, otro agente) trabaja **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
+> Al detectar sesión paralela sobre el mismo repo con posible colisión en archivos
+> compartidos: **DETÉN toda escritura y presenta las 4 opciones explícitas de
+> coordinación al usuario antes de proceder**. NUNCA decidas unilateralmente continuar.
+> Continuar y resolver conflictos al final cuesta 30+ min de merge resolution en
+> archivos canónicos (`package.json`, `CHANGELOG.md`, manifiestos) vs 2 min de
+> coordinación previa.
 
-Señales que disparan la regla:
+## Señales de detección
 
-- 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.
+- El usuario lo informa explícitamente ("hay otra sesión trabajando en esto").
+- `git status` con archivos modificados que esta sesión no tocó; commits recientes en `git log` con autor/mensaje ajenos.
+- ADRs/PLAN.md en `.planning/` con números cercanos pero contenido no propio; lockfiles o `.swl-install-state.json` con mtime posterior al inicio de la sesión.
 
-Tras detectar cualquier señal: **pausar inmediatamente** antes de la
-siguiente escritura.
-
----
+Tras cualquier señal: **pausar inmediatamente** antes de la siguiente escritura. Solo lecturas (`Read`/`Grep`/`Glob`) quedan permitidas.
 
 ## 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
+Presentarlas **literalmente** (sin inventar variantes) y esperar la decisión del usuario:
 
-| 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]
-```
-
----
+| Opción | Estrategia |
+|---|---|
+| **A — Ceder prioridad** | Pausar, revertir lo no commiteado, esperar; retomar con `git pull` + rebase. Conviene si la otra sesión está por terminar y tu trabajo no urge. |
+| **B — Avance no-conflictivo** | Continuar SOLO en archivos que la otra sesión NO toca, con lista explícita del subconjunto seguro; diferir los compartidos hasta que la otra sesión cierre. |
+| **C — Release combinada** | Cierre conjunto coordinado: mismo release/PR, sincronización explícita de versión, CHANGELOG y docs canónicas. |
+| **D — Continuar conflictivo** | Continuar todo y resolver merge conflicts al final. **NO RECOMENDADO** salvo bloqueador urgente con sesión inalcanzable. |
 
 ## 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`.
+- NUNCA commits en archivos compartidos sin estrategia confirmada; NUNCA push sin conocer el estado de la otra sesión.
+- En Opción B: mantener lista explícita de archivos seguros vs diferidos y verificarla antes de cada `Write`/`Edit`. En Opción C: coordinar versión y ubicaciones canónicas (quién bumpea, orden de PRs).
+- Nuevo conflicto no anticipado → pausar de nuevo y reportar, no resolver en silencio.
+- NUNCA revertir working tree pendiente de otra sesión por interpretación de una instrucción del usuario ("no cambies X" aplica al trabajo nuevo de esta sesión, no retroactivamente): antes de revertir un archivo que esta sesión no modificó, verificar procedencia con `git diff HEAD -- <archivo>`, `git log -- <archivo>` y trazabilidad en APRENDIZAJES/diary; si es trabajo de sesión previa, preservarlo y preguntar al usuario.
 
----
+## Excepciones
 
-## Checklist al detectar sesión paralela
+No aplica si la otra sesión es de lectura pura, si trabajan en branches distintas
+(merge por PR independiente), o si el usuario autorizó explícitamente continuar.
 
-- [ ] 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
+Detalle extendido (formato completo del reporte, protocolo anti-revert con comandos, caso de origen v1.5.0, checklist): `Skill("meta-reglas-extendido")` → `recursos/sesiones-paralelas.md`.

package/reglas/sin-duplicacion-reglas-globales.md

@@ -1,182 +1,41 @@
 # Regla: Sin duplicación de reglas globales en CLAUDE.md de proyecto
 
-Esta regla es **OBLIGATORIA** y aplica al diseño/auditoría de cualquier
-`CLAUDE.md` de proyecto donde el sistema SWL esté instalado. Extiende el
-contrato canónico de `swl-claudemd` con un sub-caso específico: la
-duplicación inline de reglas que ya viven en `~/.claude/rules/`.
-
----
+Regla OBLIGATORIA en el diseño/auditoría de cualquier `CLAUDE.md` de proyecto con SWL
+instalado. Extiende el contrato canónico de `swl-claudemd` con un sub-caso específico:
+la duplicación inline de reglas que ya viven en `~/.claude/rules/`.
 
 ## Principio
 
-> Cuando una regla ya está documentada en `~/.claude/rules/` (carga global
-> automática en todas las sesiones del usuario), **el `CLAUDE.md` del
-> proyecto NO debe duplicarla inline**. La duplicación viola DRY a nivel
-> de gobernanza, genera drift cuando la regla global se actualiza, y
-> erosiona el contrato canónico de `CLAUDE.md` (≤200 LOC).
-
-La regla global es **la fuente de verdad**. El `CLAUDE.md` del proyecto
-puede referenciarla con `@~/.claude/rules/<archivo>.md` o agregar
-**matices propios del proyecto**, pero NUNCA re-derivar el principio.
-
----
-
-## Cuándo aplicar
-
-OBLIGATORIO al:
-
-- Crear un `CLAUDE.md` de proyecto nuevo (`/swl:claudemd init-project`,
-  `/swl:nuevo-proyecto`, `/swl:adoptar-proyecto`).
-- Modificar `CLAUDE.md` de proyecto inline (`/swl:aprender` Paso 6 Tipo A,
-  edición manual del usuario, `Edit`/`Write` programático).
-- Revisar `CLAUDE.md` (`/swl:claudemd audit`, `/swl:claudemd refactor`,
-  hook `claudemd-bloat-detector`, hook `claudemd-duplicacion-detector`).
-
-NO aplica al:
-
-- `~/.claude/CLAUDE.md` (user-level) — ahí SÍ pueden declararse
-  preferencias personales que parafrasean o complementan reglas globales.
-- Documentación dentro del proyecto que no es `CLAUDE.md` (READMEs,
-  ADRs, docs de feature) — ahí no aplica el contrato canónico.
+> Cuando una regla ya está documentada en `~/.claude/rules/` (carga global automática en
+> todas las sesiones), el `CLAUDE.md` del proyecto NUNCA la duplica inline. La duplicación
+> viola DRY a nivel de gobernanza, genera drift cuando la global se actualiza y erosiona el
+> contrato canónico (≤200 LOC). La regla global es **la fuente de verdad**: referenciarla
+> con `@~/.claude/rules/<archivo>.md` o agregar matiz local ≤3 líneas — jamás re-derivar
+> el principio.
 
----
+## Cuándo aplica
 
-## Catálogo de reglas globales conocidas
-
-Las siguientes reglas globales se cargan automáticamente cada sesión y
-NO deben duplicarse en `CLAUDE.md` de proyecto:
-
-| Regla global | Sección canónica | Referencia para citar |
-|---|---|---|
-| `brevedad-output.md` | Idioma obligatorio: español de México | `@~/.claude/rules/brevedad-output.md § Idioma obligatorio` |
-| `brevedad-output.md` | Brevedad y eficiencia de output | `@~/.claude/rules/brevedad-output.md § Brevedad` |
-| `git-coauthor.md` | Sin co-autores en commits | `@~/.claude/rules/git-coauthor.md` |
-| `arreglar-al-detectar.md` | Detectar → Informar → Arreglar | `@~/.claude/rules/arreglar-al-detectar.md` |
-| `debatir-antes-de-aceptar.md` | Debatir decisiones que chocan con reglas | `@~/.claude/rules/debatir-antes-de-aceptar.md` |
-| `usar-context7.md` | Consultar Context7 antes de dependencias | `@~/.claude/rules/usar-context7.md` |
-
-Catálogo declarativo completo:
-`scripts/lib/reglas-globales-conocidas.json`. El catálogo es la fuente
-de verdad consumida por el auditor (`scripts/auditar-claudemd.js`) y el
-hook (`hooks/claudemd-duplicacion-detector.js`).
-
----
+- Al crear (`/swl:claudemd init-project`, `/swl:nuevo-proyecto`, `/swl:adoptar-proyecto`), modificar (`/swl:aprender` Tipo A, edición manual o programática) o auditar (`/swl:claudemd audit|refactor`, hooks `claudemd-bloat-detector` / `claudemd-duplicacion-detector`) un `CLAUDE.md` de proyecto. NO aplica a `~/.claude/CLAUDE.md` (user-level) ni a docs que no son `CLAUDE.md` (READMEs, ADRs).
 
 ## Qué SÍ es legítimo en CLAUDE.md de proyecto
 
-Lo siguiente NO se considera duplicación y es bienvenido:
-
-1. **Matiz local específico**: "Convenciones locales: identificadores
-   técnicos en inglés (rutas, comandos), prosa en español." — el matiz
-   es del proyecto, no la regla del idioma.
-2. **Override explícito documentado**: "Override de
-   `~/.claude/rules/brevedad-output.md` § Brevedad: este proyecto usa
-   docstrings extendidos por requerimiento legal." — el override es
-   explícito y nombra la regla global.
-3. **Excepción acotada con justificación**: "Excepción a
-   `~/.claude/rules/arreglar-al-detectar.md`: bugs cosméticos en el
-   módulo legacy `X/` se difieren a Q3 por congelación." — la excepción
-   nombra la regla y justifica.
-4. **Referencia `@`**: `@~/.claude/rules/<archivo>.md` — incluir la
-   regla por referencia, no inline.
-
----
-
-## Cómo detectarlo
-
-### Manual
+- **Matiz local específico**: convención propia del proyecto, no la regla en sí.
+- **Override explícito documentado** que nombra la regla global sobrescrita y su razón.
+- **Excepción acotada con justificación** que nombra la regla y el alcance.
+- **Referencia `@~/.claude/rules/<archivo>.md`**: incluir por referencia, no inline.
 
-```bash
-node scripts/auditar-claudemd.js
-# Buscar en el output: "duplicacion-reglas-globales"
-```
+## Detección y remediación
 
-### Automático
-
-- **Auditor síncrono**: `scripts/auditar-claudemd.js` (dimensión 7,
-  severidad WARN, no bloquea).
-- **Hook async**: `hooks/claudemd-duplicacion-detector.js` (PostToolUse,
-  emite nudge a `.planning/evolution/nudges.jsonl`).
-- **Comando**: `/swl:claudemd audit` reporta el conteo; `/swl:claudemd
-  refactor` propone el reemplazo concreto.
-
----
-
-## Cómo remediar
-
-1. **Identificar el bloque** señalado por el auditor (línea aproximada).
-2. **Decidir**:
-   - ¿El bloque es 100% paráfrasis de la regla global? → **eliminar**.
-   - ¿El bloque agrega matiz local? → **reescribir como matiz corto**
-     (≤3 líneas) que nombra la regla global ("Convenciones locales:
-     <matiz>. Ver `@~/.claude/rules/<archivo>.md`.").
-3. **Verificar**: re-ejecutar `node scripts/auditar-claudemd.js` hasta
-   que la duplicación desaparezca.
-
----
+- **Detección**: `node scripts/auditar-claudemd.js` (dimensión 7, WARN) + hook `claudemd-duplicacion-detector.js`; catálogo fuente de verdad en `scripts/lib/reglas-globales-conocidas.json`.
+- **Remediación**: paráfrasis pura → eliminar; con matiz → reescribir en ≤3 líneas nombrando la regla global; re-ejecutar el auditor hasta 0 hallazgos `duplicacion-reglas-globales`.
 
 ## Anti-patrones
 
-- **Copiar contenido de reglas globales "para que esté visible"**: la
-  regla global YA está visible — se carga automáticamente. Copiarla en
-  cada proyecto es deuda silenciosa.
-- **Re-derivar el principio con palabras propias**: si dices "todo
-  contenido generado debe ser en español de México con acentos
-  correctos…" estás re-derivando `brevedad-output.md § Idioma`.
-- **Bloque "Reglas de máxima prioridad" que repite reglas globales**:
-  las reglas globales SON prioritarias por construcción — duplicarlas
-  no aumenta su prioridad.
-- **Idioma "Language" en inglés que dice "español"**: paradójico y
-  duplica la regla.
-- **Override implícito sin nombrar la regla global**: "este proyecto
-  usa docstrings extendidos" sin decir que es override de qué.
-- **Ignorar el WARN del auditor argumentando "es para claridad"**: el
-  auditor lleva razón. La regla global es suficiente claridad.
-
----
-
-## Relación con otras reglas
-
-- `~/.claude/rules/memoria-consolidada.md § Reglas de no-duplicación`:
-  principio general "un dato vive en exactamente un canal". Esta regla
-  lo aplica al canal CLAUDE.md.
-- `~/.claude/rules/fragmentos-compartidos.md`: la analogía a nivel de
-  agentes (fragmentos `_*.md` se incrustan, no se duplican).
-- `~/.claude/rules/skills-estandar.md`: la analogía a nivel de skills
-  (skill referencia otro skill, no duplica su contenido).
-- `reglas/auditorias-documentales-estructurales.md § Para prosa
-  cuantificada en campos descriptivos`: hermana — verifica drift
-  cross-manifest. Esta regla verifica drift cross-fuente.
-
----
-
-## Origen de esta regla
-
-Sesión 2026-05-22, swl-ses v1.7.0. El usuario pegó 4 fragmentos de
-`CLAUDE.md` de distintos proyectos que repetían la misma regla de idioma
-"español de México" en formas distintas (lista con bullets, H3 inline,
-lista numerada, sección "Language" en inglés). El análisis reveló:
-
-- La regla ya vivía en `~/.claude/rules/brevedad-output.md § Idioma
-  obligatorio: español de México` desde sesiones previas.
-- Cada proyecto la había re-derivado por iteraciones de
-  `/swl:aprender` Tipo A sin que ningún check detectara la
-  duplicación.
-- El bloat acumulado en cada `CLAUDE.md` consumía 7-15 líneas que
-  podían eliminarse sin perder semántica.
-
-Resolución: crear el catálogo declarativo + detector + dimensión 7 del
-auditor + hook PostToolUse + esta regla. Release v1.7.0 MINOR.
-
----
-
-## Checklist al modificar CLAUDE.md de proyecto
+- Copiar la regla global "para que esté visible" — ya está visible: se carga automáticamente; copiarla es deuda silenciosa.
+- Re-derivar el principio con palabras propias (ej. re-explicar el idioma de `brevedad-output.md § Idioma`).
+- Bloque "Reglas de máxima prioridad" que repite globales — ya son prioritarias por construcción.
+- Sección "Language" en inglés que dice "español" — paradójico y duplica la regla.
+- Override implícito sin nombrar qué regla global sobrescribe.
+- Ignorar el WARN del auditor argumentando "es para claridad" — la regla global es suficiente claridad.
 
-- [ ] ¿El bloque que voy a agregar parafrasea una regla global de
-      `~/.claude/rules/`?
-- [ ] Si sí: ¿agrega matiz local genuino, o solo repite el principio?
-- [ ] Si solo repite: NO agregar — la regla global ya aplica.
-- [ ] Si agrega matiz: redactar en ≤3 líneas que **nombran la regla
-      global** (referencia con `@~/.claude/rules/<archivo>.md`).
-- [ ] Tras escribir: ejecutar `node scripts/auditar-claudemd.js` y
-      confirmar 0 hallazgos `duplicacion-reglas-globales`.
+Detalle extendido (catálogo de reglas globales conocidas, ejemplos completos, comandos de detección, remediación paso a paso, relación con otras reglas, caso de origen, checklist): `Skill("meta-reglas-extendido")` → `recursos/sin-duplicacion-reglas-globales.md`.