@saulwade/swl-ses 1.0.0

package/comandos/swl/evaluar-skill.md

@@ -0,0 +1,487 @@
+---
+name: swl:evaluar-skill
+description: Evalúa la calidad de un agente o skill SWL con 10 dimensiones, detecta anti-patrones y asigna badge de calidad (Platino/Oro/Plata/Bronce). Ejecutar antes de hacer merge de agentes o skills nuevas.
+argument-hint: <nombre-skill-o-agente> [--agente]
+allowed_tools: ["Read", "Bash", "Glob", "Grep"]
+---
+
+# /swl:evaluar-skill — Evaluación de calidad de skills y agentes SWL
+
+Evalúa la calidad de una skill o agente SWL con un framework de 2 capas. La
+**Capa 1** usa verificaciones deterministas (análisis estático con herramientas
+del sistema). La **Capa 2** es evaluación semántica profunda realizada por el
+propio modelo al leer el contenido completo.
+
+Al finalizar, emite un reporte con score por dimensión, badge asignado y
+recomendaciones priorizadas de mejora.
+
+## Uso
+
+```
+/swl:evaluar-skill django-experto           — Evalúa la skill habilidades/django-experto/SKILL.md
+/swl:evaluar-skill backend-python-swl --agente  — Evalúa el agente agentes/backend-python-swl.md
+/swl:evaluar-skill                          — Lista skills disponibles y pide que se especifique
+```
+
+## Paso 0 — Resolver argumento
+
+Si no se pasa argumento, listar las opciones disponibles y detenerse:
+
+```bash
+echo "=== SKILLS DISPONIBLES ===" && ls -d habilidades/*/ 2>/dev/null | xargs -I{} basename {} | sort
+echo "=== AGENTES DISPONIBLES ===" && ls agentes/*.md 2>/dev/null | xargs -I{} basename {} .md | sort
+```
+
+Informar al usuario que especifique el nombre y si es agente agregar `--agente`.
+
+Si se pasa argumento sin `--agente`, buscar en `habilidades/<nombre>/SKILL.md`.
+Si el argumento incluye `--agente`, buscar en `agentes/<nombre>.md` (quitar el flag del nombre).
+
+Si el archivo no existe, informar y terminar:
+
+```
+No se encontró: habilidades/<nombre>/SKILL.md
+Verifica el nombre con /swl:evaluar-skill (sin argumentos) para ver las opciones.
+```
+
+## Paso 1 — Capa 1: Análisis estático
+
+Ejecutar todas las verificaciones deterministas. Registrar cada error (E0XX) y
+advertencia (W0XX) encontrado. No usar juicio subjetivo en esta capa.
+
+### 1.1 Verificaciones de frontmatter
+
+```bash
+SKILL_FILE="habilidades/<nombre>/SKILL.md"  # o agentes/<nombre>.md
+
+# Extraer frontmatter
+head -30 "$SKILL_FILE"
+
+# Verificar YAML válido del frontmatter (entre los ---) usando Python
+python3 -c "
+import sys, re
+content = open('$SKILL_FILE').read()
+match = re.match(r'^---\n(.*?)\n---', content, re.DOTALL)
+if not match:
+    print('E001 YAML_INVALIDO: no se encontró bloque frontmatter')
+    sys.exit(1)
+import yaml
+try:
+    data = yaml.safe_load(match.group(1))
+    print('YAML OK:', list(data.keys()) if data else 'vacío')
+except Exception as e:
+    print('E001 YAML_INVALIDO:', e)
+" 2>/dev/null || echo "E001 YAML_INVALIDO"
+```
+
+Verificar campo `name`:
+```bash
+grep -m1 "^name:" "$SKILL_FILE" || echo "E002 NAME_AUSENTE"
+```
+
+Verificar campo `description`:
+```bash
+desc=$(grep -m1 "^description:" "$SKILL_FILE" | sed 's/^description:[[:space:]]*//')
+[ -z "$desc" ] && echo "E003 DESCRIPTION_AUSENTE" || echo "description OK: ${#desc} chars"
+```
+
+Verificar formato kebab-case de `name`:
+```bash
+name_val=$(grep -m1 "^name:" "$SKILL_FILE" | sed 's/^name:[[:space:]]*//')
+echo "$name_val" | grep -qE '^[a-z0-9][a-z0-9-]*$' || echo "E004 NAME_FORMATO: '$name_val' no es kebab-case"
+```
+
+Verificar longitud de `name` (máx 64 caracteres):
+```bash
+name_len=$(grep -m1 "^name:" "$SKILL_FILE" | sed 's/^name:[[:space:]]*//' | wc -c)
+[ "$name_len" -gt 64 ] && echo "E005 NAME_LONGITUD: $name_len chars" || echo "name length OK"
+```
+
+Verificar que `name` no use términos reservados:
+```bash
+name_val=$(grep -m1 "^name:" "$SKILL_FILE" | sed 's/^name:[[:space:]]*//')
+echo "$name_val" | grep -qiE '(anthropic|claude|swl|^tests?$|testing)' && echo "E006 NAME_RESERVADO: '$name_val'" || echo "name reservado OK"
+```
+
+Verificar coincidencia entre `name` y nombre del directorio (solo para skills):
+```bash
+dir_name="<nombre>"
+name_val=$(grep -m1 "^name:" "$SKILL_FILE" | sed 's/^name:[[:space:]]*//')
+[ "$name_val" != "$dir_name" ] && echo "E007 NAME_DIRECTORIO: name='$name_val' != dir='$dir_name'" || echo "name/dir OK"
+```
+
+Verificar longitud de `description` (máx 1,024 caracteres):
+```bash
+desc_len=$(grep -m1 "^description:" "$SKILL_FILE" | sed 's/^description:[[:space:]]*//' | wc -c)
+[ "$desc_len" -gt 1024 ] && echo "E008 DESCRIPTION_LONGITUD: $desc_len chars" || echo "description length OK"
+```
+
+### 1.2 Verificaciones de contenido
+
+Verificar presencia de trigger "Cargar cuando" o "Invocar cuando":
+```bash
+grep -qi "Cargar cuando\|Invocar cuando" "$SKILL_FILE" || echo "E009 MISSING_TRIGGER"
+```
+
+Verificar referencias a recursos internos:
+```bash
+# Encontrar referencias a recursos/X.md dentro del SKILL.md
+grep -oE 'recursos/[^)"\s]+\.md' "$SKILL_FILE" | while read ref; do
+  dir=$(dirname "$SKILL_FILE")
+  [ ! -f "$dir/$ref" ] && echo "E010 REFERENCIA_ROTA: $ref"
+done
+echo "referencias OK"
+```
+
+### 1.3 Verificaciones de advertencias
+
+Verificar si la skill supera 300 líneas:
+```bash
+lines=$(wc -l < "$SKILL_FILE")
+[ "$lines" -gt 300 ] && echo "W001 BLOATED_SKILL: $lines líneas (máx 300)" || echo "W001 OK: $lines líneas"
+```
+
+Verificar uso excesivo de directivas absolutas:
+```bash
+count=$(grep -cE '\bMUST\b|\bALWAYS\b|\bNEVER\b|\bNUNCA\b|\bSIEMPRE\b' "$SKILL_FILE" || echo 0)
+[ "$count" -gt 15 ] && echo "W002 OVER_CONSTRAINED: $count ocurrencias" || echo "W002 OK: $count ocurrencias"
+```
+
+Verificar archivos huérfanos en recursos/:
+```bash
+skill_dir=$(dirname "$SKILL_FILE")
+if [ -d "$skill_dir/recursos" ]; then
+  for rec in "$skill_dir/recursos/"*.md; do
+    base=$(basename "$rec")
+    grep -q "$base" "$SKILL_FILE" || echo "W003 HUERFANO: recursos/$base no referenciado"
+  done
+fi
+```
+
+Verificar presencia de ejemplos de código si la skill cubre implementación:
+```bash
+code_blocks=$(grep -c '```' "$SKILL_FILE" || echo 0)
+[ "$code_blocks" -eq 0 ] && echo "W004 SIN_EJEMPLO_CODIGO: cero bloques de código" || echo "W004 OK: $code_blocks delimitadores de bloque"
+```
+
+Verificar sección de "cuándo NO usar":
+```bash
+grep -qi "cuándo no\|cuando no\|no usar\|no cargar\|no invocar" "$SKILL_FILE" || echo "W005 SIN_CUANDO_NO_USAR"
+```
+
+Verificar presencia de sección Gotchas o equivalente:
+```bash
+# W008: skills sin sección Gotchas
+# Penalización inicial suave (-5) durante período de migración de Fase 3.
+# Tras la migración se promoverá a -12 para hacer la sección obligatoria.
+grep -qi "Gotcha\|Errores comunes\|trampas\|Errores no obvios\|Fallas conocidas" "$SKILL_FILE" || \
+  echo "W008 SIN_GOTCHAS: skill sin seccion Gotchas (penalizacion -5 en robustness)"
+```
+
+Verificar uso de campos legacy en inglés (sin alias en español):
+```bash
+# W010: uso de campos legacy (inglés) sin alias en español (penalización -6 en robustness)
+# Promovido 2026-04-24 tras v5.11.2 (2 releases desde introducción) — período de gracia concluido.
+node -e "
+const fs = require('fs');
+const norm = require('./scripts/lib/skill-normalizer.js');
+const raw = fs.readFileSync(process.argv[1], 'utf8');
+const match = raw.match(/^---\n([\s\S]*?)\n---/);
+if (!match) process.exit(0);
+const fm = {};
+for (const linea of match[1].split(/\r?\n/)) {
+  const m = linea.match(/^(\w[\w_-]*):\s*(.+)\$/);
+  if (m) fm[m[1]] = m[2];
+}
+const legacy = norm.detectarUsoLegacy(fm);
+const divergente = norm.detectarDivergencias(fm);
+[...legacy, ...divergente].forEach(w => process.stderr.write(w.mensaje + '\n'));
+" "\$SKILL_FILE" 2>&1 | grep W010 || echo "W010 OK: sin campos legacy"
+```
+
+Verificar justificación en directivas absolutas:
+```bash
+# W009: directivas absolutas sin justificación
+# Si hay más de 3 directivas MUST/ALWAYS/NEVER/NUNCA/SIEMPRE y ninguna está
+# acompañada de palabras justificativas en la misma línea o la siguiente,
+# el modelo obedece pero no puede generalizar a casos edge.
+directive_count=$(grep -cE '\bMUST\b|\bALWAYS\b|\bNEVER\b|\bNUNCA\b|\bSIEMPRE\b' "$SKILL_FILE" || echo 0)
+if [ "$directive_count" -gt 3 ]; then
+  justified=$(grep -E '\bMUST\b|\bALWAYS\b|\bNEVER\b|\bNUNCA\b|\bSIEMPRE\b' "$SKILL_FILE" | \
+    grep -ciE 'porque|ya que|para evitar|si no|since|because|para que' || echo 0)
+  [ "$justified" -eq 0 ] && echo "W009 DIRECTIVAS_SIN_JUSTIFICACION: $directive_count directivas absolutas sin palabras justificativas (penalizacion -8 en output_quality)" || echo "W009 OK: $justified/$directive_count directivas con justificacion"
+fi
+```
+
+### 1.4 Resumen de Capa 1
+
+Tabular todos los errores y advertencias encontrados. Aplicar penalizaciones:
+
+| Código | Tipo | Penalización |
+|--------|------|-------------|
+| E001–E010 | ERROR | Dimensión relacionada → 0 |
+| W001 | ADVERTENCIA | -8 en `progressive_disclosure` |
+| W002 | ADVERTENCIA | -5 en `scope_calibration` |
+| W003 | ADVERTENCIA | -3 en `structural_completeness` |
+| W004 | ADVERTENCIA | -10 en `code_template_quality` |
+| W005 | ADVERTENCIA | -5 en `scope_calibration` |
+| W008 | ADVERTENCIA | -5 en `robustness` (período de migración; se promoverá a -12 tras Fase 3) |
+| W009 | ADVERTENCIA | -8 en `output_quality` |
+| W010 | ADVERTENCIA | -6 en `robustness` (promovido 2026-04-24 tras v5.11.2; período de migración concluido — campos en español SWL son ahora esperados) |
+
+Mapeo de errores a dimensiones afectadas:
+- E001, E002, E003, E008 → `structural_completeness`
+- E004, E005, E006, E007 → `ecosystem_coherence`
+- E009 → `triggering_accuracy`
+- E010 → `structural_completeness`
+
+### 1.5 Métricas cuantitativas de calidad
+
+Calcular métricas de eficiencia de tokens y duplicación:
+
+```bash
+SKILL_FILE="habilidades/<nombre>/SKILL.md"
+
+# Estimar tokens del skill
+node -e "
+const { estimateTokens } = require('./hooks/lib/token-budget');
+const fs = require('fs');
+const content = fs.readFileSync('$SKILL_FILE', 'utf8');
+const tokens = estimateTokens(content, 'mixed');
+const lines = content.split('\n').length;
+const ratio = (tokens / lines).toFixed(1);
+console.log('TOKENS: ' + tokens);
+console.log('LINEAS: ' + lines);
+console.log('DENSIDAD: ' + ratio + ' tokens/línea');
+console.log(tokens > 5000 ? 'W006 TOKEN_EXCESIVO: ' + tokens + ' tokens (máx 5000)' : 'tokens OK');
+"
+```
+
+Detección de duplicación con otros skills del sistema:
+
+```bash
+# Comparar contenido con skills del mismo dominio
+node -e "
+const { jaccardSimilarity } = require('./hooks/lib/fingerprint-id');
+const fs = require('fs');
+const path = require('path');
+const target = fs.readFileSync('$SKILL_FILE', 'utf8');
+const skillsDir = 'habilidades';
+const dirs = fs.readdirSync(skillsDir, {withFileTypes:true}).filter(d=>d.isDirectory());
+const results = [];
+for (const d of dirs) {
+  const p = path.join(skillsDir, d.name, 'SKILL.md');
+  if (p === '$SKILL_FILE' || !fs.existsSync(p)) continue;
+  const content = fs.readFileSync(p, 'utf8');
+  const sim = jaccardSimilarity(target, content);
+  if (sim > 0.3) results.push({name: d.name, similarity: (sim*100).toFixed(1)});
+}
+results.sort((a,b) => b.similarity - a.similarity);
+if (results.length > 0) {
+  console.log('SIMILITUD con otros skills:');
+  results.slice(0,5).forEach(r => {
+    const flag = r.similarity > 50 ? ' W007 DUPLICADO_POTENCIAL' : '';
+    console.log('  ' + r.name + ': ' + r.similarity + '%' + flag);
+  });
+} else {
+  console.log('Sin duplicación detectada con otros skills.');
+}
+"
+```
+
+Mapeo de advertencias nuevas:
+
+| Código | Tipo | Penalización |
+|--------|------|-------------|
+| W006 | ADVERTENCIA | -8 en `token_efficiency` |
+| W007 | ADVERTENCIA | -10 en `orchestration_fitness` (posible duplicación) |
+
+## Paso 2 — Capa 2: Evaluación semántica
+
+Leer el archivo completo con `Read`. Evaluar cada dimensión de 0 a 100 con
+criterio honesto: si la skill tiene problemas reales, el score debe reflejarlos.
+
+### Tabla de dimensiones
+
+| Dimensión | Peso | Qué medir |
+|-----------|------|-----------|
+| `triggering_accuracy` | 25% | ¿La `description` activa la skill en los momentos correctos? ¿El trigger es ni muy amplio ni muy estrecho? ¿Evita activaciones falsas? |
+| `orchestration_fitness` | 20% | ¿Coordina bien con otras skills del sistema? ¿Invoca correctamente otras skills con `Skill("nombre")`? ¿Evita duplicar contenido de otras skills? |
+| `output_quality` | 15% | ¿Los ejemplos de código son reales y funcionales? ¿Las reglas son específicas, no genéricas? ¿El contenido refleja patrones idiomáticos del framework? ¿Las directivas MUST/ALWAYS/NEVER/NUNCA/SIEMPRE incluyen justificación de por qué la regla existe? Una directiva sin justificación no permite al modelo generalizar a casos edge (ver W009). |
+| `scope_calibration` | 12% | ¿El scope es coherente? ¿No cubre demasiado? ¿Hay sección de "cuándo NO usar"? ¿El contenido es específico del dominio declarado? |
+| `progressive_disclosure` | 10% | ¿El SKILL.md principal es conciso (< 300 líneas)? ¿El contenido extenso está en `recursos/`? ¿Las referencias a recursos son claras y útiles? |
+| `token_efficiency` | 6% | ¿Hay contenido redundante o repetitivo? ¿Los ejemplos son concisos pero completos? ¿Se evita documentación genérica que no agrega valor? |
+| `robustness` | 5% | ¿Documenta casos edge y anti-patrones? ¿Cubre los errores más comunes del dominio? |
+| `structural_completeness` | 3% | ¿Tiene todas las secciones mínimas requeridas? ¿El frontmatter tiene todos los campos obligatorios? |
+| `code_template_quality` | 2% | ¿Los ejemplos de código compilan/ejecutan? ¿Usan sintaxis actual del lenguaje o framework? |
+| `ecosystem_coherence` | 2% | ¿El naming sigue las convenciones del sistema SWL (kebab-case)? ¿Los patrones son consistentes con las otras skills? |
+
+**Guía de calibración de scores:**
+- 90-100: Excelente — referente del sistema
+- 80-89: Sólido — listo para uso en producción
+- 70-79: Funcional — mejoras menores posibles
+- 60-69: Aceptable — requiere revisión antes de merge
+- 40-59: Deficiente — problemas claros que afectan efectividad
+- 0-39: Insuficiente — necesita reescritura
+
+## Paso 3 — Cálculo del score final
+
+Calcular score ponderado:
+
+```
+score_final = Σ(score_dimensión × peso_dimensión)
+
+Ejemplo:
+  triggering_accuracy    = 85 × 0.25 = 21.25
+  orchestration_fitness  = 78 × 0.20 = 15.60
+  output_quality         = 90 × 0.15 = 13.50
+  scope_calibration      = 72 × 0.12 =  8.64
+  progressive_disclosure = 80 × 0.10 =  8.00
+  token_efficiency       = 70 × 0.06 =  4.20
+  robustness             = 65 × 0.05 =  3.25
+  structural_completeness= 95 × 0.03 =  2.85
+  code_template_quality  = 85 × 0.02 =  1.70
+  ecosystem_coherence    = 90 × 0.02 =  1.80
+  ─────────────────────────────────────────────
+  score_final = 80.79
+```
+
+Asignar badge:
+
+```
+≥ 90  → Platino  — production-ready, puede usarse como referencia
+≥ 80  → Oro      — listo para merge
+≥ 70  → Plata    — necesita mejoras menores antes del merge
+≥ 60  → Bronce   — requiere revisión antes de merge
+< 60  → Sin badge — no hacer merge hasta corregir
+```
+
+## Paso 4 — Emitir reporte
+
+Generar el siguiente reporte directamente en la conversación:
+
+```markdown
+## Evaluación de skill: [nombre]
+**Archivo**: habilidades/[nombre]/SKILL.md  (o agentes/[nombre].md)
+**Fecha**: [fecha actual]
+
+### Capa 1 — Análisis estático
+
+[PASS si no hay errores ni advertencias]
+[O listar cada E0XX / W0XX con descripción breve]
+
+### Capa 2 — Evaluación semántica
+
+| Dimensión | Peso | Score | Contribución |
+|-----------|------|-------|-------------|
+| Triggering accuracy | 25% | XX/100 | XX.XX |
+| Orchestration fitness | 20% | XX/100 | XX.XX |
+| Output quality | 15% | XX/100 | XX.XX |
+| Scope calibration | 12% | XX/100 | XX.XX |
+| Progressive disclosure | 10% | XX/100 | XX.XX |
+| Token efficiency | 6% | XX/100 | XX.XX |
+| Robustness | 5% | XX/100 | XX.XX |
+| Structural completeness | 3% | XX/100 | XX.XX |
+| Code template quality | 2% | XX/100 | XX.XX |
+| Ecosystem coherence | 2% | XX/100 | XX.XX |
+
+**Score final: XX.XX/100 — Badge: [🏆/🥇/🥈/🥉/❌] [Platino/Oro/Plata/Bronce/Sin badge]**
+
+### Hallazgos principales
+
+**Fortalezas:**
+- [2-3 aspectos bien ejecutados con evidencia específica del contenido]
+
+**Áreas de mejora:**
+- [hallazgos específicos con sugerencia concreta y línea o sección afectada]
+
+### Recomendaciones para subir el score
+
+[Lista priorizada de cambios concretos que mejorarían el score,
+ordenados de mayor a menor impacto. Incluir la dimensión afectada.]
+```
+
+## Paso 3 — Capa 3 opcional: Evals estructurados
+
+Si el artefacto tiene un archivo de evals en formato `skill-evals.schema.json`:
+
+```bash
+EVALS_PATH="habilidades/<nombre>/evals/evals.json"
+[ -f "$EVALS_PATH" ] && echo "EVALS_DISPONIBLES" || EVALS_PATH="agentes/evals/<nombre>.evals.json"
+[ -f "$EVALS_PATH" ] && echo "EVALS_DISPONIBLES" || echo "SIN_EVALS"
+```
+
+Si existen, ejecutar la Capa 3:
+
+### 3.1 — Validar el artefacto contra el schema
+
+```bash
+# Validación mínima de estructura (zero-deps): comprobar que es JSON válido y
+# que tiene los campos obligatorios. Validación completa del schema queda para
+# consumidores externos (ajv, etc.) — SWL no arrastra deps.
+node -e "
+  const ev = require('./$EVALS_PATH');
+  const req = ['skill_name','schema_version','evals'];
+  const missing = req.filter(k => !(k in ev));
+  if (missing.length) { console.error('FALTAN:', missing.join(',')); process.exit(1); }
+  if (!Array.isArray(ev.evals) || ev.evals.length === 0) { console.error('evals vacío'); process.exit(1); }
+  console.log('OK', ev.evals.length, 'evals');
+"
+```
+
+Si falla la validación, reportar y continuar solo con Capa 1+2 (no bloquear).
+
+### 3.2 — Ejecutar cada eval contra el skill cargado
+
+Para cada `eval` del artefacto:
+
+1. Cargar el skill con `Skill("<nombre>")`.
+2. Enviar el `prompt` exacto al modelo en una respuesta aislada (sin historial).
+3. Capturar la respuesta.
+4. Para cada entrada de `expectations[]`, verificar si la respuesta la cumple
+   (match semántico honesto, no literal).
+5. Computar `pass = true` solo si TODAS las expectations se cumplen.
+6. Aplicar `weight` (default 1.0) al score.
+
+### 3.3 — Score de Capa 3
+
+```
+score_evals = sum(pass_i * weight_i) / sum(weight_i) * 100
+```
+
+### 3.4 — Integración con score final
+
+El score final combinado es:
+
+- Sin evals: `score_final = score_capa_1_2`
+- Con evals: `score_final = score_capa_1_2 * 0.7 + score_evals * 0.3`
+
+Reportar ambos separadamente para trazabilidad. Si `score_evals < 60`, marcar
+alerta: la skill puede ser declarativa pero falla en evaluación ejecutable.
+
+### 3.5 — Reporte por eval
+
+```
+| ID | Tags | Peso | Resultado | Expectations fallidas |
+|----|------|------|-----------|----------------------|
+| 0  | primary-flow | 1.0 | ✓ pass | — |
+| 1  | edge-case | 1.0 | ✗ fail | "La respuesta distingue X de Y" |
+| anti-pattern-substitution | anti-pattern,regression | 1.5 | ✓ pass | — |
+
+Score evals: 82.4/100 (peso 30% del final)
+```
+
+## Reglas de comportamiento
+
+- La Capa 1 es **determinista**: ejecutar los scripts Bash y registrar resultados exactos. No inferir ni interpretar.
+- La Capa 2 es **semántica honesta**: si la skill tiene problemas reales el score debe reflejarlos. No inflar scores por cortesía.
+- La Capa 3 es **opcional**: si no existe `evals/evals.json`, omitirla sin penalizar. Si existe, es autoridad primaria sobre Capa 2 en caso de discrepancia (los evals son reproducibles; la evaluación semántica no).
+- Un skill con Capa 3 activa y `score_evals ≥ 90` es candidato a badge **Platino** aunque Capa 2 sea 85.
+- Los evals NUNCA se inventan en este comando — solo se ejecutan los declarados por el autor del skill. Crear evals nuevos es tarea de `/swl:aprender` o del autor del skill directamente, siguiendo `plantillas/skill-evals-template.json`.
+- Si el archivo no existe, informar al usuario con el path exacto y terminar.
+- Si `--agente` se pasa sin nombre, listar los agentes disponibles y terminar.
+- El reporte siempre se emite en la conversación. No crear archivos.
+- Las "Fortalezas" deben ser específicas del contenido leído, no genéricas.
+- Las "Áreas de mejora" deben incluir la sección o línea aproximada donde se detectó el problema.
+- Si la Capa 1 genera errores E001–E010, reflejar el impacto en el score de la dimensión afectada antes de sumar las contribuciones ponderadas.
+- Score mínimo aprobado para merge: **80/100** (badge Oro). Por debajo de ese umbral, indicar claramente que **no está listo para merge**.

package/comandos/swl/evolucion-estado.md

@@ -0,0 +1,142 @@
+---
+name: swl:evolucion-estado
+description: Dashboard del ciclo de auto-evolución del sistema SWL. Muestra health_score compuesto, tasa de acción de nudges, densidad de instintos, fallos de agentes, evoluciones aplicadas/revertidas y alertas persistentes. Responde en una pantalla a "¿SWL está aprendiendo esta semana?".
+argument-hint: [--json | --dias=N | --regenerar]
+allowed_tools: ["Read", "Bash"]
+user-invocable: true
+version: "1.0.0"
+---
+
+# /swl:evolucion-estado — Dashboard del ciclo de evolución
+
+Emite un reporte compacto del estado de auto-evolución del sistema SWL en la
+ventana reciente (default 14 días). Su propósito: responder a la pregunta
+**"¿el sistema está aprendiendo?"** con datos, no impresiones.
+
+## Flags
+
+- `--json` → emite el JSON crudo de `metricas.json` (útil para pipes).
+- `--dias=N` → regenera métricas con ventana de N días (default 14).
+- `--regenerar` → fuerza recomputo ejecutando el hook `metricas-evolucion.js`.
+  Útil cuando no se ha disparado Stop recientemente.
+
+## Paso 0 — Asegurar métricas frescas
+
+Si se pasó `--regenerar` o `metricas.json` tiene > 24h:
+
+```bash
+PATH="/c/Program Files/nodejs:/c/Program Files (x86)/nodejs:$PATH" echo '{}' | node hooks/metricas-evolucion.js
+```
+
+## Paso 1 — Cargar métricas
+
+```bash
+cat .planning/evolucion/metricas.json
+```
+
+Si el archivo no existe: ejecutar el regenerado del Paso 0. Si sigue sin
+existir: reportar "el ciclo de evolución no ha corrido aún; ejecuta cualquier
+tarea para poblar métricas iniciales".
+
+## Paso 2 — Emitir el dashboard (formato humano)
+
+Template de salida:
+
+```
+═══════════════════════════════════════════════════════════════
+  SWL — Estado del ciclo de evolución
+  Ventana: últimos N días  ·  Generado: <ts>
+═══════════════════════════════════════════════════════════════
+
+  Health score:  <N>/100   <badge>
+
+  NUDGES
+    Emitidos .............. <total>
+    Accionados ............ <n>   (<tasa>%)
+    Pendientes ............ <n>
+    Por tipo:
+      perfil-usuario      <a>/<t>  (<%>)
+      auto-evolucion      <a>/<t>  (<%>)
+      consolidacion       <a>/<t>  (<%>)
+
+  INSTINTOS
+    Proyecto .............. <n>
+    Global ................ <n>
+    Perfil-usuario ........ <n>
+    Aprendizajes totales .. <n>
+
+  AGENTES (14d)
+    Runs totales .......... <n>
+    Fallos ................ <n>
+    Tasa de éxito ......... <%>
+
+  EVOLUCIONES (30d)
+    Aplicadas ............. <n>
+    Revertidas ............ <n>
+    Neta .................. <n>
+
+  ALERTAS PERSISTENTES
+    <si alertasActivas.length === 0>
+      Sin alertas.
+    <sino>
+      [!] kind=X target=Y count=Z (primera: fecha)
+      ...
+
+═══════════════════════════════════════════════════════════════
+```
+
+## Paso 3 — Calcular badge del health_score
+
+| Rango | Badge | Interpretación |
+|-------|-------|----------------|
+| ≥ 90 | 🏆 Óptimo | ciclo completo, cerrado y saludable |
+| ≥ 75 | 🥇 Saludable | funcionando con pequeñas mejoras pendientes |
+| ≥ 60 | 🥈 Parcial | hay piezas sin activar; revisar recomendaciones |
+| ≥ 40 | 🥉 Esqueleto | infraestructura existe pero poco uso real |
+| < 40 | ⚠️ Dormido | el ciclo no está corriendo |
+
+## Paso 4 — Recomendaciones contextuales
+
+Al final del dashboard, sugerir acciones según las métricas:
+
+- Si `instintos.proyecto === 0` y `aprendizajes_totales > 10`:
+  → `node scripts/bootstrap-instintos.js` (pobla desde APRENDIZAJES.md)
+
+- Si `nudges.tasaAccion < 0.3` y `nudges.total > 5`:
+  → "Muchos nudges ignorados. Revisa `.planning/evolucion/alertas-persistentes.json`"
+
+- Si `alertasActivas.length > 0`:
+  → listar cada alerta con `/swl:evolucionar <target>` o cmd correspondiente
+
+- Si `agentes.tasaExito < 70` y `totalRuns > 5`:
+  → "Agentes con tasa de éxito baja. Candidatos a `/swl:evolucionar`:
+     <top 3 de porAgente con más fallos>"
+
+- Si `evoluciones.revertidas > evoluciones.aplicadas / 2`:
+  → "Muchas evoluciones revertidas — revisar si el gate de regresión
+     está siendo demasiado laxo o si los evals son inconsistentes"
+
+- Si `health_score >= 90`:
+  → "Sistema en óptimo. Posible candidato a habilitar modo autónomo
+     de `auto-evolucion-swl`. Ver `agentes/auto-evolucion-swl.md` —
+     sección 'Autonomía condicional'"
+
+- Si `health_score < 95`:
+  → "Para subir el score, consultar `.planning/ROADMAP-EVOLUCION.md` —
+     documenta los 5 hitos por fase y cuánto aporta cada uno. Sin uso
+     operacional real (nudges accionados, runs reales, evoluciones), el
+     score no sube por infraestructura sola."
+
+## Anti-substitution guardrails
+
+- Archivo de métricas: **siempre** `.planning/evolucion/metricas.json` (nunca `.planning/metricas.json`, `evolucion.json`, `estado-evolucion.json`).
+- Hook que regenera: **siempre** `hooks/metricas-evolucion.js` (nunca `metrics.js`, `evolucion-metricas.js`, `evolution-metrics.js`).
+- Para forzar regen: pipe `echo '{}' | node ...`, nunca invocar `require()` directo.
+
+## Response Discipline
+
+Si el usuario pasa `--json`: respuesta = **contenido crudo del archivo**,
+sin prosa ni comentarios.
+
+Si no: dashboard formateado con las 5 secciones. Las recomendaciones del
+Paso 4 van al final, máximo 3 items priorizados. Sin repetir datos del dashboard.