@saulwade/swl-ses 1.9.0 → 2.0.0

package/habilidades/calidad-contract-testing/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: calidad-contract-testing
+description: >
+  Contract testing: verificar que la implementación honra el contrato declarado
+  en la spec (Pydantic, Zod, JSON Schema, OpenAPI/AsyncAPI, protobuf) y que
+  consumidor y proveedor de una API no divergen. Cubre herramientas por stack
+  (schemathesis, Dredd, Pact, zod, Pydantic, openapi-typescript), las dos
+  familias de contract testing (schema-based property testing y
+  consumer-driven contracts), generación de tests desde el schema del PLAN, y
+  uso como gate de verificación. Cargar cuando el PLAN declara schemas como
+  parte de la spec, al integrar dos servicios con un contrato compartido, o al
+  detectar drift entre lo que la API documenta y lo que devuelve.
+version: "1.0.0"
+herramientasPermitidas: [Read, Bash, Grep, Glob]
+exclusiones:
+  - "No cargar para tests unitarios de lógica de negocio — eso es tdd-workflow; el contract testing verifica el límite spec↔implementación, no la lógica interna."
+  - "No cargar si no hay un contrato declarado (schema, OpenAPI, Pact) — sin contrato no hay nada que verificar; primero declarar el schema en el PLAN."
+  - "No cargar para validación de input en runtime — eso es responsabilidad del framework (Pydantic/Zod en el endpoint); el contract testing corre en CI, no en cada request."
+evolvable: true
+---
+# Contract Testing — La Spec que se Verifica a Sí Misma
+
+La cobertura responde "¿qué código ejecutan los tests?". El mutation testing,
+"¿los tests detectarían un bug?". El contract testing responde la pregunta del
+límite: **"¿la implementación honra el contrato que la spec promete?"**. Un
+endpoint con 90% de cobertura puede devolver un campo con el tipo equivocado,
+omitir uno requerido o aceptar un payload que el schema prohíbe — los tests
+unitarios no lo ven porque usan los mismos supuestos que el código.
+
+**Principio**: el schema declarado en el PLAN (Pydantic/Zod/JSON Schema/OpenAPI)
+ES parte de la spec. Un contrato que no se verifica es documentación que miente.
+
+## Cuándo cargar este skill
+
+- El PLAN de la fase declara schemas (Pydantic, Zod, JSON Schema, OpenAPI) como
+  entregable — esos schemas son contrato verificable, no decoración.
+- Integración de dos servicios (frontend↔backend, microservicio↔microservicio)
+  con un contrato compartido que ambos lados deben respetar.
+- Drift detectado: la API documenta un campo que ya no devuelve, o devuelve uno
+  no documentado; un cliente generado rompe tras un cambio de backend.
+- Configurar contract testing como paso de `/swl:verificar` o gate de `tdd-qa-swl`.
+
+## Las dos familias de contract testing
+
+| Familia | Pregunta | Cuándo |
+|---------|----------|--------|
+| **Schema-based / property testing** | ¿La API respeta su propio schema OpenAPI ante cualquier input válido? | API con spec OpenAPI; un solo equipo controla ambos lados |
+| **Consumer-driven contracts (CDC)** | ¿El proveedor sigue cumpliendo lo que cada consumidor concreto espera? | Múltiples consumidores, equipos separados, despliegue independiente |
+
+Schema-based es más barato (un solo artefacto, la spec) y cubre el 80% del valor
+en proyectos de un equipo. CDC paga su complejidad cuando hay equipos y
+despliegues independientes que pueden romperse mutuamente sin saberlo.
+
+## Cómo funciona (schema-based)
+
+1. El schema (OpenAPI/Pydantic/Zod) define el contrato: rutas, métodos, forma de
+   request y response, campos requeridos, tipos, constraints.
+2. La herramienta **genera casos** desde el schema (property-based: cientos de
+   payloads válidos e inválidos) y los lanza contra la API real.
+3. Verifica que cada response **conforme al schema**: status esperado, forma,
+   tipos, requeridos presentes, sin campos extra prohibidos.
+4. Reporta violaciones: el contrato dice X, la implementación devolvió Y.
+
+## Herramientas por stack
+
+Antes de instalar, verificar versión vigente con Context7
+(regla `usar-context7.md`) — los nombres de paquete cambian entre majors.
+
+| Stack | Herramienta | Familia | Comando típico |
+|-------|------------|---------|----------------|
+| OpenAPI (cualquier lenguaje) | `schemathesis` | schema-based | `schemathesis run http://localhost:8000/openapi.json` |
+| OpenAPI (Node) | Dredd | schema-based | `dredd openapi.yaml http://localhost:3000` |
+| Python | Pydantic v2 (`model_validate`) | schema (límite) | validar request/response contra el modelo en el test |
+| JS/TS | Zod (`.parse`/`.safeParse`) | schema (límite) | parsear la response contra el schema en el test |
+| TS desde OpenAPI | `openapi-typescript` + tsc | schema (compile-time) | generar tipos y dejar que el compilador detecte drift |
+| Multi-equipo (poliglota) | Pact (`@pact-foundation/pact`, `pact-python`) | CDC | consumer genera pacto → provider lo verifica |
+| gRPC | `buf breaking` / protovalidate | schema-based | `buf breaking --against '.git#branch=main'` |
+
+## Generar tests desde el schema del PLAN
+
+Cuando `planear-fase` declara un schema como entregable, la tarea que lo
+implementa se verifica generando el contract test, no escribiéndolo a mano:
+
+```
+# OpenAPI + FastAPI: schemathesis deriva los casos del propio /openapi.json
+schemathesis run http://localhost:8000/openapi.json --checks all
+```
+
+```python
+# Pydantic como contrato en el test de integración:
+def test_endpoint_respeta_contrato():
+    # verifica: REQ-NN
+    r = client.get("/facturas/1")
+    FacturaResponse.model_validate(r.json())  # falla si la forma no conforma
+```
+
+```typescript
+// Zod como contrato del lado consumidor:
+const FacturaSchema = z.object({ id: z.number(), total: z.number(), vigencia: z.string() });
+const data = FacturaSchema.parse(await res.json()); // throw si el backend cambió la forma
+```
+
+## Umbrales y cuándo aplica el gate
+
+| Contexto | Gate | Justificación |
+|----------|------|---------------|
+| API pública o consumida por otro equipo | obligatorio: 0 violaciones de contrato | Un drift rompe consumidores en silencio |
+| Integración interna front↔back del mismo proyecto | recomendado: schema-based en CI | Barato con OpenAPI ya existente; atrapa el campo renombrado |
+| Endpoint interno sin consumidores externos | opcional | El esfuerzo de mantener pactos no paga |
+
+No imponer CDC donde schema-based basta: Pact con broker es infraestructura que
+solo paga con equipos y despliegues independientes.
+
+## Uso como gate de verificación
+
+En `/swl:verificar`, tras los tests unitarios: si la fase declaró schemas en el
+PLAN, correr el contract test contra la API real (entorno de test) y tratar cada
+violación de contrato como hallazgo CRÍTICO — la implementación contradice la
+spec aprobada. En `tdd-qa-swl` es gate opt-in: requiere la API levantable en CI.
+
+## Cuándo NO cargar
+
+- No hay contrato declarado (ni OpenAPI, ni schema, ni Pact) — primero declarar
+  el schema en el PLAN; sin contrato el contract testing no tiene qué verificar.
+- Lógica de negocio pura sin límite de API — eso es `tdd-workflow`/`testing-*`.
+- Prototipo de descarte donde la API cambia cada hora — el contrato se
+  estabiliza primero, luego se verifica.
+
+## Gotchas / Errores comunes no obvios
+
+- **Schema permisivo da falso verde**: un OpenAPI con `additionalProperties: true`
+  y casi todo opcional "conforma" con cualquier response — el contract test pasa
+  sin verificar nada. Causa: schema generado laxo (FastAPI sin `model_config`
+  estricto, Zod con `.passthrough()`). Solución: el contrato debe ser tan
+  estricto como la promesa real — requeridos marcados, `additionalProperties:
+  false` donde aplica.
+- **Property testing encuentra "bugs" en el schema, no en el código**: schemathesis
+  genera un edge case válido por schema que el código nunca contempló (string de
+  10000 chars, número en el límite). A veces el bug es del schema (demasiado
+  permisivo), no del endpoint. Diagnosticar antes de "arreglar" el código.
+- **Pact sin broker compartido es teatro**: si consumer y provider verifican
+  contra pactos en ramas distintas sin un broker central que versione, cada lado
+  pasa en aislamiento y rompen juntos en producción. CDC sin broker = falsa
+  seguridad; usar schema-based si no hay broker.
+- **Tipos generados que nadie recompila**: `openapi-typescript` genera tipos al
+  día del commit; si el pipeline no los regenera contra la spec viva, el
+  compilador valida contra un contrato fósil. El gate debe regenerar y comparar,
+  no confiar en el archivo commiteado (regla `verificar-citas-normativas.md §
+  comentarios temporales`).
+- **Contract test que levanta la app real es lento y flaky en CI**: si requiere
+  BD y servicios, hereda toda su fragilidad. Para schema-based puro, preferir el
+  modo que valida la spec estáticamente o contra un mock conformante antes de
+  exigir la app completa levantada.
+
+## Anti-patrones
+
+- **Schema decorativo**: declarar OpenAPI/Pydantic y nunca verificar que la
+  implementación lo cumple — documentación que diverge en silencio.
+- **CDC donde basta schema-based**: montar Pact + broker para un front↔back de
+  un solo equipo; complejidad sin retorno.
+- **Verificar el contrato contra un mock que usa el mismo schema**: tautología —
+  el mock conforma por construcción; el contract test debe correr contra la
+  implementación real.
+- **Tratar la violación de contrato como warning**: si la API rompe su contrato,
+  un consumidor ya está roto; es CRÍTICO, no observación.

package/habilidades/changelog-generator/SKILL.md

@@ -8,7 +8,12 @@ description: >
   de conformidad para decidir fallback manual. Cargar en /swl:release Paso 7
   cuando hay commits Conventional, o manualmente para previsualizar el
   changelog antes de un release.
-version: 1.0.0
+version: 1.1.0
+evolved: true
+evolved-from: "1.0.0"
+evolved-at: "2026-06-11"
+evolved-by: "fase-10-slice-5"
+evolved-note: "v1.1.0: el parser CC tolera el prefijo de trazabilidad [T-NN]/[REQ-NN] de la convención de ejecutar-fase — commits con prefijo de tarea cuentan como conformes (Fase 10)."
 nivelRiesgo: BAJO
 herramientasPermitidas: [Read, Bash]
 skillsInvocables: [release-semver]
@@ -47,7 +52,9 @@ exclusiones:
 2. **Parsea con Conventional Commits 1.0.0**: regex que captura tipo, scope,
    marca `!`, descripción. Soporta tipos extendidos del proyecto SWL:
    `evolucion` (cambios de skills/agentes), además de `feat/fix/perf/refactor/
-   docs/style/test/ci/build/chore/revert`.
+   docs/style/test/ci/build/chore/revert`. Tolera el prefijo opcional de
+   trazabilidad `[T-NN]` / `[REQ-NN]` de la convención de `ejecutar-fase`
+   (no altera la semántica CC — el tipo+scope+descripción siguen presentes).
 3. **Detecta breaking changes** por marca `!` después del tipo o trailer
    `BREAKING CHANGE:` en el body. Los breaking siempre van al inicio del
    release, sin importar el tipo original.

package/habilidades/changelog-generator/scripts/parse-commits.js

@@ -50,8 +50,18 @@ const { execSync } = require('node:child_process');
  *   feat!: breaking change inline
  *   refactor(hooks/lib): split evolution-tracker
  *   chore(release): bump version
+ *   [T-01] feat(hooks): prefijo de trazabilidad de tarea (ejecutar-fase)
+ *   [T-07][T-08] refactor(hooks): varios prefijos consecutivos
+ *   [REQ-08] feat(scripts): prefijo de requisito
+ *
+ * El prefijo opcional `[T-NN]` / `[REQ-NN]` (uno o más, consecutivos) proviene
+ * de la convención de commits de `habilidades/ejecutar-fase/SKILL.md`
+ * (trazabilidad de tarea/requisito). No altera la semántica CC: el
+ * tipo+scope+descripción siguen presentes después del/los prefijo(s), por lo
+ * que el commit cuenta como conforme. Grupo non-capturing para no desplazar
+ * los índices [1]=tipo [2]=scope [3]=! [4]=descripcion.
  */
-const RE_CONVENTIONAL = /^(feat|fix|perf|refactor|docs|style|test|ci|build|chore|revert|evolucion|evolve)(?:\(([^)]+)\))?(!)?:\s*(.+)$/;
+const RE_CONVENTIONAL = /^(?:\[(?:T|REQ)-\d+\]\s*)*(feat|fix|perf|refactor|docs|style|test|ci|build|chore|revert|evolucion|evolve)(?:\(([^)]+)\))?(!)?:\s*(.+)$/;
 
 /** Mapa tipo CC → categoría Keep a Changelog en es-MX. */
 const CATEGORIAS = Object.freeze({

package/habilidades/diagrama-arquitectura/SKILL.md

@@ -33,7 +33,7 @@ Basado en architecture-diagram-generator (MIT, Cocoon AI) — adaptado al sistem
 - El usuario pide un diagrama de arquitectura del proyecto
 - `arquitecto-swl` necesita visualizar la arquitectura propuesta
 - `documentador-swl` genera documentación visual
-- `/swl:wiki` o `/swl:dashboard` necesitan representación gráfica
+- `/swl:wiki` o `/swl:status dashboard` necesitan representación gráfica
 - Cualquier tarea de RFC, ADR o propuesta arquitectónica
 
 ## Sistema de diseño

package/habilidades/drift-detection/SKILL.md

@@ -1,179 +1,179 @@
----
-name: drift-detection
-version: 1.0.0
-herramientasPermitidas: [Read]
-description: "Detección de drift de métricas de agentes/skills via ventana deslizante (7d) vs baseline (4 semanas). Integrado al operador Reflect del ciclo AGP."
-exclusiones:
-  - "No cargar para detectar drift en código de aplicación (regressions de negocio); este skill detecta drift en métricas de uso de agentes/skills del sistema SWL."
-  - "No cargar si hay menos de 7 días de trazas en `.planning/traces/`; el baseline de 4 semanas no existirá y los resultados serán estadísticamente inválidos."
-  - "No cargar para observabilidad de la aplicación en producción; usar `monitoring-alertas` para eso."
-  - "No cargar manualmente cuando el ciclo AGP ya ejecuta `ejecutarDriftAutomatico()` en cada SubagentStop — invocarlo dos veces dobla el trabajo sin beneficio."
-author: swl-ses
-evolvable: true
-evolvable_scope: [content, examples]
-domain: ingeniería-de-software
-tags: [agp, observabilidad, drift, métricas, ciclo-agp]
----
-# drift-detection — Detección de drift para el ciclo AGP
-
-Algoritmo de ventana deslizante que compara métricas recientes (últimos 7 días)
-contra un baseline histórico (4 semanas previas) para detectar degradación de
-skills y agentes antes de que el health score lo refleje.
-
-Adaptado de `runDriftCheck`/`getDriftTimeline` en mission-control-main (MIT).
-
-## Módulo principal
-
-`scripts/lib/drift-detector.js` — zero-deps, Node stdlib únicamente.
-
-## Cuándo se activa
-
-- Manual: desde cualquier script o agente que necesite análisis de degradación.
-- Automático (vía `hooks/auto-evolucion.js`): el hook ejecuta `ejecutarDriftAutomatico()`
-  en cada `SubagentStop` con un throttle de 24 h (configurable con `SWL_DRIFT_THROTTLE_H`).
-  Se evalúan los últimos 5 archivos JSONL de trazas. Opt-out total con `SWL_DRIFT_DISABLED=1`.
-- Automático (vía ciclo AGP): `hooks/lib/reflect-classifier.js` expone
-  `ejecutarDriftReflect(rutaJsonl, nombreAgente)` como punto de extensión alternativo.
-- Las trazas de agentes viven en `.planning/traces/YYYY-MM-DD.jsonl`.
-
-## Exports del módulo
-
-```js
-const { detectarDrift, generarLineaTemporal } = require('./scripts/lib/drift-detector');
-```
-
-### `detectarDrift(opts)`
-
-```js
-detectarDrift({
-  rutaJsonl:           '/ruta/a/traces.jsonl',
-  ventanaDias:         7,       // default
-  baselineSemanasBase: 4,       // default
-  umbralPct:           10,      // warn si |drift| > 10%
-  metricas:            ['tokens_promedio_por_sesion', 'tasa_exito_tool', 'tasa_finalizacion_tarea'],
-  agente:              'backend-python-swl',  // para nudges
-})
-```
-
-**Retorna:**
-
-```json
-{
-  "drifts": [
-    {
-      "metrica": "tokens_promedio_por_sesion",
-      "baseline": 1000,
-      "reciente": 2100,
-      "driftPct": 110.0,
-      "estado": "critico"
-    },
-    {
-      "metrica": "tasa_exito_tool",
-      "baseline": 0.9,
-      "reciente": 0.85,
-      "driftPct": -5.56,
-      "estado": "ok"
-    }
-  ],
-  "timestamp": "2026-04-19T12:00:00.000Z",
-  "estado_global": "critico"
-}
-```
-
-**Estados por métrica:**
-
-| Condición | Estado |
-|-----------|--------|
-| `abs(driftPct) <= umbralPct` | `ok` |
-| `abs(driftPct) > umbralPct` | `warn` |
-| `abs(driftPct) > umbralPct * 2` | `critico` |
-
-**Estado global:** el peor estado entre todas las métricas.
-
-### `generarLineaTemporal(opts)`
-
-```js
-generarLineaTemporal({
-  rutaJsonl: '/ruta/a/traces.jsonl',
-  dias:      30,   // default
-})
-// → [{ fecha: '2026-04-19', tokens: 3200, exitos: 12, fallos: 1 }, ...]
-```
-
-Retorna un array de longitud `dias`, uno por día, para visualización en
-el dashboard o en reportes de salud.
-
-## Estructura de eventos esperada en el JSONL
-
-El módulo es permisivo: extrae métricas de cualquier campo que coincida.
-
-| Métrica | Campos aceptados en el evento |
-|---------|-------------------------------|
-| Tokens | `atributos.tokens_totales`, `tokens`, `total_tokens` |
-| Éxito de tool | `success`, `exito`, `atributos.success` |
-| Finalización de tarea | `estado`, `status`, `atributos.estado` (valores: `OK`, `done`, `completado`) |
-| Timestamp | `timestamp`, `ts`, `inicio`, `created_at` |
-
-Formato nativo de `.planning/traces/YYYY-MM-DD.jsonl`:
-
-```json
-{"traceId":"...","nombre":"agent:backend-python-swl","inicio":"2026-04-19T10:00:00.000Z","estado":"OK","atributos":{"tokens_totales":1500}}
-```
-
-## Integración con el ciclo AGP
-
-El operador Reflect (`hooks/lib/reflect-classifier.js`) expone:
-
-```js
-const { ejecutarDriftReflect } = require('./hooks/lib/reflect-classifier');
-
-const resultado = ejecutarDriftReflect(
-  '.planning/traces/2026-04-19.jsonl',
-  'backend-python-swl'
-);
-// resultado: { drifts, timestamp, estado_global } o null si módulo no disponible
-```
-
-Cuando `estado_global === 'critico'`, el módulo emite automáticamente un nudge
-a `.planning/evolution/nudges.jsonl`:
-
-```json
-{
-  "timestamp": "2026-04-19T12:00:00.000Z",
-  "tipo": "drift-detectado",
-  "agente_o_skill": "backend-python-swl",
-  "metrica": "tokens_promedio_por_sesion",
-  "drift_pct": 110.0,
-  "estado": "critico"
-}
-```
-
-El agente `auto-evolucion-swl` consume estos nudges para proponer mejoras.
-
-## Cómo interpretar los resultados
-
-- **`ok`**: métricas estables. Sin acción requerida.
-- **`warn`**: degradación moderada. Revisar en el próximo ciclo de evolución.
-- **`critico`**: degradación severa. Invocar `/swl:evolucionar` con el agente
-  identificado. El nudge ya fue emitido — aparecerá en `/swl:salud`.
-
-## Cuándo NO cargar
-
-- Se busca detectar regresiones en el código de la aplicación (tests fallando, performance degradada); para eso usar `monitoring-alertas` o el revisor de código correspondiente.
-- El proyecto tiene menos de 7 días de trazas — el baseline de 4 semanas no puede calcularse y `detectarDrift` retornará resultados sin significado estadístico.
-- El ciclo AGP ya tiene configurado el throttle automático de 24 h; invocar el drift manualmente en el mismo intervalo produce el mismo nudge dos veces sin nuevo valor.
-
-## Gotchas / Errores comunes no obvios
-
-- **Timestamps inválidos en eventos JSONL provocan líneas ignoradas silenciosamente**: el módulo es permisivo con los campos pero si ningún campo de timestamp (`timestamp`, `ts`, `inicio`, `created_at`) tiene una fecha ISO válida, el evento se descarta del cálculo. Causa: eventos generados con timestamps de formato local (ej. `"19/04/2026"`) no pasan la validación. Solución: verificar que todos los eventos JSONL del trace tengan al menos un campo de timestamp en formato ISO 8601 — si el baseline aparece como 0, es el primer síntoma de eventos descartados.
-- **Estado `critico` emitido por baseline con muy pocos eventos**: si el baseline de 4 semanas tiene solo 3 eventos y la ventana de 7 días tiene 8, el `driftPct` de tokens se dispara al 166% cuando en realidad el agente está más activo, no degradado. Causa: el módulo no valida que el baseline tenga suficientes eventos para ser estadísticamente válido. Solución: antes de interpretar un estado `critico`, verificar que el baseline tiene al menos 20 eventos — si no, marcar el resultado como `insufficient-data` en lugar de accionar.
-- **Nudge duplicado en `.planning/evolution/nudges.jsonl` por falta de deduplicación**: el hook se ejecuta dos veces en el mismo `SubagentStop` (por bug de throttle) y emite el mismo nudge dos veces. Causa: el throttle `SWL_DRIFT_THROTTLE_H` no validó correctamente el timestamp del último run. Solución: el archivo `nudges.jsonl` es append-only — antes de emitir un nudge, verificar si el último evento del mismo `agente_o_skill` y `metrica` tiene un timestamp dentro de la ventana de throttle.
-- **`atomicWriteJSON` usado para escribir en nudges.jsonl**: escribir el archivo completo en lugar de hacer append corrompe el historial de nudges previos. Causa: confusión entre archivos de estado mutable (usan `atomicWriteJSON`) y archivos de eventos de alta frecuencia (usan `fs.appendFileSync`). Solución: `nudges.jsonl` es un JSONL de alta frecuencia — siempre usar `fs.appendFileSync(ruta, JSON.stringify(nudge) + '\n')`, nunca reescribir el archivo completo.
-
-## Referencia cruzada
-
-- Módulo: `scripts/lib/drift-detector.js`
-- Tests: `tests/lib/drift-detector.test.js`
-- Operador Reflect: `hooks/lib/reflect-classifier.js`
-- Ciclo AGP: `.planning/evolution/nudges.jsonl`
-- Origen (adaptado de): `temp/mission-control-main/src/lib/agent-evals.ts` — MIT
+---
+name: drift-detection
+version: 1.0.0
+herramientasPermitidas: [Read]
+description: "Detección de drift de métricas de agentes/skills via ventana deslizante (7d) vs baseline (4 semanas). Integrado al operador Reflect del ciclo AGP."
+exclusiones:
+  - "No cargar para detectar drift en código de aplicación (regressions de negocio); este skill detecta drift en métricas de uso de agentes/skills del sistema SWL."
+  - "No cargar si hay menos de 7 días de trazas en `.planning/traces/`; el baseline de 4 semanas no existirá y los resultados serán estadísticamente inválidos."
+  - "No cargar para observabilidad de la aplicación en producción; usar `monitoring-alertas` para eso."
+  - "No cargar manualmente cuando el ciclo AGP ya ejecuta `ejecutarDriftAutomatico()` en cada SubagentStop — invocarlo dos veces dobla el trabajo sin beneficio."
+author: swl-ses
+evolvable: true
+evolvable_scope: [content, examples]
+domain: ingeniería-de-software
+tags: [agp, observabilidad, drift, métricas, ciclo-agp]
+---
+# drift-detection — Detección de drift para el ciclo AGP
+
+Algoritmo de ventana deslizante que compara métricas recientes (últimos 7 días)
+contra un baseline histórico (4 semanas previas) para detectar degradación de
+skills y agentes antes de que el health score lo refleje.
+
+Adaptado de `runDriftCheck`/`getDriftTimeline` en mission-control-main (MIT).
+
+## Módulo principal
+
+`scripts/lib/drift-detector.js` — zero-deps, Node stdlib únicamente.
+
+## Cuándo se activa
+
+- Manual: desde cualquier script o agente que necesite análisis de degradación.
+- Automático (vía `hooks/lib/etapa-auto-evolucion.js`): el hook ejecuta `ejecutarDriftAutomatico()`
+  en cada `SubagentStop` con un throttle de 24 h (configurable con `SWL_DRIFT_THROTTLE_H`).
+  Se evalúan los últimos 5 archivos JSONL de trazas. Opt-out total con `SWL_DRIFT_DISABLED=1`.
+- Automático (vía ciclo AGP): `hooks/lib/reflect-classifier.js` expone
+  `ejecutarDriftReflect(rutaJsonl, nombreAgente)` como punto de extensión alternativo.
+- Las trazas de agentes viven en `.planning/traces/YYYY-MM-DD.jsonl`.
+
+## Exports del módulo
+
+```js
+const { detectarDrift, generarLineaTemporal } = require('./scripts/lib/drift-detector');
+```
+
+### `detectarDrift(opts)`
+
+```js
+detectarDrift({
+  rutaJsonl:           '/ruta/a/traces.jsonl',
+  ventanaDias:         7,       // default
+  baselineSemanasBase: 4,       // default
+  umbralPct:           10,      // warn si |drift| > 10%
+  metricas:            ['tokens_promedio_por_sesion', 'tasa_exito_tool', 'tasa_finalizacion_tarea'],
+  agente:              'backend-python-swl',  // para nudges
+})
+```
+
+**Retorna:**
+
+```json
+{
+  "drifts": [
+    {
+      "metrica": "tokens_promedio_por_sesion",
+      "baseline": 1000,
+      "reciente": 2100,
+      "driftPct": 110.0,
+      "estado": "critico"
+    },
+    {
+      "metrica": "tasa_exito_tool",
+      "baseline": 0.9,
+      "reciente": 0.85,
+      "driftPct": -5.56,
+      "estado": "ok"
+    }
+  ],
+  "timestamp": "2026-04-19T12:00:00.000Z",
+  "estado_global": "critico"
+}
+```
+
+**Estados por métrica:**
+
+| Condición | Estado |
+|-----------|--------|
+| `abs(driftPct) <= umbralPct` | `ok` |
+| `abs(driftPct) > umbralPct` | `warn` |
+| `abs(driftPct) > umbralPct * 2` | `critico` |
+
+**Estado global:** el peor estado entre todas las métricas.
+
+### `generarLineaTemporal(opts)`
+
+```js
+generarLineaTemporal({
+  rutaJsonl: '/ruta/a/traces.jsonl',
+  dias:      30,   // default
+})
+// → [{ fecha: '2026-04-19', tokens: 3200, exitos: 12, fallos: 1 }, ...]
+```
+
+Retorna un array de longitud `dias`, uno por día, para visualización en
+el dashboard o en reportes de salud.
+
+## Estructura de eventos esperada en el JSONL
+
+El módulo es permisivo: extrae métricas de cualquier campo que coincida.
+
+| Métrica | Campos aceptados en el evento |
+|---------|-------------------------------|
+| Tokens | `atributos.tokens_totales`, `tokens`, `total_tokens` |
+| Éxito de tool | `success`, `exito`, `atributos.success` |
+| Finalización de tarea | `estado`, `status`, `atributos.estado` (valores: `OK`, `done`, `completado`) |
+| Timestamp | `timestamp`, `ts`, `inicio`, `created_at` |
+
+Formato nativo de `.planning/traces/YYYY-MM-DD.jsonl`:
+
+```json
+{"traceId":"...","nombre":"agent:backend-python-swl","inicio":"2026-04-19T10:00:00.000Z","estado":"OK","atributos":{"tokens_totales":1500}}
+```
+
+## Integración con el ciclo AGP
+
+El operador Reflect (`hooks/lib/reflect-classifier.js`) expone:
+
+```js
+const { ejecutarDriftReflect } = require('./hooks/lib/reflect-classifier');
+
+const resultado = ejecutarDriftReflect(
+  '.planning/traces/2026-04-19.jsonl',
+  'backend-python-swl'
+);
+// resultado: { drifts, timestamp, estado_global } o null si módulo no disponible
+```
+
+Cuando `estado_global === 'critico'`, el módulo emite automáticamente un nudge
+a `.planning/evolution/nudges.jsonl`:
+
+```json
+{
+  "timestamp": "2026-04-19T12:00:00.000Z",
+  "tipo": "drift-detectado",
+  "agente_o_skill": "backend-python-swl",
+  "metrica": "tokens_promedio_por_sesion",
+  "drift_pct": 110.0,
+  "estado": "critico"
+}
+```
+
+El agente `auto-evolucion-swl` consume estos nudges para proponer mejoras.
+
+## Cómo interpretar los resultados
+
+- **`ok`**: métricas estables. Sin acción requerida.
+- **`warn`**: degradación moderada. Revisar en el próximo ciclo de evolución.
+- **`critico`**: degradación severa. Invocar `/swl:evolucionar` con el agente
+  identificado. El nudge ya fue emitido — aparecerá en `/swl:status salud`.
+
+## Cuándo NO cargar
+
+- Se busca detectar regresiones en el código de la aplicación (tests fallando, performance degradada); para eso usar `monitoring-alertas` o el revisor de código correspondiente.
+- El proyecto tiene menos de 7 días de trazas — el baseline de 4 semanas no puede calcularse y `detectarDrift` retornará resultados sin significado estadístico.
+- El ciclo AGP ya tiene configurado el throttle automático de 24 h; invocar el drift manualmente en el mismo intervalo produce el mismo nudge dos veces sin nuevo valor.
+
+## Gotchas / Errores comunes no obvios
+
+- **Timestamps inválidos en eventos JSONL provocan líneas ignoradas silenciosamente**: el módulo es permisivo con los campos pero si ningún campo de timestamp (`timestamp`, `ts`, `inicio`, `created_at`) tiene una fecha ISO válida, el evento se descarta del cálculo. Causa: eventos generados con timestamps de formato local (ej. `"19/04/2026"`) no pasan la validación. Solución: verificar que todos los eventos JSONL del trace tengan al menos un campo de timestamp en formato ISO 8601 — si el baseline aparece como 0, es el primer síntoma de eventos descartados.
+- **Estado `critico` emitido por baseline con muy pocos eventos**: si el baseline de 4 semanas tiene solo 3 eventos y la ventana de 7 días tiene 8, el `driftPct` de tokens se dispara al 166% cuando en realidad el agente está más activo, no degradado. Causa: el módulo no valida que el baseline tenga suficientes eventos para ser estadísticamente válido. Solución: antes de interpretar un estado `critico`, verificar que el baseline tiene al menos 20 eventos — si no, marcar el resultado como `insufficient-data` en lugar de accionar.
+- **Nudge duplicado en `.planning/evolution/nudges.jsonl` por falta de deduplicación**: el hook se ejecuta dos veces en el mismo `SubagentStop` (por bug de throttle) y emite el mismo nudge dos veces. Causa: el throttle `SWL_DRIFT_THROTTLE_H` no validó correctamente el timestamp del último run. Solución: el archivo `nudges.jsonl` es append-only — antes de emitir un nudge, verificar si el último evento del mismo `agente_o_skill` y `metrica` tiene un timestamp dentro de la ventana de throttle.
+- **`atomicWriteJSON` usado para escribir en nudges.jsonl**: escribir el archivo completo en lugar de hacer append corrompe el historial de nudges previos. Causa: confusión entre archivos de estado mutable (usan `atomicWriteJSON`) y archivos de eventos de alta frecuencia (usan `fs.appendFileSync`). Solución: `nudges.jsonl` es un JSONL de alta frecuencia — siempre usar `fs.appendFileSync(ruta, JSON.stringify(nudge) + '\n')`, nunca reescribir el archivo completo.
+
+## Referencia cruzada
+
+- Módulo: `scripts/lib/drift-detector.js`
+- Tests: `tests/lib/drift-detector.test.js`
+- Operador Reflect: `hooks/lib/reflect-classifier.js`
+- Ciclo AGP: `.planning/evolution/nudges.jsonl`
+- Origen (adaptado de): `temp/mission-control-main/src/lib/agent-evals.ts` — MIT