@saulwade/swl-ses 2.6.0 → 2.6.1

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

@@ -1,248 +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 };
+'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 };