@saulwade/swl-ses 1.3.1 → 1.3.3

package/scripts/auditar-claudemd.js

@@ -1,297 +1,297 @@
-#!/usr/bin/env node
-'use strict';
-
-/**
- * scripts/auditar-claudemd.js
- *
- * Auditor del archivo CLAUDE.md según best practices Anthropic (ADR-0016).
- *
- * Verifica:
- *   - Existencia del archivo (en ./ o en .claude/)
- *   - Líneas totales (umbral SWL_CLAUDEMD_MAX_LINES, default 200)
- *   - Bullets/párrafos monolíticos (umbral SWL_CLAUDEMD_MAX_BULLET_CHARS, default 1000)
- *   - Presencia de secciones canónicas (Stack, Comandos, Code style, Conventions, @references)
- *   - Uso de @references (al menos 1 si el archivo supera 80 líneas)
- *   - Placeholders sin reemplazar ([TBD], [TODO], [COMPLETAR])
- *
- * Uso:
- *   node scripts/auditar-claudemd.js [ruta]                # Audita CLAUDE.md (default: ./)
- *   node scripts/auditar-claudemd.js --json                # Salida JSON
- *   node scripts/auditar-claudemd.js --strict              # exit 1 si veredicto != OK
- *
- * Exit codes:
- *   0 — OK o WARN (veredicto consultivo)
- *   1 — ERROR (no existe / placeholders / faltan secciones críticas) o --strict + WARN
- */
-
-const fs = require('fs');
-const path = require('path');
-
-// ─── Config ───────────────────────────────────────────────────────────────
-const MAX_LINES = parseInt(process.env.SWL_CLAUDEMD_MAX_LINES, 10) || 200;
-const MAX_BULLET_CHARS =
-  parseInt(process.env.SWL_CLAUDEMD_MAX_BULLET_CHARS, 10) || 1000;
-
-const SECCIONES_CANONICAS = [
-  { nombre: 'Stack', regex: /^##\s+Stack/m },
-  { nombre: 'Comandos', regex: /^##\s+Comandos/m },
-  { nombre: 'Code style', regex: /^##\s+(Code\s+style|Estilo\s+de\s+código)/im },
-  { nombre: 'Conventions', regex: /^##\s+(Conventions|Convenciones)/im },
-];
-
-const PLACEHOLDERS = /\[(TBD|TODO|COMPLETAR|PENDIENTE|XXX|FIXME)\]/g;
-
-// ─── Auditoría ────────────────────────────────────────────────────────────
-
-function ubicarClaudeMd(dir = process.cwd()) {
-  const candidatos = [
-    path.join(dir, 'CLAUDE.md'),
-    path.join(dir, '.claude', 'CLAUDE.md'),
-  ];
-  for (const c of candidatos) {
-    if (fs.existsSync(c)) return c;
-  }
-  return null;
-}
-
-function auditar(rutaClaudeMd) {
-  if (!rutaClaudeMd || !fs.existsSync(rutaClaudeMd)) {
-    return {
-      veredicto: 'ERROR',
-      ruta: rutaClaudeMd,
-      hallazgos: [{
-        severidad: 'ERROR',
-        mensaje: 'CLAUDE.md no existe en el directorio de trabajo',
-        sugerencia: 'Ejecuta `/swl:claudemd init-project` para generarlo',
-      }],
-    };
-  }
-
-  const contenido = fs.readFileSync(rutaClaudeMd, 'utf8');
-  const lineas = contenido.split('\n');
-  const hallazgos = [];
-
-  // 1. Líneas totales
-  if (lineas.length > MAX_LINES) {
-    hallazgos.push({
-      severidad: 'WARN',
-      regla: 'tamano-total',
-      mensaje: `CLAUDE.md tiene ${lineas.length} líneas (umbral: ${MAX_LINES})`,
-      sugerencia: 'Extraer secciones grandes a archivos `@`-referenciados (ej. `@docs/variables-entorno.md`)',
-    });
-  }
-
-  // 2. Bullets/párrafos monolíticos
-  const bulletsMonoliticos = detectarBulletsGigantes(contenido);
-  for (const b of bulletsMonoliticos) {
-    hallazgos.push({
-      severidad: 'WARN',
-      regla: 'bullet-gigante',
-      mensaje: `Bullet/párrafo en línea ${b.linea} tiene ${b.chars} chars (umbral: ${MAX_BULLET_CHARS})`,
-      sugerencia: 'Convertir a tabla, lista jerárquica o extraer a archivo separado',
-      preview: b.preview,
-    });
-  }
-
-  // 3. Secciones canónicas
-  const seccionesAusentes = SECCIONES_CANONICAS.filter(s => !s.regex.test(contenido));
-  if (seccionesAusentes.length > 0) {
-    const nombres = seccionesAusentes.map(s => s.nombre).join(', ');
-    hallazgos.push({
-      severidad: 'WARN',
-      regla: 'secciones-canonicas',
-      mensaje: `Faltan secciones canónicas Anthropic: ${nombres}`,
-      sugerencia: `Agregar las secciones faltantes (ver \`/swl:claudemd refactor\` para template)`,
-    });
-  }
-
-  // 4. @references si el archivo es grande
-  if (lineas.length > 80) {
-    const tieneAtReferences = /@[a-zA-Z][a-zA-Z0-9_\-./]+\.md/.test(contenido);
-    if (!tieneAtReferences) {
-      hallazgos.push({
-        severidad: 'WARN',
-        regla: 'sin-at-references',
-        mensaje: 'Archivo grande (>80 líneas) sin @references a docs externos',
-        sugerencia: 'Usar `@docs/...md` o `@.planning/...md` para enlazar contenido en lugar de duplicarlo',
-      });
-    }
-  }
-
-  // 5. Placeholders sin reemplazar
-  const matches = [...contenido.matchAll(PLACEHOLDERS)];
-  if (matches.length > 0) {
-    hallazgos.push({
-      severidad: 'ERROR',
-      regla: 'placeholders',
-      mensaje: `${matches.length} placeholder(s) sin reemplazar: ${[...new Set(matches.map(m => m[0]))].join(', ')}`,
-      sugerencia: 'Reemplazar todos los placeholders antes de commitear',
-    });
-  }
-
-  // ─── Veredicto ───────────────────────────────────────────────────────────
-  const tieneError = hallazgos.some(h => h.severidad === 'ERROR');
-  const tieneWarn = hallazgos.some(h => h.severidad === 'WARN');
-  const veredicto = tieneError ? 'ERROR' : tieneWarn ? 'WARN' : 'OK';
-
-  return {
-    veredicto,
-    ruta: rutaClaudeMd,
-    metricas: {
-      lineas: lineas.length,
-      bytes: contenido.length,
-      umbral_lineas: MAX_LINES,
-      umbral_bullet_chars: MAX_BULLET_CHARS,
-      secciones_presentes: SECCIONES_CANONICAS.filter(s => s.regex.test(contenido)).map(s => s.nombre),
-      secciones_ausentes: seccionesAusentes.map(s => s.nombre),
-      tiene_at_references: /@[a-zA-Z][a-zA-Z0-9_\-./]+\.md/.test(contenido),
-    },
-    hallazgos,
-  };
-}
-
-/**
- * Detecta bullets/párrafos cuyo contenido excede MAX_BULLET_CHARS.
- * Un "bullet" es una línea que empieza con `-` o `*` (ignorando indentación).
- * Un "párrafo" es bloque de texto contiguo sin línea vacía.
- */
-function detectarBulletsGigantes(contenido) {
-  const lineas = contenido.split('\n');
-  const gigantes = [];
-  let buffer = '';
-  let lineaInicio = 0;
-  let dentroDeBullet = false;
-  let dentroDeCodeFence = false;
-
-  const flush = () => {
-    if (buffer.length > MAX_BULLET_CHARS) {
-      gigantes.push({
-        linea: lineaInicio + 1,
-        chars: buffer.length,
-        preview: buffer.slice(0, 100) + (buffer.length > 100 ? '…' : ''),
-      });
-    }
-    buffer = '';
-    dentroDeBullet = false;
-  };
-
-  for (let i = 0; i < lineas.length; i++) {
-    const linea = lineas[i];
-
-    // Skipear bloques de código (no son bullets)
-    if (/^\s*```/.test(linea)) {
-      flush();
-      dentroDeCodeFence = !dentroDeCodeFence;
-      continue;
-    }
-    if (dentroDeCodeFence) continue;
-
-    // Skipear tablas Markdown (líneas que empiezan con `|`):
-    // las tablas son grandes por naturaleza y no son "bullets monolíticos"
-    if (/^\s*\|/.test(linea)) {
-      flush();
-      continue;
-    }
-
-    // Línea vacía termina el bullet/párrafo actual
-    if (/^\s*$/.test(linea)) {
-      flush();
-      continue;
-    }
-
-    // Header termina el buffer
-    if (/^#/.test(linea)) {
-      flush();
-      continue;
-    }
-
-    // Inicio de nuevo bullet
-    if (/^\s*[-*+]\s/.test(linea)) {
-      flush();
-      lineaInicio = i;
-      buffer = linea;
-      dentroDeBullet = true;
-      continue;
-    }
-
-    // Continuación: si estamos en bullet, acumular; si no, párrafo
-    if (dentroDeBullet) {
-      buffer += '\n' + linea;
-    } else {
-      if (buffer === '') lineaInicio = i;
-      buffer += (buffer ? '\n' : '') + linea;
-    }
-  }
-  flush();
-  return gigantes;
-}
-
-// ─── CLI ──────────────────────────────────────────────────────────────────
-
-function imprimirReporte(resultado) {
-  const colorVeredicto = {
-    OK: '\x1b[32m',     // verde
-    WARN: '\x1b[33m',   // amarillo
-    ERROR: '\x1b[31m',  // rojo
-  };
-  const reset = '\x1b[0m';
-
-  console.log(`\n${colorVeredicto[resultado.veredicto]}=== AUDITORÍA CLAUDE.md ===${reset}`);
-  console.log(`Veredicto: ${colorVeredicto[resultado.veredicto]}${resultado.veredicto}${reset}`);
-  console.log(`Ruta: ${resultado.ruta || '(no encontrado)'}\n`);
-
-  if (resultado.metricas) {
-    const m = resultado.metricas;
-    console.log(`Métricas:`);
-    console.log(`  - Líneas: ${m.lineas} / ${m.umbral_lineas}`);
-    console.log(`  - Secciones canónicas presentes: ${m.secciones_presentes.length}/4 (${m.secciones_presentes.join(', ') || 'ninguna'})`);
-    if (m.secciones_ausentes.length > 0) {
-      console.log(`  - Secciones ausentes: ${m.secciones_ausentes.join(', ')}`);
-    }
-    console.log(`  - @references: ${m.tiene_at_references ? 'sí' : 'no'}`);
-    console.log('');
-  }
-
-  if (resultado.hallazgos.length === 0) {
-    console.log('Sin hallazgos. CLAUDE.md cumple best practices Anthropic.\n');
-    return;
-  }
-
-  console.log(`Hallazgos (${resultado.hallazgos.length}):\n`);
-  for (const h of resultado.hallazgos) {
-    const color = colorVeredicto[h.severidad] || '';
-    console.log(`  ${color}[${h.severidad}]${reset} ${h.mensaje}`);
-    if (h.sugerencia) console.log(`    → ${h.sugerencia}`);
-    if (h.preview) console.log(`    Preview: ${h.preview}`);
-    console.log('');
-  }
-}
-
-function main() {
-  const args = process.argv.slice(2);
-  const flagJson = args.includes('--json');
-  const flagStrict = args.includes('--strict');
-  const rutaArg = args.find(a => !a.startsWith('--'));
-
-  const ruta = rutaArg
-    ? path.resolve(rutaArg)
-    : ubicarClaudeMd();
-
-  const resultado = auditar(ruta);
-
-  if (flagJson) {
-    console.log(JSON.stringify(resultado, null, 2));
-  } else {
-    imprimirReporte(resultado);
-  }
-
-  if (resultado.veredicto === 'ERROR') process.exit(1);
-  if (flagStrict && resultado.veredicto === 'WARN') process.exit(1);
-  process.exit(0);
-}
-
-if (require.main === module) {
-  main();
-}
-
-module.exports = { auditar, ubicarClaudeMd, detectarBulletsGigantes, MAX_LINES, MAX_BULLET_CHARS };
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * scripts/auditar-claudemd.js
+ *
+ * Auditor del archivo CLAUDE.md según best practices Anthropic (ADR-0016).
+ *
+ * Verifica:
+ *   - Existencia del archivo (en ./ o en .claude/)
+ *   - Líneas totales (umbral SWL_CLAUDEMD_MAX_LINES, default 200)
+ *   - Bullets/párrafos monolíticos (umbral SWL_CLAUDEMD_MAX_BULLET_CHARS, default 1000)
+ *   - Presencia de secciones canónicas (Stack, Comandos, Code style, Conventions, @references)
+ *   - Uso de @references (al menos 1 si el archivo supera 80 líneas)
+ *   - Placeholders sin reemplazar ([TBD], [TODO], [COMPLETAR])
+ *
+ * Uso:
+ *   node scripts/auditar-claudemd.js [ruta]                # Audita CLAUDE.md (default: ./)
+ *   node scripts/auditar-claudemd.js --json                # Salida JSON
+ *   node scripts/auditar-claudemd.js --strict              # exit 1 si veredicto != OK
+ *
+ * Exit codes:
+ *   0 — OK o WARN (veredicto consultivo)
+ *   1 — ERROR (no existe / placeholders / faltan secciones críticas) o --strict + WARN
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// ─── Config ───────────────────────────────────────────────────────────────
+const MAX_LINES = parseInt(process.env.SWL_CLAUDEMD_MAX_LINES, 10) || 200;
+const MAX_BULLET_CHARS =
+  parseInt(process.env.SWL_CLAUDEMD_MAX_BULLET_CHARS, 10) || 1000;
+
+const SECCIONES_CANONICAS = [
+  { nombre: 'Stack', regex: /^##\s+Stack/m },
+  { nombre: 'Comandos', regex: /^##\s+Comandos/m },
+  { nombre: 'Code style', regex: /^##\s+(Code\s+style|Estilo\s+de\s+código)/im },
+  { nombre: 'Conventions', regex: /^##\s+(Conventions|Convenciones)/im },
+];
+
+const PLACEHOLDERS = /\[(TBD|TODO|COMPLETAR|PENDIENTE|XXX|FIXME)\]/g;
+
+// ─── Auditoría ────────────────────────────────────────────────────────────
+
+function ubicarClaudeMd(dir = process.cwd()) {
+  const candidatos = [
+    path.join(dir, 'CLAUDE.md'),
+    path.join(dir, '.claude', 'CLAUDE.md'),
+  ];
+  for (const c of candidatos) {
+    if (fs.existsSync(c)) return c;
+  }
+  return null;
+}
+
+function auditar(rutaClaudeMd) {
+  if (!rutaClaudeMd || !fs.existsSync(rutaClaudeMd)) {
+    return {
+      veredicto: 'ERROR',
+      ruta: rutaClaudeMd,
+      hallazgos: [{
+        severidad: 'ERROR',
+        mensaje: 'CLAUDE.md no existe en el directorio de trabajo',
+        sugerencia: 'Ejecuta `/swl:claudemd init-project` para generarlo',
+      }],
+    };
+  }
+
+  const contenido = fs.readFileSync(rutaClaudeMd, 'utf8');
+  const lineas = contenido.split('\n');
+  const hallazgos = [];
+
+  // 1. Líneas totales
+  if (lineas.length > MAX_LINES) {
+    hallazgos.push({
+      severidad: 'WARN',
+      regla: 'tamano-total',
+      mensaje: `CLAUDE.md tiene ${lineas.length} líneas (umbral: ${MAX_LINES})`,
+      sugerencia: 'Extraer secciones grandes a archivos `@`-referenciados (ej. `@docs/variables-entorno.md`)',
+    });
+  }
+
+  // 2. Bullets/párrafos monolíticos
+  const bulletsMonoliticos = detectarBulletsGigantes(contenido);
+  for (const b of bulletsMonoliticos) {
+    hallazgos.push({
+      severidad: 'WARN',
+      regla: 'bullet-gigante',
+      mensaje: `Bullet/párrafo en línea ${b.linea} tiene ${b.chars} chars (umbral: ${MAX_BULLET_CHARS})`,
+      sugerencia: 'Convertir a tabla, lista jerárquica o extraer a archivo separado',
+      preview: b.preview,
+    });
+  }
+
+  // 3. Secciones canónicas
+  const seccionesAusentes = SECCIONES_CANONICAS.filter(s => !s.regex.test(contenido));
+  if (seccionesAusentes.length > 0) {
+    const nombres = seccionesAusentes.map(s => s.nombre).join(', ');
+    hallazgos.push({
+      severidad: 'WARN',
+      regla: 'secciones-canonicas',
+      mensaje: `Faltan secciones canónicas Anthropic: ${nombres}`,
+      sugerencia: `Agregar las secciones faltantes (ver \`/swl:claudemd refactor\` para template)`,
+    });
+  }
+
+  // 4. @references si el archivo es grande
+  if (lineas.length > 80) {
+    const tieneAtReferences = /@[a-zA-Z][a-zA-Z0-9_\-./]+\.md/.test(contenido);
+    if (!tieneAtReferences) {
+      hallazgos.push({
+        severidad: 'WARN',
+        regla: 'sin-at-references',
+        mensaje: 'Archivo grande (>80 líneas) sin @references a docs externos',
+        sugerencia: 'Usar `@docs/...md` o `@.planning/...md` para enlazar contenido en lugar de duplicarlo',
+      });
+    }
+  }
+
+  // 5. Placeholders sin reemplazar
+  const matches = [...contenido.matchAll(PLACEHOLDERS)];
+  if (matches.length > 0) {
+    hallazgos.push({
+      severidad: 'ERROR',
+      regla: 'placeholders',
+      mensaje: `${matches.length} placeholder(s) sin reemplazar: ${[...new Set(matches.map(m => m[0]))].join(', ')}`,
+      sugerencia: 'Reemplazar todos los placeholders antes de commitear',
+    });
+  }
+
+  // ─── Veredicto ───────────────────────────────────────────────────────────
+  const tieneError = hallazgos.some(h => h.severidad === 'ERROR');
+  const tieneWarn = hallazgos.some(h => h.severidad === 'WARN');
+  const veredicto = tieneError ? 'ERROR' : tieneWarn ? 'WARN' : 'OK';
+
+  return {
+    veredicto,
+    ruta: rutaClaudeMd,
+    metricas: {
+      lineas: lineas.length,
+      bytes: contenido.length,
+      umbral_lineas: MAX_LINES,
+      umbral_bullet_chars: MAX_BULLET_CHARS,
+      secciones_presentes: SECCIONES_CANONICAS.filter(s => s.regex.test(contenido)).map(s => s.nombre),
+      secciones_ausentes: seccionesAusentes.map(s => s.nombre),
+      tiene_at_references: /@[a-zA-Z][a-zA-Z0-9_\-./]+\.md/.test(contenido),
+    },
+    hallazgos,
+  };
+}
+
+/**
+ * Detecta bullets/párrafos cuyo contenido excede MAX_BULLET_CHARS.
+ * Un "bullet" es una línea que empieza con `-` o `*` (ignorando indentación).
+ * Un "párrafo" es bloque de texto contiguo sin línea vacía.
+ */
+function detectarBulletsGigantes(contenido) {
+  const lineas = contenido.split('\n');
+  const gigantes = [];
+  let buffer = '';
+  let lineaInicio = 0;
+  let dentroDeBullet = false;
+  let dentroDeCodeFence = false;
+
+  const flush = () => {
+    if (buffer.length > MAX_BULLET_CHARS) {
+      gigantes.push({
+        linea: lineaInicio + 1,
+        chars: buffer.length,
+        preview: buffer.slice(0, 100) + (buffer.length > 100 ? '…' : ''),
+      });
+    }
+    buffer = '';
+    dentroDeBullet = false;
+  };
+
+  for (let i = 0; i < lineas.length; i++) {
+    const linea = lineas[i];
+
+    // Skipear bloques de código (no son bullets)
+    if (/^\s*```/.test(linea)) {
+      flush();
+      dentroDeCodeFence = !dentroDeCodeFence;
+      continue;
+    }
+    if (dentroDeCodeFence) continue;
+
+    // Skipear tablas Markdown (líneas que empiezan con `|`):
+    // las tablas son grandes por naturaleza y no son "bullets monolíticos"
+    if (/^\s*\|/.test(linea)) {
+      flush();
+      continue;
+    }
+
+    // Línea vacía termina el bullet/párrafo actual
+    if (/^\s*$/.test(linea)) {
+      flush();
+      continue;
+    }
+
+    // Header termina el buffer
+    if (/^#/.test(linea)) {
+      flush();
+      continue;
+    }
+
+    // Inicio de nuevo bullet
+    if (/^\s*[-*+]\s/.test(linea)) {
+      flush();
+      lineaInicio = i;
+      buffer = linea;
+      dentroDeBullet = true;
+      continue;
+    }
+
+    // Continuación: si estamos en bullet, acumular; si no, párrafo
+    if (dentroDeBullet) {
+      buffer += '\n' + linea;
+    } else {
+      if (buffer === '') lineaInicio = i;
+      buffer += (buffer ? '\n' : '') + linea;
+    }
+  }
+  flush();
+  return gigantes;
+}
+
+// ─── CLI ──────────────────────────────────────────────────────────────────
+
+function imprimirReporte(resultado) {
+  const colorVeredicto = {
+    OK: '\x1b[32m',     // verde
+    WARN: '\x1b[33m',   // amarillo
+    ERROR: '\x1b[31m',  // rojo
+  };
+  const reset = '\x1b[0m';
+
+  console.log(`\n${colorVeredicto[resultado.veredicto]}=== AUDITORÍA CLAUDE.md ===${reset}`);
+  console.log(`Veredicto: ${colorVeredicto[resultado.veredicto]}${resultado.veredicto}${reset}`);
+  console.log(`Ruta: ${resultado.ruta || '(no encontrado)'}\n`);
+
+  if (resultado.metricas) {
+    const m = resultado.metricas;
+    console.log(`Métricas:`);
+    console.log(`  - Líneas: ${m.lineas} / ${m.umbral_lineas}`);
+    console.log(`  - Secciones canónicas presentes: ${m.secciones_presentes.length}/4 (${m.secciones_presentes.join(', ') || 'ninguna'})`);
+    if (m.secciones_ausentes.length > 0) {
+      console.log(`  - Secciones ausentes: ${m.secciones_ausentes.join(', ')}`);
+    }
+    console.log(`  - @references: ${m.tiene_at_references ? 'sí' : 'no'}`);
+    console.log('');
+  }
+
+  if (resultado.hallazgos.length === 0) {
+    console.log('Sin hallazgos. CLAUDE.md cumple best practices Anthropic.\n');
+    return;
+  }
+
+  console.log(`Hallazgos (${resultado.hallazgos.length}):\n`);
+  for (const h of resultado.hallazgos) {
+    const color = colorVeredicto[h.severidad] || '';
+    console.log(`  ${color}[${h.severidad}]${reset} ${h.mensaje}`);
+    if (h.sugerencia) console.log(`    → ${h.sugerencia}`);
+    if (h.preview) console.log(`    Preview: ${h.preview}`);
+    console.log('');
+  }
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const flagJson = args.includes('--json');
+  const flagStrict = args.includes('--strict');
+  const rutaArg = args.find(a => !a.startsWith('--'));
+
+  const ruta = rutaArg
+    ? path.resolve(rutaArg)
+    : ubicarClaudeMd();
+
+  const resultado = auditar(ruta);
+
+  if (flagJson) {
+    console.log(JSON.stringify(resultado, null, 2));
+  } else {
+    imprimirReporte(resultado);
+  }
+
+  if (resultado.veredicto === 'ERROR') process.exit(1);
+  if (flagStrict && resultado.veredicto === 'WARN') process.exit(1);
+  process.exit(0);
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = { auditar, ubicarClaudeMd, detectarBulletsGigantes, main, MAX_LINES, MAX_BULLET_CHARS };

package/scripts/bootstrap-instintos.js

@@ -266,4 +266,4 @@ function main() {
 
 if (require.main === module) main();
 
-module.exports = { parsearAprendizajes, generarInstintos, detectarConfidence };
+module.exports = { parsearAprendizajes, generarInstintos, detectarConfidence, main };

package/scripts/cli/audit-agents-gaps.js

@@ -0,0 +1,36 @@
+'use strict';
+
+/**
+ * Wrapper CLI para `swl-ses audit-agents-gaps`.
+ *
+ * Audita gaps de metadata defensiva en agentes (Exclusion Clauses, fragments,
+ * frontmatter completo). El script standalone NO exporta main, ejecuta en
+ * top-level. Wrapper hace require() directo con argv manipulado.
+ *
+ * Flags soportadas:
+ *   --resumen   → output resumen compacto
+ *   --json      → output JSON estructurado
+ */
+
+const path = require('path');
+
+function auditAgentsGaps(opciones) {
+  const args = [];
+  if (opciones && opciones.resumen) args.push('--resumen');
+  if (opciones && opciones.json) args.push('--json');
+  if (opciones && Array.isArray(opciones._args)) {
+    args.push(...opciones._args);
+  }
+
+  const argvOriginal = process.argv;
+  process.argv = ['node', 'auditar-agentes-gaps.js', ...args];
+  try {
+    const ruta = path.resolve(__dirname, '..', 'auditar-agentes-gaps.js');
+    delete require.cache[ruta];
+    require(ruta);
+  } finally {
+    process.argv = argvOriginal;
+  }
+}
+
+module.exports = auditAgentsGaps;