@saulwade/swl-ses 1.6.3 → 1.6.5

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).

package/habilidades/backend-async-postgres-testing/SKILL.md

@@ -0,0 +1,215 @@
+---
+name: backend-async-postgres-testing
+description: >
+  Testing de código backend Python que usa asyncpg con context managers
+  asíncronos (`async with conn.transaction()`). Cubre el gotcha crítico de
+  AsyncMock que NO genera __aenter__/__aexit__ automáticamente, fixtures
+  reusables para mock_conn, testing de race conditions con SELECT FOR UPDATE,
+  y patrón de testing para servicios que envuelven INSERTs/UPDATEs en
+  transactions. Cargar cuando se escriban tests de services que usan
+  `async with conn.transaction():`, cuando un test "deba pasar" pero falla
+  con `TypeError: object MagicMock is not async iterable`, o cuando se
+  agregue transaction wrapping a un service que tenía tests previos rotos.
+version: "1.0.0"
+herramientasPermitidas: [Read, Grep]
+exclusiones:
+  - "No cargar para testing de SQLAlchemy async (AsyncSession) — esos usan `async with session.begin()` con un patrón distinto; cargar `fastapi-experto` que cubre el patrón con sessionmaker."
+  - "No cargar para testing de endpoints HTTP — el cliente httpx no requiere mock de transaction; cargar `testing-python` o `fastapi-experto`."
+  - "No cargar para testing de capa externa (S3, HTTP client) — esos requieren mock distinto (respx, moto); este skill es específico para BD asyncpg."
+  - "No cargar para testing E2E con Postgres real — si la suite levanta BD con testcontainers o docker-compose, NO se mockea transaction; cargar `testing-python`."
+evolvable: true
+---
+
+# Backend Async Postgres Testing
+
+Patrones de mock para código que usa `async with conn.transaction()` de asyncpg.
+
+## Cuándo NO cargar
+
+- El stack es SQLAlchemy async (`AsyncSession`), no asyncpg raw — cargar `fastapi-experto`.
+- Los tests son E2E con BD real (testcontainers, docker-compose con Postgres) — NO se mockea, cargar `testing-python`.
+- El código no envuelve queries en `async with conn.transaction():` — los mocks simples de `AsyncMock` bastan.
+- Tests de capa externa (S3, HTTP) — esos usan respx/moto, no este patrón.
+
+## El gotcha: AsyncMock NO genera context managers async automáticamente
+
+SIGM L-157 (2026-05-20). Tras introducir `async with conn.transaction():` en `service.py` para envolver SELECT-then-INSERT y prevenir race conditions, 3 tests existentes rompieron:
+
+```
+TypeError: 'AsyncMock' object does not support the asynchronous context manager protocol
+```
+
+El fixture original era:
+
+```python
+# MAL — AsyncMock NO implementa __aenter__/__aexit__
+@pytest.fixture
+def _mock_conn():
+    conn = AsyncMock()
+    conn.fetchrow = AsyncMock(return_value={"id": 1})
+    conn.execute = AsyncMock(return_value="UPDATE 1")
+    return conn
+```
+
+Al ejecutar:
+
+```python
+async with conn.transaction():   # ← falla aquí
+    await conn.execute(...)
+```
+
+`AsyncMock()` retorna un MagicMock cuando se llama, pero ese MagicMock NO es un context manager async — falta `__aenter__` y `__aexit__`.
+
+## Patrón correcto: configurar context manager explícitamente
+
+```python
+from unittest.mock import AsyncMock, MagicMock
+
+@pytest.fixture
+def _mock_conn():
+    """Mock de asyncpg.Connection con transaction() configurado."""
+    conn = AsyncMock()
+
+    # Configurar transaction() para que retorne un context manager async
+    transaction_cm = AsyncMock()
+    transaction_cm.__aenter__ = AsyncMock(return_value=transaction_cm)
+    transaction_cm.__aexit__ = AsyncMock(return_value=None)
+    conn.transaction = MagicMock(return_value=transaction_cm)
+    #     ↑ MagicMock — porque transaction() es sync (retorna el CM), no async
+
+    # Métodos comunes pre-configurados
+    conn.fetchrow = AsyncMock(return_value=None)
+    conn.fetch = AsyncMock(return_value=[])
+    conn.execute = AsyncMock(return_value="UPDATE 0")
+    conn.executemany = AsyncMock(return_value=None)
+
+    return conn
+```
+
+### Por qué `transaction` es `MagicMock` y no `AsyncMock`
+
+`conn.transaction()` es una llamada sync que retorna un objeto context manager async. La firma real de asyncpg:
+
+```python
+def transaction(self, *, isolation: str = None, ...) -> Transaction:
+    """Retorna un objeto Transaction (sync return)."""
+```
+
+Si pones `conn.transaction = AsyncMock(...)`, entonces `conn.transaction(...)` retorna un coroutine — y `async with <coroutine>` falla con `TypeError: 'coroutine' object does not support the asynchronous context manager protocol`.
+
+Regla:
+- `transaction` (el método): `MagicMock` (sync return).
+- El objeto retornado por `transaction()`: `AsyncMock` con `__aenter__` y `__aexit__` configurados.
+
+### Helper reutilizable
+
+Para evitar repetir el setup en cada test, extraer a helper:
+
+```python
+# tests/_helpers/asyncpg_mocks.py
+from unittest.mock import AsyncMock, MagicMock
+
+def crear_mock_conn(*, fetchrow=None, fetch=None, execute_tag="UPDATE 0") -> AsyncMock:
+    """Mock de asyncpg.Connection con transaction() configurado."""
+    conn = AsyncMock()
+
+    transaction_cm = AsyncMock()
+    transaction_cm.__aenter__ = AsyncMock(return_value=transaction_cm)
+    transaction_cm.__aexit__ = AsyncMock(return_value=None)
+    conn.transaction = MagicMock(return_value=transaction_cm)
+
+    conn.fetchrow = AsyncMock(return_value=fetchrow)
+    conn.fetch = AsyncMock(return_value=fetch or [])
+    conn.execute = AsyncMock(return_value=execute_tag)
+    return conn
+```
+
+Uso:
+
+```python
+async def test_crear_valuacion_vigente(monkeypatch):
+    conn = crear_mock_conn(
+        fetchrow={"id": uuid.uuid4(), "es_vigente": False},
+        execute_tag="UPDATE 1",
+    )
+    service = ValuacionService(conn=conn)
+    await service.crear_valuacion_vigente(predio_id, ejercicio, valor)
+
+    # Verificar que se entró a la transaction
+    conn.transaction.assert_called_once()
+    # Verificar que se actualizó la fila vigente previa
+    conn.execute.assert_any_call(
+        "UPDATE valuacion SET es_vigente=false WHERE predio_id=$1 AND ejercicio=$2",
+        predio_id, ejercicio,
+    )
+```
+
+## Testing de race conditions con SELECT FOR UPDATE
+
+Cuando el código real usa `SELECT FOR UPDATE`, el mock debe simular el lock acquired retornando el valor "lockeado" en el primer `fetchrow`:
+
+```python
+async def test_crear_valuacion_concurrente_serializada():
+    """Simula 2 peticiones concurrentes: la 2da debe esperar al lock."""
+    conn = crear_mock_conn()
+
+    # 1ra petición ve la fila vacía
+    conn.fetchrow.side_effect = [
+        None,                                  # 1er SELECT FOR UPDATE: no hay vigente
+        {"id": uuid.uuid4(), "version": 1},    # 2do SELECT FOR UPDATE: ya hay vigente (la 1ra creó)
+    ]
+    conn.execute.return_value = "INSERT 0 1"
+
+    service = ValuacionService(conn=conn)
+    await service.crear_valuacion_vigente(predio_id=p, ejercicio=2026, valor=100)
+    await service.crear_valuacion_vigente(predio_id=p, ejercicio=2026, valor=200)
+
+    # Solo el primer INSERT debe haberse ejecutado
+    inserts = [call for call in conn.execute.call_args_list if "INSERT" in str(call)]
+    assert len(inserts) == 1
+```
+
+Esta simulación NO valida que el lock realmente serialize en BD — eso requiere test E2E con Postgres real. Pero SÍ valida que el código de aplicación maneja correctamente el caso "la fila ya existe" cuando emerge del lock.
+
+## Verificar la entrada a transaction
+
+Cuando es importante verificar que el código envuelve correctamente las queries en `async with conn.transaction():`, agregar aserción:
+
+```python
+async def test_actualizar_estatus_dentro_de_transaction():
+    conn = crear_mock_conn(fetchrow={"id": 1, "estatus": "PENDIENTE"})
+    service = TramiteService(conn=conn)
+    await service.aprobar_tramite(tramite_id=1)
+
+    # Verificar que SELECT y UPDATE están dentro de la misma transaction
+    conn.transaction.assert_called_once()
+    # __aenter__ debe haberse llamado antes del primer fetchrow
+    transaction_cm = conn.transaction.return_value
+    assert transaction_cm.__aenter__.called
+    assert transaction_cm.__aexit__.called
+```
+
+Si el código olvida envolver en transaction, `conn.transaction.assert_called_once()` falla — el test detecta el bug.
+
+## Anti-patrones
+
+- **Usar `AsyncMock` para `conn.transaction`** — retorna coroutine que no es context manager. Fix: `MagicMock(return_value=AsyncMock_con_aenter_aexit)`.
+- **Compartir `_mock_conn` entre tests sin reset de side_effect** — un test configura `fetchrow.side_effect = [...]` y el siguiente recibe el iterador agotado. Fix: `@pytest.fixture` recrea conn por test (scope `function`, default).
+- **Mockear `fetchrow.return_value = dict` cuando el código real esperaba un `Record`** — los `Record` de asyncpg permiten acceso por índice (`row[0]`) Y por nombre (`row["id"]`). El dict solo permite por nombre. Si el código real usa `row[0]`, el mock con dict falla con `KeyError: 0`. Fix: si el código usa acceso posicional, mockear con un objeto que soporte ambos accesos, o cambiar el código a acceso por nombre.
+- **Olvidar mockear `__aexit__` con `return_value=None`** — si retorna otra cosa, la transaction parece haber fallado y el código puede invocar lógica de rollback que no esperabas. Fix: `__aexit__ = AsyncMock(return_value=None)` explícito.
+
+## Gotchas / Errores comunes no obvios
+
+- **`conn.transaction()` con `isolation=` o `readonly=` kwargs no se valida en mock**: el mock acepta cualquier kwarg. Si el código real espera `isolation="serializable"` y se cambia a `isolation="read committed"`, el test pasa pero el comportamiento cambia. Fix: aserción explícita `conn.transaction.assert_called_with(isolation="serializable")`.
+- **`AsyncMock(side_effect=Exception)` dentro de transaction provoca llamada a `__aexit__` con exc_type/exc/tb**: para simular rollback, `__aexit__` recibe la excepción como args. Si tu mock tiene `__aexit__ = AsyncMock(return_value=None)`, la excepción se re-eleva. Si retorna `True`, la excepción se suprime (comportamiento normal de context manager). Fix: para tests de rollback, dejar `return_value=None` (deja que la excepción propague) y verificar con `pytest.raises(...)`.
+- **`fetchrow.side_effect = [row, row]` se agota tras 2 llamadas**: en la 3ra llamada lanza `StopIteration`. Si el código real hace 3 fetchrows en distintas ramas, el test falla con error críptico. Fix: usar lista con suficientes elementos o `side_effect` callable que retorna según args (`lambda *args: row if args[0] == "SELECT..." else None`).
+- **`MagicMock` (no `AsyncMock`) en `conn.transaction` permite `assert_called_with(*args)` natural** — `AsyncMock` también lo soporta, pero produce warnings de "coroutine never awaited" si el mock se invoca incorrectamente. La distinción importa para diagnóstico, no para corrección.
+- **`pytest-asyncio` con `mode="auto"` puede no marcar el test como async si no detecta `async def`**: si el fixture es async pero el test es sync, el fixture nunca se await. Fix: explícito `@pytest.mark.asyncio` en el test, o usar `asyncio_mode = "auto"` en `pyproject.toml` y verificar que el test es `async def`.
+
+## Referencias
+
+| Tema | Recurso |
+|------|---------|
+| Patrón general de async testing en Python | `Skill("testing-python")` |
+| Endpoints FastAPI testing con httpx | `Skill("fastapi-experto")` § Testing |
+| Race conditions en PostgreSQL (lado código) | `Skill("postgresql-experto")` § SELECT-then-INSERT |