swl-ses 3.3.2

package/habilidades/validacion-ci-sistema/SKILL.md

@@ -0,0 +1,543 @@
+---
+name: validacion-ci-sistema
+description: Validación de integridad del sistema SWL inspirado en ECC CI stack. Cubre validación de frontmatter de agentes, validación de skills (SKILL.md presente y no vacío), validación de hooks (sintaxis Node.js, exit codes), validación de comandos, validación de reglas, catálogo automático con métricas y script ejecutable de validación.
+---
+
+# Validación e Integridad del Sistema SWL
+
+## Propósito
+
+El sistema SWL crece con el tiempo: nuevos agentes, skills, hooks, comandos
+y reglas se agregan continuamente. Sin validación, el sistema acumula:
+- Agentes con frontmatter incompleto que no se pueden invocar
+- Skills sin SKILL.md que el loader ignora silenciosamente
+- Hooks que fallan con códigos de salida incorrectos (bloqueando el flujo)
+- Comandos con formato inválido que producen errores crípticos
+
+Este skill define el sistema de validación de integridad del repositorio SWL.
+
+---
+
+## 1. Campos Obligatorios en Frontmatter de Agentes
+
+### Campos requeridos por familia
+
+```javascript
+// validation/schemas/agente.schema.js
+
+const CAMPOS_AGENTE = {
+  // Campos obligatorios para TODOS los agentes
+  obligatorios: ['name', 'description'],
+
+  // Campos opcionales con valores válidos
+  opcionales: {
+    model:          ['claude-opus-4-5', 'claude-sonnet-4-6', 'claude-haiku-3-5'],
+    permissionMode: ['default', 'acceptEdits', 'bypassPermissions', 'plan'],
+    color:          ['red', 'orange', 'yellow', 'green', 'blue', 'purple', 'cyan', 'white'],
+  },
+
+  // Campos que deben existir si existen otros
+  condicionales: {
+    // Si tiene 'tools', debe ser array de strings conocidos
+    tools: {
+      valoresPermitidos: [
+        'Read', 'Write', 'Edit', 'Bash', 'Grep', 'Glob',
+        'WebSearch', 'WebFetch', 'TodoRead', 'TodoWrite',
+        'Task', 'Skill', 'mcp__context7__resolve-library-id',
+        'mcp__context7__get-library-docs',
+      ],
+    },
+  },
+};
+```
+
+### Función de validación de agente
+
+```javascript
+// validation/validators/agente.validator.js
+import { parse } from 'yaml';
+import { readFileSync } from 'fs';
+
+export function validarAgente(rutaArchivo) {
+  const contenido = readFileSync(rutaArchivo, 'utf8');
+  const errores = [];
+
+  // Extraer frontmatter
+  const match = contenido.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) {
+    return [{ campo: 'frontmatter', error: 'No se encontró frontmatter YAML' }];
+  }
+
+  let frontmatter;
+  try {
+    frontmatter = parse(match[1]);
+  } catch (e) {
+    return [{ campo: 'frontmatter', error: `YAML inválido: ${e.message}` }];
+  }
+
+  // Campos obligatorios
+  for (const campo of CAMPOS_AGENTE.obligatorios) {
+    if (!frontmatter[campo] || String(frontmatter[campo]).trim() === '') {
+      errores.push({
+        campo,
+        error: `Campo obligatorio ausente o vacío: '${campo}'`,
+      });
+    }
+  }
+
+  // Validar description — mínimo 20 caracteres para ser útil
+  if (frontmatter.description && frontmatter.description.length < 20) {
+    errores.push({
+      campo: 'description',
+      error: `Description demasiado corta (${frontmatter.description.length} chars, mínimo 20)`,
+    });
+  }
+
+  // Campos opcionales con valores permitidos
+  for (const [campo, valoresPermitidos] of Object.entries(CAMPOS_AGENTE.opcionales)) {
+    if (frontmatter[campo] !== undefined) {
+      if (!valoresPermitidos.includes(frontmatter[campo])) {
+        errores.push({
+          campo,
+          error: `Valor inválido '${frontmatter[campo]}'. Permitidos: ${valoresPermitidos.join(', ')}`,
+        });
+      }
+    }
+  }
+
+  // Validar tools
+  if (frontmatter.tools) {
+    const toolsArray = String(frontmatter.tools).split(',').map(t => t.trim());
+    for (const tool of toolsArray) {
+      if (!CAMPOS_AGENTE.condicionales.tools.valoresPermitidos.includes(tool)) {
+        errores.push({
+          campo: 'tools',
+          error: `Tool desconocida: '${tool}'`,
+        });
+      }
+    }
+  }
+
+  // Validar nombre = nombre del archivo (kebab-case)
+  const nombreEsperado = path.basename(rutaArchivo, '.md');
+  if (frontmatter.name && frontmatter.name !== nombreEsperado) {
+    errores.push({
+      campo: 'name',
+      error: `name '${frontmatter.name}' no coincide con nombre de archivo '${nombreEsperado}'`,
+    });
+  }
+
+  return errores;
+}
+```
+
+---
+
+## 2. Validación de Skills
+
+### Reglas de validación de skill
+
+```javascript
+// validation/validators/skill.validator.js
+import { statSync, readFileSync } from 'fs';
+import path from 'path';
+
+export function validarSkill(directorioSkill) {
+  const errores = [];
+  const rutaSkill = path.join(directorioSkill, 'SKILL.md');
+
+  // Regla 1: SKILL.md debe existir
+  try {
+    statSync(rutaSkill);
+  } catch {
+    errores.push({
+      skill: path.basename(directorioSkill),
+      error: 'SKILL.md no encontrado en el directorio',
+    });
+    return errores;
+  }
+
+  const contenido = readFileSync(rutaSkill, 'utf8');
+
+  // Regla 2: No debe estar vacío
+  if (contenido.trim().length === 0) {
+    errores.push({ skill: path.basename(directorioSkill), error: 'SKILL.md está vacío' });
+    return errores;
+  }
+
+  // Regla 3: Frontmatter obligatorio
+  const match = contenido.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) {
+    errores.push({ skill: path.basename(directorioSkill), error: 'Sin frontmatter YAML' });
+    return errores;
+  }
+
+  let frontmatter;
+  try {
+    frontmatter = parse(match[1]);
+  } catch (e) {
+    errores.push({
+      skill: path.basename(directorioSkill),
+      error: `Frontmatter YAML inválido: ${e.message}`,
+    });
+    return errores;
+  }
+
+  // Regla 4: campos name y description obligatorios
+  if (!frontmatter.name) {
+    errores.push({ skill: path.basename(directorioSkill), error: "Falta campo 'name' en frontmatter" });
+  }
+  if (!frontmatter.description) {
+    errores.push({ skill: path.basename(directorioSkill), error: "Falta campo 'description' en frontmatter" });
+  }
+
+  // Regla 5: mínimo de contenido (100 líneas)
+  const lineas = contenido.split('\n').length;
+  if (lineas < 50) {
+    errores.push({
+      skill: path.basename(directorioSkill),
+      error: `SKILL.md demasiado corto (${lineas} líneas, mínimo recomendado 50)`,
+      severidad: 'advertencia',
+    });
+  }
+
+  return errores;
+}
+```
+
+---
+
+## 3. Validación de Hooks
+
+### Reglas de hooks
+
+```javascript
+// validation/validators/hook.validator.js
+import { execSync } from 'child_process';
+
+export function validarHook(rutaHook) {
+  const errores = [];
+  const contenido = readFileSync(rutaHook, 'utf8');
+
+  // Regla 1: Sintaxis Node.js válida
+  try {
+    execSync(`node --check "${rutaHook}"`, { stdio: 'pipe' });
+  } catch (e) {
+    errores.push({
+      hook: path.basename(rutaHook),
+      error: `Sintaxis Node.js inválida: ${e.stderr?.toString().split('\n')[0]}`,
+    });
+    return errores;
+  }
+
+  // Regla 2: Siempre debe terminar con process.exit()
+  // Un hook que no tiene exit explícito puede quedar colgado
+  if (!contenido.includes('process.exit(')) {
+    errores.push({
+      hook: path.basename(rutaHook),
+      error: 'No tiene process.exit() explícito — puede quedar colgado',
+    });
+  }
+
+  // Regla 3: Hooks de observación nunca deben usar exit(1) o exit(2)
+  // (solo permitido en hooks de blocking/validation)
+  const esObservacion = rutaHook.includes('observe');
+  if (esObservacion && contenido.includes('process.exit(1)')) {
+    errores.push({
+      hook: path.basename(rutaHook),
+      error: 'Hook de observación no debe usar exit(1) — bloquearía el flujo del agente',
+    });
+  }
+
+  // Regla 4: Debe leer stdin si es hook Pre/PostToolUse
+  const esToolHook = rutaHook.match(/pre-|post-|observe/i);
+  if (esToolHook && !contenido.includes('stdin') && !contenido.includes('readFileSync')) {
+    errores.push({
+      hook: path.basename(rutaHook),
+      error: 'Hook de herramienta no lee stdin — no puede acceder al contexto del evento',
+      severidad: 'advertencia',
+    });
+  }
+
+  // Regla 5: Timeout implícito — hooks no deben hacer operaciones que puedan colgar
+  if (contenido.includes('execSync') && !contenido.includes('timeout')) {
+    errores.push({
+      hook: path.basename(rutaHook),
+      error: 'execSync sin timeout — puede bloquear indefinidamente',
+      severidad: 'advertencia',
+    });
+  }
+
+  return errores;
+}
+```
+
+### Tabla de exit codes esperados por tipo de hook
+
+| Tipo de Hook | Exit 0 | Exit 1 | Exit 2 |
+|-------------|--------|--------|--------|
+| Observación (PreToolUse/PostToolUse) | Continuar siempre | PROHIBIDO | PROHIBIDO |
+| Validación (PreToolUse bloqueante) | Permitir herramienta | Bloquear con mensaje | — |
+| Notificación (Stop/SubagentStop) | Notificado OK | Fallo notificación (ignorar) | — |
+| Transformación (PostToolUse) | Output aceptado | Fallo (ignorar output) | — |
+
+---
+
+## 4. Validación de Comandos
+
+```javascript
+// validation/validators/comando.validator.js
+
+export function validarComando(directorioComando) {
+  const errores = [];
+  const nombreComando = path.basename(directorioComando);
+
+  // Regla 1: Debe existir command.md o index.md
+  const archivosPermitidos = ['command.md', `${nombreComando}.md`, 'index.md'];
+  const archivosEncontrados = archivosPermitidos.filter(f =>
+    existsSync(path.join(directorioComando, f))
+  );
+
+  if (archivosEncontrados.length === 0) {
+    errores.push({
+      comando: nombreComando,
+      error: `Ningún archivo de comando encontrado. Esperado: ${archivosPermitidos.join(' o ')}`,
+    });
+    return errores;
+  }
+
+  const rutaArchivo = path.join(directorioComando, archivosEncontrados[0]);
+  const contenido = readFileSync(rutaArchivo, 'utf8');
+
+  // Regla 2: Nombre en kebab-case
+  if (!/^[a-z][a-z0-9-]*[a-z0-9]$/.test(nombreComando)) {
+    errores.push({
+      comando: nombreComando,
+      error: `Nombre no está en kebab-case: '${nombreComando}'`,
+    });
+  }
+
+  // Regla 3: Si tiene frontmatter, debe ser válido
+  if (contenido.startsWith('---')) {
+    const match = contenido.match(/^---\n([\s\S]*?)\n---/);
+    if (!match) {
+      errores.push({ comando: nombreComando, error: 'Frontmatter YAML sin cerrar (falta ---)' });
+    }
+  }
+
+  // Regla 4: No debe estar vacío
+  const sinFrontmatter = contenido.replace(/^---[\s\S]*?---\n/, '').trim();
+  if (sinFrontmatter.length < 10) {
+    errores.push({ comando: nombreComando, error: 'Comando sin contenido de instrucciones' });
+  }
+
+  return errores;
+}
+```
+
+---
+
+## 5. Validación de Reglas
+
+```javascript
+// validation/validators/regla.validator.js
+
+export function validarReglas(directorioReglas) {
+  const errores = [];
+  const archivos = globSync('**/*.md', { cwd: directorioReglas, absolute: true });
+
+  // Regla 1: No reglas vacías
+  for (const ruta of archivos) {
+    const contenido = readFileSync(ruta, 'utf8').trim();
+    if (contenido.length < 20) {
+      errores.push({ regla: path.relative(directorioReglas, ruta), error: 'Regla vacía o demasiado corta' });
+    }
+  }
+
+  // Regla 2: Detectar posibles contradicciones (heurística)
+  // Una regla que diga "SIEMPRE X" y otra que diga "NUNCA X" en el mismo dominio
+  const contenidos = archivos.map(f => ({
+    nombre: path.basename(f, '.md'),
+    texto: readFileSync(f, 'utf8').toLowerCase(),
+  }));
+
+  for (let i = 0; i < contenidos.length; i++) {
+    for (let j = i + 1; j < contenidos.length; j++) {
+      const a = contenidos[i];
+      const b = contenidos[j];
+      // Extraer términos clave de reglas SIEMPRE/NUNCA
+      const siempresA = extraerTerminosSiempre(a.texto);
+      const nuncasB = extraerTerminosNunca(b.texto);
+      const conflictos = siempresA.filter(t => nuncasB.includes(t));
+      if (conflictos.length > 0) {
+        errores.push({
+          regla: `${a.nombre} ↔ ${b.nombre}`,
+          error: `Posible contradicción: SIEMPRE ${conflictos[0]} vs NUNCA ${conflictos[0]}`,
+          severidad: 'advertencia',
+        });
+      }
+    }
+  }
+
+  return errores;
+}
+```
+
+---
+
+## 6. Catálogo Automático (Métricas)
+
+```javascript
+// validation/catalogo.js
+
+export async function generarCatalogo(raizSistema) {
+  const ahora = new Date().toISOString();
+
+  const agentes  = globSync('agentes/**/*.md', { cwd: raizSistema });
+  const skills   = globSync('habilidades/*/SKILL.md', { cwd: raizSistema });
+  const hooks    = globSync('hooks/**/*.js', { cwd: raizSistema });
+  const comandos = globSync('comandos/*/', { cwd: raizSistema });
+  const reglas   = globSync('reglas/**/*.md', { cwd: raizSistema });
+
+  return {
+    generado_en: ahora,
+    totales: {
+      agentes:  agentes.length,
+      skills:   skills.length,
+      hooks:    hooks.length,
+      comandos: comandos.length,
+      reglas:   reglas.length,
+    },
+    agentes: agentes.map(a => ({
+      nombre: path.basename(a, '.md'),
+      ruta: a,
+      tamano_bytes: statSync(path.join(raizSistema, a)).size,
+    })),
+    skills: skills.map(s => ({
+      nombre: path.basename(path.dirname(s)),
+      ruta: s,
+      lineas: readFileSync(path.join(raizSistema, s), 'utf8').split('\n').length,
+    })),
+  };
+}
+```
+
+---
+
+## 7. Script de Validación Ejecutable
+
+```javascript
+#!/usr/bin/env node
+// scripts/validar-sistema.js
+// Uso: node scripts/validar-sistema.js [--fix] [--catalog]
+
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { globSync } from 'glob';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const RAIZ = path.resolve(__dirname, '..');
+
+const args = process.argv.slice(2);
+const MODO_FIX     = args.includes('--fix');
+const GENERAR_CAT  = args.includes('--catalog');
+
+let totalErrores = 0;
+let totalAdvert  = 0;
+
+function reporte(tipo, items, validador) {
+  console.log(`\n${'═'.repeat(50)}`);
+  console.log(`Validando ${tipo} (${items.length})...`);
+
+  for (const item of items) {
+    const errores = validador(item);
+    const criticos = errores.filter(e => e.severidad !== 'advertencia');
+    const advert   = errores.filter(e => e.severidad === 'advertencia');
+
+    if (criticos.length > 0) {
+      console.error(`  FAIL ${path.basename(item)}`);
+      criticos.forEach(e => console.error(`       ERROR: ${e.error}`));
+      totalErrores += criticos.length;
+    }
+    if (advert.length > 0) {
+      console.warn(`  WARN ${path.basename(item)}`);
+      advert.forEach(e => console.warn(`       WARN: ${e.error}`));
+      totalAdvert += advert.length;
+    }
+    if (criticos.length === 0 && advert.length === 0) {
+      console.log(`  OK   ${path.basename(item)}`);
+    }
+  }
+}
+
+// Ejecutar validaciones
+reporte('Agentes',   globSync('agentes/**/*.md', { cwd: RAIZ, absolute: true }), validarAgente);
+reporte('Skills',    globSync('habilidades/*', { cwd: RAIZ, absolute: true }),   validarSkill);
+reporte('Hooks',     globSync('hooks/**/*.js', { cwd: RAIZ, absolute: true }),   validarHook);
+reporte('Comandos',  globSync('comandos/*', { cwd: RAIZ, absolute: true }),      validarComando);
+
+// Resumen final
+console.log(`\n${'═'.repeat(50)}`);
+console.log(`RESUMEN: ${totalErrores} errores, ${totalAdvert} advertencias`);
+
+if (GENERAR_CAT) {
+  const catalogo = await generarCatalogo(RAIZ);
+  writeFileSync(
+    path.join(RAIZ, '.claude', 'catalogo.json'),
+    JSON.stringify(catalogo, null, 2),
+  );
+  console.log('Catálogo generado en .claude/catalogo.json');
+}
+
+// Exit code para CI
+process.exit(totalErrores > 0 ? 1 : 0);
+```
+
+### package.json — scripts de validación
+
+```json
+{
+  "scripts": {
+    "validate":         "node scripts/validar-sistema.js",
+    "validate:catalog": "node scripts/validar-sistema.js --catalog",
+    "validate:ci":      "node scripts/validar-sistema.js && echo 'Sistema íntegro'"
+  }
+}
+```
+
+### Uso en CI (GitHub Actions)
+
+```yaml
+# .github/workflows/validate-system.yml
+name: Validar integridad del sistema SWL
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: '20' }
+      - run: npm ci
+      - run: npm run validate:catalog
+      - uses: actions/upload-artifact@v4
+        with:
+          name: catalogo-sistema
+          path: .claude/catalogo.json
+```
+
+---
+
+## Anti-patrones
+
+- Agregar agentes sin los campos `name` y `description` (el loader los ignora)
+- Hooks con `process.exit(1)` en observaciones (bloquean el flujo del agente)
+- Skills con SKILL.md vacío o sin frontmatter (el Skill tool no puede cargarlos)
+- No ejecutar la validación antes de hacer commit de cambios al sistema
+- Ignorar advertencias acumuladas (se vuelven errores con el tiempo)
+- Comandos en snake_case o camelCase (deben ser kebab-case)