@saulwade/swl-ses 1.0.0 → 1.1.1

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

@@ -0,0 +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/evolucion/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', 'evolucion', '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.
+  }
+});

package/hooks/validar-memoria-hook.js

@@ -0,0 +1,218 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Hook: validar-memoria-hook.js
+ * Tipo: PostToolUse  (matcher: Write|Edit|MultiEdit)
+ *
+ * Cierra el gap señalado en `reglas/memoria-consolidada.md`: el script
+ * `scripts/validar-memoria.js` solo se ejecuta manualmente vía CLI, así
+ * que la contaminación entre canales (perfil-usuario, APRENDIZAJES,
+ * instintos) sucedía sin que nadie se enterara hasta que un humano
+ * corría el validador.
+ *
+ * Este hook dispara `validar-memoria.js` en modo JSON cada vez que se
+ * escribe un archivo de memoria sensible:
+ *   - `.planning/APRENDIZAJES.md`
+ *   - `instintos/perfil-usuario.yaml`
+ *   - `instintos/proyecto.yaml`
+ *   - `instintos/global.yaml`
+ *
+ * Comportamiento:
+ *   - Sin violaciones → silencioso (exit 0).
+ *   - Violaciones menores (canal incorrecto, duplicación cross-canal) →
+ *     emite nudge informativo via systemMessage.
+ *   - Violaciones críticas (secretos detectados) → emite mensaje fuerte
+ *     pero NO bloquea (siguiendo el contrato de hooks PostToolUse: ya pasó).
+ *     El bloqueo de secretos en escritura corresponde a `escaneo-secretos`
+ *     (PreToolUse), este hook es la red de defensa secundaria.
+ *
+ * Opt-out: SWL_VALIDAR_MEMORIA=0 desactiva el hook.
+ *
+ * El hook nunca bloquea el flujo (siempre exit 0). Los errores internos
+ * se ignoran silenciosamente — la regla "PostToolUse no rompe nada".
+ */
+
+const fs   = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+// ---------------------------------------------------------------------------
+// Configuración
+// ---------------------------------------------------------------------------
+
+/** Archivos cuya modificación dispara la validación. Paths relativos al CWD. */
+const ARCHIVOS_MEMORIA = [
+  '.planning/APRENDIZAJES.md',
+  'instintos/perfil-usuario.yaml',
+  'instintos/proyecto.yaml',
+  'instintos/global.yaml',
+];
+
+/** Path del validador. */
+const VALIDADOR = path.join(process.cwd(), 'scripts', 'validar-memoria.js');
+
+/** Timeout para el validador (ms). Si tarda más, se aborta sin bloquear. */
+const TIMEOUT_MS = 5000;
+
+// ---------------------------------------------------------------------------
+// Utilidades
+// ---------------------------------------------------------------------------
+
+/** Normaliza un path a forma POSIX para comparar contra ARCHIVOS_MEMORIA. */
+function normalizar(p) {
+  if (!p) return '';
+  return String(p).replace(/\\/g, '/').replace(/^\.\//, '');
+}
+
+/** ¿El path tocado coincide con algún archivo de memoria? */
+function esArchivoMemoria(filePath) {
+  const norm = normalizar(filePath);
+  return ARCHIVOS_MEMORIA.some(target => norm.endsWith(target));
+}
+
+/**
+ * Extrae el(los) path(s) afectado(s) por la herramienta del payload del hook.
+ * @param {object} data - Payload del hook (tool_input).
+ * @returns {string[]} Lista de paths afectados.
+ */
+function extraerPaths(data) {
+  const ti = data.tool_input || {};
+  const paths = [];
+  if (ti.file_path)  paths.push(ti.file_path);
+  if (ti.notebook_path) paths.push(ti.notebook_path);
+  // MultiEdit: file_path único + edits[]; ya cubierto arriba.
+  return paths;
+}
+
+/**
+ * Ejecuta el validador y devuelve un resumen normalizado.
+ * Schema esperado del validador (--json):
+ *   {
+ *     totalNoCriticas: N,
+ *     totalCriticas:   N,
+ *     issues: {
+ *       usuario_en_aprendizajes: [...],
+ *       anti_tecnico_en_perfil:  [...],
+ *       duplicados_cross_canal:  [...],
+ *       secretos:                [...],   // críticas
+ *       pii:                     [...],   // críticas
+ *     }
+ *   }
+ *
+ * Si el validador falla o no existe, devuelve null (silencio).
+ */
+function ejecutarValidador() {
+  if (!fs.existsSync(VALIDADOR)) return null;
+  try {
+    const r = spawnSync(process.execPath, [VALIDADOR, '--json'], {
+      cwd: process.cwd(),
+      encoding: 'utf8',
+      timeout: TIMEOUT_MS,
+      windowsHide: true,
+    });
+    if (r.status === null) return null;
+    if (!r.stdout) return null;
+    const parsed = JSON.parse(r.stdout);
+    const issues = parsed.issues || {};
+    return {
+      totalNoCriticas: Number.isInteger(parsed.totalNoCriticas) ? parsed.totalNoCriticas : 0,
+      totalCriticas:   Number.isInteger(parsed.totalCriticas)   ? parsed.totalCriticas   : 0,
+      criticas: [
+        ...(issues.secretos || []).map(x => ({ tipo: 'secreto', detalle: x })),
+        ...(issues.pii      || []).map(x => ({ tipo: 'pii',      detalle: x })),
+      ],
+      menores: [
+        ...(issues.usuario_en_aprendizajes || []).map(x => ({ tipo: 'canal: usuario en aprendizajes',     detalle: x })),
+        ...(issues.anti_tecnico_en_perfil  || []).map(x => ({ tipo: 'canal: anti-patrón técnico en perfil', detalle: x })),
+        ...(issues.duplicados_cross_canal  || []).map(x => ({ tipo: 'duplicación cross-canal',            detalle: x })),
+      ],
+    };
+  } catch (_) {
+    return null;
+  }
+}
+
+/** Trunca y limpia un detalle para mostrarlo en una línea. */
+function describir(item) {
+  if (typeof item === 'string') return item.slice(0, 120);
+  if (item && typeof item === 'object') {
+    const partes = [];
+    if (item.titulo)  partes.push(item.titulo);
+    if (item.canal)   partes.push(`canal=${item.canal}`);
+    if (item.linea)   partes.push(`L${item.linea}`);
+    if (item.muestra) partes.push(item.muestra);
+    if (partes.length === 0) return JSON.stringify(item).slice(0, 120);
+    return partes.join(' | ').slice(0, 120);
+  }
+  return String(item).slice(0, 120);
+}
+
+/**
+ * Construye el mensaje de nudge según el resultado.
+ */
+function construirMensaje(resultado, archivo) {
+  const { criticas, menores } = resultado;
+  if (criticas.length > 0) {
+    const lineas = [
+      '',
+      '╔══════════════════════════════════════════════════════╗',
+      '║  MEMORIA: VIOLACIÓN CRÍTICA DETECTADA                ║',
+      '╚══════════════════════════════════════════════════════╝',
+      `  Archivo modificado: ${archivo}`,
+      `  Críticas: ${criticas.length}`,
+    ];
+    for (const c of criticas.slice(0, 3)) {
+      lineas.push(`  • ${c.tipo}: ${describir(c.detalle)}`);
+    }
+    lineas.push('  Acción recomendada: revertir el cambio o sanitizar antes de commit.');
+    lineas.push('  Ver: reglas/memoria-consolidada.md');
+    lineas.push('');
+    return lineas.join('\n');
+  }
+  if (menores.length > 0) {
+    const lineas = [
+      '',
+      '⚠  Memoria: posibles violaciones de canal',
+      `   Archivo: ${archivo}  |  ${menores.length} hallazgo(s)`,
+    ];
+    for (const v of menores.slice(0, 3)) {
+      lineas.push(`   • ${v.tipo}: ${describir(v.detalle)}`);
+    }
+    if (menores.length > 3) {
+      lineas.push(`   • (y ${menores.length - 3} más — ejecutar: node scripts/validar-memoria.js)`);
+    }
+    lineas.push('   Ver: reglas/memoria-consolidada.md (canal correcto por tipo de dato)');
+    lineas.push('');
+    return lineas.join('\n');
+  }
+  return '';
+}
+
+// ---------------------------------------------------------------------------
+// Entrypoint
+// ---------------------------------------------------------------------------
+
+let inputRaw = '';
+process.stdin.on('data', chunk => { inputRaw += chunk; });
+
+process.stdin.on('end', () => {
+  try {
+    if (process.env.SWL_VALIDAR_MEMORIA === '0') return;
+
+    const data = JSON.parse(inputRaw);
+    const paths = extraerPaths(data);
+    const archivoTocado = paths.find(esArchivoMemoria);
+    if (!archivoTocado) return;
+
+    const resultado = ejecutarValidador();
+    if (!resultado) return;
+
+    const mensaje = construirMensaje(resultado, normalizar(archivoTocado));
+    if (mensaje) {
+      process.stdout.write(JSON.stringify({ systemMessage: mensaje }));
+    }
+  } catch (_) {
+    // PostToolUse no bloquea por errores internos.
+  }
+});

package/manifiestos/agent-output-schemas.json

@@ -0,0 +1,57 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "descripcion": "Schemas de output esperado por agente — formato compacto declarado en reglas/brevedad-output.md. El hook validar-formato-post-subagente.js usa estos patrones para detectar cuándo un agente devuelve output fuera de contrato.",
+  "version": "1.0.0",
+  "schemas": {
+    "revisor-codigo-swl": {
+      "descripcion": "Revisión de calidad — formato compacto",
+      "patronesRequeridos": [
+        "(?im)VEREDICTO\\s*:\\s*(APROBADO|APROBADO_CON_OBSERVACIONES|RECHAZADO|REQUIERE_CORRECCIONES|CUMPLE|PARCIAL|NO\\s+CUMPLE)",
+        "(?im)CR[IÍ]TICOS\\s*:\\s*\\d+",
+        "(?im)MAYORES\\s*:\\s*\\d+",
+        "(?im)MENORES\\s*:\\s*\\d+",
+        "(?im)HALLAZGOS\\s*:"
+      ]
+    },
+    "revisor-seguridad-swl": {
+      "descripcion": "Revisión de seguridad OWASP — formato compacto",
+      "patronesRequeridos": [
+        "(?im)VEREDICTO\\s*:\\s*(APROBADO|APROBADO_CON_OBSERVACIONES|RECHAZADO|REQUIERE_CORRECCIONES)",
+        "(?im)CR[IÍ]TICOS\\s*:\\s*\\d+",
+        "(?im)MAYORES\\s*:\\s*\\d+",
+        "(?im)HALLAZGOS\\s*:"
+      ]
+    },
+    "revisor-typescript-swl": {
+      "descripcion": "Revisión TypeScript — formato compacto",
+      "patronesRequeridos": [
+        "(?im)VEREDICTO\\s*:\\s*\\w+",
+        "(?im)CR[IÍ]TICOS\\s*:\\s*\\d+",
+        "(?im)HALLAZGOS\\s*:"
+      ]
+    },
+    "revisor-react-swl": {
+      "descripcion": "Revisión React — formato compacto",
+      "patronesRequeridos": [
+        "(?im)VEREDICTO\\s*:\\s*\\w+",
+        "(?im)CR[IÍ]TICOS\\s*:\\s*\\d+",
+        "(?im)HALLAZGOS\\s*:"
+      ]
+    },
+    "revisor-angular-swl": {
+      "descripcion": "Revisión Angular — formato compacto",
+      "patronesRequeridos": [
+        "(?im)VEREDICTO\\s*:\\s*\\w+",
+        "(?im)CR[IÍ]TICOS\\s*:\\s*\\d+",
+        "(?im)HALLAZGOS\\s*:"
+      ]
+    },
+    "tdd-qa-swl": {
+      "descripcion": "QA con TDD — reporte de implementación",
+      "patronesRequeridos": [
+        "(?im)ESTADO\\s*:\\s*(COMPLETADO|PARCIAL|BLOQUEADO)",
+        "(?im)(SLICES|TESTS)\\s*:"
+      ]
+    }
+  }
+}

package/manifiestos/hooks-config.json

@@ -81,6 +81,15 @@
       "maxConsecutiveFailures": 3,
       "degradeOnFailure": "skip"
     },
+    "validar-memoria-hook.js": {
+      "event": "PostToolUse",
+      "matcher": "Write|Edit|MultiEdit",
+      "description": "Ejecuta scripts/validar-memoria.js cuando se modifica APRENDIZAJES.md, perfil-usuario.yaml o instintos/{proyecto,global}.yaml. Emite nudge si detecta canal incorrecto, duplicación cross-canal, secretos o PII. Opt-out con SWL_VALIDAR_MEMORIA=0.",
+      "blocking": false,
+      "async": true,
+      "maxConsecutiveFailures": 3,
+      "degradeOnFailure": "skip"
+    },
     "sugerir-regenerar-inventario.js": {
       "event": "PostToolUse",
       "matcher": "Write|Edit|MultiEdit",
@@ -186,6 +195,15 @@
       "maxConsecutiveFailures": 5,
       "degradeOnFailure": "skip"
     },
+    "validar-formato-post-subagente.js": {
+      "event": "SubagentStop",
+      "matcher": "",
+      "description": "Valida output de subagentes con schema declarado en manifiestos/agent-output-schemas.json (revisor-* y tdd-qa). Registra violaciones en .planning/evolucion/formato-violaciones.jsonl. Opt-out: SWL_FORMATO_VALIDACION=0.",
+      "blocking": false,
+      "async": true,
+      "maxConsecutiveFailures": 3,
+      "degradeOnFailure": "skip"
+    },
     "telemetria-agentes.js": {
       "event": "PostToolUse",
       "matcher": "Agent",

package/manifiestos/modulos.json

@@ -835,7 +835,8 @@
         "reglas/arquitectura.md",
         "reglas/brevedad-output.md",
         "reglas/seguridad-agentes.md",
-        "reglas/memoria-consolidada.md"
+        "reglas/memoria-consolidada.md",
+        "reglas/usar-context7.md"
       ],
       "targets": [
         "claude",
@@ -856,6 +857,7 @@
         "reglas/api-diseno.md",
         "reglas/cloud-infra.md",
         "reglas/skills-estandar.md",
+        "reglas/fragmentos-compartidos.md",
         "reglas/gobernanza.md",
         "reglas/hooks.md",
         "reglas/patrones.md",
@@ -932,6 +934,8 @@
         "hooks/linea-estado.js",
         "hooks/monitor-contexto.js",
         "hooks/extraccion-aprendizajes.js",
+        "hooks/validar-memoria-hook.js",
+        "hooks/validar-formato-post-subagente.js",
         "hooks/inyeccion-contexto.js",
         "hooks/auto-consolidacion.js",
         "hooks/auto-background.js",