@saulwade/swl-ses 2.5.2 → 2.6.0

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

@@ -0,0 +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 };

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

@@ -0,0 +1,124 @@
+'use strict';
+
+/**
+ * Lock propio del ciclo autónomo — envuelve `hooks/lib/consolidation-lock.js`
+ * con lockfile dedicado `.ciclo-autonomo-lock` en `.planning/` (Fase 21,
+ * T-02). Garantiza exclusión mutua entre el scheduler cron y el fallback de
+ * `session-briefing` (REQ-21-11, T-11) sin compartir el lockfile de
+ * auto-consolidación (`.consolidation-lock`) — corridas concurrentes de
+ * ambos motores no se bloquean entre sí.
+ *
+ * Diferencia deliberada frente al patrón original: `liberar()` SÍ libera el
+ * mutex de inmediato (borra el lockfile) en vez de solo tocar su mtime. El
+ * módulo original está pensado para un daemon de sesión donde "liberar"
+ * significa "marcar el mtime como última corrida exitosa" y el siguiente
+ * intento normalmente lo hace un proceso nuevo (PID distinto, el anterior ya
+ * murió). El ciclo autónomo, en cambio, corre como invocación CLI de un solo
+ * tiro (`swl-ses ciclo-autonomo`) y el guard de "mínimo 24h entre corridas"
+ * lo evalúa el caller (T-11, fallback de `session-briefing`) leyendo
+ * `ultimaCorridaMs()` — no el propio lock. Por eso "última corrida" se
+ * persiste aparte, en el marcador `.planning/evolution/.ciclo-last-run`
+ * (epoch ms en texto plano), en vez de reusar el mtime del lockfile: si
+ * reusáramos el mtime, `liberar()` no podría borrar el archivo sin perder
+ * ese dato.
+ *
+ * Zero-deps, CommonJS.
+ *
+ * @module scripts/lib/ciclo-autonomo/lock
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const {
+  tryAcquireLock,
+  rollbackLock,
+  lockPath,
+} = require('../../../hooks/lib/consolidation-lock');
+const { atomicWriteSync } = require('../../../hooks/lib/atomic-write');
+
+/** Nombre del lockfile propio del ciclo (independiente del de auto-consolidación). */
+const LOCK_FILENAME = '.ciclo-autonomo-lock';
+
+/** Ruta relativa del marcador de última corrida exitosa (epoch ms). */
+const MARCADOR_RELATIVO = path.join('evolution', '.ciclo-last-run');
+
+/**
+ * Ruta absoluta del marcador de última corrida.
+ *
+ * @param {string} baseDir - Directorio raíz del proyecto.
+ * @returns {string}
+ */
+function rutaMarcador(baseDir) {
+  return path.join(baseDir, '.planning', MARCADOR_RELATIVO);
+}
+
+/**
+ * Intenta adquirir el lock del ciclo autónomo.
+ *
+ * @param {string} baseDir - Directorio raíz del proyecto.
+ * @returns {{ acquired: boolean, priorMtime: number }}
+ */
+function adquirir(baseDir) {
+  return tryAcquireLock(baseDir, { lockFilename: LOCK_FILENAME });
+}
+
+/**
+ * Libera el lock tras una corrida exitosa: borra el lockfile (mutex libre de
+ * inmediato) y registra el epoch ms de la corrida en el marcador de última
+ * corrida. El marcador es best-effort — un fallo al escribirlo no debe
+ * tumbar el ciclo (ya completó su trabajo real).
+ *
+ * @param {string} baseDir - Directorio raíz del proyecto.
+ */
+function liberar(baseDir) {
+  const lp = lockPath(baseDir, { lockFilename: LOCK_FILENAME });
+  try {
+    fs.unlinkSync(lp);
+  } catch {
+    // Ya no existía o no se pudo borrar — no bloqueante.
+  }
+
+  try {
+    atomicWriteSync(rutaMarcador(baseDir), String(Date.now()), 'utf8');
+  } catch {
+    // Best-effort: el marcador no es crítico para la corrida ya completada.
+  }
+}
+
+/**
+ * Revierte el lock tras una corrida fallida o no-op: restaura el mtime
+ * previo (o borra el lockfile si no existía antes de adquirir). NO toca el
+ * marcador de última corrida — una corrida fallida/no-op no cuenta como
+ * "última corrida".
+ *
+ * @param {string} baseDir - Directorio raíz del proyecto.
+ * @param {number} priorMtime - Epoch ms devuelto por `adquirir()`.
+ */
+function rollback(baseDir, priorMtime) {
+  rollbackLock(baseDir, priorMtime, { lockFilename: LOCK_FILENAME });
+}
+
+/**
+ * Epoch ms de la última corrida exitosa registrada por `liberar()`.
+ *
+ * @param {string} baseDir - Directorio raíz del proyecto.
+ * @returns {number|null} Epoch ms, o `null` si nunca hubo una corrida.
+ */
+function ultimaCorridaMs(baseDir) {
+  try {
+    const crudo = fs.readFileSync(rutaMarcador(baseDir), 'utf8').trim();
+    const ms = Number(crudo);
+    return Number.isFinite(ms) ? ms : null;
+  } catch {
+    return null;
+  }
+}
+
+module.exports = {
+  adquirir,
+  liberar,
+  rollback,
+  ultimaCorridaMs,
+  LOCK_FILENAME,
+};

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 };