@saulwade/swl-ses 2.0.0 → 2.2.0

package/habilidades/tdd-workflow/SKILL.md

@@ -1,713 +1,715 @@
----
-name: tdd-workflow
-description: Flujo completo de Test-Driven Development. Ciclo RED (el test falla) → GREEN (implementación mínima) → REFACTOR (limpieza). Incluye cobertura mínima obligatoria, tests de frontera, factories, fixtures y estrategias para diferentes tipos de código (APIs, services, componentes Angular).
-version: "1.2.0"
-evolved: true
-evolved-from: "1.1.0"
-evolved-at: "2026-06-11"
-evolved-by: "fase-10-slice-2"
-evolved-note: "v1.2.0: sección 'Evidencia RED en telemetría' (gate G2, ADR-0035, cierra F-TDD-6) — registro de corridas tdd-* en loop-telemetry. v1.0.5: gotcha 'Tests E2E de CLIs interactivos sin PTY real'. Origen M2 sesión 2026-05-16. v1.0.4: silenced tests por race en path único compartido. v1.0.3: gotcha cwd cacheado al require()."
-herramientasPermitidas: [Read, Bash]
-evolvable: true  # default para skill estandar
-exclusiones:
-  - "No cargar para escribir tests de regresión sobre código legacy sin suite existente — en código legacy sin tests, comenzar con caracterización de comportamiento actual antes del ciclo TDD."
-  - "No cargar para pruebas de carga o performance testing — para benchmarks y load testing cargar `performance-baseline`."
-  - "No cargar para configurar pipelines de CI/CD o runners de tests en GitHub Actions / GitLab CI — para configuración de CI cargar el skill de cloud correspondiente."
-  - "No cargar para pruebas de seguridad o fuzzing automático — para testing de seguridad cargar `threat-model-lite` y usar herramientas especializadas (Bandit, OWASP ZAP)."
----
-# Habilidad: TDD Workflow Completo
-
-## Cuándo NO cargar
-
-- La tarea es añadir tests a código legacy sin suite existente: comenzar con tests de caracterización del comportamiento actual antes del ciclo TDD.
-- La tarea es pruebas de carga o benchmarks: cargar `performance-baseline`.
-- La tarea es configurar CI/CD pipelines: cargar el skill de cloud correspondiente.
-- La tarea es fuzzing o testing de seguridad: cargar `threat-model-lite` y usar herramientas especializadas.
-
-## Propósito
-
-TDD no es "escribir tests después" ni "escribir tests antes por costumbre". Es
-un método de diseño donde los tests guían la API pública del código antes de
-que exista la implementación. El resultado es código que hace exactamente lo
-que los tests exigen — ni más, ni menos.
-
-## Cuándo activar
-
-- CONTEXT.md o PLAN.md indica que la fase requiere TDD
-- Se implementa lógica de negocio crítica (cálculos, validaciones, permisos)
-- El usuario pide explícitamente TDD
-- Se trabaja en un módulo con historial de bugs
-
----
-
-## Etapa opcional previa: Gherkin (BDD) y gate de mutación
-
-Dos extensiones opt-in del ciclo, ambas con guía completa en recursos:
-
-- **Antes del ciclo** — si la fase tiene criterios de aceptación de negocio,
-  convertirlos en escenarios Given–When–Then validados por el usuario ANTES de
-  implementar; cada escenario es el test RED de su criterio. Guía, runners por
-  stack y anti-patrones en [recursos/gherkin-bdd.md](recursos/gherkin-bdd.md).
-- **Después del ciclo** — en módulos críticos, verificar la calidad de los
-  asserts con mutation testing incremental sobre el diff:
-  `Skill("calidad-mutation-testing")`. La cobertura mide ejecución; los
-  mutantes sobrevivientes miden si los tests detectarían un bug.
-
-## El ciclo fundamental RED → GREEN → REFACTOR
-
-### Fase RED — El test debe fallar por la razón correcta
-
-**Paso 1**: Escribir el test que describe el comportamiento esperado.
-
-```python
-# RED: Este test falla porque calcular_descuento no existe todavía
-def test_descuento_cliente_premium_es_15_porciento():
-    cliente = ClienteFactory(tipo="premium")
-    resultado = calcular_descuento(cliente, monto=100.0)
-    assert resultado == 15.0
-```
-
-**Verificar que el test falla BIEN**:
-- Falla con `NameError` o `ImportError` si la función no existe: CORRECTO
-- Falla con `AssertionError` si el comportamiento es incorrecto: CORRECTO
-- Falla con `TypeError` si la firma es incorrecta: CORRECTO
-- Pasa sin que exista implementación: SEÑAL DE ALARMA — el test no prueba nada
-
-**NUNCA avanzar a GREEN si el test pasa en RED.**
-
-#### Evidencia RED en telemetría (gate G2 — proyectos con SWL)
-
-El RED debe dejar rastro verificable (cierra F-TDD-6: "TDD declarativo sin
-evidencia"). En proyectos con `.planning/`, registrar la corrida en
-`hooks/lib/loop-telemetry.js` ANTES de pasar a GREEN:
-
-```bash
-# Una vez por fase/tarea — abre la corrida
-node -e "const lt=require('./hooks/lib/loop-telemetry');const r=lt.iniciarCorrida({tipo:'tdd',direccion:'lower_is_better',config:{fase:'0N',tarea:'T-NN'}});console.log(r.dir)"
-
-# Al confirmar el RED — métrica = número de tests fallando, descripción = fallo exacto
-node -e "const lt=require('./hooks/lib/loop-telemetry');lt.registrarIteracion('<dir>',{iteracion:0,metrica:N,delta:0,estado:'baseline',descripcion:'RED T-NN: <error textual del runner>'})"
-
-# Al llegar a GREEN
-node -e "const lt=require('./hooks/lib/loop-telemetry');lt.registrarIteracion('<dir>',{iteracion:1,metrica:0,delta:-N,estado:'keep',descripcion:'GREEN T-NN: suite verde'})"
-```
-
-`hooks/tdd-gate.js` (warn-only, ADR-0035) busca la fila RED en
-`.planning/loops/tdd-*/iteraciones.tsv` al commitear un feature con tests; sin
-evidencia emite nudge `tdd-red-evidence`. Sin `.planning/` no aplica.
-
-#### Marker de trazabilidad REQ en tests (proyectos con REQ-IDs)
-
-Cuando la fase tiene criterios `REQ-NN` en el CONTEXTO, cada test que verifica un
-criterio lleva el marker en comentario — `scripts/verificar-trazabilidad.js` lo usa
-para cerrar la cadena REQ→T→commit→test:
-
-```python
-def test_descuento_cliente_premium():
-    # verifica: REQ-03
-    ...
-```
-
-```javascript
-test('descuento cliente premium', () => {
-  // verifica: REQ-03
-  ...
-});
-```
-
-### Fase GREEN — Implementación mínima
-
-**Regla de oro**: Implementar solo lo que hace pasar el test. Nada más.
-
-```python
-# GREEN: Implementación mínima que hace pasar el test
-def calcular_descuento(cliente: Cliente, monto: float) -> float:
-    if cliente.tipo == "premium":
-        return monto * 0.15
-    return 0.0
-```
-
-**Anti-patrón GREEN**: implementar todos los casos de una vez sin tests que los
-exijan. Si no hay un test para clientes "gold", no implementes el descuento gold.
-
-**Verificar**: `pytest -v test_descuentos.py` pasa con el test nuevo.
-
-### Fase REFACTOR — Limpieza sin cambiar comportamiento
-
-**Qué refactorizar en esta fase**:
-- Nombres de variables o funciones poco claros
-- Duplicación de lógica (si ya existe en otro test)
-- Magic numbers que deberían ser constantes
-- Estructura de código que anticipa el próximo test
-
-```python
-# REFACTOR: Extraer constante y mejorar legibilidad
-DESCUENTO_POR_TIPO = {
-    "premium": 0.15,
-    "gold": 0.20,
-    "standard": 0.0,
-}
-
-def calcular_descuento(cliente: Cliente, monto: float) -> float:
-    tasa = DESCUENTO_POR_TIPO.get(cliente.tipo, 0.0)
-    return monto * tasa
-```
-
-**Verificar**: todos los tests siguen pasando después del refactor.
-
----
-
-## Tests de frontera (boundary tests)
-
-Para toda función que procesa datos, escribir tests de:
-
-| Tipo de frontera | Ejemplo |
-|----------------|---------|
-| Valor cero | `monto=0.0` |
-| Valor negativo | `monto=-100.0` |
-| Valor máximo | `monto=999_999_999.99` |
-| String vacío | `nombre=""` |
-| None / null | `cliente=None` |
-| Lista vacía | `items=[]` |
-| Un solo elemento | `items=[item]` |
-| Muchos elementos | `items=lista_de_10000` |
-| Valor fuera de dominio | `tipo="inexistente"` |
-| Caracteres especiales | `nombre="<script>alert(1)</script>"` |
-
----
-
-## Factories y Fixtures
-
-### Factories (para datos de test)
-
-Las factories crean objetos con valores válidos por defecto. Los tests solo
-sobreescriben lo que importa para ese test específico.
-
-**Python con factory_boy**:
-```python
-import factory
-from myapp.models import Cliente, Pedido
-
-class ClienteFactory(factory.Factory):
-    class Meta:
-        model = Cliente
-
-    id = factory.Sequence(lambda n: f"cliente-{n}")
-    nombre = factory.Faker("name", locale="es_MX")
-    email = factory.Faker("email")
-    tipo = "standard"  # default explícito
-    activo = True
-
-# Uso en test
-def test_descuento_premium():
-    # Solo especificar lo que importa para este test
-    cliente = ClienteFactory(tipo="premium")
-    assert calcular_descuento(cliente, 100.0) == 15.0
-```
-
-**TypeScript con factory functions**:
-```typescript
-// factories/user.factory.ts
-export const createUser = (overrides: Partial<User> = {}): User => ({
-  id: 'user-1',
-  name: 'Test User',
-  email: 'test@example.com',
-  role: 'standard',
-  active: true,
-  ...overrides,
-});
-
-// Uso en test
-it('should show admin panel for admin users', () => {
-  const user = createUser({ role: 'admin' });
-  // ...
-});
-```
-
-### Fixtures (para estado persistente)
-
-```python
-# conftest.py
-import pytest
-from sqlalchemy.ext.asyncio import AsyncSession
-
-@pytest.fixture
-async def db_session():
-    """Sesión de BD en transacción que hace rollback al terminar."""
-    async with AsyncSessionLocal() as session:
-        async with session.begin():
-            yield session
-            await session.rollback()
-
-@pytest.fixture
-async def cliente_premium(db_session: AsyncSession):
-    """Cliente premium persistido en BD de test."""
-    cliente = ClienteFactory.build(tipo="premium")
-    db_session.add(cliente)
-    await db_session.flush()
-    return cliente
-```
-
----
-
-## TDD por tipo de código
-
-### Services (lógica de negocio)
-
-```python
-# Orden de tests para un service nuevo:
-# 1. Caso feliz principal
-# 2. Validaciones de input inválido
-# 3. Casos de borde del dominio
-# 4. Interacciones con dependencias (mocks)
-
-@pytest.mark.asyncio
-async def test_crear_pedido_valida_stock_disponible():
-    producto = ProductoFactory(stock=5)
-    with pytest.raises(StockInsuficienteError):
-        await PedidoService.crear(producto_id=producto.id, cantidad=10)
-```
-
-### Endpoints FastAPI
-
-```python
-# Usar TestClient de FastAPI
-from fastapi.testclient import TestClient
-
-def test_endpoint_requiere_autenticacion():
-    response = client.get("/api/v1/pedidos")
-    assert response.status_code == 401
-
-def test_endpoint_retorna_solo_pedidos_del_usuario(cliente_autenticado):
-    pedido_propio = PedidoFactory(usuario_id=cliente_autenticado.id)
-    pedido_ajeno = PedidoFactory(usuario_id="otro-usuario")
-
-    response = cliente_autenticado.get("/api/v1/pedidos")
-    ids = [p["id"] for p in response.json()["items"]]
-
-    assert pedido_propio.id in ids
-    assert pedido_ajeno.id not in ids  # IDOR check
-```
-
-### Componentes Angular
-
-```typescript
-// Usar TestBed + ComponentHarness
-describe('PedidosComponent', () => {
-  it('should display empty state when no orders exist', async () => {
-    const mockService = { getPedidos: () => of({ items: [], total: 0 }) };
-    await TestBed.configureTestingModule({
-      providers: [{ provide: PedidosService, useValue: mockService }]
-    }).compileComponents();
-
-    const fixture = TestBed.createComponent(PedidosComponent);
-    fixture.detectChanges();
-
-    const emptyState = fixture.nativeElement.querySelector('[data-testid="empty-state"]');
-    expect(emptyState).toBeTruthy();
-  });
-});
-```
-
----
-
-## Cobertura mínima obligatoria
-
-| Tipo de módulo | Cobertura mínima |
-|---------------|-----------------|
-| Services (lógica crítica) | 90% |
-| Endpoints (API) | 85% |
-| Utilities / helpers | 95% |
-| Componentes Angular | 75% |
-| Modelos ORM | 70% |
-
-**Verificar** con reporte de cobertura antes de marcar tarea como completada:
-```bash
-pytest --cov=src/services --cov-fail-under=90
-```
-
----
-
-## Anti-patrones TDD a evitar
-
-| Anti-patrón | Descripción | Solución |
-|-------------|-------------|---------|
-| Test del mock | El test solo verifica que se llamó el mock, no el comportamiento real | Testear el efecto observable |
-| Test omnibus | Un solo test que verifica 10 cosas a la vez | Un test, un comportamiento |
-| Test frágil | Falla si cambias nombres internos sin cambiar comportamiento | Testear comportamiento, no implementación |
-| Fixture global | Un fixture que modifica estado global compartido entre tests | Fixtures con scope limitado, rollback |
-| Skip como solución | `@pytest.mark.skip` para tests que fallan | Arreglar el bug o eliminar el test |
-
----
-
-## Gotchas / Errores comunes no obvios
-
-**El ciclo TDD se rompe cuando el test en fase RED pasa sin implementación porque la función ya existe con otro nombre en el módulo y Python la importa silenciosamente desde un namespace diferente**: escribir `from app.services import calcular_descuento` en el test cuando `calcular_descuento` ya existe en `app.utils` (importada en `__init__.py`) hace que el test pase en RED sin error, invalidando el ciclo. Causa: los imports con `from app.services import *` en `__init__.py` pueden re-exportar funciones de submódulos, haciendo que el test encuentre una implementación inesperada. Fix: verificar con `python -c "from app.services import calcular_descuento; print(calcular_descuento.__module__)"` que el símbolo viene del módulo correcto. Usar imports explícitos en los tests (`from app.services.descuentos import calcular_descuento`) en lugar de imports de paquete.
-
-**`pytest.mark.asyncio` con `asyncio_mode = "auto"` en `pytest.ini` hace que fixtures síncronos que retornan coroutines sean llamados sin `await`, causando que el fixture entregue un objeto coroutine en lugar del valor esperado**: un fixture `def cliente_premium(db_session)` que retorna `ClienteFactory.build(tipo="premium")` funciona, pero si accidentalmente se define como `async def cliente_premium(db_session)` y se usa en un test síncrono, pytest lo trata como fixture síncrono y el test recibe el objeto coroutine. Causa: la mezcla de fixtures `async def` y `def` en el mismo `conftest.py` con `asyncio_mode = "auto"` puede crear comportamientos inesperados dependiendo de la versión de `pytest-asyncio`. Fix: en proyectos async, definir TODOS los fixtures relevantes como `async def` explícitamente y verificar que el test use `@pytest.mark.asyncio` o tenga el modo auto configurado correctamente.
-
-**La fase REFACTOR del ciclo TDD en componentes Angular introduce regresiones silenciosas cuando se extrae lógica a un `computed()` pero el template sigue usando la función directa que ahora devuelve `undefined`**: refactorizar `getTotal()` como método del componente hacia `total = computed(() => ...)` y olvidar actualizar el template de `{{ getTotal() }}` a `{{ total() }}` no genera error de compilación con Angular 17+; el template simplemente muestra `undefined`. Causa: Angular no verifica en tiempo de compilación que los métodos referenciados en templates existen en la clase si el template usa la sintaxis de interpolación sin type-checking estricto. Fix: activar `strictTemplates: true` en `tsconfig.app.json` para que el compilador de Angular valide que todas las referencias en templates corresponden a miembros públicos del componente. Ejecutar `ng build` antes de considerar el REFACTOR completo.
-
-**`db_session.rollback()` en el fixture de pytest-asyncio no deshace los datos insertados por `db.flush()` dentro de la función testeada cuando la sesión usa `autocommit=True` implícito por configuración del engine**: algunos proyectos configuran `AsyncEngine` con `isolation_level="AUTOCOMMIT"` para compatibilidad con operaciones DDL; en ese contexto, cada `flush()` hace commit inmediatamente y el `rollback()` del fixture no puede deshacer esos cambios. Causa: `AUTOCOMMIT` en PostgreSQL significa que no hay transacción activa que se pueda revertir. Fix: verificar que el engine de tests NO use `isolation_level="AUTOCOMMIT"` (la configuración debe ser solo para el engine de migraciones Alembic, no para el de la app). Para tests que necesitan AUTOCOMMIT por alguna razón, usar una BD de test separada que se trunca con `TRUNCATE ... RESTART IDENTITY CASCADE` en el teardown del fixture.
-
-**Reloj inyectable como parámetro `ahora` habilita tests deterministas sin `freezegun`, `jest.useFakeTimers()` ni `sinon.useFakeTimers()`** [PATRÓN VALIDADO en SWL Opción C webhook]: cuando una API depende del tiempo (rate-limit con bucket que se rellena, dedup con ventana de retención, cache con TTL, schedulers), recibir el timestamp por parámetro en lugar de llamar `Date.now()` internamente permite que los tests pasen 1000 segundos en 0 ms reales. Diseño: `metodo(arg1, arg2, ahora = Date.now())` — producción no cambia (llamadas siguen siendo `obj.consumir(1)`), tests pasan `ahora` explícito (`obj.consumir(1, T0 + 5000)`). Validado en 3 módulos esta sesión: `rate-limit-ip.js` (40+ tests bucket refill, capacidad, cleanup), `webhook-dedup.js` (ventana de retención, rotación idempotente), helpers internos de `webhook-server.js`. Ningún test usa `sleep`, ningún test es flaky, ningún test mockea `Date`. Aplicable a JS/TS y a Python (`def consumir(self, tokens, ahora=None)` con `ahora = ahora or datetime.now(UTC)` al inicio).
-
-```js
-// MAL — test no-determinista, requiere sleep o mock global
-class Bucket {
-  consumir(n) {
-    const ahora = Date.now();  // ← imposible de controlar desde el test
-    this._rellenar(ahora);
-    if (this.tokens >= n) { this.tokens -= n; return true; }
-    return false;
-  }
-}
-
-// BIEN — reloj inyectable, test determinista
-class Bucket {
-  consumir(n, ahora = Date.now()) {  // ← default en producción, inyectable en test
-    this._rellenar(ahora);
-    if (this.tokens >= n) { this.tokens -= n; return true; }
-    return false;
-  }
-}
-
-// En el test:
-const T0 = 1700000000000;
-const b = new Bucket(10, 1, T0);
-for (let i = 0; i < 10; i++) b.consumir(1, T0);   // saturar
-assert.equal(b.consumir(1, T0), false);            // sin refill aún
-assert.equal(b.consumir(5, T0 + 5000), true);      // 5 seg después: 5 tokens
-```
-
-Aplica también a tests de clock skew (tiempo retrocede por NTP): pasar `T0 - 1000` y validar que la lógica no rompe. Origen: rate-limit-ip.js + webhook-dedup.js sesión 2026-05-13.
-
-**Tests nombrados por feature (`test_emitir_factura_exitosa`) pierden poder regresivo; nombrados por causa raíz (`test_repository_no_usa_columna_inexistente_p_monto`) detectan regresiones específicas sin reproducción manual** [CONFIRMADO en SIGM Opción C F1.4]: cuando se descubre un bug por una causa raíz concreta (typo en nombre de columna SQL, omisión de `selectinload`, mock que devuelve dict en vez de objeto, schema obsoleto), el test de regresión que se escribe debe llevar el nombre de la causa, no del feature afectado. Caso real: durante F1.4 de SIGM, el repository de pagos referenciaba `p.monto` cuando la columna se llamaba `p.monto_pagado`; el test escrito como `test_repository_no_usa_columna_inexistente_p_monto` falló inmediatamente en la siguiente sesión cuando otro agente reintrodujo el typo, sin necesidad de reproducir el escenario de negocio (emitir cobro real, verificar respuesta). Causa: los nombres orientados a feature (`test_pago_exitoso`) son ambiguos sobre QUÉ falla — si el test falla, el desarrollador debe diagnosticar; los nombres orientados a causa raíz (`test_X_no_usa_Y`, `test_query_incluye_selectinload_Z`, `test_service_devuelve_dict_no_objeto`) son auto-diagnósticos. Fix: para cada bug que cueste >30 min diagnosticar, escribir UN test adicional cuyo nombre describa la condición técnica violada, no el escenario de negocio. Convención: `test_<componente>_<condicion_tecnica>` o `test_<componente>_no_<anti_patron>`. Estos tests son tu segunda línea de defensa contra regresiones de la misma causa raíz, complementarios a los tests de comportamiento.
-
-**`process.cwd()` cacheado al `require()` rompe tests con `process.chdir(sandbox)`** [PATRÓN GENÉRICO TESTING CLI]: scripts Node exportables que leen `process.cwd()` en el scope del módulo (al cargar) congelan el cwd al directorio de invocación. Los tests que crean sandboxes con `fs.mkdtempSync()` y luego `process.chdir(sandbox)` no afectan al cwd cacheado — el script sigue leyendo del cwd original y los assertions fallan con paths inesperados. Caso real (swl-ses `scripts/derivar-feature-list.js` 2026-05-15): la función `enriquecerDesdeFases(fases)` leía `const CWD = process.cwd()` calculado al `require()`; 2 tests con `process.chdir(sandbox)` retornaron `[]` en lugar de detectar el PLAN.md fixture. Causa: el constante se evaluó cuando el `node --test` cargó el módulo desde el cwd del proyecto, no desde el sandbox del test individual. Fix obligatorio: funciones exportables deben aceptar `cwd` como parámetro opcional con fallback dinámico (`function fn(args, opciones = {}) { const cwd = opciones.cwd || process.cwd(); ... }`). El código de producción no cambia (sin args extras), pero los tests pueden inyectar el cwd correcto. Aplica también a Python (`def fn(args, cwd: str | None = None): cwd = cwd or os.getcwd()`) y a cualquier lenguaje con tests que usen chdir.
-
-```js
-// MAL — cwd cacheado al require, tests con process.chdir() fallan
-const CWD = process.cwd();
-const PLANNING_DIR = path.join(CWD, '.planning');
-
-function enriquecerDesdeFases(fases) {
-  const archivos = fs.readdirSync(path.join(PLANNING_DIR, 'fases'));  // cwd congelado
-  // ...
-}
-
-// BIEN — cwd dinámico con parámetro opcional para tests
-function enriquecerDesdeFases(fases, opciones = {}) {
-  const cwd = opciones.cwd || process.cwd();  // recalcula al llamar
-  const archivos = fs.readdirSync(path.join(cwd, '.planning', 'fases'));
-  // ...
-}
-
-// En el test (usa setupSandboxes — regla tests-cleanup.md):
-const { setupSandboxes } = require('../_helpers/sandbox');
-const sandboxes = setupSandboxes('swl-test-');
-
-const sandbox = sandboxes.create();
-fs.mkdirSync(path.join(sandbox, '.planning', 'fases'), { recursive: true });
-// Opción A: pasar cwd explícito (recomendado)
-const r = enriquecerDesdeFases([], { cwd: sandbox });
-// Opción B: process.chdir() — solo funciona con cwd dinámico
-process.chdir(sandbox);
-const r2 = enriquecerDesdeFases([]);
-// Cleanup automático al final del archivo vía after() registrado por setupSandboxes.
-```
-
----
-
-## Gotcha: silenced tests por race condition sobre estado compartido
-
-### El anti-patrón
-
-```javascript
-// MAL — assertion condicional dentro de if que puede ser false por race
-const FLAG = path.join(os.tmpdir(), 'mi-app.json');
-
-test('flag sin contenido emite warning', () => {
-  borrarFlag();
-  const res = correrSubproceso();
-  if (fs.existsSync(FLAG)) {           // ← otro test paralelo creó el flag
-    assert.match(res.stdout, /WARN/);  // ← NUNCA se ejecuta si el if es false
-  }
-  // sin else → test PASA sin haber validado nada
-});
-
-// El test "verde" no significa "pasó" — significa "no falló ninguna assertion".
-// Si la assertion vive dentro de un `if (race)`, una race favorable la salta
-// y el test es vacío.
-```
-
-### Por qué pasa
-
-`node:test` paraleliza **archivos** `.test.js` por default (no tests dentro
-del mismo archivo). Si dos archivos tocan el mismo path único de filesystem
-(`/tmp/foo.json`, lockfiles, sockets), las operaciones se intercalan no
-deterministamente. Patrones típicos:
-
-- Archivo A: `borrarFlag()` → spawn subprocess → assert
-- Archivo B: spawn subprocess → `crearFlag()` durante A → assert de A condicionado falla
-
-### Patrones correctos
-
-**Patrón 1 — Aislamiento por path único** (recomendado):
-
-```javascript
-const { setupSandboxes } = require('../_helpers/sandbox');
-const sandboxes = setupSandboxes('swl-mi-app-test-');
-const env = { ...process.env };
-
-// Path único por test usando el helper canónico (regla tests-cleanup.md).
-// El cleanup es automático al final del archivo vía after() registrado.
-const dir = sandboxes.create();
-env.MI_APP_FLAG_PATH = path.join(dir, 'flag.json');
-
-const res = spawnSync('node', [BIN], { env, ... });
-
-// Ahora el assert es incondicional — el path es del test, no compartido
-assert.match(res.stdout, /WARN/);
-```
-
-Requiere que el SUT (System Under Test) honre una env var para override
-del path. Si no la honra, agregar el override es parte del fix.
-
-**Patrón 2 — Serialización forzada** (cuando el path es hardcoded):
-
-```bash
-# Forzar --test-concurrency=1 en la suite completa
-node --test --test-concurrency=1 tests/
-```
-
-Tradeoff: tests más lentos pero deterministas. Aceptable si el aislamiento
-no es factible (legacy code).
-
-**Patrón 3 — assertions incondicionales** con setup determinista:
-
-```javascript
-// MAL
-if (fs.existsSync(FLAG)) assert.match(...)
-
-// BIEN — setup garantiza la precondición, assertion no se salta
-escribirFlag({ ... });
-assert.ok(fs.existsSync(FLAG), 'precondición del test');  // ← assertion sobre el setup
-const res = correrSubproceso();
-assert.match(res.stdout, /WARN/);  // ← assertion incondicional sobre el resultado
-```
-
-### Anti-patrón: `if (X) assert(Y)` sin `else`
-
-```javascript
-// MAL — un test que pasa silenciosamente cuando X es false
-test('hace algo', () => {
-  const algo = obtenerAlgo();
-  if (algo) {                       // ← race u otra fuente de no-determinismo
-    assert.equal(algo.valor, 42);
-  }
-  // sin else → veredicto "pass" sin haber validado nada
-});
-
-// BIEN — el setup garantiza la precondición o el test falla explícito
-test('hace algo', () => {
-  const algo = obtenerAlgo();
-  assert.ok(algo, 'precondición: obtenerAlgo debe devolver valor');
-  assert.equal(algo.valor, 42);
-});
-```
-
-**Regla**: una assertion dentro de un `if` sin `else` es **un test que
-puede pasar sin validar nada**. Estos "silenced tests" son la peor clase
-de falsa cobertura: el reporter dice "pass" y nadie revisa el código
-hasta que un bug llega a producción.
-
-### Detección
-
-- Buscar `if (` dentro de cuerpos de `test(...)`/`it(...)` sin `else { fail() }`
-  o `else { assert(...) }` correspondiente.
-- Si el cuerpo del `if` contiene `assert.*`, considerarlo silenced test
-  hasta que se demuestre que el `if` no puede ser false en ningún escenario.
-
-### Origen
-
-Detectado en sesión 2026-05-16 del proyecto swl-ses (PR #30): tests del
-flag `swl-ses-update-check.json` compartido entre dos archivos `.test.js`
-paralelos. El test "sin flag → debe advertir" pasaba en CI cuando otro
-archivo creaba el flag, sin ejecutar ninguna assertion. Fix: env var
-`SWL_UPDATE_FLAG_PATH` para aislamiento + assertions incondicionales.
-
----
-
-## Tests E2E de CLIs interactivos sin PTY real
-
-### El problema
-
-Probar un CLI interactivo (TUI con `readline`, prompts, keypress events,
-`process.stdin.isTTY`) en CI requiere normalmente un **pseudo-terminal
-emulado** (PTY) — usualmente vía `node-pty`, una dependencia **nativa** que:
-
-- Requiere compilación de extensiones C++ al instalar (puede fallar en
-  contenedores minimal o en Windows sin Visual Studio Build Tools).
-- Agrega ~5 MB al `node_modules` por imagen.
-- Hace que el test suite no corra en `npm test` sin setup extra.
-
-Para CLIs interactivos donde no se necesita probar **el comportamiento
-real del terminal** (escape codes, redibujado, scroll), sino solo la
-**lógica del wizard** (¿qué pasa si el usuario presiona Esc en el paso 3?,
-¿qué resuelve el promise tras Enter con default?), un harness TTY mockeado
-cubre ~90% de los casos sin dep nativa.
-
-### Patrón del harness
-
-```javascript
-// tests/harness-tty.js
-'use strict';
-
-const readline = require('readline');
-
-function crearHarness() {
-  // 1. Capturar estado original para restauración
-  const stdoutOriginal = process.stdout.write.bind(process.stdout);
-  const isTtyStdoutOriginal = process.stdout.isTTY;
-  const isTtyStdinOriginal = process.stdin.isTTY;
-  const setRawModeOriginal = process.stdin.setRawMode
-    ? process.stdin.setRawMode.bind(process.stdin) : null;
-  const emitKeypressOriginal = readline.emitKeypressEvents;
-
-  let capturado = '';
-  let listenersKeypress = [];
-
-  // 2. Forzar TTY antes de cargar módulos UI (que evalúan ES_TTY al require)
-  Object.defineProperty(process.stdout, 'isTTY', { value: true, configurable: true });
-  Object.defineProperty(process.stdin,  'isTTY', { value: true, configurable: true });
-
-  // 3. Capturar stdout en string buffer
-  process.stdout.write = (chunk) => {
-    capturado += typeof chunk === 'string' ? chunk : chunk.toString();
-    return true;
-  };
-
-  // 4. Mockear setRawMode/resume/pause como no-op (evita tomar control del terminal de test)
-  process.stdin.setRawMode = () => process.stdin;
-  process.stdin.resume = () => process.stdin;
-  process.stdin.pause = () => process.stdin;
-
-  // 5. Interceptar registros de 'keypress' para poder emitirlos a mano
-  const onListenerOriginal = process.stdin.on.bind(process.stdin);
-  process.stdin.on = (evento, listener) => {
-    if (evento === 'keypress') listenersKeypress.push(listener);
-    return onListenerOriginal(evento, listener);
-  };
-
-  // 6. Mockear readline.emitKeypressEvents (no necesita stdin real)
-  readline.emitKeypressEvents = (stream) => stream;
-
-  // 7. Limpiar require cache de módulos UI para que se evalúen con TTY=true
-  delete require.cache[require.resolve('../scripts/tui/lib/render')];
-
-  function cargarUI() {
-    return require('../scripts/tui/lib/render');
-  }
-
-  // 8. Emitir keypress programáticamente
-  function tecla(nombre, extras = {}) {
-    const key = { name: nombre, ctrl: false, meta: false, shift: false, ...extras };
-    const str = nombre.length === 1 ? nombre : '';
-    for (const listener of [...listenersKeypress]) {
-      try { listener(str, key); } catch (_) { /* swallow */ }
-    }
-  }
-
-  // 9. Esperar N ticks del event loop para promesas internas
-  function esperarTicks(n = 1) {
-    let p = Promise.resolve();
-    for (let i = 0; i < n; i++) p = p.then(() => undefined);
-    return p;
-  }
-
-  function captura(opts = {}) {
-    const valor = capturado;
-    if (opts.limpiar) capturado = '';
-    return valor;
-  }
-
-  function restaurar() {
-    Object.defineProperty(process.stdout, 'isTTY', { value: isTtyStdoutOriginal, configurable: true });
-    Object.defineProperty(process.stdin,  'isTTY', { value: isTtyStdinOriginal,  configurable: true });
-    process.stdout.write = stdoutOriginal;
-    if (setRawModeOriginal) process.stdin.setRawMode = setRawModeOriginal;
-    process.stdin.on = onListenerOriginal;
-    readline.emitKeypressEvents = emitKeypressOriginal;
-    listenersKeypress = [];
-    // Limpiar require cache para no contaminar otros tests
-    delete require.cache[require.resolve('../scripts/tui/lib/render')];
-  }
-
-  return { cargarUI, tecla, esperarTicks, captura, restaurar };
-}
-
-module.exports = { crearHarness };
-```
-
-### Uso típico
-
-```javascript
-const test = require('node:test');
-const assert = require('node:assert/strict');
-const { crearHarness } = require('./harness-tty');
-
-test('preguntarSiNo con harness: Enter resuelve con default true', async () => {
-  const h = crearHarness();
-  try {
-    const ui = h.cargarUI();
-    const promesa = ui.preguntarSiNo('test prompt', true);
-
-    await h.esperarTicks(2);
-    h.tecla('return');
-
-    const timeout = new Promise((_, reject) =>
-      setTimeout(() => reject(new Error('no resolvió en 500ms')), 500));
-
-    const r = await Promise.race([promesa, timeout]).catch(() => null);
-    // r === true si el harness simuló bien; null si readline real bloquea
-    // (caso esperado en Windows sin PTY real; documentar limitación)
-  } finally {
-    h.restaurar();
-  }
-});
-```
-
-### Reglas operativas
-
-- **`restaurar()` en `finally`**: el harness modifica state global
-  (process.stdout, process.stdin, readline, require.cache). Si un test
-  no restaura, contamina los siguientes.
-- **Test de captura como smoke**: agregar un test "harness captura stdout"
-  que valida que `process.stdout.write('hola')` aparece en `captura()`.
-  Si falla, el harness está roto antes de testear el SUT.
-- **Test "tecla() es no-op sin listeners"**: validar que emitir keypress
-  cuando nadie escucha NO rompe el harness ni propaga errores.
-- **Limitación reconocida**: si `readline.createInterface()` real toma
-  control de stdin (en Windows con Git Bash sin PTY), el callback de
-  `rl.question()` no se invoca aunque el harness emita teclas. Usar
-  `Promise.race([promesa, timeout])` para que el test no cuelgue —
-  el test marca limitación, no falla.
-
-### Cuándo NO usar este patrón
-
-- Cuando necesitas probar **redibujado real del terminal** (alt screen
-  buffer, escape codes complejos, scrollback). Ahí sí necesitas PTY real
-  via `node-pty` o test manual.
-- Cuando el SUT depende de **timing real del teclado** (input rates,
-  paste detection). El mock no replica latencia.
-- Para CLIs sin lógica de control de flujo (solo `console.log` lineal) —
-  ahí basta capturar stdout sin mockear TTY.
-
-### Origen
-
-Aplicado en swl-ses v1.6.0 (`tests/scripts/tui/harness-tty.js`, ~180 LOC).
-Validó el TUI completo de 5 fases sin instalar `node-pty`. Limitación
-documentada: 1 test E2E "preguntarSiNo con harness" marca timeout en
-Windows + Node 22+ porque readline real bloquea pese a stdin mockeado —
-el harness emite la limitación sin fallar.
+---
+name: tdd-workflow
+description: Flujo completo de Test-Driven Development. Ciclo RED (el test falla) → GREEN (implementación mínima) → REFACTOR (limpieza). Incluye cobertura mínima obligatoria, tests de frontera, factories, fixtures y estrategias para diferentes tipos de código (APIs, services, componentes Angular).
+version: "1.2.1"
+evolved: true
+evolved-from: "1.1.0"
+evolved-at: "2026-06-11"
+evolved-by: "fase-10-slice-2"
+evolved-note: "v1.2.0: sección 'Evidencia RED en telemetría' (gate G2, ADR-0035, cierra F-TDD-6) — registro de corridas tdd-* en loop-telemetry. v1.0.5: gotcha 'Tests E2E de CLIs interactivos sin PTY real'. Origen M2 sesión 2026-05-16. v1.0.4: silenced tests por race en path único compartido. v1.0.3: gotcha cwd cacheado al require()."
+herramientasPermitidas: [Read, Bash]
+evolvable: true  # default para skill estandar
+exclusiones:
+  - "No cargar para escribir tests de regresión sobre código legacy sin suite existente — en código legacy sin tests, comenzar con caracterización de comportamiento actual antes del ciclo TDD."
+  - "No cargar para pruebas de carga o performance testing — para benchmarks y load testing cargar `performance-baseline`."
+  - "No cargar para configurar pipelines de CI/CD o runners de tests en GitHub Actions / GitLab CI — para configuración de CI cargar el skill de cloud correspondiente."
+  - "No cargar para pruebas de seguridad o fuzzing automático — para testing de seguridad cargar `threat-model-lite` y usar herramientas especializadas (Bandit, OWASP ZAP)."
+---
+# Habilidad: TDD Workflow Completo
+
+## Cuándo NO cargar
+
+- La tarea es añadir tests a código legacy sin suite existente: comenzar con tests de caracterización del comportamiento actual antes del ciclo TDD.
+- La tarea es pruebas de carga o benchmarks: cargar `performance-baseline`.
+- La tarea es configurar CI/CD pipelines: cargar el skill de cloud correspondiente.
+- La tarea es fuzzing o testing de seguridad: cargar `threat-model-lite` y usar herramientas especializadas.
+
+## Propósito
+
+TDD no es "escribir tests después" ni "escribir tests antes por costumbre". Es
+un método de diseño donde los tests guían la API pública del código antes de
+que exista la implementación. El resultado es código que hace exactamente lo
+que los tests exigen — ni más, ni menos.
+
+## Cuándo activar
+
+- CONTEXT.md o PLAN.md indica que la fase requiere TDD
+- Se implementa lógica de negocio crítica (cálculos, validaciones, permisos)
+- El usuario pide explícitamente TDD
+- Se trabaja en un módulo con historial de bugs
+
+---
+
+## Etapa opcional previa: Gherkin (BDD) y gate de mutación
+
+Dos extensiones opt-in del ciclo, ambas con guía completa en recursos:
+
+- **Antes del ciclo** — si la fase tiene criterios de aceptación de negocio,
+  convertirlos en escenarios Given–When–Then validados por el usuario ANTES de
+  implementar; cada escenario es el test RED de su criterio. Guía, runners por
+  stack y anti-patrones en [recursos/gherkin-bdd.md](recursos/gherkin-bdd.md).
+- **Después del ciclo** — en módulos críticos, verificar la calidad de los
+  asserts con mutation testing incremental sobre el diff:
+  `Skill("calidad-mutation-testing")`. La cobertura mide ejecución; los
+  mutantes sobrevivientes miden si los tests detectarían un bug.
+
+## El ciclo fundamental RED → GREEN → REFACTOR
+
+### Fase RED — El test debe fallar por la razón correcta
+
+**Paso 1**: Escribir el test que describe el comportamiento esperado.
+
+```python
+# RED: Este test falla porque calcular_descuento no existe todavía
+def test_descuento_cliente_premium_es_15_porciento():
+    cliente = ClienteFactory(tipo="premium")
+    resultado = calcular_descuento(cliente, monto=100.0)
+    assert resultado == 15.0
+```
+
+**Verificar que el test falla BIEN**:
+- Falla con `NameError` o `ImportError` si la función no existe: CORRECTO
+- Falla con `AssertionError` si el comportamiento es incorrecto: CORRECTO
+- Falla con `TypeError` si la firma es incorrecta: CORRECTO
+- Pasa sin que exista implementación: SEÑAL DE ALARMA — el test no prueba nada
+
+**NUNCA avanzar a GREEN si el test pasa en RED.**
+
+#### Evidencia RED en telemetría (gate G2 — proyectos con SWL)
+
+El RED debe dejar rastro verificable (cierra F-TDD-6: "TDD declarativo sin
+evidencia"). En proyectos con `.planning/`, registrar la corrida en
+`hooks/lib/loop-telemetry.js` ANTES de pasar a GREEN:
+
+```bash
+# Una vez por fase/tarea — abre la corrida
+node -e "const lt=require('./hooks/lib/loop-telemetry');const r=lt.iniciarCorrida({tipo:'tdd',direccion:'lower_is_better',config:{fase:'0N',tarea:'T-NN'}});console.log(r.dir)"
+
+# Al confirmar el RED — métrica = número de tests fallando, descripción = fallo exacto
+node -e "const lt=require('./hooks/lib/loop-telemetry');lt.registrarIteracion('<dir>',{iteracion:0,metrica:N,delta:0,estado:'baseline',descripcion:'RED T-NN: <error textual del runner>'})"
+
+# Al llegar a GREEN
+node -e "const lt=require('./hooks/lib/loop-telemetry');lt.registrarIteracion('<dir>',{iteracion:1,metrica:0,delta:-N,estado:'keep',descripcion:'GREEN T-NN: suite verde'})"
+```
+
+`hooks/tdd-gate.js` (warn-only, ADR-0035) busca la fila RED en
+`.planning/loops/tdd-*/iteraciones.tsv` al commitear un feature con tests; sin
+evidencia emite nudge `tdd-red-evidence`. Sin `.planning/` no aplica.
+
+#### Marker de trazabilidad REQ en tests (proyectos con REQ-IDs)
+
+Cuando la fase tiene criterios `REQ-NN` (fases 01-11) o `REQ-<fase>-NN`
+(namespaceados, fases ≥12 — DT-IDS-NAMESPACE) en el CONTEXTO, cada test que
+verifica un criterio lleva el marker en comentario —
+`scripts/verificar-trazabilidad.js` lo usa para cerrar la cadena
+REQ→T→commit→test (reconoce ambos formatos):
+
+```python
+def test_descuento_cliente_premium():
+    # verifica: REQ-12-03
+    ...
+```
+
+```javascript
+test('descuento cliente premium', () => {
+  // verifica: REQ-12-03
+  ...
+});
+```
+
+### Fase GREEN — Implementación mínima
+
+**Regla de oro**: Implementar solo lo que hace pasar el test. Nada más.
+
+```python
+# GREEN: Implementación mínima que hace pasar el test
+def calcular_descuento(cliente: Cliente, monto: float) -> float:
+    if cliente.tipo == "premium":
+        return monto * 0.15
+    return 0.0
+```
+
+**Anti-patrón GREEN**: implementar todos los casos de una vez sin tests que los
+exijan. Si no hay un test para clientes "gold", no implementes el descuento gold.
+
+**Verificar**: `pytest -v test_descuentos.py` pasa con el test nuevo.
+
+### Fase REFACTOR — Limpieza sin cambiar comportamiento
+
+**Qué refactorizar en esta fase**:
+- Nombres de variables o funciones poco claros
+- Duplicación de lógica (si ya existe en otro test)
+- Magic numbers que deberían ser constantes
+- Estructura de código que anticipa el próximo test
+
+```python
+# REFACTOR: Extraer constante y mejorar legibilidad
+DESCUENTO_POR_TIPO = {
+    "premium": 0.15,
+    "gold": 0.20,
+    "standard": 0.0,
+}
+
+def calcular_descuento(cliente: Cliente, monto: float) -> float:
+    tasa = DESCUENTO_POR_TIPO.get(cliente.tipo, 0.0)
+    return monto * tasa
+```
+
+**Verificar**: todos los tests siguen pasando después del refactor.
+
+---
+
+## Tests de frontera (boundary tests)
+
+Para toda función que procesa datos, escribir tests de:
+
+| Tipo de frontera | Ejemplo |
+|----------------|---------|
+| Valor cero | `monto=0.0` |
+| Valor negativo | `monto=-100.0` |
+| Valor máximo | `monto=999_999_999.99` |
+| String vacío | `nombre=""` |
+| None / null | `cliente=None` |
+| Lista vacía | `items=[]` |
+| Un solo elemento | `items=[item]` |
+| Muchos elementos | `items=lista_de_10000` |
+| Valor fuera de dominio | `tipo="inexistente"` |
+| Caracteres especiales | `nombre="<script>alert(1)</script>"` |
+
+---
+
+## Factories y Fixtures
+
+### Factories (para datos de test)
+
+Las factories crean objetos con valores válidos por defecto. Los tests solo
+sobreescriben lo que importa para ese test específico.
+
+**Python con factory_boy**:
+```python
+import factory
+from myapp.models import Cliente, Pedido
+
+class ClienteFactory(factory.Factory):
+    class Meta:
+        model = Cliente
+
+    id = factory.Sequence(lambda n: f"cliente-{n}")
+    nombre = factory.Faker("name", locale="es_MX")
+    email = factory.Faker("email")
+    tipo = "standard"  # default explícito
+    activo = True
+
+# Uso en test
+def test_descuento_premium():
+    # Solo especificar lo que importa para este test
+    cliente = ClienteFactory(tipo="premium")
+    assert calcular_descuento(cliente, 100.0) == 15.0
+```
+
+**TypeScript con factory functions**:
+```typescript
+// factories/user.factory.ts
+export const createUser = (overrides: Partial<User> = {}): User => ({
+  id: 'user-1',
+  name: 'Test User',
+  email: 'test@example.com',
+  role: 'standard',
+  active: true,
+  ...overrides,
+});
+
+// Uso en test
+it('should show admin panel for admin users', () => {
+  const user = createUser({ role: 'admin' });
+  // ...
+});
+```
+
+### Fixtures (para estado persistente)
+
+```python
+# conftest.py
+import pytest
+from sqlalchemy.ext.asyncio import AsyncSession
+
+@pytest.fixture
+async def db_session():
+    """Sesión de BD en transacción que hace rollback al terminar."""
+    async with AsyncSessionLocal() as session:
+        async with session.begin():
+            yield session
+            await session.rollback()
+
+@pytest.fixture
+async def cliente_premium(db_session: AsyncSession):
+    """Cliente premium persistido en BD de test."""
+    cliente = ClienteFactory.build(tipo="premium")
+    db_session.add(cliente)
+    await db_session.flush()
+    return cliente
+```
+
+---
+
+## TDD por tipo de código
+
+### Services (lógica de negocio)
+
+```python
+# Orden de tests para un service nuevo:
+# 1. Caso feliz principal
+# 2. Validaciones de input inválido
+# 3. Casos de borde del dominio
+# 4. Interacciones con dependencias (mocks)
+
+@pytest.mark.asyncio
+async def test_crear_pedido_valida_stock_disponible():
+    producto = ProductoFactory(stock=5)
+    with pytest.raises(StockInsuficienteError):
+        await PedidoService.crear(producto_id=producto.id, cantidad=10)
+```
+
+### Endpoints FastAPI
+
+```python
+# Usar TestClient de FastAPI
+from fastapi.testclient import TestClient
+
+def test_endpoint_requiere_autenticacion():
+    response = client.get("/api/v1/pedidos")
+    assert response.status_code == 401
+
+def test_endpoint_retorna_solo_pedidos_del_usuario(cliente_autenticado):
+    pedido_propio = PedidoFactory(usuario_id=cliente_autenticado.id)
+    pedido_ajeno = PedidoFactory(usuario_id="otro-usuario")
+
+    response = cliente_autenticado.get("/api/v1/pedidos")
+    ids = [p["id"] for p in response.json()["items"]]
+
+    assert pedido_propio.id in ids
+    assert pedido_ajeno.id not in ids  # IDOR check
+```
+
+### Componentes Angular
+
+```typescript
+// Usar TestBed + ComponentHarness
+describe('PedidosComponent', () => {
+  it('should display empty state when no orders exist', async () => {
+    const mockService = { getPedidos: () => of({ items: [], total: 0 }) };
+    await TestBed.configureTestingModule({
+      providers: [{ provide: PedidosService, useValue: mockService }]
+    }).compileComponents();
+
+    const fixture = TestBed.createComponent(PedidosComponent);
+    fixture.detectChanges();
+
+    const emptyState = fixture.nativeElement.querySelector('[data-testid="empty-state"]');
+    expect(emptyState).toBeTruthy();
+  });
+});
+```
+
+---
+
+## Cobertura mínima obligatoria
+
+| Tipo de módulo | Cobertura mínima |
+|---------------|-----------------|
+| Services (lógica crítica) | 90% |
+| Endpoints (API) | 85% |
+| Utilities / helpers | 95% |
+| Componentes Angular | 75% |
+| Modelos ORM | 70% |
+
+**Verificar** con reporte de cobertura antes de marcar tarea como completada:
+```bash
+pytest --cov=src/services --cov-fail-under=90
+```
+
+---
+
+## Anti-patrones TDD a evitar
+
+| Anti-patrón | Descripción | Solución |
+|-------------|-------------|---------|
+| Test del mock | El test solo verifica que se llamó el mock, no el comportamiento real | Testear el efecto observable |
+| Test omnibus | Un solo test que verifica 10 cosas a la vez | Un test, un comportamiento |
+| Test frágil | Falla si cambias nombres internos sin cambiar comportamiento | Testear comportamiento, no implementación |
+| Fixture global | Un fixture que modifica estado global compartido entre tests | Fixtures con scope limitado, rollback |
+| Skip como solución | `@pytest.mark.skip` para tests que fallan | Arreglar el bug o eliminar el test |
+
+---
+
+## Gotchas / Errores comunes no obvios
+
+**El ciclo TDD se rompe cuando el test en fase RED pasa sin implementación porque la función ya existe con otro nombre en el módulo y Python la importa silenciosamente desde un namespace diferente**: escribir `from app.services import calcular_descuento` en el test cuando `calcular_descuento` ya existe en `app.utils` (importada en `__init__.py`) hace que el test pase en RED sin error, invalidando el ciclo. Causa: los imports con `from app.services import *` en `__init__.py` pueden re-exportar funciones de submódulos, haciendo que el test encuentre una implementación inesperada. Fix: verificar con `python -c "from app.services import calcular_descuento; print(calcular_descuento.__module__)"` que el símbolo viene del módulo correcto. Usar imports explícitos en los tests (`from app.services.descuentos import calcular_descuento`) en lugar de imports de paquete.
+
+**`pytest.mark.asyncio` con `asyncio_mode = "auto"` en `pytest.ini` hace que fixtures síncronos que retornan coroutines sean llamados sin `await`, causando que el fixture entregue un objeto coroutine en lugar del valor esperado**: un fixture `def cliente_premium(db_session)` que retorna `ClienteFactory.build(tipo="premium")` funciona, pero si accidentalmente se define como `async def cliente_premium(db_session)` y se usa en un test síncrono, pytest lo trata como fixture síncrono y el test recibe el objeto coroutine. Causa: la mezcla de fixtures `async def` y `def` en el mismo `conftest.py` con `asyncio_mode = "auto"` puede crear comportamientos inesperados dependiendo de la versión de `pytest-asyncio`. Fix: en proyectos async, definir TODOS los fixtures relevantes como `async def` explícitamente y verificar que el test use `@pytest.mark.asyncio` o tenga el modo auto configurado correctamente.
+
+**La fase REFACTOR del ciclo TDD en componentes Angular introduce regresiones silenciosas cuando se extrae lógica a un `computed()` pero el template sigue usando la función directa que ahora devuelve `undefined`**: refactorizar `getTotal()` como método del componente hacia `total = computed(() => ...)` y olvidar actualizar el template de `{{ getTotal() }}` a `{{ total() }}` no genera error de compilación con Angular 17+; el template simplemente muestra `undefined`. Causa: Angular no verifica en tiempo de compilación que los métodos referenciados en templates existen en la clase si el template usa la sintaxis de interpolación sin type-checking estricto. Fix: activar `strictTemplates: true` en `tsconfig.app.json` para que el compilador de Angular valide que todas las referencias en templates corresponden a miembros públicos del componente. Ejecutar `ng build` antes de considerar el REFACTOR completo.
+
+**`db_session.rollback()` en el fixture de pytest-asyncio no deshace los datos insertados por `db.flush()` dentro de la función testeada cuando la sesión usa `autocommit=True` implícito por configuración del engine**: algunos proyectos configuran `AsyncEngine` con `isolation_level="AUTOCOMMIT"` para compatibilidad con operaciones DDL; en ese contexto, cada `flush()` hace commit inmediatamente y el `rollback()` del fixture no puede deshacer esos cambios. Causa: `AUTOCOMMIT` en PostgreSQL significa que no hay transacción activa que se pueda revertir. Fix: verificar que el engine de tests NO use `isolation_level="AUTOCOMMIT"` (la configuración debe ser solo para el engine de migraciones Alembic, no para el de la app). Para tests que necesitan AUTOCOMMIT por alguna razón, usar una BD de test separada que se trunca con `TRUNCATE ... RESTART IDENTITY CASCADE` en el teardown del fixture.
+
+**Reloj inyectable como parámetro `ahora` habilita tests deterministas sin `freezegun`, `jest.useFakeTimers()` ni `sinon.useFakeTimers()`** [PATRÓN VALIDADO en SWL Opción C webhook]: cuando una API depende del tiempo (rate-limit con bucket que se rellena, dedup con ventana de retención, cache con TTL, schedulers), recibir el timestamp por parámetro en lugar de llamar `Date.now()` internamente permite que los tests pasen 1000 segundos en 0 ms reales. Diseño: `metodo(arg1, arg2, ahora = Date.now())` — producción no cambia (llamadas siguen siendo `obj.consumir(1)`), tests pasan `ahora` explícito (`obj.consumir(1, T0 + 5000)`). Validado en 3 módulos esta sesión: `rate-limit-ip.js` (40+ tests bucket refill, capacidad, cleanup), `webhook-dedup.js` (ventana de retención, rotación idempotente), helpers internos de `webhook-server.js`. Ningún test usa `sleep`, ningún test es flaky, ningún test mockea `Date`. Aplicable a JS/TS y a Python (`def consumir(self, tokens, ahora=None)` con `ahora = ahora or datetime.now(UTC)` al inicio).
+
+```js
+// MAL — test no-determinista, requiere sleep o mock global
+class Bucket {
+  consumir(n) {
+    const ahora = Date.now();  // ← imposible de controlar desde el test
+    this._rellenar(ahora);
+    if (this.tokens >= n) { this.tokens -= n; return true; }
+    return false;
+  }
+}
+
+// BIEN — reloj inyectable, test determinista
+class Bucket {
+  consumir(n, ahora = Date.now()) {  // ← default en producción, inyectable en test
+    this._rellenar(ahora);
+    if (this.tokens >= n) { this.tokens -= n; return true; }
+    return false;
+  }
+}
+
+// En el test:
+const T0 = 1700000000000;
+const b = new Bucket(10, 1, T0);
+for (let i = 0; i < 10; i++) b.consumir(1, T0);   // saturar
+assert.equal(b.consumir(1, T0), false);            // sin refill aún
+assert.equal(b.consumir(5, T0 + 5000), true);      // 5 seg después: 5 tokens
+```
+
+Aplica también a tests de clock skew (tiempo retrocede por NTP): pasar `T0 - 1000` y validar que la lógica no rompe. Origen: rate-limit-ip.js + webhook-dedup.js sesión 2026-05-13.
+
+**Tests nombrados por feature (`test_emitir_factura_exitosa`) pierden poder regresivo; nombrados por causa raíz (`test_repository_no_usa_columna_inexistente_p_monto`) detectan regresiones específicas sin reproducción manual** [CONFIRMADO en SIGM Opción C F1.4]: cuando se descubre un bug por una causa raíz concreta (typo en nombre de columna SQL, omisión de `selectinload`, mock que devuelve dict en vez de objeto, schema obsoleto), el test de regresión que se escribe debe llevar el nombre de la causa, no del feature afectado. Caso real: durante F1.4 de SIGM, el repository de pagos referenciaba `p.monto` cuando la columna se llamaba `p.monto_pagado`; el test escrito como `test_repository_no_usa_columna_inexistente_p_monto` falló inmediatamente en la siguiente sesión cuando otro agente reintrodujo el typo, sin necesidad de reproducir el escenario de negocio (emitir cobro real, verificar respuesta). Causa: los nombres orientados a feature (`test_pago_exitoso`) son ambiguos sobre QUÉ falla — si el test falla, el desarrollador debe diagnosticar; los nombres orientados a causa raíz (`test_X_no_usa_Y`, `test_query_incluye_selectinload_Z`, `test_service_devuelve_dict_no_objeto`) son auto-diagnósticos. Fix: para cada bug que cueste >30 min diagnosticar, escribir UN test adicional cuyo nombre describa la condición técnica violada, no el escenario de negocio. Convención: `test_<componente>_<condicion_tecnica>` o `test_<componente>_no_<anti_patron>`. Estos tests son tu segunda línea de defensa contra regresiones de la misma causa raíz, complementarios a los tests de comportamiento.
+
+**`process.cwd()` cacheado al `require()` rompe tests con `process.chdir(sandbox)`** [PATRÓN GENÉRICO TESTING CLI]: scripts Node exportables que leen `process.cwd()` en el scope del módulo (al cargar) congelan el cwd al directorio de invocación. Los tests que crean sandboxes con `fs.mkdtempSync()` y luego `process.chdir(sandbox)` no afectan al cwd cacheado — el script sigue leyendo del cwd original y los assertions fallan con paths inesperados. Caso real (swl-ses `scripts/derivar-feature-list.js` 2026-05-15): la función `enriquecerDesdeFases(fases)` leía `const CWD = process.cwd()` calculado al `require()`; 2 tests con `process.chdir(sandbox)` retornaron `[]` en lugar de detectar el PLAN.md fixture. Causa: el constante se evaluó cuando el `node --test` cargó el módulo desde el cwd del proyecto, no desde el sandbox del test individual. Fix obligatorio: funciones exportables deben aceptar `cwd` como parámetro opcional con fallback dinámico (`function fn(args, opciones = {}) { const cwd = opciones.cwd || process.cwd(); ... }`). El código de producción no cambia (sin args extras), pero los tests pueden inyectar el cwd correcto. Aplica también a Python (`def fn(args, cwd: str | None = None): cwd = cwd or os.getcwd()`) y a cualquier lenguaje con tests que usen chdir.
+
+```js
+// MAL — cwd cacheado al require, tests con process.chdir() fallan
+const CWD = process.cwd();
+const PLANNING_DIR = path.join(CWD, '.planning');
+
+function enriquecerDesdeFases(fases) {
+  const archivos = fs.readdirSync(path.join(PLANNING_DIR, 'fases'));  // cwd congelado
+  // ...
+}
+
+// BIEN — cwd dinámico con parámetro opcional para tests
+function enriquecerDesdeFases(fases, opciones = {}) {
+  const cwd = opciones.cwd || process.cwd();  // recalcula al llamar
+  const archivos = fs.readdirSync(path.join(cwd, '.planning', 'fases'));
+  // ...
+}
+
+// En el test (usa setupSandboxes — regla tests-cleanup.md):
+const { setupSandboxes } = require('../_helpers/sandbox');
+const sandboxes = setupSandboxes('swl-test-');
+
+const sandbox = sandboxes.create();
+fs.mkdirSync(path.join(sandbox, '.planning', 'fases'), { recursive: true });
+// Opción A: pasar cwd explícito (recomendado)
+const r = enriquecerDesdeFases([], { cwd: sandbox });
+// Opción B: process.chdir() — solo funciona con cwd dinámico
+process.chdir(sandbox);
+const r2 = enriquecerDesdeFases([]);
+// Cleanup automático al final del archivo vía after() registrado por setupSandboxes.
+```
+
+---
+
+## Gotcha: silenced tests por race condition sobre estado compartido
+
+### El anti-patrón
+
+```javascript
+// MAL — assertion condicional dentro de if que puede ser false por race
+const FLAG = path.join(os.tmpdir(), 'mi-app.json');
+
+test('flag sin contenido emite warning', () => {
+  borrarFlag();
+  const res = correrSubproceso();
+  if (fs.existsSync(FLAG)) {           // ← otro test paralelo creó el flag
+    assert.match(res.stdout, /WARN/);  // ← NUNCA se ejecuta si el if es false
+  }
+  // sin else → test PASA sin haber validado nada
+});
+
+// El test "verde" no significa "pasó" — significa "no falló ninguna assertion".
+// Si la assertion vive dentro de un `if (race)`, una race favorable la salta
+// y el test es vacío.
+```
+
+### Por qué pasa
+
+`node:test` paraleliza **archivos** `.test.js` por default (no tests dentro
+del mismo archivo). Si dos archivos tocan el mismo path único de filesystem
+(`/tmp/foo.json`, lockfiles, sockets), las operaciones se intercalan no
+deterministamente. Patrones típicos:
+
+- Archivo A: `borrarFlag()` → spawn subprocess → assert
+- Archivo B: spawn subprocess → `crearFlag()` durante A → assert de A condicionado falla
+
+### Patrones correctos
+
+**Patrón 1 — Aislamiento por path único** (recomendado):
+
+```javascript
+const { setupSandboxes } = require('../_helpers/sandbox');
+const sandboxes = setupSandboxes('swl-mi-app-test-');
+const env = { ...process.env };
+
+// Path único por test usando el helper canónico (regla tests-cleanup.md).
+// El cleanup es automático al final del archivo vía after() registrado.
+const dir = sandboxes.create();
+env.MI_APP_FLAG_PATH = path.join(dir, 'flag.json');
+
+const res = spawnSync('node', [BIN], { env, ... });
+
+// Ahora el assert es incondicional — el path es del test, no compartido
+assert.match(res.stdout, /WARN/);
+```
+
+Requiere que el SUT (System Under Test) honre una env var para override
+del path. Si no la honra, agregar el override es parte del fix.
+
+**Patrón 2 — Serialización forzada** (cuando el path es hardcoded):
+
+```bash
+# Forzar --test-concurrency=1 en la suite completa
+node --test --test-concurrency=1 tests/
+```
+
+Tradeoff: tests más lentos pero deterministas. Aceptable si el aislamiento
+no es factible (legacy code).
+
+**Patrón 3 — assertions incondicionales** con setup determinista:
+
+```javascript
+// MAL
+if (fs.existsSync(FLAG)) assert.match(...)
+
+// BIEN — setup garantiza la precondición, assertion no se salta
+escribirFlag({ ... });
+assert.ok(fs.existsSync(FLAG), 'precondición del test');  // ← assertion sobre el setup
+const res = correrSubproceso();
+assert.match(res.stdout, /WARN/);  // ← assertion incondicional sobre el resultado
+```
+
+### Anti-patrón: `if (X) assert(Y)` sin `else`
+
+```javascript
+// MAL — un test que pasa silenciosamente cuando X es false
+test('hace algo', () => {
+  const algo = obtenerAlgo();
+  if (algo) {                       // ← race u otra fuente de no-determinismo
+    assert.equal(algo.valor, 42);
+  }
+  // sin else → veredicto "pass" sin haber validado nada
+});
+
+// BIEN — el setup garantiza la precondición o el test falla explícito
+test('hace algo', () => {
+  const algo = obtenerAlgo();
+  assert.ok(algo, 'precondición: obtenerAlgo debe devolver valor');
+  assert.equal(algo.valor, 42);
+});
+```
+
+**Regla**: una assertion dentro de un `if` sin `else` es **un test que
+puede pasar sin validar nada**. Estos "silenced tests" son la peor clase
+de falsa cobertura: el reporter dice "pass" y nadie revisa el código
+hasta que un bug llega a producción.
+
+### Detección
+
+- Buscar `if (` dentro de cuerpos de `test(...)`/`it(...)` sin `else { fail() }`
+  o `else { assert(...) }` correspondiente.
+- Si el cuerpo del `if` contiene `assert.*`, considerarlo silenced test
+  hasta que se demuestre que el `if` no puede ser false en ningún escenario.
+
+### Origen
+
+Detectado en sesión 2026-05-16 del proyecto swl-ses (PR #30): tests del
+flag `swl-ses-update-check.json` compartido entre dos archivos `.test.js`
+paralelos. El test "sin flag → debe advertir" pasaba en CI cuando otro
+archivo creaba el flag, sin ejecutar ninguna assertion. Fix: env var
+`SWL_UPDATE_FLAG_PATH` para aislamiento + assertions incondicionales.
+
+---
+
+## Tests E2E de CLIs interactivos sin PTY real
+
+### El problema
+
+Probar un CLI interactivo (TUI con `readline`, prompts, keypress events,
+`process.stdin.isTTY`) en CI requiere normalmente un **pseudo-terminal
+emulado** (PTY) — usualmente vía `node-pty`, una dependencia **nativa** que:
+
+- Requiere compilación de extensiones C++ al instalar (puede fallar en
+  contenedores minimal o en Windows sin Visual Studio Build Tools).
+- Agrega ~5 MB al `node_modules` por imagen.
+- Hace que el test suite no corra en `npm test` sin setup extra.
+
+Para CLIs interactivos donde no se necesita probar **el comportamiento
+real del terminal** (escape codes, redibujado, scroll), sino solo la
+**lógica del wizard** (¿qué pasa si el usuario presiona Esc en el paso 3?,
+¿qué resuelve el promise tras Enter con default?), un harness TTY mockeado
+cubre ~90% de los casos sin dep nativa.
+
+### Patrón del harness
+
+```javascript
+// tests/harness-tty.js
+'use strict';
+
+const readline = require('readline');
+
+function crearHarness() {
+  // 1. Capturar estado original para restauración
+  const stdoutOriginal = process.stdout.write.bind(process.stdout);
+  const isTtyStdoutOriginal = process.stdout.isTTY;
+  const isTtyStdinOriginal = process.stdin.isTTY;
+  const setRawModeOriginal = process.stdin.setRawMode
+    ? process.stdin.setRawMode.bind(process.stdin) : null;
+  const emitKeypressOriginal = readline.emitKeypressEvents;
+
+  let capturado = '';
+  let listenersKeypress = [];
+
+  // 2. Forzar TTY antes de cargar módulos UI (que evalúan ES_TTY al require)
+  Object.defineProperty(process.stdout, 'isTTY', { value: true, configurable: true });
+  Object.defineProperty(process.stdin,  'isTTY', { value: true, configurable: true });
+
+  // 3. Capturar stdout en string buffer
+  process.stdout.write = (chunk) => {
+    capturado += typeof chunk === 'string' ? chunk : chunk.toString();
+    return true;
+  };
+
+  // 4. Mockear setRawMode/resume/pause como no-op (evita tomar control del terminal de test)
+  process.stdin.setRawMode = () => process.stdin;
+  process.stdin.resume = () => process.stdin;
+  process.stdin.pause = () => process.stdin;
+
+  // 5. Interceptar registros de 'keypress' para poder emitirlos a mano
+  const onListenerOriginal = process.stdin.on.bind(process.stdin);
+  process.stdin.on = (evento, listener) => {
+    if (evento === 'keypress') listenersKeypress.push(listener);
+    return onListenerOriginal(evento, listener);
+  };
+
+  // 6. Mockear readline.emitKeypressEvents (no necesita stdin real)
+  readline.emitKeypressEvents = (stream) => stream;
+
+  // 7. Limpiar require cache de módulos UI para que se evalúen con TTY=true
+  delete require.cache[require.resolve('../scripts/tui/lib/render')];
+
+  function cargarUI() {
+    return require('../scripts/tui/lib/render');
+  }
+
+  // 8. Emitir keypress programáticamente
+  function tecla(nombre, extras = {}) {
+    const key = { name: nombre, ctrl: false, meta: false, shift: false, ...extras };
+    const str = nombre.length === 1 ? nombre : '';
+    for (const listener of [...listenersKeypress]) {
+      try { listener(str, key); } catch (_) { /* swallow */ }
+    }
+  }
+
+  // 9. Esperar N ticks del event loop para promesas internas
+  function esperarTicks(n = 1) {
+    let p = Promise.resolve();
+    for (let i = 0; i < n; i++) p = p.then(() => undefined);
+    return p;
+  }
+
+  function captura(opts = {}) {
+    const valor = capturado;
+    if (opts.limpiar) capturado = '';
+    return valor;
+  }
+
+  function restaurar() {
+    Object.defineProperty(process.stdout, 'isTTY', { value: isTtyStdoutOriginal, configurable: true });
+    Object.defineProperty(process.stdin,  'isTTY', { value: isTtyStdinOriginal,  configurable: true });
+    process.stdout.write = stdoutOriginal;
+    if (setRawModeOriginal) process.stdin.setRawMode = setRawModeOriginal;
+    process.stdin.on = onListenerOriginal;
+    readline.emitKeypressEvents = emitKeypressOriginal;
+    listenersKeypress = [];
+    // Limpiar require cache para no contaminar otros tests
+    delete require.cache[require.resolve('../scripts/tui/lib/render')];
+  }
+
+  return { cargarUI, tecla, esperarTicks, captura, restaurar };
+}
+
+module.exports = { crearHarness };
+```
+
+### Uso típico
+
+```javascript
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const { crearHarness } = require('./harness-tty');
+
+test('preguntarSiNo con harness: Enter resuelve con default true', async () => {
+  const h = crearHarness();
+  try {
+    const ui = h.cargarUI();
+    const promesa = ui.preguntarSiNo('test prompt', true);
+
+    await h.esperarTicks(2);
+    h.tecla('return');
+
+    const timeout = new Promise((_, reject) =>
+      setTimeout(() => reject(new Error('no resolvió en 500ms')), 500));
+
+    const r = await Promise.race([promesa, timeout]).catch(() => null);
+    // r === true si el harness simuló bien; null si readline real bloquea
+    // (caso esperado en Windows sin PTY real; documentar limitación)
+  } finally {
+    h.restaurar();
+  }
+});
+```
+
+### Reglas operativas
+
+- **`restaurar()` en `finally`**: el harness modifica state global
+  (process.stdout, process.stdin, readline, require.cache). Si un test
+  no restaura, contamina los siguientes.
+- **Test de captura como smoke**: agregar un test "harness captura stdout"
+  que valida que `process.stdout.write('hola')` aparece en `captura()`.
+  Si falla, el harness está roto antes de testear el SUT.
+- **Test "tecla() es no-op sin listeners"**: validar que emitir keypress
+  cuando nadie escucha NO rompe el harness ni propaga errores.
+- **Limitación reconocida**: si `readline.createInterface()` real toma
+  control de stdin (en Windows con Git Bash sin PTY), el callback de
+  `rl.question()` no se invoca aunque el harness emita teclas. Usar
+  `Promise.race([promesa, timeout])` para que el test no cuelgue —
+  el test marca limitación, no falla.
+
+### Cuándo NO usar este patrón
+
+- Cuando necesitas probar **redibujado real del terminal** (alt screen
+  buffer, escape codes complejos, scrollback). Ahí sí necesitas PTY real
+  via `node-pty` o test manual.
+- Cuando el SUT depende de **timing real del teclado** (input rates,
+  paste detection). El mock no replica latencia.
+- Para CLIs sin lógica de control de flujo (solo `console.log` lineal) —
+  ahí basta capturar stdout sin mockear TTY.
+
+### Origen
+
+Aplicado en swl-ses v1.6.0 (`tests/scripts/tui/harness-tty.js`, ~180 LOC).
+Validó el TUI completo de 5 fases sin instalar `node-pty`. Limitación
+documentada: 1 test E2E "preguntarSiNo con harness" marca timeout en
+Windows + Node 22+ porque readline real bloquea pese a stdin mockeado —
+el harness emite la limitación sin fallar.