@saulwade/swl-ses 1.5.0 → 1.5.2

package/habilidades/verificar-trabajo/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: verificar-trabajo
 description: Verificación goal-backward del trabajo ejecutado en 4 niveles progresivos — EXISTE, SUSTANTIVO, CONECTADO, DATOS_FLUYEN. Clasifica claims en 4 tipos (TASK, FIX, TEST_OR_BUILD, FEATURE_GO) con evidencia proporcional. Detecta stubs, componentes huérfanos, integraciones rotas y flujos incompletos. Produce veredictos estructurados JSON con clasificación de riesgo (Low/Medium/High) y evidencia verificable. Soporta loop de reparación cuando el veredicto es Fail.
-version: "1.2.0"
+version: "1.2.1"
 evolved: true
-evolved-from: "1.1.1"
+evolved-from: "1.2.0"
 evolved-at: "2026-05-15"
 evolved-by: "aprender"
-evolved-note: "Taxonomía de claim types adoptada de cc-sdd kiro-verify-completion: cada tipo de claim (TASK/FIX/TEST_OR_BUILD/FEATURE_GO) requiere evidencia distinta. Previene declarar éxito broader que la evidencia disponible."
+evolved-note: "Gotchas v1.5.1 acumulados en este ciclo: (1) health-check post-hoc que recalcula contexto del install desde cwd actual → falso positivo (caso doctor 2026-05-15); (2) smoke E2E obligatorio para features cross-cutting (Sub-fase 11.5: transformarAgente nunca invocado pese a suite 100% verde); (3) auto-reparación debe verificar que el chequeo subsecuente ya no detecta el problema, si no → loop infinito (Sub-fase 12: doctor)."
 herramientasPermitidas: [Read, Write, Edit, Bash, Glob, Grep]
 exclusiones:
   - "No cargar durante la implementación activa de una tarea; la verificación es posterior a la implementación, no concurrente."
@@ -340,6 +340,11 @@ estructurado JSON, ver [recursos/plantilla-verificacion.md](recursos/plantilla-v
 - **Loop de reparación sin re-verificación completa**: tras el fix, el agente re-verifica solo el item que falló en lugar del veredicto completo. Causa: optimización incorrecta para ahorrar tiempo. Solución: el paso 3 del loop de reparación dice explícitamente "re-ejecutar la verificación COMPLETA" — un fix puede resolver un fallo pero introducir otro.
 - **Hollow Component no detectado en Nivel 2**: el componente Angular tiene template pero no usa ninguna señal del componente. El agente verifica que el archivo existe (Nivel 1) y que tiene contenido (Nivel 2), pero no detecta que el contenido es decorativo. Causa: la definición de "stub" en Nivel 2 no se aplicó al caso de templates sin binding. Solución: verificar explícitamente que el template usa al menos una variable/señal del componente.
 - **Verificación con tests + linter pasa pero al levantar BD fresca todo se rompe**: tests Python con mocks y `ruff check` retornan verde, pero `docker compose down -v && up` falla porque hay drift entre `database/schemas/`, seeds, funciones SQL y vistas. Caso real (SIGM 2026-05-04): primera pasada de `/swl:verificar` reportó "APROBADO 21/22" sin detectar que ~10 seeds tenían columnas obsoletas, UUIDs inválidos y un script `02-crear-buckets-minio.sh` que abortaba initdb del contenedor postgres. Causa: la verificación corre solo contra el código (que mockea BD); nunca aplica el SQL real. Solución: cuando el alcance toca cualquier archivo en `database/schemas/`, `database/seeds/`, `database/functions/` o `database/views/`, ejecutar como Nivel 4 (DATOS_FLUYEN) obligatorio: `docker compose down -v && docker compose up -d db && wait_for_health && docker logs <db_container> | grep -E "ERROR|skipped"`. Cualquier ERROR en logs de init invalida el veredicto Pass.
+- **Health-check post-hoc que recalcula contexto del install desde cwd actual produce falso positivo**: un verificador (doctor, validador, monitor) que recalcula filtros — aplicados al momento del install — desde el `process.cwd()` actual genera discrepancia falsa cuando se ejecuta desde un dir distinto. Caso real (swl-ses doctor v1.4.3, 2026-05-15): reportaba "reglas: 65 (perfil esperaba 25)" porque recalculaba `filtrarReglasPorStack(detectarStack(cwd))` con `cwd` vacío de indicadores, mientras las 40 reglas-lenguajes se habían instalado correctamente con stack detectado en el dir del proyecto. Causa: el filtro depende del contexto del momento del install, no del momento del check. Solución obligatoria: **persistir el contexto del install en el state file** (en este caso `allLangs` + `stackInstalado` en `.swl-install-state.json`). Si el state es legacy (sin estos campos), **inferir el contexto desde los archivos realmente instalados** (ej: subdirs presentes bajo `reglas/lenguajes/<lang>/`), NO recalcular desde cwd. Aplica como regla general a cualquier check post-hoc cuya validez depende del contexto del install.
+
+- **Suite 100% verde con bug latente cross-cutting que solo aparece en smoke E2E real**: las unit tests del transformador pasaban, los tests del instalador pasaban, los tests del manifiesto pasaban — pero el smoke `install --target codex --local --force` reveló que `instalarArchivo()` hacía `fs.copyFileSync(archivo.origen, destino)` literal sin invocar `transformarAgente()`. Los `.toml` de Codex y los `.md` normalizados de Cursor NUNCA se generaban en disco aunque las unit tests del transformador retornaran contenido correcto. Caso real (Sub-fase 11.5 v1.5.1, 2026-05-15): la integración de las dos capas (transformador + instalador) jamás se testeaba E2E porque cada una se probaba en aislamiento con mocks. **Regla obligatoria para features cross-cutting** (multi-capa: transformador + instalador + filesystem; o lib + bin + cliente; o backend + frontend + cache): el Nivel 4 DATOS_FLUYEN exige al menos un smoke E2E real que ejercite las tres capas con archivos reales en disco temporal. NO sustituible por unit tests aunque la suite sea 100% verde. Comando mínimo: `mkdir tmp && cd tmp && bin/CLI <comando-happy-path> && ls -R` + inspección del primer archivo generado.
+
+- **Auto-reparación ejecuta acción sin verificar que el chequeo subsecuente ya no detecta el problema**: el doctor reporta "faltan reglas: 0/25" en Codex, el usuario elige "reparar automáticamente", el doctor invoca `instalador.install({force:true})`, reinstala 230 archivos, vuelve a chequear y reporta lo mismo. Loop infinito. Caso real (Sub-fase 12 v1.5.1, 2026-05-15): los 4 falsos positivos del doctor sobre Codex/Cursor persistían tras cada "reparación" porque la causa raíz era un filtro hardcoded (`tiposPrincipales = ['agentes', 'habilidades', 'comandos', 'reglas']` sin respetar `runtime.tiposSoportados` ni `dir<Tipo>`). Cada reinstalación dejaba el filtro intacto, el chequeo seguía detectando el "problema". **Regla**: toda función de auto-reparación debe ejecutar el chequeo subsecuente ANTES de reportar "Reparado" — si el chequeo sigue detectando el problema, NO marcar como reparado y reportar "no se pudo reparar, requiere diagnóstico manual". Implementación: wrap la acción en `try { accion(); const res = chequeo(); if (!res.ok) throw new Error('reparación sin efecto'); }`.
 
 ## Regla de oro del verificador
 

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

@@ -1,75 +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) -->
+---
+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/check-update.js

@@ -37,8 +37,16 @@ const RETRY_INTERVAL_MS = 60 * 60 * 1000;
 /** Timeout para npm view (5 segundos). */
 const NPM_TIMEOUT_MS = 5000;
 
-/** Archivo flag para throttling entre sesiones. */
+/**
+ * Archivo flag para throttling entre sesiones.
+ *
+ * En producción usa `os.tmpdir()/swl-ses-update-check.json`. Los tests
+ * pueden override la ruta exportando `SWL_UPDATE_FLAG_PATH` con un path
+ * único por test (evita race entre archivos `.test.js` que corren en
+ * paralelo y comparten el mismo flag).
+ */
 function flagPath() {
+  if (process.env.SWL_UPDATE_FLAG_PATH) return process.env.SWL_UPDATE_FLAG_PATH;
   return path.join(os.tmpdir(), 'swl-ses-update-check.json');
 }
 
@@ -137,6 +145,10 @@ function debeVerificar() {
 
 /**
  * Registra que se hizo un check.
+ *
+ * `notificado` se inicializa en 0 explícitamente. Sin este campo, la
+ * comparación `data.notificado < 2` en el branch de repetición evaluaba
+ * `undefined < 2 === false` y el aviso nunca se repetía dentro del throttle.
  */
 function registrarCheck(local, remota, hayNueva) {
   try {
@@ -145,6 +157,7 @@ function registrarCheck(local, remota, hayNueva) {
       local,
       remota,
       hayNueva,
+      notificado: 0,
     }), 'utf8');
   } catch { /* silencioso */ }
 }
@@ -164,12 +177,15 @@ process.stdin.on('end', async () => {
       // Si el último check detectó actualización, repetir notificación (1 vez)
       try {
         const data = JSON.parse(fs.readFileSync(flagPath(), 'utf8'));
-        if (data.hayNueva && data.notificado < 2) {
+        // Defense-in-depth: aceptar flags antiguos sin campo `notificado`.
+        // `undefined < 2` evalúa `false` por NaN comparison — usar fallback a 0.
+        const notificadoActual = data.notificado || 0;
+        if (data.hayNueva && notificadoActual < 2) {
           process.stderr.write(
             `[swl-ses] Versión ${data.remota} disponible (actual: ${data.local}). ` +
             `Ejecuta: npx @saulwade/swl-ses@latest update\n`
           );
-          data.notificado = (data.notificado || 0) + 1;
+          data.notificado = notificadoActual + 1;
           fs.writeFileSync(flagPath(), JSON.stringify(data), 'utf8');
         }
       } catch (err) {
@@ -201,6 +217,18 @@ process.stdin.on('end', async () => {
         '',
       ].join('\n');
       process.stderr.write(msg);
+    } else if (process.env.SWL_FORCE_UPDATE_NOTIFICATION === '1') {
+      // Modo debug: mostrar siempre el estado aunque local == remota.
+      // Útil para el autor (cuya local nunca queda atrás) y para verificar
+      // que el mecanismo funciona end-to-end sin esperar a un escenario real.
+      let estado;
+      const cmp = compararSemver(local, remota);
+      if (cmp === 0) estado = 'al día';
+      else if (cmp > 0) estado = 'local adelantada (publicación pendiente)';
+      else estado = 'comparación inconclusa';
+      process.stderr.write(
+        `[swl-ses/check-update] FORCE: local=${local}, remota=${remota}, ${estado}\n`
+      );
     }
   } catch (err) {
     // El hook NUNCA bloquea Claude Code, pero deja una traza diagnóstica.

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);