@saulwade/swl-ses 1.2.1 → 1.3.0

package/hooks/claudemd-bloat-detector.js

@@ -0,0 +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);

package/manifiestos/hooks-config.json

@@ -347,6 +347,15 @@
       "maxConsecutiveFailures": 5,
       "degradeOnFailure": "skip"
     },
+    "claudemd-bloat-detector.js": {
+      "event": "PostToolUse",
+      "matcher": "Write|Edit|MultiEdit",
+      "description": "Ejecuta scripts/auditar-claudemd.js contra archivos CLAUDE.md recién modificados (basename exacto, no cualquier .md). Emite nudge a .planning/evolucion/nudges.jsonl si veredicto != OK (líneas excesivas, bullets gigantes, secciones canónicas ausentes, sin @references, placeholders). Aplica ADR-0016 (best practices Anthropic 'The CLAUDE.md file'). No bloquea. Excluye temp/, node_modules/, respositorios-git/, .planning/. Opt-out: SWL_CLAUDEMD_BLOAT=0.",
+      "blocking": false,
+      "async": true,
+      "maxConsecutiveFailures": 5,
+      "degradeOnFailure": "skip"
+    },
     "notificacion-telegram.js": {
       "event": "Stop",
       "matcher": "",

package/manifiestos/modulos.json

@@ -698,11 +698,12 @@
       ]
     },
     "habilidades-swl-herramientas": {
-      "descripcion": "Herramientas internas SWL: markitdown, revisar-impacto, NestJS",
+      "descripcion": "Herramientas internas SWL: markitdown, revisar-impacto, claudemd, NestJS",
       "tipo": "habilidades",
       "archivos": [
         "habilidades/swl-markitdown",
         "habilidades/swl-revisar-impacto",
+        "habilidades/swl-claudemd",
         "habilidades/nestjs-experto"
       ],
       "targets": [
@@ -801,7 +802,8 @@
         "comandos/swl/exportar-vault.md",
         "comandos/swl/ayuda.md",
         "comandos/swl/inbox.md",
-        "comandos/swl/reflect-skills.md"
+        "comandos/swl/reflect-skills.md",
+        "comandos/swl/claudemd.md"
       ],
       "targets": [
         "claude",
@@ -956,6 +958,7 @@
         "hooks/captura-feedback-usuario.js",
         "hooks/inbox-aviso.js",
         "hooks/aiisms-detector.js",
+        "hooks/claudemd-bloat-detector.js",
         "hooks/sugerir-regenerar-inventario.js",
         "hooks/sugerir-contribuir.js",
         "hooks/_run-hook.sh",
@@ -1136,6 +1139,22 @@
         "gemini"
       ]
     },
+    "claudemd-auditor": {
+      "descripcion": "Auditor de calidad de CLAUDE.md según best practices Anthropic (ADR-0016). Detecta inflación (líneas excesivas, bullets gigantes, secciones canónicas ausentes, sin @references, placeholders). Usado por el comando /swl:claudemd y por el hook claudemd-bloat-detector. Zero-deps. Soporta --json y --strict. Umbrales configurables: SWL_CLAUDEMD_MAX_LINES (default 200), SWL_CLAUDEMD_MAX_BULLET_CHARS (default 1000).",
+      "tipo": "scripts",
+      "archivos": [
+        "scripts/auditar-claudemd.js",
+        "docs/variables-entorno.md"
+      ],
+      "targets": [
+        "claude",
+        "openclaude",
+        "copilot",
+        "opencode",
+        "codex",
+        "gemini"
+      ]
+    },
     "mcp-server-swl": {
       "descripcion": "MCP server stub experimental que expone memoria SWL (aprendizajes, sesiones, instintos) a clientes MCP externos (Cursor, Gemini CLI, OpenCode, Cline, Claude Desktop). Modo stdio. 3 endpoints: swl_memory_search, swl_aprendizajes_recientes, swl_instintos_activos. SIN auth, SIN rate limiting, SIN HTTP transport, SIN tests integración. NO USAR EN PRODUCCIÓN. Trigger para hardening: uso real ≥2 runtimes diferentes consistentemente por ≥1 mes. El binario `swl-mcp-server` se instala automáticamente vía npm install -g (declarado en package.json bin). NO se propaga al runtime SWL — vive en el paquete npm como herramienta opt-in. Ver scripts/mcp-server/README.md para 11 limitaciones explícitas y diseño futuro.",
       "tipo": "scripts",

package/package.json

@@ -1,87 +1,87 @@
-{
-  "name": "@saulwade/swl-ses",
-  "version": "1.2.1",
-  "description": "Sistema de ingenieria de software auto-evolutivo multi-runtime polyglot con 59 agentes, 151 habilidades, 42 comandos, 64 reglas y 40 hooks. Soporta 11 lenguajes y 5 runtimes: Claude Code, Copilot, OpenCode, Codex y Gemini CLI. 100% en espanol (Mexico). Incluye gateway bidireccional con relay Telegram a Claude Code.",
-  "bin": {
-    "swl-ses": "bin/swl-ses.js",
-    "swl-telegram-bot": "bin/swl-telegram-bot.js",
-    "swl-mcp-server": "bin/swl-mcp-server.js"
-  },
-  "files": [
-    "bin",
-    "scripts",
-    "manifiestos",
-    "agentes",
-    "habilidades",
-    "comandos",
-    "reglas",
-    "hooks",
-    "plantillas",
-    "contextos",
-    "instintos",
-    "schemas",
-    "_userland",
-    "plugin.json",
-    "CLAUDE.md"
-  ],
-  "scripts": {
-    "postinstall": "echo '\n  swl-software-engineering-system instalado.\n  Ejecuta: npx swl-ses init\n'",
-    "test": "node --test tests/lib/*.test.js tests/scripts/*.test.js tests/scripts/lib/*.test.js tests/hooks/*.test.js",
-    "test:validate": "node scripts/validar.js",
-    "test:manifest": "node scripts/validar-manifest.js",
-    "test:smoke": "node scripts/smoke-test.js",
-    "test:aislamiento": "node scripts/validar-tests-aislamiento.js",
-    "test:all": "npm test && node scripts/validar.js && node scripts/validar-manifest.js",
-    "test:userland": "node scripts/validar-userland-vacio.js",
-    "test:release": "npm run test:all && npm run test:userland && npm run test:smoke",
-    "doctor": "node scripts/doctor.js",
-    "prepack": "node scripts/limpiar-artefactos-python.js && node scripts/validar-userland-vacio.js",
-    "prepublishOnly": "npm run test:release",
-    "publish:all": "node scripts/publicar.js",
-    "publish:github": "node scripts/publicar.js --solo-github",
-    "publish:npmjs": "node scripts/publicar.js --solo-npmjs",
-    "publish:dry": "node scripts/publicar.js --dry-run",
-    "generate:docs": "node scripts/generar-inventario.js",
-    "gen-checklists": "node scripts/generar-checklists-consolidados.js",
-    "gen-checklists:check": "node scripts/generar-checklists-consolidados.js --check",
-    "field-report": "node scripts/field-report.js",
-    "configure:branch-protection": "node scripts/configurar-branch-protection.js"
-  },
-  "engines": {
-    "node": ">=22.0.0"
-  },
-  "keywords": [
-    "claude-code",
-    "github-copilot",
-    "gemini-cli",
-    "opencode",
-    "codex-cli",
-    "agentes",
-    "skills",
-    "multi-runtime",
-    "spec-driven",
-    "orquestacion",
-    "ingenieria-software"
-  ],
-  "author": "Saul Wade Leon",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/saul-wade/swl-ses.git"
-  },
-  "homepage": "https://github.com/saul-wade/swl-ses#readme",
-  "bugs": {
-    "url": "https://github.com/saul-wade/swl-ses/issues"
-  },
-  "publishConfig": {
-    "registry": "https://registry.npmjs.org/",
-    "access": "public"
-  },
-  "dependencies": {
-    "docx": "^9.6.1"
-  },
-  "overrides": {
-    "pako": "^2.1.0",
-    "readable-stream": "^4.7.0"
-  }
-}
+{
+  "name": "@saulwade/swl-ses",
+  "version": "1.3.0",
+  "description": "Sistema de ingenieria de software auto-evolutivo multi-runtime polyglot con 59 agentes, 154 habilidades, 42 comandos, 64 reglas y 40 hooks. Soporta 11 lenguajes y 5 runtimes: Claude Code, Copilot, OpenCode, Codex y Gemini CLI. 100% en espanol (Mexico). Incluye gateway bidireccional con relay Telegram a Claude Code.",
+  "bin": {
+    "swl-ses": "bin/swl-ses.js",
+    "swl-telegram-bot": "bin/swl-telegram-bot.js",
+    "swl-mcp-server": "bin/swl-mcp-server.js"
+  },
+  "files": [
+    "bin",
+    "scripts",
+    "manifiestos",
+    "agentes",
+    "habilidades",
+    "comandos",
+    "reglas",
+    "hooks",
+    "plantillas",
+    "contextos",
+    "instintos",
+    "schemas",
+    "_userland",
+    "plugin.json",
+    "CLAUDE.md"
+  ],
+  "scripts": {
+    "postinstall": "echo '\n  swl-software-engineering-system instalado.\n  Ejecuta: npx swl-ses init\n'",
+    "test": "node --test tests/lib/*.test.js tests/scripts/*.test.js tests/scripts/lib/*.test.js tests/hooks/*.test.js",
+    "test:validate": "node scripts/validar.js",
+    "test:manifest": "node scripts/validar-manifest.js",
+    "test:smoke": "node scripts/smoke-test.js",
+    "test:aislamiento": "node scripts/validar-tests-aislamiento.js",
+    "test:all": "npm test && node scripts/validar.js && node scripts/validar-manifest.js",
+    "test:userland": "node scripts/validar-userland-vacio.js",
+    "test:release": "npm run test:all && npm run test:userland && npm run test:smoke",
+    "doctor": "node scripts/doctor.js",
+    "prepack": "node scripts/limpiar-artefactos-python.js && node scripts/validar-userland-vacio.js",
+    "prepublishOnly": "npm run test:release",
+    "publish:all": "node scripts/publicar.js",
+    "publish:github": "node scripts/publicar.js --solo-github",
+    "publish:npmjs": "node scripts/publicar.js --solo-npmjs",
+    "publish:dry": "node scripts/publicar.js --dry-run",
+    "generate:docs": "node scripts/generar-inventario.js",
+    "gen-checklists": "node scripts/generar-checklists-consolidados.js",
+    "gen-checklists:check": "node scripts/generar-checklists-consolidados.js --check",
+    "field-report": "node scripts/field-report.js",
+    "configure:branch-protection": "node scripts/configurar-branch-protection.js"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "keywords": [
+    "claude-code",
+    "github-copilot",
+    "gemini-cli",
+    "opencode",
+    "codex-cli",
+    "agentes",
+    "skills",
+    "multi-runtime",
+    "spec-driven",
+    "orquestacion",
+    "ingenieria-software"
+  ],
+  "author": "Saul Wade Leon",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/saul-wade/swl-ses.git"
+  },
+  "homepage": "https://github.com/saul-wade/swl-ses#readme",
+  "bugs": {
+    "url": "https://github.com/saul-wade/swl-ses/issues"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "dependencies": {
+    "docx": "^9.6.1"
+  },
+  "overrides": {
+    "pako": "^2.1.0",
+    "readable-stream": "^4.7.0"
+  }
+}