@saulwade/swl-ses 1.4.1 → 1.5.0

package/hooks/validar-memoria-hook.js

@@ -1,218 +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.
-  }
-});
+#!/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/instintos/prompt-appendices.yaml

@@ -1,57 +1,57 @@
-# instintos/prompt-appendices.yaml
-#
-# Catálogo de apéndices reusables para construcción dinámica de prompts/
-# instrucciones via `scripts/lib/prompt-builder.js`. Comandos `/swl:*` y
-# agentes pueden referenciar estos apéndices por nombre al construir mensajes
-# para subagentes o para output al usuario.
-#
-# Patrón adaptado de claudian (Yishen Tu, MIT) — buildSystemPrompt() con
-# apéndices declarativos.
-#
-# Schema:
-#   <nombre_apendice>: |
-#     Texto del apéndice. Puede contener placeholders {clave} que se
-#     interpolan con el contexto al construir el prompt.
-#
-# Soporta operadores YAML `>` (folded — colapsa newlines a espacios) y
-# `|` (literal — preserva newlines). Sin anidamiento profundo.
-#
-# Uso desde código:
-#   const pb = require('./scripts/lib/prompt-builder');
-#   const ap = pb.cargarApendices();
-#   const msg = pb.construirPrompt({
-#     base: 'Implementa la fase {fase}.',
-#     contexto: { fase: '03-validacion' },
-#     appendices: ['estilo_respuesta_breve', 'restricciones_dominio'],
-#     apendicesDisponibles: ap,
-#   });
-
-estilo_respuesta_breve: >
-  Responde directo y conciso. Sin preámbulos de cortesía
-  ("Por supuesto", "Claro"), sin cierres genéricos
-  ("Espero que ayude"). Resultado primero, contexto solo
-  si es no-obvio. Máximo 100 palabras salvo que la tarea
-  requiera más detalle.
-
-estilo_respuesta_detallado: >
-  Responde con detalle técnico. Incluye contexto, ejemplos
-  cuando ayuden a clarificar, y trade-offs si hay decisiones
-  no obvias. Estructura con encabezados o tablas si el
-  contenido lo justifica.
-
-restricciones_dominio: |
-  Restricciones de dominio del proyecto SWL-SES:
-  - Stack: Node.js zero-dependencies en hooks/lib/ y scripts/lib/
-  - Idioma: 100% español de México
-  - Filosofía: integración ligera y reutilización, no reescritura
-  - Antes de invocar herramientas externas opt-in, verificar disponibilidad
-    con `command -v` (Bash) o `execSync('<bin> --version', { stdio: 'ignore' })`
-    (Node) y caer al flujo nativo si no están
-
-contexto_proyecto: >
-  Proyecto: {proyecto}. Fase: {fase}. Working directory: {cwd}.
-
-referencia_planning: >
-  Antes de modificar archivos, lee `.planning/CONTEXTO.md`,
-  `.planning/ESTADO.md` y `CLAUDE.md` del proyecto. No editar
-  código que no se ha leído primero.
+# instintos/prompt-appendices.yaml
+#
+# Catálogo de apéndices reusables para construcción dinámica de prompts/
+# instrucciones via `scripts/lib/prompt-builder.js`. Comandos `/swl:*` y
+# agentes pueden referenciar estos apéndices por nombre al construir mensajes
+# para subagentes o para output al usuario.
+#
+# Patrón adaptado de claudian (Yishen Tu, MIT) — buildSystemPrompt() con
+# apéndices declarativos.
+#
+# Schema:
+#   <nombre_apendice>: |
+#     Texto del apéndice. Puede contener placeholders {clave} que se
+#     interpolan con el contexto al construir el prompt.
+#
+# Soporta operadores YAML `>` (folded — colapsa newlines a espacios) y
+# `|` (literal — preserva newlines). Sin anidamiento profundo.
+#
+# Uso desde código:
+#   const pb = require('./scripts/lib/prompt-builder');
+#   const ap = pb.cargarApendices();
+#   const msg = pb.construirPrompt({
+#     base: 'Implementa la fase {fase}.',
+#     contexto: { fase: '03-validacion' },
+#     appendices: ['estilo_respuesta_breve', 'restricciones_dominio'],
+#     apendicesDisponibles: ap,
+#   });
+
+estilo_respuesta_breve: >
+  Responde directo y conciso. Sin preámbulos de cortesía
+  ("Por supuesto", "Claro"), sin cierres genéricos
+  ("Espero que ayude"). Resultado primero, contexto solo
+  si es no-obvio. Máximo 100 palabras salvo que la tarea
+  requiera más detalle.
+
+estilo_respuesta_detallado: >
+  Responde con detalle técnico. Incluye contexto, ejemplos
+  cuando ayuden a clarificar, y trade-offs si hay decisiones
+  no obvias. Estructura con encabezados o tablas si el
+  contenido lo justifica.
+
+restricciones_dominio: |
+  Restricciones de dominio del proyecto SWL-SES:
+  - Stack: Node.js zero-dependencies en hooks/lib/ y scripts/lib/
+  - Idioma: 100% español de México
+  - Filosofía: integración ligera y reutilización, no reescritura
+  - Antes de invocar herramientas externas opt-in, verificar disponibilidad
+    con `command -v` (Bash) o `execSync('<bin> --version', { stdio: 'ignore' })`
+    (Node) y caer al flujo nativo si no están
+
+contexto_proyecto: >
+  Proyecto: {proyecto}. Fase: {fase}. Working directory: {cwd}.
+
+referencia_planning: >
+  Antes de modificar archivos, lee `.planning/CONTEXTO.md`,
+  `.planning/ESTADO.md` y `CLAUDE.md` del proyecto. No editar
+  código que no se ha leído primero.