@saulwade/swl-ses 1.5.2 → 1.6.1

package/scripts/verificar-docs-vs-codigo.js

@@ -0,0 +1,654 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * scripts/verificar-docs-vs-codigo.js
+ *
+ * Verificador automatizado de drift entre documentación y estado real del
+ * proyecto. Pensado para correr en CI tras un release o cuando se modifican
+ * componentes del sistema.
+ *
+ * Checks implementados:
+ *
+ *   1. CONTADORES: INVENTARIO.md vs disco
+ *      Verifica que los contadores (agentes, skills, comandos, hooks, reglas)
+ *      reportados en INVENTARIO.md, README.md, AGENTS.md, MANUAL_USO.md,
+ *      package.json#description y plugin.json#description coincidan con lo
+ *      que existe en disco.
+ *
+ *   2. COMANDOS: comandos/swl/*.md vs COMANDOS.md y MANUAL_USO.md
+ *      Cada comando con archivo en comandos/swl/ debe:
+ *        (a) Aparecer en COMANDOS.md y MANUAL_USO.md (presencia).
+ *        (b) Tener al menos PROFUNDIDAD_MINIMA menciones en MANUAL_USO si
+ *            no es comando trivial (FAIL, no WARN — endurecido v1.6.1).
+ *      Rationale: el verificador previo aceptaba 1 mención como
+ *      "documentado", lo que genera drift estructural invisible. Ver
+ *      reglas/auditorias-documentales-estructurales.md.
+ *
+ *   3. FLAGS críticos: parser vs docs
+ *      Si parsear-opciones.js declara una flag como booleana, debe aparecer
+ *      en bin/swl-ses.js --help y en COMANDOS.md tabla de opciones.
+ *
+ *   4. VERSIONES: package.json vs encabezados de docs
+ *      Las primeras líneas de CLAUDE.md, README.md, AGENTS.md, COMANDOS.md,
+ *      MANUAL_USO.md, INSTALACION.md deben mencionar la versión de
+ *      package.json.
+ *
+ *   5. TUI: scripts/tui/pantallas/*.js vs docs
+ *      Cada pantalla del TUI (welcome, menu-principal, install-wizard,
+ *      update-wizard, uninstall-wizard, inspect, progreso, resumen) debe
+ *      tener al menos una mención en MANUAL_USO.md.
+ *
+ *   6. VARIABLES DE ENTORNO: SWL_* en código vs docs/variables-entorno.md
+ *      Toda variable SWL_* que aparezca en hooks/ o scripts/ debe estar
+ *      documentada en docs/variables-entorno.md (catálogo formal único).
+ *      FAIL si hay huérfanas. Cierra el gap detectado en sesión 2026-05-16
+ *      donde 22 de 58 variables existían en código pero no en docs.
+ *
+ *   7. REGLAS: reglas/*.md en disco vs manifiestos/modulos.json
+ *      Toda regla base (excluyendo fragmentos `_*.md`) debe estar
+ *      registrada en algún módulo de manifiestos/modulos.json. Sin esto
+ *      el instalador no la propaga al destino del usuario.
+ *
+ *   8. ADRs vs CHANGELOG: ADRs aceptados con referencia en CHANGELOG.md
+ *      WARN si un ADR en estado "Aceptado" no aparece referenciado en
+ *      CHANGELOG.md. Subjetivo (no todo ADR cambia comportamiento
+ *      observable), por eso reporta WARN sin bloquear.
+ *
+ * Exit codes:
+ *   0 — todos los checks pasan
+ *   1 — hay drift en al menos un check obligatorio
+ *   2 — error de invocación
+ *
+ * Uso:
+ *   node scripts/verificar-docs-vs-codigo.js [--check N] [--quiet]
+ *
+ *   --check N    Ejecuta solo el check N (1-8). Sin flag: todos.
+ *   --quiet      Suprime el output de checks que pasan; solo reporta fallas.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const RAIZ = path.resolve(__dirname, '..');
+
+// ── helpers ───────────────────────────────────────────────────────────────────
+
+function leerArchivo(rel) {
+  try {
+    return fs.readFileSync(path.join(RAIZ, rel), 'utf-8');
+  } catch (_) {
+    return null;
+  }
+}
+
+function contarEntradasDirectorio(dir, opts = {}) {
+  const dirAbs = path.join(RAIZ, dir);
+  if (!fs.existsSync(dirAbs)) return 0;
+  const entradas = fs.readdirSync(dirAbs, { withFileTypes: true });
+  if (opts.dirsOnly) return entradas.filter(e => e.isDirectory()).length;
+  if (opts.filesOnly) {
+    return entradas.filter(e => e.isFile() && (!opts.ext || e.name.endsWith(opts.ext))).length;
+  }
+  return entradas.length;
+}
+
+function contarHooksEjecutables() {
+  const dirAbs = path.join(RAIZ, 'hooks');
+  if (!fs.existsSync(dirAbs)) return 0;
+  return fs.readdirSync(dirAbs)
+    .filter(n => n.endsWith('.js') && !n.startsWith('_'))
+    .length;
+}
+
+function contarReglasMd() {
+  const dirAbs = path.join(RAIZ, 'reglas');
+  if (!fs.existsSync(dirAbs)) return 0;
+  // Cuenta archivos .md en raíz de reglas/ + subdirectorios por lenguaje
+  let total = 0;
+  function recurse(d) {
+    for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+      if (e.isDirectory() && !e.name.startsWith('_')) recurse(path.join(d, e.name));
+      else if (e.isFile() && e.name.endsWith('.md') && !e.name.startsWith('_')) total++;
+    }
+  }
+  recurse(dirAbs);
+  return total;
+}
+
+// ── reporting ─────────────────────────────────────────────────────────────────
+
+const COLOR_OK = '\x1b[32m';
+const COLOR_FAIL = '\x1b[31m';
+const COLOR_WARN = '\x1b[33m';
+const COLOR_DIM = '\x1b[2m';
+const COLOR_RESET = '\x1b[0m';
+const tty = !!process.stdout.isTTY;
+const c = (color, txt) => (tty ? `${color}${txt}${COLOR_RESET}` : txt);
+
+const opts = (() => {
+  const args = process.argv.slice(2);
+  const checkIdx = args.indexOf('--check');
+  return {
+    only: checkIdx >= 0 ? parseInt(args[checkIdx + 1], 10) : null,
+    quiet: args.includes('--quiet'),
+  };
+})();
+
+const resultados = [];
+
+function reportar(check, etiqueta, ok, detalle) {
+  resultados.push({ check, etiqueta, ok, detalle });
+  if (ok && opts.quiet) return;
+  const mark = ok ? c(COLOR_OK, '[OK]') : c(COLOR_FAIL, '[FAIL]');
+  console.log(`  ${mark} check #${check} — ${etiqueta}`);
+  if (detalle && !opts.quiet) {
+    for (const linea of String(detalle).split('\n')) {
+      console.log(`        ${c(COLOR_DIM, linea)}`);
+    }
+  } else if (detalle && !ok) {
+    for (const linea of String(detalle).split('\n')) {
+      console.log(`        ${linea}`);
+    }
+  }
+}
+
+// ── Check 1: contadores ──────────────────────────────────────────────────────
+
+function check1Contadores() {
+  if (opts.only && opts.only !== 1) return;
+  console.log(c(COLOR_DIM, '\n[1] Contadores: INVENTARIO.md / README.md / docs vs disco'));
+
+  const real = {
+    agentes: contarEntradasDirectorio('agentes', { filesOnly: true, ext: '.md' })
+      - (fs.existsSync(path.join(RAIZ, 'agentes', 'README.md')) ? 1 : 0),
+    skills: contarEntradasDirectorio('habilidades', { dirsOnly: true }),
+    comandos: contarEntradasDirectorio('comandos/swl', { filesOnly: true, ext: '.md' }),
+    reglas: contarReglasMd(),
+    hooks: contarHooksEjecutables(),
+  };
+
+  // Corregir agentes: descartar archivos `_*.md` (fragmentos compartidos)
+  const dirAgentes = path.join(RAIZ, 'agentes');
+  real.agentes = fs.readdirSync(dirAgentes)
+    .filter(n => n.endsWith('.md') && !n.startsWith('_') && n !== 'README.md')
+    .length;
+
+  // Cargar lo que dicen los manifiestos canónicos. INVENTARIO.md usa una
+  // tabla del tipo `| Agentes SWL | 60 |` así que extraemos por fila.
+  const inventario = leerArchivo('INVENTARIO.md') || '';
+  const extraerCelda = (regex) => {
+    const m = inventario.match(regex);
+    return m ? Number(m[1]) : null;
+  };
+  const declarado = {
+    agentes:  extraerCelda(/\|\s*Agentes[^|]*\|\s*(\d+)\s*\|/i),
+    skills:   extraerCelda(/\|\s*Habilidades[^|]*\|\s*(\d+)\s*\|/i)
+              || extraerCelda(/\|\s*Skills[^|]*\|\s*(\d+)\s*\|/i),
+    comandos: extraerCelda(/\|\s*Comandos[^|]*\|\s*(\d+)\s*\|/i),
+    reglas:   (() => {
+      // INVENTARIO.md separa "Reglas base" + "Reglas por lenguaje".
+      const base = extraerCelda(/\|\s*Reglas base[^|]*\|\s*(\d+)\s*\|/i) || 0;
+      const lang = extraerCelda(/\|\s*Reglas por lenguaje[^|]*\|\s*(\d+)\s*\|/i) || 0;
+      const total = extraerCelda(/\|\s*Reglas\s*\|\s*(\d+)\s*\|/i);
+      if (total) return total;
+      if (base + lang > 0) return base + lang;
+      return null;
+    })(),
+    hooks:    extraerCelda(/\|\s*Hooks\s*\|\s*(\d+)\s*\|/i),
+  };
+
+  for (const cat of Object.keys(real)) {
+    if (declarado[cat] == null) {
+      reportar(1, `INVENTARIO.md no declara ${cat}`, false,
+        `Real en disco: ${real[cat]}; INVENTARIO.md no incluye un patrón "(\\d+) ${cat}"`);
+    } else if (Number(declarado[cat]) === real[cat]) {
+      reportar(1, `INVENTARIO.md ${cat}: ${real[cat]}`, true);
+    } else {
+      reportar(1, `INVENTARIO.md ${cat} drift`, false,
+        `Real en disco: ${real[cat]}; INVENTARIO.md declara: ${declarado[cat]}`);
+    }
+  }
+}
+
+// ── Check 2: comandos/swl/*.md vs docs ──────────────────────────────────────
+
+function check2Comandos() {
+  if (opts.only && opts.only !== 2) return;
+  console.log(c(COLOR_DIM, '\n[2] Comandos /swl:* en disco vs COMANDOS.md y MANUAL_USO.md'));
+
+  const dirAbs = path.join(RAIZ, 'comandos/swl');
+  if (!fs.existsSync(dirAbs)) {
+    reportar(2, 'comandos/swl/ no existe', false, 'Directorio faltante');
+    return;
+  }
+
+  const archivos = fs.readdirSync(dirAbs)
+    .filter(n => n.endsWith('.md') && !n.startsWith('_') && n !== 'README.md');
+
+  const comandosMd = leerArchivo('COMANDOS.md') || '';
+  const manualUsoMd = leerArchivo('MANUAL_USO.md') || '';
+
+  // Profundidad mínima de menciones en MANUAL_USO.md para comandos no triviales.
+  // Origen: reglas/auditorias-documentales-estructurales.md. Sesión 2026-05-16
+  // detectó que el check anterior aceptaba 1 sola mención como "documentado",
+  // ocultando comandos como /swl:exportar-vault con solo 2 menciones reales.
+  const PROFUNDIDAD_MINIMA = 4;
+  // Comandos operacionales simples cuya documentación profunda no aplica
+  // (son utilities de un solo flag o estado).
+  const COMANDOS_TRIVIALES = new Set([
+    'ayuda', 'salud', 'modelo', 'contexto', 'dashboard',
+    'sesiones', 'instintos', 'metricas', 'mcp-status',
+  ]);
+
+  let presenciaFails = 0;
+  let profundidadFails = 0;
+  let documentados = 0;
+  const ausentes = [];
+  const infraDocumentados = [];
+
+  for (const archivo of archivos) {
+    const nombre = archivo.replace(/\.md$/, '');
+    const refSlash = `/swl:${nombre}`;
+    const enComandos = comandosMd.includes(refSlash);
+    const enManual = manualUsoMd.includes(refSlash);
+
+    if (!enComandos || !enManual) {
+      presenciaFails++;
+      const faltas = [];
+      if (!enComandos) faltas.push('COMANDOS.md');
+      if (!enManual) faltas.push('MANUAL_USO.md');
+      ausentes.push(`${refSlash} (falta en ${faltas.join(' + ')})`);
+      continue;
+    }
+
+    // Gate de profundidad: comandos no triviales requieren >= PROFUNDIDAD_MINIMA
+    // menciones en MANUAL_USO.md.
+    if (!COMANDOS_TRIVIALES.has(nombre)) {
+      const menciones = (manualUsoMd.match(new RegExp(escapeRegex(refSlash), 'g')) || []).length;
+      if (menciones < PROFUNDIDAD_MINIMA) {
+        profundidadFails++;
+        infraDocumentados.push(`${refSlash} — solo ${menciones} mención${menciones === 1 ? '' : 'es'} en MANUAL_USO (mínimo ${PROFUNDIDAD_MINIMA})`);
+        continue;
+      }
+    }
+    documentados++;
+  }
+
+  const totalFails = presenciaFails + profundidadFails;
+  if (totalFails === 0) {
+    reportar(2, `${archivos.length} comandos /swl:* documentados con profundidad >= ${PROFUNDIDAD_MINIMA} (o triviales)`, true);
+  } else {
+    if (presenciaFails > 0) {
+      reportar(2, `${presenciaFails} comandos sin mención en docs`, false,
+        ausentes.join('\n'));
+    }
+    if (profundidadFails > 0) {
+      reportar(2, `${profundidadFails} comandos infra-documentados (< ${PROFUNDIDAD_MINIMA} menciones en MANUAL_USO)`, false,
+        infraDocumentados.join('\n') +
+        '\n(Documentar con sección dedicada: Uso / ¿Qué hace? / Cuándo usarlo / Ejemplo / Troubleshooting)');
+    }
+  }
+}
+
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+// ── Check 3: flags booleanas vs docs ────────────────────────────────────────
+
+function check3Flags() {
+  if (opts.only && opts.only !== 3) return;
+  console.log(c(COLOR_DIM, '\n[3] Flags booleanas del parser vs bin --help y COMANDOS.md'));
+
+  const parser = leerArchivo('scripts/lib/parsear-opciones.js') || '';
+  const binHelp = leerArchivo('bin/swl-ses.js') || '';
+  const comandosMd = leerArchivo('COMANDOS.md') || '';
+
+  // Extraer las booleanas del parser (busca el array BOOLEANAS)
+  const matchBool = parser.match(/const BOOLEANAS\s*=\s*\[([\s\S]*?)\];/);
+  if (!matchBool) {
+    reportar(3, 'parsear-opciones.js no exporta BOOLEANAS', false,
+      'No se encontró el array BOOLEANAS en el parser');
+    return;
+  }
+
+  const booleanas = (matchBool[1].match(/['"]([^'"]+)['"]/g) || [])
+    .map(s => s.replace(/['"]/g, ''))
+    .filter(b => !['simular', 'forzar'].includes(b)); // alias en español ya cubiertos
+
+  // Flags críticas que SÍ deben estar documentadas (subset)
+  const criticas = ['tui', 'no-tui', 'with-mcp', 'all-langs', 'force', 'dry-run', 'global'];
+
+  let fallas = 0;
+  for (const flag of criticas) {
+    if (!booleanas.includes(flag)) {
+      // Si la flag no está en el parser tampoco; eso es señalable pero no fail aquí
+      continue;
+    }
+    const enBinHelp = binHelp.includes(`--${flag}`);
+    const enComandosMd = comandosMd.includes(`--${flag}`);
+    if (!enBinHelp || !enComandosMd) {
+      fallas++;
+      const faltas = [];
+      if (!enBinHelp) faltas.push('bin/swl-ses.js (--help)');
+      if (!enComandosMd) faltas.push('COMANDOS.md');
+      reportar(3, `Flag --${flag} sin documentar en ${faltas.join(' + ')}`, false,
+        `Parser la declara como booleana pero falta en docs`);
+    }
+  }
+  if (fallas === 0) {
+    reportar(3, `${criticas.length} flags críticas documentadas en bin --help y COMANDOS.md`, true);
+  }
+}
+
+// ── Check 4: versiones ──────────────────────────────────────────────────────
+
+function check4Versiones() {
+  if (opts.only && opts.only !== 4) return;
+  console.log(c(COLOR_DIM, '\n[4] Versión de package.json vs encabezados de docs'));
+
+  let version;
+  try {
+    version = require(path.join(RAIZ, 'package.json')).version;
+  } catch (_) {
+    reportar(4, 'package.json no parsea', false);
+    return;
+  }
+
+  const docs = ['CLAUDE.md', 'README.md', 'AGENTS.md', 'COMANDOS.md', 'MANUAL_USO.md', 'INSTALACION.md'];
+  let fallas = 0;
+  for (const doc of docs) {
+    const contenido = leerArchivo(doc);
+    if (!contenido) {
+      fallas++;
+      reportar(4, `${doc} no se puede leer`, false);
+      continue;
+    }
+    const primeraLinea = contenido.split('\n')[0] || '';
+    if (!primeraLinea.includes(version)) {
+      fallas++;
+      reportar(4, `${doc} encabezado sin v${version}`, false,
+        `Primera línea: "${primeraLinea.slice(0, 100)}"`);
+    }
+  }
+  if (fallas === 0) {
+    reportar(4, `Encabezados de ${docs.length} docs consistentes con v${version}`, true);
+  }
+}
+
+// ── Check 5: pantallas TUI ───────────────────────────────────────────────────
+
+function check5Tui() {
+  if (opts.only && opts.only !== 5) return;
+  console.log(c(COLOR_DIM, '\n[5] Pantallas TUI vs menciones en MANUAL_USO.md'));
+
+  const dirAbs = path.join(RAIZ, 'scripts/tui/pantallas');
+  if (!fs.existsSync(dirAbs)) {
+    // Si no hay TUI (pre-v1.6.0), saltar el check sin fallar
+    reportar(5, 'scripts/tui/pantallas/ no existe (TUI no instalado)', true);
+    return;
+  }
+
+  const pantallas = fs.readdirSync(dirAbs)
+    .filter(n => n.endsWith('.js'))
+    .map(n => n.replace(/\.js$/, ''));
+
+  const manualUsoMd = (leerArchivo('MANUAL_USO.md') || '').toLowerCase();
+
+  // Mapeo de nombre de archivo a término que debe aparecer en docs
+  const terminos = {
+    'welcome': ['welcome', 'bienvenida'],
+    'menu-principal': ['menú principal', 'menu principal'],
+    'install-wizard': ['wizard install', 'install wizard', 'wizard de instalación', 'instalador tui'],
+    'update-wizard': ['wizard update', 'update wizard', 'wizard de actualización'],
+    'uninstall-wizard': ['uninstall', 'desinstal'],
+    'inspect': ['inspect'],
+    'progreso': ['progreso', 'barra de progreso'],
+    'resumen': ['resumen', 'pantalla resumen'],
+  };
+
+  let fallas = 0;
+  for (const pantalla of pantallas) {
+    const expectedTerms = terminos[pantalla];
+    if (!expectedTerms) continue; // archivo no es una pantalla documentable
+    const algunoPresente = expectedTerms.some(t => manualUsoMd.includes(t.toLowerCase()));
+    if (!algunoPresente) {
+      fallas++;
+      reportar(5, `Pantalla "${pantalla}" sin mención en MANUAL_USO.md`, false,
+        `Esperaba al menos uno de: ${expectedTerms.join(', ')}`);
+    }
+  }
+  if (fallas === 0) {
+    const documentables = Object.keys(terminos).length;
+    reportar(5, `${documentables} pantallas TUI mencionadas en MANUAL_USO.md`, true);
+  }
+}
+
+// ── Check 6: catálogo SWL_* completo ─────────────────────────────────────────
+
+function check6Variables() {
+  if (opts.only && opts.only !== 6) return;
+  console.log(c(COLOR_DIM, '\n[6] Variables SWL_* en código vs docs/variables-entorno.md'));
+
+  // Extraer variables del código
+  // v1.6.1: scope extendido a agentes/, comandos/, bin/ además de hooks/ y scripts/
+  // Origen: cierra Cabo A3 detectado en sondeo cross-dimensional post-v1.6.1.
+  const codeVars = new Set();
+  const escanear = (dir) => {
+    const dirAbs = path.join(RAIZ, dir);
+    if (!fs.existsSync(dirAbs)) return;
+    const recurse = (d) => {
+      for (const entry of fs.readdirSync(d, { withFileTypes: true })) {
+        const p = path.join(d, entry.name);
+        if (entry.isDirectory()) {
+          if (entry.name === 'node_modules' || entry.name.startsWith('.')) continue;
+          recurse(p);
+        } else if (entry.isFile()) {
+          const ext = path.extname(entry.name);
+          // .md incluido para agentes/ y comandos/ que pueden documentar variables
+          // como parte de su contrato operativo (ej: SWL_AUDIT_AGENTES en
+          // agentes/auto-evolucion-swl.md).
+          if (['.js', '.cjs', '.mjs', '.py', '.sh', '.md'].includes(ext)) {
+            try {
+              const contenido = fs.readFileSync(p, 'utf-8');
+              const matches = contenido.match(/\bSWL_[A-Z][A-Z0-9_]*\b/g);
+              if (matches) for (const m of matches) codeVars.add(m);
+            } catch (_) {}
+          }
+        }
+      }
+    };
+    recurse(dirAbs);
+  };
+  escanear('hooks');
+  escanear('scripts');
+  escanear('agentes');
+  escanear('comandos');
+  escanear('bin');
+
+  // Extraer variables del catálogo formal
+  const catalogo = leerArchivo('docs/variables-entorno.md') || '';
+  const manualUso = leerArchivo('MANUAL_USO.md') || '';
+  const docVars = new Set();
+  for (const m of catalogo.match(/\bSWL_[A-Z][A-Z0-9_]*\b/g) || []) docVars.add(m);
+  for (const m of manualUso.match(/\bSWL_[A-Z][A-Z0-9_]*\b/g) || []) docVars.add(m);
+
+  // Detectar huérfanas
+  const huerfanas = [...codeVars].filter(v => !docVars.has(v)).sort();
+
+  if (huerfanas.length === 0) {
+    reportar(6, `${codeVars.size} variables SWL_* del código documentadas en docs/variables-entorno.md o MANUAL_USO.md`, true);
+  } else {
+    reportar(6, `${huerfanas.length} variables SWL_* huérfanas (en código pero no documentadas)`, false,
+      huerfanas.map(v => `- ${v}`).join('\n') +
+      '\nAgregar entrada en docs/variables-entorno.md con: nombre, default, archivo que la consume.');
+  }
+}
+
+// ── Check 7: reglas en disco vs manifiestos/modulos.json ────────────────────
+
+function check7Reglas() {
+  if (opts.only && opts.only !== 7) return;
+  console.log(c(COLOR_DIM, '\n[7] Reglas en disco vs manifiestos/modulos.json'));
+
+  const dirAbs = path.join(RAIZ, 'reglas');
+  if (!fs.existsSync(dirAbs)) {
+    reportar(7, 'reglas/ no existe', true);
+    return;
+  }
+
+  // Escanear reglas en disco (excluyendo subdirectorios de lenguajes y fragmentos _*)
+  const enDisco = new Set();
+  for (const entry of fs.readdirSync(dirAbs, { withFileTypes: true })) {
+    if (entry.isFile() && entry.name.endsWith('.md') && !entry.name.startsWith('_')) {
+      enDisco.add(`reglas/${entry.name}`);
+    }
+  }
+
+  // Leer manifiestos/modulos.json
+  let manifiesto;
+  try {
+    manifiesto = require(path.join(RAIZ, 'manifiestos/modulos.json'));
+  } catch (err) {
+    reportar(7, `No se pudo leer manifiestos/modulos.json: ${err.message}`, false);
+    return;
+  }
+
+  // Extraer todas las reglas referenciadas en cualquier módulo
+  const enManifiesto = new Set();
+  const recurseFiles = (obj) => {
+    if (!obj) return;
+    if (Array.isArray(obj)) {
+      for (const item of obj) {
+        if (typeof item === 'string' && item.startsWith('reglas/')) {
+          enManifiesto.add(item);
+        } else if (typeof item === 'object') {
+          recurseFiles(item);
+        }
+      }
+    } else if (typeof obj === 'object') {
+      for (const v of Object.values(obj)) recurseFiles(v);
+    }
+  };
+  recurseFiles(manifiesto);
+
+  // Detectar reglas en disco sin entrada en manifiesto
+  const huerfanas = [...enDisco].filter(r => !enManifiesto.has(r)).sort();
+
+  if (huerfanas.length === 0) {
+    reportar(7, `${enDisco.size} reglas base en disco registradas en manifiestos/modulos.json`, true);
+  } else {
+    reportar(7, `${huerfanas.length} reglas en disco sin registrar en manifiestos/modulos.json`, false,
+      huerfanas.map(r => `- ${r}`).join('\n') +
+      '\nAgregar al módulo apropiado de manifiestos/modulos.json.');
+  }
+}
+
+// ── Check 8: ADRs aceptados vs referencia en CHANGELOG.md ───────────────────
+
+function check8ADRsChangelog() {
+  if (opts.only && opts.only !== 8) return;
+  console.log(c(COLOR_DIM, '\n[8] ADRs aceptados vs referencia en CHANGELOG.md'));
+
+  const dirAbs = path.join(RAIZ, '.planning/adrs');
+  if (!fs.existsSync(dirAbs)) {
+    reportar(8, '.planning/adrs/ no existe', true);
+    return;
+  }
+
+  // Escanear ADRs por número (NNNN-titulo.md), excluyendo README
+  const adrsAceptados = [];
+  for (const entry of fs.readdirSync(dirAbs, { withFileTypes: true })) {
+    if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
+    if (entry.name === 'README.md') continue;
+    const match = entry.name.match(/^(\d{4})-/);
+    if (!match) continue;
+
+    // Leer frontmatter/estado para confirmar "Aceptado"
+    try {
+      const contenido = fs.readFileSync(path.join(dirAbs, entry.name), 'utf-8');
+      const estadoMatch = contenido.match(/\*\*Estado\*\*:\s*(\w+)/i) ||
+                          contenido.match(/^estado:\s*(\w+)/im);
+      const estado = estadoMatch ? estadoMatch[1].toLowerCase() : 'desconocido';
+      if (estado === 'aceptado') {
+        adrsAceptados.push({ numero: match[1], archivo: entry.name });
+      }
+    } catch (_) { /* ignorar lectura fallida */ }
+  }
+
+  // Leer CHANGELOG y buscar referencias ADR-NNNN
+  const changelog = leerArchivo('CHANGELOG.md') || '';
+  const referencias = new Set();
+  for (const m of changelog.match(/ADR-(\d{4})/g) || []) {
+    referencias.add(m.replace('ADR-', ''));
+  }
+
+  // ADRs aceptados sin referencia en CHANGELOG
+  const sinReferencia = adrsAceptados.filter(adr => !referencias.has(adr.numero));
+
+  if (sinReferencia.length === 0) {
+    reportar(8, `${adrsAceptados.length} ADRs aceptados referenciados en CHANGELOG.md`, true);
+  } else {
+    // WARN no falla — el criterio "cambia comportamiento observable" es subjetivo
+    const mark = tty ? `${COLOR_WARN}[WARN]${COLOR_RESET}` : '[WARN]';
+    console.log(`  ${mark} check #8 — ${sinReferencia.length} ADRs aceptados sin referencia en CHANGELOG`);
+    if (!opts.quiet) {
+      for (const adr of sinReferencia) {
+        console.log(`        ${c(COLOR_DIM, '- ADR-' + adr.numero + ' (' + adr.archivo + ')')}`);
+      }
+      console.log(`        ${c(COLOR_DIM, '(WARN: no todos los ADRs cambian comportamiento observable. Documentar en CHANGELOG solo los que sí)')}`);
+    }
+    resultados.push({ check: 8, etiqueta: `${adrsAceptados.length - sinReferencia.length}/${adrsAceptados.length} ADRs referenciados`, ok: true, detalle: null });
+  }
+}
+
+// ── main ──────────────────────────────────────────────────────────────────────
+
+function main() {
+  console.log(c(COLOR_DIM, 'Verificador docs-vs-código — swl-ses\n' + '═'.repeat(60)));
+
+  check1Contadores();
+  check2Comandos();
+  check3Flags();
+  check4Versiones();
+  check5Tui();
+  check6Variables();
+  check7Reglas();
+  check8ADRsChangelog();
+
+  const fails = resultados.filter(r => !r.ok).length;
+  const total = resultados.length;
+
+  console.log('\n' + '─'.repeat(60));
+  if (fails === 0) {
+    console.log(c(COLOR_OK, `✓ ${total} checks OK — docs alineadas con código`));
+    process.exit(0);
+  } else {
+    console.log(c(COLOR_FAIL, `✗ ${fails}/${total} checks con drift`));
+    console.log(c(COLOR_DIM, 'Revisa los hallazgos arriba. Las menciones marcadas FAIL deben'));
+    console.log(c(COLOR_DIM, 'actualizarse antes del próximo merge.'));
+    process.exit(1);
+  }
+}
+
+if (require.main === module) {
+  try {
+    main();
+  } catch (err) {
+    console.error(c(COLOR_FAIL, `Error de ejecución: ${err.message}`));
+    if (process.env.SWL_DEBUG) console.error(err.stack);
+    process.exit(2);
+  }
+}
+
+module.exports = {
+  check1Contadores,
+  check2Comandos,
+  check3Flags,
+  check4Versiones,
+  check5Tui,
+  check6Variables,
+  check7Reglas,
+  check8ADRsChangelog,
+};

package/scripts/verificar-evolucion.js

@@ -159,18 +159,34 @@ function verificarArchivo(filePath) {
 
   const versionActual = leerCampo(fm, 'version');
   const ev = leerMetadatosEvolucion(filePath, fm);
+  // v1.6.1 (Cabo A4): aceptar `deprecated: true` o `evolvable: false` como
+  // justificación legítima para ausencia de `version`. Origen: 12 skills
+  // detectados sin version, 1 deprecated (control-profundidad) legítimo.
+  const esDeprecated = /^deprecated:\s*true\s*$/m.test(fm);
+  const esEvolvableFalse = /^evolvable:\s*false/m.test(fm);
+  const excepcionLegitima = esDeprecated; // evolvable:false aún espera version
+                                          // si tiene historia; solo deprecated
+                                          // exime completamente
 
   resultado.info.version = versionActual;
   resultado.info.evolved = ev.evolved;
   resultado.info.fuenteEvolved = ev.fuente;
+  resultado.info.excepcion = excepcionLegitima
+    ? (esDeprecated ? 'deprecated' : 'evolvable-false')
+    : null;
 
-  // CHECK 1: version presente
-  if (!versionActual) {
+  // CHECK 1: version presente (exime deprecated)
+  if (!versionActual && !excepcionLegitima) {
     resultado.problemas.push('campo `version` ausente del frontmatter');
+  } else if (!versionActual && esDeprecated) {
+    resultado.info.notas = resultado.info.notas || [];
+    resultado.info.notas.push('version ausente — aceptado porque deprecated:true');
   }
 
   // CHECK 2: evolved = true (en frontmatter o en .evolved.json)
-  if (ev.evolved !== 'true') {
+  // v1.6.1 (Cabo A4): exento si deprecated:true — no tiene sentido exigir
+  // metadatos de evolución para componentes que se van a eliminar.
+  if (ev.evolved !== 'true' && !esDeprecated) {
     resultado.problemas.push(
       '`evolved` no encontrado (ni en frontmatter ni en .evolved.json del directorio)'
     );