@saulwade/swl-ses 2.5.3 → 2.6.0

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

@@ -0,0 +1,122 @@
+'use strict';
+
+/**
+ * presupuesto.js — Contador de presupuesto USD/mes de la Fase B del ciclo
+ * autónomo (Fase 22, T-04, ADR-0042 gate G-B, REQ-22-03).
+ *
+ * Lleva la cuenta del gasto mensual sobre los campos `gasto_mes`/`mes`/
+ * `pausado_por_presupuesto` de `ciclo-config.json` (extendidos en T-01,
+ * `config.js`). El mes se calcula en hora LOCAL —
+ * `toLocaleDateString('sv').slice(0,7)` → `YYYY-MM` (gate C1: NUNCA
+ * `toISOString()`, desde México la tarde ya es "mañana" en UTC.
+ *
+ * El reset mensual es EFECTIVO en lectura: `estado`/`puedeGastar`/
+ * `estaPausado` ven el contador en cero y despausado en cuanto cambia el mes,
+ * SIN escribir a disco. La persistencia real del reset ocurre recién cuando
+ * `registrarGasto` corre (mismo patrón que "el reset lo aplica quien
+ * escribe", no quien lee).
+ *
+ * Zero-deps (solo `config.js`), CommonJS.
+ *
+ * @module scripts/lib/ciclo-autonomo/presupuesto
+ */
+
+const config = require('./config');
+
+/**
+ * Clave de mes en formato local `YYYY-MM` (gate C1: local, nunca UTC).
+ *
+ * @param {Date} [ahora]
+ * @returns {string}
+ */
+function mesActual(ahora) {
+  const momento = ahora || new Date();
+  return momento.toLocaleDateString('sv').slice(0, 7);
+}
+
+/**
+ * Estado efectivo del presupuesto para el mes de `ahora`. Si el `mes` en
+ * disco difiere del actual, devuelve el contador reseteado SIN persistirlo
+ * (la persistencia real la hace `registrarGasto`).
+ *
+ * @param {string} baseDir - Directorio raíz del proyecto.
+ * @param {{ahora?: Date}} [opciones]
+ * @returns {{gasto_mes: number, mes: string, pausado_por_presupuesto: boolean, tope: number}}
+ */
+function estado(baseDir, { ahora } = {}) {
+  const cfg = config.leerConfig(baseDir);
+  const mes = mesActual(ahora);
+
+  if (cfg.mes !== mes) {
+    return { gasto_mes: 0, mes, pausado_por_presupuesto: false, tope: cfg.presupuesto_usd_mes };
+  }
+
+  return {
+    gasto_mes: cfg.gasto_mes,
+    mes: cfg.mes,
+    pausado_por_presupuesto: cfg.pausado_por_presupuesto,
+    tope: cfg.presupuesto_usd_mes,
+  };
+}
+
+/**
+ * `true` si la Fase B está pausada por presupuesto para el mes de `ahora`.
+ * Un cambio de mes despausa automáticamente (reset efectivo, sin escribir).
+ *
+ * @param {string} baseDir - Directorio raíz del proyecto.
+ * @param {{ahora?: Date}} [opciones]
+ * @returns {boolean}
+ */
+function estaPausado(baseDir, { ahora } = {}) {
+  return estado(baseDir, { ahora }).pausado_por_presupuesto;
+}
+
+/**
+ * Evalúa si se puede gastar `usd` adicionales sin cruzar el presupuesto
+ * mensual ni estar ya pausado. NUNCA muta el config — es una consulta pura.
+ *
+ * @param {string} baseDir - Directorio raíz del proyecto.
+ * @param {number} usd - Gasto adicional a evaluar (0 = solo verificar estado).
+ * @param {{ahora?: Date}} [opciones]
+ * @returns {{permitido: boolean, razon?: string}}
+ */
+function puedeGastar(baseDir, usd, { ahora } = {}) {
+  const st = estado(baseDir, { ahora });
+
+  if (st.pausado_por_presupuesto) {
+    return { permitido: false, razon: 'pausado-presupuesto' };
+  }
+  if (st.gasto_mes + usd > st.tope) {
+    return { permitido: false, razon: 'excede-tope' };
+  }
+  return { permitido: true };
+}
+
+/**
+ * Registra un gasto de `usd` en el mes de `ahora`: resetea el contador si el
+ * mes cambió, acumula `gasto_mes`, y marca `pausado_por_presupuesto:true` si
+ * el acumulado CRUZA (supera) el tope mensual. Persiste siempre con
+ * `escribirConfig` (atomic) — incluso con `usd:0`, que es como el runner de
+ * Fase B (T-05) registra una corrida dry-run: el contador es infra, no gasta.
+ *
+ * @param {string} baseDir - Directorio raíz del proyecto.
+ * @param {number} usd - Gasto a acumular (0 = solo inicializa/preserva el mes).
+ * @param {{ahora?: Date}} [opciones]
+ * @returns {{gasto_mes: number, mes: string, pausado_por_presupuesto: boolean}}
+ */
+function registrarGasto(baseDir, usd, { ahora } = {}) {
+  const st = estado(baseDir, { ahora });
+  const gastoNuevo = st.gasto_mes + usd;
+  const pausado = st.pausado_por_presupuesto || gastoNuevo > st.tope;
+
+  const siguiente = {
+    mes: st.mes,
+    gasto_mes: gastoNuevo,
+    pausado_por_presupuesto: pausado,
+  };
+  config.escribirConfig(baseDir, siguiente);
+
+  return siguiente;
+}
+
+module.exports = { mesActual, estado, estaPausado, puedeGastar, registrarGasto };

package/scripts/lib/ciclo-autonomo/puente-degradacion.js

@@ -0,0 +1,240 @@
+'use strict';
+
+/**
+ * puente-degradacion.js — Cierra el lazo entre APRENDIZAJES.md (memoria en
+ * prosa) y los instintos derivados en `instintos/proyecto.yaml` (memoria
+ * estructurada). Cuando `hooks/degradacion-instintos.js` marca una entrada
+ * de APRENDIZAJES como `**[DEGRADADO: fecha]**` (tras 3 contradicciones,
+ * ver `hooks/degradacion-instintos.js:216-222`), ese hecho nunca bajaba la
+ * confidence del instinto YAML que se derivó de esa misma entrada — el
+ * puente cierra ese lazo (Fase 21, ADR-0041/0042).
+ *
+ * `puentear(baseDir, {ahora})` es de solo lectura sobre APRENDIZAJES.md
+ * (nunca lo escribe) y persiste sus cambios en `instintos/proyecto.yaml`
+ * únicamente cuando hubo al menos un match (`bajados > 0`).
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * Criterio de matching (decisión de diseño deliberadamente conservadora):
+ *
+ *   "Mejor NO matchear que matchear mal" — un falso positivo degrada un
+ *   instinto sano; un falso negativo simplemente pospone la degradación al
+ *   próximo aprendizaje que sí matchee con más señal.
+ *
+ * 1. Candidatos: solo instintos con `source` que mencione "aprendizajes"
+ *    (típicamente `source: "APRENDIZAJES.md"`) o con `seccion_origen` no
+ *    vacío — es decir, instintos derivados de esa memoria, nunca instintos
+ *    de otro origen (ej. instintos sembrados manualmente sin sección).
+ * 2. Se extraen keywords normalizadas (minúsculas, sin acentos, ≥4 letras,
+ *    sin stopwords) del título del aprendizaje degradado y, por el lado del
+ *    instinto, de la unión de `pattern` + `description` + `seccion_origen`.
+ * 3. Match = al menos `UMBRAL_MIN_COMPARTIDAS` (2) keywords compartidas Y
+ *    al menos `UMBRAL_COBERTURA` (40%) de las keywords del aprendizaje
+ *    cubiertas por el instinto. El umbral doble evita que una sola palabra
+ *    genérica compartida ("orquestador" solo) dispare una degradación, y
+ *    evita que un instinto con vocabulario enorme absorba matches por pura
+ *    probabilidad (la cobertura se mide sobre el lado más corto: el título
+ *    del aprendizaje, no el instinto).
+ *
+ * NUNCA usar similitud léxica difusa (Levenshtein, embeddings) — este es el
+ * motor Nivel 0 (determinista, sin LLM, ADR-0042); la heurística de keywords
+ * es intencionalmente simple y auditable.
+ *
+ * @module scripts/lib/ciclo-autonomo/puente-degradacion
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { leerInstintos, escribirInstintos } = require('./yaml-instintos');
+const { shouldAutoDeprecate } = require('../scoring-instintos');
+
+// ─────────────────────────────────────────────────────────────────────────
+// Constantes del criterio de matching
+// ─────────────────────────────────────────────────────────────────────────
+
+const LONGITUD_MINIMA_KEYWORD = 4;
+const UMBRAL_MIN_COMPARTIDAS = 2;
+const UMBRAL_COBERTURA = 0.4;
+const UMBRAL_CONTRADICTIONS_DEGRADACION = 3;
+const RAZON_DEGRADACION = 'aprendizaje origen degradado en APRENDIZAJES.md';
+
+const REGEX_DEGRADADO = /^\*\*\[DEGRADADO:\s*([^\]]+)\]\*\*/;
+// Mismo patrón que hooks/degradacion-instintos.js:leerEntradas() usa para
+// extraer el título legible de la entrada a partir del encabezado `## `.
+const REGEX_ENCABEZADO = /^##\s+\[\d{4}-\d{2}-\d{2}\]\s+\w+[-\w]*\s+—\s+/;
+
+const STOPWORDS = new Set([
+  'para', 'con', 'que', 'los', 'las', 'del', 'una', 'uno', 'este', 'esta',
+  'estos', 'estas', 'como', 'desde', 'entre', 'sobre', 'cuando', 'donde',
+  'pero', 'sin', 'tras', 'hacia', 'segun', 'según', 'muy', 'mas', 'más',
+  'menos', 'todo', 'toda', 'todos', 'todas', 'cada', 'otro', 'otra',
+  'otros', 'otras', 'ser', 'esta', 'están', 'debe', 'deben', 'hay',
+]);
+
+// ─────────────────────────────────────────────────────────────────────────
+// Utilidades de keywords normalizadas
+// ─────────────────────────────────────────────────────────────────────────
+
+function normalizarPalabra(palabra) {
+  // NFD descompone "ó" en "o" + diacrítico combinante (rango Unicode U+0300-U+036F);
+  // quitarlo deja el equivalente ASCII sin acentos para comparar keywords.
+  return palabra.normalize('NFD').replace(/[̀-ͯ]/g, '').toLowerCase();
+}
+
+/** Extrae el set de keywords normalizadas (≥4 letras, sin stopwords) de un texto. */
+function extraerKeywords(texto) {
+  if (!texto) return new Set();
+  const palabras = String(texto)
+    .split(/[^A-Za-zÀ-ÿ0-9]+/)
+    .map(normalizarPalabra)
+    .filter((p) => p.length >= LONGITUD_MINIMA_KEYWORD && !STOPWORDS.has(p));
+  return new Set(palabras);
+}
+
+/**
+ * Determina si dos sets de keywords "matchean" bajo el criterio conservador
+ * documentado arriba: compartidas ≥ UMBRAL_MIN_COMPARTIDAS Y cobertura del
+ * lado del aprendizaje ≥ UMBRAL_COBERTURA.
+ */
+function esMatch(keywordsAprendizaje, keywordsInstinto) {
+  if (keywordsAprendizaje.size === 0 || keywordsInstinto.size === 0) return false;
+
+  let compartidas = 0;
+  keywordsAprendizaje.forEach((k) => {
+    if (keywordsInstinto.has(k)) compartidas += 1;
+  });
+
+  const cobertura = compartidas / keywordsAprendizaje.size;
+  return compartidas >= UMBRAL_MIN_COMPARTIDAS && cobertura >= UMBRAL_COBERTURA;
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Lectura (solo lectura) de APRENDIZAJES.md
+// ─────────────────────────────────────────────────────────────────────────
+
+/**
+ * Lee `APRENDIZAJES.md` y devuelve las entradas marcadas `**[DEGRADADO: ...]**`
+ * (formato exacto que escribe `hooks/degradacion-instintos.js:218`), con el
+ * título de la entrada y sus keywords ya normalizadas. Nunca escribe el
+ * archivo — es puramente de lectura.
+ *
+ * @param {string} rutaAprendizajes
+ * @returns {Array<{titulo: string, fecha: string, keywords: Set<string>}>}
+ */
+function leerAprendizajesDegradados(rutaAprendizajes) {
+  const contenido = fs.readFileSync(rutaAprendizajes, 'utf8');
+  const lineas = contenido.split(/\r\n|\n/);
+  const degradados = [];
+
+  for (let i = 0; i < lineas.length; i++) {
+    if (!lineas[i].startsWith('## ')) continue;
+
+    const titulo = lineas[i].replace(REGEX_ENCABEZADO, '').trim();
+
+    let fin = i + 1;
+    while (fin < lineas.length && !lineas[fin].startsWith('## ')) fin += 1;
+
+    let fechaDegradado = null;
+    for (let j = i + 1; j < fin; j++) {
+      const m = lineas[j].match(REGEX_DEGRADADO);
+      if (m) { fechaDegradado = m[1].trim(); break; }
+    }
+
+    if (fechaDegradado) {
+      degradados.push({ titulo, fecha: fechaDegradado, keywords: extraerKeywords(titulo) });
+    }
+  }
+
+  return degradados;
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Candidatos e instintos
+// ─────────────────────────────────────────────────────────────────────────
+
+/** Un instinto es candidato al puente si fue derivado de APRENDIZAJES.md. */
+function esCandidatoDerivado(instinto) {
+  const source = String(instinto.source || '').toLowerCase();
+  const tieneSeccionOrigen = typeof instinto.seccion_origen === 'string'
+    && instinto.seccion_origen.trim() !== '';
+  return source.includes('aprendizajes') || tieneSeccionOrigen;
+}
+
+function keywordsDeInstinto(instinto) {
+  const texto = [instinto.pattern, instinto.description, instinto.seccion_origen]
+    .filter((v) => typeof v === 'string')
+    .join(' ');
+  return extraerKeywords(texto);
+}
+
+function fechaLocal(ahora) {
+  const d = ahora instanceof Date ? ahora : (ahora ? new Date(ahora) : new Date());
+  return d.toLocaleDateString('sv');
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// API pública
+// ─────────────────────────────────────────────────────────────────────────
+
+/**
+ * Baja la confidence (vía `contradictions`) de los instintos de
+ * `instintos/proyecto.yaml` cuyo aprendizaje de origen fue marcado
+ * `**[DEGRADADO]**` en `.planning/APRENDIZAJES.md`.
+ *
+ * Idempotente: un instinto ya marcado `degradado_por_puente: true` nunca
+ * vuelve a incrementarse en corridas subsecuentes, sin importar cuántas
+ * entradas degradadas nuevas matcheen con él.
+ *
+ * @param {string} baseDir - Raíz del proyecto (o sandbox de test).
+ * @param {{ahora?: Date|string}} [opts]
+ * @returns {{bajados: number}}
+ */
+function puentear(baseDir, { ahora } = {}) {
+  const rutaAprendizajes = path.join(baseDir, '.planning', 'APRENDIZAJES.md');
+  const rutaProyecto = path.join(baseDir, 'instintos', 'proyecto.yaml');
+
+  if (!fs.existsSync(rutaAprendizajes) || !fs.existsSync(rutaProyecto)) {
+    return { bajados: 0 };
+  }
+
+  const aprendizajesDegradados = leerAprendizajesDegradados(rutaAprendizajes);
+  if (aprendizajesDegradados.length === 0) return { bajados: 0 };
+
+  const datos = leerInstintos(rutaProyecto);
+  const hoy = fechaLocal(ahora);
+  let bajados = 0;
+
+  datos.instintos.forEach((instinto) => {
+    if (instinto.degradado_por_puente) return; // idempotencia: ya bajado antes
+    if (!esCandidatoDerivado(instinto)) return;
+
+    const keywordsInstinto = keywordsDeInstinto(instinto);
+    if (keywordsInstinto.size === 0) return;
+
+    const hayMatch = aprendizajesDegradados.some(
+      (aprendizaje) => esMatch(aprendizaje.keywords, keywordsInstinto)
+    );
+    if (!hayMatch) return;
+
+    instinto.contradictions = (instinto.contradictions || 0) + 1;
+    instinto.degradado_por_puente = true;
+    instinto.origen = 'ciclo-autonomo';
+    instinto.last_validated_at = hoy;
+
+    if (instinto.contradictions >= UMBRAL_CONTRADICTIONS_DEGRADACION || shouldAutoDeprecate(instinto)) {
+      instinto.status = 'degraded';
+      instinto.deprecation_reason = RAZON_DEGRADACION;
+    }
+
+    bajados += 1;
+  });
+
+  if (bajados === 0) return { bajados: 0 };
+
+  escribirInstintos(rutaProyecto, datos);
+  return { bajados };
+}
+
+module.exports = {
+  puentear,
+};

package/scripts/lib/ciclo-autonomo/runner-fase-b.js

@@ -0,0 +1,248 @@
+'use strict';
+
+/**
+ * runner-fase-b.js — Orquestador headless de la Fase B del ciclo autónomo
+ * (Fase 22, T-05, ADR-0042 gate G-B, REQ-22-04/REQ-22-05).
+ *
+ * Tubería secuencial de gates, cada uno con razón registrada (regla de
+ * negocio 5 — "toda corrida, incluso diferida, registra razón"): habilitado
+ * → lock propio (`.ciclo-fase-b-lock`) → catch-up (≥7 días desde
+ * `last_run_fase_b` Y candidatos pendientes) → guard de convivencia →
+ * credencial dual → presupuesto → tope de mutaciones por corrida →
+ * invocación (abstraída, F24). En `dryRun` (default `true`) el `invocador`
+ * NUNCA se llama — el runner valida la tubería completa y registra la
+ * corrida sin gastar ni invocar LLM.
+ *
+ * `invocador`, `detectorProcesos` y `verificadorCredencial` son interfaces
+ * INYECTABLES: F22 no implementa prompts/juez/mutación real (eso es F24);
+ * los tests inyectan dobles deterministas y verifican CERO spawns/llamadas
+ * reales al invocador.
+ *
+ * El gate de habilitado (1) es el ÚNICO que NO deja rastro en disco (ni
+ * lock ni telemetría) — Fase B apagada debe ser indistinguible de "nunca
+ * instalada". Todo gate posterior SIEMPRE appendea una línea a
+ * `evolution/ciclo-fase-b.jsonl`, incluida una corrida diferida.
+ *
+ * El marcador de "última corrida" de Fase B vive en `last_run_fase_b`
+ * (config), NO en el mtime del lockfile — por eso una corrida exitosa
+ * LIBERA el lock (lo borra) en vez de solo tocarle el mtime.
+ *
+ * Zero-deps, CommonJS.
+ *
+ * @module scripts/lib/ciclo-autonomo/runner-fase-b
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const config = require('./config');
+const candidatos = require('./candidatos');
+const guardConvivencia = require('./guard-convivencia');
+const presupuesto = require('./presupuesto');
+const { tryAcquireLock, rollbackLock, lockPath } = require('../../../hooks/lib/consolidation-lock');
+
+/** Lockfile propio de Fase B — independiente de `.ciclo-autonomo-lock` (Fase A). */
+const LOCK_FILENAME = '.ciclo-fase-b-lock';
+
+/** Ventana de catch-up: mínimo de días entre corridas reales de Fase B. */
+const CATCHUP_MS = 7 * 24 * 60 * 60 * 1000;
+
+const RUTA_TELEMETRIA_RELATIVA = path.join('evolution', 'ciclo-fase-b.jsonl');
+
+/** Razones de corte expuestas para consumo de tests/CLI (T-07 las imprime en `status`). */
+const RAZONES = Object.freeze({
+  DESHABILITADO: 'deshabilitado',
+  LOCK_OCUPADO: 'lock-ocupado',
+  SIN_CATCHUP: 'sin-catch-up',
+  SIN_CANDIDATOS: 'sin-candidatos',
+  CLAUDE_NO_EN_PATH: 'claude-no-en-path',
+  API_KEY_AUSENTE: 'api-key-ausente',
+  INVOCADOR_NO_DISPONIBLE: 'invocador-no-disponible',
+  INVOCADOR_FALLO: 'invocador-fallo',
+});
+
+function rutaTelemetria(baseDir) {
+  return path.join(baseDir, '.planning', RUTA_TELEMETRIA_RELATIVA);
+}
+
+/** Fecha-hora local legible ("YYYY-MM-DD HH:mm:ss") — NUNCA toISOString (gate C1). */
+function fechaHoraLocal(momento) {
+  return `${momento.toLocaleDateString('sv')} ${momento.toLocaleTimeString('sv')}`;
+}
+
+/** Append de una línea de telemetría a `evolution/ciclo-fase-b.jsonl`; crea el directorio si falta. */
+function escribirTelemetria(baseDir, entrada) {
+  const ruta = rutaTelemetria(baseDir);
+  const dir = path.dirname(ruta);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  fs.appendFileSync(ruta, JSON.stringify(entrada) + '\n');
+}
+
+/**
+ * `true` si ya pasaron >= 7 días desde `lastRunFaseB`. `null`/valor corrupto
+ * cuenta como catch-up debido (nunca hubo corrida real todavía).
+ */
+function tocaCatchUp(lastRunFaseB, ahora) {
+  if (!lastRunFaseB) return true;
+  const anterior = new Date(lastRunFaseB);
+  if (Number.isNaN(anterior.getTime())) return true;
+  return (ahora.getTime() - anterior.getTime()) >= CATCHUP_MS;
+}
+
+/** Detector de credencial por defecto (modo `cuenta`): `claude` resuelve en PATH. */
+function credencialCuentaPorDefecto() {
+  const resultado = spawnSync('claude', ['--version'], { timeout: 3000, encoding: 'utf8' });
+  return Boolean(resultado && !resultado.error && resultado.status === 0);
+}
+
+/**
+ * Verifica la credencial dual configurada. NUNCA lanza — cualquier fallo de
+ * detección se traduce a una razón accionable en vez de crashear el runner.
+ */
+function verificarCredencial(cfg, verificadorCredencial) {
+  if (cfg.credencial === 'api-key') {
+    const clave = process.env.ANTHROPIC_API_KEY;
+    if (!clave || clave.trim() === '') return { ok: false, razon: RAZONES.API_KEY_AUSENTE };
+    return { ok: true };
+  }
+
+  const verificar = verificadorCredencial || credencialCuentaPorDefecto;
+  let disponible = false;
+  try {
+    disponible = Boolean(verificar());
+  } catch (_) {
+    disponible = false;
+  }
+  return disponible ? { ok: true } : { ok: false, razon: RAZONES.CLAUDE_NO_EN_PATH };
+}
+
+/** Corte de una corrida diferida: rollback del lock adquirido + telemetría con la razón. */
+function diferir(baseDir, { momento, dryRun, priorMtime, razon, candidatosConsiderados = 0 }) {
+  rollbackLock(baseDir, priorMtime, { lockFilename: LOCK_FILENAME });
+  escribirTelemetria(baseDir, {
+    ts: momento.toISOString(),
+    origen: 'ciclo-fase-b',
+    dryRun,
+    razon,
+    candidatos_considerados: candidatosConsiderados,
+  });
+  return { ejecutado: false, razon };
+}
+
+/** Libera el lock de Fase B borrando el archivo (el marcador real es `last_run_fase_b`, no el mtime). */
+function liberarLock(baseDir) {
+  const lp = lockPath(baseDir, { lockFilename: LOCK_FILENAME });
+  try {
+    fs.unlinkSync(lp);
+  } catch (_) {
+    // ya no existía o no se pudo borrar — no bloqueante, la corrida ya completó.
+  }
+}
+
+/**
+ * Corre la Fase B headless sobre `baseDir`.
+ *
+ * @param {string} baseDir - Directorio raíz del proyecto.
+ * @param {{
+ *   ahora?: Date,
+ *   dryRun?: boolean,
+ *   invocador?: (candidatos: object[], ctx: {baseDir: string, ahora: Date}) => void,
+ *   detectorProcesos?: () => string,
+ *   verificadorCredencial?: () => boolean,
+ * }} [opciones]
+ * @returns {{ejecutado: boolean, razon?: string, dryRun?: boolean, candidatos?: number}}
+ */
+function correrFaseB(baseDir, {
+  ahora,
+  dryRun = true,
+  invocador,
+  detectorProcesos,
+  verificadorCredencial,
+} = {}) {
+  if (!config.estaFaseBHabilitada(baseDir)) {
+    return { ejecutado: false, razon: RAZONES.DESHABILITADO };
+  }
+
+  const momento = ahora || new Date();
+  const { acquired, priorMtime } = tryAcquireLock(baseDir, { lockFilename: LOCK_FILENAME });
+  if (!acquired) {
+    escribirTelemetria(baseDir, {
+      ts: momento.toISOString(),
+      origen: 'ciclo-fase-b',
+      dryRun,
+      razon: RAZONES.LOCK_OCUPADO,
+      candidatos_considerados: 0,
+    });
+    return { ejecutado: false, razon: RAZONES.LOCK_OCUPADO };
+  }
+
+  const cfg = config.leerConfig(baseDir);
+
+  if (!tocaCatchUp(cfg.last_run_fase_b, momento)) {
+    return diferir(baseDir, { momento, dryRun, priorMtime, razon: RAZONES.SIN_CATCHUP });
+  }
+
+  const deteccion = candidatos.detectar(baseDir, { ahora: momento });
+  if (deteccion.total === 0) {
+    return diferir(baseDir, { momento, dryRun, priorMtime, razon: RAZONES.SIN_CANDIDATOS });
+  }
+
+  const guard = guardConvivencia.evaluar({ detector: detectorProcesos });
+  if (guard.diferir) {
+    return diferir(baseDir, {
+      momento, dryRun, priorMtime, razon: guard.razon, candidatosConsiderados: deteccion.total,
+    });
+  }
+
+  const credencial = verificarCredencial(cfg, verificadorCredencial);
+  if (!credencial.ok) {
+    return diferir(baseDir, {
+      momento, dryRun, priorMtime, razon: credencial.razon, candidatosConsiderados: deteccion.total,
+    });
+  }
+
+  const gasto = presupuesto.puedeGastar(baseDir, 0, { ahora: momento });
+  if (!gasto.permitido) {
+    return diferir(baseDir, {
+      momento, dryRun, priorMtime, razon: gasto.razon, candidatosConsiderados: deteccion.total,
+    });
+  }
+
+  const candidatosAProcesar = deteccion.candidatos.slice(0, cfg.tope_mutaciones_corrida);
+
+  if (!dryRun && typeof invocador !== 'function') {
+    return diferir(baseDir, {
+      momento, dryRun, priorMtime, razon: RAZONES.INVOCADOR_NO_DISPONIBLE,
+      candidatosConsiderados: candidatosAProcesar.length,
+    });
+  }
+
+  if (!dryRun) {
+    try {
+      invocador(candidatosAProcesar, { baseDir, ahora: momento });
+    } catch (_) {
+      return diferir(baseDir, {
+        momento, dryRun, priorMtime, razon: RAZONES.INVOCADOR_FALLO,
+        candidatosConsiderados: candidatosAProcesar.length,
+      });
+    }
+  }
+
+  // dry-run feliz o corrida real exitosa: el catch-up se considera cumplido.
+  presupuesto.registrarGasto(baseDir, 0, { ahora: momento });
+  config.escribirConfig(baseDir, { last_run_fase_b: fechaHoraLocal(momento) });
+  liberarLock(baseDir);
+
+  escribirTelemetria(baseDir, {
+    ts: momento.toISOString(),
+    origen: 'ciclo-fase-b',
+    dryRun,
+    resultado: 'ok',
+    candidatos_considerados: candidatosAProcesar.length,
+  });
+
+  return { ejecutado: true, dryRun, candidatos: candidatosAProcesar.length };
+}
+
+module.exports = { correrFaseB, RAZONES };