@saulwade/swl-ses 2.3.0 → 2.4.1

package/hooks/lib/etapa-auto-evolucion.js

@@ -1,701 +1,701 @@
-#!/usr/bin/env node
-'use strict';
-
-/**
- * Hook: auto-evolucion.js
- * Tipo: SubagentStop (async: true — fire-and-forget)
- *
- * Registra la terminación de cada subagente SWL en un log JSONL y, cuando
- * un mismo agente acumula suficientes señales de baja calidad o alta fricción,
- * emite un nudge por stderr sugiriendo invocar /swl:evolucionar.
- *
- * Señales registradas por agente:
- *   - status:failed          — el agente terminó con error
- *   - trivial                — ≤5 tool calls (se descarta del análisis)
- *   - tool_calls             — número de tool calls totales
- *   - duracion_ms            — tiempo de ejecución
- *   - tipo_fallo             — clasificación del fallo (AGP Reflect, Zhang 2026 §3.2.2)
- *                              uno de: bad_output_format, tool_error, timeout,
- *                              schema_violation, task_incomplete, unknown
- *
- * Umbrales (configurables vía env):
- *   SWL_AUTOEVOL_FALLOS      (default 3)   — fallos en 14 días → nudge
- *   SWL_AUTOEVOL_RUNS        (default 10)  — corridas en 14 días → sugerir revisión
- *   SWL_AUTOEVOL_THROTTLE_H  (default 24)  — horas entre nudges del mismo agente
- *   SWL_DRIFT_THROTTLE_H     (default 24)  — horas entre chequeos globales de drift
- *   SWL_DRIFT_DISABLED=1                   — desactiva por completo el drift-detector
- *
- * El hook nunca bloquea (siempre exit 0). Zero-dependencies.
- * NO invoca agentes — solo registra y sugiere.
- *
- * convergence-detector (REC-D03): invocado en cada SubagentStop cuando hay ≥6
- * invocaciones de herramienta en las trazas del día para el agente actual.
- * Emite un nudge tipo 'loop' independiente del gate de fallos/volumen.
- *
- * drift-detector (REC-D07): invocado con throttle propio (SWL_DRIFT_THROTTLE_H)
- * sobre los últimos JSONL de trazas. Opt-out via SWL_DRIFT_DISABLED=1.
- *
- * @see hooks/auto-consolidacion.js  (patrón anti-spam con flag)
- * @see agentes/auto-evolucion-swl.md (agente que se invoca tras el nudge)
- */
-
-const fs   = require('fs');
-const path = require('path');
-
-// Escritura atómica obligatoria para estado mutable (regla CLAUDE.md).
-// Fallback defensivo si el módulo no existe en el destino.
-let atomicWriteJSON;
-try {
-  ({ atomicWriteJSON } = require('./atomic-write'));
-} catch {
-  atomicWriteJSON = (p, obj) => fs.writeFileSync(p, JSON.stringify(obj, null, 2), 'utf8');
-}
-
-let nudgeTracker;
-try {
-  nudgeTracker = require('./nudge-tracker');
-} catch {
-  nudgeTracker = null;
-}
-
-let reflect;
-try {
-  reflect = require('./reflect-classifier');
-} catch {
-  reflect = null;
-}
-
-let convergenceDetector;
-try {
-  convergenceDetector = require('./convergence-detector');
-} catch {
-  convergenceDetector = null;
-}
-
-let driftDetector;
-try {
-  driftDetector = require('../scripts/lib/drift-detector');
-} catch {
-  driftDetector = null;
-}
-
-let agentRouting;
-try {
-  agentRouting = require('./agent-routing');
-} catch {
-  agentRouting = null;
-}
-
-let singletonGuard;
-try {
-  singletonGuard = require('./singleton-guard');
-} catch {
-  singletonGuard = null;
-}
-
-// ---------------------------------------------------------------------------
-// Configuración
-// ---------------------------------------------------------------------------
-
-const UMBRAL_FALLOS        = parseInt(process.env.SWL_AUTOEVOL_FALLOS     || '3',  10);
-const UMBRAL_RUNS          = parseInt(process.env.SWL_AUTOEVOL_RUNS       || '10', 10);
-const THROTTLE_HORAS       = parseInt(process.env.SWL_AUTOEVOL_THROTTLE_H || '24', 10);
-const DRIFT_THROTTLE_HORAS = parseInt(process.env.SWL_DRIFT_THROTTLE_H    || '24', 10);
-const VENTANA_DIAS         = 14;
-const MIN_TOOL_CALLS       = 5;   // por debajo se considera trivial
-const MIN_INVOCACIONES_LOOP = 6;  // mínimo para que el ratio de convergencia sea significativo
-
-const DIR_AUTOEVOL  = path.join(process.cwd(), '.planning', 'auto-evolution');
-const DIR_TRACES    = path.join(process.cwd(), '.planning', 'traces');
-const LOG_PATH      = path.join(DIR_AUTOEVOL, 'agentes.jsonl');
-const NUDGES_PATH   = path.join(DIR_AUTOEVOL, 'nudges.json');
-
-// ---------------------------------------------------------------------------
-// Utilidades de filesystem (zero-deps)
-// ---------------------------------------------------------------------------
-
-function ensureDir(dir) {
-  try { fs.mkdirSync(dir, { recursive: true }); } catch { /* ignore */ }
-}
-
-function append(obj) {
-  ensureDir(DIR_AUTOEVOL);
-  try {
-    fs.appendFileSync(LOG_PATH, JSON.stringify(obj) + '\n', 'utf8');
-  } catch { /* ignore */ }
-}
-
-function leerNudges() {
-  try {
-    return JSON.parse(fs.readFileSync(NUDGES_PATH, 'utf8'));
-  } catch {
-    return {};
-  }
-}
-
-function escribirNudges(obj) {
-  ensureDir(DIR_AUTOEVOL);
-  try {
-    atomicWriteJSON(NUDGES_PATH, obj);
-  } catch { /* ignore */ }
-}
-
-/**
- * Lee las últimas N entradas del JSONL (sin cargar todo si es grande).
- * Para el tamaño esperado (log de agentes) una lectura simple es suficiente.
- */
-function leerLog() {
-  try {
-    const raw = fs.readFileSync(LOG_PATH, 'utf8');
-    return raw
-      .split(/\r?\n/)
-      .filter(Boolean)
-      .map(l => { try { return JSON.parse(l); } catch { return null; } })
-      .filter(Boolean);
-  } catch {
-    return [];
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Clasificador de tipo_fallo — vive en hooks/lib/reflect-classifier.js
-// (AGP Reflect, Zhang 2026 §3.2.2)
-// ---------------------------------------------------------------------------
-
-function clasificarTipoFallo(data, response) {
-  if (reflect) return reflect.clasificarTipoFallo(data, response);
-  return null; // fallback silencioso: si falta el modulo, el hook no bloquea
-}
-
-// ---------------------------------------------------------------------------
-// Análisis de payload de SubagentStop
-// ---------------------------------------------------------------------------
-
-/**
- * Extrae la info relevante del payload que Claude Code pasa al hook.
- * Campos esperados (best-effort; varían según harness):
- *   - session_id
- *   - tool_name (= "Agent")
- *   - tool_input.subagent_type  (ej. "implementador-swl")
- *   - tool_response / tool_result
- *   - duration_ms (si el harness lo provee)
- */
-function analizarPayload(data) {
-  const toolName = String(data.tool_name || data.tool?.name || '');
-  if (toolName !== 'Agent') return null;
-
-  const subagentType =
-    data.tool_input?.subagent_type ||
-    data.tool?.input?.subagent_type ||
-    data.subagent_type ||
-    'desconocido';
-
-  // Solo trackeamos agentes SWL (los demás no tenemos potestad de evolucionar)
-  if (!/-swl$/.test(subagentType)) return null;
-
-  const response = data.tool_response || data.tool_result || {};
-  const status = response.is_error || response.status === 'failed' ? 'failed' : 'success';
-
-  // Número de tool calls — lo estimamos por longitud de mensajes si está disponible
-  const mensajes = response.messages || response.mensajes || [];
-  const toolCalls = Array.isArray(mensajes)
-    ? mensajes.filter(m => m && (m.type === 'tool_use' || m.role === 'tool')).length
-    : 0;
-
-  const duracionMs =
-    data.duration_ms ||
-    response.duration_ms ||
-    response.uso?.duration_ms ||
-    null;
-
-  const tipoFallo = status === 'failed'
-    ? clasificarTipoFallo(data, response)
-    : null;
-
-  // Inferir fase/dominio del frontmatter del agente para routing precision
-  // (ADR 0012). Si el agente no tiene frontmatter o no se encuentra el archivo,
-  // los campos quedan null y la métrica simplemente no cuenta esa entrada.
-  let routedPhase = null;
-  let routedDomain = null;
-  let routingSource = 'unknown';
-  if (agentRouting) {
-    try {
-      const r = agentRouting.getRouting(subagentType);
-      routedPhase   = r.fase;
-      routedDomain  = r.dominio;
-      routingSource = r.source;
-    } catch { /* no bloquear por fallo en routing inference */ }
-  }
-
-  return {
-    ts: new Date().toISOString(),
-    sessionId: String(data.session_id || 'default'),
-    agente: subagentType,
-    status,
-    toolCalls,
-    trivial: toolCalls > 0 && toolCalls < MIN_TOOL_CALLS,
-    duracionMs,
-    tipo_fallo: tipoFallo,
-    routed_phase:   routedPhase,
-    routed_domain:  routedDomain,
-    routing_source: routingSource,
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Gates para emitir nudge
-// ---------------------------------------------------------------------------
-
-function filtrarVentana(entradas, dias) {
-  const limite = Date.now() - dias * 24 * 3600 * 1000;
-  return entradas.filter(e => {
-    const t = Date.parse(e.ts);
-    return Number.isFinite(t) && t >= limite;
-  });
-}
-
-function resumenPorAgente(entradasVentana) {
-  const resumen = {};
-  for (const e of entradasVentana) {
-    if (!resumen[e.agente]) {
-      resumen[e.agente] = { runs: 0, fallos: 0, triviales: 0, fallos_por_tipo: {} };
-    }
-    const r = resumen[e.agente];
-    if (e.trivial) r.triviales++;
-    else {
-      r.runs++;
-      if (e.status === 'failed') {
-        r.fallos++;
-        const tipo = e.tipo_fallo || 'unknown';
-        r.fallos_por_tipo[tipo] = (r.fallos_por_tipo[tipo] || 0) + 1;
-      }
-    }
-  }
-  return resumen;
-}
-
-/**
- * Determina el tipo_fallo dominante y retorna un diagnóstico estructurado
- * listo para propagar al nudge. Delega al módulo reflect-classifier.
- */
-function construirDiagnosis(resumenAgente) {
-  if (reflect) return reflect.construirDiagnosis(resumenAgente);
-  return null;
-}
-
-function debeEmitirNudge(agente, resumen, nudges) {
-  const r = resumen[agente];
-  if (!r) return null;
-
-  const ultimoNudge = nudges[agente];
-  if (ultimoNudge) {
-    const horas = (Date.now() - Date.parse(ultimoNudge)) / 3600000;
-    if (horas < THROTTLE_HORAS) return null;
-  }
-
-  if (r.fallos >= UMBRAL_FALLOS) {
-    return {
-      razon: 'fallos',
-      detalle: `${r.fallos} fallos en ${VENTANA_DIAS} días`,
-    };
-  }
-  if (r.runs >= UMBRAL_RUNS) {
-    return {
-      razon: 'volumen',
-      detalle: `${r.runs} corridas no triviales en ${VENTANA_DIAS} días`,
-    };
-  }
-  return null;
-}
-
-// ---------------------------------------------------------------------------
-// Convergence detector — gate de loop (REC-D03)
-// ---------------------------------------------------------------------------
-
-/**
- * Lee las invocaciones de herramienta del agente desde los JSONL de trazas.
- *
- * El formato nativo de otlp-exporter es:
- *   { traceId, spanId, nombre, inicio, fin, duracionMs, estado, atributos }
- * donde `nombre` es tipo "agent:nombre-swl" o "skill:nombre-skill".
- *
- * Retorna array de { tool: string } compatible con calcularScoreConvergencia.
- * Nunca lanza — retorna [] ante cualquier falla.
- *
- * @param {string} agente       - Nombre del agente SWL (sin prefijo, ej: "implementador-swl")
- * @param {number} [diasAtras]  - Cuántos días de traces revisar (1 = solo hoy, 2 = hoy y ayer)
- * @returns {Array<{tool: string}>}
- */
-function leerInvocacionesDelAgente(agente, diasAtras = 1) {
-  const invocaciones = [];
-  try {
-    const ahora = new Date();
-    for (let i = 0; i < diasAtras; i++) {
-      const fecha = new Date(ahora.getTime() - i * 24 * 3600 * 1000)
-        .toISOString()
-        .slice(0, 10);
-      const rutaJsonl = path.join(DIR_TRACES, `${fecha}.jsonl`);
-      if (!fs.existsSync(rutaJsonl)) continue;
-
-      let contenido;
-      try {
-        contenido = fs.readFileSync(rutaJsonl, 'utf8');
-      } catch {
-        continue;
-      }
-
-      const lineas = contenido.split(/\r?\n/).filter(Boolean);
-      for (const linea of lineas) {
-        let evento;
-        try {
-          evento = JSON.parse(linea);
-        } catch {
-          continue;
-        }
-
-        // El campo nombre puede ser "agent:nombre-swl", "skill:nombre", etc.
-        // Filtramos eventos asociados al agente actual.
-        const nombre = String(evento.nombre || '');
-        const esDelAgente =
-          nombre === `agent:${agente}` ||
-          nombre.includes(agente) ||
-          (evento.atributos?.agente === agente) ||
-          (evento.atributos?.agent === agente);
-
-        if (!esDelAgente) continue;
-
-        // Extraemos el nombre del tool/skill del evento como la herramienta invocada.
-        // En el formato OTLP-lite el "tool" es el nombre del span.
-        const tool = nombre || 'unknown';
-        invocaciones.push({ tool });
-      }
-    }
-  } catch {
-    // Fallback silencioso — el hook no debe crashear por traces inexistentes
-  }
-  return invocaciones;
-}
-
-/**
- * Determina si hay throttle activo para el nudge de loop del agente.
- *
- * Usa la clave "<agente>::loop" en el objeto nudges con el mismo
- * throttle configurado en THROTTLE_HORAS.
- *
- * @param {string} agente
- * @param {object} nudges
- * @returns {boolean} true si debe omitir el nudge de loop
- */
-function estaThrottledLoop(agente, nudges) {
-  const clave = `${agente}::loop`;
-  const ultimo = nudges[clave];
-  if (!ultimo) return false;
-  const horas = (Date.now() - Date.parse(ultimo)) / 3600000;
-  return horas < THROTTLE_HORAS;
-}
-
-// ---------------------------------------------------------------------------
-// Drift detector automático (REC-D07)
-// ---------------------------------------------------------------------------
-
-/**
- * Retorna las rutas de los últimos N archivos JSONL de traces ordenados
- * por fecha descendente (más reciente primero).
- *
- * @param {number} [max=5]
- * @returns {string[]}
- */
-function rutasTracesRecientes(max) {
-  const n = max || 5;
-  try {
-    if (!fs.existsSync(DIR_TRACES)) return [];
-    const archivos = fs.readdirSync(DIR_TRACES)
-      .filter(f => /^\d{4}-\d{2}-\d{2}\.jsonl$/.test(f))
-      .sort()
-      .reverse()
-      .slice(0, n);
-    return archivos.map(f => path.join(DIR_TRACES, f));
-  } catch {
-    return [];
-  }
-}
-
-/**
- * Ejecuta el drift-detector de forma automática con throttle propio.
- *
- * Respeta la clave "__drift__::global" en el objeto nudges para evitar
- * correr en cada invocación de subagente (sería costoso).
- *
- * Opt-out completo con SWL_DRIFT_DISABLED=1.
- *
- * @param {object} nudges  - Objeto de nudges leído de disco (se muta in-place)
- */
-function ejecutarDriftAutomatico(nudges) {
-  if (process.env.SWL_DRIFT_DISABLED === '1') return;
-  if (!driftDetector) return;
-
-  // Throttle: no correr si ya se corrió en las últimas DRIFT_THROTTLE_HORAS
-  const claveThrottle = '__drift__::global';
-  const ultimoDrift = nudges[claveThrottle];
-  if (ultimoDrift) {
-    const horas = (Date.now() - Date.parse(ultimoDrift)) / 3600000;
-    if (horas < DRIFT_THROTTLE_HORAS) return;
-  }
-
-  // Actualizar throttle inmediatamente para que invocaciones concurrentes no dupliquen
-  nudges[claveThrottle] = new Date().toISOString();
-
-  try {
-    const rutas = rutasTracesRecientes(5);
-    if (rutas.length === 0) return;
-
-    // Usar la traza más reciente como fuente principal de drift.
-    // detectarDrift acepta una sola rutaJsonl — pasamos el archivo más reciente.
-    const resultado = driftDetector.detectarDrift({
-      rutaJsonl: rutas[0],
-      ventanaDias: 7,
-      baselineSemanasBase: 4,
-      umbralPct: 10,
-    });
-
-    if (!resultado) return;
-    if (resultado.estado_global !== 'warn' && resultado.estado_global !== 'critico') return;
-
-    // Filtrar solo las métricas que driftearon
-    const driftsSig = (resultado.drifts || []).filter(d => d.estado !== 'ok');
-    if (driftsSig.length === 0) return;
-
-    // Emitir nudge por stderr
-    const lineasDrift = driftsSig.map(d =>
-      `    • ${d.metrica}: ${d.driftPct > 0 ? '+' : ''}${d.driftPct}% (${d.estado})`
-    );
-    const mensajeDrift = [
-      '',
-      `[auto-evolución] Drift detectado en trazas de agentes (estado: ${resultado.estado_global}).`,
-      '  Métricas con variación significativa:',
-      ...lineasDrift,
-      '  Considera revisar el ciclo de evolución:',
-      '    /swl:evolucionar',
-      '',
-    ].join('\n');
-    process.stderr.write(mensajeDrift);
-
-    // Registrar en nudge-tracker
-    if (nudgeTracker) {
-      try {
-        // Drift crítico → repair/high; drift warn → repair/medium
-        const esCritico = resultado.estado_global === 'critico';
-        nudgeTracker.emit({
-          kind: 'drift-detectado',
-          target: '__global__',
-          message: mensajeDrift.trim(),
-          source: 'hooks/auto-evolucion.js',
-          mutation_category: 'repair',
-          risk_level: esCritico ? 'high' : 'medium',
-          data: {
-            estado_global: resultado.estado_global,
-            drifts: driftsSig,
-          },
-        });
-      } catch { /* silencioso */ }
-    }
-
-  } catch {
-    // Fallback silencioso — el drift no debe bloquear el hook principal
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Entrypoint
-// ---------------------------------------------------------------------------
-
-/**
- * Etapa de auto-evolución del ciclo (sub-etapa de hooks/ciclo-evolucion-subagente.js).
- * Consume el payload de SubagentStop. Best-effort: nunca lanza al caller.
- * @param {string} inputRaw payload JSON del evento SubagentStop
- */
-function ejecutar(inputRaw) {
-  // Singleton guard: si otra instancia está corriendo (poco probable en
-  // SubagentStop pero posible con eventos concurrentes), salir silenciosamente.
-  // Lock stale tras 5 min (la etapa normalmente corre en < 1s).
-  if (singletonGuard && !singletonGuard.adquirir('auto-evolucion', { staleMs: 300000 })) {
-    return;
-  }
-
-  try {
-    const data = JSON.parse(inputRaw);
-    const entrada = analizarPayload(data);
-    if (!entrada) { if (singletonGuard) singletonGuard.liberar('auto-evolucion'); return; }
-
-    // 1. Registrar en el log JSONL
-    append(entrada);
-
-    // 2. Si fue trivial, no analizamos nudges
-    if (entrada.trivial) { if (singletonGuard) singletonGuard.liberar('auto-evolucion'); return; }
-
-    // 3. Cargar histórico en ventana y evaluar gates
-    const historico = leerLog();
-    const ventana   = filtrarVentana(historico, VENTANA_DIAS);
-    const resumen   = resumenPorAgente(ventana);
-
-    const nudges  = leerNudges();
-    const decision = debeEmitirNudge(entrada.agente, resumen, nudges);
-
-    // 4. Gate de loop (convergence-detector, REC-D03)
-    let loopInfo = null;
-    if (convergenceDetector) {
-      try {
-        const invocaciones = leerInvocacionesDelAgente(entrada.agente, 1);
-        if (invocaciones.length >= MIN_INVOCACIONES_LOOP) {
-          loopInfo = convergenceDetector.detectarLoop({ invocaciones });
-        }
-      } catch { /* fallback silencioso */ }
-    }
-
-    // Mapeo razón → (mutation_category, risk_level) según Evolver GEP.
-    // repair: corrige regresión observable; optimize: mejora sin bug; innovate: capacidad nueva.
-    const clasificarRazon = (razon) => {
-      if (razon === 'fallos' || razon === 'loop') return { mutation_category: 'repair', risk_level: 'high' };
-      if (razon === 'volumen') return { mutation_category: 'optimize', risk_level: 'medium' };
-      if (razon === 'drift') return { mutation_category: 'repair', risk_level: 'medium' };
-      return { mutation_category: undefined, risk_level: undefined };
-    };
-
-    // 5. Emitir nudge de loop si aplica (gate independiente del de fallos/volumen)
-    if (loopInfo?.estaEnLoop && !estaThrottledLoop(entrada.agente, nudges)) {
-      const mensajeLoop = [
-        '',
-        `[auto-evolución] Posible loop detectado en "${entrada.agente}".`,
-        `  Ratio calls/tools: ${Math.round(loopInfo.ratio * 100) / 100}  (umbral ${loopInfo.umbralUsado})`,
-        `  Invocaciones: ${loopInfo.totalCalls}  Tools únicos: ${loopInfo.uniqueTools}`,
-        `  Considera revisar el diseño del agente:`,
-        `    /swl:evolucionar ${entrada.agente}`,
-        '',
-      ].join('\n');
-
-      process.stderr.write(mensajeLoop);
-
-      // Registrar throttle del loop por separado
-      nudges[`${entrada.agente}::loop`] = new Date().toISOString();
-
-      if (nudgeTracker) {
-        try {
-          const clasif = clasificarRazon('loop');
-          nudgeTracker.emit({
-            kind: 'auto-evolucion',
-            target: entrada.agente,
-            message: mensajeLoop.trim(),
-            source: 'hooks/auto-evolucion.js',
-            mutation_category: clasif.mutation_category,
-            risk_level: clasif.risk_level,
-            data: {
-              razon: 'loop',
-              ratio: loopInfo.ratio,
-              totalCalls: loopInfo.totalCalls,
-              uniqueTools: loopInfo.uniqueTools,
-              umbralUsado: loopInfo.umbralUsado,
-            },
-          });
-        } catch { /* silencioso */ }
-      }
-    }
-
-    // 6. Si no hay decision de nudge principal, pasar al drift y salir
-    if (!decision) {
-      escribirNudges(nudges);
-      ejecutarDriftAutomatico(nudges);
-      escribirNudges(nudges);
-      if (singletonGuard) singletonGuard.liberar('auto-evolucion');
-      return;
-    }
-
-    // 7. Construir diagnosis semántico (AGP Reflect)
-    const diagnosis = construirDiagnosis(resumen[entrada.agente]);
-
-    // 8. Emitir nudge principal (stderr, visible al modelo como contexto)
-    const lineas = [
-      '',
-      `[auto-evolución] Agente "${entrada.agente}" acumuló señales para evolución.`,
-      `  Motivo: ${decision.razon} — ${decision.detalle}.`,
-    ];
-    if (diagnosis) {
-      lineas.push(`  Tipo de fallo dominante: ${diagnosis.tipo_fallo} (${diagnosis.conteo_dominante}/${diagnosis.total_fallos} fallos).`);
-      lineas.push(`  Hipotesis de mejora: ${diagnosis.hint_mejora}.`);
-    }
-    // Incluir info de loop en el nudge principal si también está activo
-    if (loopInfo?.estaEnLoop) {
-      lineas.push(`  Además: loop detectado (ratio ${Math.round(loopInfo.ratio * 100) / 100}, umbral ${loopInfo.umbralUsado}).`);
-    }
-    lineas.push(`  Considera invocar:`);
-    lineas.push(`    /swl:evolucionar ${entrada.agente}`);
-    lineas.push(`  (o el agente auto-evolucion-swl con foco en "${entrada.agente}")`);
-    lineas.push('');
-    const mensaje = lineas.join('\n');
-    process.stderr.write(mensaje);
-
-    // 9. Registrar timestamp del nudge para throttle
-    nudges[entrada.agente] = new Date().toISOString();
-    escribirNudges(nudges);
-
-    // 10. Registrar en nudge-tracker para medir tasa de acción
-    if (nudgeTracker) {
-      try {
-        const clasif = clasificarRazon(decision.razon);
-        nudgeTracker.emit({
-          kind: 'auto-evolucion',
-          target: entrada.agente,
-          message: mensaje.trim(),
-          source: 'hooks/auto-evolucion.js',
-          mutation_category: clasif.mutation_category,
-          risk_level: clasif.risk_level,
-          data: {
-            razon:     decision.razon,
-            detalle:   decision.detalle,
-            diagnosis,
-            loop:      loopInfo?.estaEnLoop ? loopInfo : null,
-          },
-        });
-      } catch { /* silencioso */ }
-    }
-
-    // 11. Drift automático (REC-D07) al final
-    ejecutarDriftAutomatico(nudges);
-    escribirNudges(nudges);
-
-  } catch (err) {
-    // Nunca bloquea, pero deja traza diagnóstica para no perder
-    // regresiones silenciosas en el ciclo de auto-evolución.
-    process.stderr.write(`[auto-evolucion] error interno: ${String(err.message || err).slice(0, 120)}\n`);
-  } finally {
-    if (singletonGuard) singletonGuard.liberar('auto-evolucion');
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Exports
-// ---------------------------------------------------------------------------
-
-module.exports = {
-  ejecutar,
-  leerInvocacionesDelAgente,
-  ejecutarDriftAutomatico,
-  estaThrottledLoop,
-  rutasTracesRecientes,
-  // Exponer para tests de integración completos
-  _internals: {
-    analizarPayload,
-    filtrarVentana,
-    resumenPorAgente,
-    debeEmitirNudge,
-    construirDiagnosis,
-  },
-};
-
-// Ejecución directa (compat: sigue invocable standalone para diagnóstico).
-// Los listeners de stdin solo se registran en modo CLI para no colgar el
-// event loop cuando el módulo se importa desde tests.
-if (require.main === module) {
-  let inputRaw = '';
-  process.stdin.on('data', chunk => { inputRaw += chunk; });
-  process.stdin.on('end', () => ejecutar(inputRaw));
-}
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Hook: auto-evolucion.js
+ * Tipo: SubagentStop (async: true — fire-and-forget)
+ *
+ * Registra la terminación de cada subagente SWL en un log JSONL y, cuando
+ * un mismo agente acumula suficientes señales de baja calidad o alta fricción,
+ * emite un nudge por stderr sugiriendo invocar /swl:evolucionar.
+ *
+ * Señales registradas por agente:
+ *   - status:failed          — el agente terminó con error
+ *   - trivial                — ≤5 tool calls (se descarta del análisis)
+ *   - tool_calls             — número de tool calls totales
+ *   - duracion_ms            — tiempo de ejecución
+ *   - tipo_fallo             — clasificación del fallo (AGP Reflect, Zhang 2026 §3.2.2)
+ *                              uno de: bad_output_format, tool_error, timeout,
+ *                              schema_violation, task_incomplete, unknown
+ *
+ * Umbrales (configurables vía env):
+ *   SWL_AUTOEVOL_FALLOS      (default 3)   — fallos en 14 días → nudge
+ *   SWL_AUTOEVOL_RUNS        (default 10)  — corridas en 14 días → sugerir revisión
+ *   SWL_AUTOEVOL_THROTTLE_H  (default 24)  — horas entre nudges del mismo agente
+ *   SWL_DRIFT_THROTTLE_H     (default 24)  — horas entre chequeos globales de drift
+ *   SWL_DRIFT_DISABLED=1                   — desactiva por completo el drift-detector
+ *
+ * El hook nunca bloquea (siempre exit 0). Zero-dependencies.
+ * NO invoca agentes — solo registra y sugiere.
+ *
+ * convergence-detector (REC-D03): invocado en cada SubagentStop cuando hay ≥6
+ * invocaciones de herramienta en las trazas del día para el agente actual.
+ * Emite un nudge tipo 'loop' independiente del gate de fallos/volumen.
+ *
+ * drift-detector (REC-D07): invocado con throttle propio (SWL_DRIFT_THROTTLE_H)
+ * sobre los últimos JSONL de trazas. Opt-out via SWL_DRIFT_DISABLED=1.
+ *
+ * @see hooks/auto-consolidacion.js  (patrón anti-spam con flag)
+ * @see agentes/auto-evolucion-swl.md (agente que se invoca tras el nudge)
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+// Escritura atómica obligatoria para estado mutable (regla CLAUDE.md).
+// Fallback defensivo si el módulo no existe en el destino.
+let atomicWriteJSON;
+try {
+  ({ atomicWriteJSON } = require('./atomic-write'));
+} catch {
+  atomicWriteJSON = (p, obj) => fs.writeFileSync(p, JSON.stringify(obj, null, 2), 'utf8');
+}
+
+let nudgeTracker;
+try {
+  nudgeTracker = require('./nudge-tracker');
+} catch {
+  nudgeTracker = null;
+}
+
+let reflect;
+try {
+  reflect = require('./reflect-classifier');
+} catch {
+  reflect = null;
+}
+
+let convergenceDetector;
+try {
+  convergenceDetector = require('./convergence-detector');
+} catch {
+  convergenceDetector = null;
+}
+
+let driftDetector;
+try {
+  driftDetector = require('../scripts/lib/drift-detector');
+} catch {
+  driftDetector = null;
+}
+
+let agentRouting;
+try {
+  agentRouting = require('./agent-routing');
+} catch {
+  agentRouting = null;
+}
+
+let singletonGuard;
+try {
+  singletonGuard = require('./singleton-guard');
+} catch {
+  singletonGuard = null;
+}
+
+// ---------------------------------------------------------------------------
+// Configuración
+// ---------------------------------------------------------------------------
+
+const UMBRAL_FALLOS        = parseInt(process.env.SWL_AUTOEVOL_FALLOS     || '3',  10);
+const UMBRAL_RUNS          = parseInt(process.env.SWL_AUTOEVOL_RUNS       || '10', 10);
+const THROTTLE_HORAS       = parseInt(process.env.SWL_AUTOEVOL_THROTTLE_H || '24', 10);
+const DRIFT_THROTTLE_HORAS = parseInt(process.env.SWL_DRIFT_THROTTLE_H    || '24', 10);
+const VENTANA_DIAS         = 14;
+const MIN_TOOL_CALLS       = 5;   // por debajo se considera trivial
+const MIN_INVOCACIONES_LOOP = 6;  // mínimo para que el ratio de convergencia sea significativo
+
+const DIR_AUTOEVOL  = path.join(process.cwd(), '.planning', 'auto-evolution');
+const DIR_TRACES    = path.join(process.cwd(), '.planning', 'traces');
+const LOG_PATH      = path.join(DIR_AUTOEVOL, 'agentes.jsonl');
+const NUDGES_PATH   = path.join(DIR_AUTOEVOL, 'nudges.json');
+
+// ---------------------------------------------------------------------------
+// Utilidades de filesystem (zero-deps)
+// ---------------------------------------------------------------------------
+
+function ensureDir(dir) {
+  try { fs.mkdirSync(dir, { recursive: true }); } catch { /* ignore */ }
+}
+
+function append(obj) {
+  ensureDir(DIR_AUTOEVOL);
+  try {
+    fs.appendFileSync(LOG_PATH, JSON.stringify(obj) + '\n', 'utf8');
+  } catch { /* ignore */ }
+}
+
+function leerNudges() {
+  try {
+    return JSON.parse(fs.readFileSync(NUDGES_PATH, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function escribirNudges(obj) {
+  ensureDir(DIR_AUTOEVOL);
+  try {
+    atomicWriteJSON(NUDGES_PATH, obj);
+  } catch { /* ignore */ }
+}
+
+/**
+ * Lee las últimas N entradas del JSONL (sin cargar todo si es grande).
+ * Para el tamaño esperado (log de agentes) una lectura simple es suficiente.
+ */
+function leerLog() {
+  try {
+    const raw = fs.readFileSync(LOG_PATH, 'utf8');
+    return raw
+      .split(/\r?\n/)
+      .filter(Boolean)
+      .map(l => { try { return JSON.parse(l); } catch { return null; } })
+      .filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Clasificador de tipo_fallo — vive en hooks/lib/reflect-classifier.js
+// (AGP Reflect, Zhang 2026 §3.2.2)
+// ---------------------------------------------------------------------------
+
+function clasificarTipoFallo(data, response) {
+  if (reflect) return reflect.clasificarTipoFallo(data, response);
+  return null; // fallback silencioso: si falta el modulo, el hook no bloquea
+}
+
+// ---------------------------------------------------------------------------
+// Análisis de payload de SubagentStop
+// ---------------------------------------------------------------------------
+
+/**
+ * Extrae la info relevante del payload que Claude Code pasa al hook.
+ * Campos esperados (best-effort; varían según harness):
+ *   - session_id
+ *   - tool_name (= "Agent")
+ *   - tool_input.subagent_type  (ej. "implementador-swl")
+ *   - tool_response / tool_result
+ *   - duration_ms (si el harness lo provee)
+ */
+function analizarPayload(data) {
+  const toolName = String(data.tool_name || data.tool?.name || '');
+  if (toolName !== 'Agent') return null;
+
+  const subagentType =
+    data.tool_input?.subagent_type ||
+    data.tool?.input?.subagent_type ||
+    data.subagent_type ||
+    'desconocido';
+
+  // Solo trackeamos agentes SWL (los demás no tenemos potestad de evolucionar)
+  if (!/-swl$/.test(subagentType)) return null;
+
+  const response = data.tool_response || data.tool_result || {};
+  const status = response.is_error || response.status === 'failed' ? 'failed' : 'success';
+
+  // Número de tool calls — lo estimamos por longitud de mensajes si está disponible
+  const mensajes = response.messages || response.mensajes || [];
+  const toolCalls = Array.isArray(mensajes)
+    ? mensajes.filter(m => m && (m.type === 'tool_use' || m.role === 'tool')).length
+    : 0;
+
+  const duracionMs =
+    data.duration_ms ||
+    response.duration_ms ||
+    response.uso?.duration_ms ||
+    null;
+
+  const tipoFallo = status === 'failed'
+    ? clasificarTipoFallo(data, response)
+    : null;
+
+  // Inferir fase/dominio del frontmatter del agente para routing precision
+  // (ADR 0012). Si el agente no tiene frontmatter o no se encuentra el archivo,
+  // los campos quedan null y la métrica simplemente no cuenta esa entrada.
+  let routedPhase = null;
+  let routedDomain = null;
+  let routingSource = 'unknown';
+  if (agentRouting) {
+    try {
+      const r = agentRouting.getRouting(subagentType);
+      routedPhase   = r.fase;
+      routedDomain  = r.dominio;
+      routingSource = r.source;
+    } catch { /* no bloquear por fallo en routing inference */ }
+  }
+
+  return {
+    ts: new Date().toISOString(),
+    sessionId: String(data.session_id || 'default'),
+    agente: subagentType,
+    status,
+    toolCalls,
+    trivial: toolCalls > 0 && toolCalls < MIN_TOOL_CALLS,
+    duracionMs,
+    tipo_fallo: tipoFallo,
+    routed_phase:   routedPhase,
+    routed_domain:  routedDomain,
+    routing_source: routingSource,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Gates para emitir nudge
+// ---------------------------------------------------------------------------
+
+function filtrarVentana(entradas, dias) {
+  const limite = Date.now() - dias * 24 * 3600 * 1000;
+  return entradas.filter(e => {
+    const t = Date.parse(e.ts);
+    return Number.isFinite(t) && t >= limite;
+  });
+}
+
+function resumenPorAgente(entradasVentana) {
+  const resumen = {};
+  for (const e of entradasVentana) {
+    if (!resumen[e.agente]) {
+      resumen[e.agente] = { runs: 0, fallos: 0, triviales: 0, fallos_por_tipo: {} };
+    }
+    const r = resumen[e.agente];
+    if (e.trivial) r.triviales++;
+    else {
+      r.runs++;
+      if (e.status === 'failed') {
+        r.fallos++;
+        const tipo = e.tipo_fallo || 'unknown';
+        r.fallos_por_tipo[tipo] = (r.fallos_por_tipo[tipo] || 0) + 1;
+      }
+    }
+  }
+  return resumen;
+}
+
+/**
+ * Determina el tipo_fallo dominante y retorna un diagnóstico estructurado
+ * listo para propagar al nudge. Delega al módulo reflect-classifier.
+ */
+function construirDiagnosis(resumenAgente) {
+  if (reflect) return reflect.construirDiagnosis(resumenAgente);
+  return null;
+}
+
+function debeEmitirNudge(agente, resumen, nudges) {
+  const r = resumen[agente];
+  if (!r) return null;
+
+  const ultimoNudge = nudges[agente];
+  if (ultimoNudge) {
+    const horas = (Date.now() - Date.parse(ultimoNudge)) / 3600000;
+    if (horas < THROTTLE_HORAS) return null;
+  }
+
+  if (r.fallos >= UMBRAL_FALLOS) {
+    return {
+      razon: 'fallos',
+      detalle: `${r.fallos} fallos en ${VENTANA_DIAS} días`,
+    };
+  }
+  if (r.runs >= UMBRAL_RUNS) {
+    return {
+      razon: 'volumen',
+      detalle: `${r.runs} corridas no triviales en ${VENTANA_DIAS} días`,
+    };
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Convergence detector — gate de loop (REC-D03)
+// ---------------------------------------------------------------------------
+
+/**
+ * Lee las invocaciones de herramienta del agente desde los JSONL de trazas.
+ *
+ * El formato nativo de otlp-exporter es:
+ *   { traceId, spanId, nombre, inicio, fin, duracionMs, estado, atributos }
+ * donde `nombre` es tipo "agent:nombre-swl" o "skill:nombre-skill".
+ *
+ * Retorna array de { tool: string } compatible con calcularScoreConvergencia.
+ * Nunca lanza — retorna [] ante cualquier falla.
+ *
+ * @param {string} agente       - Nombre del agente SWL (sin prefijo, ej: "implementador-swl")
+ * @param {number} [diasAtras]  - Cuántos días de traces revisar (1 = solo hoy, 2 = hoy y ayer)
+ * @returns {Array<{tool: string}>}
+ */
+function leerInvocacionesDelAgente(agente, diasAtras = 1) {
+  const invocaciones = [];
+  try {
+    const ahora = new Date();
+    for (let i = 0; i < diasAtras; i++) {
+      const fecha = new Date(ahora.getTime() - i * 24 * 3600 * 1000)
+        .toISOString()
+        .slice(0, 10);
+      const rutaJsonl = path.join(DIR_TRACES, `${fecha}.jsonl`);
+      if (!fs.existsSync(rutaJsonl)) continue;
+
+      let contenido;
+      try {
+        contenido = fs.readFileSync(rutaJsonl, 'utf8');
+      } catch {
+        continue;
+      }
+
+      const lineas = contenido.split(/\r?\n/).filter(Boolean);
+      for (const linea of lineas) {
+        let evento;
+        try {
+          evento = JSON.parse(linea);
+        } catch {
+          continue;
+        }
+
+        // El campo nombre puede ser "agent:nombre-swl", "skill:nombre", etc.
+        // Filtramos eventos asociados al agente actual.
+        const nombre = String(evento.nombre || '');
+        const esDelAgente =
+          nombre === `agent:${agente}` ||
+          nombre.includes(agente) ||
+          (evento.atributos?.agente === agente) ||
+          (evento.atributos?.agent === agente);
+
+        if (!esDelAgente) continue;
+
+        // Extraemos el nombre del tool/skill del evento como la herramienta invocada.
+        // En el formato OTLP-lite el "tool" es el nombre del span.
+        const tool = nombre || 'unknown';
+        invocaciones.push({ tool });
+      }
+    }
+  } catch {
+    // Fallback silencioso — el hook no debe crashear por traces inexistentes
+  }
+  return invocaciones;
+}
+
+/**
+ * Determina si hay throttle activo para el nudge de loop del agente.
+ *
+ * Usa la clave "<agente>::loop" en el objeto nudges con el mismo
+ * throttle configurado en THROTTLE_HORAS.
+ *
+ * @param {string} agente
+ * @param {object} nudges
+ * @returns {boolean} true si debe omitir el nudge de loop
+ */
+function estaThrottledLoop(agente, nudges) {
+  const clave = `${agente}::loop`;
+  const ultimo = nudges[clave];
+  if (!ultimo) return false;
+  const horas = (Date.now() - Date.parse(ultimo)) / 3600000;
+  return horas < THROTTLE_HORAS;
+}
+
+// ---------------------------------------------------------------------------
+// Drift detector automático (REC-D07)
+// ---------------------------------------------------------------------------
+
+/**
+ * Retorna las rutas de los últimos N archivos JSONL de traces ordenados
+ * por fecha descendente (más reciente primero).
+ *
+ * @param {number} [max=5]
+ * @returns {string[]}
+ */
+function rutasTracesRecientes(max) {
+  const n = max || 5;
+  try {
+    if (!fs.existsSync(DIR_TRACES)) return [];
+    const archivos = fs.readdirSync(DIR_TRACES)
+      .filter(f => /^\d{4}-\d{2}-\d{2}\.jsonl$/.test(f))
+      .sort()
+      .reverse()
+      .slice(0, n);
+    return archivos.map(f => path.join(DIR_TRACES, f));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Ejecuta el drift-detector de forma automática con throttle propio.
+ *
+ * Respeta la clave "__drift__::global" en el objeto nudges para evitar
+ * correr en cada invocación de subagente (sería costoso).
+ *
+ * Opt-out completo con SWL_DRIFT_DISABLED=1.
+ *
+ * @param {object} nudges  - Objeto de nudges leído de disco (se muta in-place)
+ */
+function ejecutarDriftAutomatico(nudges) {
+  if (process.env.SWL_DRIFT_DISABLED === '1') return;
+  if (!driftDetector) return;
+
+  // Throttle: no correr si ya se corrió en las últimas DRIFT_THROTTLE_HORAS
+  const claveThrottle = '__drift__::global';
+  const ultimoDrift = nudges[claveThrottle];
+  if (ultimoDrift) {
+    const horas = (Date.now() - Date.parse(ultimoDrift)) / 3600000;
+    if (horas < DRIFT_THROTTLE_HORAS) return;
+  }
+
+  // Actualizar throttle inmediatamente para que invocaciones concurrentes no dupliquen
+  nudges[claveThrottle] = new Date().toISOString();
+
+  try {
+    const rutas = rutasTracesRecientes(5);
+    if (rutas.length === 0) return;
+
+    // Usar la traza más reciente como fuente principal de drift.
+    // detectarDrift acepta una sola rutaJsonl — pasamos el archivo más reciente.
+    const resultado = driftDetector.detectarDrift({
+      rutaJsonl: rutas[0],
+      ventanaDias: 7,
+      baselineSemanasBase: 4,
+      umbralPct: 10,
+    });
+
+    if (!resultado) return;
+    if (resultado.estado_global !== 'warn' && resultado.estado_global !== 'critico') return;
+
+    // Filtrar solo las métricas que driftearon
+    const driftsSig = (resultado.drifts || []).filter(d => d.estado !== 'ok');
+    if (driftsSig.length === 0) return;
+
+    // Emitir nudge por stderr
+    const lineasDrift = driftsSig.map(d =>
+      `    • ${d.metrica}: ${d.driftPct > 0 ? '+' : ''}${d.driftPct}% (${d.estado})`
+    );
+    const mensajeDrift = [
+      '',
+      `[auto-evolución] Drift detectado en trazas de agentes (estado: ${resultado.estado_global}).`,
+      '  Métricas con variación significativa:',
+      ...lineasDrift,
+      '  Considera revisar el ciclo de evolución:',
+      '    /swl:evolucionar',
+      '',
+    ].join('\n');
+    process.stderr.write(mensajeDrift);
+
+    // Registrar en nudge-tracker
+    if (nudgeTracker) {
+      try {
+        // Drift crítico → repair/high; drift warn → repair/medium
+        const esCritico = resultado.estado_global === 'critico';
+        nudgeTracker.emit({
+          kind: 'drift-detectado',
+          target: '__global__',
+          message: mensajeDrift.trim(),
+          source: 'hooks/auto-evolucion.js',
+          mutation_category: 'repair',
+          risk_level: esCritico ? 'high' : 'medium',
+          data: {
+            estado_global: resultado.estado_global,
+            drifts: driftsSig,
+          },
+        });
+      } catch { /* silencioso */ }
+    }
+
+  } catch {
+    // Fallback silencioso — el drift no debe bloquear el hook principal
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Entrypoint
+// ---------------------------------------------------------------------------
+
+/**
+ * Etapa de auto-evolución del ciclo (sub-etapa de hooks/ciclo-evolucion-subagente.js).
+ * Consume el payload de SubagentStop. Best-effort: nunca lanza al caller.
+ * @param {string} inputRaw payload JSON del evento SubagentStop
+ */
+function ejecutar(inputRaw) {
+  // Singleton guard: si otra instancia está corriendo (poco probable en
+  // SubagentStop pero posible con eventos concurrentes), salir silenciosamente.
+  // Lock stale tras 5 min (la etapa normalmente corre en < 1s).
+  if (singletonGuard && !singletonGuard.adquirir('auto-evolucion', { staleMs: 300000 })) {
+    return;
+  }
+
+  try {
+    const data = JSON.parse(inputRaw);
+    const entrada = analizarPayload(data);
+    if (!entrada) { if (singletonGuard) singletonGuard.liberar('auto-evolucion'); return; }
+
+    // 1. Registrar en el log JSONL
+    append(entrada);
+
+    // 2. Si fue trivial, no analizamos nudges
+    if (entrada.trivial) { if (singletonGuard) singletonGuard.liberar('auto-evolucion'); return; }
+
+    // 3. Cargar histórico en ventana y evaluar gates
+    const historico = leerLog();
+    const ventana   = filtrarVentana(historico, VENTANA_DIAS);
+    const resumen   = resumenPorAgente(ventana);
+
+    const nudges  = leerNudges();
+    const decision = debeEmitirNudge(entrada.agente, resumen, nudges);
+
+    // 4. Gate de loop (convergence-detector, REC-D03)
+    let loopInfo = null;
+    if (convergenceDetector) {
+      try {
+        const invocaciones = leerInvocacionesDelAgente(entrada.agente, 1);
+        if (invocaciones.length >= MIN_INVOCACIONES_LOOP) {
+          loopInfo = convergenceDetector.detectarLoop({ invocaciones });
+        }
+      } catch { /* fallback silencioso */ }
+    }
+
+    // Mapeo razón → (mutation_category, risk_level) según Evolver GEP.
+    // repair: corrige regresión observable; optimize: mejora sin bug; innovate: capacidad nueva.
+    const clasificarRazon = (razon) => {
+      if (razon === 'fallos' || razon === 'loop') return { mutation_category: 'repair', risk_level: 'high' };
+      if (razon === 'volumen') return { mutation_category: 'optimize', risk_level: 'medium' };
+      if (razon === 'drift') return { mutation_category: 'repair', risk_level: 'medium' };
+      return { mutation_category: undefined, risk_level: undefined };
+    };
+
+    // 5. Emitir nudge de loop si aplica (gate independiente del de fallos/volumen)
+    if (loopInfo?.estaEnLoop && !estaThrottledLoop(entrada.agente, nudges)) {
+      const mensajeLoop = [
+        '',
+        `[auto-evolución] Posible loop detectado en "${entrada.agente}".`,
+        `  Ratio calls/tools: ${Math.round(loopInfo.ratio * 100) / 100}  (umbral ${loopInfo.umbralUsado})`,
+        `  Invocaciones: ${loopInfo.totalCalls}  Tools únicos: ${loopInfo.uniqueTools}`,
+        `  Considera revisar el diseño del agente:`,
+        `    /swl:evolucionar ${entrada.agente}`,
+        '',
+      ].join('\n');
+
+      process.stderr.write(mensajeLoop);
+
+      // Registrar throttle del loop por separado
+      nudges[`${entrada.agente}::loop`] = new Date().toISOString();
+
+      if (nudgeTracker) {
+        try {
+          const clasif = clasificarRazon('loop');
+          nudgeTracker.emit({
+            kind: 'auto-evolucion',
+            target: entrada.agente,
+            message: mensajeLoop.trim(),
+            source: 'hooks/auto-evolucion.js',
+            mutation_category: clasif.mutation_category,
+            risk_level: clasif.risk_level,
+            data: {
+              razon: 'loop',
+              ratio: loopInfo.ratio,
+              totalCalls: loopInfo.totalCalls,
+              uniqueTools: loopInfo.uniqueTools,
+              umbralUsado: loopInfo.umbralUsado,
+            },
+          });
+        } catch { /* silencioso */ }
+      }
+    }
+
+    // 6. Si no hay decision de nudge principal, pasar al drift y salir
+    if (!decision) {
+      escribirNudges(nudges);
+      ejecutarDriftAutomatico(nudges);
+      escribirNudges(nudges);
+      if (singletonGuard) singletonGuard.liberar('auto-evolucion');
+      return;
+    }
+
+    // 7. Construir diagnosis semántico (AGP Reflect)
+    const diagnosis = construirDiagnosis(resumen[entrada.agente]);
+
+    // 8. Emitir nudge principal (stderr, visible al modelo como contexto)
+    const lineas = [
+      '',
+      `[auto-evolución] Agente "${entrada.agente}" acumuló señales para evolución.`,
+      `  Motivo: ${decision.razon} — ${decision.detalle}.`,
+    ];
+    if (diagnosis) {
+      lineas.push(`  Tipo de fallo dominante: ${diagnosis.tipo_fallo} (${diagnosis.conteo_dominante}/${diagnosis.total_fallos} fallos).`);
+      lineas.push(`  Hipotesis de mejora: ${diagnosis.hint_mejora}.`);
+    }
+    // Incluir info de loop en el nudge principal si también está activo
+    if (loopInfo?.estaEnLoop) {
+      lineas.push(`  Además: loop detectado (ratio ${Math.round(loopInfo.ratio * 100) / 100}, umbral ${loopInfo.umbralUsado}).`);
+    }
+    lineas.push(`  Considera invocar:`);
+    lineas.push(`    /swl:evolucionar ${entrada.agente}`);
+    lineas.push(`  (o el agente auto-evolucion-swl con foco en "${entrada.agente}")`);
+    lineas.push('');
+    const mensaje = lineas.join('\n');
+    process.stderr.write(mensaje);
+
+    // 9. Registrar timestamp del nudge para throttle
+    nudges[entrada.agente] = new Date().toISOString();
+    escribirNudges(nudges);
+
+    // 10. Registrar en nudge-tracker para medir tasa de acción
+    if (nudgeTracker) {
+      try {
+        const clasif = clasificarRazon(decision.razon);
+        nudgeTracker.emit({
+          kind: 'auto-evolucion',
+          target: entrada.agente,
+          message: mensaje.trim(),
+          source: 'hooks/auto-evolucion.js',
+          mutation_category: clasif.mutation_category,
+          risk_level: clasif.risk_level,
+          data: {
+            razon:     decision.razon,
+            detalle:   decision.detalle,
+            diagnosis,
+            loop:      loopInfo?.estaEnLoop ? loopInfo : null,
+          },
+        });
+      } catch { /* silencioso */ }
+    }
+
+    // 11. Drift automático (REC-D07) al final
+    ejecutarDriftAutomatico(nudges);
+    escribirNudges(nudges);
+
+  } catch (err) {
+    // Nunca bloquea, pero deja traza diagnóstica para no perder
+    // regresiones silenciosas en el ciclo de auto-evolución.
+    process.stderr.write(`[auto-evolucion] error interno: ${String(err.message || err).slice(0, 120)}\n`);
+  } finally {
+    if (singletonGuard) singletonGuard.liberar('auto-evolucion');
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+module.exports = {
+  ejecutar,
+  leerInvocacionesDelAgente,
+  ejecutarDriftAutomatico,
+  estaThrottledLoop,
+  rutasTracesRecientes,
+  // Exponer para tests de integración completos
+  _internals: {
+    analizarPayload,
+    filtrarVentana,
+    resumenPorAgente,
+    debeEmitirNudge,
+    construirDiagnosis,
+  },
+};
+
+// Ejecución directa (compat: sigue invocable standalone para diagnóstico).
+// Los listeners de stdin solo se registran en modo CLI para no colgar el
+// event loop cuando el módulo se importa desde tests.
+if (require.main === module) {
+  let inputRaw = '';
+  process.stdin.on('data', chunk => { inputRaw += chunk; });
+  process.stdin.on('end', () => ejecutar(inputRaw));
+}