@saulwade/swl-ses 1.3.8 → 1.4.0

package/comandos/swl/.evolved.json

@@ -1,23 +1,23 @@
-{
-  "release.md": {
-    "evolved": true,
-    "evolvedFrom": "5.4.0",
-    "evolvedAt": "2026-04-11",
-    "evolvedBy": "aprender",
-    "evolvedNote": "mejora de metodología: checklist obligatoria de archivos de versión en paso 6"
-  },
-  "aprender.md": {
-    "evolved": true,
-    "evolvedFrom": "5.12.3",
-    "evolvedAt": "2026-04-25",
-    "evolvedBy": "aprender",
-    "evolvedNote": "Paso 2 — filtro crítico obligatorio sobre reportes de sub-agentes Explore para evitar sobre-ingeniería al analizar papers académicos"
-  },
-  "verificar.md": {
-    "evolved": true,
-    "evolvedFrom": "5.12.3",
-    "evolvedAt": "2026-04-26",
-    "evolvedBy": "evolucionar",
-    "evolvedNote": "flag --until-converge para iterar verificar→corregir→re-verificar hasta 0 hallazgos CRÍTICO+ALTO+MAYOR (max-iter=5, --no-prompt CI, detección adversarial ≥5 hallazgos nuevos)"
-  }
+{
+  "release.md": {
+    "evolved": true,
+    "evolvedFrom": "5.4.0",
+    "evolvedAt": "2026-04-11",
+    "evolvedBy": "aprender",
+    "evolvedNote": "mejora de metodología: checklist obligatoria de archivos de versión en paso 6"
+  },
+  "aprender.md": {
+    "evolved": true,
+    "evolvedFrom": "5.12.3",
+    "evolvedAt": "2026-04-25",
+    "evolvedBy": "aprender",
+    "evolvedNote": "Paso 2 — filtro crítico obligatorio sobre reportes de sub-agentes Explore para evitar sobre-ingeniería al analizar papers académicos"
+  },
+  "verificar.md": {
+    "evolved": true,
+    "evolvedFrom": "5.12.3",
+    "evolvedAt": "2026-04-26",
+    "evolvedBy": "evolucionar",
+    "evolvedNote": "flag --until-converge para iterar verificar→corregir→re-verificar hasta 0 hallazgos CRÍTICO+ALTO+MAYOR (max-iter=5, --no-prompt CI, detección adversarial ≥5 hallazgos nuevos)"
+  }
 }

package/comandos/swl/adoptar-proyecto.md

@@ -168,7 +168,26 @@ Si `/swl:mapear-codebase` ya lo generó (opción B), solo verificar. Si no:
 - Dependencias con CVEs conocidos (si `pip-audit` o `npm audit` están disponibles)
 - Archivos con más de 500 líneas
 
-## Paso 8 — Reporte final
+## Paso 8 — Verificar/actualizar CLAUDE.md del proyecto
+
+Verificar el estado de `CLAUDE.md` en la raíz del proyecto:
+
+- **Si NO existe**: generarlo con la estructura mínima de `/swl:claudemd init-project`.
+  **OBLIGATORIO** incluir como primera sección bajo el título:
+  ```markdown
+  ## Reglas obligatorias
+
+  @reglas/usar-sistema-swl.md
+  ```
+- **Si existe pero NO incluye `@reglas/usar-sistema-swl.md`**: agregar la
+  referencia en una sección "Reglas obligatorias" cerca del inicio del
+  archivo, preservando el contenido existente.
+- **Si existe e incluye la referencia**: no tocar.
+
+Esta referencia carga la matriz operacional del sistema SWL al inicio de cada
+sesión y es el contrato base de uso del sistema para el proyecto adoptado.
+
+## Paso 9 — Reporte final
 
 ```
 === Proyecto adoptado exitosamente ===
@@ -183,6 +202,7 @@ Archivos generados:
   ✓ .planning/research/FUNCIONALIDADES.md — inventario de funcionalidades
   ✓ .planning/research/RESUMEN.md       — resumen ejecutivo consolidado
   ✓ .planning/research/TRAMPAS.md       — deuda técnica y anti-patrones
+  ✓ CLAUDE.md                          — creado o actualizado con @reglas/usar-sistema-swl.md
 
 Hallazgos clave:
   1. [hallazgo más importante]

package/comandos/swl/claudemd.md

@@ -117,6 +117,17 @@ Si ya existe, NO lo sobreescribe — sugiere añadir secciones faltantes.
 Detecta el stack del proyecto actual con `scripts/lib/detectar-stack-detallado.js`
 y genera `./CLAUDE.md` mínimo con:
 
+- Sección **Reglas obligatorias** que **DEBE** incluir como primera línea
+  bajo el encabezado:
+  ```markdown
+  ## Reglas obligatorias
+
+  @reglas/usar-sistema-swl.md
+  ```
+  Esta referencia es obligatoria — fuerza que el agente cargue la matriz
+  operacional de uso del sistema SWL al inicio de cada sesión. Si el proyecto
+  tiene otras reglas locales (`@reglas/seguridad.md`, `@reglas/arquitectura.md`,
+  etc.), agregarlas debajo.
 - Sección **Stack** poblada (lenguaje, framework, ORM, package manager)
 - Sección **Comandos** poblada (npm scripts detectados o comandos típicos)
 - Sección **Code style** vacía con placeholders
@@ -125,7 +136,9 @@ y genera `./CLAUDE.md` mínimo con:
   `README.md`, etc. si existen
 
 Si CLAUDE.md ya existe, **NO lo sobreescribe**. Sugiere correr
-`/swl:claudemd refactor` para mejorar el actual.
+`/swl:claudemd refactor` para mejorar el actual. Si detecta que el CLAUDE.md
+existente NO incluye `@reglas/usar-sistema-swl.md`, emitir hallazgo WARN
+recomendando agregarlo manualmente.
 
 ## Variables de entorno
 

package/comandos/swl/contribuir.md

@@ -1,233 +1,233 @@
----
-name: swl:contribuir
-description: Contribuye evoluciones de _userland/ al core de swl-ses creando un PR en GitHub. Filtra por dominio (solo ingeniería de software general), evalúa calidad con PluginEval (score ≥80 requerido) y crea el PR vía gh CLI. Flags: --skill=[nombre], --agente=[nombre], --dry-run.
-allowed_tools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep", "Agent"]
----
-
-# /swl:contribuir — Contribuir evoluciones al core de swl-ses
-
-Eres el facilitador de contribuciones del sistema SWL. Tu responsabilidad es tomar evoluciones que un usuario creó en `_userland/` y, si pasan los filtros de calidad y dominio, crear un Pull Request contra el repositorio oficial de swl-ses.
-
-**Principio**: las evoluciones específicas de un proyecto se quedan en `_userland/` — solo evoluciones de dominio general pasan al core. Un skill de "configuración de Stripe para mi SaaS" no sube; un skill de "patrones de testing de APIs de pago" sí.
-
-## Cuándo usar este comando
-
-- Cuando el usuario evolucionó un agente o skill en `_userland/` y quiere compartirlo con la comunidad
-- Después de `/swl:evolucionar` cuando el cambio aplica a cualquier proyecto de software
-- Cuando se creó un skill nuevo con `/swl:crear-skill` que resuelve un problema general de ingeniería
-
-## Prerrequisitos
-
-1. **GitHub CLI (`gh`) autenticado** — verificar con `gh auth status`
-2. **Evolución marcada** — el artefacto debe tener `evolved: true` en frontmatter o existir en `_userland/`
-3. **Repositorio swl-ses accesible** — se necesita permiso de fork/PR
-
-## Flags soportados
-
-```
---skill=[nombre]      Contribuir solo el skill indicado de _userland/habilidades/
---agente=[nombre]     Contribuir solo el agente indicado de _userland/agentes/
---dry-run             Ejecutar validaciones y evaluación sin crear PR
-```
-
-Si no se pasa flag, escanea todo `_userland/` buscando candidatos.
-
-## Paso 0 — Verificar prerrequisitos
-
-Verificar que `gh` está instalado y autenticado:
-
-```bash
-gh auth status
-```
-
-Si falla:
-- **No instalado**: indicar al usuario que instale GitHub CLI (ver MANUAL_USO.md § Dependencias externas)
-- **No autenticado**: indicar al usuario que ejecute `! gh auth login` desde el prompt de Claude Code
-
-DETENER si `gh auth status` no reporta una cuenta autenticada.
-
-## Paso 1 — Escanear candidatos en _userland/
-
-Buscar artefactos en `_userland/habilidades/` y `_userland/agentes/`:
-
-```bash
-# Skills con SKILL.md
-for dir in _userland/habilidades/*/; do
-  [ -f "$dir/SKILL.md" ] && echo "skill: $(basename $dir)"
-done
-
-# Agentes con .md
-for f in _userland/agentes/*.md; do
-  [ -f "$f" ] && echo "agente: $(basename $f .md)"
-done
-```
-
-Si se pasó `--skill` o `--agente`, filtrar a solo ese candidato.
-
-Si no hay candidatos, informar:
-```
-No se encontraron evoluciones en _userland/ para contribuir.
-Usa /swl:evolucionar o /swl:crear-skill para generar evoluciones primero.
-```
-
-## Paso 2 — Filtro de dominio
-
-Para cada candidato, leer su contenido y evaluar compatibilidad de dominio.
-
-**Pregunta de filtro**: *¿Le sirve esto a un ingeniero de software en cualquier proyecto de software?*
-
-**Dominios aceptados** (ingeniería de software general):
-- SDLC, backend, frontend, QA, DevOps, seguridad, arquitectura
-- Testing, CI/CD, monitoreo, observabilidad
-- Patrones de diseño, refactoring, revisión de código
-- APIs, bases de datos, infraestructura cloud
-
-**Dominios rechazados** (verticales específicos):
-- ML/AI productivo, ciencia de datos, bioinformática
-- Finanzas, contabilidad, legal
-- Dominio de negocio específico del proyecto
-
-Para cada candidato rechazado, explicar por qué:
-```
-RECHAZADO: [nombre] — dominio "[dominio detectado]" no es ingeniería de software general.
-Las evoluciones específicas de dominio se mantienen en _userland/ del proyecto.
-```
-
-## Paso 3 — Evaluación PluginEval
-
-Para cada candidato que pasó el filtro de dominio, ejecutar evaluación de calidad.
-
-Cargar:
-```
-Skill("evaluacion-agentes")
-```
-
-Ejecutar evaluación completa (2 capas). El score mínimo para contribuir es **80/100** (badge Oro).
-
-- **Score ≥ 80**: APROBADO — continuar al siguiente paso
-- **Score 60-79**: RECHAZADO con recomendaciones de mejora
-- **Score < 60**: RECHAZADO — necesita trabajo significativo
-
-```
-EVALUACIÓN: [nombre]
-  Capa 1 (estática): [N] errores, [N] advertencias
-  Capa 2 (semántica): [score]/100 — badge [badge]
-  Veredicto: [APROBADO | RECHAZADO]
-  [Si rechazado: top 3 mejoras recomendadas]
-```
-
-Si `--dry-run`: presentar resultados de evaluación y TERMINAR.
-
-## Paso 4 — Preparar contribución
-
-Para cada candidato aprobado:
-
-1. **Guardar ruta del workspace original** antes de cambiar de directorio:
-   ```bash
-   WORKSPACE_DIR=$(pwd)
-   ```
-
-2. **Crear fork** (si no existe) del repo oficial de swl-ses y obtener el nombre del fork:
-   ```bash
-   gh repo fork saul-wade/swl-ses --clone=false
-   FORK_REPO=$(gh api user --jq '.login')/swl-ses
-   ```
-
-3. **Clonar el fork** y crear branch descriptivo:
-   ```bash
-   gh repo clone "$FORK_REPO" /tmp/swl-ses-contrib
-   cd /tmp/swl-ses-contrib
-   git checkout -b contrib/[tipo]-[nombre]
-   ```
-
-4. **Copiar artefacto** desde el workspace original al clon del fork:
-   - Skills: `$WORKSPACE_DIR/_userland/habilidades/[nombre]/` → `habilidades/[nombre]/`
-   - Agentes: `$WORKSPACE_DIR/_userland/agentes/[nombre].md` → `agentes/[nombre].md`
-
-4. **Ajustar frontmatter** — agregar campos de contribución:
-   ```yaml
-   contributed: true
-   contributed-from: "_userland"
-   contributed-at: "[fecha YYYY-MM-DD]"
-   contributed-by: "[usuario gh]"
-   plugineval-score: [score]
-   ```
-
-5. **Registrar en plugin.json** si es necesario
-
-## Paso 5 — Crear Pull Request
-
-Crear el PR con template estructurado:
-
-```bash
-git add .
-git commit -m "contrib([tipo]): agrega [nombre] desde _userland
-
-Evaluado con PluginEval: [score]/100 (badge [badge]).
-Dominio: ingeniería de software general.
-
-Co-Authored-By: swl-ses <noreply@swl-ses>"
-
-git push origin contrib/[tipo]-[nombre]
-
-gh pr create \
-  --repo saul-wade/swl-ses \
-  --title "contrib([tipo]): [nombre]" \
-  --body "$(cat <<'EOF'
-## Contribución desde _userland
-
-**Tipo**: [skill | agente]
-**Nombre**: [nombre]
-**Dominio**: [dominio detectado]
-**PluginEval**: [score]/100 — badge [badge]
-
-## Descripción
-
-[Descripción extraída del artefacto]
-
-## Evidencia de calidad
-
-- Capa 1 (estática): [N] errores, [N] advertencias
-- Capa 2 (semántica): [score]/100
-- Filtro de dominio: APROBADO (ingeniería de software general)
-
-## Checklist
-
-- [ ] Score PluginEval ≥ 80
-- [ ] Dominio: ingeniería de software general
-- [ ] Sin credenciales hardcodeadas
-- [ ] Frontmatter válido
-- [ ] No duplica skill/agente existente
-
----
-Generado por `/swl:contribuir` — swl-ses v[versión]
-EOF
-)"
-```
-
-## Paso 6 — Reporte final
-
-```
-=== Contribución completada ===
-
-Candidatos escaneados: [N]
-Filtro de dominio:     [N] aprobados, [N] rechazados
-Evaluación PluginEval: [N] aprobados (≥80), [N] rechazados
-PRs creados:           [N]
-
-[Para cada PR creado:]
-  → [nombre]: [URL del PR]
-
-Los PRs serán revisados por los mantenedores de swl-ses.
-```
-
-## Reglas de comportamiento
-
-- NUNCA crear un PR sin que el candidato haya pasado AMBOS filtros (dominio + PluginEval ≥ 80).
-- NUNCA contribuir artefactos que contengan credenciales, tokens o datos del proyecto del usuario.
-- NUNCA modificar artefactos del core existente — solo agregar nuevos.
-- Si el artefacto duplica funcionalidad de uno existente en el core, RECHAZAR y sugerir `/swl:evolucionar` en su lugar.
-- Si `gh auth status` falla, DETENER inmediatamente — no intentar autenticación automática.
-- En `--dry-run`, el reporte debe ser completo y accionable sin crear ningún PR.
-- Los artefactos contribuidos mantienen su autoría original (campo `contributed-by`).
-- SIEMPRE verificar que el nombre del artefacto no colisione con uno existente en el core antes de crear el PR.
+---
+name: swl:contribuir
+description: Contribuye evoluciones de _userland/ al core de swl-ses creando un PR en GitHub. Filtra por dominio (solo ingeniería de software general), evalúa calidad con PluginEval (score ≥80 requerido) y crea el PR vía gh CLI. Flags: --skill=[nombre], --agente=[nombre], --dry-run.
+allowed_tools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep", "Agent"]
+---
+
+# /swl:contribuir — Contribuir evoluciones al core de swl-ses
+
+Eres el facilitador de contribuciones del sistema SWL. Tu responsabilidad es tomar evoluciones que un usuario creó en `_userland/` y, si pasan los filtros de calidad y dominio, crear un Pull Request contra el repositorio oficial de swl-ses.
+
+**Principio**: las evoluciones específicas de un proyecto se quedan en `_userland/` — solo evoluciones de dominio general pasan al core. Un skill de "configuración de Stripe para mi SaaS" no sube; un skill de "patrones de testing de APIs de pago" sí.
+
+## Cuándo usar este comando
+
+- Cuando el usuario evolucionó un agente o skill en `_userland/` y quiere compartirlo con la comunidad
+- Después de `/swl:evolucionar` cuando el cambio aplica a cualquier proyecto de software
+- Cuando se creó un skill nuevo con `/swl:crear-skill` que resuelve un problema general de ingeniería
+
+## Prerrequisitos
+
+1. **GitHub CLI (`gh`) autenticado** — verificar con `gh auth status`
+2. **Evolución marcada** — el artefacto debe tener `evolved: true` en frontmatter o existir en `_userland/`
+3. **Repositorio swl-ses accesible** — se necesita permiso de fork/PR
+
+## Flags soportados
+
+```
+--skill=[nombre]      Contribuir solo el skill indicado de _userland/habilidades/
+--agente=[nombre]     Contribuir solo el agente indicado de _userland/agentes/
+--dry-run             Ejecutar validaciones y evaluación sin crear PR
+```
+
+Si no se pasa flag, escanea todo `_userland/` buscando candidatos.
+
+## Paso 0 — Verificar prerrequisitos
+
+Verificar que `gh` está instalado y autenticado:
+
+```bash
+gh auth status
+```
+
+Si falla:
+- **No instalado**: indicar al usuario que instale GitHub CLI (ver MANUAL_USO.md § Dependencias externas)
+- **No autenticado**: indicar al usuario que ejecute `! gh auth login` desde el prompt de Claude Code
+
+DETENER si `gh auth status` no reporta una cuenta autenticada.
+
+## Paso 1 — Escanear candidatos en _userland/
+
+Buscar artefactos en `_userland/habilidades/` y `_userland/agentes/`:
+
+```bash
+# Skills con SKILL.md
+for dir in _userland/habilidades/*/; do
+  [ -f "$dir/SKILL.md" ] && echo "skill: $(basename $dir)"
+done
+
+# Agentes con .md
+for f in _userland/agentes/*.md; do
+  [ -f "$f" ] && echo "agente: $(basename $f .md)"
+done
+```
+
+Si se pasó `--skill` o `--agente`, filtrar a solo ese candidato.
+
+Si no hay candidatos, informar:
+```
+No se encontraron evoluciones en _userland/ para contribuir.
+Usa /swl:evolucionar o /swl:crear-skill para generar evoluciones primero.
+```
+
+## Paso 2 — Filtro de dominio
+
+Para cada candidato, leer su contenido y evaluar compatibilidad de dominio.
+
+**Pregunta de filtro**: *¿Le sirve esto a un ingeniero de software en cualquier proyecto de software?*
+
+**Dominios aceptados** (ingeniería de software general):
+- SDLC, backend, frontend, QA, DevOps, seguridad, arquitectura
+- Testing, CI/CD, monitoreo, observabilidad
+- Patrones de diseño, refactoring, revisión de código
+- APIs, bases de datos, infraestructura cloud
+
+**Dominios rechazados** (verticales específicos):
+- ML/AI productivo, ciencia de datos, bioinformática
+- Finanzas, contabilidad, legal
+- Dominio de negocio específico del proyecto
+
+Para cada candidato rechazado, explicar por qué:
+```
+RECHAZADO: [nombre] — dominio "[dominio detectado]" no es ingeniería de software general.
+Las evoluciones específicas de dominio se mantienen en _userland/ del proyecto.
+```
+
+## Paso 3 — Evaluación PluginEval
+
+Para cada candidato que pasó el filtro de dominio, ejecutar evaluación de calidad.
+
+Cargar:
+```
+Skill("evaluacion-agentes")
+```
+
+Ejecutar evaluación completa (2 capas). El score mínimo para contribuir es **80/100** (badge Oro).
+
+- **Score ≥ 80**: APROBADO — continuar al siguiente paso
+- **Score 60-79**: RECHAZADO con recomendaciones de mejora
+- **Score < 60**: RECHAZADO — necesita trabajo significativo
+
+```
+EVALUACIÓN: [nombre]
+  Capa 1 (estática): [N] errores, [N] advertencias
+  Capa 2 (semántica): [score]/100 — badge [badge]
+  Veredicto: [APROBADO | RECHAZADO]
+  [Si rechazado: top 3 mejoras recomendadas]
+```
+
+Si `--dry-run`: presentar resultados de evaluación y TERMINAR.
+
+## Paso 4 — Preparar contribución
+
+Para cada candidato aprobado:
+
+1. **Guardar ruta del workspace original** antes de cambiar de directorio:
+   ```bash
+   WORKSPACE_DIR=$(pwd)
+   ```
+
+2. **Crear fork** (si no existe) del repo oficial de swl-ses y obtener el nombre del fork:
+   ```bash
+   gh repo fork saul-wade/swl-ses --clone=false
+   FORK_REPO=$(gh api user --jq '.login')/swl-ses
+   ```
+
+3. **Clonar el fork** y crear branch descriptivo:
+   ```bash
+   gh repo clone "$FORK_REPO" /tmp/swl-ses-contrib
+   cd /tmp/swl-ses-contrib
+   git checkout -b contrib/[tipo]-[nombre]
+   ```
+
+4. **Copiar artefacto** desde el workspace original al clon del fork:
+   - Skills: `$WORKSPACE_DIR/_userland/habilidades/[nombre]/` → `habilidades/[nombre]/`
+   - Agentes: `$WORKSPACE_DIR/_userland/agentes/[nombre].md` → `agentes/[nombre].md`
+
+4. **Ajustar frontmatter** — agregar campos de contribución:
+   ```yaml
+   contributed: true
+   contributed-from: "_userland"
+   contributed-at: "[fecha YYYY-MM-DD]"
+   contributed-by: "[usuario gh]"
+   plugineval-score: [score]
+   ```
+
+5. **Registrar en plugin.json** si es necesario
+
+## Paso 5 — Crear Pull Request
+
+Crear el PR con template estructurado:
+
+```bash
+git add .
+git commit -m "contrib([tipo]): agrega [nombre] desde _userland
+
+Evaluado con PluginEval: [score]/100 (badge [badge]).
+Dominio: ingeniería de software general.
+
+Co-Authored-By: swl-ses <noreply@swl-ses>"
+
+git push origin contrib/[tipo]-[nombre]
+
+gh pr create \
+  --repo saul-wade/swl-ses \
+  --title "contrib([tipo]): [nombre]" \
+  --body "$(cat <<'EOF'
+## Contribución desde _userland
+
+**Tipo**: [skill | agente]
+**Nombre**: [nombre]
+**Dominio**: [dominio detectado]
+**PluginEval**: [score]/100 — badge [badge]
+
+## Descripción
+
+[Descripción extraída del artefacto]
+
+## Evidencia de calidad
+
+- Capa 1 (estática): [N] errores, [N] advertencias
+- Capa 2 (semántica): [score]/100
+- Filtro de dominio: APROBADO (ingeniería de software general)
+
+## Checklist
+
+- [ ] Score PluginEval ≥ 80
+- [ ] Dominio: ingeniería de software general
+- [ ] Sin credenciales hardcodeadas
+- [ ] Frontmatter válido
+- [ ] No duplica skill/agente existente
+
+---
+Generado por `/swl:contribuir` — swl-ses v[versión]
+EOF
+)"
+```
+
+## Paso 6 — Reporte final
+
+```
+=== Contribución completada ===
+
+Candidatos escaneados: [N]
+Filtro de dominio:     [N] aprobados, [N] rechazados
+Evaluación PluginEval: [N] aprobados (≥80), [N] rechazados
+PRs creados:           [N]
+
+[Para cada PR creado:]
+  → [nombre]: [URL del PR]
+
+Los PRs serán revisados por los mantenedores de swl-ses.
+```
+
+## Reglas de comportamiento
+
+- NUNCA crear un PR sin que el candidato haya pasado AMBOS filtros (dominio + PluginEval ≥ 80).
+- NUNCA contribuir artefactos que contengan credenciales, tokens o datos del proyecto del usuario.
+- NUNCA modificar artefactos del core existente — solo agregar nuevos.
+- Si el artefacto duplica funcionalidad de uno existente en el core, RECHAZAR y sugerir `/swl:evolucionar` en su lugar.
+- Si `gh auth status` falla, DETENER inmediatamente — no intentar autenticación automática.
+- En `--dry-run`, el reporte debe ser completo y accionable sin crear ningún PR.
+- Los artefactos contribuidos mantienen su autoría original (campo `contributed-by`).
+- SIEMPRE verificar que el nombre del artefacto no colisione con uno existente en el core antes de crear el PR.