@saulwade/swl-ses 2.6.0 → 2.8.0

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

@@ -1,301 +1,301 @@
-'use strict';
-
-/**
- * index.js — Orquestador Fase A del ciclo autónomo (Fase 21, T-07,
- * ADR-0041/0042, REQ-21-02/REQ-21-09). Compone las tres sub-fases
- * deterministas bajo opt-out estricto (nace encendido; el off es sagrado), con lock de exclusión mutua propio
- * (T-02) y telemetría no-op-aware.
- *
- * Orden de composición: writer-instintos → puente-degradacion →
- * drenador-feedback. El writer corre primero porque sus transiciones
- * (promoción/degradación por decay o harmful_ratio) son la fuente primaria
- * de scoring de `instintos/proyecto.yaml`. El puente corre ANTES que el
- * drenador para que las degradaciones del día detectadas en APRENDIZAJES.md
- * (que bajan confidence de instintos derivados) ya queden reflejadas en el
- * YAML antes de que el drenador consolide señales nuevas de
- * `perfil-usuario.yaml` en esta misma corrida.
- *
- * Cada sub-fase corre en su propio try/catch: una falla no aborta las
- * otras — se acumula en `errores[]` con el nombre de la sub-fase.
- *
- * Opt-OUT estricto (regla de negocio 1 de la Fase 21, reformulada 2026-07-10
- * por decisión del usuario — el motor nace encendido): este orquestador es el
- * ÚNICO punto que consulta `config.estaHabilitado()` — las libs de sub-fase
- * son puras y no consultan config.
- *
- * Fase 22 (T-06, REQ-22-06): al final de una corrida CON acciones (nunca en
- * un no-op — el detector no debe pagar su costo cuando no hubo nada que
- * hacer), detecta candidatos a Fase B (`candidatos.detectar`) y, si hay ≥1
- * nuevo y `estaFaseBHabilitada`, spawnea el runner headless como proceso
- * detached fire-and-forget (`stdio:'ignore'` + `unref`, NUNCA `execSync` —
- * dictamen PM3, `scheduler.js:126` bloquearía otros jobs). El spawner es
- * inyectable (`opts.spawner`) para tests deterministas sin procesos reales;
- * el default resuelve el CLI de Fase B con `require.resolve` tolerante
- * (ausente en el destino ⇒ no spawnea, nunca crashea). El spawn NUNCA
- * bloquea ni espera, y cualquier error se traga con razón registrada — el
- * hook/CLI padre no debe morir por esto. La detección SIEMPRE corre en la
- * rama con acciones (aunque Fase B esté apagada) porque el conteo de
- * candidatos va a la telemetría igual.
- *
- * Zero-deps, CommonJS.
- *
- * @module scripts/lib/ciclo-autonomo/index
- */
-
-const fs = require('fs');
-const path = require('path');
-const { spawn } = require('child_process');
-
-const config = require('./config');
-const lock = require('./lock');
-const writerInstintos = require('./writer-instintos');
-const drenadorFeedback = require('./drenador-feedback');
-const puenteDegradacion = require('./puente-degradacion');
-const higieneNudges = require('./higiene-nudges');
-const candidatos = require('./candidatos');
-
-/** Razones de no-ejecución expuestas para consumo de tests/CLI. */
-const RAZONES = Object.freeze({
-  DESHABILITADO: 'deshabilitado',
-  LOCK_OCUPADO: 'lock ocupado',
-});
-
-const RUTA_TELEMETRIA_RELATIVA = path.join('evolution', 'ciclo-autonomo.jsonl');
-
-function rutaTelemetria(baseDir) {
-  return path.join(baseDir, '.planning', RUTA_TELEMETRIA_RELATIVA);
-}
-
-function contadoresVacios() {
-  return {
-    promovidos: 0, degradados: 0, archivados: 0, candidatosGlobal: 0,
-    bajados: 0, drenados: 0, archivadosCola: 0, descartados: 0,
-    nudgesAtendidos: 0, nudgesArchivados: 0,
-  };
-}
-
-/** Ejecuta una sub-fase con try/catch propio; una falla se acumula en errores[] sin abortar. */
-function correrSubFase(nombre, fn, errores) {
-  try {
-    return fn();
-  } catch (_err) {
-    errores.push(nombre);
-    return null;
-  }
-}
-
-/** Fecha-hora local legible ("YYYY-MM-DD HH:mm:ss") — NUNCA toISOString (gate C1). */
-function fechaHoraLocal(momento) {
-  return `${momento.toLocaleDateString('sv')} ${momento.toLocaleTimeString('sv')}`;
-}
-
-/** Suma las tres sub-fases en los totales acumulados de la corrida. */
-function acumularSubFases(baseDir, momento, errores) {
-  const totales = contadoresVacios();
-
-  const resWriter = correrSubFase(
-    'writer-instintos',
-    () => writerInstintos.aplicarTransiciones(baseDir, { ahora: momento }),
-    errores
-  );
-  if (resWriter) {
-    totales.promovidos += resWriter.promovidos;
-    totales.degradados += resWriter.degradados;
-    totales.archivados += resWriter.archivados;
-    totales.candidatosGlobal += resWriter.candidatosGlobal;
-  }
-
-  const resPuente = correrSubFase(
-    'puente-degradacion',
-    () => puenteDegradacion.puentear(baseDir, { ahora: momento }),
-    errores
-  );
-  if (resPuente) totales.bajados += resPuente.bajados;
-
-  const resDrenador = correrSubFase(
-    'drenador-feedback',
-    () => drenadorFeedback.drenar(baseDir, { ahora: momento }),
-    errores
-  );
-  if (resDrenador) {
-    totales.drenados += resDrenador.drenados;
-    totales.archivadosCola += resDrenador.archivados;
-    totales.descartados += resDrenador.descartados;
-  }
-
-  // Higiene del ciclo de nudges (T-09/REQ-21-05 y REQ-21-13): si el drenador
-  // consolidó señales al perfil, los nudges `perfil-usuario` pendientes quedan
-  // atendidos por el ciclo; los nudges sin accionar más viejos que la ventana
-  // se archivan sin procesar (misma ventana de 90 días del bootstrap).
-  const resHigiene = correrSubFase('higiene-nudges', () => {
-    const atendidos = totales.drenados > 0
-      ? higieneNudges.marcarAccionado(baseDir, { kinds: ['perfil-usuario'], por: 'ciclo-autonomo', ahora: momento })
-      : { marcados: 0 };
-    const viejos = higieneNudges.archivarViejos(baseDir, { ahora: momento });
-    return { atendidos: atendidos.marcados, archivados: viejos.archivados };
-  }, errores);
-  if (resHigiene) {
-    totales.nudgesAtendidos += resHigiene.atendidos;
-    totales.nudgesArchivados += resHigiene.archivados;
-  }
-
-  return totales;
-}
-
-/** Total de acciones que decide si la corrida es no-op (candidatosGlobal y descartados NO cuentan). */
-function totalAcciones(totales) {
-  return totales.promovidos + totales.degradados + totales.archivados
-    + totales.bajados + totales.drenados + totales.archivadosCola
-    + totales.nudgesAtendidos + totales.nudgesArchivados;
-}
-
-/**
- * Resuelve la ruta del CLI de Fase B (`scripts/cli/ciclo-fase-b.js`, T-07)
- * con `require.resolve` tolerante — ausente en este destino (p.ej. antes de
- * que T-07 lo registre, o un downstream que no distribuye `scripts/cli/`)
- * ⇒ `null`, nunca crashea.
- */
-function resolverRutaCliFaseB() {
-  try {
-    return require.resolve('../../cli/ciclo-fase-b');
-  } catch (err) {
-    if (err && err.code !== 'MODULE_NOT_FOUND') throw err;
-    return null;
-  }
-}
-
-/**
- * Spawner por defecto del runner de Fase B: proceso detached fire-and-forget
- * (`stdio:'ignore'` + `unref`) — NUNCA `execSync` (dictamen PM3,
- * `scheduler.js:126` bloquearía otros jobs). Si el CLI no resuelve en este
- * destino, no spawnea y registra la razón en vez de crashear.
- */
-function spawnerFaseBPorDefecto(baseDir) {
-  const rutaCli = resolverRutaCliFaseB();
-  if (!rutaCli) return { spawneado: false, razon: 'cli-no-resuelve' };
-
-  const hijo = spawn(process.execPath, [rutaCli, '--dry-run'], {
-    cwd: baseDir,
-    detached: true,
-    stdio: 'ignore',
-  });
-  hijo.unref();
-  return { spawneado: true, pid: hijo.pid };
-}
-
-/**
- * Detecta candidatos a Fase B y, si hay nuevos y Fase B está habilitada,
- * spawnea el runner headless. La detección SIEMPRE corre en este punto (para
- * que el conteo llegue a telemetría aunque Fase B esté apagada); el spawn se
- * traga cualquier error del `spawner` (inyectado o por defecto) sin
- * propagarlo — el orquestador de Fase A nunca debe morir por esto.
- *
- * @param {string} baseDir
- * @param {Date} momento
- * @param {Function} [spawner] - Inyectable para tests; default: proceso real.
- * @returns {{candidatosNuevos: number, faseBSpawneada: boolean}}
- */
-function intentarSpawnFaseB(baseDir, momento, spawner) {
-  const deteccion = candidatos.detectar(baseDir, { ahora: momento });
-  const candidatosNuevos = deteccion.nuevos;
-
-  if (candidatosNuevos < 1 || !config.estaFaseBHabilitada(baseDir)) {
-    return { candidatosNuevos, faseBSpawneada: false };
-  }
-
-  const spawnearFn = typeof spawner === 'function' ? spawner : spawnerFaseBPorDefecto;
-  let resultado;
-  try {
-    resultado = spawnearFn(baseDir);
-  } catch (_err) {
-    // El spawn NUNCA debe tumbar al proceso padre (hook/CLI): se traga el error.
-    resultado = { spawneado: false, razon: 'spawn-lanzo-error' };
-  }
-
-  return { candidatosNuevos, faseBSpawneada: Boolean(resultado && resultado.spawneado) };
-}
-
-/** Append de una entrada de telemetría a `.planning/evolution/ciclo-autonomo.jsonl`. */
-function escribirTelemetria(baseDir, totales, errores, faseB) {
-  const ruta = rutaTelemetria(baseDir);
-  const dir = path.dirname(ruta);
-  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
-
-  const entrada = {
-    ts: new Date().toISOString(), // telemetría de evento puntual — no fecha de artefacto (gate C1 no aplica)
-    origen: 'ciclo-autonomo',
-    promovidos: totales.promovidos,
-    degradados: totales.degradados,
-    archivados: totales.archivados,
-    candidatosGlobal: totales.candidatosGlobal,
-    bajados: totales.bajados,
-    drenados: totales.drenados,
-    archivadosCola: totales.archivadosCola,
-    descartados: totales.descartados,
-    nudgesAtendidos: totales.nudgesAtendidos,
-    nudgesArchivados: totales.nudgesArchivados,
-    candidatosNuevos: faseB.candidatosNuevos,
-    faseBSpawneada: faseB.faseBSpawneada,
-    errores,
-  };
-  fs.appendFileSync(ruta, JSON.stringify(entrada) + '\n');
-}
-
-/**
- * Corre la Fase A del ciclo autónomo sobre `baseDir`.
- *
- * @param {string} baseDir - Directorio raíz del proyecto.
- * @param {{ahora?: Date, forzar?: boolean, spawner?: Function}} [opciones]
- *   `spawner` es inyectable (T-06, REQ-22-06): reemplaza el spawn real del
- *   runner de Fase B en tests deterministas.
- * @returns {object} `{ejecutado:false, razon}` si no corrió;
- *   `{ejecutado:true, acciones:0}` si no-op; o el detalle completo de la
- *   corrida (totales + `errores[]` + `candidatosNuevos` + `faseBSpawneada`)
- *   si hubo al menos una acción.
- */
-function correrFaseA(baseDir, { ahora, forzar = false, spawner } = {}) {
-  if (!config.estaHabilitado(baseDir) && !forzar) {
-    return { ejecutado: false, razon: RAZONES.DESHABILITADO };
-  }
-
-  const momento = ahora || new Date();
-  const { acquired, priorMtime } = lock.adquirir(baseDir);
-  if (!acquired) {
-    return { ejecutado: false, razon: RAZONES.LOCK_OCUPADO };
-  }
-
-  try {
-    const errores = [];
-    const totales = acumularSubFases(baseDir, momento, errores);
-    const acciones = totalAcciones(totales);
-
-    if (acciones === 0 && errores.length === 0) {
-      // NO-OP: la corrida no cuenta como última corrida real.
-      lock.rollback(baseDir, priorMtime);
-      return { ejecutado: true, acciones: 0 };
-    }
-
-    const resultadoFaseB = intentarSpawnFaseB(baseDir, momento, spawner);
-
-    escribirTelemetria(baseDir, totales, errores, resultadoFaseB);
-    config.escribirConfig(baseDir, {
-      last_run: fechaHoraLocal(momento),
-      ultima_corrida: {
-        promovidos: totales.promovidos,
-        degradados: totales.degradados,
-        drenados: totales.drenados,
-        archivados: totales.archivadosCola,
-        bajados: totales.bajados,
-      },
-    });
-    lock.liberar(baseDir);
-
-    return { ejecutado: true, acciones, ...totales, errores, ...resultadoFaseB };
-  } catch (err) {
-    // Error catastrófico fuera de las sub-fases: revertir el lock y relanzar.
-    lock.rollback(baseDir, priorMtime);
-    throw err;
-  }
-}
-
-module.exports = { correrFaseA, RAZONES };
+'use strict';
+
+/**
+ * index.js — Orquestador Fase A del ciclo autónomo (Fase 21, T-07,
+ * ADR-0041/0042, REQ-21-02/REQ-21-09). Compone las tres sub-fases
+ * deterministas bajo opt-out estricto (nace encendido; el off es sagrado), con lock de exclusión mutua propio
+ * (T-02) y telemetría no-op-aware.
+ *
+ * Orden de composición: writer-instintos → puente-degradacion →
+ * drenador-feedback. El writer corre primero porque sus transiciones
+ * (promoción/degradación por decay o harmful_ratio) son la fuente primaria
+ * de scoring de `instintos/proyecto.yaml`. El puente corre ANTES que el
+ * drenador para que las degradaciones del día detectadas en APRENDIZAJES.md
+ * (que bajan confidence de instintos derivados) ya queden reflejadas en el
+ * YAML antes de que el drenador consolide señales nuevas de
+ * `perfil-usuario.yaml` en esta misma corrida.
+ *
+ * Cada sub-fase corre en su propio try/catch: una falla no aborta las
+ * otras — se acumula en `errores[]` con el nombre de la sub-fase.
+ *
+ * Opt-OUT estricto (regla de negocio 1 de la Fase 21, reformulada 2026-07-10
+ * por decisión del usuario — el motor nace encendido): este orquestador es el
+ * ÚNICO punto que consulta `config.estaHabilitado()` — las libs de sub-fase
+ * son puras y no consultan config.
+ *
+ * Fase 22 (T-06, REQ-22-06): al final de una corrida CON acciones (nunca en
+ * un no-op — el detector no debe pagar su costo cuando no hubo nada que
+ * hacer), detecta candidatos a Fase B (`candidatos.detectar`) y, si hay ≥1
+ * nuevo y `estaFaseBHabilitada`, spawnea el runner headless como proceso
+ * detached fire-and-forget (`stdio:'ignore'` + `unref`, NUNCA `execSync` —
+ * dictamen PM3, `scheduler.js:126` bloquearía otros jobs). El spawner es
+ * inyectable (`opts.spawner`) para tests deterministas sin procesos reales;
+ * el default resuelve el CLI de Fase B con `require.resolve` tolerante
+ * (ausente en el destino ⇒ no spawnea, nunca crashea). El spawn NUNCA
+ * bloquea ni espera, y cualquier error se traga con razón registrada — el
+ * hook/CLI padre no debe morir por esto. La detección SIEMPRE corre en la
+ * rama con acciones (aunque Fase B esté apagada) porque el conteo de
+ * candidatos va a la telemetría igual.
+ *
+ * Zero-deps, CommonJS.
+ *
+ * @module scripts/lib/ciclo-autonomo/index
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { spawn } = require('child_process');
+
+const config = require('./config');
+const lock = require('./lock');
+const writerInstintos = require('./writer-instintos');
+const drenadorFeedback = require('./drenador-feedback');
+const puenteDegradacion = require('./puente-degradacion');
+const higieneNudges = require('./higiene-nudges');
+const candidatos = require('./candidatos');
+
+/** Razones de no-ejecución expuestas para consumo de tests/CLI. */
+const RAZONES = Object.freeze({
+  DESHABILITADO: 'deshabilitado',
+  LOCK_OCUPADO: 'lock ocupado',
+});
+
+const RUTA_TELEMETRIA_RELATIVA = path.join('evolution', 'ciclo-autonomo.jsonl');
+
+function rutaTelemetria(baseDir) {
+  return path.join(baseDir, '.planning', RUTA_TELEMETRIA_RELATIVA);
+}
+
+function contadoresVacios() {
+  return {
+    promovidos: 0, degradados: 0, archivados: 0, candidatosGlobal: 0,
+    bajados: 0, drenados: 0, archivadosCola: 0, descartados: 0,
+    nudgesAtendidos: 0, nudgesArchivados: 0,
+  };
+}
+
+/** Ejecuta una sub-fase con try/catch propio; una falla se acumula en errores[] sin abortar. */
+function correrSubFase(nombre, fn, errores) {
+  try {
+    return fn();
+  } catch (_err) {
+    errores.push(nombre);
+    return null;
+  }
+}
+
+/** Fecha-hora local legible ("YYYY-MM-DD HH:mm:ss") — NUNCA toISOString (gate C1). */
+function fechaHoraLocal(momento) {
+  return `${momento.toLocaleDateString('sv')} ${momento.toLocaleTimeString('sv')}`;
+}
+
+/** Suma las tres sub-fases en los totales acumulados de la corrida. */
+function acumularSubFases(baseDir, momento, errores) {
+  const totales = contadoresVacios();
+
+  const resWriter = correrSubFase(
+    'writer-instintos',
+    () => writerInstintos.aplicarTransiciones(baseDir, { ahora: momento }),
+    errores
+  );
+  if (resWriter) {
+    totales.promovidos += resWriter.promovidos;
+    totales.degradados += resWriter.degradados;
+    totales.archivados += resWriter.archivados;
+    totales.candidatosGlobal += resWriter.candidatosGlobal;
+  }
+
+  const resPuente = correrSubFase(
+    'puente-degradacion',
+    () => puenteDegradacion.puentear(baseDir, { ahora: momento }),
+    errores
+  );
+  if (resPuente) totales.bajados += resPuente.bajados;
+
+  const resDrenador = correrSubFase(
+    'drenador-feedback',
+    () => drenadorFeedback.drenar(baseDir, { ahora: momento }),
+    errores
+  );
+  if (resDrenador) {
+    totales.drenados += resDrenador.drenados;
+    totales.archivadosCola += resDrenador.archivados;
+    totales.descartados += resDrenador.descartados;
+  }
+
+  // Higiene del ciclo de nudges (T-09/REQ-21-05 y REQ-21-13): si el drenador
+  // consolidó señales al perfil, los nudges `perfil-usuario` pendientes quedan
+  // atendidos por el ciclo; los nudges sin accionar más viejos que la ventana
+  // se archivan sin procesar (misma ventana de 90 días del bootstrap).
+  const resHigiene = correrSubFase('higiene-nudges', () => {
+    const atendidos = totales.drenados > 0
+      ? higieneNudges.marcarAccionado(baseDir, { kinds: ['perfil-usuario'], por: 'ciclo-autonomo', ahora: momento })
+      : { marcados: 0 };
+    const viejos = higieneNudges.archivarViejos(baseDir, { ahora: momento });
+    return { atendidos: atendidos.marcados, archivados: viejos.archivados };
+  }, errores);
+  if (resHigiene) {
+    totales.nudgesAtendidos += resHigiene.atendidos;
+    totales.nudgesArchivados += resHigiene.archivados;
+  }
+
+  return totales;
+}
+
+/** Total de acciones que decide si la corrida es no-op (candidatosGlobal y descartados NO cuentan). */
+function totalAcciones(totales) {
+  return totales.promovidos + totales.degradados + totales.archivados
+    + totales.bajados + totales.drenados + totales.archivadosCola
+    + totales.nudgesAtendidos + totales.nudgesArchivados;
+}
+
+/**
+ * Resuelve la ruta del CLI de Fase B (`scripts/cli/ciclo-fase-b.js`, T-07)
+ * con `require.resolve` tolerante — ausente en este destino (p.ej. antes de
+ * que T-07 lo registre, o un downstream que no distribuye `scripts/cli/`)
+ * ⇒ `null`, nunca crashea.
+ */
+function resolverRutaCliFaseB() {
+  try {
+    return require.resolve('../../cli/ciclo-fase-b');
+  } catch (err) {
+    if (err && err.code !== 'MODULE_NOT_FOUND') throw err;
+    return null;
+  }
+}
+
+/**
+ * Spawner por defecto del runner de Fase B: proceso detached fire-and-forget
+ * (`stdio:'ignore'` + `unref`) — NUNCA `execSync` (dictamen PM3,
+ * `scheduler.js:126` bloquearía otros jobs). Si el CLI no resuelve en este
+ * destino, no spawnea y registra la razón en vez de crashear.
+ */
+function spawnerFaseBPorDefecto(baseDir) {
+  const rutaCli = resolverRutaCliFaseB();
+  if (!rutaCli) return { spawneado: false, razon: 'cli-no-resuelve' };
+
+  const hijo = spawn(process.execPath, [rutaCli, '--dry-run'], {
+    cwd: baseDir,
+    detached: true,
+    stdio: 'ignore',
+  });
+  hijo.unref();
+  return { spawneado: true, pid: hijo.pid };
+}
+
+/**
+ * Detecta candidatos a Fase B y, si hay nuevos y Fase B está habilitada,
+ * spawnea el runner headless. La detección SIEMPRE corre en este punto (para
+ * que el conteo llegue a telemetría aunque Fase B esté apagada); el spawn se
+ * traga cualquier error del `spawner` (inyectado o por defecto) sin
+ * propagarlo — el orquestador de Fase A nunca debe morir por esto.
+ *
+ * @param {string} baseDir
+ * @param {Date} momento
+ * @param {Function} [spawner] - Inyectable para tests; default: proceso real.
+ * @returns {{candidatosNuevos: number, faseBSpawneada: boolean}}
+ */
+function intentarSpawnFaseB(baseDir, momento, spawner) {
+  const deteccion = candidatos.detectar(baseDir, { ahora: momento });
+  const candidatosNuevos = deteccion.nuevos;
+
+  if (candidatosNuevos < 1 || !config.estaFaseBHabilitada(baseDir)) {
+    return { candidatosNuevos, faseBSpawneada: false };
+  }
+
+  const spawnearFn = typeof spawner === 'function' ? spawner : spawnerFaseBPorDefecto;
+  let resultado;
+  try {
+    resultado = spawnearFn(baseDir);
+  } catch (_err) {
+    // El spawn NUNCA debe tumbar al proceso padre (hook/CLI): se traga el error.
+    resultado = { spawneado: false, razon: 'spawn-lanzo-error' };
+  }
+
+  return { candidatosNuevos, faseBSpawneada: Boolean(resultado && resultado.spawneado) };
+}
+
+/** Append de una entrada de telemetría a `.planning/evolution/ciclo-autonomo.jsonl`. */
+function escribirTelemetria(baseDir, totales, errores, faseB) {
+  const ruta = rutaTelemetria(baseDir);
+  const dir = path.dirname(ruta);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+  const entrada = {
+    ts: new Date().toISOString(), // telemetría de evento puntual — no fecha de artefacto (gate C1 no aplica)
+    origen: 'ciclo-autonomo',
+    promovidos: totales.promovidos,
+    degradados: totales.degradados,
+    archivados: totales.archivados,
+    candidatosGlobal: totales.candidatosGlobal,
+    bajados: totales.bajados,
+    drenados: totales.drenados,
+    archivadosCola: totales.archivadosCola,
+    descartados: totales.descartados,
+    nudgesAtendidos: totales.nudgesAtendidos,
+    nudgesArchivados: totales.nudgesArchivados,
+    candidatosNuevos: faseB.candidatosNuevos,
+    faseBSpawneada: faseB.faseBSpawneada,
+    errores,
+  };
+  fs.appendFileSync(ruta, JSON.stringify(entrada) + '\n');
+}
+
+/**
+ * Corre la Fase A del ciclo autónomo sobre `baseDir`.
+ *
+ * @param {string} baseDir - Directorio raíz del proyecto.
+ * @param {{ahora?: Date, forzar?: boolean, spawner?: Function}} [opciones]
+ *   `spawner` es inyectable (T-06, REQ-22-06): reemplaza el spawn real del
+ *   runner de Fase B en tests deterministas.
+ * @returns {object} `{ejecutado:false, razon}` si no corrió;
+ *   `{ejecutado:true, acciones:0}` si no-op; o el detalle completo de la
+ *   corrida (totales + `errores[]` + `candidatosNuevos` + `faseBSpawneada`)
+ *   si hubo al menos una acción.
+ */
+function correrFaseA(baseDir, { ahora, forzar = false, spawner } = {}) {
+  if (!config.estaHabilitado(baseDir) && !forzar) {
+    return { ejecutado: false, razon: RAZONES.DESHABILITADO };
+  }
+
+  const momento = ahora || new Date();
+  const { acquired, priorMtime } = lock.adquirir(baseDir);
+  if (!acquired) {
+    return { ejecutado: false, razon: RAZONES.LOCK_OCUPADO };
+  }
+
+  try {
+    const errores = [];
+    const totales = acumularSubFases(baseDir, momento, errores);
+    const acciones = totalAcciones(totales);
+
+    if (acciones === 0 && errores.length === 0) {
+      // NO-OP: la corrida no cuenta como última corrida real.
+      lock.rollback(baseDir, priorMtime);
+      return { ejecutado: true, acciones: 0 };
+    }
+
+    const resultadoFaseB = intentarSpawnFaseB(baseDir, momento, spawner);
+
+    escribirTelemetria(baseDir, totales, errores, resultadoFaseB);
+    config.escribirConfig(baseDir, {
+      last_run: fechaHoraLocal(momento),
+      ultima_corrida: {
+        promovidos: totales.promovidos,
+        degradados: totales.degradados,
+        drenados: totales.drenados,
+        archivados: totales.archivadosCola,
+        bajados: totales.bajados,
+      },
+    });
+    lock.liberar(baseDir);
+
+    return { ejecutado: true, acciones, ...totales, errores, ...resultadoFaseB };
+  } catch (err) {
+    // Error catastrófico fuera de las sub-fases: revertir el lock y relanzar.
+    lock.rollback(baseDir, priorMtime);
+    throw err;
+  }
+}
+
+module.exports = { correrFaseA, RAZONES };