@saulwade/swl-ses 2.3.0 → 2.4.1

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.

package/comandos/swl/deuda-codigo.md

@@ -0,0 +1,97 @@
+---
+name: swl:deuda-codigo
+description: Cosecha los marcadores `simplificado:` del código (simplificaciones deliberadas con techo y trigger de upgrade) hacia un ledger visible, detecta marcadores sin trigger (riesgo de rot) y sincroniza opcionalmente con .planning/DEUDA-TECNICA.md. Cargar cuando el usuario pida "qué simplificamos", "deuda de código", "cosecha los marcadores", o tras una fase que dejó marcadores simplificado:.
+allowed_tools: ["Grep", "Read", "Edit", "Bash"]
+---
+
+# /swl:deuda-codigo — Cosecha de simplificaciones deliberadas
+
+Todo atajo intencional marcado con `simplificado: <techo>, <trigger>` (convención
+de `Skill("prevencion-sobreingenieria")`, adaptada del patrón `ponytail:` de
+ponytail, MIT) se cosecha aquí en un ledger — para que un "después" no se
+convierta en "nunca" (regla `arreglar-al-detectar.md`).
+
+## Uso
+
+```
+/swl:deuda-codigo              — Reporte en pantalla (no escribe nada)
+/swl:deuda-codigo --sync       — Además sincroniza a .planning/DEUDA-TECNICA.md
+/swl:deuda-codigo --owners     — Agrega autor por marcador (git blame)
+/swl:deuda-codigo <directorio> — Limita la cosecha a un subárbol
+```
+
+## Paso 1 — Cosechar los marcadores
+
+Buscar con Grep (herramienta, no shell) el patrón sobre el árbol del proyecto,
+excluyendo `node_modules`, `.git`, `dist`, `build`, `temp`, `respositorios-git`:
+
+```
+Grep(pattern: "(#|//|--|<!--|/\\*)\\s?simplificado:", output_mode: "content", -n: true)
+```
+
+Cada hit es una fila del ledger. El prefijo de comentario evita capturar prosa
+que solo menciona la convención (como este archivo o el SKILL.md).
+
+## Paso 2 — Parsear techo y trigger
+
+La convención es `simplificado: <techo>, <trigger de upgrade>`:
+
+- **techo**: el límite conocido del atajo (lock global, O(n²), heurística naive).
+- **trigger**: la condición observable que obliga el upgrade ("si throughput > X",
+  "cuando haya un segundo consumidor", "antes del primer deploy productivo").
+
+Si el texto tras `simplificado:` no contiene una condición observable,
+etiquetar la fila `sin-trigger` — esos son los que rotan en silencio.
+
+## Paso 3 — Reporte
+
+Una fila por marcador, agrupado por archivo:
+
+```
+## Ledger de simplificaciones — [fecha]
+
+| Ubicación | Qué se simplificó | Techo | Trigger de upgrade | Estado |
+|---|---|---|---|---|
+| src/locks.py:42 | lock global | contención con N workers | throughput > 500 rps | ok |
+| api/cache.js:17 | TTL fijo 5 min | staleness | (ninguno) | sin-trigger |
+
+Total: N marcadores, M sin trigger.
+```
+
+Con `--owners`: agregar columna con `git blame -L<línea>,<línea> --porcelain <archivo>`
+(solo el autor, una llamada por fila).
+
+Si no hay marcadores: `Sin deuda simplificado:. Ledger limpio.` — y terminar.
+
+## Paso 4 — Sincronizar al ledger formal (solo con --sync)
+
+Para cada marcador `sin-trigger` o de techo relevante que no exista ya en
+`.planning/DEUDA-TECNICA.md`:
+
+1. Leer el ledger actual y verificar duplicados por ubicación (`archivo:línea`).
+2. Agregar entrada `### DT-SIMPLIFICADO-<n>` con: ubicación, techo, trigger
+   (o `PENDIENTE DE TRIGGER` marcado como acción requerida), fecha de cosecha.
+3. Los `sin-trigger` NO se sincronizan como DT válidas hasta tener trigger:
+   reportarlos al usuario como acción inmediata — una DT sin trigger verificable
+   viola `arreglar-al-detectar.md § DT formal`.
+
+NUNCA borrar ni editar los marcadores del código durante la cosecha: el
+comando lee y reporta; el código solo cambia cuando el trigger se cumple y
+el upgrade se implementa.
+
+## Cuándo usarlo
+
+- Cierre de fase (`/swl:verificar` lo puede invocar como pasada complementaria).
+- Antes de un release: los `sin-trigger` son bloqueo blando (reportar en el gate).
+- Auditorías de deuda: junto con la sección "Sobre-ingeniería" de `/swl:revisar`.
+
+## Gotchas
+
+- **Marcadores en fixtures o docs**: los hits dentro de `tests/fixtures/`,
+  ejemplos de skills o este propio comando son material de referencia, no deuda
+  — excluirlos del conteo y decir cuántos se excluyeron (sin caps silenciosos).
+- **Prefijos de comentario por stack**: el patrón cubre `#` (Python/shell),
+  `//` (JS/TS/Go/Rust/C#/Java), `--` (SQL/Lua), `<!--` (HTML/MD) y `/*` (CSS/C).
+  Si el proyecto usa otro prefijo, agregarlo al patrón y decirlo en el reporte.
+- **`git blame` sobre archivos renombrados**: usar `git blame -M -C` si el
+  autor aparece como el commit del rename.