@saulwade/swl-ses 2.3.0 → 2.4.1

package/hooks/telemetria-skill-routing.js

@@ -1,100 +1,100 @@
-#!/usr/bin/env node
-'use strict';
-
-/**
- * Hook: telemetria-skill-routing.js
- * Tipo: PostToolUse (matcher: "Skill")
- *
- * Cablea la lib huérfana `scripts/lib/skill-metrics.js`: por cada invocación
- * del tool Skill registra la frecuencia/estado en `.planning/skill-metrics.json`
- * vía `registrarUso(cwd, skillName, estado, duracionMs)`.
- *
- * Propósito (Revisión Evolutiva 04, P-2 "bloat y precisión de routing"):
- * acumular telemetría de qué skills se invocan para alimentar la futura
- * auditoría de bloat (skills muertos / solapados). Es la instrumentación que
- * el roadmap permite adelantar como "tarea suelta" antes de la fase de auditoría.
- *
- * Distinto de telemetria-agentes.js (spans OTLP a traces/) y de audit-trail.js
- * (todos los tool calls a audit.jsonl): este hook produce el agregado por-skill
- * que la auditoría de bloat necesita y que ningún otro hook genera.
- *
- * NUNCA bloquea (siempre exit 0). Async: corre en background.
- * Opt-out: SWL_SKILL_TELEMETRIA=0.
- *
- * Origen: punto P-2 de la Revisión Evolutiva 04 (instrumentación adelantada).
- */
-
-/**
- * Extrae el evento de skill de un payload PostToolUse.
- * Pura y testeable — no toca el filesystem.
- *
- * @param {object} data  payload PostToolUse
- * @returns {{skillName: string, estado: 'ok'|'error'}|null} null si no aplica
- */
-function extraerEvento(data) {
-  if (!data || typeof data !== 'object') return null;
-  const toolName = String(data.tool_name || (data.tool && data.tool.name) || '');
-  if (toolName !== 'Skill') return null;
-
-  const input = data.tool_input || {};
-  const skillName = String(input.skill || input.name || '').trim();
-  if (!skillName) return null;
-
-  const esError = Boolean(data.error_message || data.error);
-  return { skillName, estado: esError ? 'error' : 'ok' };
-}
-
-/**
- * Carga defensiva de la lib de métricas. Si no está disponible (destino
- * aplanado, instalación parcial), retorna null y el hook degrada en silencio.
- * @returns {Function|null} registrarUso o null
- */
-function cargarRegistrar() {
-  try {
-    return require('../scripts/lib/skill-metrics').registrarUso;
-  } catch (_) {
-    try {
-      return require('./lib/skill-metrics').registrarUso;
-    } catch (_2) {
-      return null;
-    }
-  }
-}
-
-/**
- * Procesa un payload y registra el uso del skill si aplica.
- * @param {object} data  payload PostToolUse
- * @param {string} cwd   directorio del proyecto
- * @param {Function} [registrar]  inyectable para tests; default carga skill-metrics
- * @returns {boolean} true si registró
- */
-function procesar(data, cwd, registrar) {
-  const evento = extraerEvento(data);
-  if (!evento) return false;
-  const fn = registrar || cargarRegistrar();
-  if (!fn) return false;
-  fn(cwd, evento.skillName, evento.estado, 0);
-  return true;
-}
-
-module.exports = { extraerEvento, procesar };
-
-// --- Entrypoint -------------------------------------------------------------
-// Claude Code invoca el hook vía `node -e "require('./hooks/...')"`, donde
-// `require.main` es undefined. Adjuntar stdin SOLO en ese caso (o invocación
-// directa), nunca cuando un test requiere el módulo (ahí require.main es el
-// runner, definido y ≠ este módulo) — así los tests no cuelgan en stdin.
-if (!require.main || require.main === module) {
-  // Opt-out: no adjuntar el listener (sin process.exit, seguro de requerir).
-  if (process.env.SWL_SKILL_TELEMETRIA !== '0') {
-    let inputRaw = '';
-    process.stdin.on('data', (chunk) => { inputRaw += chunk; });
-    process.stdin.on('end', () => {
-      try {
-        procesar(JSON.parse(inputRaw), process.cwd());
-      } catch (_) {
-        // Silencioso — nunca interrumpir la sesión por un fallo de telemetría.
-      }
-    });
-  }
-}
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Hook: telemetria-skill-routing.js
+ * Tipo: PostToolUse (matcher: "Skill")
+ *
+ * Cablea la lib huérfana `scripts/lib/skill-metrics.js`: por cada invocación
+ * del tool Skill registra la frecuencia/estado en `.planning/skill-metrics.json`
+ * vía `registrarUso(cwd, skillName, estado, duracionMs)`.
+ *
+ * Propósito (Revisión Evolutiva 04, P-2 "bloat y precisión de routing"):
+ * acumular telemetría de qué skills se invocan para alimentar la futura
+ * auditoría de bloat (skills muertos / solapados). Es la instrumentación que
+ * el roadmap permite adelantar como "tarea suelta" antes de la fase de auditoría.
+ *
+ * Distinto de telemetria-agentes.js (spans OTLP a traces/) y de audit-trail.js
+ * (todos los tool calls a audit.jsonl): este hook produce el agregado por-skill
+ * que la auditoría de bloat necesita y que ningún otro hook genera.
+ *
+ * NUNCA bloquea (siempre exit 0). Async: corre en background.
+ * Opt-out: SWL_SKILL_TELEMETRIA=0.
+ *
+ * Origen: punto P-2 de la Revisión Evolutiva 04 (instrumentación adelantada).
+ */
+
+/**
+ * Extrae el evento de skill de un payload PostToolUse.
+ * Pura y testeable — no toca el filesystem.
+ *
+ * @param {object} data  payload PostToolUse
+ * @returns {{skillName: string, estado: 'ok'|'error'}|null} null si no aplica
+ */
+function extraerEvento(data) {
+  if (!data || typeof data !== 'object') return null;
+  const toolName = String(data.tool_name || (data.tool && data.tool.name) || '');
+  if (toolName !== 'Skill') return null;
+
+  const input = data.tool_input || {};
+  const skillName = String(input.skill || input.name || '').trim();
+  if (!skillName) return null;
+
+  const esError = Boolean(data.error_message || data.error);
+  return { skillName, estado: esError ? 'error' : 'ok' };
+}
+
+/**
+ * Carga defensiva de la lib de métricas. Si no está disponible (destino
+ * aplanado, instalación parcial), retorna null y el hook degrada en silencio.
+ * @returns {Function|null} registrarUso o null
+ */
+function cargarRegistrar() {
+  try {
+    return require('../scripts/lib/skill-metrics').registrarUso;
+  } catch (_) {
+    try {
+      return require('./lib/skill-metrics').registrarUso;
+    } catch (_2) {
+      return null;
+    }
+  }
+}
+
+/**
+ * Procesa un payload y registra el uso del skill si aplica.
+ * @param {object} data  payload PostToolUse
+ * @param {string} cwd   directorio del proyecto
+ * @param {Function} [registrar]  inyectable para tests; default carga skill-metrics
+ * @returns {boolean} true si registró
+ */
+function procesar(data, cwd, registrar) {
+  const evento = extraerEvento(data);
+  if (!evento) return false;
+  const fn = registrar || cargarRegistrar();
+  if (!fn) return false;
+  fn(cwd, evento.skillName, evento.estado, 0);
+  return true;
+}
+
+module.exports = { extraerEvento, procesar };
+
+// --- Entrypoint -------------------------------------------------------------
+// Claude Code invoca el hook vía `node -e "require('./hooks/...')"`, donde
+// `require.main` es undefined. Adjuntar stdin SOLO en ese caso (o invocación
+// directa), nunca cuando un test requiere el módulo (ahí require.main es el
+// runner, definido y ≠ este módulo) — así los tests no cuelgan en stdin.
+if (!require.main || require.main === module) {
+  // Opt-out: no adjuntar el listener (sin process.exit, seguro de requerir).
+  if (process.env.SWL_SKILL_TELEMETRIA !== '0') {
+    let inputRaw = '';
+    process.stdin.on('data', (chunk) => { inputRaw += chunk; });
+    process.stdin.on('end', () => {
+      try {
+        procesar(JSON.parse(inputRaw), process.cwd());
+      } catch (_) {
+        // Silencioso — nunca interrumpir la sesión por un fallo de telemetría.
+      }
+    });
+  }
+}

package/hooks/validar-formato-post-subagente.js

@@ -1,140 +1,140 @@
-#!/usr/bin/env node
-'use strict';
-
-/**
- * Hook: validar-formato-post-subagente.js
- * Tipo: SubagentStop (async: true — fire-and-forget)
- *
- * Cuando un subagente SWL termina, valida que su output cumple con el
- * schema declarado en `manifiestos/agent-output-schemas.json`. Si el
- * agente no tiene schema declarado, el hook no hace nada — no asume
- * que todo agente debe seguir el formato compacto.
- *
- * Registra el resultado en `.planning/evolution/formato-violaciones.jsonl`
- * para que `metricas-evolucion.js` calcule la tasa de violación por
- * agente y la incluya en el dashboard de calidad conductual.
- *
- * Schema simple: lista de patrones regex que DEBEN aparecer en el output.
- * Si todos matchean → conforme. Si falta alguno → violación con detalle.
- *
- * Opt-out: SWL_FORMATO_VALIDACION=0 desactiva el hook.
- *
- * El hook nunca bloquea — solo registra para análisis posterior.
- */
-
-const fs   = require('fs');
-const path = require('path');
-
-const CWD = process.cwd();
-const SCHEMAS_PATH = path.join(CWD, 'manifiestos', 'agent-output-schemas.json');
-const LOG_PATH     = path.join(CWD, '.planning', 'evolution', 'formato-violaciones.jsonl');
-
-// ---------------------------------------------------------------------------
-// Carga del schema (una vez)
-// ---------------------------------------------------------------------------
-
-function cargarSchemas() {
-  try {
-    const raw = fs.readFileSync(SCHEMAS_PATH, 'utf8');
-    const parsed = JSON.parse(raw);
-    return parsed.schemas || {};
-  } catch {
-    return {};
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Validación
-// ---------------------------------------------------------------------------
-
-/**
- * Compara el output contra el schema. Devuelve { violation, errors }.
- * @param {string} output - Texto del output del subagente
- * @param {object} schema - { patronesRequeridos: string[] }
- */
-function validarOutput(output, schema) {
-  const errors = [];
-  const patrones = Array.isArray(schema.patronesRequeridos)
-    ? schema.patronesRequeridos
-    : [];
-  for (const patron of patrones) {
-    // El schema puede declarar inline flags estilo (?im) por compatibilidad
-    // con regex POSIX. JavaScript no los soporta inline — los stripeamos
-    // y aplicamos 'im' siempre (case-insensitive + multiline).
-    const limpio = patron.replace(/^\(\?[imsxu]+\)/, '');
-    let regex;
-    try { regex = new RegExp(limpio, 'im'); }
-    catch { errors.push(`Patrón inválido en schema: ${patron}`); continue; }
-    if (!regex.test(output)) {
-      errors.push(`Falta patrón requerido: ${patron}`);
-    }
-  }
-  return { violation: errors.length > 0, errors };
-}
-
-/**
- * Extrae el output textual del subagente del payload del hook.
- * El payload del SubagentStop expone el resultado en distintos lugares
- * según versión de Claude Code; intentamos varias rutas.
- */
-function extraerOutput(data) {
-  const r = data.tool_response || data.tool_result || data.response || {};
-  // Posibles ubicaciones del output del subagente
-  if (typeof r.text === 'string') return r.text;
-  if (typeof r.content === 'string') return r.content;
-  if (Array.isArray(r.messages)) {
-    return r.messages
-      .map(m => (typeof m.content === 'string' ? m.content : ''))
-      .filter(Boolean)
-      .join('\n');
-  }
-  if (typeof r.output === 'string') return r.output;
-  return '';
-}
-
-function ensureDir() {
-  try { fs.mkdirSync(path.dirname(LOG_PATH), { recursive: true }); } catch { /* ignore */ }
-}
-
-// ---------------------------------------------------------------------------
-// Entrypoint
-// ---------------------------------------------------------------------------
-
-let inputRaw = '';
-process.stdin.on('data', chunk => { inputRaw += chunk; });
-
-process.stdin.on('end', () => {
-  try {
-    if (process.env.SWL_FORMATO_VALIDACION === '0') return;
-
-    const data = JSON.parse(inputRaw);
-    const subagentType =
-      data.tool_input?.subagent_type ||
-      data.tool?.input?.subagent_type ||
-      data.subagent_type ||
-      null;
-    if (!subagentType) return;
-
-    const schemas = cargarSchemas();
-    const schema = schemas[subagentType];
-    if (!schema) return; // agente sin schema → no se evalúa
-
-    const output = extraerOutput(data);
-    if (!output || output.length < 10) return; // output trivial — no evaluar
-
-    const { violation, errors } = validarOutput(output, schema);
-    const entry = {
-      ts: new Date().toISOString(),
-      sessionId: String(data.session_id || 'default'),
-      agente: subagentType,
-      violation,
-      errors,
-      outputLen: output.length,
-    };
-
-    ensureDir();
-    fs.appendFileSync(LOG_PATH, JSON.stringify(entry) + '\n', 'utf8');
-  } catch {
-    // SubagentStop hook nunca bloquea por error interno.
-  }
-});
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Hook: validar-formato-post-subagente.js
+ * Tipo: SubagentStop (async: true — fire-and-forget)
+ *
+ * Cuando un subagente SWL termina, valida que su output cumple con el
+ * schema declarado en `manifiestos/agent-output-schemas.json`. Si el
+ * agente no tiene schema declarado, el hook no hace nada — no asume
+ * que todo agente debe seguir el formato compacto.
+ *
+ * Registra el resultado en `.planning/evolution/formato-violaciones.jsonl`
+ * para que `metricas-evolucion.js` calcule la tasa de violación por
+ * agente y la incluya en el dashboard de calidad conductual.
+ *
+ * Schema simple: lista de patrones regex que DEBEN aparecer en el output.
+ * Si todos matchean → conforme. Si falta alguno → violación con detalle.
+ *
+ * Opt-out: SWL_FORMATO_VALIDACION=0 desactiva el hook.
+ *
+ * El hook nunca bloquea — solo registra para análisis posterior.
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+const CWD = process.cwd();
+const SCHEMAS_PATH = path.join(CWD, 'manifiestos', 'agent-output-schemas.json');
+const LOG_PATH     = path.join(CWD, '.planning', 'evolution', 'formato-violaciones.jsonl');
+
+// ---------------------------------------------------------------------------
+// Carga del schema (una vez)
+// ---------------------------------------------------------------------------
+
+function cargarSchemas() {
+  try {
+    const raw = fs.readFileSync(SCHEMAS_PATH, 'utf8');
+    const parsed = JSON.parse(raw);
+    return parsed.schemas || {};
+  } catch {
+    return {};
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Validación
+// ---------------------------------------------------------------------------
+
+/**
+ * Compara el output contra el schema. Devuelve { violation, errors }.
+ * @param {string} output - Texto del output del subagente
+ * @param {object} schema - { patronesRequeridos: string[] }
+ */
+function validarOutput(output, schema) {
+  const errors = [];
+  const patrones = Array.isArray(schema.patronesRequeridos)
+    ? schema.patronesRequeridos
+    : [];
+  for (const patron of patrones) {
+    // El schema puede declarar inline flags estilo (?im) por compatibilidad
+    // con regex POSIX. JavaScript no los soporta inline — los stripeamos
+    // y aplicamos 'im' siempre (case-insensitive + multiline).
+    const limpio = patron.replace(/^\(\?[imsxu]+\)/, '');
+    let regex;
+    try { regex = new RegExp(limpio, 'im'); }
+    catch { errors.push(`Patrón inválido en schema: ${patron}`); continue; }
+    if (!regex.test(output)) {
+      errors.push(`Falta patrón requerido: ${patron}`);
+    }
+  }
+  return { violation: errors.length > 0, errors };
+}
+
+/**
+ * Extrae el output textual del subagente del payload del hook.
+ * El payload del SubagentStop expone el resultado en distintos lugares
+ * según versión de Claude Code; intentamos varias rutas.
+ */
+function extraerOutput(data) {
+  const r = data.tool_response || data.tool_result || data.response || {};
+  // Posibles ubicaciones del output del subagente
+  if (typeof r.text === 'string') return r.text;
+  if (typeof r.content === 'string') return r.content;
+  if (Array.isArray(r.messages)) {
+    return r.messages
+      .map(m => (typeof m.content === 'string' ? m.content : ''))
+      .filter(Boolean)
+      .join('\n');
+  }
+  if (typeof r.output === 'string') return r.output;
+  return '';
+}
+
+function ensureDir() {
+  try { fs.mkdirSync(path.dirname(LOG_PATH), { recursive: true }); } catch { /* ignore */ }
+}
+
+// ---------------------------------------------------------------------------
+// Entrypoint
+// ---------------------------------------------------------------------------
+
+let inputRaw = '';
+process.stdin.on('data', chunk => { inputRaw += chunk; });
+
+process.stdin.on('end', () => {
+  try {
+    if (process.env.SWL_FORMATO_VALIDACION === '0') return;
+
+    const data = JSON.parse(inputRaw);
+    const subagentType =
+      data.tool_input?.subagent_type ||
+      data.tool?.input?.subagent_type ||
+      data.subagent_type ||
+      null;
+    if (!subagentType) return;
+
+    const schemas = cargarSchemas();
+    const schema = schemas[subagentType];
+    if (!schema) return; // agente sin schema → no se evalúa
+
+    const output = extraerOutput(data);
+    if (!output || output.length < 10) return; // output trivial — no evaluar
+
+    const { violation, errors } = validarOutput(output, schema);
+    const entry = {
+      ts: new Date().toISOString(),
+      sessionId: String(data.session_id || 'default'),
+      agente: subagentType,
+      violation,
+      errors,
+      outputLen: output.length,
+    };
+
+    ensureDir();
+    fs.appendFileSync(LOG_PATH, JSON.stringify(entry) + '\n', 'utf8');
+  } catch {
+    // SubagentStop hook nunca bloquea por error interno.
+  }
+});