@saulwade/swl-ses 2.3.0 → 2.4.1

package/hooks/claudemd-duplicacion-detector.js

@@ -1,170 +1,170 @@
-#!/usr/bin/env node
-'use strict';
-
-/**
- * Hook: claudemd-duplicacion-detector.js
- * Tipo: PostToolUse  (aplica a: Write, Edit, MultiEdit)
- *
- * Detecta duplicación de reglas globales (`~/.claude/rules/`) inline en
- * `CLAUDE.md` de proyecto recién modificados. Consume el detector
- * `scripts/lib/detector-reglas-duplicadas.js` que lee el catálogo
- * declarativo `scripts/lib/reglas-globales-conocidas.json`.
- *
- * Aplica la regla `reglas/sin-duplicacion-reglas-globales.md`:
- * el `CLAUDE.md` del proyecto NO debe duplicar reglas que ya viven en
- * `~/.claude/rules/`. La regla global es fuente de verdad; el proyecto
- * referencia, no duplica.
- *
- * Opt-out: SWL_CLAUDEMD_DUPLICACION=0 desactiva completamente el hook.
- *
- * Comportamiento:
- *   - Nunca bloquea operaciones (exit code 0 siempre)
- *   - Solo emite nudge cuando hay duplicaciones detectadas
- *   - Solo se dispara con archivos cuyo basename sea exactamente CLAUDE.md
- *   - Respeta exclusiones: temp/, node_modules/, respositorios-git/
- *   - NO evalúa user-level (~/.claude/CLAUDE.md) — ahí sí pueden
- *     declararse preferencias personales
- *
- * Formato del nudge:
- *   {
- *     id: string,
- *     kind: "claudemd-duplicacion-reglas",
- *     target: "documentador-swl",
- *     source: "hooks/claudemd-duplicacion-detector.js",
- *     message: "...",
- *     data: { archivo, duplicaciones: [...] },
- *     ts: ISO,
- *     accionado: false
- *   }
- */
-
-const fs = require('fs');
-const path = require('path');
-const os = require('os');
-const crypto = require('crypto');
-
-// ─── Opt-out global ───────────────────────────────────────────────────────
-if (process.env.SWL_CLAUDEMD_DUPLICACION === '0') {
-  process.exit(0);
-}
-
-let hookInput = '';
-try {
-  hookInput = fs.readFileSync(0, 'utf-8');
-} catch (_) {
-  process.exit(0);
-}
-
-let evento;
-try {
-  evento = JSON.parse(hookInput);
-} catch (_) {
-  process.exit(0);
-}
-
-const toolName = evento?.tool_name;
-const toolInput = evento?.tool_input;
-
-if (!toolName || !['Write', 'Edit', 'MultiEdit'].includes(toolName)) {
-  process.exit(0);
-}
-
-const filePath = toolInput?.file_path;
-if (!filePath) {
-  process.exit(0);
-}
-
-// Solo CLAUDE.md (basename exacto, case-sensitive)
-const basename = path.basename(filePath);
-if (basename !== 'CLAUDE.md') {
-  process.exit(0);
-}
-
-const pathNormalized = filePath.replace(/\\/g, '/');
-const RUTAS_EXCLUIDAS = [
-  '/temp/',
-  '/node_modules/',
-  '/respositorios-git/',
-  '/.planning/',
-];
-if (RUTAS_EXCLUIDAS.some((excluida) => pathNormalized.includes(excluida))) {
-  process.exit(0);
-}
-
-// User-level: no evaluar (puede declarar preferencias personales)
-const homeClaudeDir = path.resolve(path.join(os.homedir(), '.claude'));
-const rutaAbs = path.resolve(filePath);
-const esUserLevel = rutaAbs.startsWith(homeClaudeDir + path.sep) || rutaAbs === path.join(homeClaudeDir, 'CLAUDE.md');
-
-// El archivo debe existir
-if (!fs.existsSync(filePath)) {
-  process.exit(0);
-}
-
-// ─── Cargar detector ──────────────────────────────────────────────────────
-const CWD = process.cwd();
-const detectorPath = path.join(CWD, 'scripts', 'lib', 'detector-reglas-duplicadas.js');
-if (!fs.existsSync(detectorPath)) {
-  // No hay detector instalado en este destino; salir silenciosamente
-  process.exit(0);
-}
-
-let resultado;
-try {
-  const { detectarDuplicaciones } = require(detectorPath);
-  const contenido = fs.readFileSync(filePath, 'utf8');
-  resultado = detectarDuplicaciones(contenido, null, { esUserLevel });
-} catch (_) {
-  // Cualquier error del detector: salir silenciosamente
-  process.exit(0);
-}
-
-// Solo emitir nudge si hay duplicaciones detectadas
-if (!resultado || !resultado.evaluado || resultado.duplicaciones.length === 0) {
-  process.exit(0);
-}
-
-// ─── Construir nudge ──────────────────────────────────────────────────────
-const rutaRelativa = path.relative(CWD, filePath).replace(/\\/g, '/');
-const topDuplicaciones = resultado.duplicaciones
-  .slice(0, 5)
-  .map((d) => `  - [${d.severidad}] ${d.id} (regla global: ${d.regla_global}, línea ~${d.linea_aproximada})`)
-  .join('\n');
-
-const nudge = {
-  id: crypto.randomBytes(8).toString('hex'),
-  kind: 'claudemd-duplicacion-reglas',
-  target: 'documentador-swl',
-  source: 'hooks/claudemd-duplicacion-detector.js',
-  message:
-    `[claudemd-dup] ${rutaRelativa} duplica ${resultado.duplicaciones.length} regla(s) global(es):\n` +
-    topDuplicaciones + '\n' +
-    `  Ejecutar \`/swl:claudemd audit\` para detalle, ` +
-    `\`/swl:claudemd refactor\` para sugerencias de reemplazo.\n` +
-    `  Ver regla: \`reglas/sin-duplicacion-reglas-globales.md\`.`,
-  data: {
-    archivo: rutaRelativa,
-    total_evaluadas: resultado.total_reglas_evaluadas,
-    detectadas: resultado.duplicaciones.length,
-    ids: resultado.duplicaciones.map((d) => d.id),
-    reglas_globales: [...new Set(resultado.duplicaciones.map((d) => d.regla_global))],
-  },
-  ts: new Date().toISOString(),
-  accionado: false,
-  accionado_ts: null,
-  accionado_por: null,
-};
-
-// ─── Persistir a nudges.jsonl ─────────────────────────────────────────────
-try {
-  const nudgesPath = path.join(CWD, '.planning', 'evolution', 'nudges.jsonl');
-  const nudgesDir = path.dirname(nudgesPath);
-  if (!fs.existsSync(nudgesDir)) {
-    fs.mkdirSync(nudgesDir, { recursive: true });
-  }
-  fs.appendFileSync(nudgesPath, JSON.stringify(nudge) + '\n', 'utf-8');
-} catch (_) {
-  // No fallar el hook por error de escritura
-}
-
-process.exit(0);
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Hook: claudemd-duplicacion-detector.js
+ * Tipo: PostToolUse  (aplica a: Write, Edit, MultiEdit)
+ *
+ * Detecta duplicación de reglas globales (`~/.claude/rules/`) inline en
+ * `CLAUDE.md` de proyecto recién modificados. Consume el detector
+ * `scripts/lib/detector-reglas-duplicadas.js` que lee el catálogo
+ * declarativo `scripts/lib/reglas-globales-conocidas.json`.
+ *
+ * Aplica la regla `reglas/sin-duplicacion-reglas-globales.md`:
+ * el `CLAUDE.md` del proyecto NO debe duplicar reglas que ya viven en
+ * `~/.claude/rules/`. La regla global es fuente de verdad; el proyecto
+ * referencia, no duplica.
+ *
+ * Opt-out: SWL_CLAUDEMD_DUPLICACION=0 desactiva completamente el hook.
+ *
+ * Comportamiento:
+ *   - Nunca bloquea operaciones (exit code 0 siempre)
+ *   - Solo emite nudge cuando hay duplicaciones detectadas
+ *   - Solo se dispara con archivos cuyo basename sea exactamente CLAUDE.md
+ *   - Respeta exclusiones: temp/, node_modules/, respositorios-git/
+ *   - NO evalúa user-level (~/.claude/CLAUDE.md) — ahí sí pueden
+ *     declararse preferencias personales
+ *
+ * Formato del nudge:
+ *   {
+ *     id: string,
+ *     kind: "claudemd-duplicacion-reglas",
+ *     target: "documentador-swl",
+ *     source: "hooks/claudemd-duplicacion-detector.js",
+ *     message: "...",
+ *     data: { archivo, duplicaciones: [...] },
+ *     ts: ISO,
+ *     accionado: false
+ *   }
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const crypto = require('crypto');
+
+// ─── Opt-out global ───────────────────────────────────────────────────────
+if (process.env.SWL_CLAUDEMD_DUPLICACION === '0') {
+  process.exit(0);
+}
+
+let hookInput = '';
+try {
+  hookInput = fs.readFileSync(0, 'utf-8');
+} catch (_) {
+  process.exit(0);
+}
+
+let evento;
+try {
+  evento = JSON.parse(hookInput);
+} catch (_) {
+  process.exit(0);
+}
+
+const toolName = evento?.tool_name;
+const toolInput = evento?.tool_input;
+
+if (!toolName || !['Write', 'Edit', 'MultiEdit'].includes(toolName)) {
+  process.exit(0);
+}
+
+const filePath = toolInput?.file_path;
+if (!filePath) {
+  process.exit(0);
+}
+
+// Solo CLAUDE.md (basename exacto, case-sensitive)
+const basename = path.basename(filePath);
+if (basename !== 'CLAUDE.md') {
+  process.exit(0);
+}
+
+const pathNormalized = filePath.replace(/\\/g, '/');
+const RUTAS_EXCLUIDAS = [
+  '/temp/',
+  '/node_modules/',
+  '/respositorios-git/',
+  '/.planning/',
+];
+if (RUTAS_EXCLUIDAS.some((excluida) => pathNormalized.includes(excluida))) {
+  process.exit(0);
+}
+
+// User-level: no evaluar (puede declarar preferencias personales)
+const homeClaudeDir = path.resolve(path.join(os.homedir(), '.claude'));
+const rutaAbs = path.resolve(filePath);
+const esUserLevel = rutaAbs.startsWith(homeClaudeDir + path.sep) || rutaAbs === path.join(homeClaudeDir, 'CLAUDE.md');
+
+// El archivo debe existir
+if (!fs.existsSync(filePath)) {
+  process.exit(0);
+}
+
+// ─── Cargar detector ──────────────────────────────────────────────────────
+const CWD = process.cwd();
+const detectorPath = path.join(CWD, 'scripts', 'lib', 'detector-reglas-duplicadas.js');
+if (!fs.existsSync(detectorPath)) {
+  // No hay detector instalado en este destino; salir silenciosamente
+  process.exit(0);
+}
+
+let resultado;
+try {
+  const { detectarDuplicaciones } = require(detectorPath);
+  const contenido = fs.readFileSync(filePath, 'utf8');
+  resultado = detectarDuplicaciones(contenido, null, { esUserLevel });
+} catch (_) {
+  // Cualquier error del detector: salir silenciosamente
+  process.exit(0);
+}
+
+// Solo emitir nudge si hay duplicaciones detectadas
+if (!resultado || !resultado.evaluado || resultado.duplicaciones.length === 0) {
+  process.exit(0);
+}
+
+// ─── Construir nudge ──────────────────────────────────────────────────────
+const rutaRelativa = path.relative(CWD, filePath).replace(/\\/g, '/');
+const topDuplicaciones = resultado.duplicaciones
+  .slice(0, 5)
+  .map((d) => `  - [${d.severidad}] ${d.id} (regla global: ${d.regla_global}, línea ~${d.linea_aproximada})`)
+  .join('\n');
+
+const nudge = {
+  id: crypto.randomBytes(8).toString('hex'),
+  kind: 'claudemd-duplicacion-reglas',
+  target: 'documentador-swl',
+  source: 'hooks/claudemd-duplicacion-detector.js',
+  message:
+    `[claudemd-dup] ${rutaRelativa} duplica ${resultado.duplicaciones.length} regla(s) global(es):\n` +
+    topDuplicaciones + '\n' +
+    `  Ejecutar \`/swl:claudemd audit\` para detalle, ` +
+    `\`/swl:claudemd refactor\` para sugerencias de reemplazo.\n` +
+    `  Ver regla: \`reglas/sin-duplicacion-reglas-globales.md\`.`,
+  data: {
+    archivo: rutaRelativa,
+    total_evaluadas: resultado.total_reglas_evaluadas,
+    detectadas: resultado.duplicaciones.length,
+    ids: resultado.duplicaciones.map((d) => d.id),
+    reglas_globales: [...new Set(resultado.duplicaciones.map((d) => d.regla_global))],
+  },
+  ts: new Date().toISOString(),
+  accionado: false,
+  accionado_ts: null,
+  accionado_por: null,
+};
+
+// ─── Persistir a nudges.jsonl ─────────────────────────────────────────────
+try {
+  const nudgesPath = path.join(CWD, '.planning', 'evolution', 'nudges.jsonl');
+  const nudgesDir = path.dirname(nudgesPath);
+  if (!fs.existsSync(nudgesDir)) {
+    fs.mkdirSync(nudgesDir, { recursive: true });
+  }
+  fs.appendFileSync(nudgesPath, JSON.stringify(nudge) + '\n', 'utf-8');
+} catch (_) {
+  // No fallar el hook por error de escritura
+}
+
+process.exit(0);

package/hooks/contexto-iteracion.js

@@ -1,144 +1,145 @@
-#!/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 };
+#!/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 */ }
+  });
+}
+
+// Entrypoint directo o wrapper `node -e "require(...)"` (require.main undefined).
+if (!require.main || require.main === module) main();
+
+module.exports = { debeInyectar, registrarInyeccion, construirBloque, THROTTLE_MS, ARCHIVO_ESTADO };