@saulwade/swl-ses 1.3.8 → 1.4.1

package/comandos/swl/nemesis.md

@@ -0,0 +1,122 @@
+---
+name: swl:nemesis
+description: >
+  Auditoría iterativa Feynman + State Inconsistency (loop hasta convergencia).
+  Invoca el agente nemesis-auditor-swl con los 2 skills subordinados.
+  Persiste hallazgos en .planning/audit/findings/.
+allowed-tools: [Read, Grep, Glob, Bash, Write, Agent]
+argument-hint: "[--pass1 | --pass2 | --continue | --modulo <ruta>]"
+---
+
+# /swl:nemesis — Auditoría iterativa de profundidad
+
+Dos auditores en loop: Feynman interroga suposiciones línea por línea; State
+Inconsistency mapea pares de estado acoplado y encuentra mutaciones
+incompletas. Cada pasada alimenta la siguiente hasta que no aparecen hallazgos
+nuevos o se llega al máximo de 6 pasadas.
+
+## Cuándo invocar
+
+- El módulo pasó `/swl:revisar` con score ≥ 9.0 pero hay sospechas de bugs
+  de lógica profunda que el revisor de código no captura (suposiciones
+  incorrectas, invariantes rotos, condiciones de carrera sutiles).
+- Antes de un release de componente crítico: auth, pagos, contratos, permisos.
+- Cuando un bug en producción se atribuye a lógica aparentemente correcta —
+  usar Nemesis para encontrar el patrón de fallo subyacente.
+- Para módulos legacy con alta deuda técnica donde los tests no cubren los
+  caminos de estado.
+
+## Cuándo NO invocar
+
+- El módulo tiene menos de 200 LOC y es CRUD simple sin lógica de negocio.
+- Se necesita revisión de estilo, naming o cobertura de tests — usar
+  `/swl:revisar` en su lugar.
+- El proyecto no tiene `agentes/nemesis-auditor-swl.md` instalado — verificar
+  con `ls agentes/ | grep nemesis` antes de invocar.
+- La tarea urgente es un hotfix en producción — Nemesis es deliberado (8-20
+  turnos); en incidente activo, usar `/swl:verificar` acotado.
+
+## Modos disponibles
+
+| Modo | Flag | Descripción |
+|---|---|---|
+| Loop completo (default) | (sin flag) | Pasada 1 (Feynman) + Pasada 2 (State) + N pasadas alternadas hasta convergencia, máximo 6 en total |
+| Solo Feynman | `--pass1` | Una pasada Feynman exhaustiva; no ejecuta State |
+| Solo State | `--pass2` | Una pasada State Inconsistency; puede alimentarse con findings previos de Feynman si existen en `.planning/audit/findings/` |
+| Retomar | `--continue` | Continúa desde la última pasada registrada en `.planning/audit/findings/`; útil si la sesión se interrumpió |
+| Acotar módulo | `--modulo <ruta>` | Limita el scope a un archivo o subdirectorio específico; se puede combinar con cualquier otro flag |
+
+## Qué produce
+
+Todos los archivos se crean en `.planning/audit/findings/`:
+
+| Archivo | Cuándo se genera |
+|---|---|
+| `feynman-pass[N].md` | Al completar cada pasada Feynman (N = número de pasada) |
+| `state-pass[N].md` | Al completar cada pasada State Inconsistency |
+| `nemesis-verified.md` | Al final del loop completo; consolida todos los hallazgos con estado de verificación |
+
+Si el directorio `.planning/audit/findings/` no existe, el agente lo crea antes
+de la primera escritura.
+
+## Cómo interpretar el reporte
+
+Cada hallazgo en los archivos de pasada usa este formato:
+
+```
+## [SEVERIDAD] Título del hallazgo
+
+**Discovery path**: Feynman-only | State-only | Cross-feed Pass N → Pass M
+**Verification**: Code trace | PoC test | Both
+**Líneas afectadas**: archivo:L1-L2
+
+Descripción del problema y por qué es un bug y no solo código sospechoso.
+```
+
+**Severidades**:
+
+| Nivel | Criterio |
+|---|---|
+| CRITICAL | Explotable sin precondiciones; pérdida de datos o control total |
+| HIGH | Explotable bajo condiciones razonables; impacto severo |
+| MEDIUM | Requiere condiciones específicas; impacto moderado |
+| LOW | Impacto menor o difícil de explotar; documentar para trazabilidad |
+
+**Discovery path** indica cuándo se encontró:
+
+- `Feynman-only`: Feynman lo detectó; State no lo confirmó ni refutó.
+- `State-only`: State Inconsistency lo encontró analizando mutaciones.
+- `Cross-feed Pass N → Pass M`: Feynman marcó un sospechoso en la pasada N;
+  State lo confirmó como bug real en la pasada M (o viceversa). Estos
+  hallazgos son los más confiables.
+
+**Verification** indica la evidencia disponible:
+
+- `Code trace`: el path al bug se puede seguir leyendo el código.
+- `PoC test`: hay un caso de prueba que demuestra el comportamiento incorrecto.
+- `Both`: lo más sólido; implica un test listo para agregar a la suite.
+
+## Costo estimado
+
+| Modo | Turnos aproximados |
+|---|---|
+| Loop completo, módulo pequeño (< 500 LOC) | 8-12 turnos |
+| Loop completo, módulo mediano (500-2000 LOC) | 12-18 turnos |
+| Loop completo, módulo grande (> 2000 LOC) | 18-30 turnos |
+| Solo `--pass1` o `--pass2` | 4-8 turnos |
+
+Para módulos mayores a 5000 LOC, usar `--modulo <ruta>` para acotar el scope.
+Un loop sobre un módulo gigante puede tomar 30+ turnos sin garantía de que los
+hallazgos sean más útiles que los de un subconjunto bien elegido.
+
+## Ejemplos de invocación
+
+```
+/swl:nemesis                               # loop completo del proyecto
+/swl:nemesis --modulo src/auth             # acotado al módulo auth
+/swl:nemesis --pass1 --modulo src/auth     # solo Feynman sobre auth
+/swl:nemesis --pass2                       # solo State sobre findings existentes
+/swl:nemesis --continue                    # retoma desde la última pasada guardada
+```
+
+<!-- Adaptado de nemesis-auditor-main bajo MIT License (transmissions11/nemesis-auditor) -->

package/comandos/swl/nuevo-proyecto.md

@@ -135,11 +135,33 @@ Estructura:
 - Si el usuario no definió fases claras, propón una división lógica basada en las respuestas del Bloque C
 - Estado inicial de todas las fases: "Pendiente"
 
-## Paso 6 — Reporte al usuario
+## Paso 6 — Generar CLAUDE.md inicial del proyecto
+
+Si NO existe `CLAUDE.md` en la raíz del proyecto, generarlo con la estructura
+mínima definida en `/swl:claudemd init-project`. **OBLIGATORIO** incluir como
+primera sección bajo el título:
+
+```markdown
+## Reglas obligatorias
+
+@reglas/usar-sistema-swl.md
+```
+
+Esta referencia carga la matriz operacional del sistema SWL al inicio de cada
+sesión del proyecto y previene que el agente haga trabajo directo cuando
+existe un componente especializado. Sin ella, el proyecto pierde el contrato
+de uso del sistema SWL.
+
+Si ya existe `CLAUDE.md` (verificado en Paso 1), revisar que incluya
+`@reglas/usar-sistema-swl.md` en la sección de reglas obligatorias. Si NO
+lo incluye, agregarlo en este paso preservando el resto del contenido.
+
+## Paso 7 — Reporte al usuario
 
 Al terminar, reporta:
 
-1. Lista de archivos creados con sus rutas absolutas
+1. Lista de archivos creados con sus rutas absolutas (incluyendo CLAUDE.md
+   si se generó o se modificó)
 2. Resumen de la investigación del agente (cuando esté disponible)
 3. Próximo paso recomendado: "Para comenzar a trabajar en la Fase 1, usa `/swl:discutir-fase 1`"
 4. Si encontraste riesgos o ambigüedades durante la entrevista, listarlos aquí como "Puntos a resolver"

package/comandos/swl/salud.md

@@ -33,6 +33,34 @@ echo "Reglas: $(ls reglas/*.md 2>/dev/null | wc -l)" && \
 echo "Hooks: $(ls hooks/*.js 2>/dev/null | wc -l)"
 ```
 
+## Paso 0.5 — Detección automática de tier del proyecto
+
+Antes de ejecutar los pasos de diagnóstico, /swl:salud detecta el tier del proyecto contando archivos relevantes:
+
+```bash
+find . -type f \
+  -not -path '*/node_modules/*' \
+  -not -path '*/.git/*' \
+  -not -path '*/dist/*' \
+  -not -path '*/build/*' \
+  -not -path '*/.next/*' \
+  -not -path '*/coverage/*' \
+  -not -path '*/__pycache__/*' \
+  -not -path '*/.cache/*' \
+  -not -path '*/.planning/sessions/*' \
+  | wc -l
+```
+
+| Tier | Rango | Características esperadas |
+|---|---|---|
+| **Simple** | <500 archivos | 1 contributor, CI mínimo o ninguno. CLAUDE.md opcional. Skills/agentes opcionales. |
+| **Standard** | 500–5,000 archivos | Equipo pequeño con CI. CLAUDE.md + 1-2 reglas. 2-4 skills. Hooks básicos. |
+| **Complex** | >5,000 archivos | Múltiples contributors, CI activo. Setup completo de 6 capas: agentes + skills + reglas + hooks + instintos + memoria. |
+
+El tier detectado se reporta al inicio del SALUD.md generado.
+
+**Default ante ambigüedad**: si el conteo cae cerca de 500 (490-510) o 5000 (4900-5100), aplicar el tier superior. Es preferible diagnosticar de más que de menos.
+
 ## Paso 1 — Diagnóstico de agentes (determinista)
 
 Ejecutar script Bash que verifica cada agente mecánicamente:
@@ -65,6 +93,8 @@ echo "Agentes: $ok OK, $warns advertencias, $errors errores"
 
 Score de agentes = `(ok / total) * 100`
 
+**Restricción de tier**: el análisis cruzado de agentes (cross-check entre `exclusiones` declaradas y rutas reales en `manifiestos/modulos.json`) se ejecuta solo en proyectos **Standard** o **Complex**. En tier Simple, reportar el conteo básico y omitir la validación cruzada.
+
 ## Paso 2 — Diagnóstico de skills (determinista)
 
 ```bash
@@ -109,6 +139,8 @@ grep -r "Skill(" agentes/ comandos/ 2>/dev/null | grep -o '"[^"]*"' | sort | uni
 
 Score de skills = `((total - errors*10 - warns*2) / total) * 100`, mínimo 0
 
+**Restricción de tier**: la detección de skills huérfanos (no referenciados en ningún agente ni comando) se ejecuta solo en proyectos **Standard** o **Complex**. En tier Simple, donde hay menos de 10 skills esperados, la verificación de huérfanos genera falsos positivos y se omite.
+
 ## Paso 3 — Diagnóstico de comandos (determinista)
 
 ```bash
@@ -413,3 +445,5 @@ Presenta resumen con los problemas más críticos. Si hay errores, listarlos tod
 - Los scores son aritmética pura. No ajustar el score "porque parece un sistema sano".
 - Si no hay git, omitir verificaciones dependientes y notar la omisión.
 - Si detectas un patrón sistémico (mismo error en múltiples componentes), mencionarlo en recomendaciones.
+
+<!-- Patrón de 3 tiers adaptado de Waza/skills/health bajo MIT License (tw93/Waza) -->

package/comandos/swl/verificar.md

@@ -13,6 +13,7 @@ Eres el coordinador de verificación SWL. Tu trabajo es asegurar la calidad del
 | Flag | Efecto |
 |------|--------|
 | (sin flag) | Verificación estándar: tests + linter + revisor-codigo-swl + revisor-seguridad-swl |
+| `--full` | Añade 4 audits ejecutables en paralelo al flujo estándar: `code-profiler.js`, `pentest-scanner.js`, `dep-doctor.js` y secret-scanner. Produce un scorecard agregado 0-100 con thresholds de aprobación. Ver sección "Modo `--full`". |
 | `--ultra` | Añade tercera pasada de **revisión profunda** con Opus 4.7 sobre los hallazgos de los dos revisores. Consolida, prioriza, detecta contradicciones entre reviewers y genera plan de acción. Ideal para fases críticas (auth, pagos, migraciones de schema, endpoints públicos). |
 | `--solo-codigo` | Ejecuta solo revisor-codigo-swl (salta seguridad). Usar solo para refactors internos sin impacto externo. |
 | `--solo-seguridad` | Ejecuta solo revisor-seguridad-swl (salta código). Usar para auditorías de seguridad focalizadas. |
@@ -576,6 +577,48 @@ El comando:
 repetía 2+ veces por sesión con alta variación sobre el alcance exacto. Formalizar
 con flag elimina los 2 mensajes de fricción y deja el scope auditable en el comando.
 
+## Modo `--full` — Parallel Scorecard
+
+Al pasar el flag `--full`, /swl:verificar lanza en paralelo 4 audits ejecutables además del flujo secuencial estándar (revisor-codigo-swl + revisor-seguridad-swl). Cada audit produce score 0-100 y findings JSON. El scorecard final agrega resultados con thresholds estándar.
+
+### Audits paralelos invocados
+
+| Tool | Detecta | Comando |
+|---|---|---|
+| `code-profiler.js` | N+1 queries, sync I/O en async, memory leaks, ReDoS, queries unbounded | `node scripts/audit-tools/code-profiler.js .` |
+| `pentest-scanner.js` | XSS, SQLi, SSTI, CORS misconfig, JWT vulnerabilities, prototype pollution | `node scripts/audit-tools/pentest-scanner.js <target>` |
+| `dep-doctor.js` | Deps no usadas, outdated, heavy deps con alternativa | `node scripts/audit-tools/dep-doctor.js .` |
+| `secret-scanner` (hook existente) | Credenciales hardcodeadas | (vía hook) |
+
+### Thresholds del scorecard
+
+| Score | Status | Acción |
+|---|---|---|
+| ≥80 | READY | Listo para mergear |
+| 60-79 | NEEDS WORK | Hallazgos menores; mergear bajo decisión informada |
+| <60 | NOT READY | Hallazgos críticos; bloquear merge |
+
+### Salida agregada
+
+El comando produce un reporte tipo:
+
+```
+SCORECARD — Audits paralelos
+─────────────────────────────────
+code-profiler:    95 / 100  [READY]
+pentest-scanner:  82 / 100  [READY]
+dep-doctor:       70 / 100  [NEEDS WORK]
+secret-scanner:  100 / 100  [READY]
+─────────────────────────────────
+Score promedio:   86.75     [READY]
+Total findings:   3 (0 críticos, 2 mayores, 1 menor)
+```
+
+### Cuándo usar `--full` vs flujo estándar
+
+- **Flujo estándar** (`/swl:verificar`): revisión cualitativa por agentes con criterio editorial. Adecuado para PRs pequeños/medianos donde la calidad arquitectónica importa más que cobertura mecánica.
+- **Flag `--full`**: agrega análisis estático y dinámico ejecutable. Adecuado pre-release, audit de seguridad mensual, o features que tocan endpoints, dependencias o lógica compleja.
+
 ## Reglas de comportamiento
 
 - NUNCA marques una fase como APROBADO si hay hallazgos CRÍTICOS de seguridad.
@@ -583,3 +626,5 @@ con flag elimina los 2 mensajes de fricción y deja el scope auditable en el com
 - Si los tests fallan, es siempre CRÍTICO, sin excepción.
 - Las SUGERENCIAS son de largo plazo — no bloquean el avance pero deben documentarse.
 - Si el RESUMEN.md no existe, usa git diff para inferir el alcance. Nunca te bloquees.
+
+<!-- El patrón parallel scorecard adaptado de Houseofmvps/ultraship /ship bajo MIT License -->

package/gateway/adapters/base.js

@@ -0,0 +1,109 @@
+'use strict';
+
+/**
+ * Base Adapter — Clase base abstracta para adaptadores de plataforma.
+ *
+ * Cada plataforma (Telegram, Discord, Webhook) extiende esta clase
+ * e implementa los métodos abstractos. El gateway/index.js orquesta
+ * múltiples adaptadores de forma uniforme.
+ *
+ * Patrón adoptado de Hermes Agent (gateway/platforms/base.py).
+ *
+ * @module gateway/adapters/base
+ */
+
+/**
+ * @abstract
+ */
+class BaseAdapter {
+  /**
+   * @param {string} name   - Nombre de la plataforma (ej: 'telegram').
+   * @param {object} config - Configuración específica de la plataforma.
+   */
+  constructor(name, config) {
+    if (new.target === BaseAdapter) {
+      throw new Error('BaseAdapter es abstracto — usar un adaptador concreto.');
+    }
+    this.name    = name;
+    this.config  = config;
+    this.running = false;
+    this._messageHandler = null;
+  }
+
+  /**
+   * Inicia la conexión con la plataforma.
+   * @abstract
+   * @returns {Promise<void>}
+   */
+  async start() {
+    throw new Error(`${this.name}: start() no implementado`);
+  }
+
+  /**
+   * Detiene la conexión con la plataforma.
+   * @abstract
+   * @returns {Promise<void>}
+   */
+  async stop() {
+    this.running = false;
+  }
+
+  /**
+   * Envía un mensaje formateado a la plataforma.
+   * @abstract
+   * @param {object} message
+   * @param {string} message.text    - Texto del mensaje (Markdown).
+   * @param {string} [message.chatId] - Destino específico.
+   * @param {string} [message.type]   - Tipo: 'notification', 'alert', 'response'.
+   * @returns {Promise<boolean>} true si se envió correctamente.
+   */
+  async send(message) {
+    throw new Error(`${this.name}: send() no implementado`);
+  }
+
+  /**
+   * Registra un handler para mensajes entrantes de la plataforma.
+   * @param {function} handler - Callback (message) => void.
+   */
+  onMessage(handler) {
+    this._messageHandler = handler;
+  }
+
+  /**
+   * Emite un mensaje entrante al handler registrado.
+   * @protected
+   * @param {object} message
+   */
+  _emitMessage(message) {
+    if (typeof this._messageHandler === 'function') {
+      this._messageHandler({
+        platform: this.name,
+        ...message,
+      });
+    }
+  }
+
+  /**
+   * Formatea un mensaje SWL para la plataforma específica.
+   * Override en cada adaptador para formato nativo (embeds, markdown, etc.).
+   *
+   * @param {object} swlMessage - Mensaje del sistema SWL.
+   * @returns {string} Texto formateado para la plataforma.
+   */
+  formatMessage(swlMessage) {
+    const { jobName, status, output, type } = swlMessage.payload || swlMessage;
+    const lines = [];
+
+    if (type === 'gateway_notification' || jobName) {
+      lines.push(`*${jobName || 'SWL Notificación'}*`);
+      if (status) lines.push(`Estado: ${status}`);
+      if (output) lines.push(`\`\`\`\n${output.substring(0, 500)}\n\`\`\``);
+    } else {
+      lines.push(swlMessage.text || JSON.stringify(swlMessage));
+    }
+
+    return lines.join('\n');
+  }
+}
+
+module.exports = BaseAdapter;

package/gateway/adapters/discord.js

@@ -0,0 +1,167 @@
+'use strict';
+
+/**
+ * Discord Adapter — Adaptador de plataforma para Discord.
+ *
+ * Usa discord.js para conectar un bot. Soporta:
+ *   - Recepción de mensajes en canal dedicado
+ *   - Envío con embeds para notificaciones estructuradas
+ *   - Comandos slash nativos
+ *   - Filtro por guildId y channelId
+ *
+ * Dependencia: discord.js (npm install discord.js)
+ * Si no está instalada, el adaptador se desactiva silenciosamente.
+ *
+ * Inspirado en Hermes Agent (gateway/platforms/discord.py).
+ *
+ * @module gateway/adapters/discord
+ */
+
+const BaseAdapter = require('./base');
+
+/** Límite de caracteres por mensaje de Discord. */
+const MAX_MSG_LENGTH = 2000;
+
+class DiscordAdapter extends BaseAdapter {
+  constructor(config) {
+    super('discord', config);
+    this._client = null;
+  }
+
+  async start() {
+    let Discord;
+    try {
+      Discord = require('discord.js');
+    } catch (_) {
+      console.log('[discord] discord.js no instalado. Ejecutar: npm install discord.js');
+      return;
+    }
+
+    const token = this.config.token || process.env.DISCORD_BOT_TOKEN;
+    if (!token) {
+      console.log('[discord] Token no configurado. Establecer DISCORD_BOT_TOKEN.');
+      return;
+    }
+
+    const { Client, GatewayIntentBits } = Discord;
+
+    this._client = new Client({
+      intents: [
+        GatewayIntentBits.Guilds,
+        GatewayIntentBits.GuildMessages,
+        GatewayIntentBits.MessageContent,
+      ],
+    });
+
+    this._client.on('ready', () => {
+      this.running = true;
+      console.log(`[discord] Bot conectado como ${this._client.user.tag}`);
+    });
+
+    this._client.on('messageCreate', (msg) => {
+      // Ignorar mensajes del bot
+      if (msg.author.bot) return;
+
+      // Filtrar por guild y canal si están configurados
+      if (this.config.guildId && msg.guildId !== this.config.guildId) return;
+      if (this.config.channelId && msg.channelId !== this.config.channelId) return;
+
+      const text    = msg.content || '';
+      const parts   = text.split(/\s+/);
+      const command = parts[0].startsWith('/') ? parts[0] : null;
+      const args    = command ? parts.slice(1).join(' ') : '';
+
+      this._emitMessage({
+        chatId:    msg.channelId,
+        userId:    msg.author.id,
+        userName:  msg.author.username,
+        text:      text,
+        command:   command,
+        args:      args,
+        guildId:   msg.guildId,
+        raw:       msg,
+      });
+    });
+
+    this._client.on('error', (err) => {
+      console.error(`[discord] Error: ${err.message}`);
+    });
+
+    await this._client.login(token);
+    console.log('[discord] Adaptador iniciado.');
+  }
+
+  async stop() {
+    if (this._client) {
+      try { await this._client.destroy(); } catch (_) {}
+      this._client = null;
+    }
+    this.running = false;
+    console.log('[discord] Adaptador detenido.');
+  }
+
+  async send(message) {
+    if (!this._client) return false;
+
+    const channelId = message.chatId || this.config.channelId;
+    if (!channelId) return false;
+
+    try {
+      const channel = await this._client.channels.fetch(channelId);
+      if (!channel || !channel.isTextBased()) return false;
+
+      const embed = this._buildEmbed(message);
+      if (embed) {
+        await channel.send({ embeds: [embed] });
+      } else {
+        const text = this.formatMessage(message);
+        // Split si excede límite
+        if (text.length > MAX_MSG_LENGTH) {
+          const chunks = [];
+          for (let i = 0; i < text.length; i += MAX_MSG_LENGTH) {
+            chunks.push(text.substring(i, i + MAX_MSG_LENGTH));
+          }
+          for (const chunk of chunks) await channel.send(chunk);
+        } else {
+          await channel.send(text);
+        }
+      }
+      return true;
+    } catch (err) {
+      console.error(`[discord] Error enviando: ${err.message}`);
+      return false;
+    }
+  }
+
+  /**
+   * Construye un embed de Discord para notificaciones estructuradas.
+   * @private
+   */
+  _buildEmbed(message) {
+    const payload = message.payload || message;
+    if (!payload.jobName && !payload.title) return null;
+
+    let Discord;
+    try { Discord = require('discord.js'); } catch (_) { return null; }
+
+    const { EmbedBuilder } = Discord;
+    const isError = payload.status === 'error';
+
+    const embed = new EmbedBuilder()
+      .setTitle(payload.jobName || payload.title || 'SWL Notificación')
+      .setColor(isError ? 0xFF0000 : 0x00CC66)
+      .setTimestamp();
+
+    if (payload.status) {
+      embed.addFields({ name: 'Estado', value: `\`${payload.status}\``, inline: true });
+    }
+    if (payload.output) {
+      const output = payload.output.substring(0, 1000);
+      embed.addFields({ name: 'Output', value: `\`\`\`\n${output}\n\`\`\`` });
+    }
+
+    return embed;
+  }
+}
+
+module.exports = DiscordAdapter;