@saulwade/swl-ses 1.0.0

package/hooks/extraccion-aprendizajes.js

@@ -0,0 +1,763 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Hook: extraccion-aprendizajes.js
+ * Tipo: PostToolUse  (aplica a: Bash, Write, Edit — al finalizar acciones del agente)
+ *
+ * Lee el output de herramientas del agente buscando patrones que indiquen
+ * un aprendizaje significativo: errores resueltos, bugs encontrados, decisiones
+ * arquitectónicas, descubrimientos de comportamiento inesperado.
+ *
+ * Si detecta un aprendizaje potencial:
+ *   1. Clasifica el tipo: anti-patrón | patrón | gotcha | decisión | bug-fix
+ *   2. Extrae el contexto (±3 líneas alrededor del keyword)
+ *   3. Verifica que no sea un duplicado de aprendizajes ya registrados
+ *   4. Escribe la entrada en .planning/APRENDIZAJES.md
+ *
+ * El hook nunca bloquea (siempre exit 0).
+ * Los errores internos se reportan en stderr y se ignoran silenciosamente.
+ *
+ * Formato de entrada en APRENDIZAJES.md:
+ * ─────────────────────────────────────────────────────────
+ * ## [YYYY-MM-DD] tipo — descripción corta
+ * **Agente**: nombre-del-agente
+ * **Contexto**: extracto del output que originó el aprendizaje
+ * ─────────────────────────────────────────────────────────
+ */
+
+const fs   = require('fs');
+const path = require('path');
+const os   = require('os');
+
+const { atomicWriteSync } = require('./lib/atomic-write');
+
+// ---------------------------------------------------------------------------
+// Constantes de configuración
+// ---------------------------------------------------------------------------
+
+/**
+ * Ruta del archivo donde se acumulan los aprendizajes.
+ * Se resuelve relativa al CWD del proceso (raíz del proyecto).
+ */
+const RUTA_APRENDIZAJES = path.join(process.cwd(), '.planning', 'APRENDIZAJES.md');
+
+/**
+ * Número de líneas de contexto a extraer alrededor del keyword detectado.
+ * El extracto será de hasta (LINEAS_CONTEXTO * 2 + 1) líneas.
+ */
+const LINEAS_CONTEXTO = 3;
+
+/**
+ * Longitud máxima del extracto de contexto a guardar (en caracteres).
+ * Evita que contextos muy largos inflen el archivo de aprendizajes.
+ */
+const MAX_CHARS_CONTEXTO = 500;
+
+/**
+ * Longitud mínima de la descripción extraída para considerarla significativa.
+ * Extractos muy cortos (< N chars) se descartan como ruido.
+ */
+const MIN_CHARS_DESCRIPCION = 40;
+
+/**
+ * Umbral de similitud para deduplicación (Jaccard sobre bigramas de palabras).
+ * Valores entre 0 y 1. Un aprendizaje con similitud >= este umbral se considera
+ * duplicado y no se escribe.
+ */
+const UMBRAL_SIMILITUD = 0.75;
+
+// ---------------------------------------------------------------------------
+// Keywords y clasificación de aprendizajes
+// ---------------------------------------------------------------------------
+
+/**
+ * Keywords que indican un aprendizaje potencial.
+ * Cada entrada define:
+ *   - keywords: términos a buscar (case-insensitive) en el output
+ *   - tipo:     categoría del aprendizaje
+ *   - peso:     prioridad al elegir entre múltiples matches en la misma línea
+ */
+const REGLAS_CLASIFICACION = [
+  {
+    keywords: ['anti-patrón', 'antipatron', 'anti patrón', 'nunca hacer', 'never do', 'bad practice'],
+    tipo: 'anti-patrón',
+    peso: 5,
+  },
+  {
+    keywords: ['bug fix', 'bugfix', 'corrección', 'corregido', 'fixed', 'se corrigió', 'arreglado'],
+    tipo: 'bug-fix',
+    peso: 5,
+  },
+  {
+    keywords: ['gotcha', 'trampa', 'cuidado con', 'ojo con', 'footgun', 'pitfall'],
+    tipo: 'gotcha',
+    peso: 4,
+  },
+  {
+    keywords: ['decisión', 'decision', 'decidimos', 'elegimos', 'optamos por', 'trade-off', 'tradeoff'],
+    tipo: 'decisión',
+    peso: 3,
+  },
+  {
+    keywords: ['patrón', 'patron', 'best practice', 'buena práctica', 'recomendado', 'siempre usar'],
+    tipo: 'patrón',
+    peso: 3,
+  },
+  {
+    keywords: ['descubrimiento', 'discovery', 'encontramos', 'hallazgo', 'aprendizaje', 'lección'],
+    tipo: 'descubrimiento',
+    peso: 2,
+  },
+  {
+    keywords: ['error', 'fallo', 'failure', 'exception', 'traceback'],
+    tipo: 'bug-fix',
+    peso: 1,
+  },
+  {
+    keywords: ['bug', 'issue', 'problema resuelto'],
+    tipo: 'bug-fix',
+    peso: 1,
+  },
+  {
+    keywords: ['fix', 'solucion', 'solución', 'resuelto', 'resolved'],
+    tipo: 'bug-fix',
+    peso: 1,
+  },
+];
+
+// ---------------------------------------------------------------------------
+// Utilidades de texto
+// ---------------------------------------------------------------------------
+
+/**
+ * Trunca un texto respetando bordes naturales: prefiere cortar al final de
+ * una oración (`. ! ?`) y si no hay, al final de una palabra (último espacio).
+ * Jamás corta a mitad de palabra ni en medio de un caracter multibyte.
+ *
+ * @param {string} texto
+ * @param {number} maxChars        Límite duro superior.
+ * @param {object} [opts]
+ * @param {number} [opts.minRatio=0.6]  Proporción mínima de maxChars que debe
+ *                                      alcanzar el punto de corte. Si un corte
+ *                                      de oración caería antes de este ratio,
+ *                                      preferimos cortar en espacio.
+ * @returns {string}               Texto truncado con '…' si se acortó.
+ */
+function truncarElegante(texto, maxChars, opts = {}) {
+  const s = String(texto || '');
+  if (s.length <= maxChars) return s;
+
+  const minRatio = typeof opts.minRatio === 'number' ? opts.minRatio : 0.6;
+  const minCorte = Math.floor(maxChars * minRatio);
+  const ventana = s.slice(0, maxChars);
+
+  // 1. Intentar corte en fin de oración (`. ! ?` seguido de espacio o fin)
+  const reOracion = /[.!?](?=\s|$)/g;
+  let ultimaOracion = -1;
+  let m;
+  while ((m = reOracion.exec(ventana)) !== null) {
+    ultimaOracion = m.index + 1; // incluir el signo de puntuación
+  }
+  if (ultimaOracion >= minCorte) {
+    return s.slice(0, ultimaOracion).trimEnd() + ' …';
+  }
+
+  // 2. Intentar corte en `,` o `;` seguido de espacio
+  const reClausula = /[,;:](?=\s)/g;
+  let ultimaClausula = -1;
+  while ((m = reClausula.exec(ventana)) !== null) {
+    ultimaClausula = m.index + 1;
+  }
+  if (ultimaClausula >= minCorte) {
+    return s.slice(0, ultimaClausula).trimEnd() + ' …';
+  }
+
+  // 3. Último recurso: último espacio antes del límite
+  const ultimoEspacio = ventana.lastIndexOf(' ');
+  if (ultimoEspacio >= minCorte) {
+    return s.slice(0, ultimoEspacio).trimEnd() + ' …';
+  }
+
+  // 4. Si la "palabra" es enorme (URL, ruta), cortar duro pero no en
+  //    medio de un code-point (trimEnd no ayuda con surrogates; usar Array.from).
+  const chars = Array.from(ventana);
+  return chars.slice(0, maxChars).join('').trimEnd() + ' …';
+}
+
+/**
+ * Construye el conjunto de bigramas de palabras de un texto.
+ * Usado para la deduplicación por similitud Jaccard.
+ *
+ * @param {string} texto
+ * @returns {Set<string>}
+ */
+function bigramasTexto(texto) {
+  const palabras = texto
+    .toLowerCase()
+    .replace(/[^\w\s]/g, ' ')
+    .split(/\s+/)
+    .filter(p => p.length > 2); // Ignorar palabras muy cortas
+
+  const bigramas = new Set();
+  for (let i = 0; i < palabras.length - 1; i++) {
+    bigramas.add(`${palabras[i]}|${palabras[i + 1]}`);
+  }
+  return bigramas;
+}
+
+/**
+ * Calcula la similitud de Jaccard entre dos conjuntos.
+ *
+ * @param {Set<string>} a
+ * @param {Set<string>} b
+ * @returns {number} Valor entre 0 (sin similitud) y 1 (idénticos).
+ */
+function similitudJaccard(a, b) {
+  if (a.size === 0 && b.size === 0) return 1;
+  if (a.size === 0 || b.size === 0) return 0;
+
+  let interseccion = 0;
+  for (const elem of a) {
+    if (b.has(elem)) interseccion++;
+  }
+  const union = a.size + b.size - interseccion;
+  return interseccion / union;
+}
+
+/**
+ * Extrae un identificador hash simple de un texto para comparación rápida
+ * antes de calcular Jaccard completo (optimización).
+ *
+ * @param {string} texto
+ * @returns {string}
+ */
+function hashTexto(texto) {
+  let hash = 0;
+  for (let i = 0; i < texto.length; i++) {
+    hash = ((hash << 5) - hash + texto.charCodeAt(i)) | 0;
+  }
+  return String(hash >>> 0);
+}
+
+// ---------------------------------------------------------------------------
+// Normalización de fechas relativas (patrón autoDream)
+// ---------------------------------------------------------------------------
+
+/**
+ * Mapa de expresiones relativas en español a funciones de cálculo.
+ * Convierte "ayer", "hace 2 días", etc. a fechas absolutas YYYY-MM-DD.
+ */
+const PATRONES_FECHA_RELATIVA = [
+  { regex: /\bhoy\b/gi,                         calc: () => 0 },
+  { regex: /\bayer\b/gi,                         calc: () => -1 },
+  { regex: /\banteayer\b/gi,                     calc: () => -2 },
+  { regex: /\bhace\s+(\d+)\s+días?\b/gi,        calc: (m) => -parseInt(m[1], 10) },
+  { regex: /\bhace\s+(\d+)\s+semanas?\b/gi,     calc: (m) => -parseInt(m[1], 10) * 7 },
+  { regex: /\bla\s+semana\s+pasada\b/gi,        calc: () => -7 },
+  { regex: /\bhace\s+(\d+)\s+meses?\b/gi,       calc: (m) => -parseInt(m[1], 10) * 30 },
+  { regex: /\bel\s+mes\s+pasado\b/gi,           calc: () => -30 },
+];
+
+/**
+ * Reemplaza fechas relativas en un texto por fechas absolutas YYYY-MM-DD.
+ * Preserva el texto original si no hay coincidencias.
+ *
+ * @param {string} texto - Texto con posibles fechas relativas.
+ * @param {Date} [ahora] - Fecha de referencia (default: Date.now()).
+ * @returns {string} Texto con fechas absolutas.
+ */
+function normalizarFechas(texto, ahora = new Date()) {
+  let resultado = texto;
+
+  for (const { regex, calc } of PATRONES_FECHA_RELATIVA) {
+    resultado = resultado.replace(regex, (...args) => {
+      const diasOffset = calc(args);
+      const fecha = new Date(ahora);
+      fecha.setDate(fecha.getDate() + diasOffset);
+      return fecha.toISOString().slice(0, 10); // YYYY-MM-DD
+    });
+  }
+
+  return resultado;
+}
+
+// ---------------------------------------------------------------------------
+// Extracción del texto a analizar
+// ---------------------------------------------------------------------------
+
+/**
+ * Extrae el texto relevante del payload del hook para analizar en busca
+ * de aprendizajes. Soporta múltiples estructuras que Claude Code puede enviar.
+ *
+ * @param {object} data - Payload JSON del hook.
+ * @returns {{ texto: string, agente: string }}
+ */
+function extraerTextoYAgente(data) {
+  const toolName   = String(data.tool_name   || data.tool?.name || '');
+  const toolResult = data.tool_result || data.tool?.result || {};
+  const toolInput  = data.tool_input  || data.tool?.input  || {};
+
+  // Nombre del agente: preferir session_id o model; fallback a tool_name
+  const agente = String(
+    data.agent_name ||
+    data.session_id ||
+    data.model      ||
+    toolName        ||
+    'agente-desconocido'
+  ).slice(0, 60);
+
+  // Recolectar fragmentos de texto del resultado de la herramienta
+  const fragmentos = [];
+
+  // Resultado puede ser string directo
+  if (typeof toolResult === 'string') {
+    fragmentos.push(toolResult);
+  }
+
+  // Resultado puede ser objeto con campo "output", "content", "stdout", etc.
+  if (toolResult && typeof toolResult === 'object') {
+    const camposResultado = ['output', 'content', 'stdout', 'text', 'result', 'message'];
+    for (const campo of camposResultado) {
+      if (typeof toolResult[campo] === 'string') {
+        fragmentos.push(toolResult[campo]);
+      }
+    }
+  }
+
+  // Para herramientas Write/Edit, analizar el contenido que se escribió
+  if (['Write', 'Edit'].includes(toolName)) {
+    const contenido = toolInput.content || toolInput.new_string || '';
+    if (typeof contenido === 'string' && contenido.length > 0) {
+      // Solo analizar comentarios y docstrings del código, no el código mismo
+      const lineasComentario = contenido
+        .split('\n')
+        .filter(l => /^\s*(#|\/\/|\/\*|\*|"""|''')/.test(l))
+        .join('\n');
+      if (lineasComentario) fragmentos.push(lineasComentario);
+    }
+  }
+
+  // Leer también de stdin si hay datos adicionales (modo pipe directo)
+  const texto = fragmentos.join('\n\n').slice(0, 50_000); // Límite de 50KB para análisis
+
+  return { texto, agente };
+}
+
+// ---------------------------------------------------------------------------
+// Detección y clasificación de aprendizajes
+// ---------------------------------------------------------------------------
+
+/**
+ * Resultado de analizar el texto en busca de aprendizajes.
+ * @typedef {{ tipo: string, contexto: string, descripcion: string }} Aprendizaje
+ */
+
+/**
+ * Analiza el texto del output del agente buscando aprendizajes significativos.
+ * Retorna el aprendizaje más relevante encontrado, o null si no hay ninguno.
+ *
+ * Estrategia:
+ *   1. Buscar keywords de mayor peso primero.
+ *   2. Para cada match, extraer contexto de ±LINEAS_CONTEXTO líneas.
+ *   3. Verificar longitud mínima del contexto.
+ *   4. Clasificar por el tipo de keyword que disparó la detección.
+ *
+ * @param {string} texto
+ * @returns {Aprendizaje|null}
+ */
+function detectarAprendizaje(texto) {
+  if (!texto || texto.trim().length < MIN_CHARS_DESCRIPCION) return null;
+
+  const lineas = texto.split('\n');
+
+  // Ordenar reglas de mayor a menor peso para priorizar los más significativos
+  const reglasPorPeso = [...REGLAS_CLASIFICACION].sort((a, b) => b.peso - a.peso);
+
+  for (const { keywords, tipo } of reglasPorPeso) {
+    for (const keyword of keywords) {
+      const patronKeyword = new RegExp(keyword, 'i');
+
+      for (let i = 0; i < lineas.length; i++) {
+        if (!patronKeyword.test(lineas[i])) continue;
+
+        // Extraer contexto alrededor de la línea con el keyword
+        const inicio    = Math.max(0, i - LINEAS_CONTEXTO);
+        const fin       = Math.min(lineas.length, i + LINEAS_CONTEXTO + 1);
+        const contexto  = lineas.slice(inicio, fin).join('\n').trim();
+
+        // Verificar longitud mínima significativa
+        if (contexto.length < MIN_CHARS_DESCRIPCION) continue;
+
+        // Truncar el contexto respetando bordes de oración/palabra
+        const contextoFinal = truncarElegante(contexto, MAX_CHARS_CONTEXTO);
+
+        // Descripción: la línea del keyword, limpiada de símbolos de código.
+        // Preferir cortar al final de la primera oración si cabe en 120 chars;
+        // si no, al último espacio antes del límite.
+        const lineaLimpia = lineas[i]
+          .trim()
+          .replace(/^[#*\/\-–•]+\s*/, '') // Quitar prefijos de comentario/lista
+          .replace(/\*\*/g, '')            // Quitar marcadores de negrita Markdown
+          .replace(/`+/g, '');             // Quitar backticks
+
+        // Si la línea tiene un punto temprano, usarlo como fin natural
+        const matchOracion = lineaLimpia.match(/^[^.!?]*[.!?]/);
+        const descripcionBase = matchOracion
+          ? matchOracion[0].trim()
+          : lineaLimpia;
+
+        const descripcion = truncarElegante(descripcionBase, 120, { minRatio: 0.4 });
+
+        if (descripcion.length < 10) continue;
+
+        return { tipo, contexto: contextoFinal, descripcion };
+      }
+    }
+  }
+
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Gestión del archivo APRENDIZAJES.md
+// ---------------------------------------------------------------------------
+
+/**
+ * Lee las entradas existentes en APRENDIZAJES.md.
+ * Retorna el contenido completo y una lista de descripciones para deduplicar.
+ *
+ * @returns {{ contenidoExistente: string, descripciones: string[] }}
+ */
+function leerAprendizajesExistentes() {
+  try {
+    const contenido = fs.readFileSync(RUTA_APRENDIZAJES, 'utf8');
+    // Extraer las líneas de descripción corta (las que empiezan con "##")
+    const descripciones = contenido
+      .split('\n')
+      .filter(l => l.startsWith('## '))
+      .map(l => l.replace(/^##\s+\[\d{4}-\d{2}-\d{2}\]\s+\w+[-\w]*\s+—\s+/, '').trim());
+
+    return { contenidoExistente: contenido, descripciones };
+  } catch (_) {
+    // El archivo no existe aún — primera ejecución
+    return { contenidoExistente: '', descripciones: [] };
+  }
+}
+
+/**
+ * Verifica si un aprendizaje candidato ya existe en el archivo,
+ * usando similitud de Jaccard sobre bigramas para detectar duplicados
+ * semánticamente similares aunque no idénticos.
+ *
+ * @param {string} descripcion       - Descripción del aprendizaje candidato.
+ * @param {string[]} descripciones   - Descripciones existentes en el archivo.
+ * @returns {boolean} true si el aprendizaje ya existe (o es muy similar).
+ */
+function esDuplicado(descripcion, descripciones) {
+  if (descripciones.length === 0) return false;
+
+  const bigramasNuevo = bigramasTexto(descripcion);
+
+  for (const desc of descripciones) {
+    const bigramasExistente = bigramasTexto(desc);
+    const similitud = similitudJaccard(bigramasNuevo, bigramasExistente);
+    if (similitud >= UMBRAL_SIMILITUD) return true;
+  }
+
+  return false;
+}
+
+/**
+ * Asegura que el directorio padre de RUTA_APRENDIZAJES existe.
+ * Crea el directorio .planning/ si no existe.
+ */
+function asegurarDirectorio() {
+  const dir = path.dirname(RUTA_APRENDIZAJES);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+}
+
+/**
+ * Escribe el encabezado inicial del archivo APRENDIZAJES.md si está vacío.
+ *
+ * @param {string} contenidoExistente
+ * @returns {string} Contenido actualizado con encabezado.
+ */
+function asegurarEncabezado(contenidoExistente) {
+  if (contenidoExistente.length > 0) return contenidoExistente;
+
+  return [
+    '# Aprendizajes del Sistema',
+    '',
+    'Registro automático de aprendizajes extraídos por el hook `extraccion-aprendizajes.js`.',
+    'Cada entrada describe un anti-patrón, patrón, gotcha, bug-fix o decisión detectada',
+    'durante la ejecución de agentes en el proyecto.',
+    '',
+    '---',
+    '',
+  ].join('\n');
+}
+
+/**
+ * Formatea una entrada de aprendizaje para insertar en el archivo.
+ *
+ * @param {string} fecha       - Fecha en formato YYYY-MM-DD.
+ * @param {string} tipo        - Tipo del aprendizaje.
+ * @param {string} descripcion - Descripción corta.
+ * @param {string} agente      - Nombre/ID del agente que generó el aprendizaje.
+ * @param {string} contexto    - Extracto del output del agente.
+ * @returns {string}
+ */
+function formatearEntrada(fecha, tipo, descripcion, agente, contexto) {
+  // Indentar el contexto para que se muestre como blockquote en Markdown
+  const contextoIndentado = contexto
+    .split('\n')
+    .map(l => `> ${l}`)
+    .join('\n');
+
+  // Markdown válido requiere líneas en blanco antes de ## y antes/después de ---
+  return [
+    '',
+    `## [${fecha}] ${tipo} — ${descripcion}`,
+    '',
+    `**Agente**: \`${agente}\``,
+    '',
+    `**Contexto**:`,
+    '',
+    contextoIndentado,
+    '',
+    '---',
+    '',
+  ].join('\n');
+}
+
+/**
+ * Escribe un nuevo aprendizaje al final del archivo APRENDIZAJES.md.
+ *
+ * @param {Aprendizaje} aprendizaje
+ * @param {string} agente
+ */
+function escribirAprendizaje(aprendizaje, agente) {
+  asegurarDirectorio();
+
+  const { contenidoExistente, descripciones } = leerAprendizajesExistentes();
+
+  // Verificar duplicado antes de escribir
+  if (esDuplicado(aprendizaje.descripcion, descripciones)) {
+    // Aprendizaje duplicado — omitido silenciosamente
+    return;
+  }
+
+  const fecha         = new Date().toISOString().slice(0, 10); // YYYY-MM-DD
+  const contenidoBase = asegurarEncabezado(contenidoExistente);
+
+  // Normalizar fechas relativas a absolutas (patrón autoDream)
+  const descripcionNorm = normalizarFechas(aprendizaje.descripcion);
+  const contextoNorm    = normalizarFechas(aprendizaje.contexto);
+
+  const entrada       = formatearEntrada(
+    fecha,
+    aprendizaje.tipo,
+    descripcionNorm,
+    agente,
+    contextoNorm
+  );
+
+  atomicWriteSync(RUTA_APRENDIZAJES, contenidoBase + entrada);
+
+  // Aprendizaje registrado silenciosamente
+}
+
+// ---------------------------------------------------------------------------
+// Filtros de señal vs. ruido
+// ---------------------------------------------------------------------------
+
+/**
+ * Determina si el evento del hook proviene de una herramienta cuyo output
+ * vale la pena analizar para extraer aprendizajes.
+ *
+ * Se excluyen herramientas puramente de lectura y de estado
+ * que generan mucho ruido sin información nueva.
+ *
+ * @param {string} toolName
+ * @returns {boolean}
+ */
+function esHerramientaRelevante(toolName) {
+  const HERRAMIENTAS_EXCLUIDAS = new Set([
+    'Read',   // Lectura pura — sin aprendizajes del agente
+    'Glob',   // Listado de archivos
+    'Grep',   // Búsqueda — output técnico sin narrativa
+  ]);
+  return !HERRAMIENTAS_EXCLUIDAS.has(toolName);
+}
+
+/**
+ * Rutas de archivos SWL donde Write/Edit NO debe generar aprendizajes.
+ * Editar contenido de skills, reglas, APRENDIZAJES, ADRs, etc. es
+ * mantenimiento del sistema SWL, no descubrimiento en tiempo de ejecución.
+ * Capturar fragmentos de esos archivos produce ruido auto-referente.
+ */
+const PATRONES_ARCHIVO_SWL_EXCLUIDO = [
+  /[\\/]habilidades[\\/]/,
+  /[\\/]agentes[\\/]/,
+  /[\\/]reglas[\\/]/,
+  /[\\/]comandos[\\/]swl[\\/]/,
+  /[\\/]hooks[\\/]/,
+  /[\\/]scripts[\\/]/,
+  /[\\/]schemas[\\/]/,
+  /[\\/]manifiestos[\\/]/,
+  /[\\/]plantillas[\\/]/,
+  /[\\/]contextos[\\/]/,
+  /[\\/]instintos[\\/]/,
+  // Todo .planning/ salvo wiki/ (que puede contener conocimiento del proyecto usuario).
+  // En swl-ses .planning/ es meta del sistema; los aprendizajes se gestionan manualmente.
+  /[\\/]\.planning[\\/](?!wiki[\\/])/,
+  /[\\/]CHANGELOG\.md$/i,
+  /[\\/]CLAUDE\.md$/i,
+  /[\\/]AGENTS\.md$/i,
+  /[\\/]README\.md$/i,
+  /[\\/]MANUAL_USO\.md$/i,
+  /[\\/]COMANDOS\.md$/i,
+  /[\\/]INSTALACION\.md$/i,
+  /[\\/]INVENTARIO\.md$/i,
+  /[\\/]SALUD\.md$/i,
+  /[\\/]package\.json$/,
+  /[\\/]plugin\.json$/,
+  /[\\/]package-lock\.json$/,
+];
+
+/**
+ * Determina si el target de Write/Edit es un archivo del sistema SWL
+ * donde la edición es mantenimiento, no descubrimiento. Previene ruido
+ * auto-referente (capturar fragmentos de SKILL.md propios como "aprendizajes").
+ *
+ * @param {string} filePath
+ * @returns {boolean}
+ */
+function esArchivoSwlExcluido(filePath) {
+  if (!filePath || typeof filePath !== 'string') return false;
+  return PATRONES_ARCHIVO_SWL_EXCLUIDO.some(rx => rx.test(filePath));
+}
+
+/**
+ * Detecta si un fragmento parece ser contenido estructurado de skill/regla
+ * (frontmatter YAML, encabezados ## NN, tablas markdown grandes) en vez de
+ * un aprendizaje narrativo genuino. Filtro final antes de persistir.
+ *
+ * @param {string} contexto
+ * @returns {boolean} true si el fragmento parece estructural (descartar)
+ */
+function pareceContenidoEstructuralSwl(contexto) {
+  if (!contexto) return false;
+  const lineas = contexto.split('\n');
+
+  // Frontmatter YAML: ---\nname: ...\ndescription: ...\n---
+  if (lineas.some(l => /^---\s*$/.test(l)) && lineas.some(l => /^(name|description|version|evolved):/i.test(l))) {
+    return true;
+  }
+
+  // Tabla markdown dominante: más del 50% de líneas no vacías son filas de tabla
+  const noVacias = lineas.filter(l => l.trim().length > 0);
+  const filas = noVacias.filter(l => /^\|.*\|/.test(l));
+  if (noVacias.length > 0 && filas.length / noVacias.length > 0.5) {
+    return true;
+  }
+
+  // Enumeración de encabezados sin cuerpo sustantivo
+  // (3+ líneas tipo "## [fecha] tipo — descripción" juntas)
+  const encabezadosFecha = lineas.filter(l => /^##\s+\[\d{4}-\d{2}-\d{2}\]/.test(l));
+  if (encabezadosFecha.length >= 2) {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Determina si el texto tiene suficiente contenido narrativo para contener
+ * un aprendizaje significativo (vs. output técnico puro como stack traces
+ * o listados de archivos).
+ *
+ * Heurística: el ratio de palabras largas (>4 chars) sobre el total
+ * indica prosa vs. código/rutas.
+ *
+ * @param {string} texto
+ * @returns {boolean}
+ */
+function tieneContenidoNarrativo(texto) {
+  if (texto.length < MIN_CHARS_DESCRIPCION) return false;
+
+  const palabras         = texto.split(/\s+/).filter(p => p.length > 0);
+  const palabrasLargas   = palabras.filter(p => p.length > 4);
+  const ratioNarrativo   = palabras.length > 0 ? palabrasLargas.length / palabras.length : 0;
+
+  // Al menos 30% de palabras largas sugiere prosa con contenido semántico
+  return ratioNarrativo >= 0.30 && palabras.length >= 10;
+}
+
+// ---------------------------------------------------------------------------
+// Entrypoint principal
+// ---------------------------------------------------------------------------
+
+let inputRaw = '';
+
+process.stdin.on('data', chunk => {
+  inputRaw += chunk;
+});
+
+process.stdin.on('end', () => {
+  try {
+    const data = JSON.parse(inputRaw);
+
+    const toolName = String(data.tool_name || data.tool?.name || '');
+
+    // Filtrar herramientas que generan ruido sin aprendizajes
+    if (!esHerramientaRelevante(toolName)) {
+      return;
+    }
+
+    // Filtrar Write/Edit sobre archivos del sistema SWL (auto-referencia).
+    // Editar habilidades/, agentes/, reglas/, CHANGELOG, CLAUDE.md, etc. es
+    // mantenimiento del sistema, no descubrimiento en tiempo de ejecución.
+    if (toolName === 'Write' || toolName === 'Edit' || toolName === 'MultiEdit') {
+      const toolInput = data.tool_input || data.tool?.input || {};
+      const filePath = String(toolInput.file_path || toolInput.path || '');
+      if (esArchivoSwlExcluido(filePath)) {
+        return;
+      }
+    }
+
+    // Extraer texto y nombre del agente del payload
+    const { texto, agente } = extraerTextoYAgente(data);
+
+    // Verificar que el texto tiene contenido narrativo suficiente
+    if (!tieneContenidoNarrativo(texto)) {
+      return;
+    }
+
+    // Detectar aprendizaje en el texto
+    const aprendizaje = detectarAprendizaje(texto);
+
+    if (!aprendizaje) {
+      // Sin aprendizaje detectado — salir silenciosamente
+      return;
+    }
+
+    // Filtro final: descartar si el contexto parece estructural (frontmatter
+    // YAML, tablas markdown, enumeración de encabezados sin cuerpo). Previene
+    // que fragmentos de skills/reglas se persistan como aprendizajes.
+    if (pareceContenidoEstructuralSwl(aprendizaje.contexto)) {
+      return;
+    }
+
+    // Escribir el aprendizaje (incluye deduplicación interna)
+    escribirAprendizaje(aprendizaje, agente);
+
+    // PostToolUse: no escribir a stdout — salida limpia.
+
+  } catch (err) {
+    // No escribir a stderr — Claude Code lo reporta como hook error
+  }
+});