@saulwade/swl-ses 1.9.0 → 2.1.0

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

package/reglas/skills-estandar.md

@@ -1,3 +1,9 @@
+---
+paths:
+  - "**/habilidades/**"
+  - "**/skills/**"
+  - "**/_userland/**"
+---
 # Regla: Estándar Oficial de Claude Agent Skills para el Sistema SWL
 
 **Aplica a**: Toda skill nueva o modificada en `habilidades/` y `skills/`

package/reglas/testing.md

@@ -1,3 +1,10 @@
+---
+paths:
+  - "**/*.tsx"
+  - "**/*.jsx"
+  - "**/vitest.config.{js,ts,mjs}"
+  - "**/playwright.config.{js,ts}"
+---
 # Regla: Testing — Next.js
 
 Probar Next.js con App Router requiere estrategia porque existen tres tipos de

package/reglas/tests-cleanup.md

@@ -1,3 +1,7 @@
+---
+paths:
+  - "**/tests/**"
+---
 # Regla: Cleanup obligatorio de directorios temporales en tests
 
 Esta regla es **OBLIGATORIA** y aplica a todo test Node.js del sistema SWL

package/reglas/usar-code-review-graph.md

@@ -0,0 +1,155 @@
+# Regla: Usar code-review-graph antes de Read/Grep/Glob para explorar
+
+Esta regla es OBLIGATORIA y aplica a todo proyecto del usuario donde el MCP
+server `code-review-graph` esté disponible (sus herramientas
+`mcp__code-review-graph__*` aparecen registradas o deferred en la sesión, o el
+proyecto declara el grafo en su `CLAUDE.md`).
+
+El grafo de conocimiento es un índice estructural del codebase construido con
+Tree-sitter: nodos (archivos, clases, funciones, tipos, tests) y aristas
+(llamadas, imports, dependencias, cobertura). Consultarlo es **más barato en
+tokens**, **más rápido** y aporta **contexto estructural** (callers, dependents,
+blast radius, tests) que un `Grep`/`Read` plano no puede dar.
+
+---
+
+## Principio
+
+> Cuando necesites **explorar, entender, revisar o medir impacto** de código y
+> el grafo `code-review-graph` esté disponible, **consúltalo PRIMERO** con las
+> herramientas `mcp__code-review-graph__*`. Cae a `Read`/`Grep`/`Glob` solo
+> cuando el grafo no cubre lo que necesitas (ver excepciones), no por inercia.
+
+El costo de una consulta al grafo es de segundos y pocos tokens. El costo de
+leer 5-10 archivos completos para reconstruir relaciones que el grafo ya conoce
+es contexto desperdiciado y dinero.
+
+---
+
+## Cuándo usar el grafo PRIMERO (obligatorio)
+
+| Necesidad | Herramienta del grafo | En vez de |
+|---|---|---|
+| Encontrar una función/clase/tipo por nombre o keyword | `semantic_search_nodes_tool` | `Grep` amplio |
+| Entender la arquitectura de alto nivel | `get_architecture_overview_tool`, `list_communities_tool` | leer N archivos para inferir estructura |
+| Trazar callers / callees / imports / tests | `query_graph_tool` (patrones callers_of, callees_of, imports_of, tests_for, dependencies) | `Grep` recursivo + lectura manual |
+| Medir blast radius de un cambio | `get_impact_radius_tool` | rastrear imports a mano |
+| Saber qué flujos de ejecución afecta un cambio | `get_affected_flows_tool` | inferir leyendo |
+| Revisar cambios (code review) con riesgo puntuado | `detect_changes_tool` | `git diff` + leer archivos completos |
+| Obtener snippets justos para revisar | `get_review_context_tool`, `get_minimal_context_tool` | `Read` de archivos enteros |
+| Planear renames / detectar código muerto | `refactor_tool` | `Grep` + verificación manual |
+| Funciones grandes / hubs / puentes arquitectónicos | `find_large_functions_tool`, `get_hub_nodes_tool`, `get_bridge_nodes_tool` | heurística manual |
+| Verificar cobertura de tests de un símbolo | `query_graph_tool` pattern `tests_for` | `Grep` de nombres de test |
+
+Antes de una sesión de exploración/revisión, vale `list_graph_stats_tool` para
+confirmar que el grafo está construido y fresco (`Last updated`).
+
+---
+
+## Workflow estándar
+
+1. **Localizar**: `semantic_search_nodes_tool` con el nombre/keyword del símbolo
+   o `get_architecture_overview_tool` para el mapa general.
+2. **Relacionar**: `query_graph_tool` (callers/callees/imports/tests) o
+   `get_impact_radius_tool` para el blast radius.
+3. **Leer dirigido**: `get_review_context_tool`/`get_minimal_context_tool` para
+   traer solo los snippets relevantes — no el archivo completo.
+4. **Caer al filesystem solo entonces**: si el grafo no cubre el detalle
+   concreto (líneas exactas no indexadas, archivos no parseados, formatos no
+   soportados), ahí sí `Read`/`Grep` con foco específico.
+
+El grafo se auto-actualiza vía hooks al cambiar archivos. Si `list_graph_stats`
+muestra un `Last updated` viejo respecto a cambios recientes, reconstruir con
+`build_or_update_graph_tool` antes de confiar en sus resultados.
+
+---
+
+## Cuándo SÍ usar Read/Grep/Glob directo (excepciones)
+
+NO forzar el grafo cuando:
+
+1. **El grafo no está disponible** — el proyecto no tiene `code-review-graph`
+   instalado, o `list_graph_stats_tool` falla. Usar Read/Grep sin más.
+2. **Lenguaje/formato no indexado** — el grafo parsea código fuente (Python, JS,
+   TS, Go, Rust, Java, C#, bash). Para `.md`, `.json`, `.sql`, `.yaml`, `.env`,
+   migraciones, seeds, configs → Read/Grep directo (el grafo no los modela).
+3. **Necesitas líneas exactas o contenido literal** — verificar una cita
+   `archivo:línea`, leer el cuerpo completo de un archivo que vas a editar,
+   confirmar texto exacto. El grafo da estructura, no sustituye `Read` del
+   archivo que vas a modificar.
+4. **El usuario pidió explícitamente** leer un archivo concreto o hacer un grep
+   puntual.
+5. **Operación de un solo archivo ya conocido** — sabes exactamente qué archivo
+   y qué línea; un `Read` dirigido es más simple que el grafo.
+6. **El grafo está desactualizado** para el cambio recién hecho y no quieres
+   reconstruirlo en ese instante — usa Grep para lo recién escrito.
+
+Antes de editar un archivo, SIEMPRE `Read` del archivo (la regla de Edit lo
+exige y la verificación de citas `archivo:línea` también). El grafo localiza
+**qué** leer; no reemplaza la lectura del archivo que vas a tocar.
+
+---
+
+## Anti-patrones
+
+- **`Grep` amplio del codebase** para encontrar una función cuando
+  `semantic_search_nodes_tool` la ubica en una llamada.
+- **Leer 5+ archivos completos** para entender la arquitectura sin haber
+  consultado `get_architecture_overview_tool` primero.
+- **Rastrear imports a mano con `Grep`** para estimar el impacto de un cambio en
+  vez de `get_impact_radius_tool` / `get_affected_flows_tool`.
+- **`git diff` + leer archivos enteros** para revisar cuando `detect_changes_tool`
+  da el diff con riesgo puntuado y `get_review_context_tool` los snippets justos.
+- **Defaultear a Read/Grep "porque es lo de siempre"** cuando las herramientas
+  `mcp__code-review-graph__*` aparecen deferred (schemas not loaded) — deferred
+  ≠ ausente: cargar el schema con `ToolSearch(query="select:<tool>")` y usarlo.
+  Confundir "no cargado" con "no disponible" es el mismo error documentado para
+  el MCP `obsidian` en `consultar-vault-primero.md`.
+- **Confiar en el grafo sin verificar frescura** tras cambios recientes — si
+  `Last updated` es anterior al cambio, reconstruir o caer a Grep para esa parte.
+
+---
+
+## Relación con otras reglas
+
+- `~/.claude/rules/consultar-vault-primero.md` — patrón hermano: consultar la
+  fuente curada (vault Obsidian para decisiones; grafo para estructura de
+  código) antes de leer múltiples archivos. Mismo principio de economía de
+  tokens y mismo anti-patrón de "deferred ≠ ausente".
+- `~/.claude/rules/verificar-citas-normativas.md § Familia 2` — el grafo
+  **localiza** la cita `archivo:línea`; verificarla aún exige `Read` del archivo
+  real. El grafo no exime de la verificación de citas.
+- `~/.claude/rules/harness-claude-code.md § Disciplina de input format` — repos
+  grandes (>500 archivos) son donde el grafo da el mayor ahorro de tokens
+  (6.8-49× por review según la nota de ese harness).
+- `~/.claude/rules/analizar-directorios-antes-de-escribir.md` — para decidir
+  DÓNDE escribir docs sigue siendo `ls`/`Glob`; el grafo es para explorar
+  **código**, no estructura de directorios de documentación.
+
+---
+
+## Aplicabilidad
+
+Aplica a:
+- Claude Code (CLI, Desktop, IDE) en proyectos con `code-review-graph` activo.
+- Sesiones de exploración, debugging, code review, refactor, análisis de impacto.
+
+NO aplica a:
+- Proyectos sin el grafo instalado.
+- Exploración de documentación/configuración no indexada por el grafo.
+- Sub-agentes que operan sobre un único archivo pasado como argumento.
+
+---
+
+## Origen
+
+Formalizada el 2026-06-09 a petición explícita del usuario tras observar que en
+una sesión larga (feature B-1 de SIGM) se usó `Grep`/`Read`/`Bash` directo de
+forma intensiva para explorar el codebase mientras el MCP `code-review-graph`
+estaba disponible y auto-actualizado (9336 nodos, 78247 aristas). El proyecto
+SIGM ya documentaba la preferencia en su `CLAUDE.md` ("ALWAYS use the
+code-review-graph MCP tools BEFORE using Grep/Glob/Read"), pero el usuario pidió
+promoverla a regla global para que aplique a todo proyecto con el grafo, no solo
+a SIGM. La regla global es ahora la fuente de verdad del comportamiento; el
+`CLAUDE.md` de cada proyecto solo debe declarar que el grafo está disponible
+(no re-derivar el comportamiento — ver `sin-duplicacion-reglas-globales.md`).

package/reglas/usar-sistema-swl.md

@@ -78,7 +78,7 @@ de ejecutar.
 | Capturar aprendizaje recurrente | `/swl:aprender` → APRENDIZAJES.md → posible promoción a regla/skill |
 | Release con bump de versión | `/swl:release` (sincronización de ubicaciones de versión) |
 | Documentación viva post-feature | `documentador-swl` |
-| Diagnóstico del sistema | `/swl:salud` |
+| Diagnóstico del sistema | `/swl:status salud` |
 
 ### Para tareas de búsqueda y contexto