@saulwade/swl-ses 1.4.0 → 1.4.2

package/habilidades/web-fetcher-routing/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: web-fetcher-routing
+description: >
+  Routing inteligente para fetching de URLs según dominio y formato:
+  GitHub raw, PDF, sitios JS-heavy y default. Reduce tokens consumidos
+  evitando WebFetch cuando hay alternativa más eficiente. Cargar antes
+  de hacer WebFetch a URLs externas, especialmente repositorios GitHub,
+  PDFs públicos, o sitios con paywall/Cloudflare/JS heavy.
+---
+
+# web-fetcher-routing
+
+Selecciona la herramienta correcta para cada URL antes de intentar el fetch.
+Un WebFetch al HTML de GitHub UI consume 10-30× más tokens que leer el raw.
+Un PDF vía Read devuelve basura binaria. La elección equivocada cuesta tokens
+reales; este skill la automatiza.
+
+## Cuándo cargar
+
+- Antes de hacer `WebFetch` a cualquier URL externa no trivial.
+- Cuando la URL apunta a GitHub (repositorio, archivo o blob).
+- Cuando la URL termina en `.pdf` o el contexto indica documento PDF.
+- Cuando el fetch previo falló con 402, página de login o contenido vacío
+  (señal de JS-heavy o Cloudflare).
+
+## Cuándo NO cargar
+
+- URLs internas del proyecto o localhost — usar `Read` directamente.
+- Contenido ya cargado en el contexto de esta sesión — no re-fetchar.
+- Cuando el usuario dictó explícitamente la herramienta a usar
+  ("usa WebFetch", "lee con curl").
+
+## Tabla de routing
+
+| Patrón de URL | Herramienta | Razón |
+|---|---|---|
+| `github.com/[user]/[repo]/blob/[branch]/[path]` | Reescribir a `raw.githubusercontent.com/[user]/[repo]/[branch]/[path]` y hacer `WebFetch` con la URL reescrita | Evita el HTML de la UI de GitHub; 10-30× menos tokens |
+| `raw.githubusercontent.com/...` | `WebFetch` directo | Ya es raw content |
+| URL termina en `.pdf` | Invocar `Skill("swl-markitdown")` para conversión con `pdftotext` o `markitdown` | `Read` no soporta PDF; `WebFetch` devuelve binario o HTML de visor |
+| `x.com`, `twitter.com`, cualquier host con CAPTCHA o Cloudflare detectado | Invocar `Skill("agent-browser")` con headless Chrome | `WebFetch` devuelve 402 o página de login; `agent-browser` usa accessibility tree (~82% menos tokens que screenshots) |
+| `mp.weixin.qq.com`, `feishu.cn`, `larksuite.com` | Invocar `Skill("agent-browser")` | Plataformas chinas con autenticación o JS requerido |
+| Todo lo demás | `WebFetch` directo | El caso común; probar primero antes de escalar |
+
+## Algoritmo de decisión
+
+1. Parsear la URL: extraer esquema, dominio y extensión del path.
+2. Comparar con los patrones de la tabla, en orden de arriba hacia abajo.
+3. Si el dominio es `github.com` con segmento `/blob/` en el path:
+   reescribir la URL antes de hacer el fetch.
+4. Invocar la herramienta asignada al patrón que coincide.
+5. Si el resultado tiene señales de paywall o error (primeras 10 líneas
+   contienen "Subscribe", "Sign in", "403", página vacía): escalar al
+   patrón JS-heavy con `Skill("agent-browser")`.
+6. Reportar qué método se usó y por qué, en una línea antes del contenido.
+
+## Ejemplo de reescritura GitHub
+
+```
+# URL original
+https://github.com/tw93/Waza/blob/main/skills/read/SKILL.md
+
+# URL reescrita para raw
+https://raw.githubusercontent.com/tw93/Waza/main/skills/read/SKILL.md
+```
+
+## Señales de fallo que activan escalado
+
+| Señal en la respuesta | Acción |
+|---|---|
+| HTTP 402 | Escalar a `agent-browser` |
+| Primeras líneas con "Sign in" o "Subscribe" | Detener, avisar al usuario |
+| Contenido HTML con menos de 200 caracteres | Reintentar con método alternativo |
+| Binario o caracteres ilegibles | Verificar si es PDF; si sí, usar `swl-markitdown` |
+
+<!-- Adaptado de Waza/skills/read bajo MIT License (tw93/Waza) -->

package/hooks/claudemd-bloat-detector.js

@@ -1,161 +1,161 @@
-#!/usr/bin/env node
-'use strict';
-
-/**
- * Hook: claudemd-bloat-detector.js
- * Tipo: PostToolUse  (aplica a: Write, Edit, MultiEdit)
- *
- * Ejecuta `scripts/auditar-claudemd.js` contra archivos `CLAUDE.md`
- * recién modificados y emite un nudge a `.planning/evolucion/nudges.jsonl`
- * si el veredicto es WARN o ERROR.
- *
- * Aplica ADR-0016 (best practices Anthropic "The CLAUDE.md file"):
- * detecta inflación (líneas excesivas, bullets monolíticos, secciones
- * canónicas ausentes, ausencia de @references) y sugiere intervención
- * con `/swl:claudemd refactor`.
- *
- * Opt-out: SWL_CLAUDEMD_BLOAT=0 desactiva completamente el hook.
- *
- * Comportamiento:
- *   - Nunca bloquea operaciones (exit code 0 siempre)
- *   - Solo emite nudge cuando veredicto != OK — ruido mínimo
- *   - Solo se dispara con archivos cuyo basename sea exactamente CLAUDE.md
- *   - Respeta exclusiones: temp/, node_modules/, respositorios-git/
- *
- * Formato del nudge:
- *   {
- *     id: string,
- *     kind: "claudemd-bloat",
- *     target: "documentador-swl",
- *     source: "hooks/claudemd-bloat-detector.js",
- *     message: "...",
- *     data: { archivo, veredicto, lineas, hallazgos_count },
- *     ts: ISO,
- *     accionado: false
- *   }
- */
-
-const fs = require('fs');
-const path = require('path');
-const crypto = require('crypto');
-
-// ─── Opt-out global ───────────────────────────────────────────────────────
-if (process.env.SWL_CLAUDEMD_BLOAT === '0') {
-  process.exit(0);
-}
-
-let hookInput = '';
-try {
-  hookInput = fs.readFileSync(0, 'utf-8');
-} catch (_) {
-  process.exit(0);
-}
-
-let evento;
-try {
-  evento = JSON.parse(hookInput);
-} catch (_) {
-  process.exit(0);
-}
-
-const toolName = evento?.tool_name;
-const toolInput = evento?.tool_input;
-
-if (!toolName || !['Write', 'Edit', 'MultiEdit'].includes(toolName)) {
-  process.exit(0);
-}
-
-const filePath = toolInput?.file_path;
-if (!filePath) {
-  process.exit(0);
-}
-
-// Solo CLAUDE.md (basename exacto, case-sensitive)
-const basename = path.basename(filePath);
-if (basename !== 'CLAUDE.md') {
-  process.exit(0);
-}
-
-const pathNormalized = filePath.replace(/\\/g, '/');
-const RUTAS_EXCLUIDAS = [
-  '/temp/',
-  '/node_modules/',
-  '/respositorios-git/',
-  '/.planning/',
-];
-if (RUTAS_EXCLUIDAS.some((excluida) => pathNormalized.includes(excluida))) {
-  process.exit(0);
-}
-
-// El archivo debe existir
-if (!fs.existsSync(filePath)) {
-  process.exit(0);
-}
-
-// ─── Ejecutar auditor (módulo, no subproceso) ─────────────────────────────
-const CWD = process.cwd();
-const auditorPath = path.join(CWD, 'scripts', 'auditar-claudemd.js');
-if (!fs.existsSync(auditorPath)) {
-  // No hay auditor instalado en este destino; salir silenciosamente
-  process.exit(0);
-}
-
-let resultado;
-try {
-  const { auditar } = require(auditorPath);
-  resultado = auditar(filePath);
-} catch (_) {
-  // Cualquier error del auditor: salir silenciosamente, no romper el hook
-  process.exit(0);
-}
-
-// Solo emitir nudge si veredicto != OK
-if (!resultado || resultado.veredicto === 'OK') {
-  process.exit(0);
-}
-
-// ─── Construir nudge ──────────────────────────────────────────────────────
-const rutaRelativa = path.relative(CWD, filePath).replace(/\\/g, '/');
-const topHallazgos = (resultado.hallazgos || [])
-  .slice(0, 3)
-  .map((h) => `  - [${h.severidad}] ${h.mensaje}`)
-  .join('\n');
-
-const nudge = {
-  id: crypto.randomBytes(8).toString('hex'),
-  kind: 'claudemd-bloat',
-  target: 'documentador-swl',
-  source: 'hooks/claudemd-bloat-detector.js',
-  message:
-    `[claudemd] ${rutaRelativa} veredicto: ${resultado.veredicto} ` +
-    `(${resultado.hallazgos.length} hallazgos)\n` +
-    topHallazgos + '\n' +
-    `  Ejecutar \`/swl:claudemd audit\` para detalle, ` +
-    `\`/swl:claudemd refactor\` para sugerencias de extracción.`,
-  data: {
-    archivo: rutaRelativa,
-    veredicto: resultado.veredicto,
-    lineas: resultado.metricas?.lineas,
-    secciones_ausentes: resultado.metricas?.secciones_ausentes || [],
-    tiene_at_references: resultado.metricas?.tiene_at_references,
-    hallazgos_count: resultado.hallazgos.length,
-  },
-  ts: new Date().toISOString(),
-  accionado: false,
-  accionado_ts: null,
-  accionado_por: null,
-};
-
-// ─── Persistir a nudges.jsonl ─────────────────────────────────────────────
-try {
-  const nudgesPath = path.join(CWD, '.planning', 'evolucion', 'nudges.jsonl');
-  const nudgesDir = path.dirname(nudgesPath);
-  if (!fs.existsSync(nudgesDir)) {
-    fs.mkdirSync(nudgesDir, { recursive: true });
-  }
-  fs.appendFileSync(nudgesPath, JSON.stringify(nudge) + '\n', 'utf-8');
-} catch (_) {
-  // No fallar el hook por error de escritura
-}
-
-process.exit(0);
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Hook: claudemd-bloat-detector.js
+ * Tipo: PostToolUse  (aplica a: Write, Edit, MultiEdit)
+ *
+ * Ejecuta `scripts/auditar-claudemd.js` contra archivos `CLAUDE.md`
+ * recién modificados y emite un nudge a `.planning/evolucion/nudges.jsonl`
+ * si el veredicto es WARN o ERROR.
+ *
+ * Aplica ADR-0016 (best practices Anthropic "The CLAUDE.md file"):
+ * detecta inflación (líneas excesivas, bullets monolíticos, secciones
+ * canónicas ausentes, ausencia de @references) y sugiere intervención
+ * con `/swl:claudemd refactor`.
+ *
+ * Opt-out: SWL_CLAUDEMD_BLOAT=0 desactiva completamente el hook.
+ *
+ * Comportamiento:
+ *   - Nunca bloquea operaciones (exit code 0 siempre)
+ *   - Solo emite nudge cuando veredicto != OK — ruido mínimo
+ *   - Solo se dispara con archivos cuyo basename sea exactamente CLAUDE.md
+ *   - Respeta exclusiones: temp/, node_modules/, respositorios-git/
+ *
+ * Formato del nudge:
+ *   {
+ *     id: string,
+ *     kind: "claudemd-bloat",
+ *     target: "documentador-swl",
+ *     source: "hooks/claudemd-bloat-detector.js",
+ *     message: "...",
+ *     data: { archivo, veredicto, lineas, hallazgos_count },
+ *     ts: ISO,
+ *     accionado: false
+ *   }
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+// ─── Opt-out global ───────────────────────────────────────────────────────
+if (process.env.SWL_CLAUDEMD_BLOAT === '0') {
+  process.exit(0);
+}
+
+let hookInput = '';
+try {
+  hookInput = fs.readFileSync(0, 'utf-8');
+} catch (_) {
+  process.exit(0);
+}
+
+let evento;
+try {
+  evento = JSON.parse(hookInput);
+} catch (_) {
+  process.exit(0);
+}
+
+const toolName = evento?.tool_name;
+const toolInput = evento?.tool_input;
+
+if (!toolName || !['Write', 'Edit', 'MultiEdit'].includes(toolName)) {
+  process.exit(0);
+}
+
+const filePath = toolInput?.file_path;
+if (!filePath) {
+  process.exit(0);
+}
+
+// Solo CLAUDE.md (basename exacto, case-sensitive)
+const basename = path.basename(filePath);
+if (basename !== 'CLAUDE.md') {
+  process.exit(0);
+}
+
+const pathNormalized = filePath.replace(/\\/g, '/');
+const RUTAS_EXCLUIDAS = [
+  '/temp/',
+  '/node_modules/',
+  '/respositorios-git/',
+  '/.planning/',
+];
+if (RUTAS_EXCLUIDAS.some((excluida) => pathNormalized.includes(excluida))) {
+  process.exit(0);
+}
+
+// El archivo debe existir
+if (!fs.existsSync(filePath)) {
+  process.exit(0);
+}
+
+// ─── Ejecutar auditor (módulo, no subproceso) ─────────────────────────────
+const CWD = process.cwd();
+const auditorPath = path.join(CWD, 'scripts', 'auditar-claudemd.js');
+if (!fs.existsSync(auditorPath)) {
+  // No hay auditor instalado en este destino; salir silenciosamente
+  process.exit(0);
+}
+
+let resultado;
+try {
+  const { auditar } = require(auditorPath);
+  resultado = auditar(filePath);
+} catch (_) {
+  // Cualquier error del auditor: salir silenciosamente, no romper el hook
+  process.exit(0);
+}
+
+// Solo emitir nudge si veredicto != OK
+if (!resultado || resultado.veredicto === 'OK') {
+  process.exit(0);
+}
+
+// ─── Construir nudge ──────────────────────────────────────────────────────
+const rutaRelativa = path.relative(CWD, filePath).replace(/\\/g, '/');
+const topHallazgos = (resultado.hallazgos || [])
+  .slice(0, 3)
+  .map((h) => `  - [${h.severidad}] ${h.mensaje}`)
+  .join('\n');
+
+const nudge = {
+  id: crypto.randomBytes(8).toString('hex'),
+  kind: 'claudemd-bloat',
+  target: 'documentador-swl',
+  source: 'hooks/claudemd-bloat-detector.js',
+  message:
+    `[claudemd] ${rutaRelativa} veredicto: ${resultado.veredicto} ` +
+    `(${resultado.hallazgos.length} hallazgos)\n` +
+    topHallazgos + '\n' +
+    `  Ejecutar \`/swl:claudemd audit\` para detalle, ` +
+    `\`/swl:claudemd refactor\` para sugerencias de extracción.`,
+  data: {
+    archivo: rutaRelativa,
+    veredicto: resultado.veredicto,
+    lineas: resultado.metricas?.lineas,
+    secciones_ausentes: resultado.metricas?.secciones_ausentes || [],
+    tiene_at_references: resultado.metricas?.tiene_at_references,
+    hallazgos_count: resultado.hallazgos.length,
+  },
+  ts: new Date().toISOString(),
+  accionado: false,
+  accionado_ts: null,
+  accionado_por: null,
+};
+
+// ─── Persistir a nudges.jsonl ─────────────────────────────────────────────
+try {
+  const nudgesPath = path.join(CWD, '.planning', 'evolucion', 'nudges.jsonl');
+  const nudgesDir = path.dirname(nudgesPath);
+  if (!fs.existsSync(nudgesDir)) {
+    fs.mkdirSync(nudgesDir, { recursive: true });
+  }
+  fs.appendFileSync(nudgesPath, JSON.stringify(nudge) + '\n', 'utf-8');
+} catch (_) {
+  // No fallar el hook por error de escritura
+}
+
+process.exit(0);

package/hooks/lib/agent-routing.js

@@ -1,107 +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 };
+'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 };