@saulwade/swl-ses 2.4.2 → 2.5.1

package/scripts/actualizar.js

@@ -1,253 +1,253 @@
-'use strict';
-
-/**
- * swl-ses update
- * Actualiza componentes instalados preservando _userland/.
- * Interactivo: muestra versiones, pide confirmación, muestra progreso.
- * No-interactivo con --force o sin TTY.
- *
- * Modo --check (read-only):
- *   Solo muestra el estado actual de versiones (local vs npm vs runtimes instalados).
- *   No pide confirmación. No actualiza nada. Util para el autor o usuarios que
- *   quieren verificar si están al dia sin esperar al hook automatico.
- */
-
-const fs = require('fs');
-const os = require('os');
-const path = require('path');
-const { detectarRuntimes, scopesReales } = require('./lib/detectar-runtime');
-const { cargarEstado } = require('./lib/estado');
-const {
-  color, icono, encabezado, formatearPaso, formatearAdvertencia,
-  spinner, preguntarSiNo, lineaSeparadora, ES_TTY,
-} = require('./lib/ui');
-const { versionRemotaParalela, compararSemver } = require('./lib/npm-version');
-
-const VERSION_LOCAL = require('../package.json').version;
-
-/**
- * Consulta la versión más reciente publicada en npm. Si la consulta falla
- * (sin red, timeout), retorna la versión local como fallback razonable.
- */
-async function obtenerVersionRemota() {
-  const r = await versionRemotaParalela({ timeoutMs: 10000 });
-  return r.version || VERSION_LOCAL;
-}
-
-/**
- * Modo --check: muestra el estado actual sin actualizar. Read-only.
- *
- * Salida:
- *   - Version del paquete que esta ejecutando este CLI (VERSION_LOCAL).
- *   - Version mas reciente publicada en npm.
- *   - Comparacion semver: al dia / adelantado / atras.
- *   - Estado del hook check-update.js: ultima verificacion automatica.
- *   - Tabla por runtime instalado (si los detecta) con su versionSistema.
- */
-async function checkStatus() {
-  console.log(encabezado('swl-ses update --check', VERSION_LOCAL));
-
-  // Resolver version remota con timeout corto
-  const remota = await obtenerVersionRemota();
-  const cmp = compararSemver(VERSION_LOCAL, remota);
-
-  let estadoVersion;
-  if (cmp === null) {
-    estadoVersion = color.amarillo('Comparacion no disponible (formato inesperado)');
-  } else if (cmp === 0) {
-    estadoVersion = color.verde('Al dia');
-  } else if (cmp < 0) {
-    estadoVersion = color.amarillo(`Nueva version disponible (${remota})`);
-  } else {
-    estadoVersion = color.dim(`Local mas reciente que npm (${VERSION_LOCAL} > ${remota}, publicacion pendiente)`);
-  }
-
-  console.log(`  Paquete ejecutado:  ${color.negrita('v' + VERSION_LOCAL)}`);
-  console.log(`  Version en npm:     ${color.negrita('v' + remota)}`);
-  console.log(`  Estado:             ${estadoVersion}`);
-  console.log('');
-
-  // Estado del hook automatico (check-update.js).
-  // SWL_UPDATE_FLAG_PATH override solo para tests (evita race con flag único).
-  const flagPath = process.env.SWL_UPDATE_FLAG_PATH || path.join(os.tmpdir(), 'swl-ses-update-check.json');
-  try {
-    const flag = JSON.parse(fs.readFileSync(flagPath, 'utf8'));
-    const horas = ((Date.now() - flag.timestamp) / 3600000).toFixed(1);
-    console.log(`  ${color.negrita('Hook automatico (check-update.js):')}`);
-    console.log(`    Ultima verificacion: hace ${horas}h`);
-    console.log(`    Local registrada:    ${flag.local}`);
-    console.log(`    Remota registrada:   ${flag.remota || color.dim('(no resuelta)')}`);
-    console.log(`    hayNueva:            ${flag.hayNueva ? color.amarillo('si') : color.verde('no')}`);
-    console.log(`    Flag:                ${flagPath}`);
-  } catch {
-    console.log(`  ${color.negrita('Hook automatico (check-update.js):')}`);
-    console.log(`    ${color.dim('Sin flag de throttle — el hook nunca se ha ejecutado en este equipo,')}`);
-    console.log(`    ${color.dim('o el archivo temp/swl-ses-update-check.json fue removido.')}`);
-  }
-  console.log('');
-
-  // Estado por runtime instalado
-  const runtimes = detectarRuntimes();
-  if (runtimes.length === 0) {
-    console.log(formatearAdvertencia('Runtimes', 'No se detectaron runtimes con instalacion SWL'));
-    console.log('');
-    return;
-  }
-
-  console.log(`  ${color.negrita('Runtimes detectados:')}`);
-  let totalRuntimes = 0;
-  for (const runtime of runtimes) {
-    // Dedup + guard anti-fantasma (ver scopesReales): desde HOME el local
-    // colapsa con el global propio o con el de otro runtime.
-    for (const { dir, esGlobal } of scopesReales(runtime)) {
-      if (!fs.existsSync(dir)) continue;
-      const estado = cargarEstado(dir);
-      if (!estado) continue;
-
-      const ubicacion = esGlobal ? 'global' : 'proyecto';
-      const v = estado.versionSistema || 'desconocida';
-
-      const cmpRuntime = compararSemver(v, remota);
-      let etiqueta;
-      if (cmpRuntime === null) {
-        etiqueta = color.dim('(version no reconocida)');
-      } else if (cmpRuntime === 0) {
-        etiqueta = color.verde('al dia');
-      } else if (cmpRuntime < 0) {
-        etiqueta = color.amarillo(`atrasada (npm: ${remota})`);
-      } else {
-        etiqueta = color.dim('adelantada');
-      }
-
-      console.log(`    ${runtime.nombre} (${ubicacion}): v${v}  ${etiqueta}`);
-      totalRuntimes++;
-    }
-  }
-  if (totalRuntimes === 0) {
-    console.log(`    ${color.dim('(ninguno con .swl-install-state.json valido)')}`);
-  }
-  console.log('');
-  console.log(`  ${color.dim('Modo --check es read-only. Para actualizar:')} npx -y @saulwade/swl-ses@latest update`);
-  console.log('');
-}
-
-async function update(opciones) {
-  // Modo read-only: solo reportar estado, no tocar nada
-  if (opciones.check) {
-    await checkStatus();
-    return;
-  }
-
-  const force = opciones.force || !ES_TTY;
-
-  // Obtener la versión más reciente del registro npm
-  const VERSION = await obtenerVersionRemota();
-
-  console.log(encabezado('swl-ses update', VERSION_LOCAL));
-
-  // 1. Detectar runtimes
-  const runtimes = detectarRuntimes();
-
-  if (runtimes.length === 0) {
-    console.log(formatearAdvertencia('Runtimes', 'No se detectaron runtimes con instalación SWL'));
-    console.log(`\n  Ejecuta primero: npx @saulwade/swl-ses@latest install --target claude`);
-    process.exit(1);
-  }
-
-  let actualizados = 0;
-  let omitidos = 0;
-
-  // 2. Iterar runtimes
-  for (const runtime of runtimes) {
-    // Dedup + guard anti-fantasma (ver scopesReales).
-    for (const { dir, esGlobal } of scopesReales(runtime)) {
-      if (!fs.existsSync(dir)) continue;
-
-      const estado = cargarEstado(dir);
-      if (!estado) continue;
-
-      const versionInstalada = estado.versionSistema || 'desconocida';
-      const ubicacion = esGlobal ? 'global' : 'proyecto';
-
-      const necesitaActualizar = versionInstalada !== VERSION;
-      const paqueteDesactualizado = VERSION_LOCAL !== VERSION;
-
-      console.log(`  ${color.negrita(`Runtime: ${runtime.nombre}`)} ${color.dim(`(${ubicacion})`)}`);
-      console.log(`  Versión instalada:  ${necesitaActualizar ? color.amarillo(versionInstalada) : color.verde(versionInstalada)}`);
-      console.log(`  Versión disponible: ${color.verde(VERSION)}${paqueteDesactualizado ? color.dim(` (ejecutando con v${VERSION_LOCAL})`) : ''}`);
-      console.log(`  Perfil:             ${estado.perfil}`);
-      console.log(`  Componentes:        ${estado.componentesInstalados.length}`);
-      console.log(`  Archivos:           ${estado.archivosInstalados.length}`);
-      console.log('');
-
-      // Si la versión disponible es más reciente pero el paquete ejecutándose es viejo,
-      // indicar al usuario que use @latest
-      if (paqueteDesactualizado && necesitaActualizar) {
-        console.log(formatearAdvertencia(runtime.nombre,
-          `Este paquete es v${VERSION_LOCAL} pero la v${VERSION} está disponible.\n` +
-          `  Para actualizar, ejecuta: npx @saulwade/swl-ses@latest update --force`));
-        console.log('');
-        omitidos++;
-        continue;
-      }
-
-      // Verificar si ya está actualizado
-      if (!necesitaActualizar && !force) {
-        console.log(formatearPaso(runtime.nombre, 'Ya está en la versión más reciente'));
-        console.log('');
-        omitidos++;
-        continue;
-      }
-
-      // Confirmar
-      if (!force) {
-        const confirmar = await preguntarSiNo(
-          !necesitaActualizar
-            ? `¿Re-instalar ${runtime.nombre} v${VERSION}?`
-            : `¿Actualizar ${runtime.nombre} de ${versionInstalada} a ${VERSION}?`
-        );
-        console.log('');
-
-        if (!confirmar) {
-          console.log(formatearAdvertencia(runtime.nombre, 'Actualización cancelada por el usuario'));
-          console.log('');
-          omitidos++;
-          continue;
-        }
-      }
-
-      // Ejecutar actualización con spinner
-      const sp = spinner(`Actualizando ${runtime.nombre}...`);
-
-      try {
-        const instalador = require('./instalador');
-        await instalador({
-          target: runtime.id,
-          profile: estado.perfil,
-          global: estado.global,
-          force: true,
-        });
-
-        sp.exito(`${runtime.nombre} actualizado a v${VERSION} (${estado.archivosInstalados.length} archivos)`);
-        actualizados++;
-      } catch (err) {
-        sp.fallo(`Error actualizando ${runtime.nombre}: ${err.message}`);
-      }
-
-      console.log('');
-    }
-  }
-
-  // 3. Reporte final
-  console.log(`  ${lineaSeparadora()}`);
-  if (actualizados > 0) {
-    console.log(formatearPaso('Resultado', `${actualizados} runtime(s) actualizado(s)${omitidos > 0 ? `, ${omitidos} omitido(s)` : ''}`));
-  } else if (omitidos > 0) {
-    console.log(formatearPaso('Resultado', 'Todo está actualizado'));
-  } else {
-    console.log(formatearAdvertencia('Resultado', 'Ningún runtime fue actualizado'));
-  }
-  console.log('');
-}
-
-module.exports = update;
+'use strict';
+
+/**
+ * swl-ses update
+ * Actualiza componentes instalados preservando _userland/.
+ * Interactivo: muestra versiones, pide confirmación, muestra progreso.
+ * No-interactivo con --force o sin TTY.
+ *
+ * Modo --check (read-only):
+ *   Solo muestra el estado actual de versiones (local vs npm vs runtimes instalados).
+ *   No pide confirmación. No actualiza nada. Util para el autor o usuarios que
+ *   quieren verificar si están al dia sin esperar al hook automatico.
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { detectarRuntimes, scopesReales } = require('./lib/detectar-runtime');
+const { cargarEstado } = require('./lib/estado');
+const {
+  color, icono, encabezado, formatearPaso, formatearAdvertencia,
+  spinner, preguntarSiNo, lineaSeparadora, ES_TTY,
+} = require('./lib/ui');
+const { versionRemotaParalela, compararSemver } = require('./lib/npm-version');
+
+const VERSION_LOCAL = require('../package.json').version;
+
+/**
+ * Consulta la versión más reciente publicada en npm. Si la consulta falla
+ * (sin red, timeout), retorna la versión local como fallback razonable.
+ */
+async function obtenerVersionRemota() {
+  const r = await versionRemotaParalela({ timeoutMs: 10000 });
+  return r.version || VERSION_LOCAL;
+}
+
+/**
+ * Modo --check: muestra el estado actual sin actualizar. Read-only.
+ *
+ * Salida:
+ *   - Version del paquete que esta ejecutando este CLI (VERSION_LOCAL).
+ *   - Version mas reciente publicada en npm.
+ *   - Comparacion semver: al dia / adelantado / atras.
+ *   - Estado del hook check-update.js: ultima verificacion automatica.
+ *   - Tabla por runtime instalado (si los detecta) con su versionSistema.
+ */
+async function checkStatus() {
+  console.log(encabezado('swl-ses update --check', VERSION_LOCAL));
+
+  // Resolver version remota con timeout corto
+  const remota = await obtenerVersionRemota();
+  const cmp = compararSemver(VERSION_LOCAL, remota);
+
+  let estadoVersion;
+  if (cmp === null) {
+    estadoVersion = color.amarillo('Comparacion no disponible (formato inesperado)');
+  } else if (cmp === 0) {
+    estadoVersion = color.verde('Al dia');
+  } else if (cmp < 0) {
+    estadoVersion = color.amarillo(`Nueva version disponible (${remota})`);
+  } else {
+    estadoVersion = color.dim(`Local mas reciente que npm (${VERSION_LOCAL} > ${remota}, publicacion pendiente)`);
+  }
+
+  console.log(`  Paquete ejecutado:  ${color.negrita('v' + VERSION_LOCAL)}`);
+  console.log(`  Version en npm:     ${color.negrita('v' + remota)}`);
+  console.log(`  Estado:             ${estadoVersion}`);
+  console.log('');
+
+  // Estado del hook automatico (check-update.js).
+  // SWL_UPDATE_FLAG_PATH override solo para tests (evita race con flag único).
+  const flagPath = process.env.SWL_UPDATE_FLAG_PATH || path.join(os.tmpdir(), 'swl-ses-update-check.json');
+  try {
+    const flag = JSON.parse(fs.readFileSync(flagPath, 'utf8'));
+    const horas = ((Date.now() - flag.timestamp) / 3600000).toFixed(1);
+    console.log(`  ${color.negrita('Hook automatico (check-update.js):')}`);
+    console.log(`    Ultima verificacion: hace ${horas}h`);
+    console.log(`    Local registrada:    ${flag.local}`);
+    console.log(`    Remota registrada:   ${flag.remota || color.dim('(no resuelta)')}`);
+    console.log(`    hayNueva:            ${flag.hayNueva ? color.amarillo('si') : color.verde('no')}`);
+    console.log(`    Flag:                ${flagPath}`);
+  } catch {
+    console.log(`  ${color.negrita('Hook automatico (check-update.js):')}`);
+    console.log(`    ${color.dim('Sin flag de throttle — el hook nunca se ha ejecutado en este equipo,')}`);
+    console.log(`    ${color.dim('o el archivo temp/swl-ses-update-check.json fue removido.')}`);
+  }
+  console.log('');
+
+  // Estado por runtime instalado
+  const runtimes = detectarRuntimes();
+  if (runtimes.length === 0) {
+    console.log(formatearAdvertencia('Runtimes', 'No se detectaron runtimes con instalacion SWL'));
+    console.log('');
+    return;
+  }
+
+  console.log(`  ${color.negrita('Runtimes detectados:')}`);
+  let totalRuntimes = 0;
+  for (const runtime of runtimes) {
+    // Dedup + guard anti-fantasma (ver scopesReales): desde HOME el local
+    // colapsa con el global propio o con el de otro runtime.
+    for (const { dir, esGlobal } of scopesReales(runtime)) {
+      if (!fs.existsSync(dir)) continue;
+      const estado = cargarEstado(dir);
+      if (!estado) continue;
+
+      const ubicacion = esGlobal ? 'global' : 'proyecto';
+      const v = estado.versionSistema || 'desconocida';
+
+      const cmpRuntime = compararSemver(v, remota);
+      let etiqueta;
+      if (cmpRuntime === null) {
+        etiqueta = color.dim('(version no reconocida)');
+      } else if (cmpRuntime === 0) {
+        etiqueta = color.verde('al dia');
+      } else if (cmpRuntime < 0) {
+        etiqueta = color.amarillo(`atrasada (npm: ${remota})`);
+      } else {
+        etiqueta = color.dim('adelantada');
+      }
+
+      console.log(`    ${runtime.nombre} (${ubicacion}): v${v}  ${etiqueta}`);
+      totalRuntimes++;
+    }
+  }
+  if (totalRuntimes === 0) {
+    console.log(`    ${color.dim('(ninguno con .swl-install-state.json valido)')}`);
+  }
+  console.log('');
+  console.log(`  ${color.dim('Modo --check es read-only. Para actualizar:')} npx -y @saulwade/swl-ses@latest update`);
+  console.log('');
+}
+
+async function update(opciones) {
+  // Modo read-only: solo reportar estado, no tocar nada
+  if (opciones.check) {
+    await checkStatus();
+    return;
+  }
+
+  const force = opciones.force || !ES_TTY;
+
+  // Obtener la versión más reciente del registro npm
+  const VERSION = await obtenerVersionRemota();
+
+  console.log(encabezado('swl-ses update', VERSION_LOCAL));
+
+  // 1. Detectar runtimes
+  const runtimes = detectarRuntimes();
+
+  if (runtimes.length === 0) {
+    console.log(formatearAdvertencia('Runtimes', 'No se detectaron runtimes con instalación SWL'));
+    console.log(`\n  Ejecuta primero: npx @saulwade/swl-ses@latest install --target claude`);
+    process.exit(1);
+  }
+
+  let actualizados = 0;
+  let omitidos = 0;
+
+  // 2. Iterar runtimes
+  for (const runtime of runtimes) {
+    // Dedup + guard anti-fantasma (ver scopesReales).
+    for (const { dir, esGlobal } of scopesReales(runtime)) {
+      if (!fs.existsSync(dir)) continue;
+
+      const estado = cargarEstado(dir);
+      if (!estado) continue;
+
+      const versionInstalada = estado.versionSistema || 'desconocida';
+      const ubicacion = esGlobal ? 'global' : 'proyecto';
+
+      const necesitaActualizar = versionInstalada !== VERSION;
+      const paqueteDesactualizado = VERSION_LOCAL !== VERSION;
+
+      console.log(`  ${color.negrita(`Runtime: ${runtime.nombre}`)} ${color.dim(`(${ubicacion})`)}`);
+      console.log(`  Versión instalada:  ${necesitaActualizar ? color.amarillo(versionInstalada) : color.verde(versionInstalada)}`);
+      console.log(`  Versión disponible: ${color.verde(VERSION)}${paqueteDesactualizado ? color.dim(` (ejecutando con v${VERSION_LOCAL})`) : ''}`);
+      console.log(`  Perfil:             ${estado.perfil}`);
+      console.log(`  Componentes:        ${estado.componentesInstalados.length}`);
+      console.log(`  Archivos:           ${estado.archivosInstalados.length}`);
+      console.log('');
+
+      // Si la versión disponible es más reciente pero el paquete ejecutándose es viejo,
+      // indicar al usuario que use @latest
+      if (paqueteDesactualizado && necesitaActualizar) {
+        console.log(formatearAdvertencia(runtime.nombre,
+          `Este paquete es v${VERSION_LOCAL} pero la v${VERSION} está disponible.\n` +
+          `  Para actualizar, ejecuta: npx @saulwade/swl-ses@latest update --force`));
+        console.log('');
+        omitidos++;
+        continue;
+      }
+
+      // Verificar si ya está actualizado
+      if (!necesitaActualizar && !force) {
+        console.log(formatearPaso(runtime.nombre, 'Ya está en la versión más reciente'));
+        console.log('');
+        omitidos++;
+        continue;
+      }
+
+      // Confirmar
+      if (!force) {
+        const confirmar = await preguntarSiNo(
+          !necesitaActualizar
+            ? `¿Re-instalar ${runtime.nombre} v${VERSION}?`
+            : `¿Actualizar ${runtime.nombre} de ${versionInstalada} a ${VERSION}?`
+        );
+        console.log('');
+
+        if (!confirmar) {
+          console.log(formatearAdvertencia(runtime.nombre, 'Actualización cancelada por el usuario'));
+          console.log('');
+          omitidos++;
+          continue;
+        }
+      }
+
+      // Ejecutar actualización con spinner
+      const sp = spinner(`Actualizando ${runtime.nombre}...`);
+
+      try {
+        const instalador = require('./instalador');
+        await instalador({
+          target: runtime.id,
+          profile: estado.perfil,
+          global: estado.global,
+          force: true,
+        });
+
+        sp.exito(`${runtime.nombre} actualizado a v${VERSION} (${estado.archivosInstalados.length} archivos)`);
+        actualizados++;
+      } catch (err) {
+        sp.fallo(`Error actualizando ${runtime.nombre}: ${err.message}`);
+      }
+
+      console.log('');
+    }
+  }
+
+  // 3. Reporte final
+  console.log(`  ${lineaSeparadora()}`);
+  if (actualizados > 0) {
+    console.log(formatearPaso('Resultado', `${actualizados} runtime(s) actualizado(s)${omitidos > 0 ? `, ${omitidos} omitido(s)` : ''}`));
+  } else if (omitidos > 0) {
+    console.log(formatearPaso('Resultado', 'Todo está actualizado'));
+  } else {
+    console.log(formatearAdvertencia('Resultado', 'Ningún runtime fue actualizado'));
+  }
+  console.log('');
+}
+
+module.exports = update;

package/scripts/audit-tools/auditar-relleno-inventario.js

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+// Auditoría de relleno: cross-referencias de componentes SWL.
+// Para cada skill/agente/comando cuenta las referencias de "cableado" desde
+// otros componentes (agentes, comandos, reglas, hooks, scripts, contextos,
+// otros skills). 0 referencias = huérfano operacional (candidato a relleno
+// o a cablear). Una skill sin cableado sigue siendo invocable por descripción,
+// así que el resultado es señal, no veredicto.
+//
+// Uso: node scripts/audit-tools/auditar-relleno-inventario.js [--json <ruta>]
+// Output JSON por defecto: .planning/audit/relleno-crossref.json
+'use strict';
+const fs = require('fs');
+const path = require('path');
+
+const REPO = path.resolve(__dirname, '..', '..');
+const DIRS_EXCLUIDOS = ['node_modules', '.git', 'temp', 'respositorios-git', '_logs'];
+
+function listarArchivos(dir, exts, out = []) {
+  if (!fs.existsSync(dir)) return out;
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    const p = path.join(dir, e.name);
+    if (e.isDirectory()) {
+      if (DIRS_EXCLUIDOS.includes(e.name)) continue;
+      listarArchivos(p, exts, out);
+    } else if (exts.some((x) => e.name.endsWith(x))) {
+      out.push(p);
+    }
+  }
+  return out;
+}
+
+// --- Inventario de componentes ---
+const skills = fs.readdirSync(path.join(REPO, 'habilidades'), { withFileTypes: true })
+  .filter((e) => e.isDirectory() && fs.existsSync(path.join(REPO, 'habilidades', e.name, 'SKILL.md')))
+  .map((e) => e.name);
+
+const agentes = fs.readdirSync(path.join(REPO, 'agentes'))
+  .filter((f) => f.endsWith('.md') && !f.startsWith('_'))
+  .map((f) => f.replace(/\.md$/, ''));
+
+const comandos = fs.readdirSync(path.join(REPO, 'comandos', 'swl'))
+  .filter((f) => f.endsWith('.md'))
+  .map((f) => f.replace(/\.md$/, ''));
+
+// --- Corpus de cableado (fuentes que "usan" componentes) ---
+const archivosCableado = [
+  ...listarArchivos(path.join(REPO, 'agentes'), ['.md']),
+  ...listarArchivos(path.join(REPO, 'comandos'), ['.md']),
+  ...listarArchivos(path.join(REPO, 'reglas'), ['.md']),
+  ...listarArchivos(path.join(REPO, 'hooks'), ['.js']),
+  ...listarArchivos(path.join(REPO, 'scripts'), ['.js']),
+  ...listarArchivos(path.join(REPO, 'contextos'), ['.md']),
+  ...listarArchivos(path.join(REPO, 'habilidades'), ['.md']),
+];
+
+const corpus = archivosCableado.map((f) => ({
+  file: f.replace(/\\/g, '/'),
+  text: fs.readFileSync(f, 'utf8'),
+}));
+const repoNorm = REPO.replace(/\\/g, '/') + '/';
+
+function contarReferencias(nombre, fragmentosPropios) {
+  const re = new RegExp(`(?<![\\w/-])${nombre.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?![\\w-])`, 'g');
+  let refs = 0;
+  const referrers = new Set();
+  for (const { file, text } of corpus) {
+    if (fragmentosPropios.some((frag) => file.includes(frag))) continue;
+    const m = text.match(re);
+    if (m) {
+      refs += m.length;
+      referrers.add(file.replace(repoNorm, ''));
+    }
+  }
+  return { refs, referrers: [...referrers] };
+}
+
+// --- modulos.json: pertenencia a módulos ---
+let componenteAModulo = {};
+try {
+  const modulosRaw = JSON.parse(fs.readFileSync(path.join(REPO, 'manifiestos', 'modulos.json'), 'utf8'));
+  const modulosDef = modulosRaw.modulos || modulosRaw;
+  for (const [modName, mod] of Object.entries(modulosDef)) {
+    const comps = mod.componentes || mod.archivos || [];
+    for (const c of (Array.isArray(comps) ? comps : [])) {
+      const base = String(c).split('/').pop().replace(/\.md$/, '');
+      componenteAModulo[base] = modName;
+      const parts = String(c).split('/');
+      if (parts[0] === 'habilidades' && parts[1]) componenteAModulo[parts[1]] = modName;
+    }
+  }
+} catch (err) {
+  console.warn(`[auditar-relleno] No se pudo leer manifiestos/modulos.json: ${err.message}`);
+}
+
+// Uso REAL (telemetría del hook telemetria-skill-routing.js → skill-metrics).
+// El cableado estático dice quién PODRÍA invocar una skill; esta señal dice
+// quién la invocó de verdad. Sin datos (proyecto sin sesiones), usos = null.
+let usosPorSkill = null;
+try {
+  const { obtenerMetricas } = require(path.join(REPO, 'scripts', 'lib', 'skill-metrics.js'));
+  const lista = obtenerMetricas(REPO); // [{skill, total, ok, error, ...}]
+  if (Array.isArray(lista) && lista.length > 0) {
+    usosPorSkill = Object.fromEntries(lista.map(m => [m.skill, m]));
+  }
+} catch (err) {
+  console.warn(`[auditar-relleno] telemetría de uso no disponible: ${err.message}`);
+}
+
+const reporte = { generado: null, conUsoReal: Boolean(usosPorSkill), skills: [], agentes: [], comandos: [] };
+
+for (const s of skills) {
+  const { refs, referrers } = contarReferencias(s, [`habilidades/${s}/`]);
+  const uso = usosPorSkill ? (usosPorSkill[s] ? usosPorSkill[s].total : 0) : null;
+  reporte.skills.push({ name: s, refs, usos: uso, modulo: componenteAModulo[s] || '?', referrers: referrers.slice(0, 8) });
+}
+for (const a of agentes) {
+  const { refs, referrers } = contarReferencias(a, [`agentes/${a}.md`]);
+  reporte.agentes.push({ name: a, refs, modulo: componenteAModulo[a] || '?', referrers: referrers.slice(0, 8) });
+}
+for (const c of comandos) {
+  const { refs, referrers } = contarReferencias(`swl:${c}`, [`comandos/swl/${c}.md`]);
+  reporte.comandos.push({ name: c, refs, modulo: componenteAModulo[c] || '?', referrers: referrers.slice(0, 8) });
+}
+
+for (const key of ['skills', 'agentes', 'comandos']) reporte[key].sort((x, y) => x.refs - y.refs);
+
+const idxJson = process.argv.indexOf('--json');
+const outPath = idxJson > -1 && process.argv[idxJson + 1]
+  ? path.resolve(process.argv[idxJson + 1])
+  : path.join(REPO, '.planning', 'audit', 'relleno-crossref.json');
+fs.writeFileSync(outPath, JSON.stringify(reporte, null, 2));
+
+console.log(`Skills: ${skills.length} | Agentes: ${agentes.length} | Comandos: ${comandos.length}`);
+console.log(usosPorSkill
+  ? `Telemetría de uso real: ${Object.keys(usosPorSkill).length} skills con invocaciones registradas (columna usos=)`
+  : 'Telemetría de uso real: sin datos (.planning/skill-metrics.json vacío — el hook telemetria-skill-routing la alimenta con el uso)');
+const huerfanas = reporte.skills.filter((s) => s.refs === 0);
+console.log(`\n=== SKILLS con 0 referencias de cableado (${huerfanas.length}) ===`);
+for (const s of huerfanas) console.log(`  ${s.name} [${s.modulo}]`);
+const bajas = reporte.skills.filter((s) => s.refs >= 1 && s.refs <= 2);
+console.log(`\n=== SKILLS con 1-2 referencias (${bajas.length}) ===`);
+for (const s of bajas) console.log(`  ${s.name} [${s.modulo}] refs=${s.refs} <- ${s.referrers.join(', ')}`);
+console.log('\n=== AGENTES con 0-2 referencias ===');
+for (const a of reporte.agentes.filter((x) => x.refs <= 2)) console.log(`  ${a.name} refs=${a.refs} <- ${a.referrers.join(', ')}`);
+console.log(`\nJSON completo: ${outPath}`);