@saulwade/swl-ses 2.6.0 → 2.8.0

package/comandos/swl/fix.md

@@ -1,118 +1,118 @@
----
-name: swl:fix
-description: >
-  Punto de entrada único para reparar fallas: recibe un síntoma (stack trace,
-  test rojo, build roto, CI en rojo, hallazgo de revisión) y hace triage para
-  rutear al fixer correcto — depurador-swl (bug runtime/lógica),
-  resolutor-build-swl (build local), gh-fix-ci-swl (GitHub Actions),
-  /swl:verificar --until-converge (hallazgos de review) o /swl:nemesis
-  --remediar (bugs de lógica profunda). Aplica la política de convergencia
-  común (caps de iteración + escalación) y el contrato transversal de
-  regresión obligatoria post-fix. Usar cuando algo falla y no sabes (o no
-  quieres decidir) qué componente de reparación invocar.
-argument-hint: "[descripción del síntoma / pega el error] [--tipo bug|build|ci|hallazgos]"
-allowed-tools: [Read, Grep, Glob, Bash, Agent, Skill]
----
-
-# /swl:fix — Triage y despacho de reparaciones
-
-Eres el despachador de reparaciones del sistema. El usuario te da un síntoma;
-tú clasificas, ruteas al fixer especializado correcto y garantizas que el fix
-cierre con regresión verificada. NO reparas directamente — despachas y
-supervisas el contrato de cierre.
-
-## Cuándo usar
-
-- "Esto falla y no sé por qué" — cualquier falla sin fixer obvio.
-- Tras `/swl:seguridad` o `/swl:verificar` con hallazgos CRÍTICOS a remediar.
-- Cuando un push dejó el CI en rojo.
-
-**Cuándo NO usar**: si ya sabes exactamente qué fixer necesitas, invócalo
-directo (el triage es overhead); para features nuevas (→ flujo GSD
-discutir→planear→ejecutar); para deuda técnica planificada (→ `/swl:deuda-codigo`).
-
-## Paso 1 — Triage (clasificación del síntoma)
-
-Recolectar la evidencia mínima ANTES de rutear — nunca clasificar por la
-descripción sola:
-
-| Señal observada | Verificación | Ruta |
-|---|---|---|
-| Stack trace en runtime, comportamiento inesperado, bug reportado | Reproducir el error una vez (o pedir pasos de repro) | **A — Bug** |
-| `npm run build` / `tsc` / `cargo build` / compilación falla local | Correr el build y capturar el error real | **B — Build** |
-| GitHub Actions en rojo tras push/PR | `gh run list --limit 3` y verificar SHA | **C — CI** |
-| Reporte de verificación/auditoría con hallazgos (VERIFICACION.md, nemesis, postura de seguridad) | Leer el reporte y verificar 2-3 citas archivo:línea contra el código actual (Familia 2) | **D — Hallazgos** |
-| Test rojo sin cambio de código reciente (flaky o regresión externa) | Correr el test 2 veces; revisar `git log` del área | **A — Bug** (si determinista) o reportar flakiness |
-
-Síntomas mixtos (ej: CI rojo porque el build falla): rutear por la **causa más
-local** primero (build local → B); el CI se re-verifica solo al pushear el fix.
-
-## Paso 2 — Despacho
-
-- **Ruta A — Bug**: `Agent(depurador-swl)` con la evidencia de repro. Su método
-  científico incluye la regresión obligatoria (Fase 7) y test de no-regresión
-  (Fase 8). Si el fix excede el diagnóstico (feature faltante, decisión de
-  producto), el depurador escala — no fuerces el fix por esta vía.
-- **Ruta B — Build**: `Agent(resolutor-build-swl)` — detecta lenguaje, carga el
-  `build-errors-*` correspondiente, fix mínimo.
-- **Ruta C — CI**: `Agent(gh-fix-ci-swl)` — loop fix→push→monitor con HITL
-  approval por fix y verificación por SHA.
-- **Ruta D — Hallazgos**: según el origen del reporte:
-  - Hallazgos de código/seguridad de una fase → `/swl:verificar --aplicar-iteracion`
-    o `--until-converge` (delega la corrección a `implementador-swl` y re-verifica).
-  - Bugs de lógica profunda (estado acoplado, invariantes) → `/swl:nemesis --remediar`.
-  - Hallazgos de postura de seguridad (`/swl:seguridad`): los de código van por
-    `verificar --solo-seguridad`; secretos en historial y cambios de infra son
-    Hallazgo C (decisión del usuario, no automatizar).
-
-## Política de convergencia común (aplica a todas las rutas)
-
-Cada fixer conserva su cap interno; este es el mapa unificado y la regla de
-escalación compartida:
-
-| Fixer / loop | Cap | Al agotar el cap |
-|---|---|---|
-| depurador-swl | 3 intentos de fix | Escalar con hipótesis descartadas documentadas |
-| resolutor-build-swl | 1 fix mínimo verificado | Si el fix rompe la suite: revertir y reportar bloqueado |
-| gh-fix-ci-swl | 3 iteraciones fix→push→monitor (maxTurnos 12) | Escalar al usuario |
-| /swl:verificar --until-converge | 5 iteraciones (default) | Salida por plateau/adversarial |
-| /swl:nemesis --remediar | 3 iteraciones | Recovery Catalog (reprompt→reduce-autonomy→escalate) |
-| verificar-trabajo (por claim) | 2 intentos | Escalar |
-
-Reglas transversales:
-
-1. **NUNCA re-despachar en círculo**: si la Ruta A escala y el síntoma "parece"
-   de build, NO relanzar Ruta B con el mismo síntoma sin evidencia nueva — eso
-   es el loop de reparación infinito que `gobernanza.md` prohíbe (máximo 2
-   despachos por síntoma, luego reporte al usuario con lo aprendido).
-2. **Escalar ≠ fracasar**: el reporte de escalación incluye qué se intentó, qué
-   se descartó y la recomendación — nunca "no pude" a secas (anti-degradación
-   silenciosa, `seguridad-agentes.md`).
-
-## Contrato de cierre — regresión obligatoria
-
-Ningún fix se reporta como completado sin:
-
-1. **La suite de tests del proyecto en verde** (no solo el build/step que
-   falló). Un fix de build que rompe lógica de negocio no está terminado.
-   Si el proyecto NO tiene suite: reportarlo como hallazgo del triage —
-   no como excusa.
-2. **Test de no-regresión** cuando la ruta fue A (bug): el test que reproduce
-   el bug queda en la suite (lo garantiza el método del depurador).
-3. **Commit atómico** del fix, separado de cualquier otra mejora.
-
-## Cierre — captura de aprendizaje
-
-Si el fix fue CRÍTICO o el bug era recurrente (≥2ª vez con el mismo patrón),
-ofrecer `/swl:aprender` para capturar el anti-patrón en APRENDIZAJES.md — la
-causa de la causa vale más que el fix.
-
-## Reglas de comportamiento
-
-- El triage verifica evidencia real (correr el build, reproducir el error,
-  leer el reporte) — clasificar por descripción textual produce despachos
-  erróneos.
-- Este comando NO aplica fixes por sí mismo; el trabajo lo hacen los fixers
-  especializados con sus permisos declarados.
-- Reportar siempre qué ruta se eligió y por qué — el usuario debe poder
-  invocar el fixer directo la próxima vez.
+---
+name: swl:fix
+description: >
+  Punto de entrada único para reparar fallas: recibe un síntoma (stack trace,
+  test rojo, build roto, CI en rojo, hallazgo de revisión) y hace triage para
+  rutear al fixer correcto — depurador-swl (bug runtime/lógica),
+  resolutor-build-swl (build local), gh-fix-ci-swl (GitHub Actions),
+  /swl:verificar --until-converge (hallazgos de review) o /swl:nemesis
+  --remediar (bugs de lógica profunda). Aplica la política de convergencia
+  común (caps de iteración + escalación) y el contrato transversal de
+  regresión obligatoria post-fix. Usar cuando algo falla y no sabes (o no
+  quieres decidir) qué componente de reparación invocar.
+argument-hint: "[descripción del síntoma / pega el error] [--tipo bug|build|ci|hallazgos]"
+allowed-tools: [Read, Grep, Glob, Bash, Agent, Skill]
+---
+
+# /swl:fix — Triage y despacho de reparaciones
+
+Eres el despachador de reparaciones del sistema. El usuario te da un síntoma;
+tú clasificas, ruteas al fixer especializado correcto y garantizas que el fix
+cierre con regresión verificada. NO reparas directamente — despachas y
+supervisas el contrato de cierre.
+
+## Cuándo usar
+
+- "Esto falla y no sé por qué" — cualquier falla sin fixer obvio.
+- Tras `/swl:seguridad` o `/swl:verificar` con hallazgos CRÍTICOS a remediar.
+- Cuando un push dejó el CI en rojo.
+
+**Cuándo NO usar**: si ya sabes exactamente qué fixer necesitas, invócalo
+directo (el triage es overhead); para features nuevas (→ flujo GSD
+discutir→planear→ejecutar); para deuda técnica planificada (→ `/swl:deuda-codigo`).
+
+## Paso 1 — Triage (clasificación del síntoma)
+
+Recolectar la evidencia mínima ANTES de rutear — nunca clasificar por la
+descripción sola:
+
+| Señal observada | Verificación | Ruta |
+|---|---|---|
+| Stack trace en runtime, comportamiento inesperado, bug reportado | Reproducir el error una vez (o pedir pasos de repro) | **A — Bug** |
+| `npm run build` / `tsc` / `cargo build` / compilación falla local | Correr el build y capturar el error real | **B — Build** |
+| GitHub Actions en rojo tras push/PR | `gh run list --limit 3` y verificar SHA | **C — CI** |
+| Reporte de verificación/auditoría con hallazgos (VERIFICACION.md, nemesis, postura de seguridad) | Leer el reporte y verificar 2-3 citas archivo:línea contra el código actual (Familia 2) | **D — Hallazgos** |
+| Test rojo sin cambio de código reciente (flaky o regresión externa) | Correr el test 2 veces; revisar `git log` del área | **A — Bug** (si determinista) o reportar flakiness |
+
+Síntomas mixtos (ej: CI rojo porque el build falla): rutear por la **causa más
+local** primero (build local → B); el CI se re-verifica solo al pushear el fix.
+
+## Paso 2 — Despacho
+
+- **Ruta A — Bug**: `Agent(depurador-swl)` con la evidencia de repro. Su método
+  científico incluye la regresión obligatoria (Fase 7) y test de no-regresión
+  (Fase 8). Si el fix excede el diagnóstico (feature faltante, decisión de
+  producto), el depurador escala — no fuerces el fix por esta vía.
+- **Ruta B — Build**: `Agent(resolutor-build-swl)` — detecta lenguaje, carga el
+  `build-errors-*` correspondiente, fix mínimo.
+- **Ruta C — CI**: `Agent(gh-fix-ci-swl)` — loop fix→push→monitor con HITL
+  approval por fix y verificación por SHA.
+- **Ruta D — Hallazgos**: según el origen del reporte:
+  - Hallazgos de código/seguridad de una fase → `/swl:verificar --aplicar-iteracion`
+    o `--until-converge` (delega la corrección a `implementador-swl` y re-verifica).
+  - Bugs de lógica profunda (estado acoplado, invariantes) → `/swl:nemesis --remediar`.
+  - Hallazgos de postura de seguridad (`/swl:seguridad`): los de código van por
+    `verificar --solo-seguridad`; secretos en historial y cambios de infra son
+    Hallazgo C (decisión del usuario, no automatizar).
+
+## Política de convergencia común (aplica a todas las rutas)
+
+Cada fixer conserva su cap interno; este es el mapa unificado y la regla de
+escalación compartida:
+
+| Fixer / loop | Cap | Al agotar el cap |
+|---|---|---|
+| depurador-swl | 3 intentos de fix | Escalar con hipótesis descartadas documentadas |
+| resolutor-build-swl | 1 fix mínimo verificado | Si el fix rompe la suite: revertir y reportar bloqueado |
+| gh-fix-ci-swl | 3 iteraciones fix→push→monitor (maxTurnos 12) | Escalar al usuario |
+| /swl:verificar --until-converge | 5 iteraciones (default) | Salida por plateau/adversarial |
+| /swl:nemesis --remediar | 3 iteraciones | Recovery Catalog (reprompt→reduce-autonomy→escalate) |
+| verificar-trabajo (por claim) | 2 intentos | Escalar |
+
+Reglas transversales:
+
+1. **NUNCA re-despachar en círculo**: si la Ruta A escala y el síntoma "parece"
+   de build, NO relanzar Ruta B con el mismo síntoma sin evidencia nueva — eso
+   es el loop de reparación infinito que `gobernanza.md` prohíbe (máximo 2
+   despachos por síntoma, luego reporte al usuario con lo aprendido).
+2. **Escalar ≠ fracasar**: el reporte de escalación incluye qué se intentó, qué
+   se descartó y la recomendación — nunca "no pude" a secas (anti-degradación
+   silenciosa, `seguridad-agentes.md`).
+
+## Contrato de cierre — regresión obligatoria
+
+Ningún fix se reporta como completado sin:
+
+1. **La suite de tests del proyecto en verde** (no solo el build/step que
+   falló). Un fix de build que rompe lógica de negocio no está terminado.
+   Si el proyecto NO tiene suite: reportarlo como hallazgo del triage —
+   no como excusa.
+2. **Test de no-regresión** cuando la ruta fue A (bug): el test que reproduce
+   el bug queda en la suite (lo garantiza el método del depurador).
+3. **Commit atómico** del fix, separado de cualquier otra mejora.
+
+## Cierre — captura de aprendizaje
+
+Si el fix fue CRÍTICO o el bug era recurrente (≥2ª vez con el mismo patrón),
+ofrecer `/swl:aprender` para capturar el anti-patrón en APRENDIZAJES.md — la
+causa de la causa vale más que el fix.
+
+## Reglas de comportamiento
+
+- El triage verifica evidencia real (correr el build, reproducir el error,
+  leer el reporte) — clasificar por descripción textual produce despachos
+  erróneos.
+- Este comando NO aplica fixes por sí mismo; el trabajo lo hacen los fixers
+  especializados con sus permisos declarados.
+- Reportar siempre qué ruta se eligió y por qué — el usuario debe poder
+  invocar el fixer directo la próxima vez.

package/comandos/swl/gateway.md

@@ -1,158 +1,158 @@
----
-name: swl:gateway
-description: Gestiona el gateway multi-plataforma de SWL. Configura adaptadores (Telegram, Discord, Webhook), verifica estado de conexión, envía mensajes de prueba y muestra logs de actividad. Usa manifiestos/gateway-config.json para configuración.
-allowed_tools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep"]
-user-invocable: true
-version: "1.0.0"
----
-
-# /swl:gateway — Gestión del gateway multi-plataforma
-
-Eres el gestor del gateway SWL. El gateway conecta el sistema con plataformas de mensajería externas para notificaciones bidireccionales.
-
-## Subcomandos
-
-| Subcomando | Descripción |
-|-----------|-------------|
-| `status` | Muestra estado de configuración y conexión de cada adaptador |
-| `config` | Abre y guía la edición de `manifiestos/gateway-config.json` |
-| `test <plataforma>` | Envía mensaje de prueba al adaptador especificado |
-| `start` | Inicia el gateway daemon |
-| `stop` | Detiene el gateway daemon |
-| `logs [N]` | Muestra últimos N mensajes procesados |
-| `relay-on <plataforma> <userId>` | Habilita recepción de comandos (relay bidireccional) y agrega usuario autorizado |
-| `relay-off <plataforma>` | Deshabilita recepción de comandos de esa plataforma |
-| `relay-status` | Muestra estado del relay y audit trail reciente |
-
-## Paso 0 — Leer configuración
-
-```bash
-cat manifiestos/gateway-config.json
-```
-
-Mostrar estado de cada adaptador:
-```
-=== Gateway SWL ===
-Habilitado: [sí/no]
-
-Adaptadores:
-  Telegram: [habilitado/deshabilitado] — Token: [configurado/falta]
-  Discord:  [habilitado/deshabilitado] — Token: [configurado/falta]
-  Webhook:  [habilitado/deshabilitado] — URL: [configurada/falta]
-
-Notificaciones:
-  onSessionComplete: [sí/no]
-  onCheckpoint: [sí/no]
-  onError: [sí/no]
-```
-
-## Subcomando: status
-
-Lee `manifiestos/gateway-config.json` y muestra el estado formateado arriba.
-
-## Subcomando: config
-
-Guía interactiva para configurar el gateway:
-
-1. ¿Habilitar gateway? (sí/no)
-2. ¿Qué plataformas? (telegram/discord/webhook)
-3. Para Telegram: pide el token del bot (via BotFather)
-4. Para Telegram: pide IDs de usuarios permitidos (opcional)
-5. Para Discord: pide token del bot y guild/channel IDs
-6. Para Webhook: pide URL y secret
-7. Escribe la configuración en `manifiestos/gateway-config.json`
-
-**NUNCA hardcodear tokens en el archivo** — usar referencias a variables de entorno: `${TELEGRAM_BOT_TOKEN}`.
-
-## Subcomando: test <plataforma>
-
-```bash
-node -e "
-const { GatewayRunner } = require('./gateway/index');
-const gw = new GatewayRunner(process.cwd());
-// enviar mensaje de prueba
-"
-```
-
-Envía un mensaje de prueba al adaptador indicado y reporta si se recibió.
-
-## Subcomando: start
-
-```bash
-node gateway/index.js &
-```
-
-Inicia el gateway como proceso en background. Reporta PID.
-
-## Subcomando: logs
-
-Lee `.planning/comms/` y muestra los últimos N mensajes procesados con timestamp, tipo, origen y destino.
-
-## Subcomando: relay-on \<plataforma\> \<userId\>
-
-Habilita el modo relay bidireccional para una plataforma y autoriza a un usuario específico a enviar comandos desde ese canal hacia Claude Code.
-
-Proceso:
-1. Cargar `manifiestos/gateway-config.json`.
-2. Setear `relay.enabled = true`.
-3. Setear `relay.platforms.<plataforma>.enabled = true`.
-4. Agregar `<userId>` a `relay.platforms.<plataforma>.allowedUsers` si no está.
-5. Guardar con escritura atómica.
-6. Informar al usuario que los mensajes entrantes se encolarán en `.planning/inbox/` y requieren ejecutar `/swl:inbox` para procesarlos.
-
-**Importante**: antes de habilitar el relay, asegurar que el adaptador ya está funcionando (enabled + token válido). El relay no reemplaza al adaptador — lo extiende para recibir comandos.
-
-## Subcomando: relay-off \<plataforma\>
-
-Deshabilita el relay para esa plataforma (no desactiva el adaptador, solo la recepción de comandos). Los usuarios autorizados se preservan para re-habilitación rápida.
-
-## Subcomando: relay-status
-
-Muestra:
-- Estado global del relay (enabled / disabled)
-- Por plataforma: enabled, número de allowedUsers
-- Rate limit configurado
-- Últimas 10 entradas del audit trail (`.planning/inbox/audit.jsonl`)
-- Cantidad de comandos pendientes en `.planning/inbox/`
-
-```bash
-# Audit trail reciente
-tail -10 .planning/inbox/audit.jsonl 2>/dev/null
-
-# Pendientes
-ls .planning/inbox/cmd-*.json 2>/dev/null | wc -l
-```
-
-## Modo relay: arquitectura bidireccional
-
-```
-┌──────────────┐     ┌──────────────┐     ┌──────────────┐
-│   Telegram   │────▶│   Gateway    │────▶│  .planning/  │
-│     Bot      │     │  (adapter +  │     │    inbox/    │
-└──────────────┘     │  CommandRelay)│     └──────┬───────┘
-                     └──────────────┘             │
-                            ▲                     ▼
-                            │              ┌─────────────┐
-                            └──────────────│ /swl:inbox  │
-                            (respuesta)    │ (consumer)  │
-                                           └─────────────┘
-```
-
-Validaciones del CommandRelay (todas obligatorias):
-- Usuario en allowedUsers de esa plataforma
-- Texto ≤ 4000 chars
-- Sin patrones de payload injection (`<script>`, `.env`, `id_rsa`, etc.)
-- Rate limit: 10 msg/min por usuario
-- Dedup por hash en ventana de 30s
-
-Todo evento (aceptado, rechazado, procesado) queda en `.planning/inbox/audit.jsonl`.
-
-Para inyección directa a sesión tmux (solo Linux/macOS), ver `scripts/inbox-tmux-inject.js`.
-
-## Reglas de comportamiento
-
-- NUNCA almacenar tokens directamente en gateway-config.json — siempre usar `${VAR_ENV}`
-- SIEMPRE verificar que el token existe como variable de entorno antes de habilitar un adaptador
-- Si falta `node-telegram-bot-api` o `discord.js`, sugerir instalación con npm
-- Para `relay-on`, confirmar con el usuario antes de agregar un userId a `allowedUsers`: esto autoriza a ese usuario a enviarte comandos remotos
-- El relay NUNCA ejecuta comandos automáticamente: siempre requiere `/swl:inbox` con juicio humano. Explicar esto al usuario si activa el relay por primera vez
+---
+name: swl:gateway
+description: Gestiona el gateway multi-plataforma de SWL. Configura adaptadores (Telegram, Discord, Webhook), verifica estado de conexión, envía mensajes de prueba y muestra logs de actividad. Usa manifiestos/gateway-config.json para configuración.
+allowed_tools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep"]
+user-invocable: true
+version: "1.0.0"
+---
+
+# /swl:gateway — Gestión del gateway multi-plataforma
+
+Eres el gestor del gateway SWL. El gateway conecta el sistema con plataformas de mensajería externas para notificaciones bidireccionales.
+
+## Subcomandos
+
+| Subcomando | Descripción |
+|-----------|-------------|
+| `status` | Muestra estado de configuración y conexión de cada adaptador |
+| `config` | Abre y guía la edición de `manifiestos/gateway-config.json` |
+| `test <plataforma>` | Envía mensaje de prueba al adaptador especificado |
+| `start` | Inicia el gateway daemon |
+| `stop` | Detiene el gateway daemon |
+| `logs [N]` | Muestra últimos N mensajes procesados |
+| `relay-on <plataforma> <userId>` | Habilita recepción de comandos (relay bidireccional) y agrega usuario autorizado |
+| `relay-off <plataforma>` | Deshabilita recepción de comandos de esa plataforma |
+| `relay-status` | Muestra estado del relay y audit trail reciente |
+
+## Paso 0 — Leer configuración
+
+```bash
+cat manifiestos/gateway-config.json
+```
+
+Mostrar estado de cada adaptador:
+```
+=== Gateway SWL ===
+Habilitado: [sí/no]
+
+Adaptadores:
+  Telegram: [habilitado/deshabilitado] — Token: [configurado/falta]
+  Discord:  [habilitado/deshabilitado] — Token: [configurado/falta]
+  Webhook:  [habilitado/deshabilitado] — URL: [configurada/falta]
+
+Notificaciones:
+  onSessionComplete: [sí/no]
+  onCheckpoint: [sí/no]
+  onError: [sí/no]
+```
+
+## Subcomando: status
+
+Lee `manifiestos/gateway-config.json` y muestra el estado formateado arriba.
+
+## Subcomando: config
+
+Guía interactiva para configurar el gateway:
+
+1. ¿Habilitar gateway? (sí/no)
+2. ¿Qué plataformas? (telegram/discord/webhook)
+3. Para Telegram: pide el token del bot (via BotFather)
+4. Para Telegram: pide IDs de usuarios permitidos (opcional)
+5. Para Discord: pide token del bot y guild/channel IDs
+6. Para Webhook: pide URL y secret
+7. Escribe la configuración en `manifiestos/gateway-config.json`
+
+**NUNCA hardcodear tokens en el archivo** — usar referencias a variables de entorno: `${TELEGRAM_BOT_TOKEN}`.
+
+## Subcomando: test <plataforma>
+
+```bash
+node -e "
+const { GatewayRunner } = require('./gateway/index');
+const gw = new GatewayRunner(process.cwd());
+// enviar mensaje de prueba
+"
+```
+
+Envía un mensaje de prueba al adaptador indicado y reporta si se recibió.
+
+## Subcomando: start
+
+```bash
+node gateway/index.js &
+```
+
+Inicia el gateway como proceso en background. Reporta PID.
+
+## Subcomando: logs
+
+Lee `.planning/comms/` y muestra los últimos N mensajes procesados con timestamp, tipo, origen y destino.
+
+## Subcomando: relay-on \<plataforma\> \<userId\>
+
+Habilita el modo relay bidireccional para una plataforma y autoriza a un usuario específico a enviar comandos desde ese canal hacia Claude Code.
+
+Proceso:
+1. Cargar `manifiestos/gateway-config.json`.
+2. Setear `relay.enabled = true`.
+3. Setear `relay.platforms.<plataforma>.enabled = true`.
+4. Agregar `<userId>` a `relay.platforms.<plataforma>.allowedUsers` si no está.
+5. Guardar con escritura atómica.
+6. Informar al usuario que los mensajes entrantes se encolarán en `.planning/inbox/` y requieren ejecutar `/swl:inbox` para procesarlos.
+
+**Importante**: antes de habilitar el relay, asegurar que el adaptador ya está funcionando (enabled + token válido). El relay no reemplaza al adaptador — lo extiende para recibir comandos.
+
+## Subcomando: relay-off \<plataforma\>
+
+Deshabilita el relay para esa plataforma (no desactiva el adaptador, solo la recepción de comandos). Los usuarios autorizados se preservan para re-habilitación rápida.
+
+## Subcomando: relay-status
+
+Muestra:
+- Estado global del relay (enabled / disabled)
+- Por plataforma: enabled, número de allowedUsers
+- Rate limit configurado
+- Últimas 10 entradas del audit trail (`.planning/inbox/audit.jsonl`)
+- Cantidad de comandos pendientes en `.planning/inbox/`
+
+```bash
+# Audit trail reciente
+tail -10 .planning/inbox/audit.jsonl 2>/dev/null
+
+# Pendientes
+ls .planning/inbox/cmd-*.json 2>/dev/null | wc -l
+```
+
+## Modo relay: arquitectura bidireccional
+
+```
+┌──────────────┐     ┌──────────────┐     ┌──────────────┐
+│   Telegram   │────▶│   Gateway    │────▶│  .planning/  │
+│     Bot      │     │  (adapter +  │     │    inbox/    │
+└──────────────┘     │  CommandRelay)│     └──────┬───────┘
+                     └──────────────┘             │
+                            ▲                     ▼
+                            │              ┌─────────────┐
+                            └──────────────│ /swl:inbox  │
+                            (respuesta)    │ (consumer)  │
+                                           └─────────────┘
+```
+
+Validaciones del CommandRelay (todas obligatorias):
+- Usuario en allowedUsers de esa plataforma
+- Texto ≤ 4000 chars
+- Sin patrones de payload injection (`<script>`, `.env`, `id_rsa`, etc.)
+- Rate limit: 10 msg/min por usuario
+- Dedup por hash en ventana de 30s
+
+Todo evento (aceptado, rechazado, procesado) queda en `.planning/inbox/audit.jsonl`.
+
+Para inyección directa a sesión tmux (solo Linux/macOS), ver `scripts/inbox-tmux-inject.js`.
+
+## Reglas de comportamiento
+
+- NUNCA almacenar tokens directamente en gateway-config.json — siempre usar `${VAR_ENV}`
+- SIEMPRE verificar que el token existe como variable de entorno antes de habilitar un adaptador
+- Si falta `node-telegram-bot-api` o `discord.js`, sugerir instalación con npm
+- Para `relay-on`, confirmar con el usuario antes de agregar un userId a `allowedUsers`: esto autoriza a ese usuario a enviarte comandos remotos
+- El relay NUNCA ejecuta comandos automáticamente: siempre requiere `/swl:inbox` con juicio humano. Explicar esto al usuario si activa el relay por primera vez