@saulwade/swl-ses 1.0.0

package/scripts/lib/configurar-ci.js

@@ -0,0 +1,380 @@
+'use strict';
+
+/**
+ * scripts/lib/configurar-ci.js
+ *
+ * Lógica reutilizable para /swl:configurar-ci.
+ * Gestiona la instalación, estado y desinstalación de los workflows CI/CD
+ * de swl-ses en proyectos de usuarios.
+ *
+ * API pública:
+ *   init(opciones)              — copia plantillas al proyecto destino
+ *   status(opciones)            — lista workflows instalados y secrets faltantes
+ *   uninstall(opciones)         — elimina workflows SWL del proyecto
+ *   detectarMetodoProteccion()  — detecta si usar Rulesets o legacy (para branch protection)
+ *   construirPayloadRuleset()   — construye el payload para la API de Rulesets
+ *   construirPayloadClassic()   — construye el payload para branch protection legacy
+ *
+ * Ninguna función hace network ni invoca gh CLI directamente.
+ * El llamador (comando /swl:configurar-ci) orquesta las llamadas interactivas.
+ *
+ * NOTA: Las funciones de branch protection (detectarMetodoProteccion,
+ * construirPayloadRuleset, construirPayloadClassic) están aquí para que el
+ * comando distribuido /swl:configurar-ci pueda usarlas sin depender del
+ * script del repo madre (configurar-branch-protection.js), que NO se
+ * distribuye a los proyectos de los usuarios.
+ *
+ * Referencia API Rulesets: https://docs.github.com/en/rest/repos/rules
+ * Restricción de plan legacy: https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches
+ */
+
+const fs   = require('node:fs');
+const path = require('node:path');
+const os   = require('node:os');
+
+// ---------------------------------------------------------------------------
+// Rutas y constantes
+// ---------------------------------------------------------------------------
+
+/** Directorio de plantillas dentro del repo swl-ses instalado. */
+const PLANTILLAS_DIR = path.join(__dirname, '..', '..', 'plantillas', 'github-workflows');
+
+/** Nombre del directorio destino en el proyecto del usuario. */
+const WORKFLOWS_DIR = '.github/workflows';
+
+/** Workflows que este módulo gestiona (identificados por nombre de archivo). */
+const WORKFLOWS_SWL = {
+  security: 'swl-security.yml',
+  ci:       'swl-ci.yml',
+  release:  'release-please.yml',
+};
+
+/** Secrets que requiere cada workflow. */
+const SECRETS_REQUERIDOS = {
+  'swl-security.yml': ['CLAUDE_API_KEY'],
+  'swl-ci.yml':       [],
+  'release-please.yml': [],
+};
+
+// ---------------------------------------------------------------------------
+// Helpers internos
+// ---------------------------------------------------------------------------
+
+/**
+ * Valida que el path del proyecto destino sea seguro.
+ * Previene path traversal y paths relativos.
+ *
+ * @param {string} proyectPath
+ * @throws {Error} Si el path no es seguro
+ */
+function validarPathProyecto(proyectPath) {
+  if (!path.isAbsolute(proyectPath)) {
+    throw new Error(`El path del proyecto debe ser absoluto. Recibido: "${proyectPath}"`);
+  }
+  // Normalizar y verificar que no escape con ..
+  const normalizado = path.normalize(proyectPath);
+  if (normalizado !== proyectPath) {
+    throw new Error(`El path contiene secuencias inseguras: "${proyectPath}"`);
+  }
+  // Bloquear paths sospechosos (rutas del sistema)
+  const peligrosos = ['/etc', '/usr', '/var', '/bin', '/sbin', '/boot', '/proc', '/sys'];
+  const enPeligroso = peligrosos.some(p => normalizado.startsWith(p + path.sep) || normalizado === p);
+  if (enPeligroso) {
+    throw new Error(`El path apunta a un directorio del sistema: "${proyectPath}"`);
+  }
+}
+
+/**
+ * Detecta el directorio del proyecto actual.
+ * Usa override para tests.
+ *
+ * @param {string|undefined} override
+ * @returns {string}
+ */
+function detectarProyecto(override) {
+  const dir = override || process.cwd();
+  validarPathProyecto(dir);
+  return dir;
+}
+
+/**
+ * Lista los archivos en el directorio de plantillas.
+ *
+ * @returns {string[]} nombres de archivo
+ */
+function listarPlantillas() {
+  try {
+    return fs.readdirSync(PLANTILLAS_DIR).filter(f => f.endsWith('.yml'));
+  } catch (_) {
+    return [];
+  }
+}
+
+// ---------------------------------------------------------------------------
+// init
+// ---------------------------------------------------------------------------
+
+/**
+ * Copia los workflows seleccionados al proyecto destino.
+ *
+ * @param {object} opciones
+ * @param {boolean} [opciones.withSecurity=true]         Instalar swl-security.yml
+ * @param {boolean} [opciones.withCi=true]               Instalar swl-ci.yml
+ * @param {boolean} [opciones.withReleasePlease=false]   Instalar release-please.yml
+ * @param {boolean} [opciones.dryRun=false]              Solo mostrar cambios, no copiar
+ * @param {boolean} [opciones.force=false]               Sobreescribir archivos existentes
+ * @param {string}  [opciones._proyectoPathOverride]     Path del proyecto (tests)
+ * @returns {{ copiados: string[], existentes: string[], error?: string }}
+ */
+function init({
+  withSecurity = true,
+  withCi       = true,
+  withReleasePlease = false,
+  dryRun       = false,
+  force        = false,
+  _proyectoPathOverride,
+} = {}) {
+  const proyecto = detectarProyecto(_proyectoPathOverride);
+  const destDir  = path.join(proyecto, WORKFLOWS_DIR);
+
+  const seleccionados = [];
+  if (withSecurity)     seleccionados.push(WORKFLOWS_SWL.security);
+  if (withCi)           seleccionados.push(WORKFLOWS_SWL.ci);
+  if (withReleasePlease) seleccionados.push(WORKFLOWS_SWL.release);
+
+  const copiados   = [];
+  const existentes = [];
+
+  for (const archivo of seleccionados) {
+    const origen  = path.join(PLANTILLAS_DIR, archivo);
+    const destino = path.join(destDir, archivo);
+
+    if (!fs.existsSync(origen)) {
+      return { copiados, existentes, error: `Plantilla no encontrada: ${origen}` };
+    }
+
+    if (fs.existsSync(destino) && !force) {
+      existentes.push(archivo);
+      continue;
+    }
+
+    if (!dryRun) {
+      fs.mkdirSync(destDir, { recursive: true });
+      fs.copyFileSync(origen, destino);
+    }
+    copiados.push(archivo);
+  }
+
+  return { copiados, existentes };
+}
+
+// ---------------------------------------------------------------------------
+// status
+// ---------------------------------------------------------------------------
+
+/**
+ * Verifica qué workflows SWL están instalados en el proyecto.
+ *
+ * @param {object} opciones
+ * @param {string} [opciones._proyectoPathOverride]
+ * @returns {{ instalados: string[], faltantes: string[], secretsFaltantes: Record<string,string[]> }}
+ */
+function status({ _proyectoPathOverride } = {}) {
+  const proyecto  = detectarProyecto(_proyectoPathOverride);
+  const destDir   = path.join(proyecto, WORKFLOWS_DIR);
+  const instalados = [];
+  const faltantes  = [];
+  const secretsFaltantes = {};
+
+  for (const [, archivo] of Object.entries(WORKFLOWS_SWL)) {
+    const ruta = path.join(destDir, archivo);
+    if (fs.existsSync(ruta)) {
+      instalados.push(archivo);
+      const requeridos = SECRETS_REQUERIDOS[archivo] || [];
+      if (requeridos.length > 0) {
+        // No podemos verificar secrets reales sin gh CLI — reportar los necesarios
+        secretsFaltantes[archivo] = requeridos;
+      }
+    } else {
+      faltantes.push(archivo);
+    }
+  }
+
+  return { instalados, faltantes, secretsFaltantes };
+}
+
+// ---------------------------------------------------------------------------
+// uninstall
+// ---------------------------------------------------------------------------
+
+/**
+ * Elimina los workflows SWL del proyecto destino.
+ * Solo elimina archivos gestionados por swl-ses, no otros workflows.
+ *
+ * @param {object} opciones
+ * @param {boolean} [opciones.confirmar=false]   Si false, solo lista qué se eliminaría
+ * @param {string}  [opciones._proyectoPathOverride]
+ * @returns {{ eliminados: string[], noEncontrados: string[] }}
+ */
+function uninstall({ confirmar = false, _proyectoPathOverride } = {}) {
+  const proyecto  = detectarProyecto(_proyectoPathOverride);
+  const destDir   = path.join(proyecto, WORKFLOWS_DIR);
+  const eliminados    = [];
+  const noEncontrados = [];
+
+  for (const [, archivo] of Object.entries(WORKFLOWS_SWL)) {
+    const ruta = path.join(destDir, archivo);
+    if (!fs.existsSync(ruta)) {
+      noEncontrados.push(archivo);
+      continue;
+    }
+    if (confirmar) {
+      fs.unlinkSync(ruta);
+    }
+    eliminados.push(archivo);
+  }
+
+  return { eliminados, noEncontrados };
+}
+
+// ---------------------------------------------------------------------------
+// Branch protection — lógica distribuible
+//
+// Estas funciones replican la lógica de scripts/configurar-branch-protection.js
+// para uso en el comando /swl:configurar-ci. Son puras (sin side effects de red).
+// El llamador es responsable de ejecutar gh api con el payload devuelto.
+// ---------------------------------------------------------------------------
+
+/** Status checks requeridos por defecto para la protección de rama. */
+const STATUS_CHECKS_DEFAULT = ['test (22)', 'test (24)', 'smoke'];
+
+/** Nombre canónico del ruleset gestionado por swl-ses. */
+const NOMBRE_RULESET_SWL = 'swl-protection-main';
+
+/**
+ * Detecta qué método de branch protection conviene usar según el plan del repo.
+ *
+ * Diseñado para ser llamado con el output de `gh api /repos/{owner}/{repo}`.
+ * No hace network — recibe repoInfo ya parseado.
+ *
+ * Lógica:
+ *   - Repo privado + plan Free o desconocido → 'rulesets'
+ *   - Repo privado + plan Pro/Team/Enterprise → 'classic'
+ *   - Repo público → 'classic'
+ *   - --prefer-rulesets → 'rulesets' (override)
+ *   - --prefer-classic  → 'classic'  (override)
+ *
+ * Referencia: https://docs.github.com/en/rest/repos/repos#get-a-repository
+ *   Campo `private` (boolean), campo `owner.plan.name` (string)
+ *
+ * @param {{ private: boolean, owner?: { plan?: { name?: string } } } | null} repoInfo
+ * @param {{ preferRulesets?: boolean, preferClassic?: boolean }} [flags]
+ * @returns {'rulesets'|'classic'}
+ */
+function detectarMetodoProteccion(repoInfo, flags = {}) {
+  if (flags.preferRulesets) return 'rulesets';
+  if (flags.preferClassic)  return 'classic';
+
+  if (!repoInfo) return 'rulesets'; // fallback seguro si no hay info
+
+  const esPrivado = repoInfo.private === true;
+  const plan      = repoInfo.owner?.plan?.name || 'desconocido';
+
+  if (esPrivado && (plan === 'free' || plan === 'desconocido')) {
+    return 'rulesets';
+  }
+  return 'classic';
+}
+
+/**
+ * Construye el payload para la API de GitHub Rulesets.
+ *
+ * Fuente: https://docs.github.com/en/rest/repos/rules#create-a-repository-ruleset
+ *
+ * @param {{ rama?: string, approvals?: number, statusChecks?: string[] }} [opciones]
+ * @returns {object} Payload listo para JSON.stringify y envío a la API
+ */
+function construirPayloadRuleset({ rama = 'main', approvals = 1, statusChecks = STATUS_CHECKS_DEFAULT } = {}) {
+  return {
+    name:        NOMBRE_RULESET_SWL,
+    target:      'branch',
+    enforcement: 'active',
+    conditions: {
+      ref_name: {
+        include: ['refs/heads/' + rama],
+        exclude: [],
+      },
+    },
+    rules: [
+      {
+        type: 'pull_request',
+        parameters: {
+          required_approving_review_count:   approvals,
+          dismiss_stale_reviews_on_push:     true,
+          require_code_owner_review:         false,
+          require_last_push_approval:        false,
+          required_review_thread_resolution: false,
+        },
+      },
+      {
+        type: 'required_status_checks',
+        parameters: {
+          required_status_checks: statusChecks.map(c => ({
+            context:        c,
+            integration_id: null,
+          })),
+          strict_required_status_checks_policy: true,
+        },
+      },
+      { type: 'non_fast_forward' },
+      { type: 'deletion' },
+    ],
+  };
+}
+
+/**
+ * Construye el payload para la API de Branch protection legacy.
+ *
+ * Fuente: https://docs.github.com/en/rest/branches/branch-protection
+ *
+ * @param {{ approvals?: number, statusChecks?: string[] }} [opciones]
+ * @returns {object}
+ */
+function construirPayloadClassic({ approvals = 1, statusChecks = STATUS_CHECKS_DEFAULT } = {}) {
+  return {
+    required_status_checks: {
+      strict:   true,
+      contexts: statusChecks,
+    },
+    enforce_admins: false,
+    required_pull_request_reviews: {
+      required_approving_review_count: approvals,
+      dismiss_stale_reviews:           false,
+      require_code_owner_reviews:      false,
+    },
+    restrictions:       null,
+    allow_force_pushes: false,
+    allow_deletions:    false,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+module.exports = {
+  init,
+  status,
+  uninstall,
+  // Lógica de branch protection distribuible
+  detectarMetodoProteccion,
+  construirPayloadRuleset,
+  construirPayloadClassic,
+  // Constantes para tests y para el comando
+  WORKFLOWS_SWL,
+  WORKFLOWS_DIR,
+  PLANTILLAS_DIR,
+  SECRETS_REQUERIDOS,
+  NOMBRE_RULESET_SWL,
+  STATUS_CHECKS_DEFAULT,
+};

package/scripts/lib/console-span-exporter.js

@@ -0,0 +1,92 @@
+'use strict';
+
+/**
+ * ConsoleSpanExporter — exportador de referencia para depuración manual.
+ *
+ * Imprime spans a stderr con formato compacto. NO se activa automáticamente
+ * en ningún flujo del sistema. Debe invocarse de forma explícita únicamente
+ * durante sesiones de depuración local.
+ *
+ * Uso correcto:
+ *   const { ConsoleSpanExporter } = require('./console-span-exporter');
+ *   const exportador = new ConsoleSpanExporter();
+ *   exportador.export([span]);   // imprime a stderr
+ *
+ * IMPORTANTE: Este exportador no debe requerirse ni ejecutarse en hooks de
+ * producción ni durante flujos normales de telemetría. Es exclusivamente
+ * una herramienta de introspección manual para el desarrollador.
+ *
+ * Zero-deps. Solo módulos nativos de Node.js.
+ *
+ * @module scripts/lib/console-span-exporter
+ */
+
+const { TracingExporter } = require('./tracing-processor-interface');
+
+// ---------------------------------------------------------------------------
+// ConsoleSpanExporter
+// ---------------------------------------------------------------------------
+
+/**
+ * Exportador que escribe spans a stderr en formato compacto.
+ *
+ * Formato de salida:
+ *   [span] tipo=X nombre=Y duracion=Zms estado=OK|ERROR
+ *
+ * Usa process.stderr.write (nunca console.log) para no contaminar stdout.
+ *
+ * @extends TracingExporter
+ *
+ * @example
+ * const exp = new ConsoleSpanExporter();
+ * exp.export([{ tipo: 'agent', nombre: 'revisor-swl', duracionMs: 120, estado: 'OK' }]);
+ * // stderr: [span] tipo=agent nombre=revisor-swl duracion=120ms estado=OK
+ */
+class ConsoleSpanExporter extends TracingExporter {
+  /**
+   * Exporta un array de spans escribiendo cada uno a stderr.
+   *
+   * El método es tolerante: si un ítem no puede formatearse, escribe
+   * una línea de error y continúa con el siguiente.
+   *
+   * @param {object[]} items - Array de spans a exportar.
+   * @returns {void}
+   */
+  export(items) {
+    if (!Array.isArray(items)) return;
+
+    for (const item of items) {
+      try {
+        const linea = _formatearSpan(item);
+        process.stderr.write(linea + '\n');
+      } catch (_) {
+        process.stderr.write('[span] <error al formatear el ítem>\n');
+      }
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers privados
+// ---------------------------------------------------------------------------
+
+/**
+ * Formatea un span como línea de texto compacta.
+ *
+ * @param {object} span - Span a formatear.
+ * @returns {string} Línea formateada lista para impresión.
+ */
+function _formatearSpan(span) {
+  const tipo      = span.tipo      || span.nombre  || 'desconocido';
+  const nombre    = span.nombre    || '—';
+  const duracion  = typeof span.duracionMs === 'number' ? `${span.duracionMs}ms` : 'N/A';
+  const estado    = span.estado    || 'N/A';
+
+  return `[span] tipo=${tipo} nombre=${nombre} duracion=${duracion} estado=${estado}`;
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+module.exports = { ConsoleSpanExporter };

package/scripts/lib/contadores-inventario.js

@@ -0,0 +1,217 @@
+'use strict';
+
+/**
+ * contadores-inventario.js
+ *
+ * Funciones puras zero-deps para validar consistencia entre los contadores
+ * de inventario (agentes, skills, comandos, hooks, reglas) declarados en
+ * `INVENTARIO.md` (fuente de verdad regenerada por
+ * `scripts/generar-inventario.js`) y los contadores citados en los demás
+ * documentos canónicos del repositorio.
+ *
+ * Motivado por el drift recurrente detectado el 2026-04-29: MAPEO_SKILLS_AGENTES.md
+ * decía "153 skills" cuando la realidad eran 150; COMPACTACION.md reportaba
+ * "147 skills, 40 comandos, 31 hooks". El hook `verificar-release.js` valida
+ * versión pero no contadores. Este módulo cierra ese hueco.
+ *
+ * Cobertura intencional:
+ *   - Patrón resumen "X agentes, Y skills, Z comandos, W reglas, V hooks"
+ *     (separadores `,` o `+` o `y`) — valida los 5 números a la vez.
+ *   - Patrón "X agentes + Y habilidades + Z comandos + W reglas + V hooks"
+ *     común en tablas de perfiles `completo`.
+ *   - Patrón "Total de agentes: X" / "Total de skills: X" en MAPEO.
+ *
+ * Cobertura intencionalmente excluida (falsos positivos clásicos):
+ *   - "los 17 skills de Anthropic" (skills externos)
+ *   - "8 lenguajes × 5 reglas" (multiplicación)
+ *   - perfiles parciales "2 hooks", "6 hooks" (no son totales)
+ *   - notas históricas "estimé 28 hooks visualmente y propagué el error"
+ *   - referencias a versiones pasadas en MAPEO ("136 skills tras release X")
+ *   - filas de tabla histórica con SemVer + fecha ("| 5.4.0 | 2026-04-10 | 57 agentes...")
+ *
+ * Estas se ignoran porque el patrón resumen es el único que tiene los 5
+ * componentes alineados; las menciones aisladas de un solo número se dejan
+ * para una auditoría aparte (no bloqueante).
+ */
+
+const COMPONENTES = ['agentes', 'skills', 'comandos', 'hooks', 'reglas'];
+
+/**
+ * Parsea la sección "## Resumen" de INVENTARIO.md y retorna un mapa con
+ * los contadores reales del sistema.
+ *
+ * Espera tabla del tipo:
+ *   ## Resumen
+ *   | Componente | Cantidad |
+ *   |-----------|----------|
+ *   | Agentes SWL | 59 |
+ *   | Habilidades | 150 |
+ *   | Comandos | 41 |
+ *   | Reglas base | 20 |
+ *   | Reglas por lenguaje | 40 |
+ *   | Hooks | 36 |
+ *
+ * Retorna `{ agentes, skills, comandos, hooks, reglas }`.
+ * `skills` y `habilidades` se mapean al mismo número.
+ * `reglas` = base + por_lenguaje.
+ */
+function parsearInventario(rawMd) {
+  const lineas = rawMd.split(/\r?\n/);
+  const resumen = {};
+  let enResumen = false;
+  for (const linea of lineas) {
+    if (/^##\s+Resumen\s*$/.test(linea)) { enResumen = true; continue; }
+    if (enResumen && /^##\s+/.test(linea)) break;
+    if (!enResumen) continue;
+    const m = linea.match(/^\|\s*([^|]+?)\s*\|\s*(\d+)\s*\|/);
+    if (m) resumen[m[1].trim()] = parseInt(m[2], 10);
+  }
+
+  const reglasBase = resumen['Reglas base'] || 0;
+  const reglasLeng = resumen['Reglas por lenguaje'] || 0;
+
+  return {
+    agentes: resumen['Agentes SWL'] || 0,
+    skills: resumen['Habilidades'] || 0,
+    comandos: resumen['Comandos'] || 0,
+    hooks: resumen['Hooks'] || 0,
+    reglas: reglasBase + reglasLeng,
+  };
+}
+
+/**
+ * Detecta el patrón resumen en una línea y retorna los números encontrados.
+ * Soporta separadores `,`, `+` y `y`. Tolera el orden canónico
+ * agentes → skills/habilidades → comandos → reglas → hooks.
+ *
+ * Ejemplos que matchean:
+ *   "59 agentes, 150 skills, 41 comandos, 60 reglas, 36 hooks"
+ *   "59 agentes + 150 habilidades + 41 comandos + 60 reglas + 36 hooks"
+ *   "59 agentes, 150 skills, 41 comandos, 60 reglas y 36 hooks"
+ *   "Frontmatter: 59 agentes + 150 skills + 41 comandos verificados"
+ *     (los 3 primeros se validan; los 2 últimos faltan → no full match,
+ *      se devuelve match parcial con flags)
+ *
+ * Retorna `null` si no encuentra al menos `agentes` y un segundo componente.
+ */
+function extraerResumenDeLinea(linea) {
+  // Patrón principal: 5 componentes en orden
+  const re5 = /(\d{1,4})\s+agentes?[\s,+y]+\s*(\d{1,4})\s+(?:skills|habilidades)[\s,+y]+\s*(\d{1,4})\s+comandos[\s,+y]+\s*(\d{1,4})\s+reglas[\s,+y]+\s*(\d{1,4})\s+hooks/i;
+  const m5 = linea.match(re5);
+  if (m5) {
+    return {
+      tipo: 'resumen5',
+      texto: m5[0],
+      agentes: parseInt(m5[1], 10),
+      skills: parseInt(m5[2], 10),
+      comandos: parseInt(m5[3], 10),
+      reglas: parseInt(m5[4], 10),
+      hooks: parseInt(m5[5], 10),
+    };
+  }
+
+  // Patrón parcial: 3 componentes (agentes, skills/habilidades, comandos)
+  const re3 = /(\d{1,4})\s+agentes?[\s,+y]+\s*(\d{1,4})\s+(?:skills|habilidades)[\s,+y]+\s*(\d{1,4})\s+comandos/i;
+  const m3 = linea.match(re3);
+  if (m3) {
+    return {
+      tipo: 'resumen3',
+      texto: m3[0],
+      agentes: parseInt(m3[1], 10),
+      skills: parseInt(m3[2], 10),
+      comandos: parseInt(m3[3], 10),
+    };
+  }
+
+  return null;
+}
+
+/**
+ * Decide si una línea debe ignorarse por ser obviamente histórica
+ * (fila de changelog/timeline con versión SemVer + fecha en formato tabla).
+ */
+function esLineaHistorica(linea) {
+  // Tabla con versión SemVer + fecha ISO: "| 5.4.0 | 2026-04-10 | ..."
+  if (/^\s*\|\s*\d+\.\d+\.\d+\s*\|\s*\d{4}-\d{2}-\d{2}/.test(linea)) return true;
+  // "Baseline:" suele ser nota histórica
+  if (/\bBaseline\s*:/i.test(linea)) return true;
+  // "antes de v|previa a|tras release N" sugiere historia
+  if (/\b(?:antes de v|previa a|tras release|en v\d+\.\d+)\b/i.test(linea)) return true;
+  // Línea entre comillas dobles (cita textual de un patrón documentado): "22 hooks"
+  if (/"\s*\d+\s+(?:agentes|skills|habilidades|comandos|hooks|reglas)\s*"/i.test(linea)) return true;
+  return false;
+}
+
+/**
+ * Valida un archivo contra los contadores reales.
+ * Solo flagea las líneas que contienen patrón resumen identificable.
+ *
+ * Retorna { ok, lineas_revisadas, discrepancias: [{linea, encontrado, esperado, tipo, contexto}] }
+ */
+function validarArchivo(rawMd, contadoresReales) {
+  const lineas = rawMd.split(/\r?\n/);
+  const discrepancias = [];
+  let lineasRevisadas = 0;
+
+  for (let i = 0; i < lineas.length; i++) {
+    if (esLineaHistorica(lineas[i])) continue;
+    const r = extraerResumenDeLinea(lineas[i]);
+    if (!r) continue;
+    lineasRevisadas++;
+
+    const campos = r.tipo === 'resumen5'
+      ? COMPONENTES
+      : ['agentes', 'skills', 'comandos'];
+
+    for (const campo of campos) {
+      if (r[campo] !== contadoresReales[campo]) {
+        discrepancias.push({
+          linea: i + 1,
+          campo,
+          encontrado: r[campo],
+          esperado: contadoresReales[campo],
+          tipo: r.tipo,
+          contexto: lineas[i].trim().slice(0, 110),
+        });
+      }
+    }
+  }
+
+  // Patrón nominal: "**Total de agentes**: N", "**Total de skills**: N"
+  const reTotal = /\*?\*?Total\s+de\s+(agentes|skills|habilidades|comandos|hooks|reglas)\*?\*?\s*:\s*(\d{1,4})/gi;
+  for (let i = 0; i < lineas.length; i++) {
+    if (esLineaHistorica(lineas[i])) continue;
+    let m;
+    reTotal.lastIndex = 0;
+    while ((m = reTotal.exec(lineas[i])) !== null) {
+      const palabra = m[1].toLowerCase();
+      const campo = palabra === 'habilidades' ? 'skills' : palabra;
+      const num = parseInt(m[2], 10);
+      lineasRevisadas++;
+      if (num !== contadoresReales[campo]) {
+        discrepancias.push({
+          linea: i + 1,
+          campo,
+          encontrado: num,
+          esperado: contadoresReales[campo],
+          tipo: 'total_nominal',
+          contexto: lineas[i].trim().slice(0, 110),
+        });
+      }
+    }
+  }
+
+  return {
+    ok: discrepancias.length === 0,
+    lineas_revisadas: lineasRevisadas,
+    discrepancias,
+  };
+}
+
+module.exports = {
+  COMPONENTES,
+  parsearInventario,
+  extraerResumenDeLinea,
+  esLineaHistorica,
+  validarArchivo,
+};