@saulwade/swl-ses 1.7.4 → 1.9.0

package/hooks/validar-planning-paths.js

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Hook: validar-planning-paths.js
+ * Tipo: PostToolUse  (aplica a: Write, Edit, MultiEdit)
+ *
+ * Advierte cuando una sesion crea un directorio top-level NUEVO en .planning/
+ * que NO esta en la allowlist canonica (manifiestos/planning-paths.json).
+ * Atrapa divergencias es/en (auditoria/ vs audit/, ux/ vs design/) ANTES de
+ * que proliferen.
+ *
+ * Aplica reglas/analizar-directorios-antes-de-escribir.md y cierra
+ * DT-PLANNING-OUTPUT-PATHS. No bloquea (modo warn-only). ADR-0031.
+ *
+ * Opt-out: SWL_PLANNING_PATHS=0 desactiva el hook.
+ *
+ * Formato del nudge: kind "planning-path-divergente" -> documentador-swl.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+if (process.env.SWL_PLANNING_PATHS === '0') process.exit(0);
+
+let evento;
+try {
+  evento = JSON.parse(fs.readFileSync(0, 'utf-8'));
+} 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);
+
+const norm = filePath.replace(/\\/g, '/');
+
+// Solo nos interesa lo que cae dentro de .planning/. Soporta path absoluto
+// (con '/.planning/' embebido, lo que Claude Code envia en produccion) y path
+// relativo ('.planning/...'). `resto` es todo lo que sigue a '.planning/'.
+const marcador = '/.planning/';
+let resto;
+const idx = norm.indexOf(marcador);
+if (idx >= 0) {
+  resto = norm.slice(idx + marcador.length);     // path absoluto / embebido
+} else if (norm.startsWith('.planning/')) {
+  resto = norm.slice('.planning/'.length);        // path relativo
+} else {
+  process.exit(0);                                // fuera de .planning/
+}
+
+// resto = "<segmento>/..." o "<archivo>"
+const partes = resto.split('/').filter(Boolean);
+if (partes.length === 0) process.exit(0);
+
+// Si es un archivo directo en .planning/ (sin subdirectorio), es archivo
+// top-level: lo permitimos (ESTADO.md, nudges.jsonl, etc.).
+if (partes.length === 1) process.exit(0);
+
+const topDir = partes[0];
+
+// ─── Allowlist embebida (fallback portable) ────────────────────────────────
+// manifiestos/ NO se propaga a proyectos consumidores; el hook debe ser
+// autosuficiente. En el repo swl-ses se prefiere el manifest (fuente de
+// verdad); en consumidores se usa esta lista. Mantener ambas en sync.
+const DIRS_CANONICOS = [
+  'adrs', 'analysis', 'archive', 'audit', 'auto-evolution', 'backups',
+  'benchmark', 'comms', 'cron', 'design', 'evolution', 'fases', 'gateway',
+  'inbox', 'knowledge', 'locks', 'red-team', 'research', 'runs', 'sessions',
+  'traces', 'user-profile', 'wiki',
+];
+
+// ─── Cargar allowlist (manifest si existe, embebida si no) ──────────────────
+const CWD = process.cwd();
+const allowlistPath = path.join(CWD, 'manifiestos', 'planning-paths.json');
+let permitidos;
+try {
+  const allow = JSON.parse(fs.readFileSync(allowlistPath, 'utf-8'));
+  permitidos = new Set((allow.directorios || []).map((d) => d.nombre));
+} catch (_) {
+  permitidos = new Set(DIRS_CANONICOS);
+}
+if (permitidos.has(topDir)) process.exit(0);
+
+// Directorio top-level NO canonico -> divergencia potencial.
+// Detectar variante es/en conocida para sugerir el canonico correcto.
+const VARIANTES = {
+  auditoria: 'audit', auditorias: 'audit',
+  ux: 'design', ui: 'design', diseno: 'design', 'diseno-visual': 'design',
+  investigacion: 'research', conocimiento: 'knowledge',
+  evolucion: 'evolution', 'auto-evolucion': 'auto-evolution',
+  'perfil-usuario': 'user-profile', archivo: 'archive',
+  sesiones: 'sessions', decisiones: 'adrs',
+};
+const sugerido = VARIANTES[topDir] || null;
+
+// Ruta de display relativa a .planning/, independiente de si el path era
+// absoluto o relativo (resto ya es todo lo que sigue a '.planning/').
+const rutaRelativa = '.planning/' + resto;
+const nudge = {
+  id: crypto.randomBytes(8).toString('hex'),
+  kind: 'planning-path-divergente',
+  target: 'documentador-swl',
+  source: 'hooks/validar-planning-paths.js',
+  message:
+    `[planning-path] Se escribio en \`.planning/${topDir}/\`, un directorio top-level ` +
+    `NO canonico (${rutaRelativa}).\n` +
+    (sugerido
+      ? `  Probable divergencia es/en: usa el canonico \`.planning/${sugerido}/\` en su lugar.\n`
+      : `  Si es un dominio nuevo legitimo, agregalo a \`manifiestos/planning-paths.json\`.\n`) +
+    `  Ver \`reglas/analizar-directorios-antes-de-escribir.md\` y la allowlist canonica.`,
+  data: {
+    dir_detectado: topDir,
+    canonico_sugerido: sugerido,
+    archivo: rutaRelativa,
+  },
+  ts: new Date().toISOString(),
+  accionado: false,
+  accionado_ts: null,
+  accionado_por: null,
+};
+
+try {
+  const nudgesPath = path.join(CWD, '.planning', 'evolution', 'nudges.jsonl');
+  fs.mkdirSync(path.dirname(nudgesPath), { recursive: true });
+  fs.appendFileSync(nudgesPath, JSON.stringify(nudge) + '\n', 'utf-8');
+} catch (_) { /* no fallar el hook */ }
+
+process.exit(0);

package/llms.txt

@@ -0,0 +1,29 @@
+# swl-ses (@saulwade/swl-ses)
+
+> Sistema de ingeniería de software auto-evolutivo multi-runtime polyglot (SDLC completo), distribuido como paquete npm y plugin de Claude Code. 61 agentes, 181 habilidades, 45 comandos, 31 reglas base y 45 hooks. Soporta 11 lenguajes y 7 runtimes (Claude Code, OpenClaude, OpenCode, Gemini, Cursor, Codex, Copilot). Versión 1.9.0.
+
+Archivo generado por `node scripts/generar-inventario.js` — no editar a mano. Las cifras se sincronizan con INVENTARIO.md en cada regeneración.
+
+## Documentación
+
+- [README](README.md): overview público y quickstart
+- [Manual de uso](MANUAL_USO.md): manual operacional completo
+- [Comandos](COMANDOS.md): referencia detallada de cada comando `/swl:*`
+- [Agentes](AGENTS.md): catálogo de agentes con capacidades
+- [Inventario](INVENTARIO.md): conteos oficiales de todos los componentes
+- [Instalación](INSTALACION.md): instalación, perfiles y configuración
+- [Instrucciones del proyecto](CLAUDE.md): convenciones, stack y reglas
+
+## Componentes
+
+- 61 agentes especializados en `agentes/` (orquestación, implementación por stack, revisión, calidad, diseño)
+- 181 habilidades cargables bajo demanda en `habilidades/` (conocimiento operacional con divulgación progresiva)
+- 45 comandos `/swl:*` en `comandos/swl/` (ciclo GSD, calidad, release, diagnóstico)
+- 31 reglas base + 40 reglas por lenguaje en `reglas/` (políticas obligatorias por matcher)
+- 45 hooks en `hooks/` (telemetría, validación, seguridad; zero-deps, escrituras atómicas)
+
+## Opcional
+
+- [CHANGELOG](CHANGELOG.md): historial de versiones
+- [Índice de ADRs](.planning/adrs/README.md): decisiones de arquitectura
+- [Variables de entorno](docs/variables-entorno.md): configuración opt-in

package/manifiestos/hooks-config.json

@@ -17,13 +17,13 @@
   },
   "riskThresholds": {
     "allow": 0.35,
-    "review": 0.60,
+    "review": 0.6,
     "confirm": 0.85
   },
   "costBudget": {
     "maxUsd": 10.0,
     "maxTokens": 500000,
-    "alertAt": 0.80
+    "alertAt": 0.8
   },
   "circuitBreaker": {
     "maxConsecutiveFailures": 3,
@@ -171,7 +171,7 @@
     "actualizar-perfil-usuario.js": {
       "event": "Stop",
       "matcher": "",
-      "description": "Detecta señales de corrección/preferencia del usuario y acumula un dirty-bit en .planning/perfil-usuario/. Emite nudge a perfilador-usuario-swl cuando cruza el umbral (default 3 señales).",
+      "description": "Detecta señales de corrección/preferencia del usuario y acumula un dirty-bit en .planning/user-profile/. Emite nudge a perfilador-usuario-swl cuando cruza el umbral (default 3 señales).",
       "blocking": false,
       "async": true,
       "maxConsecutiveFailures": 5,
@@ -180,7 +180,7 @@
     "metricas-evolucion.js": {
       "event": "Stop",
       "matcher": "",
-      "description": "Consolida métricas del ciclo de evolución (nudges accionados/pendientes, instintos, fallos de agentes, evoluciones aplicadas/revertidas) y actualiza .planning/evolucion/metricas.json con health_score compuesto. Dispara escalamiento a alertas persistentes si >=5 nudges del mismo tipo ignorados en 14d.",
+      "description": "Consolida métricas del ciclo de evolución (nudges accionados/pendientes, instintos, fallos de agentes, evoluciones aplicadas/revertidas) y actualiza .planning/evolution/metricas.json con health_score compuesto. Dispara escalamiento a alertas persistentes si >=5 nudges del mismo tipo ignorados en 14d.",
       "blocking": false,
       "async": true,
       "maxConsecutiveFailures": 5,
@@ -198,7 +198,7 @@
     "auto-evolucion.js": {
       "event": "SubagentStop",
       "matcher": "",
-      "description": "Registra cada terminación de subagente SWL en .planning/auto-evolucion/agentes.jsonl y emite nudge a /swl:evolucionar cuando un agente acumula fallos o volumen de runs (ventana 14 días, throttle 24h).",
+      "description": "Registra cada terminación de subagente SWL en .planning/auto-evolution/agentes.jsonl y emite nudge a /swl:evolucionar cuando un agente acumula fallos o volumen de runs (ventana 14 días, throttle 24h).",
       "blocking": false,
       "async": true,
       "maxConsecutiveFailures": 5,
@@ -207,7 +207,7 @@
     "validar-formato-post-subagente.js": {
       "event": "SubagentStop",
       "matcher": "",
-      "description": "Valida output de subagentes con schema declarado en manifiestos/agent-output-schemas.json (revisor-* y tdd-qa). Registra violaciones en .planning/evolucion/formato-violaciones.jsonl. Opt-out: SWL_FORMATO_VALIDACION=0.",
+      "description": "Valida output de subagentes con schema declarado en manifiestos/agent-output-schemas.json (revisor-* y tdd-qa). Registra violaciones en .planning/evolution/formato-violaciones.jsonl. Opt-out: SWL_FORMATO_VALIDACION=0.",
       "blocking": false,
       "async": true,
       "maxConsecutiveFailures": 3,
@@ -301,6 +301,15 @@
       "maxConsecutiveFailures": 5,
       "degradeOnFailure": "skip"
     },
+    "contexto-iteracion.js": {
+      "event": "UserPromptSubmit",
+      "matcher": "",
+      "description": "Anti-context-rot para loops iterativos: inyecta el estado de la corrida activa en .planning/loops/ (iteración, últimas filas del TSV, plateau/recomendación de trayectoria). Throttled a 1 inyección cada 4 min por corrida. Opt-out: SWL_CONTEXTO_ITERACION=0.",
+      "blocking": false,
+      "async": true,
+      "maxConsecutiveFailures": 5,
+      "degradeOnFailure": "skip"
+    },
     "guardrail-modelo.js": {
       "event": "PreToolUse",
       "matcher": "Task|Agent",
@@ -323,7 +332,7 @@
     "captura-feedback-usuario.js": {
       "event": "UserPromptSubmit",
       "matcher": "",
-      "description": "Detecta correcciones explícitas del usuario (no hagas X, prefiero Y, recuerda Z, nunca W) y las encola en .planning/evolucion/feedback-queue.jsonl para consumo por perfilador-usuario-swl y el ciclo AGP. Patrones regex en español e inglés. Opt-out: SWL_CAPTURAR_FEEDBACK=0.",
+      "description": "Detecta correcciones explícitas del usuario (no hagas X, prefiero Y, recuerda Z, nunca W) y las encola en .planning/evolution/feedback-queue.jsonl para consumo por perfilador-usuario-swl y el ciclo AGP. Patrones regex en español e inglés. Opt-out: SWL_CAPTURAR_FEEDBACK=0.",
       "blocking": false,
       "async": true,
       "maxConsecutiveFailures": 5,
@@ -341,7 +350,7 @@
     "aiisms-detector.js": {
       "event": "PostToolUse",
       "matcher": "Write|Edit|MultiEdit",
-      "description": "Ejecuta detector portable Python contra archivos .md recién modificados y emite nudge a .planning/evolucion/nudges.jsonl si encuentra al menos un AI-ism P0. No bloquea. Requiere Python 3.10+. Respeta auto-referencia (habilidades/estilo-sin-ai-isms/), .planning/, temp/, node_modules/. Opt-out: SWL_AIISMS_HOOK=0.",
+      "description": "Ejecuta detector portable Python contra archivos .md recién modificados y emite nudge a .planning/evolution/nudges.jsonl si encuentra al menos un AI-ism P0. No bloquea. Requiere Python 3.10+. Respeta auto-referencia (habilidades/estilo-sin-ai-isms/), .planning/, temp/, node_modules/. Opt-out: SWL_AIISMS_HOOK=0.",
       "blocking": false,
       "async": true,
       "maxConsecutiveFailures": 5,
@@ -350,7 +359,7 @@
     "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.",
+      "description": "Ejecuta scripts/auditar-claudemd.js contra archivos CLAUDE.md recién modificados (basename exacto, no cualquier .md). Emite nudge a .planning/evolution/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,
@@ -359,7 +368,7 @@
     "claudemd-duplicacion-detector.js": {
       "event": "PostToolUse",
       "matcher": "Write|Edit|MultiEdit",
-      "description": "Detecta duplicación de reglas globales (~/.claude/rules/) inline en CLAUDE.md de proyecto. Consume scripts/lib/detector-reglas-duplicadas.js + catálogo scripts/lib/reglas-globales-conocidas.json. Aplica regla reglas/sin-duplicacion-reglas-globales.md. Emite nudge a .planning/evolucion/nudges.jsonl si hay duplicaciones detectadas. No bloquea — kind: claudemd-duplicacion-reglas. Excluye temp/, node_modules/, respositorios-git/, .planning/, ~/.claude/ (user-level). Opt-out: SWL_CLAUDEMD_DUPLICACION=0.",
+      "description": "Detecta duplicación de reglas globales (~/.claude/rules/) inline en CLAUDE.md de proyecto. Consume scripts/lib/detector-reglas-duplicadas.js + catálogo scripts/lib/reglas-globales-conocidas.json. Aplica regla reglas/sin-duplicacion-reglas-globales.md. Emite nudge a .planning/evolution/nudges.jsonl si hay duplicaciones detectadas. No bloquea — kind: claudemd-duplicacion-reglas. Excluye temp/, node_modules/, respositorios-git/, .planning/, ~/.claude/ (user-level). Opt-out: SWL_CLAUDEMD_DUPLICACION=0.",
       "blocking": false,
       "async": true,
       "maxConsecutiveFailures": 5,
@@ -368,7 +377,7 @@
     "validar-intent-spec.js": {
       "event": "PostToolUse",
       "matcher": "Write|Edit|MultiEdit",
-      "description": "Verifica que agentes nivelRiesgo:ALTO declaren las 6 partes del framework Intent Engineering (strategy, healthMetrics, steering, hardGuardrails, maxTurnos, fragmentos:[_intent-spec]) segun reglas/intent-engineering.md. Solo aplica a agentes/*.md no fragmentos. Emite nudge a .planning/evolucion/nudges.jsonl si faltan campos. No bloquea (modo warn-only inicial; promocion a blocking:true tras 2 semanas estables). Excluye temp/, node_modules/, respositorios-git/, _userland/, .planning/. Opt-out: SWL_INTENT_SPEC=0. ADR-0027.",
+      "description": "Verifica que agentes nivelRiesgo:ALTO declaren las 6 partes del framework Intent Engineering (strategy, healthMetrics, steering, hardGuardrails, maxTurnos, fragmentos:[_intent-spec]) segun reglas/intent-engineering.md. Solo aplica a agentes/*.md no fragmentos. Emite nudge a .planning/evolution/nudges.jsonl si faltan campos. No bloquea (modo warn-only inicial; promocion a blocking:true tras 2 semanas estables). Excluye temp/, node_modules/, respositorios-git/, _userland/, .planning/. Opt-out: SWL_INTENT_SPEC=0. ADR-0027.",
       "blocking": false,
       "async": true,
       "maxConsecutiveFailures": 5,
@@ -395,7 +404,7 @@
     "notificacion-telegram-subagent.js": {
       "event": "SubagentStop",
       "matcher": "",
-      "description": "Envía notificación Telegram cuando un subagente termina su turno. Best-effort: siempre exit 0. Comparte implementación con notificacion-telegram.js. Opt-out: SWL_NOTIFICACIONES_TELEGRAM=0.",
+      "description": "Envía notificación Telegram cuando un subagente termina su turno. INERTE por default: SubagentStop no está en los eventos default del script compartido porque duplica la notificación del Stop final (mismo cuerpo, dos mensajes). Activar con CLAUDE_NOTIFY_EVENTS=Stop,Notification,SubagentStop. Best-effort: siempre exit 0. Opt-out global: SWL_NOTIFICACIONES_TELEGRAM=0.",
       "blocking": false,
       "async": true,
       "maxConsecutiveFailures": 5,
@@ -409,6 +418,15 @@
       "async": false,
       "maxConsecutiveFailures": 5,
       "degradeOnFailure": "skip"
+    },
+    "validar-planning-paths.js": {
+      "event": "PostToolUse",
+      "matcher": "Write|Edit|MultiEdit",
+      "description": "Advierte cuando una sesion crea un directorio top-level NUEVO en .planning/ fuera de la allowlist canonica (manifiestos/planning-paths.json). Atrapa divergencias es/en (auditoria/ vs audit/, ux/ vs design/) antes de que proliferen. Aplica reglas/analizar-directorios-antes-de-escribir.md, cierra DT-PLANNING-OUTPUT-PATHS (ADR-0031). Emite nudge kind: planning-path-divergente a .planning/evolution/nudges.jsonl. No bloquea (warn-only). Opt-out: SWL_PLANNING_PATHS=0.",
+      "blocking": false,
+      "async": true,
+      "maxConsecutiveFailures": 5,
+      "degradeOnFailure": "skip"
     }
   }
 }