@saulwade/swl-ses 2.6.0 → 2.8.0

package/habilidades/calidad-anti-patrones-universales/SKILL.md

@@ -11,7 +11,7 @@ description: >
   condiciones, if anidadas ≥3 niveles, queries en loops, dos funciones casi
   idénticas, mutaciones de estado sin guard). NO sustituye a los revisores —
   los enriquece con vocabulario nombrado para reportes consistentes.
-version: "1.0.0"
+version: "1.0.1"
 herramientasPermitidas: [Read, Grep, Glob]
 exclusiones:
   - "No cargar como sustituto de revisor-codigo-swl ni de los revisores especializados — este skill aporta vocabulario y ejemplos, los revisores ejecutan el análisis."
@@ -331,6 +331,110 @@ const vacio = items.length === 0;
 
 ---
 
+## Anti-patrones de robustez de tests (concurrencia y CI)
+
+Cuatro anti-patrones que no son code smells del sujeto bajo prueba, sino de la
+suite misma: producen tests flaky que erosionan la confianza en el CI. Aparecen
+cross-lenguaje en cualquier runner con procesos fork y locks.
+
+### A. Aserción de exclusión perfecta sobre un lock near-perfect
+
+NUNCA asertar exclusión PERFECTA ("exactamente 1 ganador SIEMPRE") sobre un lock
+documentado como *near-perfect* — es MÁS ESTRICTO que el contrato, así que el
+test es flaky de raíz.
+
+**Problema**: un lock de archivo zero-dep (tipo `proper-lockfile`) documenta una
+race residual "despreciable" (leak en µs + doble-reclamo). Bajo la carga de un
+runner de CI esa race sube a ~15-40%, y una aserción de exclusión perfecta la
+convierte en falla intermitente.
+
+**Fix de fondo** — alinear el test al contrato: reintentar el escenario con estado
+100% FRESCO por intento (re-provisionar sandbox/fixtures/lock) hasta N=8, cortando
+cuando la exclusión se cumple; aserción final sobre el ÚLTIMO intento. Un bug
+catastrófico falla los 8 intentos (se caza); la race despreciable gana en alguno.
+NO eliminar el test (pierde la red de regresión) NI reforzar el lock (rediseño de
+alto riesgo).
+
+```javascript
+// MAL — asevera exclusión perfecta; flaky bajo carga de CI
+const ganadores = await correrNProcesos(16);
+assert.equal(ganadores.length, 1);   // la race del lock lo tumba ~15-40%
+
+// BIEN — retry-align al contrato "near-perfect"
+const { conReintentoDeExclusion } = require('../_helpers/exclusion-retry');
+await conReintentoDeExclusion({
+  intentos: 8,
+  provisionar: prepararSandboxFresco,     // estado 100% fresco por intento
+  escenario: () => correrNProcesos(16),   // corta al 1er intento con exclusión OK
+});
+```
+
+**Reporte**: "Stress test flaky — `<archivo:línea>` asevera exclusión perfecta sobre lock near-perfect. Alinear con retry-align (`conReintentoDeExclusion`, `tests/_helpers/exclusion-retry.js`)."
+
+### B. IPC `process.send` seguido de `disconnect()` en el mismo tick
+
+NUNCA `process.send(payload); process.disconnect()` en el mismo tick — bajo carga
+el proceso sale (exit 0) y cierra el canal IPC antes de entregar el mensaje.
+
+**Problema**: el padre ve `'exit'` sin `'result'` → falla intermitente
+"worker terminó sin resultado". Fue bug de CLASE en 3 archivos (single-use-store,
+policy-broker-concurrency, integrity-ledger fixture).
+
+**Fix**: SIEMPRE desconectar en el callback de send, porque el callback garantiza
+el flush del mensaje antes de cerrar el canal.
+
+```javascript
+// MAL — disconnect en el mismo tick; el mensaje puede no entregarse
+process.send(payload);
+process.disconnect();
+
+// BIEN — disconnect tras el callback de flush
+process.send(payload, () => process.disconnect());
+```
+
+### C. Construcciones de path platform-específicas en tests
+
+NUNCA construir un path de test asumiendo una sola plataforma — pasa en Windows y
+falla en Linux CI (o viceversa).
+
+**Problema**: `\\?\` (extended-length de Windows) NO es absoluto en POSIX; `C:\...`
+no es absoluto en Linux; `:` es ADS en NTFS pero char válido en POSIX. Un fixture
+que arma la ruta con la sintaxis de un solo SO revienta la aserción en el otro.
+
+**Fix**: construir platform-aware, manteniendo la rama `win32` IDÉNTICA al input
+original ya verificado, para no romper el kill/aserción que sí funcionaba.
+
+```javascript
+// MAL — \\?\ no es absoluto en POSIX; el test falla en Linux CI
+const ruta = '\\\\?\\C:\\tmp\\objetivo';
+
+// BIEN — platform-aware; rama win32 intacta
+const ruta = process.platform === 'win32'
+  ? '\\\\?\\C:\\tmp\\objetivo'
+  : '/tmp/objetivo';
+```
+
+**Reporte**: "Path platform-específico — `<archivo:línea>` asume `<so>`; ramificar con `process.platform === 'win32'`."
+
+### D. Crecimiento de suite que destapa flakiness pre-existente
+
+SIEMPRE sospechar contención de recursos (no regresión de código) cuando un test
+de stress que pasaba empieza a flaquear tras agregar muchos tests.
+
+**Problema**: agregar muchos tests —aunque cada uno sea rápido— sube la carga del
+runner de CI y destapa flakiness pre-existente en tests de stress de concurrencia
+(starvation de procesos fork). Señal: un test de 16 procesos que pasaba empieza a
+flaquear tras agregar ~250 tests nuevos, sin que el código bajo prueba cambiara.
+
+**Fix**: mitigación de primera línea (insuficiente sola) `--test-concurrency=1` en
+CI, que serializa archivos y da CPU dedicada a los tests de stress; el fix durable
+es el retry-align del anti-patrón A, porque `--test-concurrency=1` reduce la
+probabilidad de la race pero no la elimina.
+
+**Reporte**: "Flaky por contención — `<archivo:línea>` (test de stress) flaquea tras crecer la suite. Aplicar retry-align, no reintentar a ciegas."
+
+---
+
 ## Formato de reporte sugerido
 
 Cuando un revisor detecta uno o más anti-patrones, integrarlo en su reporte

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

@@ -1,165 +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.
+---
+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/calidad-mutation-testing/SKILL.md

@@ -10,7 +10,7 @@ description: >
   tdd-qa-swl. Cargar cuando la cobertura de líneas es alta pero se sospecha de
   asserts débiles, al endurecer la suite de un módulo crítico, o al configurar
   el gate de mutación en CI.
-version: "1.0.0"
+version: "1.0.2"
 herramientasPermitidas: [Read, Bash, Grep, Glob]
 exclusiones:
   - "No cargar si la suite no está verde y estable — el mutation testing presupone tests deterministas que pasan; con tests flaky el score es ruido."
@@ -157,6 +157,20 @@ débil" o "test faltante" se atienden antes del cierre (regla
   referencia commits que el rebase reescribió — el modo incremental se
   degrada a corrida completa sin avisar. Presupuestar la primera corrida
   post-rebase como completa.
+- **El baseline "rápido" de validación debe copiar el MISMO set de directorios por módulo que las tareas reales de mutación, nunca la unión del batch**: un motor propio (`scripts/lib/w4-motor-mutacion.js`, swl-ses F32-T07) validaba el baseline de N módulos en un solo directorio temporal compartido, copiando la UNIÓN de las dependencias extra (`directoriosExtra`) declaradas por todo el batch — mientras que cada tarea de mutación real copiaba solo el set del módulo individual. La unión enmascaró que 7/20 módulos nunca declaraban sus dependencias reales: el baseline (que veía el paquete completo) pasaba, pero cada mutante individual de esos 7 módulos fallaba con `MODULE_NOT_FOUND` — y el clasificador `exitCode !== 0 = muerto` contó esos fallos de entorno como kills legítimos, produciendo un falso 100% de mutation score en 7 módulos críticos. Detectado solo al reproducir `ejecutarMutationTesting({modulos:[unicoModulo]})` en aislamiento para cada módulo "100%" — ninguno de los 4 revisores adversariales que auditaron el motor lo detectó porque ninguno re-derivó el número, solo revisaron la lógica (ver `extractor-de-aprendizajes/SKILL.md § Modo G`). Fix: el baseline corre por módulo, en su propio directorio efímero, con el MISMO set de directorios (`directoriosParaModulo`, nunca la unión) que usan las tareas reales — cualquier discrepancia de dependencias declaradas se vuelve visible de inmediato como `MUTATION_BASELINE_FAILED` en vez de quedar enmascarada. Regla general: si un paso de validación rápida comparte entorno entre unidades que en producción corren aisladas, ese paso no prueba lo que dice probar.
+- **Verificar equivalencia de un sobreviviente SIEMPRE contra el MOTOR REAL,
+  nunca en un sandbox aislado**: agentes escépticos que "mataron" o "confirmaron
+  equivalente" mutantes en sandboxes propios produjeron 88 falsos sobrevivientes
+  (52 supuestamente muertos seguían vivos contra el motor). Solo correr el motor
+  real con un `filtroClaves` (opt-in: corre únicamente los mutantes puntuales
+  sobre el working tree actual) da la verdad, porque el sandbox no reproduce el
+  entorno de dependencias real donde el mutante se mata o sobrevive. Además, la
+  clave con que se anota un mutante como equivalente DEBE incluir el offset
+  absoluto (`inicioAbs`), no solo `{modulo, linea, operador, original, mutado}`:
+  una línea puede tener >1 operador idéntico (p. ej. `!a || b || c` genera 3
+  mutantes `||→&&` con la MISMA clave sin offset), donde uno es matable y los
+  otros equivalentes; sin offset se confunden y la anotación de uno tapa a otro.
+  Evidencia: DT-T07, ADR-0055.
 
 ## Anti-patrones
 
@@ -168,3 +182,13 @@ débil" o "test faltante" se atienden antes del cierre (regla
   en PR, completa nightly.
 - **Ignorar el desglose y mirar solo el porcentaje** — los sobrevivientes
   individuales son la información; el score es solo el resumen.
+- **Inyectar el 100% de mutation score a mano (anti-gaming)** — el Gate debe
+  computar el score MECÁNICAMENTE (lo calcula el motor), nunca escribir el 100%
+  a dedo, porque un número tecleado no prueba nada. La anotación de equivalentes
+  se blinda con un invariante fail-closed: un mutante anotado como equivalente
+  que resulte MUERTO por un TEST REAL (`detailCode` ausente) hace FALLAR el motor
+  (`MUTATION_EQUIVALENTE_MATADO`), ya que si un test real lo mata no era
+  equivalente y la anotación falsa se delata sola. Refinamiento: muerte por
+  `TIMEOUT` o `SYNTAX_ERROR` es ruido de infraestructura (tests-worker flaky), NO
+  detección de comportamiento → no invalida la anotación. Evidencia: ADR-0055,
+  `scripts/lib/w4-motor-mutacion.js`.