@saulwade/swl-ses 1.0.0

package/habilidades/testing-python/recursos/ejemplos-completos.md

@@ -0,0 +1,167 @@
+# Testing Python — Ejemplos completos y referencia
+
+## Mocking con unittest.mock y pytest-mock
+
+```python
+from unittest.mock import MagicMock, AsyncMock, patch
+import pytest
+
+# Mock de una función de módulo
+def test_crear_factura_llama_servicio_timbre(factura_service, mock_timbre):
+    with patch("app.services.factura_service.timbre_service") as mock_timbre:
+        mock_timbre.timbrar = MagicMock(return_value={"uuid": "abc-123"})
+
+        factura = factura_service.crear(datos_validos)
+
+        mock_timbre.timbrar.assert_called_once_with(factura)
+        assert factura.uuid_timbre == "abc-123"
+
+# Con pytest-mock (más limpio)
+def test_notificacion_enviada(mocker, factura_service):
+    mock_email = mocker.patch("app.services.email_service.enviar")
+
+    factura_service.emitir(factura_id="fac-123")
+
+    mock_email.assert_called_once()
+    llamada = mock_email.call_args
+    assert llamada.kwargs["destinatario"] == "cliente@empresa.com"
+
+# Mock de async
+async def test_obtener_usuario_llama_api_externa(mocker):
+    mock_get = mocker.patch("httpx.AsyncClient.get", new_callable=AsyncMock)
+    mock_get.return_value.json.return_value = {"id": "u1", "nombre": "Ana"}
+    mock_get.return_value.status_code = 200
+
+    usuario = await servicio.obtener_usuario("u1")
+
+    assert usuario.nombre == "Ana"
+    mock_get.assert_awaited_once()
+```
+
+---
+
+## Testing async con pytest-asyncio
+
+```python
+# pyproject.toml
+# [tool.pytest.ini_options]
+# asyncio_mode = "auto"  # Marcar todos los tests async automáticamente
+
+import pytest
+from httpx import AsyncClient, ASGITransport
+
+@pytest.mark.asyncio
+async def test_crear_factura_endpoint(async_client: AsyncClient):
+    respuesta = await async_client.post(
+        "/api/v1/facturas/",
+        json={
+            "folio": "F-001",
+            "fecha": "2026-03-25",
+            "subtotal": "1000.00",
+            "cliente_id": "cliente-123",
+        },
+        headers={"Authorization": "Bearer token-test"},
+    )
+    assert respuesta.status_code == 201
+    data = respuesta.json()
+    assert data["estatus"] == "borrador"
+    assert "id" in data
+
+@pytest.fixture
+async def async_client(app, async_db):
+    async with AsyncClient(
+        transport=ASGITransport(app=app),
+        base_url="http://test",
+    ) as client:
+        yield client
+```
+
+---
+
+## Factories con factory_boy
+
+```python
+# tests/factories.py
+import factory
+from decimal import Decimal
+from datetime import date
+from app.models import Factura, Cliente, Item
+
+class ClienteFactory(factory.Factory):
+    class Meta:
+        model = Cliente
+
+    id = factory.Sequence(lambda n: f"cliente-{n:05d}")
+    nombre = factory.Faker("company", locale="es_MX")
+    rfc = factory.LazyFunction(lambda: f"RFC{factory.Faker('numerify', text='######')}")
+    activo = True
+
+class ItemFactory(factory.Factory):
+    class Meta:
+        model = Item
+
+    descripcion = factory.Faker("sentence", nb_words=4, locale="es_MX")
+    cantidad = factory.Faker("pyint", min_value=1, max_value=10)
+    precio_unitario = factory.Faker("pydecimal", min_value=10, max_value=1000,
+                                    right_digits=2)
+
+class FacturaFactory(factory.Factory):
+    class Meta:
+        model = Factura
+
+    id = factory.Sequence(lambda n: f"fac-{n:05d}")
+    folio = factory.Sequence(lambda n: f"F-{n:05d}")
+    fecha = factory.LazyFunction(date.today)
+    estatus = "borrador"
+    cliente = factory.SubFactory(ClienteFactory)
+    items = factory.List([factory.SubFactory(ItemFactory)])
+
+# Uso en tests
+def test_calcular_total():
+    items = [ItemFactory(cantidad=2, precio_unitario=Decimal("100.00"))]
+    factura = FacturaFactory(items=items)
+    assert factura.calcular_total() == Decimal("200.00")
+```
+
+---
+
+## Anti-patrones en tests
+
+```python
+# MAL: test que verifica demasiado
+def test_factura():
+    f = Factura(...)
+    assert f.folio == "F-001"
+    assert f.estatus == "borrador"
+    assert f.total == 1160
+    assert f.cliente.nombre == "Acme"
+    assert f.puede_cancelar() == True
+    # ... 10 asserts más
+
+# BIEN: un comportamiento por test
+def test_factura_nueva_tiene_estatus_borrador():
+    factura = FacturaFactory()
+    assert factura.estatus == "borrador"
+
+def test_factura_calcula_total_con_iva():
+    factura = FacturaFactory(subtotal=Decimal("1000.00"), tasa_iva=0.16)
+    assert factura.total == Decimal("1160.00")
+
+# MAL: lógica de negocio en los tests
+def test_calcular_descuento():
+    if monto > 1000:      # lógica duplicada del código de producción
+        esperado = monto * 0.1
+    else:
+        esperado = 0
+    assert calcular_descuento(monto) == esperado
+
+# BIEN: valores concretos y explícitos
+@pytest.mark.parametrize("monto,descuento_esperado", [
+    (500,  Decimal("0.00")),
+    (1000, Decimal("0.00")),
+    (1001, Decimal("100.10")),
+    (2000, Decimal("200.00")),
+])
+def test_calcular_descuento(monto, descuento_esperado):
+    assert calcular_descuento(monto) == descuento_esperado
+```

package/habilidades/threat-model-lite/SKILL.md

@@ -0,0 +1,246 @@
+---
+name: threat-model-lite
+description: Modelado de amenazas ligero basado en STRIDE simplificado. Identifica la superficie de ataque del sistema, los activos críticos, los flujos de datos sensibles y genera mitigaciones priorizadas. Diseñado para completarse en una sesión de trabajo, no en semanas.
+version: "1.0.0"
+herramientasPermitidas: [Read, Grep]
+evolvable: true  # default para skill estandar
+nist_csf: [ID.RA-01, ID.RA-03, ID.RA-04]
+nist_ai_rmf: [MAP-1.1, MAP-5.1, MAP-5.2]
+exclusiones:
+  - "No cargar para implementar las mitigaciones técnicas identificadas (RBAC, rate limiting, TLS) — threat model produce el diagnóstico; para implementación cargar el skill del stack correspondiente."
+  - "No cargar para auditoría de código buscando vulnerabilidades específicas (SQL injection, XSS en código) — para revisión de código de seguridad cargar `checklist-seguridad` o el skill de revisión del lenguaje."
+  - "No cargar para análisis de cumplimiento normativo (PCI-DSS, SOC 2, ISO 27001) — el threat model es una entrada para el compliance, no el análisis de cumplimiento completo."
+  - "No cargar para red-teaming o pruebas de penetración activas — threat model es análisis estático; para pentest activo usar herramientas especializadas con autorización explícita."
+---
+# Habilidad: Threat Model Lite
+
+## Cuándo NO cargar
+
+- La tarea es implementar las mitigaciones identificadas (RBAC, rate limiting, TLS): usar el skill del stack correspondiente para la implementación.
+- La tarea es revisión de código buscando vulnerabilidades: cargar `checklist-seguridad`.
+- La tarea es análisis de cumplimiento normativo (PCI-DSS, SOC 2): el threat model es una entrada, no el análisis completo.
+- La tarea es pentest activo o red-teaming: usar herramientas especializadas con autorización explícita.
+
+## Propósito
+
+Un threat model completo toma semanas. Esta versión toma entre 2 y 4 horas y
+cubre el 80% de los riesgos reales. El objetivo no es ser exhaustivo — es
+identificar las amenazas de mayor impacto antes de que lleguen a producción.
+
+## Cuándo activar
+
+- Al diseñar un nuevo sistema o módulo crítico
+- Antes del primer deploy a producción de una aplicación nueva
+- Cuando el sistema maneja datos PII, financieros o de salud
+- Cuando se añade una nueva integración con sistemas externos
+- Como parte de la revisión de seguridad trimestral
+
+---
+
+## Paso 1 — Definir el alcance en 15 minutos
+
+Responder estas 4 preguntas antes de proceder:
+
+1. **¿Qué estamos protegiendo?** (activos: datos, dinero, reputación, disponibilidad)
+2. **¿De quién lo protegemos?** (actores: usuarios maliciosos, atacantes externos,
+   empleados deshonestos, errores accidentales)
+3. **¿Cuál sería el peor escenario?** (impacto: pérdida de datos, fraude, downtime)
+4. **¿Cuál es el perímetro del análisis?** (módulo específico, sistema completo,
+   integración puntual)
+
+Si no puedes responder estas preguntas, detente y habla con el stakeholder antes
+de continuar.
+
+---
+
+## Paso 2 — Mapear la superficie de ataque
+
+### Diagrama de flujo de datos (DFD simplificado)
+
+Identificar y documentar:
+
+**Puntos de entrada** (donde datos externos entran al sistema):
+- [ ] Endpoints HTTP/REST públicos
+- [ ] Endpoints autenticados
+- [ ] Webhooks recibidos de sistemas externos
+- [ ] Archivos cargados por usuarios
+- [ ] Variables de entorno y configuración
+- [ ] Mensajes de colas (Kafka, RabbitMQ, SQS)
+- [ ] Interfaces de línea de comandos (CLI)
+
+**Flujos de datos sensibles** (donde los datos críticos viajan):
+- [ ] Datos de usuario en tránsito (login, sesión)
+- [ ] Datos financieros (pagos, montos, cuentas)
+- [ ] PII en requests/responses
+- [ ] Tokens y credenciales en headers
+- [ ] Datos en logs
+- [ ] Datos exportados (CSV, PDF, reportes)
+
+**Límites de confianza** (dónde cambia el nivel de confianza):
+- [ ] Internet → API Gateway / Load Balancer
+- [ ] API → Base de datos
+- [ ] Microservicio A → Microservicio B
+- [ ] Sistema interno → Sistema externo
+
+---
+
+## Paso 3 — STRIDE simplificado
+
+Para cada punto de entrada y flujo de datos, evaluar las 6 categorías STRIDE:
+
+### S — Spoofing (Suplantación de identidad)
+**Pregunta**: ¿Puede un atacante hacerse pasar por un usuario legítimo?
+- Autenticación débil o ausente en algún endpoint
+- Tokens sin expiración o sin firma válida
+- No verificación de origen en webhooks
+- Reset de contraseña sin validación de identidad
+
+### T — Tampering (Manipulación de datos)
+**Pregunta**: ¿Puede un atacante modificar datos en tránsito o en reposo?
+- Comunicación HTTP (no HTTPS) entre componentes internos
+- HMAC ausente en mensajes de colas
+- Validación insuficiente de inputs antes de persistir
+- Archivos subidos sin verificación de integridad
+
+### R — Repudiation (Repudio)
+**Pregunta**: ¿Puede un actor negar haber realizado una acción?
+- Acciones críticas sin audit log
+- Logs sin timestamp confiable o sin integridad garantizada
+- Sin registro de IP/agente en acciones de alto riesgo
+
+### I — Information Disclosure (Divulgación de información)
+**Pregunta**: ¿Puede un atacante acceder a información que no debería ver?
+- Stack traces expuestos en respuestas de error
+- Datos sensibles en logs
+- Respuestas de API que revelan más de lo necesario
+- Endpoints de debug accesibles en producción
+- IDOR: acceso a recursos de otros usuarios
+
+### D — Denial of Service (Denegación de servicio)
+**Pregunta**: ¿Puede un atacante degradar o eliminar el servicio?
+- Sin rate limiting en endpoints públicos
+- Queries sin límite de resultados (full table scan por input del usuario)
+- Archivos de tamaño ilimitado aceptados
+- Operaciones costosas sin throttling
+
+### E — Elevation of Privilege (Escalación de privilegios)
+**Pregunta**: ¿Puede un usuario normal obtener permisos de administrador?
+- RBAC incompleto o con brechas
+- Endpoints de admin sin verificación de rol
+- Parámetros de rol aceptados del cliente sin validación del servidor
+- Tokens JWT con claims manipulables
+
+---
+
+## Paso 4 — Identificar activos críticos
+
+Clasificar los activos del sistema por impacto si se comprometen:
+
+| Activo | Tipo | Impacto si comprometido | Nivel |
+|--------|------|------------------------|-------|
+| Contraseñas de usuarios | PII + Auth | Acceso no autorizado a cuentas | CRÍTICO |
+| Datos financieros | Financiero | Pérdida monetaria / fraude | CRÍTICO |
+| PII (nombre, email, RFC) | PII | Violación de privacidad / LFPDPPP | ALTO |
+| Tokens JWT | Auth | Suplantación de identidad | ALTO |
+| Logs de acceso | Operacional | Pérdida de auditoría | MEDIO |
+| Datos de configuración | Operacional | Exposición de infraestructura | MEDIO |
+
+---
+
+## Paso 5 — Generar mitigaciones priorizadas
+
+Usar la matriz de riesgo para priorizar:
+
+```
+Riesgo = Probabilidad × Impacto
+
+Probabilidad: 1 (baja) → 5 (casi seguro)
+Impacto: 1 (insignificante) → 5 (crítico)
+Prioridad: [1-5] Baja | [6-14] Media | [15-25] Alta
+```
+
+Para cada amenaza STRIDE encontrada, generar:
+
+```markdown
+### [ID-001] [Nombre de la amenaza]
+- **Categoría STRIDE**: [S/T/R/I/D/E]
+- **Activo afectado**: [nombre del activo]
+- **Flujo de datos**: [de dónde a dónde]
+- **Descripción del ataque**: [cómo un atacante lo exploraría]
+- **Probabilidad**: [1-5] | **Impacto**: [1-5] | **Riesgo**: [producto]
+- **Mitigación propuesta**: [solución técnica específica]
+- **Costo de mitigación**: [Bajo/Medio/Alto]
+- **Estado**: Pendiente / En progreso / Mitigado / Aceptado
+```
+
+---
+
+## Plantilla de salida: `THREAT-MODEL.md`
+
+```markdown
+# THREAT-MODEL.md — [Nombre del Sistema]
+**Fecha**: [fecha]  **Versión**: [N]  **Autor**: [agente/persona]
+
+## Alcance
+[Descripción del sistema y qué está dentro/fuera del análisis]
+
+## Activos críticos
+| Activo | Nivel | Propietario |
+|--------|-------|------------|
+|        |       |            |
+
+## Superficie de ataque
+### Puntos de entrada
+- [lista]
+
+### Flujos de datos sensibles
+- [lista]
+
+### Límites de confianza
+- [lista]
+
+## Amenazas identificadas
+[Para cada amenaza, la ficha del formato anterior]
+
+## Resumen de riesgos
+| ID | Amenaza | Riesgo | Estado |
+|----|---------|--------|--------|
+|    |         |        |        |
+
+## Plan de mitigación (priorizado)
+| Prioridad | ID | Acción | Responsable | Fecha límite |
+|-----------|---|--------|-------------|-------------|
+| 1 (ALTO)  |   |        |             |             |
+| 2 (MEDIO) |   |        |             |             |
+
+## Amenazas aceptadas (con justificación)
+| ID | Amenaza | Justificación | Quién aceptó |
+|----|---------|--------------|-------------|
+|    |         |              |             |
+
+## Próxima revisión
+**Fecha**: [fecha de revisión] o cuando ocurra: [evento trigger]
+```
+
+---
+
+## Triggers para actualizar el modelo
+
+El threat model debe revisarse cuando:
+- Se añade un nuevo punto de entrada al sistema
+- Se integra un servicio externo nuevo
+- Se cambia el mecanismo de autenticación
+- Los datos que maneja el sistema cambian de clasificación
+- Se detecta una vulnerabilidad en producción
+
+---
+
+## Gotchas / Errores comunes no obvios
+
+**El STRIDE simplificado de este skill omite sistemáticamente amenazas de "confused deputy" donde un servicio interno con privilegios elevados ejecuta acciones en nombre de un actor de menor privilegio sin verificar la identidad original**: en un microservicio de reportes que llama al microservicio de pagos usando credenciales de servicio (no del usuario), un atacante que compromete el microservicio de reportes puede consultar pagos de cualquier usuario. Causa: STRIDE evalúa cada componente aisladamente; las amenazas confused deputy emergen en la interacción entre dos límites de confianza. Fix: al mapear límites de confianza en el Paso 2, agregar explícitamente la pregunta: "¿Este servicio actúa en nombre de un actor? ¿Verifica que la acción solicitada está autorizada para ese actor específico?" Documentar la identidad que fluye entre servicios en el DFD.
+
+**Las mitigaciones de prioridad calculadas con `Probabilidad × Impacto` son inconsistentes entre revisores porque la escala 1-5 es subjetiva y dos ingenieros pueden asignar probabilidad 2 vs 4 a la misma amenaza según su experiencia personal**: un equipo que usa el threat model sin calibración previa genera matrices de riesgo donde "SQL injection en el endpoint de búsqueda" tiene riesgo 6 para un revisor (Prob=2, Imp=3) y riesgo 20 para otro (Prob=4, Imp=5). Causa: las escalas ordinales sin anclas concretas son inherentemente subjetivas. Fix: antes de la sesión, calibrar la escala con 2-3 amenazas históricas conocidas del sector: "CVE-XXXX-YYYY tuvo Probabilidad=4 porque fue explotado activamente en los 6 meses anteriores al parche". Las anclas históricas reducen la varianza entre revisores.
+
+**El THREAT-MODEL.md marcado como "Mitigado" para una amenaza de IDOR queda obsoleto en 3 meses cuando se agrega un nuevo endpoint de API que expone el mismo recurso sin la verificación de autorización implementada en los endpoints originales**: el threat model registra que "IDOR en `/api/v1/pedidos/{id}`" fue mitigado, pero el endpoint nuevo `/api/v2/orders/{id}` (agregado en sprint 14) no fue evaluado y tiene el mismo vector. Causa: el threat model es un documento puntual; los cambios incrementales al sistema no lo actualizan automáticamente. Fix: en el mapa de propagación de cambios del proyecto, agregar una regla: "nuevo endpoint en `api/` → verificar si el THREAT-MODEL.md cubre el nuevo recurso expuesto". Revisar las amenazas de tipo I (Information Disclosure) y E (Elevation of Privilege) del modelo cada vez que se añade un endpoint.
+
+**La categoría S (Spoofing) suele generar mitigaciones de "agregar autenticación" que quedan como ítems en el backlog indefinidamente porque no tienen criterio de aceptación técnico medible**: la mitigación "implementar autenticación JWT en el endpoint" sin especificar qué claims verificar, qué algoritmo usar, qué TTL del token, ni cómo manejar revocación es inaccionable. El ticket se cierra cuando se agrega "cualquier autenticación" aunque sea trivialmente bypasseable. Causa: las mitigaciones STRIDE son descripciones de objetivo, no especificaciones técnicas. Fix: para cada mitigación en el plan de acción, agregar los criterios de aceptación mínimos: "Verificar firma RS256, audience claim = 'api.mi-sistema.com', exp < now() + 1h, validar contra JWKS endpoint del IdP. Test: request sin token retorna 401, request con token expirado retorna 401, request con audience incorrecta retorna 401."

package/habilidades/tracing-processor/SKILL.md

@@ -0,0 +1,212 @@
+---
+name: tracing-processor
+description: Documenta el patrón TracingProcessor para el sistema de trazabilidad SWL. Cómo crear exportadores de trazas (Langfuse, Jaeger, consola) sin modificar el núcleo, usando la interfaz formal en scripts/lib/tracing-processor-interface.js. Cargar cuando se implementa un exportador de trazas nuevo, se integra observabilidad externa, o se usa MultiProcessor.
+version: "1.0.0"
+herramientasPermitidas: [Read, Write]
+exclusiones:
+  - "No cargar para leer trazas ya generadas en `.planning/traces/` — eso es lectura directa de JSONL con el Read tool o con `drift-detection`; este skill documenta cómo implementar nuevos exportadores, no cómo consumir trazas."
+  - "No cargar para agregar observabilidad a hooks que no son parte del pipeline de trazabilidad — los hooks que registran eventos en `nudges.jsonl`, `alertas-persistentes.json` o archivos de estado no son TracingProcessors; este skill es exclusivo para exportadores de spans del ciclo de vida de agentes."
+  - "No cargar para depurar por qué un agente falla — las trazas son observabilidad, no diagnóstico de bugs; para bugs usar `depurador-swl` o revisar los logs del hook directamente."
+  - "No cargar si el exportador objetivo ya está implementado en `hooks/lib/otlp-exporter.js` y solo necesita configuración vía variable de entorno — los exportadores existentes se activan con variables opt-in, no requieren código nuevo."
+evolvable: true
+evolvable_scope:
+  - content
+  - examples
+  - anti-patterns
+---
+# Habilidad: TracingProcessor — Exportadores de Trazas
+
+## Propósito del patrón
+
+El sistema SWL ya registra spans en `.planning/traces/YYYY-MM-DD.jsonl` vía
+`hooks/lib/otlp-exporter.js`. Sin la interfaz formal, agregar un segundo
+destino de exportación (Langfuse, Jaeger, consola) requeriría modificar ese
+archivo — violando el principio Open/Closed.
+
+**TracingProcessor** resuelve esto: define un contrato que cualquier exportador
+debe cumplir. El núcleo (`hooks/telemetria-agentes.js`) solo conoce la interfaz;
+los destinos concretos son plugins intercambiables.
+
+Beneficios:
+- Agregar destinos sin tocar código existente.
+- Combinar múltiples destinos con `MultiProcessor` (patrón Composite).
+- Testear exportadores de forma aislada.
+
+---
+
+## Contrato de la interfaz
+
+Archivo: `scripts/lib/tracing-processor-interface.js`
+
+| Método | Cuándo se invoca | Responsabilidad |
+|--------|-----------------|----------------|
+| `onTraceStart(traza)` | Al iniciar una traza de alto nivel | Registrar inicio, crear buffer si aplica |
+| `onTraceEnd(traza)` | Al finalizar una traza completa | Exportar la traza completa, liberar buffer |
+| `onSpanStart(span)` | Al iniciar un span individual | Registrar inicio del span |
+| `onSpanEnd(span)` | Al finalizar un span (datos completos disponibles) | Punto principal de exportación |
+| `shutdown()` | Al detener la aplicación | Vaciar buffers, cerrar archivos/conexiones |
+| `forceFlush()` | Antes de shutdown o cuando se necesita garantía | Forzar volcado de colas internas |
+
+Reglas del contrato:
+- Los métodos deben retornar rápidamente. Usar colas internas para I/O lento.
+- Los errores internos no deben propagarse al caller.
+- Todos los métodos son síncronos por contrato; las subclases usan colas async internamente.
+
+---
+
+## Cómo crear un exportador alterno
+
+### Paso 1 — Extender la clase abstracta
+
+```js
+'use strict';
+const { TracingProcessor } = require('../../scripts/lib/tracing-processor-interface');
+
+class MiExportador extends TracingProcessor {
+  constructor(opciones = {}) {
+    super();
+    this._buffer = [];
+    this._destino = opciones.destino || 'https://mi-backend.example.com/traces';
+  }
+
+  onTraceStart(traza) { /* opcional: registrar inicio */ }
+  onTraceEnd(traza)   { this._enviarBatch(); }
+  onSpanStart(span)   { /* opcional */ }
+
+  onSpanEnd(span) {
+    this._buffer.push(span);
+    if (this._buffer.length >= 50) this._enviarBatch();
+  }
+
+  shutdown()    { this._enviarBatch(); }
+  forceFlush()  { this._enviarBatch(); }
+
+  _enviarBatch() {
+    const lote = this._buffer.splice(0);
+    if (!lote.length) return;
+    // Envío HTTP fire-and-forget
+    try {
+      const https = require('https');
+      const body  = JSON.stringify(lote);
+      const req   = https.request(this._destino, { method: 'POST',
+        headers: { 'Content-Type': 'application/json' } });
+      req.on('error', () => {});
+      req.write(body);
+      req.end();
+    } catch (_) {}
+  }
+}
+
+module.exports = { MiExportador };
+```
+
+### Paso 2 — Verificar la implementación
+
+```js
+const { TracingProcessor } = require('../../scripts/lib/tracing-processor-interface');
+const { MiExportador } = require('./mi-exportador');
+
+console.log(TracingProcessor.esProcesadorValido(new MiExportador())); // → true
+```
+
+### Paso 3 — Registrar en el pipeline (opcional)
+
+```js
+const { MultiProcessor } = require('../../scripts/lib/tracing-processor-interface');
+const { OtlpLocalProcessor } = require('../../hooks/lib/otlp-exporter');
+const { MiExportador } = require('./mi-exportador');
+
+const pipeline = new MultiProcessor([
+  new OtlpLocalProcessor(process.cwd()),   // siempre activo
+  new MiExportador({ destino: process.env.TRACES_ENDPOINT }),
+]);
+```
+
+---
+
+## Patrón Composite con MultiProcessor
+
+`MultiProcessor` implementa `TracingProcessor` y propaga cada evento a N hijos.
+
+**Cuándo usarlo:**
+- Necesitas enviar spans a más de un destino simultáneamente.
+- Quieres activar un exportador de consola durante debugging sin modificar el pipeline.
+- Construyes un pipeline configurable donde los destinos se leen de variables de entorno.
+
+**Comportamiento ante errores:** si un hijo lanza en `onSpanEnd`, `MultiProcessor`
+captura la excepción y continúa con los demás hijos. Ningún fallo individual
+interrumpe el pipeline completo.
+
+```js
+const multi = new MultiProcessor([exportadorA, exportadorB]);
+multi.addProcessor(exportadorC);   // agregar en tiempo de ejecución
+multi.removeProcessor(exportadorB); // eliminar por referencia
+```
+
+---
+
+## Casos de uso reales
+
+### Exportador a Langfuse (mediano plazo)
+
+Langfuse acepta trazas vía HTTP. Crear `scripts/lib/langfuse-processor.js`
+extendiendo `TracingProcessor`. En `onSpanEnd`, formatear el span al schema
+de Langfuse y encolarlo. En `shutdown`, vaciar la cola con `forceFlush`.
+
+Variables de entorno necesarias: `LANGFUSE_PUBLIC_KEY`, `LANGFUSE_SECRET_KEY`,
+`LANGFUSE_HOST`. El procesador solo se activa si `LANGFUSE_PUBLIC_KEY` está
+definida (patrón opt-in de `CLAUDE.md`).
+
+### Exportador a Jaeger
+
+Jaeger acepta spans en formato OpenTelemetry JSON. Los spans de swl-ses ya
+tienen la estructura correcta (`traceId`, `spanId`, `nombre`, `duracionMs`).
+El exportador debe mapear `estado: 'ERROR'` al código de status OTLP `2`.
+
+Endpoint: `JAEGER_OTLP_ENDPOINT` (por defecto `http://localhost:4318/v1/traces`).
+
+### Exportador para métricas agregadas
+
+En lugar de persistir spans crudos, un exportador puede agregar en memoria:
+contar spans por tipo, sumar duraciones, detectar anomalías. En `onTraceEnd`
+emite las métricas agregadas a `.planning/evolucion/metricas.json` usando
+`atomicWriteJSON` de `hooks/lib/atomic-write.js`.
+
+---
+
+## Anti-patrones
+
+| Anti-patrón | Problema | Solución |
+|-------------|----------|---------|
+| Exportador que bloquea `onSpanEnd` con I/O síncrono lento | Ralentiza todos los agentes | Usar cola interna y enviar en batch desde `onTraceEnd` o un setInterval |
+| Exportador que relanza excepciones de red | Interrumpe el pipeline completo | Capturar con try/catch, registrar el error internamente |
+| Exportador sin `shutdown` / `forceFlush` implementados | Spans en buffer se pierden al cerrar el proceso | Implementar ambos métodos; `shutdown` debe vaciar el buffer |
+| Exportador que modifica el span recibido | Efectos secundarios para otros procesadores en el pipeline | Clonar el span antes de mutarlo: `const s = { ...span }` |
+| Exportador activado incondicionalmente en producción | Agrega latencia sin config del usuario | Patrón opt-in: `if (!process.env.MI_ENDPOINT) return` al inicio |
+
+---
+
+## Relación con el resto del sistema
+
+| Componente | Relación |
+|-----------|----------|
+| `scripts/lib/tracing-processor-interface.js` | Define las clases abstractas `TracingProcessor`, `TracingExporter` y `MultiProcessor` |
+| `hooks/lib/otlp-exporter.js` | Implementación concreta `OtlpLocalProcessor` + funciones sueltas (compatibilidad) |
+| `scripts/lib/span-schema.js` | Taxonomía de 13 tipos de span; los spans que llegan a `onSpanEnd` siguen este schema |
+| `hooks/telemetria-agentes.js` | Produce los spans del ciclo de vida de agentes; es el emisor principal |
+| `.planning/traces/YYYY-MM-DD.jsonl` | Destino por defecto del `OtlpLocalProcessor` |
+| `hooks/lib/atomic-write.js` | Para exportadores que persisten estado (métricas, índices) — no usar para JSONL |
+
+## Cuándo NO cargar
+
+- Se leen o analizan trazas ya generadas en `.planning/traces/` — usar Read tool o `drift-detection`; este skill describe cómo construir exportadores nuevos, no cómo consumir el JSONL existente.
+- Se agrega observabilidad a hooks que no emiten spans del ciclo de vida de agentes (hooks de perfilado, guardrails, auditoría) — esos hooks registran en sus propios archivos JSONL; `TracingProcessor` es para el pipeline de spans de `telemetria-agentes.js`.
+- El exportador objetivo ya existe en `hooks/lib/otlp-exporter.js` y solo necesita activarse — los exportadores implementados se activan con la variable de entorno correspondiente (patrón opt-in); no requieren código nuevo.
+- Se diagnostica por qué un agente produjo un resultado incorrecto — las trazas miden ciclo de vida y duración, no lógica; para bugs usar `depurador-swl` o los logs del hook directamente.
+
+## Gotchas / Errores comunes no obvios
+
+- **`onSpanEnd` con I/O síncrono bloquea el pipeline completo**: el exportador llama a `fetch()` o `fs.writeFileSync()` directamente en `onSpanEnd` y ralentiza todos los agentes porque cada span espera al I/O antes de continuar. Causa: `onSpanEnd` se ejecuta síncronamente en el mismo event loop. Solución: encolar los spans en un buffer interno y vaciar el buffer en `onTraceEnd` o con un `setInterval` — el anti-patrón está documentado explícitamente en la tabla del skill.
+- **Exportador que mutua el span recibido afecta a otros procesadores en el pipeline**: un exportador agrega un campo `exportado: true` al span y el siguiente procesador en el `MultiProcessor` recibe el span modificado. Causa: los procesadores comparten el mismo objeto span por referencia. Solución: clonar el span antes de mutarlo (`const s = { ...span }`) — regla documentada en los anti-patrones del skill.
+- **`shutdown()` no implementado provoca pérdida de spans en buffer al cerrar el proceso**: el proceso del hook termina y los spans acumulados en la cola interna se descartan. Causa: implementar solo `onSpanEnd` y `onTraceEnd` sin `shutdown`. Solución: `shutdown` debe vaciar el buffer síncronamente (o retornar una Promise que resuelve al vaciar); Claude Code llama a `shutdown` en el proceso de cierre del hook.
+- **Exportador activado sin variable de entorno opt-in en todos los entornos**: el exportador a Langfuse se activa incluso en proyectos que no configuraron `LANGFUSE_PUBLIC_KEY`, añadiendo latencia de red sin beneficio. Causa: no implementar el guard de opt-in al inicio de `onSpanEnd`. Solución: todo exportador externo debe comenzar con `if (!process.env.MI_ENDPOINT) return` — el patrón opt-in de CLAUDE.md es obligatorio para integraciones enterprise.