@saulwade/swl-ses 1.3.7 → 1.4.0

package/comandos/swl/exportar-vault.md

@@ -17,9 +17,12 @@ Este comando es **complementario a `/swl:compactar`**, no lo reemplaza. Compacta
 - Saul lo pide explícitamente.
 - La sesión produjo una decisión arquitectural que afecta a otros proyectos del ecosistema.
 
-## Paso 0 — Validación del destino
+## Paso 0 — Validación del destino y canal de escritura
 
-Verifica que el vault existe y es accesible:
+Hay **dos canales** posibles para escribir al vault. El canal preferido es el
+MCP de Obsidian; el filesystem directo es fallback documentado.
+
+### 0a — Validar el vault en filesystem (para lectura y detección)
 
 ```bash
 test -d "F:\Google Drive\Developer\Obsidian\Vault\SWL\00-Inbox" \
@@ -29,6 +32,89 @@ test -d "F:\Google Drive\Developer\Obsidian\Vault\SWL\00-Inbox" \
 
 Si la ruta no es accesible (por ejemplo, Google Drive no sincronizado o letra de unidad distinta), **abortar con mensaje claro**. No intentes rutas alternativas sin permiso explícito.
 
+### 0b — Detectar disponibilidad del MCP de Obsidian
+
+Verifica si los tools `mcp__obsidian__obsidian_append_content` o
+`mcp__obsidian__obsidian_patch_content` están cargados o deferidos:
+
+- Si aparecen como **deferred** en `<system-reminder>`, cargar el schema con
+  `ToolSearch(query="select:mcp__obsidian__obsidian_append_content", ...)`.
+- Si tras `ToolSearch` siguen sin estar disponibles, el MCP server no está
+  corriendo (Obsidian cerrado o plugin Local REST API desactivado). En ese
+  caso usar canal de fallback (filesystem directo) — ver Paso 4.
+
+**Por qué MCP-first**: el hook `proteccion-rutas.js` bloquea la herramienta
+`Write` con destino fuera del CWD del proyecto. La ruta del vault
+(`F:\Google Drive\...`) siempre cae fuera del CWD si trabajas en
+`D:\Python\<proyecto>\`. El MCP de Obsidian opera vía HTTPS al puerto 27124
+del plugin Local REST API — **no pasa por el hook de filesystem**, así que
+nunca dispara el bloqueo.
+
+Defaultear a filesystem cuando el MCP está disponible es un anti-patrón
+documentado en `reglas/consultar-vault-primero.md § Workflow forzoso para
+escritura al vault`. El bloqueo por `proteccion-rutas.js` no es una falla a
+esquivar — es una señal de que el canal correcto es el MCP.
+
+### 0c — Verificar que el vault activo de Obsidian apunta a `Vault\SWL\` (CRÍTICO)
+
+> Origen del paso: sesión 2026-05-13 v1.4.0. El MCP de Obsidian resuelve paths
+> relativos contra el **vault que Obsidian tiene abierto**, no contra una
+> ruta hardcodeada en el plugin. Si Obsidian abrió un vault distinto del
+> esperado (ej. `F:\Google Drive\Developer\Obsidian\Vault\` raíz en lugar
+> de `Vault\SWL\`), todas las escrituras del MCP irán al vault equivocado.
+> El plugin **crea carpetas inexistentes** sobre la marcha, así que ni
+> siquiera obtendrás error — los archivos terminan en una ubicación huérfana.
+
+Verifica antes de cualquier llamada MCP:
+
+```bash
+# Path canónico de la config global de Obsidian en Windows
+APP="$APPDATA/obsidian/obsidian.json"
+node -e "
+const fs = require('fs');
+const data = JSON.parse(fs.readFileSync(process.argv[1], 'utf8'));
+const abierto = Object.values(data.vaults).find(v => v.open === true);
+console.log('Vault abierto:', abierto ? abierto.path : 'NINGUNO');
+console.log('Esperado:      F:\\\\Google Drive\\\\Developer\\\\Obsidian\\\\Vault\\\\SWL');
+console.log('OK:', abierto && abierto.path.endsWith('SWL') ? 'sí' : 'NO');
+" "$APP"
+```
+
+Resultado esperado:
+
+```
+Vault abierto: F:\Google Drive\Developer\Obsidian\Vault\SWL
+Esperado:      F:\Google Drive\Developer\Obsidian\Vault\SWL
+OK: sí
+```
+
+Si `OK: NO` o `Vault abierto: NINGUNO`, **NO usar MCP** — caer al filesystem
+para esta sesión y reportar al usuario que debe abrir el vault `SWL` en
+Obsidian (File → Open vault → seleccionar `F:\Google Drive\Developer\Obsidian\Vault\SWL`).
+
+### 0d — Verificar que la apiKey del MCP coincide con la del plugin activo
+
+> Origen: cuando el vault activo cambia, la apiKey del plugin Local REST API
+> cambia (cada vault tiene su propio `.obsidian/plugins/obsidian-local-rest-api/data.json`
+> con apiKey, cert y privateKey distintos). El MCP server registrado en
+> Claude.ai tiene una apiKey hardcodeada — si no se actualiza tras cambiar de
+> vault, todas las llamadas retornan `40101 Authorization required`.
+
+Si tras `ToolSearch` el MCP carga sus tools pero la primera llamada (ej.
+`obsidian_list_files_in_dir`) retorna `Error 40101: Authorization required`,
+el síntoma es claro: apiKey desincronizada.
+
+Acción:
+1. Leer la apiKey actual del plugin con
+   `grep '"apiKey"' "F:/Google Drive/Developer/Obsidian/Vault/SWL/.obsidian/plugins/obsidian-local-rest-api/data.json"`
+2. Reportar al usuario que actualice en **claude.ai → Settings → Connectors
+   → Obsidian → API Key**. Disconnect + Reconnect tras pegar el valor.
+3. Mientras tanto, usar filesystem como fallback para escribir al Inbox.
+
+Si hay procesos zombie de Obsidian o `mcp-obsidian` cliente con apiKey
+cacheada, requieren terminación + reinicio de Claude Code para tomar la
+nueva apiKey.
+
 ## Paso 1 — Identificación del proyecto actual
 
 Detecta qué proyecto eres leyendo:
@@ -205,23 +291,104 @@ Ejecutar `/sync-projects {proyecto-slug}` en el vault para integrar los cambios
 
 ## Paso 4 — Escritura en el vault
 
-Escribe el archivo en:
+El archivo destino es:
 
 ```
 F:\Google Drive\Developer\Obsidian\Vault\SWL\00-Inbox\YYYY-MM-DD_HHMM_export-{proyecto-slug}.md
 ```
 
-Usar UTF-8 sin BOM. En PowerShell:
+Con UTF-8 sin BOM. Usar **uno de dos canales** según disponibilidad:
+
+### Canal A (preferido) — MCP de Obsidian
+
+Si el Paso 0b confirmó que `mcp__obsidian__obsidian_append_content` está
+disponible (cargado directamente o tras `ToolSearch`), usar este canal:
+
+```jsonc
+// La ruta es RELATIVA al vault root (no incluye F:\...\SWL\)
+mcp__obsidian__obsidian_append_content({
+  filepath: "00-Inbox/YYYY-MM-DD_HHMM_export-{proyecto-slug}.md",
+  content: "<contenido completo del export>"
+})
+```
+
+Ventajas frente al filesystem:
+- **No pasa por `proteccion-rutas.js`** — el MCP opera vía HTTPS al puerto
+  27124, fuera del flujo de Bash/Write/Edit.
+- **Sin staging intermedio**: escribe directamente al archivo final del vault.
+- **Auditable**: el plugin Local REST API de Obsidian registra el acceso.
+- **Cross-OS**: el wrapper funciona idéntico en Windows/macOS/Linux sin
+  manejar separators de path.
+
+Notas operativas:
+- Si el archivo ya existe con ese timestamp (raro), agregar sufijo `_b`
+  al nombre antes de invocar `append_content`. El MCP de obsidian no
+  sobreescribe si el archivo existe — `append` agrega al final.
+- Si se necesita escribir secciones específicas en lugar de un archivo
+  completo, usar `mcp__obsidian__obsidian_patch_content` con
+  `target_type: "heading"`.
+
+### Canal B (fallback) — Filesystem directo
+
+Solo cuando el MCP no responde tras `ToolSearch` (Obsidian cerrado, plugin
+desactivado, sin red local). **Esto va a chocar con `proteccion-rutas.js`**
+si el CWD es el directorio del proyecto, así que requiere ejecución vía
+Bash con redirección o vía un comando del CLI nativo del SO:
 
 ```powershell
+# PowerShell — UTF-8 sin BOM
 $encoding = New-Object System.Text.UTF8Encoding($false)
 [System.IO.File]::WriteAllText($path, $content, $encoding)
 ```
 
-En Node.js hook o script:
+```bash
+# Bash + heredoc — UTF-8 sin BOM por default en Node 18+
+cat > "$path" <<'EOF'
+<contenido del export>
+EOF
+```
+
+**No usar `Write` directo** desde la herramienta del agente — `proteccion-rutas.js`
+lo bloquea. Si por algún motivo el agente necesita usar `Write`, primero
+escribe a `_userland/staging/<timestamp>.md` dentro del CWD, luego mueve con
+`Bash` (`mv` o PowerShell `Move-Item`).
+
+Reportar al usuario qué canal se usó:
+- Canal A → `[OK] Vía: MCP Obsidian (puerto 27124)`
+- Canal B → `[OK] Vía: filesystem directo (MCP no disponible)`
+- Canal Híbrido → `[OK] Vía: filesystem para Inbox, MCP para promociones`
+
+### Modo HÍBRIDO (validado en sesión 2026-05-13)
+
+Cuando la sesión incluye **autorización ampliada para promover documentos**
+a `02-Projects/`, `07-Decisions/` y `04-Resources/`, el flujo óptimo combina
+ambos canales:
+
+1. **Inbox** (`00-Inbox/YYYY-MM-DD_HHMM_export-{slug}.md`): usar siempre
+   **filesystem directo via Bash heredoc con ruta absoluta** (canal B). Razón:
+   el Bash heredoc bypassa cualquier desalineación del vault activo de
+   Obsidian — escribe directamente al disco en la ruta exacta.
+
+2. **Promociones** (a `02-Projects/`, `07-Decisions/`, `04-Resources/`):
+   usar **MCP append_content** (canal A) tras validar Pasos 0c y 0d. Razón:
+   las promociones requieren enlaces bidireccionales con `[[...]]` que el
+   plugin de Obsidian indexa al detectar la escritura. El filesystem directo
+   crea el archivo pero no dispara la reindexación hasta que Obsidian
+   detecte el cambio.
+
+3. **Aprobación de revisiones** (cambiar `status: pending-review` → `reviewed`
+   en frontmatter): si el archivo está en `00-Inbox/`, usar `sed` via Bash;
+   si está en `02-Projects/` etc., usar `mcp__obsidian__obsidian_patch_content`
+   con `target_type: "frontmatter"`. Validado que `patch_content` puede
+   responder 404 en algunos archivos pre-existentes — caer al filesystem si
+   falla.
+
+Reportar al usuario el desglose final del modo híbrido:
 
-```javascript
-fs.writeFileSync(path, content, { encoding: 'utf8' });
+```
+[OK] Inbox creado via filesystem: F:\...\00-Inbox\...md
+[OK] 3 promociones via MCP: 02-Projects, 07-Decisions, 04-Resources
+[OK] Revisión aprobada (reviewed: true) en el Inbox
 ```
 
 ## Paso 5 — Confirmación
@@ -267,6 +434,12 @@ Próximo paso: al abrir el vault, ejecuta:
 - Duplicar con el `COMPACTACION.md` del proyecto (copiar pega tal cual). El export es una **síntesis para vault**, no un espejo.
 - Intentar escribir directamente en `02-Projects/` del vault. Eso es zona ⚠️ en el vault — solo Saul decide si promoverlo.
 - Usar rutas con backslash no escapadas en código generado.
+- **Defaultear a filesystem cuando el MCP de Obsidian está disponible**.
+  El bloqueo por `proteccion-rutas.js` no es una falla a esquivar con Bash
+  staging — es señal de que el canal correcto es el MCP. Ver Paso 0b.
+- **Recurrir al workaround del filesystem antes de cargar el schema del
+  MCP con `ToolSearch`**. Tools deferred ≠ tools ausentes — el MCP server
+  está corriendo, solo falta cargar el schema. Cargar antes de defaultear.
 
 ## Relación con otros comandos SWL
 
@@ -285,7 +458,34 @@ Produce:
 
 ```
 [OK] Export creado: F:\Google Drive\Developer\Obsidian\Vault\SWL\00-Inbox\2026-04-16_2130_export-sigaf.md (487 palabras)
+[OK] Vía: MCP Obsidian (puerto 27124)
+[OK] Enlace canónico: [[DEV - SIGAF]]
 
 Próximo paso: al abrir el vault, ejecuta:
   /sync-projects sigaf
 ```
+
+## Historial de cambios del comando
+
+- **v1.4.0** (2026-05-13) — Agregados Pasos 0c y 0d con verificación previa
+  del vault activo de Obsidian y de la apiKey del MCP. Origen: sesión
+  2026-05-13 con autorización ampliada del usuario para promover docs;
+  el MCP escribió `02-Projects/DEV - swl-ses.md` en `Vault\` raíz en lugar
+  de `Vault\SWL\` porque Obsidian tenía abierto el vault un nivel arriba
+  del esperado. Hallazgo crítico: el plugin Local REST API resuelve paths
+  relativos contra el vault que Obsidian tiene abierto en `obsidian.json`
+  global, no contra una ruta hardcodeada. Si el vault activo está mal,
+  el MCP escribe a la ubicación equivocada sin error (el plugin crea
+  carpetas inexistentes). Agregado también Paso 0d para apiKey
+  desincronizada (síntoma `40101 Authorization required`). Y nuevo
+  modo HÍBRIDO en Paso 4: filesystem directo para Inbox + MCP para
+  promociones, validado en la misma sesión.
+
+- **v1.3.8** (2026-05-11) — Agregado flujo MCP-first en Paso 4 con detección
+  en Paso 0b. Origen: en la sesión v1.3.4 → v1.3.8 el comando defaultó a
+  `Write` directo al filesystem que fue bloqueado por `proteccion-rutas.js`.
+  El fallback al MCP funcionó pero quedó manual. Esta versión documenta
+  el orden de preferencia (MCP primero, filesystem como fallback explícito)
+  y agrega la nota de "tools deferred ≠ tools ausentes" en anti-patrones.
+  Aplicación de la regla `consultar-vault-primero.md § Workflow forzoso
+  para escritura al vault`.

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