@saulwade/swl-ses 2.5.3 → 2.6.1

package/scripts/lib/ciclo-autonomo/candidatos.js

@@ -0,0 +1,174 @@
+'use strict';
+
+/**
+ * candidatos.js — Detector determinista de candidatos a Fase B del ciclo
+ * autónomo (Fase 22, T-02, ADR-0042 gate G-B, REQ-22-01).
+ *
+ * Tres fuentes deterministas, SIN invocar LLM:
+ *   1. Instintos con `candidato_global:true` en `instintos/proyecto.yaml`
+ *      (via `yaml-instintos.leerInstintos`, tolerante a archivo ausente).
+ *   2. Nudges `kind:'auto-evolucion'` no accionados con evidencia
+ *      (`data.diagnosis` o `data.razon` en {fallos, loop}) leídos de
+ *      `evolution/nudges.jsonl`.
+ *   3. Skills fríos vía `require('../skill-metrics').skillsStale` (require
+ *      tolerante → `[]` si la lib no resuelve en el destino de instalación).
+ *
+ * Persiste SOLO los candidatos nuevos (dedupe por `id`, releyendo el jsonl
+ * previo con tolerancia por línea) en `evolution/candidatos-fase-b.jsonl`.
+ * Una corrida sin candidatos nuevos NO escribe el archivo (ni lo crea si no
+ * existía). Zero-deps, CommonJS.
+ *
+ * @module scripts/lib/ciclo-autonomo/candidatos
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { leerInstintos } = require('./yaml-instintos');
+
+const RUTA_INSTINTOS_RELATIVA = path.join('instintos', 'proyecto.yaml');
+const RUTA_NUDGES_RELATIVA = path.join('.planning', 'evolution', 'nudges.jsonl');
+const RUTA_CANDIDATOS_RELATIVA = path.join('.planning', 'evolution', 'candidatos-fase-b.jsonl');
+
+/** Razones de nudge `auto-evolucion` que cuentan como evidencia suficiente. */
+const RAZONES_CON_EVIDENCIA = new Set(['fallos', 'loop']);
+
+/** Lee un JSONL con tolerancia por línea: línea corrupta se descarta, nunca crashea. */
+function leerJsonlTolerante(ruta) {
+  let crudo;
+  try {
+    crudo = fs.readFileSync(ruta, 'utf8');
+  } catch (_) {
+    return [];
+  }
+  return crudo.split(/\r\n|\n/)
+    .filter((linea) => linea.trim() !== '')
+    .map((linea) => {
+      try {
+        return JSON.parse(linea);
+      } catch (_) {
+        return null;
+      }
+    })
+    .filter(Boolean);
+}
+
+/** Fuente 1: instintos con `candidato_global:true` en instintos/proyecto.yaml. */
+function candidatosDeInstintos(baseDir, ts) {
+  const ruta = path.join(baseDir, RUTA_INSTINTOS_RELATIVA);
+  let datos;
+  try {
+    datos = leerInstintos(ruta);
+  } catch (_) {
+    return []; // archivo ausente o YAML corrupto: sin candidatos de esta fuente
+  }
+
+  return (datos.instintos || [])
+    .filter((instinto) => instinto.candidato_global === true)
+    .map((instinto) => ({
+      id: `instinto:${instinto.id}`,
+      fuente: 'instinto-global',
+      ref: { id: instinto.id, pattern: instinto.pattern || null },
+      ts,
+      origen: 'ciclo-autonomo',
+    }));
+}
+
+/** Fuente 2: nudges `kind:'auto-evolucion'` no accionados con evidencia. */
+function candidatosDeNudges(baseDir, ts) {
+  const ruta = path.join(baseDir, RUTA_NUDGES_RELATIVA);
+
+  return leerJsonlTolerante(ruta)
+    .filter((nudge) => nudge && nudge.kind === 'auto-evolucion' && nudge.accionado !== true)
+    .filter((nudge) => {
+      const data = nudge.data || {};
+      return Boolean(data.diagnosis) || RAZONES_CON_EVIDENCIA.has(data.razon);
+    })
+    .map((nudge) => ({
+      id: `nudge:${nudge.id}`,
+      fuente: 'evolucion-agente',
+      ref: {
+        target: nudge.target || null,
+        razon: (nudge.data || {}).razon || null,
+        tieneDiagnosis: Boolean((nudge.data || {}).diagnosis),
+      },
+      ts,
+      origen: 'ciclo-autonomo',
+    }));
+}
+
+/** Fuente 3: skills fríos vía skill-metrics.skillsStale (require tolerante → []). */
+function candidatosDeSkillsFrios(baseDir, ahora, ts) {
+  let skillsStale;
+  try {
+    ({ skillsStale } = require('../skill-metrics'));
+  } catch (_) {
+    return []; // lib no distribuida en este destino: sin candidatos de esta fuente
+  }
+
+  let frios;
+  try {
+    frios = skillsStale(baseDir, ahora);
+  } catch (_) {
+    return [];
+  }
+
+  return (frios || []).map((frio) => ({
+    id: `skill:${frio.skill}`,
+    fuente: 'skill-stale',
+    ref: { skill: frio.skill, diasInactivo: frio.diasInactivo },
+    ts,
+    origen: 'ciclo-autonomo',
+  }));
+}
+
+/** Ids ya persistidos en `candidatos-fase-b.jsonl` (dedupe, tolerante por línea). */
+function idsConocidos(baseDir) {
+  const ruta = path.join(baseDir, RUTA_CANDIDATOS_RELATIVA);
+  return new Set(leerJsonlTolerante(ruta).map((entrada) => entrada.id).filter(Boolean));
+}
+
+/** Append de los candidatos nuevos (dedupe ya aplicado por el caller); no-op si viene vacío. */
+function persistirNuevos(baseDir, nuevos) {
+  if (nuevos.length === 0) return;
+
+  const ruta = path.join(baseDir, RUTA_CANDIDATOS_RELATIVA);
+  const dir = path.dirname(ruta);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+  const lineas = nuevos.map((candidato) => JSON.stringify(candidato)).join('\n') + '\n';
+  fs.appendFileSync(ruta, lineas);
+}
+
+/**
+ * Detecta candidatos a Fase B desde las tres fuentes deterministas y
+ * persiste (dedupe por id) SOLO los nuevos en `evolution/candidatos-fase-b.jsonl`.
+ * Tolerante a la ausencia de cualquier fuente — nunca crashea.
+ *
+ * @param {string} baseDir - Directorio raíz del proyecto.
+ * @param {{ahora?: Date}} [opciones]
+ * @returns {{nuevos: number, total: number, candidatos: object[]}}
+ */
+function detectar(baseDir, { ahora } = {}) {
+  const momento = ahora || new Date();
+  const ts = momento.toISOString();
+
+  const candidatos = [
+    ...candidatosDeInstintos(baseDir, ts),
+    ...candidatosDeNudges(baseDir, ts),
+    ...candidatosDeSkillsFrios(baseDir, momento, ts),
+  ];
+
+  const conocidos = idsConocidos(baseDir);
+  const vistos = new Set();
+  const nuevosCandidatos = candidatos.filter((candidato) => {
+    if (conocidos.has(candidato.id) || vistos.has(candidato.id)) return false;
+    vistos.add(candidato.id);
+    return true;
+  });
+
+  persistirNuevos(baseDir, nuevosCandidatos);
+
+  return { nuevos: nuevosCandidatos.length, total: candidatos.length, candidatos };
+}
+
+module.exports = { detectar };

package/scripts/lib/ciclo-autonomo/config.js

@@ -0,0 +1,165 @@
+'use strict';
+
+/**
+ * Loader/writer de `.planning/evolution/ciclo-config.json` — schema del
+ * motor determinista de aprendizaje (Fase 21, ADR-0041/ADR-0042, Nivel 0).
+ *
+ * Opt-OUT estricto (decisión del usuario 2026-07-10, reformula la regla de
+ * negocio 1 de la Fase 21): el motor NACE ENCENDIDO — "un ciclo que exige
+ * encendido es un ciclo muerto en downstream". Kill-switch doble:
+ * `habilitado:false` en el config (vía `/swl:evolucion-continua off`) o
+ * `SWL_CICLO_AUTONOMO=0` por sesión. Esta lib solo expone el predicado
+ * `estaHabilitado()`; el único punto que lo consulta para decidir si
+ * ejecutar es el orquestador (T-07, `index.js`) — las libs de sub-fase
+ * (writer, drenador, puente) son puras y no consultan config.
+ *
+ * Zero-deps, CommonJS.
+ *
+ * @module scripts/lib/ciclo-autonomo/config
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { atomicWriteJSON } = require('../../../hooks/lib/atomic-write');
+
+/** Ruta relativa del archivo de config dentro del baseDir del proyecto. */
+const CONFIG_RELATIVA = path.join('.planning', 'evolution', 'ciclo-config.json');
+
+/** Valores aceptados para el campo `credencial` (dual: cuenta Claude o API key). */
+const CREDENCIALES_VALIDAS = new Set(['cuenta', 'api-key']);
+
+/**
+ * Defaults del schema completo. Los campos LLM (`presupuesto_usd_mes`,
+ * `tope_mutaciones_corrida`) nacieron reservados en Fase 21 y se consumen a
+ * partir de Fase 22. Los campos `fase_b_habilitada`, `last_run_fase_b`,
+ * `gasto_mes`, `mes` y `pausado_por_presupuesto` son propios de Fase 22
+ * (headless plumbing, ADR-0042 gate G-B): `fase_b_habilitada` nace en `true`
+ * —kill-switch separado del motor, coherente con el opt-out estricto general
+ * (default encendido)—; `gasto_mes`/`mes` llevan el contador de presupuesto
+ * del mes en curso (clave `mes` en formato `YYYY-MM` local); `mes:null`
+ * fuerza el primer `registrarGasto` a inicializar el mes actual.
+ */
+const DEFAULTS = Object.freeze({
+  habilitado: true,
+  credencial: 'cuenta',
+  presupuesto_usd_mes: 10,
+  tope_mutaciones_corrida: 3,
+  last_run: null,
+  ultima_corrida: null,
+  fase_b_habilitada: true,
+  last_run_fase_b: null,
+  gasto_mes: 0,
+  mes: null,
+  pausado_por_presupuesto: false,
+});
+
+/**
+ * Resuelve la ruta absoluta del archivo de config para un baseDir dado.
+ *
+ * @param {string} baseDir - Directorio raíz del proyecto (normalmente cwd).
+ * @returns {string} Ruta absoluta a `ciclo-config.json`.
+ */
+function rutaConfig(baseDir) {
+  return path.join(baseDir, CONFIG_RELATIVA);
+}
+
+/**
+ * Normaliza el campo `credencial`: valor fuera del dominio válido cae a
+ * "cuenta" sin lanzar error — un config corrupto o editado a mano nunca
+ * debe crashear al motor.
+ *
+ * @param {*} valor - Valor crudo leído de disco o de un patch.
+ * @returns {"cuenta"|"api-key"}
+ */
+function normalizarCredencial(valor) {
+  return CREDENCIALES_VALIDAS.has(valor) ? valor : 'cuenta';
+}
+
+/**
+ * Lee el config del disco y lo mergea con los defaults del schema.
+ *
+ * Tolerante a archivo ausente (proyecto nunca habilitó el ciclo) y a JSON
+ * corrupto (config editado a mano incorrectamente) — en ambos casos cae
+ * a los defaults en vez de lanzar.
+ *
+ * @param {string} baseDir - Directorio raíz del proyecto.
+ * @returns {object} Config completo con todos los campos del schema.
+ */
+function leerConfig(baseDir) {
+  const ruta = rutaConfig(baseDir);
+  let crudo = {};
+
+  try {
+    const contenido = fs.readFileSync(ruta, 'utf8');
+    crudo = JSON.parse(contenido);
+  } catch (_) {
+    // Archivo ausente o JSON corrupto: se opera con los defaults.
+    crudo = {};
+  }
+
+  const mergeado = { ...DEFAULTS, ...crudo };
+  mergeado.credencial = normalizarCredencial(mergeado.credencial);
+  return mergeado;
+}
+
+/**
+ * Escribe un patch sobre el config existente (merge, no overwrite) y lo
+ * persiste de forma atómica. Crea `.planning/evolution/` si falta.
+ *
+ * @param {string} baseDir - Directorio raíz del proyecto.
+ * @param {object} patch   - Campos a actualizar; el resto se preserva.
+ * @returns {object} Config final ya escrito a disco.
+ */
+function escribirConfig(baseDir, patch) {
+  const actual = leerConfig(baseDir);
+  const siguiente = { ...actual, ...patch };
+  siguiente.credencial = normalizarCredencial(siguiente.credencial);
+
+  const ruta = rutaConfig(baseDir);
+  const dir = path.dirname(ruta);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  atomicWriteJSON(ruta, siguiente);
+  return siguiente;
+}
+
+/**
+ * Predicado de encendido del ciclo autónomo — opt-OUT estricto (decisión
+ * del usuario 2026-07-10): el motor nace ENCENDIDO; se apaga con
+ * `habilitado:false` en el config (`/swl:evolucion-continua off`) o con
+ * `SWL_CICLO_AUTONOMO=0` por sesión. `SWL_CICLO_AUTONOMO=1` fuerza el
+ * encendido por encima de un `off` en disco (override operacional en
+ * CI/cron sin tocar el archivo).
+ *
+ * @param {string} baseDir - Directorio raíz del proyecto.
+ * @returns {boolean}
+ */
+function estaHabilitado(baseDir) {
+  if (process.env.SWL_CICLO_AUTONOMO === '0') return false;
+  if (process.env.SWL_CICLO_AUTONOMO === '1') return true;
+  return leerConfig(baseDir).habilitado !== false;
+}
+
+/**
+ * Predicado de encendido de la Fase B (detector + runner headless,
+ * Fase 22) — kill-switch separado del motor general, pero SUBORDINADO a él
+ * (regla de negocio 1: motor apagado ⇒ Fase B apagada, sin excepción). Fase B
+ * no agrega variable de entorno propia: hereda `SWL_CICLO_AUTONOMO` a través
+ * de `estaHabilitado`.
+ *
+ * @param {string} baseDir - Directorio raíz del proyecto.
+ * @returns {boolean}
+ */
+function estaFaseBHabilitada(baseDir) {
+  if (!estaHabilitado(baseDir)) return false;
+  return leerConfig(baseDir).fase_b_habilitada !== false;
+}
+
+module.exports = {
+  estaHabilitado,
+  estaFaseBHabilitada,
+  leerConfig,
+  escribirConfig,
+};

package/scripts/lib/ciclo-autonomo/drenador-feedback.js

@@ -0,0 +1,174 @@
+'use strict';
+
+/**
+ * drenador-feedback.js — Drena `.planning/evolution/feedback-queue.jsonl`
+ * hacia `instintos/perfil-usuario.yaml` como señales draft (Fase 21 T-05,
+ * ADR-0041/0042, REQ-21-03/REQ-21-04).
+ *
+ * Ventana de 90 días sobre `ts`: lo reciente se consolida como señal draft
+ * de baja confianza (0.3 — nunca se inyecta a contexto, umbral en
+ * `hooks/inyeccion-contexto.js`); lo viejo se archiva SIN procesar. La cola
+ * activa se reescribe al final solo con lo que no pudo clasificarse (en la
+ * práctica, nada) — nunca crece sin límite.
+ *
+ * Tolerancia a líneas corruptas (patrón de `scripts/lib/evidencia-valor.js`
+ * función `leerNudges`): JSON inválido o sin `ts` parseable → se cuenta y
+ * se descarta, NUNCA crashea el drenado completo por una línea mala.
+ *
+ * Zero-deps, CommonJS.
+ *
+ * @module scripts/lib/ciclo-autonomo/drenador-feedback
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { atomicWriteSync } = require('../../../hooks/lib/atomic-write');
+const { agregarSenalesPerfil } = require('./yaml-instintos');
+
+const DIA_MS = 24 * 60 * 60 * 1000;
+const VENTANA_DIAS = 90;
+const CONFIDENCE_DRAFT = 0.3;
+
+const RUTA_COLA_RELATIVA = path.join('.planning', 'evolution', 'feedback-queue.jsonl');
+const RUTA_ARCHIVE_RELATIVA = path.join('.planning', 'evolution', 'feedback-queue.archive.jsonl');
+const RUTA_PERFIL_RELATIVA = path.join('instintos', 'perfil-usuario.yaml');
+
+/**
+ * Mapa `tipo` de señal → sección real de `perfil-usuario.yaml`.
+ *
+ * `preferencia` apunta a `preferencias_comunicacion`, que en el YAML real es
+ * un objeto de campos fijos (no una lista) — `agregarSenalesPerfil` lo trata
+ * como merge superficial de patch. `prohibicion`/`limite` apuntan a
+ * `limites_explicitos.no_sugerir`: el YAML real NO tiene una sub-lista
+ * `no_hacer` (solo `no_guardar`/`no_sugerir`); `no_sugerir` es la más
+ * genérica de las dos para una señal de "evitar X" sin más contexto.
+ */
+const MAPA_SECCION_POR_TIPO = {
+  correccion: 'correcciones_repetidas',
+  preferencia: 'preferencias_comunicacion',
+  prohibicion: 'limites_explicitos.no_sugerir',
+  limite: 'limites_explicitos.no_sugerir',
+  accion: 'patrones_trabajo',
+};
+const SECCION_POR_DEFECTO = 'patrones_trabajo';
+
+function rutaCola(baseDir) { return path.join(baseDir, RUTA_COLA_RELATIVA); }
+function rutaArchive(baseDir) { return path.join(baseDir, RUTA_ARCHIVE_RELATIVA); }
+function rutaPerfil(baseDir) { return path.join(baseDir, RUTA_PERFIL_RELATIVA); }
+
+function seccionParaTipo(tipo) {
+  return MAPA_SECCION_POR_TIPO[tipo] || SECCION_POR_DEFECTO;
+}
+
+/** Resumen legible de la señal para dedupe y para el campo `texto` del draft. */
+function resumenSenal(entrada) {
+  const partes = [entrada.accion, entrada.archivo].filter(Boolean);
+  if (partes.length > 0) return partes.join(' — ');
+  return String(entrada.tipo || 'señal');
+}
+
+/**
+ * Drena la cola de feedback hacia `perfil-usuario.yaml` con ventana de 90
+ * días y rotación de la cola.
+ *
+ * @param {string} baseDir - Directorio raíz del proyecto.
+ * @param {{ ahora?: Date }} [opts]
+ * @returns {{ drenados: number, archivados: number, descartados: number }}
+ */
+function drenar(baseDir, { ahora = new Date() } = {}) {
+  const resultado = { drenados: 0, archivados: 0, descartados: 0 };
+
+  const rutaColaAbs = rutaCola(baseDir);
+  if (!fs.existsSync(rutaColaAbs)) return resultado;
+
+  const lineas = fs.readFileSync(rutaColaAbs, 'utf8').split(/\r?\n/);
+  const corte = ahora.getTime() - VENTANA_DIAS * DIA_MS;
+
+  const paraArchive = [];
+  // Grupos de dedupe: sección → (texto normalizado → entrada draft acumulada).
+  const gruposPorSeccion = new Map();
+
+  for (const linea of lineas) {
+    if (!linea.trim()) continue;
+
+    let entrada;
+    try {
+      entrada = JSON.parse(linea);
+    } catch (_) {
+      resultado.descartados += 1;
+      continue;
+    }
+    if (!entrada || typeof entrada !== 'object') {
+      resultado.descartados += 1;
+      continue;
+    }
+
+    if (entrada.procesado === true) {
+      // Ya consumida en una corrida previa: solo limpiar de la cola activa.
+      paraArchive.push(linea);
+      continue;
+    }
+
+    const tsMs = Date.parse(entrada.ts);
+    if (Number.isNaN(tsMs)) {
+      resultado.descartados += 1;
+      continue;
+    }
+
+    if (tsMs <= corte) {
+      // >90 días: archivar SIN procesar.
+      paraArchive.push(linea);
+      resultado.archivados += 1;
+      continue;
+    }
+
+    // ≤90 días: consolidar como señal draft.
+    const seccion = seccionParaTipo(entrada.tipo);
+    const texto = resumenSenal(entrada);
+    const clave = texto.trim().toLowerCase();
+
+    if (!gruposPorSeccion.has(seccion)) gruposPorSeccion.set(seccion, new Map());
+    const grupo = gruposPorSeccion.get(seccion);
+
+    if (grupo.has(clave)) {
+      grupo.get(clave).ocurrencias += 1;
+    } else {
+      grupo.set(clave, {
+        texto,
+        confidence: CONFIDENCE_DRAFT,
+        origen: 'ciclo-autonomo',
+        fecha: ahora.toLocaleDateString('sv'), // fecha local — gate C1
+        evidencia: entrada.sessionId || null,
+        ocurrencias: 1,
+      });
+    }
+
+    entrada.procesado = true;
+    paraArchive.push(JSON.stringify(entrada));
+    resultado.drenados += 1;
+  }
+
+  if (gruposPorSeccion.size > 0) {
+    const rutaPerfilAbs = rutaPerfil(baseDir);
+    for (const [seccion, grupo] of gruposPorSeccion) {
+      const entradas = [...grupo.values()];
+      const valores = seccion.startsWith('limites_explicitos.')
+        ? entradas.map((e) => e.texto)
+        : entradas;
+      agregarSenalesPerfil(rutaPerfilAbs, seccion, valores);
+    }
+  }
+
+  // Append al archive (JSONL de alta frecuencia — nunca reescritura total).
+  if (paraArchive.length > 0) {
+    fs.appendFileSync(rutaArchive(baseDir), paraArchive.join('\n') + '\n');
+  }
+
+  // Rotación: la cola activa solo conserva lo que no se pudo clasificar
+  // (en la práctica, nada — drenados/archivados/descartados cubren todo).
+  atomicWriteSync(rutaColaAbs, '');
+
+  return resultado;
+}
+
+module.exports = { drenar };

package/scripts/lib/ciclo-autonomo/fallback.js

@@ -0,0 +1,77 @@
+'use strict';
+
+/**
+ * fallback.js — Predicado puro del fallback de disparo del ciclo autónomo
+ * desde `hooks/session-briefing.js` (Fase 21, T-11, REQ-21-11).
+ *
+ * El scheduler cron (`gateway/cron/jobs.example.json`) es el disparador
+ * primario de la Fase A. Este predicado cubre el caso sin scheduler
+ * configurado: si el motor está habilitado y pasaron >=24h desde la última
+ * corrida exitosa (o nunca corrió), señala que toca disparar. El lock propio
+ * del ciclo (`lock.js`, T-02) es quien garantiza la exclusión mutua real
+ * entre el scheduler y este fallback — `debeDisparar` NO consulta el estado
+ * del lock, solo el reloj.
+ *
+ * Puro y testeable: recibe `baseDir` y una fecha inyectable (`ahora`), sin
+ * spawnear procesos — el caller (el hook) decide cómo lanzar la Fase A.
+ *
+ * Guard barato PRIMERO (`fs.existsSync` de `.planning/evolution/`): si el
+ * directorio de señales no existe, el proyecto no tiene telemetría SWL y se
+ * retorna de inmediato SIN requerir `config.js` ni `lock.js` — ese costo no
+ * debe pagarse en el hot path de un hook SessionStart (presupuesto <200ms,
+ * REQ-12-02). Antes el guard era la existencia de `ciclo-config.json`
+ * (opt-in); con el default encendido (decisión del usuario 2026-07-10,
+ * opt-out) el config puede no existir y el motor debe correr igual.
+ *
+ * Zero-deps, CommonJS.
+ *
+ * @module scripts/lib/ciclo-autonomo/fallback
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/** Ventana mínima entre corridas del fallback: 24 horas en ms. */
+const VENTANA_MS = 24 * 60 * 60 * 1000;
+
+/** Directorio de señales SWL — su existencia es el guard barato del hot path. */
+const EVOLUTION_RELATIVA = path.join('.planning', 'evolution');
+
+/**
+ * Decide si el fallback de `session-briefing` debe disparar la Fase A.
+ *
+ * @param {string} baseDir - Directorio raíz del proyecto.
+ * @param {{ahora?: Date}} [opciones]
+ * @returns {{disparar: boolean, razon: string}}
+ */
+function debeDisparar(baseDir, { ahora } = {}) {
+  const rutaEvolution = path.join(baseDir, EVOLUTION_RELATIVA);
+  if (!fs.existsSync(rutaEvolution)) {
+    return { disparar: false, razon: 'sin-telemetria-swl' };
+  }
+
+  // Solo en proyectos con telemetría SWL se paga el costo de requerir las
+  // libs del ciclo (el default es encendido — opt-out estricto).
+  const config = require('./config');
+  const lock = require('./lock');
+
+  if (!config.estaHabilitado(baseDir)) {
+    return { disparar: false, razon: 'deshabilitado' };
+  }
+
+  const momento = ahora || new Date();
+  const ultimaMs = lock.ultimaCorridaMs(baseDir);
+
+  if (ultimaMs === null) {
+    return { disparar: true, razon: 'sin corridas previas' };
+  }
+
+  const transcurridoMs = momento.getTime() - ultimaMs;
+  if (transcurridoMs >= VENTANA_MS) {
+    return { disparar: true, razon: `>=24h desde última corrida (${transcurridoMs}ms)` };
+  }
+
+  return { disparar: false, razon: `<24h desde última corrida (${transcurridoMs}ms)` };
+}
+
+module.exports = { debeDisparar, VENTANA_MS };