@saulwade/swl-ses 1.0.0

package/scripts/validar-tokens-test.js

@@ -0,0 +1,208 @@
+'use strict';
+
+/**
+ * validar-tokens-test.js
+ *
+ * Análisis estático: detecta literales con apariencia de token Telegram real
+ * (TELEGRAM_BOT_TOKEN=<valor> o TELEGRAM_CHAT_ID=<valor>) en archivos de test.
+ *
+ * Un token Telegram real tiene formato: <bot_id>:<hash_40chars>
+ * Un chat ID real tiene formato: [-]<número de 10+ dígitos>
+ *
+ * Este script NO bloquea por tokens con sufijo _test, _fake, _mock, ni por
+ * valores de longitud claramente inválida. Bloquea cuando el valor tiene
+ * apariencia estructuralmente válida de credencial real.
+ *
+ * Propósito: prevenir que fixtures de test con credenciales de apariencia real
+ * lleguen a commits y contaminen el .env del usuario o el historial de git.
+ * Introducido en v5.12.2 como Fix E.
+ *
+ * Uso:
+ *   node scripts/validar-tokens-test.js
+ *   node scripts/validar-tokens-test.js [directorio]
+ *
+ * Salida:
+ *   0 — ningún problema encontrado
+ *   1 — se encontraron literales de credencial con apariencia real
+ */
+
+const fs   = require('node:fs');
+const path = require('node:path');
+
+// ─── Configuración ─────────────────────────────────────────────────────────
+
+const DIRECTORIO_DEFAULT = path.join(__dirname, '..', 'tests');
+const EXTENSION          = '.test.js';
+
+// Comentario de exención explícita — úsalo cuando el valor es intencionalmente
+// similar a un token real (ej: test de validación del formato del token).
+// Ejemplo: const token = '1234567890:AABBCCxyz'; // swl-token-test:ok
+const EXENCION_COMENTARIO = 'swl-token-test:ok';
+
+// Regex para detectar un token de bot Telegram con apariencia real:
+// Formato: <dígitos>:<letras_y_símbolos_de_40+chars>
+// Se considera "apariencia real" si la parte hash tiene ≥ 25 caracteres alfanuméricos/guiones/guiones_bajos
+const RX_BOT_TOKEN = /TELEGRAM_BOT_TOKEN\s*=\s*['"]?(\d{8,12}:[A-Za-z0-9_\-]{25,})['"]?/;
+
+// Regex para detectar chat ID con apariencia real:
+// Los IDs reales tienen entre 9 y 14 dígitos, con posible prefijo -100 para grupos/canales
+// Un valor de test "real" como -100999888777 tiene 12 dígitos — apariencia válida.
+// Exentar si el valor es claramente sintético (todos los mismos dígitos, ej: -100111111111)
+const RX_CHAT_ID_REAL = /TELEGRAM_CHAT_ID\s*=\s*['"]?(-?[1-9]\d{8,13})['"]?/;
+
+// Sufijos que indican que el valor es intencionalmente sintético — no reportar
+// Estos patrones en el token hash indican uso de prueba sin ambigüedad
+const SUFIJOS_SINTETICOS = [
+  /^[0-9]+$/, // solo dígitos — no es un token real (que mezcla alfa + guiones)
+  /test/i,
+  /fake/i,
+  /mock/i,
+  /dummy/i,
+  /placeholder/i,
+  /example/i,
+  /invalid/i,
+];
+
+// IDs de bot conocidos como fixtures de test del sistema SWL — no son credenciales reales
+// Estos IDs se usan en tests internos y están documentados como fixtures sintéticos.
+const BOT_IDS_SINTETICOS = new Set([
+  '7123456789',  // ID de fixture SWL-test (introducido en Slice 004, v5.12.0)
+]);
+
+// Chat IDs que son claramente sintéticos por su patrón repetitivo
+const RX_CHAT_ID_SINTETICO = /^-?1+$|^-?0+$|^-?1+0+$|^-?10+$|(\d)\1{4,}/;
+
+// Archivos explícitamente exentos (ninguno por ahora)
+const EXENTOS = new Set([]);
+
+// ─── Utilidades ────────────────────────────────────────────────────────────
+
+/**
+ * Recorre un directorio recursivamente y devuelve todos los archivos .test.js
+ * @param {string} dir
+ * @returns {string[]}
+ */
+function obtenerArchivosTest(dir) {
+  const resultado = [];
+  if (!fs.existsSync(dir)) return resultado;
+
+  for (const entrada of fs.readdirSync(dir, { withFileTypes: true })) {
+    const ruta = path.join(dir, entrada.name);
+    if (entrada.isDirectory()) {
+      resultado.push(...obtenerArchivosTest(ruta));
+    } else if (entrada.isFile() && entrada.name.endsWith(EXTENSION)) {
+      resultado.push(ruta);
+    }
+  }
+  return resultado;
+}
+
+/**
+ * Verifica si el hash de un token parece sintético (no credencial real).
+ * @param {string} hash - Parte después de ":" en el token
+ * @returns {boolean}
+ */
+function esHashSintetico(hash) {
+  return SUFIJOS_SINTETICOS.some(rx => rx.test(hash));
+}
+
+/**
+ * Analiza un archivo de test línea por línea.
+ * Devuelve la lista de alertas encontradas.
+ *
+ * @param {string} rutaArchivo
+ * @returns {{ archivo: string, linea: number, tipo: string, valor: string }[]}
+ */
+function analizarArchivo(rutaArchivo) {
+  const alertas = [];
+  const lineas = fs.readFileSync(rutaArchivo, 'utf8').split('\n');
+
+  for (let i = 0; i < lineas.length; i++) {
+    const lineaActual = lineas[i];
+
+    // Ignorar líneas de comentario puro
+    const lineaTrimmed = lineaActual.trim();
+    if (lineaTrimmed.startsWith('//') || lineaTrimmed.startsWith('*')) continue;
+
+    // Verificar exención explícita
+    const lineaAnterior = i > 0 ? lineas[i - 1] : '';
+    const tieneExencion =
+      lineaActual.includes(EXENCION_COMENTARIO) ||
+      lineaAnterior.includes(EXENCION_COMENTARIO);
+    if (tieneExencion) continue;
+
+    // Verificar token de bot
+    const matchToken = lineaActual.match(RX_BOT_TOKEN);
+    if (matchToken) {
+      const valorCompleto = matchToken[1]; // <id>:<hash>
+      const partesToken   = valorCompleto.split(':');
+      const botId         = partesToken[0] || '';
+      const hash          = partesToken[1] || '';
+      if (!esHashSintetico(hash) && !BOT_IDS_SINTETICOS.has(botId)) {
+        alertas.push({
+          archivo: rutaArchivo,
+          linea:   i + 1,
+          tipo:    'TELEGRAM_BOT_TOKEN',
+          valor:   valorCompleto.substring(0, 20) + '...',
+        });
+      }
+    }
+
+    // Verificar chat ID
+    const matchChatId = lineaActual.match(RX_CHAT_ID_REAL);
+    if (matchChatId) {
+      const valorChatId = matchChatId[1];
+      if (!RX_CHAT_ID_SINTETICO.test(valorChatId)) {
+        alertas.push({
+          archivo: rutaArchivo,
+          linea:   i + 1,
+          tipo:    'TELEGRAM_CHAT_ID',
+          valor:   valorChatId,
+        });
+      }
+    }
+  }
+
+  return alertas;
+}
+
+// ─── Main ───────────────────────────────────────────────────────────────────
+
+function main() {
+  const args       = process.argv.slice(2);
+  const directorio = args[0] ? path.resolve(args[0]) : DIRECTORIO_DEFAULT;
+
+  console.log(`Validando tokens en archivos de test: ${directorio}`);
+  console.log(`Buscando literales TELEGRAM_BOT_TOKEN/CHAT_ID con apariencia real...\n`);
+
+  const archivos    = obtenerArchivosTest(directorio);
+  const todasAlertas = [];
+
+  for (const archivo of archivos) {
+    if (EXENTOS.has(path.basename(archivo))) continue;
+    const alertas = analizarArchivo(archivo);
+    todasAlertas.push(...alertas);
+  }
+
+  if (todasAlertas.length === 0) {
+    console.log(`OK: ${archivos.length} archivo(s) analizados — ningún token de apariencia real encontrado.`);
+    process.exit(0);
+  }
+
+  console.error(`ERROR: Se encontraron ${todasAlertas.length} literal(es) de credencial con apariencia real:\n`);
+  for (const a of todasAlertas) {
+    const rutaRelativa = path.relative(process.cwd(), a.archivo);
+    console.error(`  ${rutaRelativa}:${a.linea}`);
+    console.error(`    → ${a.tipo} = ${a.valor}`);
+    console.error('');
+  }
+  console.error(
+    'Si el valor es intencionalmente sintético, agregar comentario en la misma línea:\n' +
+    `  // ${EXENCION_COMENTARIO}\n` +
+    'Ver scripts/lib/notificaciones-telegram.js para referencia de fixtures de test seguros.\n' +
+    'Si es una credencial real filtrada: rotar el token en BotFather INMEDIATAMENTE.'
+  );
+  process.exit(1);
+}
+
+main();

package/scripts/validar.js

@@ -0,0 +1,147 @@
+'use strict';
+
+/**
+ * Validación básica de la estructura del paquete SWL.
+ * Ejecuta con: npm test
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const RAIZ = path.resolve(__dirname, '..');
+let errores = 0;
+
+function verificar(condicion, mensaje) {
+  if (condicion) {
+    console.log(`  [OK] ${mensaje}`);
+  } else {
+    console.log(`  [FALLA] ${mensaje}`);
+    errores++;
+  }
+}
+
+console.log('Validando estructura SWL...\n');
+
+// 1. package.json
+const pkg = require('../package.json');
+const { NOMBRES_VALIDOS } = require('./lib/paquetes-conocidos');
+verificar(
+  NOMBRES_VALIDOS.includes(pkg.name),
+  `package.json: nombre correcto (esperado uno de ${JSON.stringify(NOMBRES_VALIDOS)}; actual: ${pkg.name})`
+);
+verificar(pkg.bin && pkg.bin['swl-ses'], 'package.json: bin swl-ses definido');
+verificar(pkg.engines && pkg.engines.node, 'package.json: engine de node definido');
+
+// 2. CLI
+verificar(fs.existsSync(path.join(RAIZ, 'bin', 'swl-ses.js')), 'bin/swl-ses.js existe');
+
+// 3. Scripts
+const scriptsRequeridos = ['inicializar.js', 'instalador.js', 'doctor.js', 'actualizar.js', 'desinstalar.js'];
+for (const s of scriptsRequeridos) {
+  verificar(fs.existsSync(path.join(RAIZ, 'scripts', s)), `scripts/${s} existe`);
+}
+
+// 4. Manifiestos
+const manifiestosRequeridos = ['perfiles.json', 'modulos.json', 'hooks-config.json'];
+for (const m of manifiestosRequeridos) {
+  verificar(fs.existsSync(path.join(RAIZ, 'manifiestos', m)), `manifiestos/${m} existe`);
+}
+
+// 4b. Validar hooks-config.json tiene entradas para cada hook
+const hooksConfigPath = path.join(RAIZ, 'manifiestos', 'hooks-config.json');
+if (fs.existsSync(hooksConfigPath)) {
+  const hooksConfig = JSON.parse(fs.readFileSync(hooksConfigPath, 'utf-8'));
+  const hooksEnConfig = Object.keys(hooksConfig.hooks || {});
+  verificar(hooksEnConfig.length >= 4, `hooks-config.json: ${hooksEnConfig.length} hooks definidos (mínimo 4)`);
+  for (const hookName of hooksEnConfig) {
+    const hc = hooksConfig.hooks[hookName];
+    const eventosValidos = ['PreToolUse', 'PostToolUse', 'Stop', 'Notification', 'SubagentStop', 'UserPromptSubmit', 'PreCompact', 'SessionStart'];
+    verificar(
+      eventosValidos.includes(hc.event),
+      `hooks-config.json: ${hookName} tiene event válido (${hc.event})`
+    );
+  }
+}
+
+// 5. Agentes (mínimo 12)
+const agentes = fs.readdirSync(path.join(RAIZ, 'agentes')).filter(f => f.endsWith('.md'));
+verificar(agentes.length >= 12, `Agentes: ${agentes.length} (mínimo 12)`);
+
+// Verificar frontmatter en agentes
+for (const agente of agentes) {
+  const contenido = fs.readFileSync(path.join(RAIZ, 'agentes', agente), 'utf-8');
+  verificar(contenido.startsWith('---'), `${agente}: tiene frontmatter YAML`);
+  verificar(contenido.includes('name:'), `${agente}: tiene campo name`);
+  verificar(contenido.includes('description:'), `${agente}: tiene campo description`);
+}
+
+// 6. Habilidades (mínimo 25)
+const habilidades = fs.readdirSync(path.join(RAIZ, 'habilidades'))
+  .filter(h => {
+    const skillPath = path.join(RAIZ, 'habilidades', h, 'SKILL.md');
+    return fs.existsSync(skillPath);
+  });
+verificar(habilidades.length >= 25, `Habilidades: ${habilidades.length} (mínimo 25)`);
+
+// 7. Comandos
+const comandos = fs.readdirSync(path.join(RAIZ, 'comandos', 'swl')).filter(f => f.endsWith('.md'));
+verificar(comandos.length >= 9, `Comandos: ${comandos.length} (mínimo 9)`);
+
+// 8. Reglas
+const reglas = fs.readdirSync(path.join(RAIZ, 'reglas')).filter(f => f.endsWith('.md'));
+verificar(reglas.length >= 7, `Reglas: ${reglas.length} (mínimo 7)`);
+
+// 9. Hooks
+const hooks = fs.readdirSync(path.join(RAIZ, 'hooks')).filter(f => f.endsWith('.js'));
+verificar(hooks.length >= 4, `Hooks: ${hooks.length} (mínimo 4)`);
+
+// 10. Plantillas
+verificar(fs.existsSync(path.join(RAIZ, 'plantillas', 'PROYECTO.md')), 'plantillas/PROYECTO.md existe');
+verificar(fs.existsSync(path.join(RAIZ, 'plantillas', 'ESTADO.md')), 'plantillas/ESTADO.md existe');
+
+// 11. plugin.json
+const pluginPath = path.join(RAIZ, 'plugin.json');
+verificar(fs.existsSync(pluginPath), 'plugin.json existe');
+if (fs.existsSync(pluginPath)) {
+  const plugin = JSON.parse(fs.readFileSync(pluginPath, 'utf-8'));
+  verificar(plugin.skills && plugin.skills.length >= 25, `plugin.json: ${(plugin.skills || []).length} skills registrados`);
+  verificar(plugin.agents && plugin.agents.length >= 12, `plugin.json: ${(plugin.agents || []).length} agentes registrados`);
+  verificar(plugin.hooks && plugin.hooks.PreToolUse, 'plugin.json: tiene hooks PreToolUse');
+  verificar(plugin.hooks && plugin.hooks.PostToolUse, 'plugin.json: tiene hooks PostToolUse');
+}
+
+// 12. CLAUDE.md
+verificar(fs.existsSync(path.join(RAIZ, 'CLAUDE.md')), 'CLAUDE.md existe');
+
+// 13. Memoria consolidada
+const memRule = path.join(RAIZ, 'reglas', 'memoria-consolidada.md');
+verificar(fs.existsSync(memRule), 'reglas/memoria-consolidada.md existe');
+
+// 14. Validación de memoria: ejecuta validar-memoria.js
+try {
+  const { execSync } = require('child_process');
+  const memoria = path.join(RAIZ, 'scripts', 'validar-memoria.js');
+  if (fs.existsSync(memoria)) {
+    try {
+      execSync(`node "${memoria}" --json`, { stdio: 'pipe' });
+      verificar(true, 'Memoria consolidada: sin violaciones');
+    } catch (e) {
+      const exitCode = e.status;
+      if (exitCode === 2) {
+        verificar(false, 'Memoria consolidada: violaciones CRÍTICAS (posibles secretos)');
+      } else if (exitCode === 1) {
+        verificar(true, "Memoria consolidada: warnings no críticos — ver 'node scripts/validar-memoria.js'");
+      } else {
+        verificar(true, 'Memoria consolidada: sin violaciones');
+      }
+    }
+  }
+} catch { /* ignore */ }
+
+console.log('\n' + '='.repeat(40));
+if (errores === 0) {
+  console.log('Todas las validaciones pasaron.');
+} else {
+  console.log(`${errores} validaciones fallaron.`);
+  process.exit(1);
+}

package/scripts/validate-markdown.py

@@ -0,0 +1,339 @@
+"""
+validate-markdown.py — Validador de sintaxis Markdown para skills del sistema SWL
+
+Uso:
+  python scripts/validate-markdown.py                                          # valida todos los .md
+  python scripts/validate-markdown.py --path habilidades/django-experto/SKILL.md
+  python scripts/validate-markdown.py --check                                  # modo CI: exit 1 si hay errores
+
+Valida SKILL.md y recursos/*.md de todas las habilidades en ../habilidades.
+Exit code 0 = éxito o solo advertencias; 1 = hay errores.
+"""
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+
+# ---------------------------------------------------------------------------
+# Constantes
+# ---------------------------------------------------------------------------
+REGEX_APERTURA_BLOQUE = re.compile(r"^```(\w*)\s*$")
+REGEX_CIERRE_BLOQUE = re.compile(r"^```\s*$")
+REGEX_FILA_TABLA = re.compile(r"^\s*\|.*\|\s*$")
+REGEX_SEPARADOR_TABLA = re.compile(r"^\s*\|[\s|:\-]+\|\s*$")
+REGEX_COMENTARIO_HTML = re.compile(r"<!--.*?-->", re.DOTALL)
+REGEX_ENCABEZADO = re.compile(r"^(#{1,6})\s+\S")
+
+
+# ---------------------------------------------------------------------------
+# Tipos de resultado
+# ---------------------------------------------------------------------------
+def _problema(tipo: str, codigo: str, linea: int | None, mensaje: str) -> dict:
+    return {"type": tipo, "code": codigo, "line": linea, "message": mensaje}
+
+
+def _error(codigo: str, linea: int | None, mensaje: str) -> dict:
+    return _problema("error", codigo, linea, mensaje)
+
+
+def _advertencia(codigo: str, linea: int | None, mensaje: str) -> dict:
+    return _problema("warning", codigo, linea, mensaje)
+
+
+# ---------------------------------------------------------------------------
+# Validación de bloques de código
+# ---------------------------------------------------------------------------
+def _validar_bloques_codigo(lineas: list[str]) -> list[dict]:
+    issues: list[dict] = []
+    dentro_bloque = False
+    linea_apertura = 0
+
+    for i, linea in enumerate(lineas, start=1):
+        if not dentro_bloque:
+            if REGEX_APERTURA_BLOQUE.match(linea):
+                dentro_bloque = True
+                linea_apertura = i
+        else:
+            if REGEX_CIERRE_BLOQUE.match(linea):
+                dentro_bloque = False
+
+    if dentro_bloque:
+        issues.append(_error(
+            "UNCLOSED_CODE_BLOCK",
+            linea_apertura,
+            f"Bloque de codigo abierto en linea {linea_apertura} nunca se cierra"
+        ))
+
+    return issues
+
+
+# ---------------------------------------------------------------------------
+# Validación de tablas
+# ---------------------------------------------------------------------------
+def _contar_columnas(fila: str) -> int:
+    """Cuenta el número de columnas en una fila de tabla Markdown."""
+    fila = fila.strip()
+    if fila.startswith("|"):
+        fila = fila[1:]
+    if fila.endswith("|"):
+        fila = fila[:-1]
+    return len(fila.split("|"))
+
+
+def _validar_tablas(lineas: list[str]) -> list[dict]:
+    issues: list[dict] = []
+    dentro_bloque = False
+    i = 0
+
+    while i < len(lineas):
+        linea = lineas[i]
+        num_linea = i + 1
+
+        # No validar tablas dentro de bloques de código
+        if not dentro_bloque and REGEX_APERTURA_BLOQUE.match(linea):
+            dentro_bloque = True
+        elif dentro_bloque and REGEX_CIERRE_BLOQUE.match(linea):
+            dentro_bloque = False
+        elif not dentro_bloque and REGEX_FILA_TABLA.match(linea):
+            # Inicio potencial de tabla: fila de encabezado
+            fila_encabezado = linea
+            num_cols_encabezado = _contar_columnas(fila_encabezado)
+            num_linea_encabezado = num_linea
+
+            # Verificar si la siguiente línea es el separador
+            if i + 1 < len(lineas):
+                linea_siguiente = lineas[i + 1]
+                if not REGEX_SEPARADOR_TABLA.match(linea_siguiente):
+                    # Puede ser tabla sin separador solo si la línea siguiente también es fila de tabla
+                    if REGEX_FILA_TABLA.match(linea_siguiente):
+                        issues.append(_error(
+                            "TABLE_MISSING_SEPARATOR",
+                            num_linea,
+                            f"Tabla en linea {num_linea} no tiene separador (segunda fila debe tener |---|)"
+                        ))
+                else:
+                    # Tiene separador: avanzar y validar columnas del resto
+                    i += 2  # saltar encabezado y separador
+                    while i < len(lineas) and REGEX_FILA_TABLA.match(lineas[i]):
+                        num_cols_fila = _contar_columnas(lineas[i])
+                        if num_cols_fila != num_cols_encabezado:
+                            issues.append(_error(
+                                "TABLE_INCONSISTENT_COLUMNS",
+                                i + 1,
+                                f"Fila {i + 1} de tabla tiene {num_cols_fila} columna(s) "
+                                f"pero el encabezado (linea {num_linea_encabezado}) define {num_cols_encabezado}"
+                            ))
+                        # Advertencia: comentarios HTML dentro de celdas de tabla
+                        if REGEX_COMENTARIO_HTML.search(lineas[i]):
+                            issues.append(_advertencia(
+                                "HTML_COMMENT_IN_TABLE",
+                                i + 1,
+                                f"Comentario HTML en fila {i + 1} de tabla; puede romper el parsing en algunas herramientas"
+                            ))
+                        i += 1
+                    continue  # ya avanzamos manualmente
+
+        i += 1
+
+    return issues
+
+
+# ---------------------------------------------------------------------------
+# Validación de encabezados (salto de nivel)
+# ---------------------------------------------------------------------------
+def _validar_encabezados(lineas: list[str]) -> list[dict]:
+    issues: list[dict] = []
+    dentro_bloque = False
+    nivel_anterior = 0
+
+    for i, linea in enumerate(lineas, start=1):
+        if not dentro_bloque and REGEX_APERTURA_BLOQUE.match(linea):
+            dentro_bloque = True
+            continue
+        if dentro_bloque and REGEX_CIERRE_BLOQUE.match(linea):
+            dentro_bloque = False
+            continue
+        if dentro_bloque:
+            continue
+
+        m = REGEX_ENCABEZADO.match(linea)
+        if m:
+            nivel_actual = len(m.group(1))
+            if nivel_anterior > 0 and nivel_actual > nivel_anterior + 1:
+                issues.append(_advertencia(
+                    "HEADING_LEVEL_SKIP",
+                    i,
+                    f"Encabezado salta de H{nivel_anterior} a H{nivel_actual} en linea {i} "
+                    f"(se omite H{nivel_anterior + 1})"
+                ))
+            nivel_anterior = nivel_actual
+
+    return issues
+
+
+# ---------------------------------------------------------------------------
+# Validación de un archivo individual
+# ---------------------------------------------------------------------------
+def validar_archivo(ruta: Path) -> dict:
+    """
+    Valida un archivo Markdown.
+    Devuelve dict con claves: archivo, status, issues.
+    """
+    issues: list[dict] = []
+
+    if not ruta.exists():
+        return {
+            "archivo": str(ruta),
+            "status": "error",
+            "issues": [_error("FILE_NOT_FOUND", None, f"Archivo no encontrado: {ruta}")]
+        }
+
+    contenido = ruta.read_text(encoding="utf-8", errors="replace")
+    lineas = contenido.splitlines()
+
+    issues.extend(_validar_bloques_codigo(lineas))
+    issues.extend(_validar_tablas(lineas))
+    issues.extend(_validar_encabezados(lineas))
+
+    tiene_error = any(i["type"] == "error" for i in issues)
+    tiene_advertencia = any(i["type"] == "warning" for i in issues)
+
+    if tiene_error:
+        estado = "error"
+    elif tiene_advertencia:
+        estado = "warning"
+    else:
+        estado = "ok"
+
+    return {"archivo": str(ruta), "status": estado, "issues": issues}
+
+
+# ---------------------------------------------------------------------------
+# Recolección de archivos a validar
+# ---------------------------------------------------------------------------
+def recolectar_archivos_markdown(dir_habilidades: Path) -> list[Path]:
+    """Devuelve todos los SKILL.md y recursos/*.md bajo dir_habilidades."""
+    archivos: list[Path] = []
+
+    for skill_dir in sorted(dir_habilidades.iterdir()):
+        if not skill_dir.is_dir():
+            continue
+
+        skill_md = skill_dir / "SKILL.md"
+        if skill_md.exists():
+            archivos.append(skill_md)
+
+        recursos_dir = skill_dir / "recursos"
+        if recursos_dir.is_dir():
+            for archivo in sorted(recursos_dir.iterdir()):
+                if archivo.suffix.lower() == ".md":
+                    archivos.append(archivo)
+
+    return archivos
+
+
+# ---------------------------------------------------------------------------
+# Presentación de resultados
+# ---------------------------------------------------------------------------
+def _iconos() -> dict[str, str]:
+    """Devuelve iconos Unicode si el terminal los soporta, ASCII en caso contrario."""
+    enc = getattr(sys.stdout, "encoding", "") or ""
+    if enc.lower().replace("-", "") in ("utf8", "utf16", "utf32"):
+        return {"ok": "\u2713", "warning": "\u26a0", "error": "\u2717"}
+    return {"ok": "[OK]", "warning": "[WARN]", "error": "[ERR]"}
+
+
+def imprimir_resultado_normal(resultado: dict, raiz: Path, iconos: dict[str, str]) -> None:
+    """Imprime el resultado de un archivo, mostrando la ruta relativa a raiz."""
+    ruta_abs = Path(resultado["archivo"])
+    try:
+        ruta_mostrar = ruta_abs.relative_to(raiz)
+    except ValueError:
+        ruta_mostrar = ruta_abs
+
+    estado = resultado["status"]
+    icono = iconos.get(estado, "?")
+    issues = resultado["issues"]
+
+    if estado == "ok":
+        print(f"{icono} {ruta_mostrar} - OK")
+    else:
+        for issue in issues:
+            prefijo = "ERROR" if issue["type"] == "error" else "ADVERTENCIA"
+            ref_linea = f" (linea {issue['line']})" if issue.get("line") else ""
+            print(f"{icono} {ruta_mostrar}{ref_linea} - {prefijo}: {issue['message']}")
+
+
+# ---------------------------------------------------------------------------
+# Punto de entrada
+# ---------------------------------------------------------------------------
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Validador de sintaxis Markdown para skills del sistema SWL"
+    )
+    parser.add_argument(
+        "--path",
+        metavar="RUTA",
+        help="Validar un archivo Markdown específico"
+    )
+    parser.add_argument(
+        "--check",
+        action="store_true",
+        help="Modo CI: exit 1 si hay errores"
+    )
+    args = parser.parse_args()
+
+    raiz = Path(__file__).parent.parent
+    dir_habilidades = raiz / "habilidades"
+
+    if args.path:
+        # Ruta puede ser relativa a la raíz del proyecto o absoluta
+        ruta_archivo = Path(args.path)
+        if not ruta_archivo.is_absolute():
+            ruta_archivo = raiz / ruta_archivo
+        archivos = [ruta_archivo]
+    else:
+        if not dir_habilidades.is_dir():
+            print(
+                f"ERROR: Directorio de habilidades no encontrado: {dir_habilidades}",
+                file=sys.stderr
+            )
+            return 1
+        archivos = recolectar_archivos_markdown(dir_habilidades)
+
+    if not archivos:
+        print("No se encontraron archivos Markdown para validar.")
+        return 0
+
+    resultados: list[dict] = []
+    for ruta in archivos:
+        resultado = validar_archivo(ruta)
+        resultados.append(resultado)
+
+    # Contadores
+    n_ok = sum(1 for r in resultados if r["status"] == "ok")
+    n_warnings = sum(1 for r in resultados if r["status"] == "warning")
+    n_errors = sum(1 for r in resultados if r["status"] == "error")
+
+    iconos = _iconos()
+    for resultado in resultados:
+        imprimir_resultado_normal(resultado, raiz, iconos)
+
+    total = len(resultados)
+    partes = [f"{total} archivo(s) validado(s)", f"{n_ok} OK"]
+    if n_warnings:
+        partes.append(f"{n_warnings} advertencia(s)")
+    if n_errors:
+        partes.append(f"{n_errors} error(es)")
+    print(f"\nResumen: {', '.join(partes)}")
+
+    if args.check and n_errors > 0:
+        return 1
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())