@saulwade/swl-ses 1.0.0

package/hooks/grafo-contexto.js

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * grafo-contexto.js — Hook PreToolUse: inyecta contexto del grafo antes de búsquedas.
+ *
+ * Cuando Claude está a punto de ejecutar Glob, Grep o Read para buscar en el
+ * codebase, este hook verifica si existe .planning/REPORTE-GRAFO.md e inyecta
+ * un resumen topológico relevante en hookSpecificOutput.
+ *
+ * Resultado: los agentes navegan por el grafo de dependencias ANTES de leer
+ * archivos raw, reduciendo el número de tool calls y el costo en tokens ~71x.
+ *
+ * Opt-in: si .planning/REPORTE-GRAFO.md no existe, el hook pasa silenciosamente.
+ * Construir el grafo: python scripts/lib/graph-builder.py
+ *
+ * Evento: PreToolUse
+ * Matcher: Glob|Grep|Read
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+const CWD         = process.env.PWD || process.cwd();
+const REPORT_FILE = path.join(CWD, '.planning', 'REPORTE-GRAFO.md');
+const GRAPH_FILE  = path.join(CWD, '.planning', 'graph.json');
+
+// Máximo de caracteres a inyectar para no saturar el contexto
+const MAX_INJECT_CHARS = 1200;
+
+// ---------------------------------------------------------------------------
+// Lectura del reporte
+// ---------------------------------------------------------------------------
+
+function leerResumenGrafo() {
+  if (!fs.existsSync(REPORT_FILE)) return null;
+  try {
+    return fs.readFileSync(REPORT_FILE, 'utf8');
+  } catch (_) {
+    return null;
+  }
+}
+
+function existeGrafo() {
+  return fs.existsSync(GRAPH_FILE);
+}
+
+// ---------------------------------------------------------------------------
+// Extracción de sección relevante del reporte
+// ---------------------------------------------------------------------------
+
+/**
+ * Extrae las secciones más útiles del REPORTE-GRAFO.md:
+ * inventario + god nodes. Trunca a MAX_INJECT_CHARS.
+ *
+ * @param {string} reporte
+ * @returns {string}
+ */
+function extraerContextoRelevante(reporte) {
+  // Buscar sección de inventario y god nodes
+  const seccionInv  = reporte.match(/## Inventario por tipo[\s\S]*?(?=## |\z)/)?.[0] || '';
+  const seccionGod  = reporte.match(/## Nodos más conectados[\s\S]*?(?=## |\z)/)?.[0] || '';
+  const seccionHuer = reporte.match(/## Nodos huérfanos[\s\S]*?(?=## |\z)/)?.[0] || '';
+
+  const combinado = [seccionInv, seccionGod, seccionHuer]
+    .map(s => s.trim())
+    .filter(Boolean)
+    .join('\n\n');
+
+  if (combinado.length <= MAX_INJECT_CHARS) return combinado;
+  return combinado.slice(0, MAX_INJECT_CHARS) + '\n...[ver .planning/REPORTE-GRAFO.md para detalle completo]';
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+let inputRaw = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => { inputRaw += chunk; });
+process.stdin.on('end', () => {
+  // Solo proceder si el grafo existe
+  if (!existeGrafo()) {
+    process.exit(0);
+  }
+
+  const reporte = leerResumenGrafo();
+  if (!reporte) {
+    process.exit(0);
+  }
+
+  let hookInput;
+  try {
+    hookInput = JSON.parse(inputRaw);
+  } catch (_) {
+    process.exit(0);
+  }
+
+  const toolName = hookInput?.tool_name || '';
+
+  // Solo actuar si es una búsqueda de archivos
+  if (!['Glob', 'Grep', 'Read'].includes(toolName)) {
+    process.exit(0);
+  }
+
+  const contexto = extraerContextoRelevante(reporte);
+  if (!contexto) {
+    process.exit(0);
+  }
+
+  // Inyectar como contexto adicional
+  const output = {
+    hookSpecificOutput: {
+      hookType: 'grafo-contexto',
+      message:  [
+        '📊 Grafo de dependencias SWL disponible (.planning/graph.json).',
+        'Consulta este resumen antes de buscar archivos raw:',
+        '',
+        contexto,
+        '',
+        'Para análisis completo: python scripts/lib/graph-analyze.py god_nodes',
+        'Para blast radius: python scripts/lib/graph-analyze.py blast_radius <nombre>',
+      ].join('\n'),
+    },
+  };
+
+  process.stdout.write(JSON.stringify(output) + '\n');
+  process.exit(0);
+});

package/hooks/graph-update.js

@@ -0,0 +1,67 @@
+'use strict';
+
+/**
+ * Hook: graph-update.js
+ * Tipo: PostToolUse  (aplica a: Write | Edit)
+ *
+ * Mantiene el grafo de code-review-graph actualizado automáticamente
+ * después de cada modificación de archivo en la sesión.
+ *
+ * Comportamiento:
+ *   - Detecta si existe .code-review-graph/graph.db en el proyecto
+ *   - Si existe: ejecuta `code-review-graph update` de forma asíncrona
+ *   - El update usa git diff para detectar solo los archivos cambiados (<2s)
+ *   - Silencioso: ningún output llega al usuario
+ *   - Non-blocking: no ralentiza la sesión (spawn sin esperar resultado)
+ *
+ * Esto implementa el patrón PostToolUse de code-review-graph:
+ * el grafo siempre refleja el estado actual del código para que
+ * las herramientas MCP (get_impact_radius, detect_changes, etc.)
+ * entreguen resultados precisos.
+ */
+
+const fs    = require('fs');
+const path  = require('path');
+const { spawn } = require('child_process');
+
+// ---------------------------------------------------------------------------
+// Entrada principal
+// ---------------------------------------------------------------------------
+
+try {
+  const input = JSON.parse(process.env.CLAUDE_TOOL_INPUT || '{}');
+  const toolName = process.env.CLAUDE_TOOL_NAME || '';
+
+  // Solo aplica a Write y Edit
+  if (!/^(Write|Edit)$/.test(toolName)) process.exit(0);
+
+  const projectRoot = process.cwd();
+  const dbPath = path.join(projectRoot, '.code-review-graph', 'graph.db');
+
+  // Si el grafo no existe aún, no hacer nada (se construye con /swl:revisar-impacto)
+  if (!fs.existsSync(dbPath)) process.exit(0);
+
+  // Lanzar update en background — no esperar resultado
+  const proc = spawn('python', ['-c', `
+import sys
+sys.argv = ['code-review-graph', 'update']
+from code_review_graph.cli import main
+main()
+`], {
+    cwd:      projectRoot,
+    detached: true,
+    stdio:    'ignore',
+    env: {
+      ...process.env,
+      PYTHONIOENCODING: 'utf-8',
+    },
+  });
+
+  // Desacoplar del proceso padre para que no bloquee
+  proc.unref();
+
+} catch (_) {
+  // Nunca bloquear la sesión por fallo del hook de observabilidad
+}
+
+process.exit(0);

package/hooks/guardrail-modelo.js

@@ -0,0 +1,247 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Hook: guardrail-modelo.js
+ * Tipo: PreToolUse (aplica a: Task, Agent)
+ *
+ * Guardrail semántico observacional para degradación de modelo.
+ * Evalúa el prompt del subagente antes de su invocación y registra si podría
+ * ejecutarse con un modelo menos costoso.
+ *
+ * Modo: OBSERVACIONAL — nunca bloquea (exit 0 siempre). Solo registra y emite
+ * nudge al usuario. La activación automática de degradación requiere revisión
+ * manual de guardrail-observaciones.jsonl tras >= 50 activaciones.
+ *
+ * Opt-in: solo activo si SWL_GUARDRAIL_MODELO=1.
+ * Sin esta variable el hook retorna inmediatamente (exit 0).
+ *
+ * Basado en el patrón InputGuardrail de openai-agents-python.
+ * Referencia: habilidades/guardrail-semantico/SKILL.md
+ *
+ * @see habilidades/guardrail-semantico/SKILL.md
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+// ---------------------------------------------------------------------------
+// Guard de opt-in — zero-config por defecto
+// ---------------------------------------------------------------------------
+
+if (!process.env.SWL_GUARDRAIL_MODELO) {
+  process.exit(0);
+}
+
+// ---------------------------------------------------------------------------
+// Rutas
+// ---------------------------------------------------------------------------
+
+const CWD          = process.cwd();
+const DIR_EVOL     = path.join(CWD, '.planning', 'evolucion');
+const GUARDRAIL_LOG = path.join(DIR_EVOL, 'guardrail-observaciones.jsonl');
+
+// ---------------------------------------------------------------------------
+// Criterios de tripwire
+// ---------------------------------------------------------------------------
+
+/**
+ * Palabras clave que indican una decisión crítica o irreversible.
+ * Si el prompt contiene alguna, NO se activa el tripwire de longitud.
+ */
+const RE_CRITICO = /arquitectura|seguridad|diseño|decisión|decision|riesgo|critico|crítico|irreversible/i;
+
+/**
+ * Palabras clave que indican una tarea ligera (determinista, sin razonamiento complejo).
+ * Si el prompt contiene alguna y el agente no es de alto riesgo, se activa el tripwire.
+ */
+const RE_TAREA_LIGERA = /\b(lista|formatea|muestra|busca|cuenta|consulta|renombra|copia|mueve|imprime|listar|mostrar|buscar|contar|consultar)\b/i;
+
+/** Umbral de longitud en caracteres para considerar un prompt como "trivial por longitud". */
+const UMBRAL_LONGITUD = 200;
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Evalúa si el prompt activa el tripwire de tarea trivial por longitud.
+ *
+ * @param {string} texto - Texto del prompt a evaluar.
+ * @returns {boolean}
+ */
+function esTrivialPorLongitud(texto) {
+  return texto.length < UMBRAL_LONGITUD && !RE_CRITICO.test(texto);
+}
+
+/**
+ * Evalúa si el prompt contiene palabras clave de tarea ligera.
+ *
+ * @param {string} texto - Texto del prompt a evaluar.
+ * @returns {boolean}
+ */
+function esTareaLigera(texto) {
+  return RE_TAREA_LIGERA.test(texto) && !RE_CRITICO.test(texto);
+}
+
+/**
+ * Determina la razón del tripwire para el registro de observación.
+ *
+ * @param {string}  texto        - Prompt evaluado.
+ * @param {boolean} trivialLen   - Si activó criterio de longitud.
+ * @param {boolean} tareaLigera  - Si activó criterio de palabras clave.
+ * @returns {string}
+ */
+function razonTripwire(texto, trivialLen, tareaLigera) {
+  if (trivialLen && tareaLigera) return 'prompt-corto-y-palabras-clave-ligeras';
+  if (trivialLen) return `prompt-corto-sin-keywords-criticas (${texto.length} chars)`;
+  if (tareaLigera) return 'palabras-clave-de-tarea-ligera';
+  return 'desconocida';
+}
+
+/**
+ * Determina el modelo sugerido por degradación según modelo actual del agente.
+ *
+ * @param {string} modeloActual - Identificador del modelo actual ('opus'|'sonnet'|'haiku'|...).
+ * @returns {string} Modelo sugerido.
+ */
+function modeloSugerido(modeloActual) {
+  const m = (modeloActual || '').toLowerCase();
+  if (m.includes('opus'))   return 'claude-sonnet-4-6';
+  if (m.includes('sonnet')) return 'claude-haiku-4-5-20251001';
+  // haiku o inherit — no hay degradación posible
+  return modeloActual || 'claude-haiku-4-5-20251001';
+}
+
+// ---------------------------------------------------------------------------
+// Lectura del payload de Claude Code (stdin JSON)
+// ---------------------------------------------------------------------------
+
+/**
+ * Lee y parsea el payload de invocación desde stdin.
+ * Retorna null si el payload no es válido o no es una invocación de agente.
+ *
+ * @returns {Promise<object|null>}
+ */
+async function leerPayload() {
+  return new Promise((resolve) => {
+    let raw = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => { raw += chunk; });
+    process.stdin.on('end', () => {
+      try {
+        const datos = JSON.parse(raw);
+        resolve(datos);
+      } catch (_) {
+        resolve(null);
+      }
+    });
+    process.stdin.on('error', () => resolve(null));
+
+    // timeout defensivo — si stdin nunca cierra, continuar
+    setTimeout(() => resolve(null), 3000);
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Registro de observación
+// ---------------------------------------------------------------------------
+
+/**
+ * Persiste un evento de observación en JSONL append-only.
+ *
+ * @param {object} evento - Datos del evento de guardrail.
+ */
+function registrarObservacion(evento) {
+  try {
+    if (!fs.existsSync(DIR_EVOL)) {
+      fs.mkdirSync(DIR_EVOL, { recursive: true });
+    }
+    fs.appendFileSync(GUARDRAIL_LOG, JSON.stringify(evento) + '\n', 'utf8');
+  } catch (_) {
+    // I/O error — silencioso para no interrumpir el flujo del agente
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Lógica principal
+// ---------------------------------------------------------------------------
+
+/**
+ * Punto de entrada del hook. Evalúa el payload de invocación del subagente
+ * y registra una observación si el tripwire se activa.
+ *
+ * Siempre retorna exit 0 (modo observacional).
+ */
+async function main() {
+  const payload = await leerPayload();
+
+  // Payload inválido o herramienta no relevante — salir silenciosamente
+  if (!payload) {
+    process.exit(0);
+  }
+
+  const toolName = (payload.tool_name || payload.tool || '').toLowerCase();
+
+  // Solo aplicar a invocaciones de subagentes (Task / Agent)
+  if (toolName !== 'task' && toolName !== 'agent') {
+    process.exit(0);
+  }
+
+  const toolInput    = payload.tool_input || payload.input || {};
+  const prompt       = String(toolInput.prompt || toolInput.description || toolInput.task || '');
+  const agenteNombre = String(toolInput.agent || toolInput.subagent || toolInput.name || 'desconocido');
+  const modeloActual = String(toolInput.model || toolInput.modelo || 'sonnet');
+
+  // Override: agentes de alto riesgo nunca se degradan
+  // Se verifica leyendo el frontmatter del agente si está disponible en el input,
+  // o usando una lista de agentes críticos conocidos como fallback.
+  const nivelRiesgo = String(toolInput.nivelRiesgo || toolInput.nivel_riesgo || '').toUpperCase();
+  const AGENTES_CRITICOS = ['orquestador-swl', 'arquitecto-swl', 'revisor-seguridad-swl', 'producto-prd-swl'];
+  const esAgenteCritico = nivelRiesgo === 'ALTO' || AGENTES_CRITICOS.includes(agenteNombre);
+
+  if (esAgenteCritico) {
+    // No aplicar guardrail a agentes críticos — override incondicional
+    process.exit(0);
+  }
+
+  // Override: agente ya en modelo mínimo
+  const modeloNorm = modeloActual.toLowerCase();
+  if (modeloNorm.includes('haiku') || modeloNorm === 'inherit') {
+    process.exit(0);
+  }
+
+  // Evaluación de criterios de tripwire
+  const trivialLen  = esTrivialPorLongitud(prompt);
+  const tareaLigera = esTareaLigera(prompt);
+  const tripwire    = trivialLen || tareaLigera;
+
+  if (!tripwire) {
+    process.exit(0);
+  }
+
+  // Registrar observación JSONL
+  const evento = {
+    timestamp:       new Date().toISOString(),
+    agente:          agenteNombre,
+    modelo_actual:   modeloActual,
+    modelo_sugerido: modeloSugerido(modeloActual),
+    razon_tripwire:  razonTripwire(prompt, trivialLen, tareaLigera),
+    prompt_length:   prompt.length,
+  };
+
+  registrarObservacion(evento);
+
+  // Nudge visible al usuario (stderr) — informativo, no bloquea
+  process.stderr.write(
+    `[guardrail-modelo] El agente '${agenteNombre}' podría ejecutarse con ` +
+    `'${evento.modelo_sugerido}' (menos costoso). ` +
+    `Razón: ${evento.razon_tripwire}. ` +
+    `Ver .planning/evolucion/guardrail-observaciones.jsonl\n`
+  );
+
+  // Modo observacional — exit 0 siempre
+  process.exit(0);
+}
+
+main().catch(() => process.exit(0));

package/hooks/inbox-aviso.js

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Hook: inbox-aviso.js
+ * Tipo: SessionStart | UserPromptSubmit
+ *
+ * Avisa a Claude cuando hay comandos pendientes en .planning/inbox/
+ * enviados desde canales externos (Telegram vía gateway con relay).
+ * Inyecta un mensaje al contexto mediante additionalContext para que
+ * Claude sugiera al usuario ejecutar /swl:inbox.
+ *
+ * Zero-deps. Nunca bloquea.
+ *
+ * Opt-out: SWL_INBOX_AVISO=0
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+const INBOX_DIR = '.planning/inbox';
+
+function contarPendientes(cwd) {
+  const dir = path.join(cwd, INBOX_DIR);
+  if (!fs.existsSync(dir)) return { total: 0, preview: [] };
+  try {
+    const archivos = fs.readdirSync(dir)
+      .filter(f => f.startsWith('cmd-') && f.endsWith('.json'));
+    const pendientes = [];
+    for (const f of archivos) {
+      try {
+        const obj = JSON.parse(fs.readFileSync(path.join(dir, f), 'utf8'));
+        if (obj.estado === 'pending') pendientes.push(obj);
+      } catch (_) {}
+    }
+    const preview = pendientes.slice(0, 3).map(p => ({
+      plataforma: p.platform,
+      usuario:    p.userName,
+      texto:      (p.texto || '').slice(0, 100),
+    }));
+    return { total: pendientes.length, preview };
+  } catch (_) {
+    return { total: 0, preview: [] };
+  }
+}
+
+let inputRaw = '';
+process.stdin.on('data', c => { inputRaw += c; });
+
+process.stdin.on('end', () => {
+  try {
+    if (process.env.SWL_INBOX_AVISO === '0') return;
+
+    const { total, preview } = contarPendientes(process.cwd());
+    if (total === 0) return;
+
+    const lineas = [];
+    lineas.push(`📬 ${total} comando(s) pendiente(s) en el inbox del gateway SWL.`);
+    for (const p of preview) {
+      lineas.push(`  • [${p.plataforma}/${p.usuario}] ${p.texto}`);
+    }
+    if (total > preview.length) {
+      lineas.push(`  • ... y ${total - preview.length} más.`);
+    }
+    lineas.push('Ejecutar `/swl:inbox` para procesarlos.');
+
+    const output = {
+      hookSpecificOutput: {
+        hookEventName:     'UserPromptSubmit',
+        additionalContext: lineas.join('\n'),
+      },
+    };
+    process.stdout.write(JSON.stringify(output));
+  } catch (_) { /* silencioso */ }
+});