@saulwade/swl-ses 1.6.3 → 1.6.5

package/hooks/lib/deep-links.js

@@ -0,0 +1,185 @@
+'use strict';
+
+/**
+ * Deep Links — Helper zero-deps para construir URLs que abren archivos en
+ * IDEs y editores directamente desde notificaciones.
+ *
+ * Cubre VS Code (vscode://), VS Code Insiders, Cursor (cursor://), JetBrains
+ * (jetbrains://), Codex Desktop (codex://) y fallbacks para apps sin esquema
+ * oficial (Visual Studio en Windows usa CLI fallback).
+ *
+ * Documentación funcional y matriz de soporte en:
+ *   habilidades/agent-deep-links/SKILL.md
+ *
+ * Documentado en ADR-0029 (integración parcial awesome-codex-skills).
+ *
+ * @module hooks/lib/deep-links
+ */
+
+const path = require('node:path');
+
+/**
+ * IDEs soportados con esquema oficial confiable.
+ * Cualquier valor fuera de esta lista retorna null en construirDeepLink.
+ */
+const IDES_SOPORTADOS = Object.freeze([
+  'vscode',
+  'vscode-insiders',
+  'cursor',
+  'codex',
+  'jetbrains-idea',
+  'jetbrains-pycharm',
+  'jetbrains-webstorm',
+  'jetbrains-goland',
+  'jetbrains-rubymine',
+  'jetbrains-clion',
+  'jetbrains-rider',
+  'jetbrains-phpstorm',
+]);
+
+/**
+ * Map de IDE → esquema base. JetBrains usa formato distinto (manejado en
+ * función separada).
+ */
+const ESQUEMAS = Object.freeze({
+  'vscode':           'vscode://file',
+  'vscode-insiders':  'vscode-insiders://file',
+  'cursor':           'cursor://file',
+});
+
+/**
+ * Indica si un IDE soporta deep links a archivo:línea.
+ *
+ * @param {string} ide - Identificador del IDE.
+ * @returns {boolean}
+ */
+function soportaDeepLinks(ide) {
+  if (typeof ide !== 'string') return false;
+  return IDES_SOPORTADOS.includes(ide);
+}
+
+/**
+ * Normaliza un path absoluto para uso en deep links.
+ * - Resuelve a absoluto (rechaza relativos).
+ * - Normaliza separadores (Windows backslash → forward slash; VS Code/Cursor
+ *   aceptan forward slashes incluso en Windows).
+ * - Encoding URI para espacios y caracteres especiales.
+ *
+ * @param {string} rutaAbsoluta
+ * @returns {string|null}
+ * @private
+ */
+function _normalizarPath(rutaAbsoluta) {
+  if (typeof rutaAbsoluta !== 'string' || rutaAbsoluta.length === 0) {
+    return null;
+  }
+  if (!path.isAbsolute(rutaAbsoluta)) {
+    return null;
+  }
+  // path.resolve normaliza .., ., dobles separadores.
+  const resuelto = path.resolve(rutaAbsoluta);
+  // Forward slashes en todos los SO — los IDEs los aceptan en Windows también.
+  const forwardSlashes = resuelto.split(path.sep).join('/');
+  // encodeURI preserva : y / (los necesitamos), encodea espacios y caracteres especiales.
+  return encodeURI(forwardSlashes);
+}
+
+/**
+ * Valida que línea y columna sean enteros positivos si están definidos.
+ * @private
+ */
+function _validarPosicion(linea, columna) {
+  if (linea !== undefined && linea !== null) {
+    if (!Number.isInteger(linea) || linea < 1) return false;
+  }
+  if (columna !== undefined && columna !== null) {
+    if (!Number.isInteger(columna) || columna < 1) return false;
+  }
+  return true;
+}
+
+/**
+ * Construye un deep link para abrir un archivo en el IDE especificado.
+ *
+ * Retorna null cuando:
+ *   - El IDE no soporta deep links a archivos (Codex Desktop, Xcode, etc.).
+ *   - La ruta no es absoluta o está vacía.
+ *   - Línea/columna están definidas pero no son enteros positivos.
+ *   - El IDE es JetBrains pero falta `proyecto` (requerido).
+ *
+ * @param {object} params
+ * @param {string} params.ide - 'vscode' | 'vscode-insiders' | 'cursor' | 'jetbrains-<ide-id>'
+ * @param {string} params.rutaAbsoluta - Path absoluto al archivo. Forward o backslashes.
+ * @param {number} [params.linea] - Línea 1-indexed.
+ * @param {number} [params.columna] - Columna 1-indexed.
+ * @param {string} [params.proyecto] - Solo para JetBrains: nombre del proyecto.
+ * @returns {string|null} URL del deep link, o null si no se puede construir.
+ */
+function construirDeepLink(params) {
+  const { ide, rutaAbsoluta, linea, columna, proyecto } = params || {};
+
+  if (!soportaDeepLinks(ide)) return null;
+  if (!_validarPosicion(linea, columna)) return null;
+
+  const pathNormalizado = _normalizarPath(rutaAbsoluta);
+  if (!pathNormalizado) return null;
+
+  // JetBrains usa un formato distinto al resto.
+  if (ide.startsWith('jetbrains-')) {
+    if (!proyecto || typeof proyecto !== 'string') return null;
+    const ideId = ide.slice('jetbrains-'.length);
+    // jetbrains://idea/navigate/reference?project=<name>&path=<rel>:<line>
+    const query = new URLSearchParams({
+      project: proyecto,
+      path: linea ? `${pathNormalizado}:${linea}` : pathNormalizado,
+    }).toString();
+    return `jetbrains://${ideId}/navigate/reference?${query}`;
+  }
+
+  // VS Code / Cursor / VS Code Insiders.
+  const base = ESQUEMAS[ide];
+  let url = `${base}${pathNormalizado.startsWith('/') ? '' : '/'}${pathNormalizado}`;
+  if (linea) {
+    url += `:${linea}`;
+    if (columna) {
+      url += `:${columna}`;
+    }
+  }
+  return url;
+}
+
+/**
+ * Formato según receptor — envuelve un deep link en la sintaxis correcta del
+ * canal destino. Devuelve texto plano (con sufijo "(abrir manualmente)") si
+ * el deep link es null.
+ *
+ * @param {string|null} deepLink - URL del deep link, o null para fallback.
+ * @param {string} etiqueta - Texto visible para el usuario.
+ * @param {string} receptor - 'telegram' | 'discord' | 'slack' | 'email' | 'plain'
+ * @returns {string}
+ */
+function formatearEnlace(deepLink, etiqueta, receptor) {
+  if (!deepLink) {
+    return `${etiqueta} (abrir manualmente)`;
+  }
+  switch (receptor) {
+    case 'slack':
+      return `<${deepLink}|${etiqueta}>`;
+    case 'telegram':
+    case 'discord':
+      // Ambos usan Markdown estándar para enlaces.
+      return `[${etiqueta}](${deepLink})`;
+    case 'email':
+      return `<a href="${deepLink}">${etiqueta}</a>`;
+    case 'plain':
+    default:
+      return `${etiqueta}: ${deepLink}`;
+  }
+}
+
+module.exports = {
+  construirDeepLink,
+  formatearEnlace,
+  soportaDeepLinks,
+  IDES_SOPORTADOS,
+};

package/hooks/lib/evolution-tracker.js

@@ -345,6 +345,30 @@ function _stripEvolutionFields(content) {
     .join('\n');
 }
 
+/**
+ * Separa frontmatter YAML del body en un archivo markdown SWL.
+ *
+ * Cuando se calcula el diff de mutaciones de un archivo evolucionado, el
+ * frontmatter SIEMPRE diverge (el destino tiene campos `evolved-*` que el
+ * origen no tiene, y viceversa con campos nuevos del paquete). Contar esas
+ * diferencias como "mutaciones del usuario" genera ruido masivo por
+ * desplazamiento de líneas. Esta función permite comparar solo el body.
+ *
+ * @param {string} content - Contenido completo del archivo .md.
+ * @returns {{ frontmatter: string, body: string }}
+ *   - `frontmatter`: bloque YAML entre `---` (vacío si no hay frontmatter).
+ *   - `body`: todo lo que viene después del frontmatter cerrado.
+ * @private
+ */
+function _splitFrontmatterAndBody(content) {
+  const m = content.match(/^(---\r?\n[\s\S]*?\r?\n---\r?\n?)([\s\S]*)$/);
+  if (!m) return { frontmatter: '', body: content };
+  return { frontmatter: m[1], body: m[2] };
+}
+
+/** Umbral defensivo: tras este número de diffs el archivo pasa a modo resumen. */
+const DIFF_NOISY_THRESHOLD = 50;
+
 // ---------------------------------------------------------------------------
 // Merge de evoluciones
 // ---------------------------------------------------------------------------
@@ -356,10 +380,29 @@ function _stripEvolutionFields(content) {
  * evolución (frontmatter evolved-*). Las mutaciones de contenido se preservan
  * generando un archivo .evolved-diff.md que Claude puede re-aplicar.
  *
+ * Comparación: solo el body (post-frontmatter) se compara línea-a-línea.
+ * El frontmatter SIEMPRE diverge (el destino tiene campos `evolved-*` que el
+ * origen no tiene, y viceversa con campos nuevos del paquete), por lo que
+ * contarlo como mutación genera ruido por desplazamiento.
+ *
+ * Limpieza: cuando un merge posterior elimina la divergencia (diffs vacíos),
+ * borra el `.evolved-diff.md` huérfano de sesiones previas si existe.
+ *
+ * Cap defensivo: si tras alinear correctamente el body aún hay más de
+ * `DIFF_NOISY_THRESHOLD` líneas distintas, genera un resumen estadístico
+ * con muestra (primeras 20 + últimas 5) en lugar del dump completo.
+ *
  * @param {string} destino      - Ruta del archivo evolucionado (local).
  * @param {string} origen       - Ruta del archivo nuevo del paquete.
  * @param {string} versionNueva - Versión del paquete nuevo.
- * @returns {{ merged: boolean, diffPath?: string, error?: string }}
+ * @returns {{
+ *   merged: boolean,
+ *   diffPath?: string,
+ *   diffsCount?: number,
+ *   cleanedDiff?: boolean,
+ *   truncated?: boolean,
+ *   error?: string
+ * }}
  */
 function mergeEvolved(destino, origen, versionNueva) {
   try {
@@ -375,11 +418,14 @@ function mergeEvolved(destino, origen, versionNueva) {
     const destinoContent = fs.readFileSync(destino, 'utf8');
     const origenContent  = fs.readFileSync(origen, 'utf8');
 
-    // Extraer las líneas que son diferentes entre destino (sin evolved fields) y origen.
-    // Normalizar CRLF a LF para comparar independientemente del SO de origen.
-    const destinoSinEvo = _stripEvolutionFields(destinoContent);
-    const origenLines    = origenContent.split(/\r?\n/);
-    const destinoLines   = destinoSinEvo.split(/\r?\n/);
+    // Comparar SOLO el body, no el frontmatter. El frontmatter del destino
+    // tiene los campos `evolved-*` que el origen no tiene — contarlos como
+    // mutaciones desplaza todas las líneas siguientes y genera ruido.
+    const { body: destinoBody } = _splitFrontmatterAndBody(destinoContent);
+    const { body: origenBody  } = _splitFrontmatterAndBody(origenContent);
+
+    const origenLines  = origenBody.split(/\r?\n/);
+    const destinoLines = destinoBody.split(/\r?\n/);
 
     const diffs = [];
     const maxLen = Math.max(origenLines.length, destinoLines.length);
@@ -395,34 +441,85 @@ function mergeEvolved(destino, origen, versionNueva) {
       }
     }
 
+    const diffPath = destino.replace(/\.md$/, '.evolved-diff.md');
+
     if (diffs.length === 0) {
-      // Sin diferencias reales — solo re-aplicar campos evolved al nuevo
+      // Sin diferencias reales — limpiar diff huérfano si existe (de sesión
+      // previa donde sí hubo divergencia que ya quedó resuelta) y re-aplicar
+      // campos evolved al destino.
+      let cleanedDiff = false;
+      if (fs.existsSync(diffPath)) {
+        try {
+          fs.unlinkSync(diffPath);
+          cleanedDiff = true;
+        } catch {
+          // Best-effort: si el unlink falla por permisos/locks, dejarlo —
+          // el merge sigue siendo válido.
+        }
+      }
+
+      // force: true — `mergeEvolved` solo se invoca en contexto de update
+      // intencional. El skip de isPackageRoot() aplica a la primera marca
+      // del mantenedor, no a re-aplicar campos tras un merge resuelto.
       const marked = markAsEvolved(destino, {
         from: versionNueva,
         by: evo.metadata.evolvedBy || 'auto-evolución',
         rounds: evo.metadata.evolvedRounds ? parseInt(evo.metadata.evolvedRounds, 10) : undefined,
         score: evo.metadata.evolvedScore,
         note: `Re-aplicado desde v${evo.metadata.evolvedFrom || '?'} tras actualización a v${versionNueva}`,
+        force: true,
       });
-      return { merged: marked.marked };
+      return { merged: marked.marked, cleanedDiff };
     }
 
-    // Guardar diff para revisión/re-aplicación por Claude
-    const diffPath = destino.replace(/\.md$/, '.evolved-diff.md');
-    const diffContent = [
+    // Cap defensivo: tras alinear correctamente sigue habiendo más de N diffs.
+    // En lugar de dumpear cada línea (puede explotar a miles), generar resumen
+    // con muestra acotada.
+    const truncated = diffs.length > DIFF_NOISY_THRESHOLD;
+    const diffsParaMostrar = truncated
+      ? [...diffs.slice(0, 20), ...diffs.slice(-5)]
+      : diffs;
+
+    const header = [
       `# Diff de evolución — ${path.basename(destino)}`,
       ``,
       `**Archivo evolucionado por**: ${evo.metadata.evolvedBy || 'auto-evolución'}`,
       `**Versión base original**: ${evo.metadata.evolvedFrom || '?'}`,
       `**Versión nueva**: ${versionNueva}`,
       `**Fecha**: ${new Date().toISOString().split('T')[0]}`,
+      `**Diferencias detectadas (body)**: ${diffs.length}`,
       ``,
-      `## Mutaciones locales a re-aplicar`,
-      ``,
-      `Estas son las líneas que difieren entre la versión evolucionada y la nueva.`,
-      `Re-aplicar con \`/swl:autoresearch\` o manualmente.`,
-      ``,
-      ...diffs.map(d => [
+    ];
+
+    if (truncated) {
+      header.push(
+        `## ⚠ Resumen (truncado)`,
+        ``,
+        `El diff excede el umbral defensivo de ${DIFF_NOISY_THRESHOLD} líneas`,
+        `(${diffs.length} diferencias detectadas). Esto suele indicar:`,
+        ``,
+        `- El archivo fue reescrito completo entre versiones (rebrand, refactor).`,
+        `- El alineamiento línea-a-línea no es útil aquí — usar \`git diff\`.`,
+        ``,
+        `Se muestran las primeras 20 + últimas 5 diferencias como muestra.`,
+        `Para diff completo: \`diff <(sed '1,/^---$/d; 1,/^---$/d' archivo) <(...)\`.`,
+        ``,
+        `## Muestra de mutaciones (primeras 20 + últimas 5)`,
+        ``,
+      );
+    } else {
+      header.push(
+        `## Mutaciones locales a re-aplicar`,
+        ``,
+        `Estas son las líneas del body que difieren entre la versión`,
+        `evolucionada y la nueva. Re-aplicar con \`/swl:autoresearch\` o manualmente.`,
+        ``,
+      );
+    }
+
+    const diffContent = [
+      ...header,
+      ...diffsParaMostrar.map(d => [
         `### Línea ${d.line}`,
         `- **Nueva (base)**: \`${d.origen}\``,
         `- **Evolucionada**: \`${d.destino}\``,
@@ -432,7 +529,7 @@ function mergeEvolved(destino, origen, versionNueva) {
 
     atomicWriteSync(diffPath, diffContent, 'utf8');
 
-    return { merged: true, diffPath, diffsCount: diffs.length };
+    return { merged: true, diffPath, diffsCount: diffs.length, truncated };
   } catch (err) {
     return { merged: false, error: err.message };
   }

package/hooks/lib/gateway-notify.js

@@ -21,9 +21,23 @@ const fs   = require('fs');
 const path = require('path');
 const { atomicWriteJSON } = require('./atomic-write');
 
+// Deep links opt-in (ADR-0029). Si el módulo no carga (instalación incompleta),
+// el enriquecimiento se omite silenciosamente — comportamiento default sin
+// cambios respecto a versiones previas.
+let construirDeepLink, formatearEnlace;
+try {
+  ({ construirDeepLink, formatearEnlace } = require('./deep-links'));
+} catch {
+  construirDeepLink = () => null;
+  formatearEnlace   = (_, etiqueta) => etiqueta;
+}
+
 const COMMS_DIR = '.planning/comms';
 const CONFIG_PATH = 'manifiestos/gateway-config.json';
 
+/** Receptores reconocidos para formato de deep link. */
+const RECEPTORES = new Set(['telegram', 'discord', 'slack', 'email', 'plain']);
+
 /**
  * Verifica si el gateway está habilitado en configuración.
  * @returns {boolean}
@@ -66,10 +80,52 @@ function tipoHabilitado(tipo) {
   }
 }
 
+/**
+ * Si el payload incluye `fileRef` + `idePreferido`, retorna el enlace
+ * formateado al receptor; en otro caso retorna null. No modifica el payload.
+ *
+ * Estructura esperada del payload (opt-in, ADR-0029):
+ *   payload.fileRef = {
+ *     archivo: '/abs/path/al/archivo.js',
+ *     linea?: 42,
+ *     columna?: 8,
+ *     etiqueta?: 'Abrir archivo.js:42',   // default: archivo:linea
+ *     proyecto?: 'mi-proyecto',           // requerido solo para JetBrains
+ *   }
+ *   payload.idePreferido = 'vscode' | 'cursor' | ...
+ *
+ * @param {object} payload
+ * @param {string} receptor - 'telegram' | 'discord' | 'slack' | 'email' | 'plain'
+ * @returns {string|null}
+ * @private
+ */
+function _construirEnlaceFileRef(payload, receptor) {
+  if (!payload || !payload.fileRef || !payload.idePreferido) return null;
+  const { archivo, linea, columna, etiqueta, proyecto } = payload.fileRef;
+  if (!archivo) return null;
+
+  const url = construirDeepLink({
+    ide: payload.idePreferido,
+    rutaAbsoluta: archivo,
+    linea,
+    columna,
+    proyecto,
+  });
+
+  const label = etiqueta || (linea ? `${path.basename(archivo)}:${linea}` : path.basename(archivo));
+  const formato = RECEPTORES.has(receptor) ? receptor : 'plain';
+  return formatearEnlace(url, label, formato);
+}
+
 /**
  * Encola una notificación para el gateway.
  * No bloquea ni lanza. Retorna true si se encoló, false si fue descartada.
  *
+ * Enriquecimiento opt-in (ADR-0029): si `params.payload.fileRef` +
+ * `params.payload.idePreferido` están presentes, el mensaje agrega el campo
+ * `enlace` con un deep link formateado al receptor. Sin esos campos, el
+ * comportamiento es idéntico al previo (compatibilidad hacia atrás).
+ *
  * @param {object} params
  * @param {string} params.tipo - session-stop, checkpoint, error, release, build-fail, custom
  * @param {string} [params.titulo] - Título corto.
@@ -89,17 +145,24 @@ function notificarGateway(params) {
     }
 
     const id = `msg-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`;
+    const receptor = params.to || 'all';
+    const payloadBase = {
+      tipo:   params.tipo,
+      titulo: params.titulo || '',
+      texto:  params.texto  || '',
+      ...(params.payload || {}),
+    };
+
+    // Enriquecimiento opt-in con deep link (ADR-0029).
+    const enlace = _construirEnlaceFileRef(payloadBase, receptor);
+    if (enlace) payloadBase.enlace = enlace;
+
     const msg = {
       id,
       type:   'gateway_notification',
       from:   'swl-system',
-      to:     params.to || 'all',
-      payload: {
-        tipo:   params.tipo,
-        titulo: params.titulo || '',
-        texto:  params.texto  || '',
-        ...(params.payload || {}),
-      },
+      to:     receptor,
+      payload: payloadBase,
       text: params.texto || '',
       timestamp: new Date().toISOString(),
       status: 'pending',

package/manifiestos/modulos.json

@@ -18,6 +18,7 @@
         "agentes/depurador-swl.md",
         "agentes/documentador-swl.md",
         "agentes/resolutor-build-swl.md",
+        "agentes/gh-fix-ci-swl.md",
         "agentes/perfilador-usuario-swl.md"
       ],
       "targets": [
@@ -241,7 +242,11 @@
         "habilidades/reducir-entropia",
         "habilidades/proceso-intent-engineering",
         "habilidades/proceso-ddia-fundamentos",
-        "habilidades/proceso-ddia-streaming"
+        "habilidades/proceso-ddia-streaming",
+        "habilidades/proceso-discovery-machote",
+        "habilidades/proceso-modular-split",
+        "habilidades/agent-deep-links",
+        "habilidades/changelog-generator"
       ],
       "targets": [
         "claude",
@@ -264,7 +269,9 @@
         "habilidades/testing-python",
         "habilidades/manejo-errores",
         "habilidades/auth-patrones",
-        "habilidades/build-errors-python"
+        "habilidades/build-errors-python",
+        "habilidades/backend-error-design",
+        "habilidades/backend-async-postgres-testing"
       ],
       "targets": [
         "claude",
@@ -709,6 +716,8 @@
         "habilidades/prompt-engineering",
         "habilidades/structured-outputs",
         "habilidades/agent-browser",
+        "habilidades/browser-interaction-patterns",
+        "habilidades/browser-research-domains",
         "habilidades/wiki-conocimiento",
         "habilidades/orquestacion-async",
         "habilidades/diagrama-arquitectura",
@@ -895,7 +904,8 @@
         "reglas/analisis-previo-tareas-grandes.md",
         "reglas/registro-componentes-nuevos.md",
         "reglas/auditorias-documentales-estructurales.md",
-        "reglas/intent-engineering.md"
+        "reglas/intent-engineering.md",
+        "reglas/tests-cleanup.md"
       ],
       "targets": [
         "claude",