@saulwade/swl-ses 1.0.0

package/comandos/swl/release.md

@@ -0,0 +1,217 @@
+---
+name: swl:release
+description: Gestión del ciclo de release del proyecto. Genera versión siguiendo SemVer, crea changelog automático desde commits con Conventional Commits, valida que los tests pasan, crea tag de git y genera release notes. Flags: --tipo=patch|minor|major, --dry-run, --skip-tests.
+allowed_tools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep"]
+evolved: true
+evolved-from: "5.10.5"
+evolved-at: "2026-04-20"
+evolved-by: "aprender"
+evolved-note: "Paso 10 integra scripts/verificar-release.js como gate anti-gap obligatoria tras 3 releases consecutivos donde el release-manager-swl omitio archivos"
+---
+
+# /swl:release — Gestión del ciclo de release
+
+Eres el gestor de releases del proyecto. Orquestas el proceso completo de crear una nueva versión: calcular el número de versión, recopilar cambios, validar estado publicable y crear artefactos de release.
+
+**Carga**: `Skill("release-semver")` — contiene las reglas de SemVer, Conventional Commits, estrategia de tags y proceso detallado de release. Delega toda lógica de versionado al skill.
+
+## Cuándo usar este comando
+
+- Al completar un conjunto de features o fixes listos para producción
+- Al final de un sprint cuando hay cambios acumulados
+- Para hotfixes críticos (patch release)
+- Antes de una demo o entrega a cliente
+
+## Flags soportados
+
+```
+--tipo=patch     Incrementa PATCH (0.0.X) — bugs y correcciones menores
+--tipo=minor     Incrementa MINOR (0.X.0) — features nuevas sin breaking changes
+--tipo=major     Incrementa MAJOR (X.0.0) — breaking changes
+--dry-run        Muestra qué haría sin ejecutar nada
+--skip-tests     Omite tests. Requiere justificación y confirmación explícita.
+```
+
+Si no se pasa `--tipo`, se determina automáticamente según los commits (ver skill).
+
+## Paso 0 — Verificación de prerrequisitos
+
+```bash
+git rev-parse --is-inside-work-tree 2>&1
+git branch --show-current
+git status --porcelain
+git remote -v
+```
+
+- Si hay cambios sin commitear, DETENER y listar archivos pendientes.
+- Si la rama no es la principal, advertir y pedir confirmación.
+
+## Paso 1 — Leer versión actual
+
+```bash
+cat package.json 2>/dev/null | grep '"version"' | head -1
+cat pyproject.toml 2>/dev/null | grep "^version" | head -1
+cat VERSION 2>/dev/null
+git describe --tags --abbrev=0 2>/dev/null || echo "Sin tags previos"
+```
+
+Si hay múltiples fuentes, pedir al usuario que confirme la canónica. Sin versión en ningún lugar: `0.0.0`.
+
+## Paso 2 — Recopilar y clasificar commits
+
+```bash
+LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null)
+if [ -z "$LAST_TAG" ]; then
+  git log --oneline --format="%H %s"
+else
+  git log --oneline --format="%H %s" ${LAST_TAG}..HEAD
+fi
+```
+
+Clasifica cada commit según Conventional Commits (tipos y su impacto en versión definidos en `Skill("release-semver")`).
+
+## Paso 3 — Calcular tipo de versión
+
+Si no se especificó `--tipo`, usar reglas del skill:
+- Breaking change en algún commit -> MAJOR
+- feat: sin breaking changes -> MINOR
+- Cualquier otro caso -> PATCH
+
+Si el usuario pasó `--tipo` y hay discrepancia (ej: breaking changes con --tipo=patch), advertir y pedir confirmación.
+
+## Paso 4 — Calcular nueva versión
+
+Aplica reglas SemVer del skill: MAJOR resets MINOR y PATCH a 0, MINOR resets PATCH a 0.
+
+Si `--dry-run`, mostrar preview del changelog y terminar sin modificar nada.
+
+## Paso 5 — Ejecutar tests
+
+Si NO se pasó `--skip-tests`, detectar runner y ejecutar:
+
+```bash
+ls package.json pytest.ini setup.cfg pyproject.toml Makefile 2>/dev/null
+npm test 2>&1 || pytest 2>&1 || make test 2>&1
+```
+
+Si fallan, DETENER. Si `--skip-tests`, pedir confirmación explícita ("confirmo").
+
+## Paso 6 — Actualizar archivos de versión
+
+Actualiza la versión en TODOS los archivos que la contienen. Para proyectos SWL-SES, la checklist obligatoria es:
+
+```
+[ ] package.json
+[ ] package-lock.json (2 ubicaciones: líneas 3 y 9)
+[ ] plugin.json
+[ ] CLAUDE.md
+[ ] README.md
+[ ] AGENTS.md
+[ ] COMANDOS.md
+[ ] MANUAL_USO.md
+[ ] INSTALACION.md
+[ ] SALUD.md
+[ ] INVENTARIO.md
+[ ] CHANGELOG.md (entrada nueva)
+[ ] .planning/COMPACTACION.md
+[ ] .planning/ESTADO.md
+[ ] .swl-install-state.json (si existe)
+```
+
+Para proyectos no-SWL: actualiza los archivos detectados en Paso 1 (package.json, pyproject.toml, VERSION).
+
+En ambos casos, verificar consistencia después de actualizar con `grep -r "versión-anterior" .` para detectar referencias olvidadas.
+
+## Paso 7 — Generar CHANGELOG
+
+Lee CHANGELOG.md existente (o créalo). Agrega entrada al inicio con formato Keep a Changelog:
+
+- Secciones: Funcionalidades nuevas, Correcciones, Mejoras de rendimiento, Cambios internos, Breaking Changes, Estadísticas.
+- Descripciones legibles por humanos (sin prefijo feat:/fix:).
+- Omitir commits style: y test: del changelog público.
+
+## Paso 8 — Commit de release y tag
+
+```bash
+git add package.json pyproject.toml setup.py VERSION CHANGELOG.md 2>/dev/null
+git commit -m "chore(release): versión [nueva-versión]"
+git tag -a "v[nueva-versión]" -m "Release v[nueva-versión]"
+```
+
+Usar tags anotados siempre (regla del skill).
+
+## Paso 9 — Generar RELEASE-NOTES
+
+Crea `RELEASE-NOTES-v[nueva-versión].md` con: resumen, cambios, instrucciones de actualización y guía de migración si hay breaking changes.
+
+## Paso 10 — Verificación final
+
+### 10.1 Gate automática anti-gap (OBLIGATORIA antes del push)
+
+Ejecutar `scripts/verificar-release.js` que valida que la versión nueva esté reflejada en las 14 ubicaciones canónicas de la checklist (y avisa sobre MANUAL_USO opcional):
+
+```bash
+node scripts/verificar-release.js
+```
+
+Exit codes:
+- `0` — todas las ubicaciones obligatorias con la versión correcta, puedes continuar al push
+- `1` — al menos un archivo quedó en versión anterior. **NO hacer push hasta corregir**. El reporte indica el archivo y el problema específico
+- `2` — error de invocación (package.json ausente, versión inválida)
+
+Ejemplo de output en éxito:
+```
+[OK] package.json: version=5.10.5
+[OK] plugin.json: version=5.10.5
+[OK] package-lock.json: version=5.10.5, packages[""].version=5.10.5
+...
+[OK] CHANGELOG.md: seccion [5.10.5] presente con fecha
+Resultado: 14/15 OK, 1 WARN opcional(es)
+```
+
+Ejemplo de output en fallo que obliga a corregir:
+```
+[FALLA] .planning/MAPEO_SKILLS_AGENTES.md: solo 0 ocurrencia(s) de 5.10.5 (minimo 1)
+[FALLA] README.md: primera linea no menciona 5.10.5 — actual: "# swl-software-engineering-system v5.10.4"
+Resultado: 13/15 OK, 2 FALLA(S) obligatoria(s)
+```
+
+Esta gate existe porque el agente `release-manager-swl` ha omitido archivos en 3 releases consecutivos (5.10.3, 5.10.4, 5.10.5 — ver APRENDIZAJES.md) pese a tener la checklist documentada en su frontmatter. Un checklist textual no basta: se necesita ejecución.
+
+### 10.2 Verificación manual post-gate
+
+```bash
+git tag -l "v[nueva-versión]"
+git log --oneline -3
+head -30 CHANGELOG.md
+```
+
+## Paso 11 — Reporte final
+
+```
+=== Release v[nueva-versión] completado ===
+
+Versión anterior: v[versión-anterior]
+Nueva versión:    v[nueva-versión]
+Tipo:             [PATCH | MINOR | MAJOR]
+
+Archivos actualizados: [lista]
+Git: Commit [hash], Tag v[nueva-versión]
+Commits incluidos: [N] (feat: [N], fix: [N], otros: [N])
+Tests: [ejecutados OK | omitidos (--skip-tests)]
+
+Próximos pasos:
+  1. Revisar RELEASE-NOTES-v[nueva-versión].md
+  2. git push origin v[nueva-versión]
+  3. Publicar release en GitHub/GitLab si aplica
+  4. Notificar al equipo
+```
+
+## Reglas de comportamiento
+
+- NUNCA crear release con repositorio dirty.
+- NUNCA omitir actualización de archivos de versión — inconsistencias causan errores de build.
+- NUNCA usar `--skip-tests` sin documentarlo en CHANGELOG y sin confirmación.
+- Si tipo calculado es MAJOR pero usuario pidió --tipo=patch, reportar discrepancia y esperar confirmación.
+- CHANGELOG legible por alguien que no conoce el código.
+- Si es monorepo, reportar que no se soporta y sugerir lerna/changesets.

package/comandos/swl/revisar-impacto.md

@@ -0,0 +1,206 @@
+---
+name: swl:revisar-impacto
+description: Analiza el impacto estructural de cambios usando el grafo de dependencias SWL. Proporciona blast radius topológico real, god nodes, comunidades y conexiones sorpresivas. Potenciado por graph-builder.py + graph-analyze.py (graphify-3 patterns).
+allowed_tools: ["Bash", "Read"]
+evolved: true
+evolved-from: "5.3.4"
+evolved-at: "2026-04-09"
+evolved-by: "graphify-integration"
+evolved-note: "Análisis topológico real con networkx — graph-builder + graph-analyze + graph-cluster"
+---
+
+# /swl:revisar-impacto — Análisis de impacto estructural
+
+Usa el grafo de dependencias de swl-ses para responder:
+¿qué se rompe si modifico esto? ¿cuál es el riesgo real de estos cambios?
+
+## Uso
+
+```
+/swl:revisar-impacto                          — Resumen topológico general
+/swl:revisar-impacto build                    — Construir/reconstruir el grafo
+/swl:revisar-impacto build --force            — Reconstruir ignorando cache SHA256
+/swl:revisar-impacto status                   — Estado del grafo actual
+/swl:revisar-impacto impacto <nombre>         — Blast radius de un componente
+/swl:revisar-impacto god_nodes [--top N]      — Componentes más conectados
+/swl:revisar-impacto comunidades              — Estructura modular del sistema
+/swl:revisar-impacto sorpresivo               — Acoplamiento oculto cross-community
+/swl:revisar-impacto preguntas                — Preguntas arquitectónicas del grafo
+/swl:revisar-impacto diff <grafo1> <grafo2>   — Cambios entre dos snapshots
+```
+
+---
+
+## Paso 0 — Verificar grafo disponible
+
+```bash
+ls .planning/graph.json .planning/REPORTE-GRAFO.md 2>/dev/null \
+  && echo "GRAFO DISPONIBLE" || echo "GRAFO NO CONSTRUIDO"
+```
+
+Si el grafo no existe, construirlo con `build` antes de cualquier análisis.
+
+---
+
+## Subcomando: build
+
+Construye el grafo de dependencias desde los metadatos del sistema.
+Parsea: `agentes/*.md`, `habilidades/*/SKILL.md`, `hooks/*.js`, `hooks/lib/*.js`, `comandos/swl/*.md`.
+
+```bash
+python scripts/lib/graph-builder.py
+```
+
+Con flag `--force` ignora el cache SHA256 y reparse todos los archivos:
+
+```bash
+python scripts/lib/graph-builder.py --force
+```
+
+Salidas generadas:
+- `.planning/graph.json` — grafo persistente (networkx node-link format)
+- `.planning/REPORTE-GRAFO.md` — reporte legible para agentes
+- `.planning/graph-cache.json` — cache SHA256 por archivo
+
+---
+
+## Subcomando: status
+
+```bash
+python scripts/lib/graph-builder.py --stats
+```
+
+Muestra conteo de nodos por tipo y aristas totales.
+
+---
+
+## Subcomando: impacto (blast radius)
+
+Calcula qué componentes quedan afectados si un nodo cambia.
+Usa BFS en el grafo invertido a profundidad 3.
+
+```bash
+python scripts/lib/graph-analyze.py blast_radius <nombre>
+# Ejemplos:
+python scripts/lib/graph-analyze.py blast_radius event-bus
+python scripts/lib/graph-analyze.py blast_radius fastapi-experto
+python scripts/lib/graph-analyze.py blast_radius atomic-write
+```
+
+Interpretar el resultado:
+- **dependientes**: componentes que dependen de `<nombre>` — se ven afectados si cambia
+- **dependencias**: qué usa `<nombre>` — se ven afectados si fallan
+- **grado alto** → blast radius alto → mayor precaución al modificar
+
+---
+
+## Subcomando: god_nodes
+
+Identifica los componentes más conectados del sistema (single points of failure).
+
+```bash
+python scripts/lib/graph-analyze.py god_nodes --top 10
+```
+
+Un god node con grado > 5 debe considerarse un componente crítico.
+Modificarlo requiere revisión de todos sus dependientes.
+
+---
+
+## Subcomando: comunidades
+
+Detecta módulos funcionales automáticamente mediante Louvain community detection.
+
+```bash
+python scripts/lib/graph-cluster.py
+# Salida JSON:
+python scripts/lib/graph-cluster.py json
+```
+
+Interpretar:
+- **cohesión < 0.10** con ≥ 5 nodos → comunidad candidata a refactoring
+- **comunidades bien cohesionadas** → módulos funcionalmente coherentes
+
+---
+
+## Subcomando: sorpresivo
+
+Detecta acoplamiento oculto: aristas cross-community inesperadas.
+
+```bash
+python scripts/lib/graph-analyze.py sorpresivo
+```
+
+Una conexión "sorpresiva" es aquella que cruza comunidades y conecta tipos
+distintos de componentes — acoplamiento que debería hacerse explícito.
+
+---
+
+## Subcomando: preguntas
+
+Genera preguntas arquitectónicas derivadas de la topología del grafo.
+
+```bash
+python scripts/lib/graph-analyze.py preguntas
+```
+
+Fuentes: bridge nodes (alta betweenness), god nodes (alto grado), nodos huérfanos,
+comunidades de baja cohesión. Alimentar al `arquitecto-swl` con estas preguntas.
+
+---
+
+## Subcomando: diff
+
+Compara dos snapshots del grafo para entender qué cambió estructuralmente.
+
+```bash
+# Guardar snapshot antes de los cambios:
+cp .planning/graph.json .planning/graph-before.json
+
+# Hacer cambios, reconstruir grafo:
+python scripts/lib/graph-builder.py --force
+
+# Comparar:
+python scripts/lib/graph-analyze.py diff .planning/graph-before.json .planning/graph.json
+```
+
+---
+
+## Flujo recomendado pre-modificación de componente crítico
+
+```bash
+# 1. Verificar que el grafo está actualizado
+python scripts/lib/graph-builder.py
+
+# 2. Calcular blast radius del componente a modificar
+python scripts/lib/graph-analyze.py blast_radius <nombre>
+
+# 3. Ver si es un god node
+python scripts/lib/graph-analyze.py god_nodes --top 20 | grep <nombre>
+
+# 4. Verificar comunidad del componente
+python scripts/lib/graph-cluster.py json | python -c "
+import json,sys
+data=json.load(sys.stdin)
+nombre='<nombre>'
+for cid,c in data.items():
+    if nombre in c['nodos']:
+        print(f'Comunidad {cid}: {c[\"etiqueta\"]} (cohesión {c[\"cohesion\"]})')
+"
+```
+
+---
+
+## Cómo usar REPORTE-GRAFO.md
+
+El archivo `.planning/REPORTE-GRAFO.md` es inyectado automáticamente por el hook
+`grafo-contexto.js` antes de cualquier búsqueda de archivos (Glob/Grep/Read).
+
+Esto significa que los agentes tienen contexto del grafo ANTES de leer archivos raw,
+reduciendo el número de tool calls para mapear el codebase.
+
+Para leer el reporte directamente:
+
+```bash
+cat .planning/REPORTE-GRAFO.md
+```