@saulwade/swl-ses 1.8.0 → 1.9.0

package/habilidades/tdd-workflow/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: tdd-workflow
 description: Flujo completo de Test-Driven Development. Ciclo RED (el test falla) → GREEN (implementación mínima) → REFACTOR (limpieza). Incluye cobertura mínima obligatoria, tests de frontera, factories, fixtures y estrategias para diferentes tipos de código (APIs, services, componentes Angular).
-version: "1.0.6"
+version: "1.1.0"
 evolved: true
 evolved-from: "1.0.4"
 evolved-at: "2026-05-16"
@@ -40,6 +40,19 @@ que los tests exigen — ni más, ni menos.
 
 ---
 
+## Etapa opcional previa: Gherkin (BDD) y gate de mutación
+
+Dos extensiones opt-in del ciclo, ambas con guía completa en recursos:
+
+- **Antes del ciclo** — si la fase tiene criterios de aceptación de negocio,
+  convertirlos en escenarios Given–When–Then validados por el usuario ANTES de
+  implementar; cada escenario es el test RED de su criterio. Guía, runners por
+  stack y anti-patrones en [recursos/gherkin-bdd.md](recursos/gherkin-bdd.md).
+- **Después del ciclo** — en módulos críticos, verificar la calidad de los
+  asserts con mutation testing incremental sobre el diff:
+  `Skill("calidad-mutation-testing")`. La cobertura mide ejecución; los
+  mutantes sobrevivientes miden si los tests detectarían un bug.
+
 ## El ciclo fundamental RED → GREEN → REFACTOR
 
 ### Fase RED — El test debe fallar por la razón correcta

package/habilidades/tdd-workflow/recursos/gherkin-bdd.md

@@ -0,0 +1,111 @@
+# Etapa Gherkin (BDD) — de criterios de aceptación a tests ejecutables
+
+Etapa opt-in previa al ciclo RED→GREEN→REFACTOR que convierte los criterios de
+aceptación del CONTEXTO.md/PRD en escenarios **Given–When–Then** ejecutables.
+Cierra el hueco entre "lo que el negocio pidió" y "lo que los tests verifican":
+cada escenario es a la vez especificación legible por el usuario y esqueleto
+del test.
+
+Inspirada en el flujo de Robert C. Martin (spec → hard spec → Gherkin → TDD →
+mutation testing): el Gherkin es la "hard spec" verificable; el ciclo TDD la
+implementa; el mutation testing (`Skill("calidad-mutation-testing")`) verifica
+la suite resultante.
+
+## Cuándo usar la etapa (y cuándo no)
+
+**Usar cuando**: la fase tiene criterios de aceptación de negocio (PRD o
+CONTEXTO.md con decisiones cerradas), el comportamiento tiene reglas con casos
+distinguibles (descuentos, permisos, estados), o el usuario validará la spec
+sin leer código.
+
+**NO usar cuando**: la fase es técnica pura (refactor, migración, infra), los
+criterios son triviales (CRUD sin reglas), o no hay quien lea los escenarios —
+Gherkin sin lector de negocio es ceremonia que duplica los tests.
+
+## Formato
+
+```gherkin
+# language: es
+Característica: Descuento por nivel de cliente
+  Como cliente premium quiero recibir mi descuento automático
+  para no capturar cupones manualmente.
+
+  Escenario: Cliente premium recibe 15% en compras normales
+    Dado un cliente con nivel "premium"
+    Cuando realiza una compra de $100.00 MXN
+    Entonces el descuento aplicado es de $15.00 MXN
+
+  Esquema del escenario: Descuento por nivel
+    Dado un cliente con nivel "<nivel>"
+    Cuando realiza una compra de $<monto> MXN
+    Entonces el descuento aplicado es de $<descuento> MXN
+
+    Ejemplos:
+      | nivel    | monto  | descuento |
+      | normal   | 100.00 | 0.00      |
+      | premium  | 100.00 | 15.00     |
+      | mayorista| 100.00 | 22.00     |
+```
+
+Reglas de redacción:
+
+- **Un comportamiento por escenario** — si necesitas "Y cuando..." encadenados,
+  son dos escenarios.
+- **Lenguaje del dominio, no de la implementación**: "Dado un cliente premium",
+  NUNCA "Dado un row en la tabla clientes con tipo=2".
+- **Valores concretos** en los ejemplos — los criterios vagos ("un monto
+  válido") no son verificables.
+- **Esquema del escenario** para reglas con tabla de casos — es la forma
+  natural de los tests de frontera de `pruebas.md`.
+- Español de México (`# language: es`) — los escenarios los lee el usuario.
+
+## Derivación desde CONTEXTO.md / PRD
+
+1. Tomar cada criterio de aceptación cerrado del CONTEXTO.md (o historia del PRD).
+2. Reescribirlo como 1-N escenarios: el caso feliz + las fronteras + el caso de error.
+3. Presentar los escenarios al usuario para validación ANTES de implementar —
+   este es el checkpoint humano del flujo: corregir una spec cuesta una
+   conversación; corregir la implementación cuesta un refactor.
+4. Los escenarios validados se guardan en `tests/features/<dominio>.feature`
+   y el PLAN.md referencia qué tarea implementa cada escenario.
+
+## Runners por stack
+
+| Stack | Runner | Binding típico |
+|-------|--------|----------------|
+| Python | `pytest-bdd` (o `behave`) | `@scenario("features/descuento.feature", "Cliente premium...")` + steps con `@given/@when/@then` |
+| JS/TS | `@cucumber/cucumber` | steps en `features/steps/*.ts` con `Given/When/Then` |
+| C#/.NET | Reqnroll (sucesor de SpecFlow) | bindings `[Given]/[When]/[Then]` |
+| Java | Cucumber-JVM | anotaciones `@Given/@When/@Then` |
+
+Verificar versión vigente con Context7 antes de instalar (regla `usar-context7.md`).
+
+Los steps son **pegamento delgado**: parsean el Gherkin y llaman al mismo
+código de test que usaría el ciclo TDD (factories incluidas). La lógica de
+verificación vive en los asserts, no en los steps.
+
+## Integración con el ciclo TDD
+
+```
+CONTEXTO.md/PRD → escenarios Gherkin → validación del usuario (checkpoint)
+      → por cada escenario: RED (step sin implementar falla)
+      → GREEN (implementación mínima) → REFACTOR
+      → al cierre de fase: mutation testing opcional sobre el diff
+```
+
+Cada escenario Gherkin ES un test RED al inicio: el runner reporta steps sin
+implementar como fallos — exactamente la fase RED del ciclo. No escribir tests
+unitarios duplicados del mismo criterio: el escenario cubre el comportamiento
+de negocio; los tests unitarios cubren los detalles internos que el Gherkin
+no expresa (errores de infraestructura, edge cases técnicos).
+
+## Anti-patrones
+
+- **Gherkin imperativo de UI**: "Cuando hago clic en el botón #submit" — eso
+  es un script de Selenium disfrazado. Los escenarios describen comportamiento
+  de dominio; la UI cambia sin que la regla de negocio cambie.
+- **Escenarios escritos DESPUÉS de implementar** para "documentar" — pierde el
+  checkpoint de validación, que es el valor de la etapa.
+- **Steps con lógica de negocio** — la duplican; los steps solo traducen.
+- **Un .feature gigante por módulo** — un archivo por característica, como el
+  código.

package/hooks/contexto-iteracion.js

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Hook: contexto-iteracion.js
+ * Tipo: UserPromptSubmit (matcher vacío)
+ *
+ * Anti-context-rot para loops iterativos: cuando hay una corrida activa en
+ * .planning/loops/ (autoresearch, nemesis --remediar, verificar
+ * --until-converge, debate adversarial), inyecta al contexto un bloque
+ * compacto con el estado del loop — iteración actual, últimas 3 filas del
+ * TSV y la recomendación de trayectoria (continuar / detener por plateau /
+ * cambiar estrategia).
+ *
+ * En sesiones largas el modelo pierde de vista en qué iteración va y si la
+ * métrica sigue mejorando; este hook re-ancla ese estado sin que el agente
+ * tenga que releer archivos. Patrón adoptado del análisis de autoresearch
+ * v2.1 (hook iteration-context), adaptado a SWL: estado en el directorio de
+ * la corrida (no /tmp) y throttle por tiempo (no por conteo de prompts).
+ *
+ * Throttle: máximo 1 inyección cada 4 minutos por corrida (estado en
+ * .inject-state.json dentro del directorio de la corrida — se limpia solo
+ * con la corrida). 4 min < TTL del prompt cache (5 min): la inyección no
+ * coincide dos veces dentro de la misma ventana de cache.
+ *
+ * Zero-deps (solo hooks/lib/loop-telemetry). Nunca bloquea.
+ * Opt-out: SWL_CONTEXTO_ITERACION=0
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { atomicWriteJSON } = require('./lib/atomic-write');
+const { corridaActiva, analizarTrayectoria } = require('./lib/loop-telemetry');
+
+/** Intervalo mínimo entre inyecciones para la misma corrida (4 minutos). */
+const THROTTLE_MS = 4 * 60 * 1000;
+
+const ARCHIVO_ESTADO = '.inject-state.json';
+
+/**
+ * Decide si toca inyectar según el estado de throttle de la corrida.
+ * @param {string} dirCorrida - Directorio de la corrida activa.
+ * @param {number} [ahora=Date.now()]
+ * @returns {boolean}
+ */
+function debeInyectar(dirCorrida, ahora = Date.now()) {
+  try {
+    const estado = JSON.parse(
+      fs.readFileSync(path.join(dirCorrida, ARCHIVO_ESTADO), 'utf8')
+    );
+    return ahora - (estado.ultimaInyeccion || 0) > THROTTLE_MS;
+  } catch {
+    return true; // sin estado = primera inyección
+  }
+}
+
+/** Registra la inyección para el throttle. Best-effort, escritura atómica. */
+function registrarInyeccion(dirCorrida, ahora = Date.now()) {
+  try {
+    atomicWriteJSON(
+      path.join(dirCorrida, ARCHIVO_ESTADO),
+      { ultimaInyeccion: ahora }
+    );
+  } catch { /* silencioso */ }
+}
+
+/**
+ * Construye el bloque de contexto a inyectar.
+ * @param {{dir: string, tipo: string, ultimasFilas: object[], totalFilas: number}} activa
+ * @param {object} trayectoria - Resultado de analizarTrayectoria.
+ * @returns {string}
+ */
+function construirBloque(activa, trayectoria) {
+  const lineas = [];
+  lineas.push(`🔁 Loop activo: \`${activa.tipo}\` (${path.basename(activa.dir)})`);
+  lineas.push(
+    `Iteraciones: ${trayectoria.totalIteraciones} | keep: ${trayectoria.keeps} | ` +
+    `revert: ${trayectoria.reverts} | métrica: ${trayectoria.metricaInicial} → ${trayectoria.metricaFinal}`
+  );
+
+  if (activa.ultimasFilas.length > 0) {
+    lineas.push('Últimas iteraciones:');
+    for (const fila of activa.ultimasFilas) {
+      const desc = (fila.descripcion || '').slice(0, 80);
+      lineas.push(`  ${fila.iteracion ?? '?'}. [${fila.estado || '?'}] métrica=${fila.metrica ?? '?'} — ${desc}`);
+    }
+  }
+
+  if (trayectoria.plateau) {
+    lineas.push(
+      '⚠️ PLATEAU detectado: las últimas iteraciones no mejoran la métrica. ' +
+      'Considera cerrar el loop y reportar el mejor estado alcanzado en lugar de seguir iterando.'
+    );
+  } else {
+    lineas.push(`Recomendación de trayectoria: ${trayectoria.recomendacion}.`);
+  }
+  lineas.push(`Registro completo: ${path.join(activa.dir, 'iteraciones.tsv')}`);
+
+  return lineas.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// Entrypoint
+// ---------------------------------------------------------------------------
+
+function main() {
+  let inputRaw = '';
+  process.stdin.on('data', (c) => { inputRaw += c; });
+
+  process.stdin.on('end', () => {
+    try {
+      if (process.env.SWL_CONTEXTO_ITERACION === '0') return;
+
+      const activa = corridaActiva(process.cwd(), { maxEdadMin: 30 });
+      if (!activa) return;
+      if (!debeInyectar(activa.dir)) return;
+
+      const trayectoria = analizarTrayectoria(activa.dir);
+      // Sin iteraciones más allá del baseline no hay nada útil que anclar
+      if (trayectoria.totalIteraciones === 0) return;
+
+      const output = {
+        hookSpecificOutput: {
+          hookEventName: 'UserPromptSubmit',
+          additionalContext: construirBloque(activa, trayectoria),
+        },
+      };
+      // Marcar el throttle SOLO tras un write exitoso: si stdout falla
+      // (broken pipe, harness cerró el canal), no registrar la inyección
+      // para que el próximo prompt reintente en vez de saltarse 4 min con
+      // un mensaje que nunca llegó. Best-effort: el hook nunca bloquea.
+      process.stdout.write(JSON.stringify(output), (err) => {
+        if (!err) {
+          try { registrarInyeccion(activa.dir); } catch { /* throttle best-effort */ }
+        }
+      });
+    } catch { /* nunca bloquea */ }
+  });
+}
+
+if (require.main === module) main();
+
+module.exports = { debeInyectar, registrarInyeccion, construirBloque, THROTTLE_MS, ARCHIVO_ESTADO };

package/hooks/lib/loop-telemetry.js

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

package/hooks/notificacion-telegram.js

@@ -3,7 +3,13 @@
 /**
  * Hook de notificaciones Telegram para Claude Code.
  *
- * Se dispara en Stop, Notification y SubagentStop.
+ * Se dispara en Stop y Notification por default. SubagentStop es opt-in:
+ * cuando un turno usa subagentes, SubagentStop dispara casi simultáneo al
+ * Stop final y el usuario recibe el mismo contenido dos veces ("Subagente
+ * terminó" + "Claude terminó"). Para recibir también las terminaciones de
+ * subagentes (útil con agentes largos en background):
+ *   CLAUDE_NOTIFY_EVENTS=Stop,Notification,SubagentStop
+ *
  * Best-effort: siempre termina con exit 0, nunca bloquea el flujo de Claude.
  * Registra actividad en ~/.claude/notifications/hook.log (append-only).
  *
@@ -214,9 +220,11 @@ async function run() {
 
   log('evento', nombreEvento, 'proyecto', nombreProyecto);
 
-  // Filtrar eventos no deseados (configurable vía variable de entorno)
+  // Filtrar eventos no deseados (configurable vía variable de entorno).
+  // SubagentStop NO está en el default: duplica la notificación del Stop
+  // final cuando el turno usó subagentes (mismo cuerpo, dos mensajes).
   const eventosActivos = (
-    process.env.CLAUDE_NOTIFY_EVENTS || 'Stop,Notification,SubagentStop'
+    process.env.CLAUDE_NOTIFY_EVENTS || 'Stop,Notification'
   ).split(',').map(s => s.trim());
 
   if (!eventosActivos.includes(nombreEvento)) {

package/llms.txt

@@ -0,0 +1,29 @@
+# swl-ses (@saulwade/swl-ses)
+
+> Sistema de ingeniería de software auto-evolutivo multi-runtime polyglot (SDLC completo), distribuido como paquete npm y plugin de Claude Code. 61 agentes, 181 habilidades, 45 comandos, 31 reglas base y 45 hooks. Soporta 11 lenguajes y 7 runtimes (Claude Code, OpenClaude, OpenCode, Gemini, Cursor, Codex, Copilot). Versión 1.9.0.
+
+Archivo generado por `node scripts/generar-inventario.js` — no editar a mano. Las cifras se sincronizan con INVENTARIO.md en cada regeneración.
+
+## Documentación
+
+- [README](README.md): overview público y quickstart
+- [Manual de uso](MANUAL_USO.md): manual operacional completo
+- [Comandos](COMANDOS.md): referencia detallada de cada comando `/swl:*`
+- [Agentes](AGENTS.md): catálogo de agentes con capacidades
+- [Inventario](INVENTARIO.md): conteos oficiales de todos los componentes
+- [Instalación](INSTALACION.md): instalación, perfiles y configuración
+- [Instrucciones del proyecto](CLAUDE.md): convenciones, stack y reglas
+
+## Componentes
+
+- 61 agentes especializados en `agentes/` (orquestación, implementación por stack, revisión, calidad, diseño)
+- 181 habilidades cargables bajo demanda en `habilidades/` (conocimiento operacional con divulgación progresiva)
+- 45 comandos `/swl:*` en `comandos/swl/` (ciclo GSD, calidad, release, diagnóstico)
+- 31 reglas base + 40 reglas por lenguaje en `reglas/` (políticas obligatorias por matcher)
+- 45 hooks en `hooks/` (telemetría, validación, seguridad; zero-deps, escrituras atómicas)
+
+## Opcional
+
+- [CHANGELOG](CHANGELOG.md): historial de versiones
+- [Índice de ADRs](.planning/adrs/README.md): decisiones de arquitectura
+- [Variables de entorno](docs/variables-entorno.md): configuración opt-in