@saulwade/swl-ses 2.3.0 → 2.4.1

package/hooks/lib/loop-telemetry.js

@@ -1,321 +1,321 @@
-'use strict';
-
-/**
- * Loop Telemetry — Registro tabular de iteraciones para loops autónomos.
- *
- * Da trazabilidad a cualquier loop iterativo del sistema (autoresearch,
- * /swl:verificar --until-converge, /swl:nemesis --remediar): cada corrida
- * deja una carpeta en .planning/loops/ con un TSV por iteración, un
- * handoff.json para encadenamiento entre comandos, y utilidades de análisis
- * de trayectoria (plateau, revert rate, mejora acumulada).
- *
- * Patrón adoptado del análisis de autoresearch v2.1 (temp/autoresearch-master,
- * sesión 2026-06-10): TSV por iteración + handoff.json + detección de plateau.
- * Adaptado a convenciones SWL: estado en .planning/ (no /tmp), escrituras
- * atómicas para JSON, append para el TSV (alta frecuencia relativa).
- *
- * Formato del TSV (línea 1 = comentario de dirección, línea 2 = header):
- *
- *   # metric_direction: higher_is_better
- *   iteracion	timestamp	metrica	delta	estado	descripcion
- *   0	2026-06-10T20:00:00Z	62	0	baseline	estado inicial
- *   1	2026-06-10T20:05:00Z	65	3	keep	agrega test de frontera X
- *
- * Estados canónicos: baseline | keep | revert | crash | no-op | error-metrica
- *
- * Zero-deps (solo node:fs/path y hooks/lib/atomic-write).
- *
- * @module hooks/lib/loop-telemetry
- */
-
-const fs = require('fs');
-const path = require('path');
-const { atomicWriteSync, atomicWriteJSON } = require('./atomic-write');
-
-const DIR_LOOPS = path.join('.planning', 'loops');
-const COLUMNAS_DEFAULT = ['iteracion', 'timestamp', 'metrica', 'delta', 'estado', 'descripcion'];
-const DIRECCIONES = ['higher_is_better', 'lower_is_better'];
-const VERSION_HANDOFF = '1.0-swl';
-
-/** Sanitiza un valor para celda TSV: sin tabs ni saltos de línea. */
-function sanitizarCelda(valor) {
-  if (valor === null || valor === undefined) return '';
-  return String(valor).replace(/[\t\r\n]+/g, ' ').trim();
-}
-
-function timestampCompacto(fecha) {
-  const f = fecha || new Date();
-  const pad = (n) => String(n).padStart(2, '0');
-  return (
-    String(f.getFullYear()).slice(2) + pad(f.getMonth() + 1) + pad(f.getDate()) +
-    '-' + pad(f.getHours()) + pad(f.getMinutes()) + pad(f.getSeconds())
-  );
-}
-
-/**
- * Inicia una corrida de loop: crea .planning/loops/<tipo>-<YYMMDD-HHMMSS>/
- * con iteraciones.tsv (comentario de dirección + header) y meta.json.
- *
- * @param {object} opciones
- * @param {string} opciones.tipo - Identificador del loop (ej: 'autoresearch', 'nemesis', 'verificar').
- * @param {string} [opciones.direccion='higher_is_better'] - Dirección de la métrica.
- * @param {string[]} [opciones.columnas] - Columnas del TSV (default COLUMNAS_DEFAULT).
- * @param {string} [opciones.raiz=process.cwd()] - Raíz del proyecto.
- * @param {object} [opciones.config={}] - Config inicial persistida en meta.json.
- * @returns {{dir: string, tsvPath: string}}
- */
-function iniciarCorrida({ tipo, direccion = 'higher_is_better', columnas, raiz = process.cwd(), config = {} }) {
-  if (!tipo || !/^[a-z0-9-]+$/.test(tipo)) {
-    throw new TypeError(`loop-telemetry: tipo inválido "${tipo}" — usar kebab-case (ej: "autoresearch")`);
-  }
-  if (!DIRECCIONES.includes(direccion)) {
-    throw new TypeError(`loop-telemetry: dirección inválida "${direccion}" — usar ${DIRECCIONES.join(' | ')}`);
-  }
-  const cols = Array.isArray(columnas) && columnas.length > 0 ? columnas : COLUMNAS_DEFAULT;
-
-  // Colisiones en el mismo segundo: el sufijo se agrega sobre la base
-  // inmutable (tipo-YYMMDD-HHMMSS-N). NUNCA recortar del nombre acumulado —
-  // un replace de "último bloque numérico" se come el HHMMSS del timestamp
-  // y rompe la extracción de tipo en corridaActiva().
-  const base = path.join(raiz, DIR_LOOPS, `${tipo}-${timestampCompacto()}`);
-  let dir = base;
-  let sufijo = 1;
-  while (fs.existsSync(dir)) {
-    sufijo += 1;
-    dir = `${base}-${sufijo}`;
-  }
-  fs.mkdirSync(dir, { recursive: true });
-
-  const tsvPath = path.join(dir, 'iteraciones.tsv');
-  // Header del TSV con escritura atómica: un header truncado rompe
-  // parsearTsv() para toda la vida de la corrida. Las filas posteriores sí
-  // van con appendFileSync (excepción sancionada para appends).
-  atomicWriteSync(tsvPath, `# metric_direction: ${direccion}\n${cols.join('\t')}\n`);
-
-  atomicWriteJSON(path.join(dir, 'meta.json'), {
-    tipo,
-    direccion,
-    columnas: cols,
-    iniciada: new Date().toISOString(),
-    config,
-  });
-
-  return { dir, tsvPath };
-}
-
-/**
- * Registra una iteración: agrega una fila al TSV de la corrida.
- * Las columnas se toman del header del TSV; campos ausentes quedan vacíos.
- *
- * @param {string} dir - Directorio de la corrida (retornado por iniciarCorrida).
- * @param {object} fila - Objeto con valores por columna (ej: {iteracion: 1, metrica: 65, estado: 'keep'}).
- */
-function registrarIteracion(dir, fila) {
-  const tsvPath = path.join(dir, 'iteraciones.tsv');
-  const { columnas } = parsearTsv(tsvPath);
-  const valores = columnas.map((col) => {
-    if (col === 'timestamp' && !(col in fila)) return new Date().toISOString();
-    return sanitizarCelda(fila[col]);
-  });
-  fs.appendFileSync(tsvPath, valores.join('\t') + '\n', 'utf8');
-}
-
-/** Parsea el TSV de una corrida. @returns {{direccion: string, columnas: string[], filas: object[]}} */
-function parsearTsv(tsvPath) {
-  const contenido = fs.readFileSync(tsvPath, 'utf8');
-  const lineas = contenido.split('\n').filter((l) => l.trim().length > 0);
-
-  let direccion = 'higher_is_better';
-  let inicio = 0;
-  if (lineas[0] && lineas[0].startsWith('#')) {
-    const m = lineas[0].match(/metric_direction:\s*(\S+)/);
-    if (m && DIRECCIONES.includes(m[1])) direccion = m[1];
-    inicio = 1;
-  }
-  const columnas = (lineas[inicio] || '').split('\t');
-  const filas = lineas.slice(inicio + 1).map((linea) => {
-    const celdas = linea.split('\t');
-    const obj = {};
-    columnas.forEach((col, i) => { obj[col] = celdas[i] !== undefined ? celdas[i] : ''; });
-    return obj;
-  });
-  return { direccion, columnas, filas };
-}
-
-/** Lee las iteraciones de una corrida. */
-function leerIteraciones(dir) {
-  return parsearTsv(path.join(dir, 'iteraciones.tsv'));
-}
-
-/**
- * Detecta plateau: las últimas `ventana` filas con métrica numérica no
- * muestran mejora respecto al mejor valor previo a la ventana.
- *
- * @param {object[]} filas - Filas parseadas del TSV.
- * @param {object} [opciones]
- * @param {number} [opciones.ventana=3]
- * @param {string} [opciones.campo='metrica']
- * @param {string} [opciones.direccion='higher_is_better']
- * @returns {boolean}
- */
-function detectarPlateau(filas, { ventana = 3, campo = 'metrica', direccion = 'higher_is_better' } = {}) {
-  const numericas = filas
-    .map((f) => parseFloat(f[campo]))
-    .filter((n) => Number.isFinite(n));
-  if (numericas.length < ventana + 1) return false;
-
-  const previas = numericas.slice(0, numericas.length - ventana);
-  const ultimas = numericas.slice(-ventana);
-  const mejor = direccion === 'higher_is_better' ? Math.max(...previas) : Math.min(...previas);
-
-  return ultimas.every((n) =>
-    direccion === 'higher_is_better' ? n <= mejor : n >= mejor
-  );
-}
-
-/**
- * Analiza la trayectoria completa de una corrida.
- *
- * @param {string} dir - Directorio de la corrida.
- * @returns {{
- *   totalIteraciones: number, keeps: number, reverts: number, crashes: number,
- *   revertRate: number, metricaInicial: number|null, metricaFinal: number|null,
- *   mejora: number|null, plateau: boolean, mayorSalto: {iteracion: string, delta: number}|null,
- *   recomendacion: string
- * }}
- */
-function analizarTrayectoria(dir) {
-  const { direccion, filas } = leerIteraciones(dir);
-  const datos = filas.filter((f) => f.estado !== 'baseline');
-  const keeps = datos.filter((f) => f.estado === 'keep').length;
-  const reverts = datos.filter((f) => f.estado === 'revert').length;
-  const crashes = datos.filter((f) => f.estado === 'crash').length;
-  const total = datos.length;
-
-  const metricas = filas
-    .map((f) => parseFloat(f.metrica))
-    .filter((n) => Number.isFinite(n));
-  const metricaInicial = metricas.length > 0 ? metricas[0] : null;
-  const metricaFinal = metricas.length > 0 ? metricas[metricas.length - 1] : null;
-  const mejora = metricaInicial !== null && metricaFinal !== null
-    ? metricaFinal - metricaInicial
-    : null;
-
-  let mayorSalto = null;
-  for (const f of datos) {
-    const delta = parseFloat(f.delta);
-    if (!Number.isFinite(delta)) continue;
-    const magnitud = direccion === 'higher_is_better' ? delta : -delta;
-    if (mayorSalto === null || magnitud > (direccion === 'higher_is_better' ? mayorSalto.delta : -mayorSalto.delta)) {
-      mayorSalto = { iteracion: f.iteracion, delta };
-    }
-  }
-
-  const plateau = detectarPlateau(filas, { direccion });
-  const revertRate = total > 0 ? Math.round((reverts / total) * 100) / 100 : 0;
-
-  let recomendacion;
-  if (plateau) {
-    recomendacion = 'detener: plateau detectado — las últimas iteraciones no mejoran la métrica';
-  } else if (total >= 3 && revertRate >= 0.67) {
-    recomendacion = 'cambiar estrategia: la mayoría de las mutaciones se revierten';
-  } else if (total === 0) {
-    recomendacion = 'sin datos: la corrida no registró iteraciones más allá del baseline';
-  } else {
-    recomendacion = 'continuar: la trayectoria muestra mejora activa';
-  }
-
-  return {
-    totalIteraciones: total, keeps, reverts, crashes, revertRate,
-    metricaInicial, metricaFinal, mejora, plateau, mayorSalto, recomendacion,
-  };
-}
-
-/**
- * Escribe handoff.json: contrato de encadenamiento entre comandos iterativos.
- *
- * @param {string} dir - Directorio de la corrida.
- * @param {object} datos
- * @param {string} datos.source - Comando origen (ej: 'swl:nemesis').
- * @param {string} datos.status - COMPLETO | ACOTADO | PLATEAU | INTERRUMPIDO | ERROR
- * @param {object[]} [datos.findings=[]] - Hallazgos transferibles ({id, severidad, archivo_linea, resumen}).
- * @param {object} [datos.config={}] - Config consumible por el comando siguiente.
- */
-function escribirHandoff(dir, { source, status, findings = [], config = {} }) {
-  if (!source || !status) {
-    throw new TypeError('loop-telemetry: handoff requiere source y status');
-  }
-  atomicWriteJSON(path.join(dir, 'handoff.json'), {
-    version: VERSION_HANDOFF,
-    source,
-    status,
-    timestamp: new Date().toISOString(),
-    iteraciones_tsv: 'iteraciones.tsv',
-    findings,
-    config,
-  });
-}
-
-/** Lee el handoff.json de una corrida. @returns {object|null} */
-function leerHandoff(dir) {
-  try {
-    return JSON.parse(fs.readFileSync(path.join(dir, 'handoff.json'), 'utf8'));
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Encuentra la corrida activa más reciente: directorio en .planning/loops/
- * cuyo iteraciones.tsv fue modificado hace menos de maxEdadMin minutos.
- *
- * @param {string} [raiz=process.cwd()]
- * @param {object} [opciones]
- * @param {number} [opciones.maxEdadMin=30]
- * @returns {{dir: string, tipo: string, ultimasFilas: object[], totalFilas: number}|null}
- */
-function corridaActiva(raiz = process.cwd(), { maxEdadMin = 30 } = {}) {
-  const base = path.join(raiz, DIR_LOOPS);
-  let candidatos;
-  try {
-    candidatos = fs.readdirSync(base, { withFileTypes: true })
-      .filter((e) => e.isDirectory())
-      .map((e) => path.join(base, e.name));
-  } catch {
-    return null;
-  }
-
-  const limite = Date.now() - maxEdadMin * 60 * 1000;
-  let mejor = null;
-  for (const dir of candidatos) {
-    const tsvPath = path.join(dir, 'iteraciones.tsv');
-    let stat;
-    try { stat = fs.statSync(tsvPath); } catch { continue; }
-    if (stat.mtimeMs < limite) continue;
-    if (mejor === null || stat.mtimeMs > mejor.mtimeMs) {
-      mejor = { dir, mtimeMs: stat.mtimeMs };
-    }
-  }
-  if (!mejor) return null;
-
-  const { filas } = leerIteraciones(mejor.dir);
-  return {
-    dir: mejor.dir,
-    tipo: path.basename(mejor.dir).replace(/-\d{6}-\d{6}(-\d+)?$/, ''),
-    ultimasFilas: filas.slice(-3),
-    totalFilas: filas.length,
-  };
-}
-
-module.exports = {
-  DIR_LOOPS,
-  COLUMNAS_DEFAULT,
-  iniciarCorrida,
-  registrarIteracion,
-  leerIteraciones,
-  detectarPlateau,
-  analizarTrayectoria,
-  escribirHandoff,
-  leerHandoff,
-  corridaActiva,
-};
+'use strict';
+
+/**
+ * Loop Telemetry — Registro tabular de iteraciones para loops autónomos.
+ *
+ * Da trazabilidad a cualquier loop iterativo del sistema (autoresearch,
+ * /swl:verificar --until-converge, /swl:nemesis --remediar): cada corrida
+ * deja una carpeta en .planning/loops/ con un TSV por iteración, un
+ * handoff.json para encadenamiento entre comandos, y utilidades de análisis
+ * de trayectoria (plateau, revert rate, mejora acumulada).
+ *
+ * Patrón adoptado del análisis de autoresearch v2.1 (temp/autoresearch-master,
+ * sesión 2026-06-10): TSV por iteración + handoff.json + detección de plateau.
+ * Adaptado a convenciones SWL: estado en .planning/ (no /tmp), escrituras
+ * atómicas para JSON, append para el TSV (alta frecuencia relativa).
+ *
+ * Formato del TSV (línea 1 = comentario de dirección, línea 2 = header):
+ *
+ *   # metric_direction: higher_is_better
+ *   iteracion	timestamp	metrica	delta	estado	descripcion
+ *   0	2026-06-10T20:00:00Z	62	0	baseline	estado inicial
+ *   1	2026-06-10T20:05:00Z	65	3	keep	agrega test de frontera X
+ *
+ * Estados canónicos: baseline | keep | revert | crash | no-op | error-metrica
+ *
+ * Zero-deps (solo node:fs/path y hooks/lib/atomic-write).
+ *
+ * @module hooks/lib/loop-telemetry
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { atomicWriteSync, atomicWriteJSON } = require('./atomic-write');
+
+const DIR_LOOPS = path.join('.planning', 'loops');
+const COLUMNAS_DEFAULT = ['iteracion', 'timestamp', 'metrica', 'delta', 'estado', 'descripcion'];
+const DIRECCIONES = ['higher_is_better', 'lower_is_better'];
+const VERSION_HANDOFF = '1.0-swl';
+
+/** Sanitiza un valor para celda TSV: sin tabs ni saltos de línea. */
+function sanitizarCelda(valor) {
+  if (valor === null || valor === undefined) return '';
+  return String(valor).replace(/[\t\r\n]+/g, ' ').trim();
+}
+
+function timestampCompacto(fecha) {
+  const f = fecha || new Date();
+  const pad = (n) => String(n).padStart(2, '0');
+  return (
+    String(f.getFullYear()).slice(2) + pad(f.getMonth() + 1) + pad(f.getDate()) +
+    '-' + pad(f.getHours()) + pad(f.getMinutes()) + pad(f.getSeconds())
+  );
+}
+
+/**
+ * Inicia una corrida de loop: crea .planning/loops/<tipo>-<YYMMDD-HHMMSS>/
+ * con iteraciones.tsv (comentario de dirección + header) y meta.json.
+ *
+ * @param {object} opciones
+ * @param {string} opciones.tipo - Identificador del loop (ej: 'autoresearch', 'nemesis', 'verificar').
+ * @param {string} [opciones.direccion='higher_is_better'] - Dirección de la métrica.
+ * @param {string[]} [opciones.columnas] - Columnas del TSV (default COLUMNAS_DEFAULT).
+ * @param {string} [opciones.raiz=process.cwd()] - Raíz del proyecto.
+ * @param {object} [opciones.config={}] - Config inicial persistida en meta.json.
+ * @returns {{dir: string, tsvPath: string}}
+ */
+function iniciarCorrida({ tipo, direccion = 'higher_is_better', columnas, raiz = process.cwd(), config = {} }) {
+  if (!tipo || !/^[a-z0-9-]+$/.test(tipo)) {
+    throw new TypeError(`loop-telemetry: tipo inválido "${tipo}" — usar kebab-case (ej: "autoresearch")`);
+  }
+  if (!DIRECCIONES.includes(direccion)) {
+    throw new TypeError(`loop-telemetry: dirección inválida "${direccion}" — usar ${DIRECCIONES.join(' | ')}`);
+  }
+  const cols = Array.isArray(columnas) && columnas.length > 0 ? columnas : COLUMNAS_DEFAULT;
+
+  // Colisiones en el mismo segundo: el sufijo se agrega sobre la base
+  // inmutable (tipo-YYMMDD-HHMMSS-N). NUNCA recortar del nombre acumulado —
+  // un replace de "último bloque numérico" se come el HHMMSS del timestamp
+  // y rompe la extracción de tipo en corridaActiva().
+  const base = path.join(raiz, DIR_LOOPS, `${tipo}-${timestampCompacto()}`);
+  let dir = base;
+  let sufijo = 1;
+  while (fs.existsSync(dir)) {
+    sufijo += 1;
+    dir = `${base}-${sufijo}`;
+  }
+  fs.mkdirSync(dir, { recursive: true });
+
+  const tsvPath = path.join(dir, 'iteraciones.tsv');
+  // Header del TSV con escritura atómica: un header truncado rompe
+  // parsearTsv() para toda la vida de la corrida. Las filas posteriores sí
+  // van con appendFileSync (excepción sancionada para appends).
+  atomicWriteSync(tsvPath, `# metric_direction: ${direccion}\n${cols.join('\t')}\n`);
+
+  atomicWriteJSON(path.join(dir, 'meta.json'), {
+    tipo,
+    direccion,
+    columnas: cols,
+    iniciada: new Date().toISOString(),
+    config,
+  });
+
+  return { dir, tsvPath };
+}
+
+/**
+ * Registra una iteración: agrega una fila al TSV de la corrida.
+ * Las columnas se toman del header del TSV; campos ausentes quedan vacíos.
+ *
+ * @param {string} dir - Directorio de la corrida (retornado por iniciarCorrida).
+ * @param {object} fila - Objeto con valores por columna (ej: {iteracion: 1, metrica: 65, estado: 'keep'}).
+ */
+function registrarIteracion(dir, fila) {
+  const tsvPath = path.join(dir, 'iteraciones.tsv');
+  const { columnas } = parsearTsv(tsvPath);
+  const valores = columnas.map((col) => {
+    if (col === 'timestamp' && !(col in fila)) return new Date().toISOString();
+    return sanitizarCelda(fila[col]);
+  });
+  fs.appendFileSync(tsvPath, valores.join('\t') + '\n', 'utf8');
+}
+
+/** Parsea el TSV de una corrida. @returns {{direccion: string, columnas: string[], filas: object[]}} */
+function parsearTsv(tsvPath) {
+  const contenido = fs.readFileSync(tsvPath, 'utf8');
+  const lineas = contenido.split('\n').filter((l) => l.trim().length > 0);
+
+  let direccion = 'higher_is_better';
+  let inicio = 0;
+  if (lineas[0] && lineas[0].startsWith('#')) {
+    const m = lineas[0].match(/metric_direction:\s*(\S+)/);
+    if (m && DIRECCIONES.includes(m[1])) direccion = m[1];
+    inicio = 1;
+  }
+  const columnas = (lineas[inicio] || '').split('\t');
+  const filas = lineas.slice(inicio + 1).map((linea) => {
+    const celdas = linea.split('\t');
+    const obj = {};
+    columnas.forEach((col, i) => { obj[col] = celdas[i] !== undefined ? celdas[i] : ''; });
+    return obj;
+  });
+  return { direccion, columnas, filas };
+}
+
+/** Lee las iteraciones de una corrida. */
+function leerIteraciones(dir) {
+  return parsearTsv(path.join(dir, 'iteraciones.tsv'));
+}
+
+/**
+ * Detecta plateau: las últimas `ventana` filas con métrica numérica no
+ * muestran mejora respecto al mejor valor previo a la ventana.
+ *
+ * @param {object[]} filas - Filas parseadas del TSV.
+ * @param {object} [opciones]
+ * @param {number} [opciones.ventana=3]
+ * @param {string} [opciones.campo='metrica']
+ * @param {string} [opciones.direccion='higher_is_better']
+ * @returns {boolean}
+ */
+function detectarPlateau(filas, { ventana = 3, campo = 'metrica', direccion = 'higher_is_better' } = {}) {
+  const numericas = filas
+    .map((f) => parseFloat(f[campo]))
+    .filter((n) => Number.isFinite(n));
+  if (numericas.length < ventana + 1) return false;
+
+  const previas = numericas.slice(0, numericas.length - ventana);
+  const ultimas = numericas.slice(-ventana);
+  const mejor = direccion === 'higher_is_better' ? Math.max(...previas) : Math.min(...previas);
+
+  return ultimas.every((n) =>
+    direccion === 'higher_is_better' ? n <= mejor : n >= mejor
+  );
+}
+
+/**
+ * Analiza la trayectoria completa de una corrida.
+ *
+ * @param {string} dir - Directorio de la corrida.
+ * @returns {{
+ *   totalIteraciones: number, keeps: number, reverts: number, crashes: number,
+ *   revertRate: number, metricaInicial: number|null, metricaFinal: number|null,
+ *   mejora: number|null, plateau: boolean, mayorSalto: {iteracion: string, delta: number}|null,
+ *   recomendacion: string
+ * }}
+ */
+function analizarTrayectoria(dir) {
+  const { direccion, filas } = leerIteraciones(dir);
+  const datos = filas.filter((f) => f.estado !== 'baseline');
+  const keeps = datos.filter((f) => f.estado === 'keep').length;
+  const reverts = datos.filter((f) => f.estado === 'revert').length;
+  const crashes = datos.filter((f) => f.estado === 'crash').length;
+  const total = datos.length;
+
+  const metricas = filas
+    .map((f) => parseFloat(f.metrica))
+    .filter((n) => Number.isFinite(n));
+  const metricaInicial = metricas.length > 0 ? metricas[0] : null;
+  const metricaFinal = metricas.length > 0 ? metricas[metricas.length - 1] : null;
+  const mejora = metricaInicial !== null && metricaFinal !== null
+    ? metricaFinal - metricaInicial
+    : null;
+
+  let mayorSalto = null;
+  for (const f of datos) {
+    const delta = parseFloat(f.delta);
+    if (!Number.isFinite(delta)) continue;
+    const magnitud = direccion === 'higher_is_better' ? delta : -delta;
+    if (mayorSalto === null || magnitud > (direccion === 'higher_is_better' ? mayorSalto.delta : -mayorSalto.delta)) {
+      mayorSalto = { iteracion: f.iteracion, delta };
+    }
+  }
+
+  const plateau = detectarPlateau(filas, { direccion });
+  const revertRate = total > 0 ? Math.round((reverts / total) * 100) / 100 : 0;
+
+  let recomendacion;
+  if (plateau) {
+    recomendacion = 'detener: plateau detectado — las últimas iteraciones no mejoran la métrica';
+  } else if (total >= 3 && revertRate >= 0.67) {
+    recomendacion = 'cambiar estrategia: la mayoría de las mutaciones se revierten';
+  } else if (total === 0) {
+    recomendacion = 'sin datos: la corrida no registró iteraciones más allá del baseline';
+  } else {
+    recomendacion = 'continuar: la trayectoria muestra mejora activa';
+  }
+
+  return {
+    totalIteraciones: total, keeps, reverts, crashes, revertRate,
+    metricaInicial, metricaFinal, mejora, plateau, mayorSalto, recomendacion,
+  };
+}
+
+/**
+ * Escribe handoff.json: contrato de encadenamiento entre comandos iterativos.
+ *
+ * @param {string} dir - Directorio de la corrida.
+ * @param {object} datos
+ * @param {string} datos.source - Comando origen (ej: 'swl:nemesis').
+ * @param {string} datos.status - COMPLETO | ACOTADO | PLATEAU | INTERRUMPIDO | ERROR
+ * @param {object[]} [datos.findings=[]] - Hallazgos transferibles ({id, severidad, archivo_linea, resumen}).
+ * @param {object} [datos.config={}] - Config consumible por el comando siguiente.
+ */
+function escribirHandoff(dir, { source, status, findings = [], config = {} }) {
+  if (!source || !status) {
+    throw new TypeError('loop-telemetry: handoff requiere source y status');
+  }
+  atomicWriteJSON(path.join(dir, 'handoff.json'), {
+    version: VERSION_HANDOFF,
+    source,
+    status,
+    timestamp: new Date().toISOString(),
+    iteraciones_tsv: 'iteraciones.tsv',
+    findings,
+    config,
+  });
+}
+
+/** Lee el handoff.json de una corrida. @returns {object|null} */
+function leerHandoff(dir) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(dir, 'handoff.json'), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Encuentra la corrida activa más reciente: directorio en .planning/loops/
+ * cuyo iteraciones.tsv fue modificado hace menos de maxEdadMin minutos.
+ *
+ * @param {string} [raiz=process.cwd()]
+ * @param {object} [opciones]
+ * @param {number} [opciones.maxEdadMin=30]
+ * @returns {{dir: string, tipo: string, ultimasFilas: object[], totalFilas: number}|null}
+ */
+function corridaActiva(raiz = process.cwd(), { maxEdadMin = 30 } = {}) {
+  const base = path.join(raiz, DIR_LOOPS);
+  let candidatos;
+  try {
+    candidatos = fs.readdirSync(base, { withFileTypes: true })
+      .filter((e) => e.isDirectory())
+      .map((e) => path.join(base, e.name));
+  } catch {
+    return null;
+  }
+
+  const limite = Date.now() - maxEdadMin * 60 * 1000;
+  let mejor = null;
+  for (const dir of candidatos) {
+    const tsvPath = path.join(dir, 'iteraciones.tsv');
+    let stat;
+    try { stat = fs.statSync(tsvPath); } catch { continue; }
+    if (stat.mtimeMs < limite) continue;
+    if (mejor === null || stat.mtimeMs > mejor.mtimeMs) {
+      mejor = { dir, mtimeMs: stat.mtimeMs };
+    }
+  }
+  if (!mejor) return null;
+
+  const { filas } = leerIteraciones(mejor.dir);
+  return {
+    dir: mejor.dir,
+    tipo: path.basename(mejor.dir).replace(/-\d{6}-\d{6}(-\d+)?$/, ''),
+    ultimasFilas: filas.slice(-3),
+    totalFilas: filas.length,
+  };
+}
+
+module.exports = {
+  DIR_LOOPS,
+  COLUMNAS_DEFAULT,
+  iniciarCorrida,
+  registrarIteracion,
+  leerIteraciones,
+  detectarPlateau,
+  analizarTrayectoria,
+  escribirHandoff,
+  leerHandoff,
+  corridaActiva,
+};