@saulwade/swl-ses 2.5.2 → 2.6.0

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

package/scripts/lib/ciclo-autonomo/guard-convivencia.js

@@ -0,0 +1,139 @@
+'use strict';
+
+/**
+ * guard-convivencia.js — Guard de convivencia con una sesión interactiva de
+ * Claude Code en la misma máquina (Fase 22, T-03, REQ-22-02).
+ *
+ * El runner headless de Fase B (`runner-fase-b.js`, T-05) NUNCA debe competir
+ * por recursos/rate-limit con un usuario trabajando en una sesión interactiva.
+ * Este módulo detecta si hay un proceso con imagen `claude` corriendo:
+ * `tasklist /FO CSV /NH` en win32, `ps -eo comm=` en POSIX.
+ *
+ * El `detector` es INYECTABLE — una función sin argumentos que devuelve la
+ * salida cruda del listado de procesos (string) o lanza. Los tests SIEMPRE
+ * inyectan el detector; nunca se spawnea un proceso real en la suite. El
+ * detector por defecto usa `child_process.spawnSync` con un timeout corto
+ * (2s) para que un binario colgado nunca bloquee el runner.
+ *
+ * Semántica CONSERVADORA (dictamen adversarial, supuesto 2 del CONTEXTO):
+ * proceso `claude` presente → diferir; ausente → no diferir; CUALQUIER fallo
+ * de detección (spawn falla, binario ausente, timeout, salida ilegible) →
+ * diferir también. Un falso positivo (diferir de más) es aceptable; competir
+ * con un usuario interactivo no lo es. El guard NUNCA lanza hacia el caller.
+ *
+ * LIMITACIÓN DOCUMENTADA (fase dry-run, F22 no la resuelve): el detector
+ * matchea por NOMBRE de imagen de proceso, no por árbol de PIDs. Si el propio
+ * runner (headless, `node`) fuese lanzado como hijo de un proceso `claude`
+ * padre (p. ej. invocado manualmente desde dentro de una sesión interactiva),
+ * este guard lo tomaría como sesión interactiva activa y diferiría — no hay
+ * forma de distinguir "mi propio ancestro" de "otra sesión del usuario" sin
+ * caminar el árbol de procesos por PID/PPID, algo que el CONTEXTO de esta fase
+ * no exige y el plan no especifica. El proceso `node` del propio runner NUNCA
+ * cuenta como match (solo se busca la imagen `claude`), pero un ancestro
+ * `claude` sí produce el mismo diferir que una sesión ajena. F24 (ciclo con
+ * mutaciones reales) es quien debe afinar esta distinción si el patrón de
+ * disparo cambia (p. ej. invocación manual desde dentro de una sesión).
+ *
+ * Zero-deps, CommonJS.
+ *
+ * @module scripts/lib/ciclo-autonomo/guard-convivencia
+ */
+
+const { spawnSync } = require('child_process');
+
+/** Timeout del spawn de detección — nunca debe colgar el runner headless. */
+const TIMEOUT_MS = 2000;
+
+/** Nombre de imagen de proceso que identifica una sesión interactiva. */
+const NOMBRE_PROCESO = 'claude';
+
+/**
+ * Resuelve el comando de listado de procesos según la plataforma. Puro y
+ * exportado para poder verificar la selección win32/POSIX en tests sin
+ * spawnear nada real.
+ *
+ * @param {string} plataforma - Típicamente `process.platform`.
+ * @returns {{cmd: string, args: string[]}}
+ */
+function resolverComando(plataforma) {
+  if (plataforma === 'win32') {
+    return { cmd: 'tasklist', args: ['/FO', 'CSV', '/NH'] };
+  }
+  return { cmd: 'ps', args: ['-eo', 'comm='] };
+}
+
+/**
+ * Detector por defecto: spawnSync del listado de procesos de la plataforma.
+ * Lanza si el spawn falla, sale con código distinto de 0, o no produce una
+ * salida de texto utilizable — el caller (`evaluar`) trata cualquier lanzamiento
+ * como fallo de detección conservador.
+ *
+ * @param {string} plataforma
+ * @returns {string} Salida cruda del comando.
+ */
+function detectorPorDefecto(plataforma) {
+  const { cmd, args } = resolverComando(plataforma);
+  const resultado = spawnSync(cmd, args, { timeout: TIMEOUT_MS, encoding: 'utf8' });
+
+  if (!resultado || resultado.error || resultado.status !== 0 || typeof resultado.stdout !== 'string') {
+    throw new Error(`guard-convivencia: "${cmd}" no produjo salida utilizable`);
+  }
+
+  return resultado.stdout;
+}
+
+/**
+ * `true` si la salida cruda del listado de procesos contiene una imagen
+ * `claude` (case-insensitive; matchea tanto `claude` como `claude.exe` en
+ * una línea CSV de tasklist o en la salida de `ps -eo comm=`).
+ *
+ * @param {string} salidaCruda
+ * @returns {boolean}
+ */
+function contieneProcesoClaude(salidaCruda) {
+  return salidaCruda
+    .split(/\r?\n/)
+    .some((linea) => linea.toLowerCase().includes(NOMBRE_PROCESO));
+}
+
+/**
+ * `true` si hay una sesión interactiva de Claude Code corriendo, según el
+ * detector inyectado (o el detector por defecto para la plataforma dada).
+ * Lanza si la detección falla — `evaluar` es quien decide el fallback
+ * conservador; esta función expone el booleano crudo.
+ *
+ * @param {{detector?: () => string, plataforma?: string}} [opciones]
+ * @returns {boolean}
+ */
+function haySesionInteractiva({ detector, plataforma = process.platform } = {}) {
+  const salidaCruda = detector ? detector() : detectorPorDefecto(plataforma);
+  if (typeof salidaCruda !== 'string') {
+    throw new Error('guard-convivencia: el detector no devolvió una salida de texto');
+  }
+  return contieneProcesoClaude(salidaCruda);
+}
+
+/**
+ * Evalúa si el runner de Fase B debe diferirse por convivencia con una
+ * sesión interactiva. NUNCA lanza — cualquier error de detección se
+ * convierte en `{diferir:true, razon:'deteccion-fallida'}` (conservador).
+ *
+ * @param {{detector?: () => string, plataforma?: string}} [opciones]
+ * @returns {{diferir: boolean, razon?: string}}
+ */
+function evaluar({ detector, plataforma } = {}) {
+  let activa;
+  try {
+    activa = haySesionInteractiva({ detector, plataforma });
+  } catch (_) {
+    return { diferir: true, razon: 'deteccion-fallida' };
+  }
+
+  if (activa) {
+    return { diferir: true, razon: 'sesion-interactiva' };
+  }
+
+  return { diferir: false };
+}
+
+module.exports = { evaluar, haySesionInteractiva, resolverComando };

package/scripts/lib/ciclo-autonomo/higiene-nudges.js

@@ -0,0 +1,112 @@
+'use strict';
+
+/**
+ * Higiene del ciclo de nudges (T-09, Fase 21 — ADR-0041).
+ *
+ * Opera sobre `.planning/evolution/nudges.jsonl` con formato compatible con
+ * `hooks/lib/nudge-tracker.js` ({id, kind, target, ts, accionado,
+ * accionado_ts, accionado_por}), pero con `baseDir` inyectable — el tracker
+ * fija sus rutas al cwd del require y no sirve para el motor ni para tests
+ * en sandbox.
+ *
+ *   - marcarAccionado(baseDir, {id | kinds, por, ahora}) → {marcados}
+ *   - archivarViejos(baseDir, {ahora, dias=90})          → {archivados}
+ *
+ * Zero-deps. Reescritura completa vía atomic-write; líneas con schema viejo
+ * o corruptas se conservan intactas (nunca se pierden por higiene).
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { atomicWriteSync } = require('../../../hooks/lib/atomic-write');
+
+const DIAS_VENTANA_DEFAULT = 90;
+
+function rutaNudges(baseDir) {
+  return path.join(baseDir, '.planning', 'evolution', 'nudges.jsonl');
+}
+
+function rutaArchive(baseDir) {
+  return path.join(baseDir, '.planning', 'evolution', 'nudges.archive.jsonl');
+}
+
+// Lee el JSONL preservando las líneas crudas: las que no parsean se devuelven
+// con `nudge: null` para reescribirlas tal cual (tolerancia sin pérdida).
+function leerLineas(baseDir) {
+  const ruta = rutaNudges(baseDir);
+  if (!fs.existsSync(ruta)) return null;
+  return fs
+    .readFileSync(ruta, 'utf8')
+    .split('\n')
+    .filter((l) => l.trim() !== '')
+    .map((cruda) => {
+      try {
+        return { cruda, nudge: JSON.parse(cruda) };
+      } catch {
+        return { cruda, nudge: null };
+      }
+    });
+}
+
+function escribirLineas(baseDir, lineas) {
+  const contenido = lineas.map((l) => l.cruda).join('\n') + (lineas.length ? '\n' : '');
+  atomicWriteSync(rutaNudges(baseDir), contenido, 'utf8');
+}
+
+/**
+ * Marca nudges como accionados, por `id` exacto o por lista de `kinds`
+ * (solo los aún no accionados). Nunca pisa un `accionado_por` previo.
+ */
+function marcarAccionado(baseDir, { id, kinds, por = 'desconocido', ahora = new Date() } = {}) {
+  const lineas = leerLineas(baseDir);
+  if (!lineas) return { marcados: 0 };
+
+  let marcados = 0;
+  for (const linea of lineas) {
+    const n = linea.nudge;
+    if (!n || n.accionado === true) continue;
+    const porId = id != null && n.id === id;
+    const porKind = Array.isArray(kinds) && kinds.includes(n.kind);
+    if (!porId && !porKind) continue;
+
+    n.accionado = true;
+    n.accionado_ts = ahora.toISOString();
+    n.accionado_por = por;
+    linea.cruda = JSON.stringify(n);
+    marcados++;
+  }
+
+  if (marcados > 0) escribirLineas(baseDir, lineas);
+  return { marcados };
+}
+
+/**
+ * Mueve al archive los nudges SIN accionar con `ts` más viejo que la ventana.
+ * Los nudges sin `ts` parseable y las líneas corruptas se conservan activos
+ * (mejor conservar de más que archivar señal viva).
+ */
+function archivarViejos(baseDir, { ahora = new Date(), dias = DIAS_VENTANA_DEFAULT } = {}) {
+  const lineas = leerLineas(baseDir);
+  if (!lineas) return { archivados: 0 };
+
+  const limiteMs = ahora.getTime() - dias * 24 * 3600 * 1000;
+  const activos = [];
+  const archivados = [];
+
+  for (const linea of lineas) {
+    const n = linea.nudge;
+    const tsMs = n && n.ts ? Date.parse(n.ts) : NaN;
+    const esViejoSinAccionar = n && n.accionado !== true && Number.isFinite(tsMs) && tsMs < limiteMs;
+    (esViejoSinAccionar ? archivados : activos).push(linea);
+  }
+
+  if (archivados.length > 0) {
+    const bloque = archivados.map((l) => l.cruda).join('\n') + '\n';
+    fs.appendFileSync(rutaArchive(baseDir), bloque, 'utf8');
+    escribirLineas(baseDir, activos);
+  }
+
+  return { archivados: archivados.length };
+}
+
+module.exports = { marcarAccionado, archivarViejos, DIAS_VENTANA_DEFAULT };