@saulwade/swl-ses 1.0.1 → 1.1.2

package/habilidades/release-semver/.evolved.json

@@ -1,9 +1,9 @@
-{
-  "SKILL.md": {
-    "evolved": true,
-    "evolvedFrom": "5.10.4",
-    "evolvedAt": "2026-04-20",
-    "evolvedBy": "aprender",
-    "evolvedNote": "npx @latest en post-install"
-  }
+{
+  "SKILL.md": {
+    "evolved": true,
+    "evolvedFrom": "1.0.1",
+    "evolvedAt": "2026-05-02",
+    "evolvedBy": "aprender",
+    "evolvedNote": "Sección nueva: publish a múltiples registries (republish-only + auth GitHub Packages)"
+  }
 }

package/habilidades/release-semver/SKILL.md

@@ -1,7 +1,12 @@
 ---
 name: release-semver
 description: Versionado semántico (SemVer). Cuándo bumpar major/minor/patch, changelogs convencionales, estrategia de tags y proceso de release completo.
-version: "1.0.1"
+version: "1.0.2"
+evolved: true
+evolved-from: "1.0.1"
+evolved-at: "2026-05-02"
+evolved-by: "aprender"
+evolved-note: "Sección nueva: publish a múltiples registries (npmjs + GitHub Packages) — republish-only pattern y auth GitHub Packages no soporta npm login"
 herramientasPermitidas: [Read, Bash]
 exclusiones:
   - "No cargar para versionar el sistema SWL — el bump de versión de swl-ses sigue el checklist de 15 ubicaciones documentado en `/swl:release`; este skill cubre SemVer general para proyectos de usuario, no el proceso interno de release del sistema."
@@ -209,6 +214,85 @@ git describe --tags --abbrev=0    # Último tag del commit actual
 
 ---
 
+## Publish a múltiples registries (mirror dual)
+
+Cuando un paquete se publica al mismo tiempo en dos registries (típicamente
+npmjs.org como canónico y GitHub Packages como mirror), la coordinación de
+versiones tiene reglas distintas a un publish simple.
+
+### NUNCA: reintentar la misma versión cuando uno de los registries ya la aceptó
+
+**Problema**: el publish dual falló en uno de los dos registries pero el otro
+quedó publicado correctamente. La intuición lleva a "republicar la misma versión"
+después de arreglar el problema. Esto NO funciona: ningún registry permite
+sobreescribir una versión ya publicada (es la garantía de inmutabilidad de
+paquetes). El publish al registry que ya tiene esa versión devuelve:
+
+```
+npm error You cannot publish over the previously published versions: X.Y.Z
+```
+
+```
+# MAL — reintentar 1.1.0 porque GitHub Packages la tiene pero npmjs no
+npm publish --registry=https://registry.npmjs.org/        # podría funcionar
+npm publish --registry=https://npm.pkg.github.com         # FALLA: ya existe 1.1.0
+```
+
+```
+# BIEN — bumpear PATCH y publicar solo al registry faltante
+# 1.1.0 → 1.1.1 en package.json + plugin.json + lock + headers de docs
+node scripts/publicar.js --solo-npmjs                     # solo al que falta
+```
+
+**Regla**: si un publish dual falla en el registry A pero queda publicado en B,
+bumpear PATCH inmediatamente y publicar solo a A. Documentar en CHANGELOG que
+es un republish exclusivo de coordinación entre registries (sin cambios funcionales).
+
+### NUNCA: usar `npm login` con GitHub Packages
+
+**Problema**: GitHub Packages NO soporta `npm login` (ni el flujo web OAuth ni el
+fallback CouchDB de creación de usuarios). Ejecutar `npm login --registry=https://npm.pkg.github.com`
+devuelve 404 en `/-/v1/login` y luego 403 en el `PUT /-/user/...`. La autenticación
+a GitHub Packages se hace EXCLUSIVAMENTE con un Personal Access Token de GitHub
+configurado como `_authToken` directamente en `~/.npmrc`.
+
+```bash
+# MAL — esto siempre devuelve 403
+npm login --registry=https://npm.pkg.github.com
+
+# BIEN — agregar el PAT al ~/.npmrc manualmente
+echo "//npm.pkg.github.com/:_authToken=ghp_xxxxxxxx" >> ~/.npmrc
+npm whoami --registry=https://npm.pkg.github.com   # → tu-usuario-github
+```
+
+El token requiere los scopes `read:packages` y `write:packages` en GitHub
+(Settings → Developer settings → Personal access tokens).
+
+### SIEMPRE: diagnosticar auth con `npm whoami` antes de `npm login`
+
+**Cuándo aplicar**: cuando un publish falla con "no autenticado" o 401/403.
+**Beneficio**: distingue entre "sin token", "token expirado", "cuenta sin permiso
+al scope" y "registry equivocado" sin abrir el flujo interactivo de login.
+
+```bash
+# Diagnóstico estructurado
+npm whoami --registry=https://registry.npmjs.org/
+
+# Resultado posible 1: nombre de usuario → autenticado correctamente
+# Resultado posible 2: 401 Unauthorized → token expirado/inválido
+#   → fix: npm login --registry=https://registry.npmjs.org/
+# Resultado posible 3: 404 → registry incorrecto
+# Resultado posible 4: nombre distinto al esperado → cuenta sin permiso
+#   → fix: verificar dueño del scope con
+#     npm owner ls @scope/paquete --registry=https://registry.npmjs.org/
+```
+
+Ningún publisher debería hacer `npm login` sin antes hacer `npm whoami`. El whoami
+es no-destructivo y revela la causa raíz; el login interactivo solo cubre el caso
+de token inválido.
+
+---
+
 ## Herramientas recomendadas
 
 | Herramienta            | Uso                                          |

package/hooks/auto-evolucion.js

@@ -42,6 +42,15 @@
 const fs   = require('fs');
 const path = require('path');
 
+// Escritura atómica obligatoria para estado mutable (regla CLAUDE.md).
+// Fallback defensivo si el módulo no existe en el destino.
+let atomicWriteJSON;
+try {
+  ({ atomicWriteJSON } = require('./lib/atomic-write'));
+} catch {
+  atomicWriteJSON = (p, obj) => fs.writeFileSync(p, JSON.stringify(obj, null, 2), 'utf8');
+}
+
 let nudgeTracker;
 try {
   nudgeTracker = require('./lib/nudge-tracker');
@@ -70,6 +79,13 @@ try {
   driftDetector = null;
 }
 
+let agentRouting;
+try {
+  agentRouting = require('./lib/agent-routing');
+} catch {
+  agentRouting = null;
+}
+
 let singletonGuard;
 try {
   singletonGuard = require('./lib/singleton-guard');
@@ -120,7 +136,7 @@ function leerNudges() {
 function escribirNudges(obj) {
   ensureDir(DIR_AUTOEVOL);
   try {
-    fs.writeFileSync(NUDGES_PATH, JSON.stringify(obj, null, 2), 'utf8');
+    atomicWriteJSON(NUDGES_PATH, obj);
   } catch { /* ignore */ }
 }
 
@@ -196,6 +212,21 @@ function analizarPayload(data) {
     ? clasificarTipoFallo(data, response)
     : null;
 
+  // Inferir fase/dominio del frontmatter del agente para routing precision
+  // (ADR 0012). Si el agente no tiene frontmatter o no se encuentra el archivo,
+  // los campos quedan null y la métrica simplemente no cuenta esa entrada.
+  let routedPhase = null;
+  let routedDomain = null;
+  let routingSource = 'unknown';
+  if (agentRouting) {
+    try {
+      const r = agentRouting.getRouting(subagentType);
+      routedPhase   = r.fase;
+      routedDomain  = r.dominio;
+      routingSource = r.source;
+    } catch { /* no bloquear por fallo en routing inference */ }
+  }
+
   return {
     ts: new Date().toISOString(),
     sessionId: String(data.session_id || 'default'),
@@ -205,6 +236,9 @@ function analizarPayload(data) {
     trivial: toolCalls > 0 && toolCalls < MIN_TOOL_CALLS,
     duracionMs,
     tipo_fallo: tipoFallo,
+    routed_phase:   routedPhase,
+    routed_domain:  routedDomain,
+    routing_source: routingSource,
   };
 }
 

package/hooks/clasificador-mensajes.js

@@ -11,14 +11,31 @@
  * arquitectura, seguridad, performance, refactor, documentación.
  *
  * Inspirado en obsidian-mind classify-message.py.
- * Zero-dependencies: regex puro en JS.
+ * Zero-dependencies: regex puro en JS + lib propia text-similarity.js.
  *
  * Resultado:
  *   - Señales detectadas → hookSpecificOutput con hints de routing
  *   - Sin señales → exit 0 silencioso
  *   - Error interno → exit 0 silencioso (nunca bloquear)
+ *
+ * Opt-in opcional:
+ *   - SWL_FUZZY_CLASIFICADOR=1 activa fuzzy matching (Levenshtein + stem ES)
+ *     como SEGUNDA pasada cuando regex no detectó señales. NUNCA degrada
+ *     señales del regex original. Útil para typos y variantes morfológicas
+ *     ("documentar" → matches "documentación"). Costo: ~5-15ms por prompt.
  */
 
+const path = require('path');
+const FUZZY_HABILITADO = process.env.SWL_FUZZY_CLASIFICADOR === '1';
+let textSim = null;
+if (FUZZY_HABILITADO) {
+  try {
+    textSim = require(path.join(__dirname, 'lib', 'text-similarity'));
+  } catch (_) {
+    // Si la lib no existe, fuzzy se desactiva silenciosamente
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Mapa de complejidad de tarea → modelo recomendado
 //
@@ -212,22 +229,52 @@ function anyMatch(patterns, text) {
   return false;
 }
 
+/**
+ * Verifica si algún patrón aparece de forma aproximada (fuzzy) en el texto.
+ * Usa Levenshtein + stem español. Solo se invoca si SWL_FUZZY_CLASIFICADOR=1.
+ * NO se llama si `anyMatch` ya devolvió true para esa señal — fuzzy es
+ * fallback puro, no reemplazo.
+ *
+ * @param {string[]} patterns
+ * @param {string} text - texto original (no lowercase necesariamente)
+ * @returns {boolean}
+ */
+function anyMatchFuzzy(patterns, text) {
+  if (!textSim) return false;
+  for (const phrase of patterns) {
+    // Solo aplicar fuzzy a patterns de palabra única o frase corta.
+    // Patterns de >3 palabras tienden a generar falsos positivos.
+    const tokens = phrase.split(/\s+/).filter(Boolean);
+    if (tokens.length > 3) continue;
+    if (textSim.fuzzyContains(text, phrase)) return true;
+  }
+  return false;
+}
+
 /**
  * Clasifica el mensaje del usuario.
  * @param {string} prompt
- * @returns {{ hints: string[], signalNames: string[] }}
+ * @returns {{ hints: string[], signalNames: string[], fuzzyAdded: number }}
  */
 function classify(prompt) {
   const text = (prompt || '').toLowerCase();
   const hints = [];
   const signalNames = [];
+  let fuzzyAdded = 0;
+
   for (const sig of SIGNALS) {
     if (anyMatch(sig.patterns, text)) {
       hints.push(sig.hint);
       signalNames.push(sig.name);
+    } else if (FUZZY_HABILITADO && anyMatchFuzzy(sig.patterns, text)) {
+      // Fuzzy detectó algo que el regex perdió — marca con [fuzzy] para
+      // observabilidad
+      hints.push(sig.hint + ' [match aproximado]');
+      signalNames.push(sig.name);
+      fuzzyAdded++;
     }
   }
-  return { hints, signalNames };
+  return { hints, signalNames, fuzzyAdded };
 }
 
 // ---------------------------------------------------------------------------

package/hooks/lib/agent-routing.js

@@ -0,0 +1,107 @@
+'use strict';
+
+/**
+ * agent-routing.js — Helper para inferir fase y dominio del routing.
+ *
+ * Lee el frontmatter del agente (agentes/<nombre>.md) y extrae los campos
+ * `fase` y `dominio` introducidos en v1.1.0 (ADR 0012). El orquestador no
+ * registra explícitamente "qué fase/dominio motivó la elección" — pero
+ * cuando elige un agente, podemos asumir que lo eligió porque su fase y
+ * dominio matcheaban. Por lo tanto, leer el frontmatter del agente
+ * efectivamente invocado nos da la celda fase×dominio del routing.
+ *
+ * Esto es proxy de precisión, no precisión absoluta:
+ *   - Tasa de éxito por celda (fase, dominio) sirve como indicador de
+ *     que el routing está enviando trabajo correctamente al agente
+ *     adecuado.
+ *   - Una celda con tasa de éxito baja sugiere routing impreciso (el
+ *     agente recibe trabajo que no le compete) o agente sub-óptimo.
+ *
+ * Cache simple en memoria del proceso para evitar I/O repetida (cada
+ * invocación de hook es proceso fresco, así que el cache no persiste,
+ * pero protege dentro de la misma invocación).
+ *
+ * @module hooks/lib/agent-routing
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+const _cache = Object.create(null);
+
+/**
+ * Resuelve la ruta del archivo de agente. Acepta tanto el repo madre como
+ * proyectos consumidores (donde los agentes pueden estar en otras rutas).
+ *
+ * @param {string} agentName - p.ej. "backend-python-swl"
+ * @param {string} [cwd]     - Directorio de proyecto (default process.cwd())
+ * @returns {string|null}    - Ruta absoluta o null si no existe
+ */
+function resolveAgentPath(agentName, cwd) {
+  const baseDir = cwd || process.cwd();
+  const candidates = [
+    path.join(baseDir, 'agentes', `${agentName}.md`),
+    path.join(baseDir, '.claude', 'agents', `${agentName}.md`),
+  ];
+  for (const c of candidates) {
+    try { if (fs.statSync(c).isFile()) return c; } catch { /* siguiente */ }
+  }
+  return null;
+}
+
+/**
+ * Extrae fase y dominio del frontmatter de un agente.
+ *
+ * @param {string} agentName - Nombre del agente sin extensión
+ * @param {string} [cwd]
+ * @returns {{ fase: string|null, dominio: string|null, source: string }}
+ *   - source: 'frontmatter' | 'cache' | 'unknown'
+ */
+function getRouting(agentName, cwd) {
+  if (!agentName) return { fase: null, dominio: null, source: 'unknown' };
+  if (_cache[agentName]) {
+    return { ..._cache[agentName], source: 'cache' };
+  }
+
+  const agentPath = resolveAgentPath(agentName, cwd);
+  if (!agentPath) {
+    const result = { fase: null, dominio: null, source: 'unknown' };
+    _cache[agentName] = { fase: null, dominio: null };
+    return result;
+  }
+
+  let raw;
+  try {
+    raw = fs.readFileSync(agentPath, 'utf8');
+  } catch {
+    return { fase: null, dominio: null, source: 'unknown' };
+  }
+
+  const fmMatch = raw.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!fmMatch) {
+    _cache[agentName] = { fase: null, dominio: null };
+    return { fase: null, dominio: null, source: 'unknown' };
+  }
+  const fm = fmMatch[1];
+
+  // Parser minimalista — solo busca las dos líneas que necesitamos.
+  // Evitamos depender de un parser YAML completo (zero-deps).
+  const faseMatch    = fm.match(/^fase:\s*(\S+)/m);
+  const dominioMatch = fm.match(/^dominio:\s*(\S+)/m);
+
+  const result = {
+    fase:    faseMatch    ? faseMatch[1].trim()    : null,
+    dominio: dominioMatch ? dominioMatch[1].trim() : null,
+  };
+  _cache[agentName] = result;
+  return { ...result, source: 'frontmatter' };
+}
+
+/**
+ * Limpia el cache (para tests o tras modificar agentes).
+ */
+function clearCache() {
+  for (const k of Object.keys(_cache)) delete _cache[k];
+}
+
+module.exports = { getRouting, resolveAgentPath, clearCache };