@saulwade/swl-ses 1.6.1 → 1.6.5

package/comandos/swl/salud.md

@@ -347,6 +347,38 @@ Documentación completa en `@docs/variables-entorno.md`.
 Este paso siempre se ejecuta (no es opt-in) — la calidad de CLAUDE.md
 es métrica continua del sistema.
 
+## Paso 5g — Smoke test de servidores MCP (opt-in)
+
+Si el proyecto declara servidores MCP en `.claude/settings.json` o en
+`~/.cursor/mcp.json` o `~/.claude/settings.json` (global), ejecutar un smoke
+test rápido para detectar configuraciones rotas antes de que fallen en uso
+interactivo:
+
+```bash
+python scripts/mcp-orchestrator.py status --json 2>/dev/null
+```
+
+El orchestrator levanta un proceso MCP fresh por cada server configurado y
+reporta:
+
+- `status: "OK"` — handshake completo + lista de tools devuelta correctamente
+- `status: "ERROR"` — fallo de handshake, autenticación o spawn
+
+Casos detectables que `/swl:salud` debe reportar:
+
+| Síntoma | Causa probable | Acción sugerida |
+|---|---|---|
+| `40101 Authorization required` | apiKey desincronizada entre cliente y plugin | Verificar `HKCU\Environment` (Windows) o variable de entorno del shell coincide con apiKey del plugin |
+| `Server failed to start` | Binario no encontrado en `command` | Verificar path absoluto del binario |
+| `Connection refused` | Plugin/servicio destino no corriendo | Iniciar plugin (ej. Obsidian con Local REST API activo) |
+| `env=None passed` | Config tiene `"env": {}` literal — rompe herencia | Omitir clave `env` por completo en JSON (no dejar vacía) |
+
+Si no hay servers configurados, este paso se omite silenciosamente.
+
+Este smoke test detecta drift de apiKeys ANTES de que el usuario interactivo
+encuentre 40101 en una invocación crítica. Recomendado ejecutar como parte del
+flujo `/swl:salud` periódico mensual.
+
 ## Paso 5e — Verificación de drift de skills (skills-lock)
 
 Si existe `manifiestos/skills-lock.json`, comparar el hash actual de cada

package/comandos/swl/verificar.md

@@ -21,6 +21,7 @@ Eres el coordinador de verificación SWL. Tu trabajo es asegurar la calidad del
 | `--until-converge` | Itera el ciclo verificar → corregir → re-verificar hasta convergencia (0 hallazgos CRÍTICO + ALTO + MAYOR en una pasada nueva) o hasta alcanzar `--max-iter`. Compatible con `--ultra` y `--solo-codigo`/`--solo-seguridad`. Ver sección "Modo `--until-converge`". |
 | `--max-iter=N` | Límite de iteraciones para `--until-converge`. Default: `5`. Rango válido: 1-10. |
 | `--no-prompt` | Suprime la confirmación interactiva entre pasadas (para CI). Solo aplica con `--until-converge`. |
+| `--ci-aware` | Antes de declarar convergencia natural en `--until-converge`, espera el estado terminal del CI sobre el HEAD pushed. Convergencia confirmada solo si CI verde + revisores APROBADO. CI rojo reabre el loop con los hallazgos del workflow como pasada N+1. Útil cuando el alcance modifica migraciones, seeds o tests E2E que el CI valida pero los revisores locales no. Ver sección 4.6.7. |
 
 ### Cuándo usar `--ultra`
 
@@ -286,9 +287,18 @@ El loop se detiene cuando se cumple **cualquiera** de estas señales (la primera
 | **A — éxito** | La pasada N produce 0 hallazgos nuevos de severidad `CRÍTICO`, `ALTO` o `MAYOR` | Convergencia natural — la fase está limpia |
 | **B — adversarial** | La pasada N+1 introduce ≥5 hallazgos NUEVOS sobre el código corregido en la pasada N | Las correcciones están introduciendo regresión; escalar al usuario |
 | **C — máximo** | Se alcanza `--max-iter=N` (default 5) sin converger | No-convergente; reportar al usuario |
+| **D — CI verde** (solo con `--ci-aware`) | Tras Señal A, el CI sobre el HEAD pushed termina en estado `success` para todos los workflows aplicables al SHA | Convergencia confirmada cross-stack (revisores + tests locales + CI con migraciones/seeds/E2E) |
 
 Los hallazgos `MEDIO`, `BAJO` y `SUGERENCIA` no rompen convergencia — se acumulan como deuda técnica documentada.
 
+**Importante sobre la Señal D**: sin `--ci-aware`, la convergencia natural se evalúa SOLO contra revisores + suite local. Esto NO detecta bugs que solo emergen en CI:
+- Migraciones aplicadas a BD limpia (CI fresh) vs BD productiva (donde seeds ya corrieron).
+- Seeds dependientes que fallan en cadena por orden migración↔seed invertido.
+- Tests E2E que requieren datos demo.
+- Partial unique indexes con `WHERE` que no son predicado puro (rompen en CI fresh).
+
+Origen del flag: SIGAF 2026-05-15 declaró convergencia natural en Pasada 3 (commit `4d2fb23`) basado en revisores APROBADO + 2161 pytest passed. 3 commits posteriores el CI Playwright reveló 3 tests E2E fallando por bug introducido en la propia Pasada 2 (migración 0061 con índice `WHERE` que rompía seeds en BD limpia). El loop cerró sin validar la integración E2E.
+
 ### 4.6.2 — Control de pausa entre iteraciones
 
 Antes de invocar al implementador para aplicar correcciones de la pasada N, el comando muestra un resumen y permite al usuario decidir:
@@ -381,9 +391,63 @@ El VERIFICACION.md reportado al usuario al final del loop incluye una sección a
 - Estado persistido: `.planning/fases/0N-converge-run-[timestamp].json`
 ```
 
-### 4.6.7 — Backward compatibility
+### 4.6.7 — Protocolo `--ci-aware` (Señal D)
+
+Cuando `--ci-aware` está activo, el bucle de convergencia se extiende con un gate adicional ANTES de declarar Señal A como cierre definitivo:
+
+**Precondición**: el último commit de la pasada N debe estar pusheado a la rama remota. Si no:
+
+```
+Pasada N converge natural pero --ci-aware requiere CI sobre HEAD pushed.
+
+HEAD local: abc1234 (no pusheado)
+[p] push automático + monitor CI
+[c] continuar sin --ci-aware (convergencia solo local)
+[q] abortar — pushear manualmente y re-invocar
+```
+
+Con `--no-prompt`: default es `p` (push automático).
+
+**Algoritmo de espera**:
+
+1. Tras Señal A, obtener SHA actual de `HEAD` y ejecutar `git ls-remote origin <rama>` para confirmar que está sincronizado.
+2. Listar workflows aplicables al SHA con:
+   ```bash
+   gh run list --branch <rama> --limit 10 \
+     --json status,conclusion,name,headSha \
+     --jq '.[] | select(.headSha == "<SHA>")'
+   ```
+3. Esperar usando la regla global `monitor-ci.md` (patrón Monitor con `gh --jq`, NO `| jq`).
+4. Clasificar resultado:
+   - **Todos `completed`+`success`** → Señal D confirmada, convergencia válida.
+   - **Algún workflow en `failure` o `cancelled`** → reabrir loop. Los hallazgos se extraen del log con `gh run view <run-id> --log-failed` y se procesan como pasada N+1.
+   - **Algún workflow `skipped` legítimo** (no se disparó por `paths:` filter) → NO suma al gate; convergencia válida si los aplicables están `success`.
+   - **Workflows aún en `in_progress` después del timeout configurado en monitor-ci** → escalar al usuario, no cerrar convergencia.
+
+**Workflows aplicables vs no aplicables**:
+
+`gh run list` puede listar workflows que NO se dispararon en el SHA actual por filtros `paths:` en el `on:` del workflow (ej. cambio solo en frontend no dispara Backend CI). Esos son **legítimamente ausentes**, no fallos.
+
+El gate solo evalúa workflows que **sí se dispararon en el SHA**. La verificación es:
+
+```bash
+gh run list --branch <rama> --limit 10 --json headSha,name,status,conclusion \
+  --jq '[.[] | select(.headSha | startswith("<sha-corto>"))] | all(.[]; .status == "completed" and .conclusion == "success")'
+```
 
-Sin `--until-converge`, el comportamiento del comando es idéntico al actual: una sola pasada, ofrece correcciones tras el veredicto, sale. El flag es 100% aditivo.
+Output `true` → Señal D. `false` con detalle → reabrir loop.
+
+**Anti-patrones explícitos**:
+
+- **Tratar timeout del monitor como "verde por default"**: el timeout significa "estado desconocido", NO `success`. Re-armar monitor o escalar al usuario.
+- **Sumar skipped legítimo como pass sin matizar**: si el workflow X no se disparó porque el commit solo tocó docs, está bien, pero el reporte final debe enumerarlo: "Frontend CI: skipped por filtro paths (commit toca solo backend/)".
+- **Asumir verde porque `git push` retornó exit 0**: push exitoso ≠ CI verde. push solo confirma que GitHub aceptó el push.
+
+Origen: regla global `monitor-ci.md` cubre este protocolo en detalle. Esta sección lo activa específicamente para `/swl:verificar`.
+
+### 4.6.8 — Backward compatibility
+
+Sin `--until-converge`, el comportamiento del comando es idéntico al actual: una sola pasada, ofrece correcciones tras el veredicto, sale. Los flags `--until-converge` y `--ci-aware` son 100% aditivos.
 
 ## Paso 5 — Verificación de criterios de aceptación
 
@@ -401,6 +465,56 @@ Ejemplo de tabla de verificación:
 | El usuario puede crear una cuenta | Test e2e / manual | PASA / FALLA / PENDIENTE |
 ```
 
+### Smoke test manual obligatorio para módulos frontend grandes
+
+Origen: SIGAF sesión 2026-05-21 (mejora D2). Cuando el alcance de la
+verificación toca un **componente frontend > 2,000 LOC** (típicamente módulos
+como `/catalogos`, `/contratos`, `/expedientes` que crecen orgánicamente), la
+verificación automática NO es suficiente. Los tests unitarios pueden pasar y
+el linter quedar limpio mientras el componente está **roto en el render
+real** (estado inicial mal calculado, evento que no propaga, route guard que
+redirige en loop, error de hidratación SSR que solo aparece en producción).
+
+Reglas duras para esta sub-categoría:
+
+1. **Detección automática del trigger**: si el revisor de código reporta
+   ≥1 archivo en `frontend/` con LOC > 2000, OR la suma de LOC de archivos
+   modificados en el último commit en `frontend/` excede 1500, activar este
+   sub-paso.
+
+2. **Smoke test manual obligatorio**: el VERIFICACION.md DEBE incluir un
+   bloque `## Smoke test manual (módulo frontend grande)` con los siguientes
+   checks que el usuario humano marca PASA/FALLA antes del merge:
+
+   ```markdown
+   ## Smoke test manual — frontend/<modulo> (X LOC)
+
+   - [ ] Arranca el dev server sin errores en consola
+   - [ ] Renderiza la pantalla principal del módulo sin pantalla blanca
+   - [ ] Navegación a cada sub-ruta funciona (listar nombres)
+   - [ ] Acciones CRUD principales completan flujo end-to-end
+   - [ ] No hay warnings de hidratación en consola (SSR si aplica)
+   - [ ] Layout responsive funciona en viewport mobile + desktop
+   - [ ] [Si aplica] Web vitals sin regresión vs commit anterior
+   ```
+
+3. **NO marcar verificación como APROBADA** hasta que el bloque esté completo
+   o el usuario explícitamente exente checks específicos con justificación.
+
+4. **El comando NO ejecuta el smoke automáticamente** (requiere browser
+   humano); su responsabilidad es **incluir el bloque en VERIFICACION.md** y
+   marcar la decisión de verificación como `APROBADO_CON_OBSERVACIONES`
+   hasta que el bloque se cierre.
+
+**Cuándo NO aplicar este sub-paso**:
+
+- Módulos backend puros (cobertura suficiente con tests de integración).
+- Cambios cosméticos a componentes frontend grandes (typo en texto, ajuste
+  de color de un botón) — la heurística LOC sigue disparándose pero el
+  usuario puede exentar con `[exento: cambio cosmético en X líneas]`.
+- Módulos con cobertura E2E > 70% probada (webapp-testing, Playwright,
+  Cypress) — el smoke automático cubre la necesidad.
+
 ## Paso 6 — Consolidación y generación del VERIFICACION.md
 
 Consolida todos los hallazgos en `.planning/fases/0N-VERIFICACION.md`:

package/habilidades/agent-browser/SKILL.md

@@ -8,10 +8,15 @@ description: >
   cuando WebFetch devuelve contenido incompleto. También alimenta directamente
   el wiki de proyecto (raw/) con fuentes verificadas.
 user-invocable: false
-version: "1.0.0"
-herramientasPermitidas: [Read, Bash, WebFetch]
-evolved: false
-fuente: "Vercel Labs agent-browser — 26K+ GitHub stars (2026-04)"
+version: "1.2.0"
+herramientasPermitidas: [Read, Bash, WebFetch, Skill]
+skillsInvocables: [browser-interaction-patterns, browser-research-domains]
+evolved: true
+evolved-from: "1.6.3"
+evolved-at: "2026-05-18"
+evolved-by: "aprender"
+evolved-note: "Adoptar patrones CDP de browser-harness (MIT) — coordinate clicks, wait_for_network_idle, dialogs auto-detect; añadir skillsInvocables a 2 skills nuevos consolidados"
+fuente: "Vercel Labs agent-browser — 26K+ GitHub stars (2026-04); patrones CDP avanzados adaptados de browser-use/browser-harness (MIT, 2026)"
 evolvable: true  # default para skill estandar
 exclusiones:
   - "No cargar para scraping de páginas estáticas simples — usar WebFetch directamente, es más rápido y sin overhead."
@@ -216,3 +221,105 @@ puede consumir 50K tokens solo en overhead de scraping. Con agent-browser: ~9K t
 **Usar `agent-browser` en un loop con 10+ URLs causa que el proceso Chrome se quede sin memoria y falle silenciosamente**: el Chrome controlado no libera memoria entre páginas del mismo proceso. Causa: cada `open` reutiliza el mismo proceso Chrome sin reiniciarlo. Fix: para loops de investigación intensiva (>10 URLs), dividir en sub-lotes y reiniciar `agent-browser` entre grupos, o procesar en secuencia con pausa de 500ms entre páginas.
 
 **`agent-browser navigate` a una página de login redirecciona a la URL original sin error**: si el sitio detecta el browser headless y redirecciona al login, el agente no recibe señal de fallo — simplemente extrae el contenido del formulario de login en lugar de la página deseada. Causa: sites como LinkedIn, Cloudflare-protected pages bloquean headless browsers. Fix: verificar que el output extraído contiene el contenido esperado (>200 palabras reales), no un formulario. Usar `--headed` para hacer el login visible y manual cuando el sitio requiere autenticación humana.
+
+## Patrones avanzados de CDP (adoptados de browser-harness MIT)
+
+Cuatro patrones que mejoran robustez y reducen tokens, adaptados del runtime
+`browser-use/browser-harness`. Aplican aunque agent-browser sea otra
+implementación (npm CLI vs Python CDP) — son patrones agnósticos al runtime.
+
+### 1. Coordinate clicks > selector clicks
+
+Cuando la página tiene iframes cross-origin, shadow DOM, o componentes
+complejos, los selectors CSS son frágiles. La alternativa robusta es operar
+a nivel **compositor** de Chrome con eventos de mouse por coordenadas.
+
+```bash
+# MAL — selector frágil cuando hay iframe o shadow DOM
+agent-browser click "button.submit-btn"
+
+# BIEN — leer coordenadas del screenshot y click por XY
+agent-browser screenshot /tmp/page.png
+# (visual: el botón está en ~ x=420, y=380)
+agent-browser click-xy 420 380
+agent-browser screenshot /tmp/after.png  # verificar
+```
+
+El click coordinate atraviesa iframes cross-origin y shadow DOM sin trabajo
+extra porque sucede en el compositor antes de llegar al árbol DOM. Solo bajar
+a DOM-level cuando el elemento NO tiene geometría visible.
+
+### 2. `wait_for_network_idle` > `wait` fijo
+
+Esperar timeouts fijos (`wait 2000`) es ciego — desperdicia tiempo en páginas
+rápidas y falla en páginas lentas. El patrón correcto es esperar evento-driven
+hasta que NO haya requests pendientes por N ms.
+
+```bash
+# MAL — timeout ciego
+agent-browser open https://app-spa.com
+agent-browser wait 2000
+agent-browser get text "main"
+
+# BIEN — esperar idle de red (event-driven)
+agent-browser open https://app-spa.com
+agent-browser wait-network-idle --timeout 10000 --idle-ms 500
+agent-browser get text "main"
+```
+
+Si tu agent-browser CLI no expone este helper, fallback razonable: `wait` con
+verificación posterior (screenshot + assert que el contenido renderizó).
+
+### 3. Screenshots primero para verificación
+
+Tras CUALQUIER acción que modifica estado (click, navigate, form submit), la
+única señal confiable de éxito es re-capturar screenshot. El DOM puede
+mentir durante transiciones; `page_info()` puede tener race conditions.
+
+```bash
+# MAL — asumir que el click funcionó
+agent-browser click-xy 420 380
+agent-browser get text ".confirmation-msg"  # puede estar vacío
+
+# BIEN — screenshot intermedio verifica visualmente
+agent-browser click-xy 420 380
+agent-browser screenshot /tmp/after-click.png
+# Inspeccionar visualmente o cargar a vision LLM para verificar
+agent-browser get text ".confirmation-msg"
+```
+
+### 4. Auto-detección de dialogs antes de actuar
+
+Los dialogs nativos (`alert`, `confirm`, `prompt`, `beforeunload`) **congelan
+el thread de JS** del page. Cualquier acción siguiente cuelga hasta que el
+dialog se resuelva. Patrón seguro: verificar `page_info()` antes de cada
+acción tras navegación o form submit.
+
+```bash
+agent-browser open https://site.com/form
+agent-browser submit-form
+# Antes del siguiente click, verificar
+agent-browser page-info
+# Si retorna {"dialog": {"type": "beforeunload", "message": "..."}},
+# dismissar con accept o cancel antes de continuar
+agent-browser dismiss-dialog --accept
+```
+
+Si el CLI de agent-browser no expone helper de dialog, la opción CDP raw es
+`Page.handleJavaScriptDialog`. Inyectar stubs JS (`window.alert = ...`) es
+alternativa solo cuando NO hay `beforeunload` involucrado.
+
+## Cuándo cargar skills complementarios
+
+Cuando este skill base no resuelve el caso:
+
+- **`browser-interaction-patterns`** — escalas a un tropiezo específico:
+  iframes cross-origin, shadow DOM, dropdown que no responde, upload bloqueado,
+  cookies HttpOnly, network requests que no producen DOM change. 14 patrones
+  con código MAL/BIEN.
+- **`browser-research-domains`** — el research toca github, arxiv, hackernews,
+  stackoverflow, pubmed, openalex o sec edgar. Para esos dominios, **NUNCA
+  abras un browser** — todo está en API. Reduce tokens 20-50× y latencia 5-20×.
+
+Cargar con `Skill("browser-interaction-patterns")` o
+`Skill("browser-research-domains")` según necesidad.

package/habilidades/agent-deep-links/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: agent-deep-links
+description: >
+  Constructor y validador de deep links para abrir archivos, líneas, carpetas y
+  ajustes directamente en IDEs y editores desde notificaciones, mensajes del
+  gateway o output de agentes. Cubre VS Code (vscode://), VS Code Insiders,
+  Cursor (cursor://), JetBrains (jetbrains://), Codex Desktop (codex://) y
+  fallbacks para apps sin esquema oficial. Cargar cuando un agente o hook deba
+  emitir referencias a archivo:línea que el usuario pueda abrir con un clic
+  desde Telegram, desktop notifications, Discord, Slack o e-mail.
+version: 1.0.0
+nivelRiesgo: BAJO
+herramientasPermitidas: [Read]
+exclusiones:
+  - "No invocar para generar URLs HTTP/HTTPS de navegación web — esto es solo para deep links a apps de escritorio."
+  - "No invocar para integraciones con servicios externos (Linear, Notion, Jira); este skill solo cubre IDEs y editores locales del desarrollador."
+  - "No invocar para enlaces a sesiones de Claude Code en la nube — esos son URLs claude.ai/code/..., no deep links."
+---
+
+# /habilidades/agent-deep-links — Deep links a IDEs
+
+## Cuándo cargar
+
+- Antes de emitir una notificación que incluya referencias a archivos del proyecto
+  desde `notificador-swl`, `hooks/lib/gateway-notify.js`, `inbox-aviso.js`,
+  `notificacion-sesion-stop.js` o cualquier hook que mencione `archivo:línea`.
+- Al diseñar nuevos hooks o agentes que produzcan output con referencias a código
+  que el usuario pueda querer abrir directamente.
+- Antes de generar mensajes desde el `documentador-swl` cuyo destino sea un canal
+  externo (Telegram, Discord, e-mail) y el receptor probablemente esté en su
+  IDE.
+
+## Cuándo NO cargar
+
+- Cuando la notificación es solo texto plano sin referencias a archivos
+  (mensajes de status, métricas agregadas).
+- Cuando el receptor es un agente, no un humano (los agentes no abren IDEs).
+- Cuando estás generando URLs de navegación web (HTTP/HTTPS) — usa generación
+  estándar.
+- Cuando el proyecto no expone su path absoluto al gateway (los deep links de
+  IDE requieren absolute paths).
+
+## Helper programático
+
+La lógica del skill está implementada en `hooks/lib/deep-links.js`. El skill
+documenta **qué** generar; el helper genera **cómo**. Para uso desde código:
+
+```js
+const { construirDeepLink, soportaDeepLinks } = require('./lib/deep-links');
+
+const url = construirDeepLink({
+  ide:        'cursor',      // 'vscode' | 'vscode-insiders' | 'cursor' | 'codex' | 'jetbrains' | 'visualstudio'
+  rutaAbsoluta: '/abs/path/a/archivo.js',
+  linea:      42,
+  columna:    8,
+});
+// → 'cursor://file//abs/path/a/archivo.js:42:8'
+
+if (!url) {
+  // El IDE solicitado no soporta deep links — usar fallback en texto plano
+}
+```
+
+## Matriz de soporte por IDE
+
+| IDE / App | Esquema | Soporte | Patrón canónico | Notas |
+|---|---|---|---|---|
+| **VS Code** | `vscode://` | Total | `vscode://file/<absoluteFile>:<line>:<column>` | Requiere VS Code instalado en máquina del receptor. |
+| **VS Code Insiders** | `vscode-insiders://` | Total | `vscode-insiders://file/<absoluteFile>:<line>:<column>` | Esquema específico Insiders. |
+| **Cursor** | `cursor://` | Total | `cursor://file/<absoluteFile>:<line>:<column>` | Fork de VS Code; misma forma. |
+| **Codex Desktop** | `codex://` | Total | `codex://threads/<thread-uuid>`, `codex://settings` | Para hilos y settings; no archivos. |
+| **JetBrains (IntelliJ/PyCharm/WebStorm/...)** | `jetbrains://` | Total | `jetbrains://<ide-id>/navigate/reference?project=<name>&path=<relPath>` | Requiere nombre del proyecto. Ver fila JetBrains abajo. |
+| **JetBrains Toolbox URL** | `idea://` (deprecado), `jetbrains://idea/...` | Parcial | `jetbrains://idea/navigate/reference?project=<name>&path=<rel>:<line>` | Cada IDE tiene su `<ide-id>`: idea, pycharm, webstorm, goland, rubymine, etc. |
+| **Visual Studio (Windows)** | (no estándar) | Sin esquema oficial | Usar CLI fallback: `devenv /edit <rutaAbsoluta>` | Solo Windows. |
+| **Xcode** | `xcode://` | Parcial | `xcode://...` | Esquema existe; rutas de archivo no bien documentadas. NO confiable. |
+| **Claude Desktop** | `claude://` | Desconocido | `claude://...` | Esquema registrado, rutas no documentadas. |
+| **Codex CLI** (terminal) | n/a | No aplica | n/a | Es CLI; no abre archivos en IDE. Usar fallback texto plano. |
+| **Cualquier app web** | n/a | No aplica | n/a | Si el destino es navegador, usar URL HTTP estándar. |
+
+## Reglas de construcción
+
+1. **Path absoluto obligatorio**. Deep links con rutas relativas no funcionan.
+   El helper rechaza `path.relative` y retorna `null`.
+2. **Encoding de paths con espacios**: aplicar `encodeURI` al path completo (no
+   solo al filename). El helper lo hace automáticamente.
+3. **Línea y columna son opcionales**: si no se especifican, el IDE abre al
+   inicio del archivo. Línea 1, columna 1 es válido pero redundante.
+4. **JetBrains requiere `proyecto`**: sin el nombre del proyecto, el deep link
+   no resuelve. Si no se conoce, usar `vscode://` como fallback (la mayoría de
+   los desarrolladores tienen VS Code instalado).
+5. **NUNCA inventar esquemas**: si la matriz dice "No aplica" o "Desconocido",
+   el helper retorna `null` y el caller debe usar texto plano.
+
+## Formato según receptor
+
+| Receptor | Forma del enlace |
+|---|---|
+| **Telegram** (Markdown V2) | `[abrir en IDE](cursor://file//abs/path:42:8)` |
+| **Discord** | `[abrir en IDE](cursor://file//abs/path:42:8)` |
+| **Slack** | `<cursor://file//abs/path:42:8\|abrir en Cursor>` (pipe-separado) |
+| **Desktop notification** (Linux/macOS) | URL plana sin label; el notificador maneja el clic |
+| **E-mail HTML** | `<a href="cursor://file//abs/path:42:8">abrir en Cursor</a>` |
+| **Texto plano / fallback** | `archivo.js:42 (abrir manualmente)` |
+
+## Gotchas observables
+
+- **El receptor debe tener el IDE instalado**: un enlace `cursor://` no funciona
+  si el receptor no tiene Cursor instalado. NO hay forma de detectarlo desde
+  el emisor; documentar al usuario que el deep link es opt-in.
+- **Slack tiene su propia sintaxis** `<url|label>`, no Markdown estándar. Mezclar
+  los formatos rompe el clic.
+- **Windows usa backslashes**: el path absoluto en Windows es
+  `C:\Users\...\archivo.js`. El esquema `vscode://file/C:\\Users\\...` requiere
+  doble-backslash en algunos casos; el helper normaliza con `path.resolve` +
+  `encodeURI` para producir `vscode://file/C:/Users/...` (slashes forward) que
+  VS Code/Cursor sí aceptan correctamente.
+- **JetBrains URL Handler debe estar habilitado**: en JetBrains está bajo
+  Settings → Tools → Web Browsers and Preview → "Use JetBrains as a
+  redirect..." NO está activado por defecto en todas las distribuciones.
+
+## Integración con SWL
+
+Hoy se integra en `hooks/lib/gateway-notify.js` (opt-in): cuando un caller pasa
+`payload.fileRef = { archivo, linea, columna }` Y existe `payload.idePreferido`,
+el helper enriquece el mensaje con el deep link en el formato del adaptador
+destino (Telegram / Discord / etc.).
+
+Extensiones futuras (no implementadas hoy):
+
+- `notificador-swl` (Telegram nativo): pasar `idePreferido` desde
+  `instintos/perfil-usuario.yaml § ide_preferido`.
+- `documentador-swl`: enlaces a archivos citados en docs generados.
+- `revisor-codigo-swl`: enlaces a archivo:línea en reportes de hallazgos.
+
+## Origen
+
+Adaptado del skill `agent-deep-links` de
+`temp/awesome-codex-skills-master/agent-deep-links/` (ComposioHQ, MIT) con:
+
+- Frontmatter al estándar SWL (es-MX, `nivelRiesgo`, `exclusiones`,
+  `herramientasPermitidas`).
+- Matriz extendida con JetBrains (no estaba) y Visual Studio fallback.
+- Sección "Formato según receptor" agregada para Telegram/Discord además del
+  Slack original.
+- Helper Node.js (`hooks/lib/deep-links.js`) que el repo origen no tenía.
+- Sección "Integración con SWL" agregada.
+
+Documentado en ADR-0029 (integración parcial awesome-codex-skills, Opción B).