---
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.
version: "1.1.0"
herramientasPermitidas: [Read, Bash]
exclusiones:
  - "No cargar para validar el código de aplicación del usuario (tests, linting de Python/TS, cobertura) — este skill valida la integridad del sistema SWL (frontmatter de agentes, SKILL.md presentes, exit codes de hooks); para validación de código cargar `reglas/pruebas.md` o invocar `tdd-qa-swl`."
  - "No cargar para diagnosticar por qué un agente específico falló en una tarea — este skill detecta problemas estructurales del sistema SWL, no bugs en la lógica de un agente; para diagnóstico de agente usar `evaluacion-agentes`."
  - "No cargar si `/swl:status salud` acaba de ejecutarse sin errores — la validación CI es un subconjunto de lo que salud corre; no tiene sentido duplicarla en la misma sesión."
  - "No cargar para agregar un componente nuevo al sistema — primero crear el componente (agente, skill, hook) y luego ejecutar validación CI para verificarlo; no como guía de creación."
evolvable: true  # default para skill estandar
---
# Validación e Integridad del Sistema SWL

## Propósito

El sistema SWL crece con el tiempo. Sin validación, 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
- Comandos con formato inválido

## Precondición — solo aplica al repo host de SWL

Este skill valida los **componentes** del sistema SWL (`agentes/`, `habilidades/`,
`comandos/swl/`, `reglas/`, `hooks/`). Solo tiene sentido en el repo que los
**hospeda** (swl-ses o un fork). En un proyecto **consumidor** (usa las
convenciones SWL vía `~/.claude/` pero no aloja los componentes), no hay nada que
validar y un score de componentes sería engañoso. El gate determinista vive en
`/swl:status salud` (Paso 0):

```bash
node scripts/lib/detectar-host-swl.js --json
```

Si `esHost: false`, NO ejecutar este skill: reportar que `salud` no aplica y
redirigir a los subcomandos de `/swl:status` que sí aplican al proyecto consumidor.

---

## Reglas de Validación por Componente

### Agentes

- Campos OBLIGATORIOS: `name`, `description`
- `description` mínimo 20 caracteres
- `name` debe coincidir con nombre del archivo (kebab-case)
- `model`, `permissionMode`, `color`: solo valores permitidos
- `tools`: solo tools conocidas del sistema

### Skills

- `SKILL.md` DEBE existir y no estar vacío
- Frontmatter YAML con `name` y `description` obligatorios
- Mínimo 50 líneas de contenido

### Hooks

- Sintaxis Node.js válida (`node --check`)
- SIEMPRE tener `process.exit()` explícito
- Hooks de observación NUNCA usan `exit(1)` (bloquearía el flujo)
- `execSync` SIEMPRE con `timeout`
- Hooks Pre/PostToolUse DEBEN leer stdin

### Comandos

- Nombre en kebab-case estricto
- Archivo `command.md`, `{nombre}.md` o `index.md` presente
- Frontmatter YAML válido si existe
- Contenido de instrucciones no vacío

### Reglas

- Sin reglas vacías o menores a 20 caracteres
- Detección heurística de contradicciones SIEMPRE/NUNCA entre reglas

---

## Tabla de Exit Codes para Hooks

| Tipo de Hook | Exit 0 | Exit 1 | Exit 2 |
|-------------|--------|--------|--------|
| Observación (Pre/PostToolUse) | Continuar | PROHIBIDO | PROHIBIDO |
| Validación (PreToolUse bloqueante) | Permitir | Bloquear con mensaje | -- |
| Notificación (Stop/SubagentStop) | OK | Ignorar | -- |

---

## Ejecución

```bash
# Validar todo el sistema
node scripts/validar-sistema.js

# Validar y generar catálogo
node scripts/validar-sistema.js --catalog

# En CI
npm run validate:ci
```

El script ejecutable está en `scripts/validar-sistema.sh`.

### package.json scripts

```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'"
  }
}
```

---

## Anti-patrones

- Agentes sin `name` y `description` (el loader los ignora)
- Hooks con `process.exit(1)` en observaciones (bloquean el agente)
- Skills con SKILL.md vacío o sin frontmatter
- No ejecutar validación antes de commit
- Ignorar advertencias acumuladas
- Comandos en snake_case o camelCase

---

## Checklist

- [ ] `npm run validate` pasa sin errores
- [ ] Todos los agentes tienen `name` + `description`
- [ ] Todos los skills tienen `SKILL.md` con frontmatter
- [ ] Hooks tienen `process.exit()` explícito
- [ ] Hooks de observación no usan `exit(1)`
- [ ] Comandos en kebab-case

Para código fuente completo de todos los validadores (agentes, skills, hooks, comandos, reglas, catálogo), ver [recursos/validadores-completos.md](recursos/validadores-completos.md).

## Cuándo NO cargar

- Se valida código de aplicación del usuario (tests Python/TS, cobertura, linting) — este skill valida la integridad del sistema SWL; para código de aplicación cargar `reglas/pruebas.md` o invocar `tdd-qa-swl`.
- `/swl:status salud` acaba de ejecutarse sin errores en esta sesión — la validación CI es un subconjunto de lo que salud ejecuta; duplicarla no aporta información nueva.
- El objetivo es diagnosticar por qué un agente específico falló en su tarea de dominio — este skill detecta problemas estructurales (frontmatter faltante, exit code incorrecto), no bugs en la lógica de un agente; para eso usar `evaluacion-agentes`.
- Se está creando un componente nuevo y se necesita orientación sobre la estructura — este skill verifica componentes existentes, no guía la creación; usar `estructura-proyecto-claude` para crear con la estructura correcta desde el inicio.

## Gotchas / Errores comunes no obvios

- **Hook de observabilidad que usa `process.exit(1)` detectado como error crítico**: el validador marca el hook como inválido pero el hook fue escrito intencionalmente para bloquear en ciertos escenarios. Causa: el validador distingue entre hooks de observación (deben usar `exit(0)` siempre) y hooks de bloqueo (pueden usar `exit(1)` para rechazar acciones); si el hook no está categorizado correctamente, el validador aplica la regla incorrecta. Solución: verificar si el hook es bloqueante o de observación antes de corregir — un guardrail de seguridad que usa `exit(1)` es correcto; un hook de telemetría que usa `exit(1)` es un bug.
- **Agente con `name` diferente al nombre de archivo pasa validación en local pero falla en CI**: el validador local compara el campo `name` del frontmatter con el nombre del directorio, pero CI usa la ruta del archivo. Causa: un agente renombrado actualiza el directorio pero no el campo `name` en el frontmatter. Solución: el checklist dice "name debe coincidir con nombre del archivo (kebab-case)" — al renombrar un agente o skill, actualizar el campo `name` del frontmatter en el mismo commit.
- **`npm run validate` pasa sin advertencias pero `/swl:status salud` reporta inconsistencias**: el script de validación CI cubre un subconjunto de las verificaciones de salud. Causa: las validaciones de grafo de dependencias, métricas de evolución y consistencia de versiones solo corren en `/swl:status salud`, no en el validador CI básico. Solución: antes de un release o merge importante, ejecutar `/swl:status salud` completo, no solo la validación CI — la validación CI es el mínimo para commits diarios.
- **Skills con `description: >` YAML multiline registrados como sin frontmatter**: el validador usa una regex basada solo en LF (`/^---\n[\s\S]*?\n---/`) que no parsea correctamente archivos con terminaciones CRLF. Causa: archivos creados en Windows con CRLF en el frontmatter. Solución: si el validador reporta `sin-frontmatter` en un skill que claramente tiene frontmatter, verificar las terminaciones de línea con `file skill.md` — convertir CRLF→LF con `git config core.autocrlf input` o `sed -i 's/\r//'`.
