@saulwade/swl-ses 2.2.4 → 2.3.1

package/habilidades/swl-claudemd/recursos/duplicacion-reglas-globales.md

@@ -1,85 +1,85 @@
-# Dimensión 8 — Detección de duplicación de reglas globales
-
-## Por qué existe
-
-Las reglas en `~/.claude/rules/` se cargan automáticamente en cada
-sesión SWL. Si un proyecto duplica inline el contenido de esas reglas
-en su `CLAUDE.md`, ocurren tres patologías:
-
-1. **Bloat acumulativo**: 7-15 líneas por regla duplicada × N proyectos
-   = inflación silenciosa que rompe el umbral de 200 LOC.
-2. **Drift al actualizar la global**: si la regla global cambia, las
-   copias en cada CLAUDE.md quedan obsoletas sin alerta.
-3. **Erosión del contrato canónico**: cada CLAUDE.md re-deriva el
-   principio con palabras propias, generando 4 paráfrasis distintas
-   del mismo contenido.
-
-La regla `reglas/sin-duplicacion-reglas-globales.md` (v1.7.0) prohíbe
-esta duplicación. Esta dimensión del auditor la detecta.
-
-## Catálogo declarativo
-
-`scripts/lib/reglas-globales-conocidas.json` lista las reglas globales
-conocidas con sus patrones de detección. Estructura por entrada:
-
-```json
-{
-  "id": "idioma-espanol-mexico",
-  "regla_global": "brevedad-output.md",
-  "seccion_canonica": "Idioma obligatorio: español de México",
-  "referencia_canonica": "@~/.claude/rules/brevedad-output.md § Idioma obligatorio",
-  "patrones": ["\\bespañol\\s+de\\s+M[ée]xico\\b", "..."],
-  "min_matches": 2,
-  "remediacion_sugerida": "Eliminar el bloque local..."
-}
-```
-
-Reglas incluidas en v1.7.0:
-
-- `idioma-espanol-mexico` (brevedad-output.md § Idioma)
-- `brevedad-sin-aiisms` (brevedad-output.md § Brevedad)
-- `git-sin-coautores` (git-coauthor.md)
-- `arreglar-al-detectar` (arreglar-al-detectar.md)
-- `debatir-antes-de-aceptar` (debatir-antes-de-aceptar.md)
-- `usar-context7` (usar-context7.md)
-
-## Cuándo NO se evalúa
-
-- **User-level** (`~/.claude/CLAUDE.md`): ahí sí pueden declararse
-  preferencias personales que parafrasean reglas globales. La opción
-  `esUserLevel: true` skipea la evaluación.
-- **Archivos < 20 LOC**: CLAUDE.md mínimos no acumulan duplicaciones
-  con suficiente densidad para evaluar.
-
-## Capa async — hook
-
-`hooks/claudemd-duplicacion-detector.js` (PostToolUse, no bloquea)
-ejecuta el detector tras cualquier Write/Edit a CLAUDE.md y emite
-nudge a `.planning/evolution/nudges.jsonl` con `kind:
-claudemd-duplicacion-reglas`. Opt-out: `SWL_CLAUDEMD_DUPLICACION=0`.
-
-## Cómo refactorizar duplicaciones detectadas
-
-Tres opciones para cada hallazgo:
-
-1. **Eliminar** (default recomendado): el bloque solo repite la regla
-   global, eliminarlo no pierde información.
-2. **Convertir a matiz local** (≤3 líneas): si el bloque agrega valor
-   local genuino, reescribirlo corto referenciando la regla global:
-   ```markdown
-   Convenciones locales: identificadores técnicos en inglés (rutas,
-   comandos). Ver @~/.claude/rules/brevedad-output.md.
-   ```
-3. **Documentar override explícito** (raro): si el proyecto contradice
-   la regla global por requerimiento documentable:
-   ```markdown
-   Override de @~/.claude/rules/brevedad-output.md § Brevedad: este
-   proyecto exige docstrings extendidos por compliance regulatorio.
-   ```
-
-## Anti-patrón: "lo dejo por claridad"
-
-La regla global YA es visible — se carga automáticamente. Duplicarla
-no aumenta su prioridad ni su claridad; solo crea deuda. Si el WARN
-del auditor incomoda, la respuesta correcta es **resolver la
-duplicación**, no aceptar el WARN.
+# Dimensión 8 — Detección de duplicación de reglas globales
+
+## Por qué existe
+
+Las reglas en `~/.claude/rules/` se cargan automáticamente en cada
+sesión SWL. Si un proyecto duplica inline el contenido de esas reglas
+en su `CLAUDE.md`, ocurren tres patologías:
+
+1. **Bloat acumulativo**: 7-15 líneas por regla duplicada × N proyectos
+   = inflación silenciosa que rompe el umbral de 200 LOC.
+2. **Drift al actualizar la global**: si la regla global cambia, las
+   copias en cada CLAUDE.md quedan obsoletas sin alerta.
+3. **Erosión del contrato canónico**: cada CLAUDE.md re-deriva el
+   principio con palabras propias, generando 4 paráfrasis distintas
+   del mismo contenido.
+
+La regla `reglas/sin-duplicacion-reglas-globales.md` (v1.7.0) prohíbe
+esta duplicación. Esta dimensión del auditor la detecta.
+
+## Catálogo declarativo
+
+`scripts/lib/reglas-globales-conocidas.json` lista las reglas globales
+conocidas con sus patrones de detección. Estructura por entrada:
+
+```json
+{
+  "id": "idioma-espanol-mexico",
+  "regla_global": "brevedad-output.md",
+  "seccion_canonica": "Idioma obligatorio: español de México",
+  "referencia_canonica": "@~/.claude/rules/brevedad-output.md § Idioma obligatorio",
+  "patrones": ["\\bespañol\\s+de\\s+M[ée]xico\\b", "..."],
+  "min_matches": 2,
+  "remediacion_sugerida": "Eliminar el bloque local..."
+}
+```
+
+Reglas incluidas en v1.7.0:
+
+- `idioma-espanol-mexico` (brevedad-output.md § Idioma)
+- `brevedad-sin-aiisms` (brevedad-output.md § Brevedad)
+- `git-sin-coautores` (git-coauthor.md)
+- `arreglar-al-detectar` (arreglar-al-detectar.md)
+- `debatir-antes-de-aceptar` (debatir-antes-de-aceptar.md)
+- `usar-context7` (usar-context7.md)
+
+## Cuándo NO se evalúa
+
+- **User-level** (`~/.claude/CLAUDE.md`): ahí sí pueden declararse
+  preferencias personales que parafrasean reglas globales. La opción
+  `esUserLevel: true` skipea la evaluación.
+- **Archivos < 20 LOC**: CLAUDE.md mínimos no acumulan duplicaciones
+  con suficiente densidad para evaluar.
+
+## Capa async — hook
+
+`hooks/claudemd-duplicacion-detector.js` (PostToolUse, no bloquea)
+ejecuta el detector tras cualquier Write/Edit a CLAUDE.md y emite
+nudge a `.planning/evolution/nudges.jsonl` con `kind:
+claudemd-duplicacion-reglas`. Opt-out: `SWL_CLAUDEMD_DUPLICACION=0`.
+
+## Cómo refactorizar duplicaciones detectadas
+
+Tres opciones para cada hallazgo:
+
+1. **Eliminar** (default recomendado): el bloque solo repite la regla
+   global, eliminarlo no pierde información.
+2. **Convertir a matiz local** (≤3 líneas): si el bloque agrega valor
+   local genuino, reescribirlo corto referenciando la regla global:
+   ```markdown
+   Convenciones locales: identificadores técnicos en inglés (rutas,
+   comandos). Ver @~/.claude/rules/brevedad-output.md.
+   ```
+3. **Documentar override explícito** (raro): si el proyecto contradice
+   la regla global por requerimiento documentable:
+   ```markdown
+   Override de @~/.claude/rules/brevedad-output.md § Brevedad: este
+   proyecto exige docstrings extendidos por compliance regulatorio.
+   ```
+
+## Anti-patrón: "lo dejo por claridad"
+
+La regla global YA es visible — se carga automáticamente. Duplicarla
+no aumenta su prioridad ni su claridad; solo crea deuda. Si el WARN
+del auditor incomoda, la respuesta correcta es **resolver la
+duplicación**, no aceptar el WARN.

package/habilidades/swl-claudemd/recursos/plantillas-init.md

@@ -1,94 +1,94 @@
-# Plantillas literales de init-project / init-user
-
-Bloques exactos que `/swl:claudemd init-project` inserta en el CLAUDE.md
-generado. Este recurso es la fuente de verdad de los templates — el SKILL.md
-los referencia sin duplicarlos.
-
----
-
-## Bloque obligatorio SWL-tooling (init-project)
-
-Toda generación nueva en un proyecto destino incluye esta sub-sección literal
-(empareja el CLAUDE.md con la sección swl-ses del `.gitignore` — gestionada por
-`scripts/lib/gitignore-manifest.js`). Sin ella, un compañero del equipo no sabe
-qué archivos son del proyecto y cuáles son runtime de la herramienta:
-
-```markdown
-## SWL es tooling de desarrollo (frontera de versionado)
-
-Este proyecto usa [swl-ses](https://www.npmjs.com/package/@saulwade/swl-ses) como
-herramienta de desarrollo. Lo que SWL instala y genera **no forma parte del
-proyecto** y está en `.gitignore` (sección `# [swl-ses:inicio]`): `.claude/`
-(framework), `hooks/`, `instintos/`, `usage.db` y el runtime bajo `.planning/`
-(APRENDIZAJES, métricas, sesiones, traces, evolution, loops, locks, feature-list,
-caches del grafo, etc.).
-
-SÍ se versionan (los edita el equipo): `CLAUDE.md`, `.claude/settings.json`, el
-manifest `.swl-ses`, y las plantillas de `.planning/` — `PROYECTO.md`,
-`REQUISITOS.md`, `HOJA-RUTA.md`, `ESTADO.md`, `research/`, `adrs/`, y los
-`fases/0N-{CONTEXTO,PLAN,RESUMEN,VERIFICACION}.md`.
-
-Reinstalar/actualizar el tooling: `npx -y @saulwade/swl-ses@latest install`.
-```
-
-Justificación: la lista de qué se ignora vs qué se commitea es la **fuente de
-verdad** de `gitignore-manifest.js`. Replicarla en prosa en el CLAUDE.md del
-proyecto cierra el gap de "el .gitignore lo sabe pero el humano que lee CLAUDE.md
-no". Mantener ambas en sync: si `ENTRADAS_BASE` cambia, este bloque se actualiza.
-
----
-
-## Bloque obligatorio Karpathy (init-project)
-
-Toda generación nueva incluye esta sub-sección literal en "Reglas de
-máxima prioridad":
-
-```markdown
-### Cuatro principios de implementación (Karpathy)
-Antes de implementar, refactorizar o corregir bugs: (1) **pensar antes de codificar** (no asumir en silencio), (2) **simplicidad primero** (sin abstracciones especulativas), (3) **cambios quirúrgicos** (leer archivo completo antes de editar, no refactor de oportunidad), (4) **ejecución orientada a metas** (criterios verificables, test que reproduce bugs antes del fix). Detalle + 9 ejemplos MAL→BIEN: `Skill("prevencion-sobreingenieria")` + `recursos/EXAMPLES.md`.
-```
-
-Justificación: el skill `prevencion-sobreingenieria` y su `recursos/EXAMPLES.md`
-se distribuyen con cada instalación SWL, así que la referencia siempre resuelve.
-La sub-sección compacta (5 líneas) ataca los gaps cognitivos más frecuentes
-de cualquier proyecto sin agregar opinión específica.
-
----
-
-## Check Karpathy en audit
-
-`scripts/auditar-claudemd.js` debe verificar (search regex case-insensitive):
-
-- `/karpathy/i`
-- `/cuatro principios/i` o `/4 principios/i`
-- `/prevencion-sobreingenieria/`
-- `/Skill\(["'`]prevencion-sobreingenieria["'`]\)/`
-
-Si NO encuentra ninguna AND el archivo tiene >50 LOC AND es project-level
-(no `~/.claude/CLAUDE.md`): emitir hallazgo WARN con mensaje:
-
-```
-CLAUDE.md no menciona los cuatro principios Karpathy ni el skill
-prevencion-sobreingenieria. Considerar agregar la sub-sección compacta
-(ver /swl:claudemd init-project § Bloque obligatorio Karpathy).
-```
-
-Esta dimensión es WARN, no ERROR — guía sin imponer. CLAUDE.md user-level
-(`~/.claude/`) NO se evalúa contra este check.
-
----
-
-## Secciones canónicas: project-level vs user-level (init-user)
-
-| Sección | Project-level | User-level |
-|---|---|---|
-| Stack | Sí — del proyecto | No (varía por proyecto) |
-| Comandos | Sí — del proyecto | No |
-| Code style | Sí — convenciones del equipo | Sí — preferencias personales (indent, naming favorito) |
-| Conventions | Sí — del proyecto | No |
-| Mi rol y stack preferido | No | Sí |
-| Estilo de comunicación | No | Sí |
-| Patrones que aplico siempre | No | Sí — meta-preferencias cross-project |
-
-El template completo de user-level vive en el comando `/swl:claudemd`
-sección `init-user`.
+# Plantillas literales de init-project / init-user
+
+Bloques exactos que `/swl:claudemd init-project` inserta en el CLAUDE.md
+generado. Este recurso es la fuente de verdad de los templates — el SKILL.md
+los referencia sin duplicarlos.
+
+---
+
+## Bloque obligatorio SWL-tooling (init-project)
+
+Toda generación nueva en un proyecto destino incluye esta sub-sección literal
+(empareja el CLAUDE.md con la sección swl-ses del `.gitignore` — gestionada por
+`scripts/lib/gitignore-manifest.js`). Sin ella, un compañero del equipo no sabe
+qué archivos son del proyecto y cuáles son runtime de la herramienta:
+
+```markdown
+## SWL es tooling de desarrollo (frontera de versionado)
+
+Este proyecto usa [swl-ses](https://www.npmjs.com/package/@saulwade/swl-ses) como
+herramienta de desarrollo. Lo que SWL instala y genera **no forma parte del
+proyecto** y está en `.gitignore` (sección `# [swl-ses:inicio]`): `.claude/`
+(framework), `hooks/`, `instintos/`, `usage.db` y el runtime bajo `.planning/`
+(APRENDIZAJES, métricas, sesiones, traces, evolution, loops, locks, feature-list,
+caches del grafo, etc.).
+
+SÍ se versionan (los edita el equipo): `CLAUDE.md`, `.claude/settings.json`, el
+manifest `.swl-ses`, y las plantillas de `.planning/` — `PROYECTO.md`,
+`REQUISITOS.md`, `HOJA-RUTA.md`, `ESTADO.md`, `research/`, `adrs/`, y los
+`fases/0N-{CONTEXTO,PLAN,RESUMEN,VERIFICACION}.md`.
+
+Reinstalar/actualizar el tooling: `npx -y @saulwade/swl-ses@latest install`.
+```
+
+Justificación: la lista de qué se ignora vs qué se commitea es la **fuente de
+verdad** de `gitignore-manifest.js`. Replicarla en prosa en el CLAUDE.md del
+proyecto cierra el gap de "el .gitignore lo sabe pero el humano que lee CLAUDE.md
+no". Mantener ambas en sync: si `ENTRADAS_BASE` cambia, este bloque se actualiza.
+
+---
+
+## Bloque obligatorio Karpathy (init-project)
+
+Toda generación nueva incluye esta sub-sección literal en "Reglas de
+máxima prioridad":
+
+```markdown
+### Cuatro principios de implementación (Karpathy)
+Antes de implementar, refactorizar o corregir bugs: (1) **pensar antes de codificar** (no asumir en silencio), (2) **simplicidad primero** (sin abstracciones especulativas), (3) **cambios quirúrgicos** (leer archivo completo antes de editar, no refactor de oportunidad), (4) **ejecución orientada a metas** (criterios verificables, test que reproduce bugs antes del fix). Detalle + 9 ejemplos MAL→BIEN: `Skill("prevencion-sobreingenieria")` + `recursos/EXAMPLES.md`.
+```
+
+Justificación: el skill `prevencion-sobreingenieria` y su `recursos/EXAMPLES.md`
+se distribuyen con cada instalación SWL, así que la referencia siempre resuelve.
+La sub-sección compacta (5 líneas) ataca los gaps cognitivos más frecuentes
+de cualquier proyecto sin agregar opinión específica.
+
+---
+
+## Check Karpathy en audit
+
+`scripts/auditar-claudemd.js` debe verificar (search regex case-insensitive):
+
+- `/karpathy/i`
+- `/cuatro principios/i` o `/4 principios/i`
+- `/prevencion-sobreingenieria/`
+- `/Skill\(["'`]prevencion-sobreingenieria["'`]\)/`
+
+Si NO encuentra ninguna AND el archivo tiene >50 LOC AND es project-level
+(no `~/.claude/CLAUDE.md`): emitir hallazgo WARN con mensaje:
+
+```
+CLAUDE.md no menciona los cuatro principios Karpathy ni el skill
+prevencion-sobreingenieria. Considerar agregar la sub-sección compacta
+(ver /swl:claudemd init-project § Bloque obligatorio Karpathy).
+```
+
+Esta dimensión es WARN, no ERROR — guía sin imponer. CLAUDE.md user-level
+(`~/.claude/`) NO se evalúa contra este check.
+
+---
+
+## Secciones canónicas: project-level vs user-level (init-user)
+
+| Sección | Project-level | User-level |
+|---|---|---|
+| Stack | Sí — del proyecto | No (varía por proyecto) |
+| Comandos | Sí — del proyecto | No |
+| Code style | Sí — convenciones del equipo | Sí — preferencias personales (indent, naming favorito) |
+| Conventions | Sí — del proyecto | No |
+| Mi rol y stack preferido | No | Sí |
+| Estilo de comunicación | No | Sí |
+| Patrones que aplico siempre | No | Sí — meta-preferencias cross-project |
+
+El template completo de user-level vive en el comando `/swl:claudemd`
+sección `init-user`.

package/habilidades/swl-dashboard/SKILL.md

@@ -126,7 +126,7 @@ Muestra el consumo del día en terminal. Ejemplo de salida esperada:
 ------------------------------------------------------------
   Today's Usage  (2026-04-08)
 ------------------------------------------------------------
-  claude-sonnet-4-6   turns=47  in=125.4K  out=42.9K  cost=$0.58
+  claude-sonnet-5   turns=47  in=125.4K  out=42.9K  cost=$0.58
 ------------------------------------------------------------
   TOTAL               turns=47  in=125.4K  out=42.9K  cost=$0.58
   Sessions today: 3
@@ -195,7 +195,7 @@ Dashboard iniciando en http://localhost:<DASHBOARD_PORT>
 Filtros disponibles:
   • Rangos de tiempo: 7d, 30d, 90d, all
   • Selección de modelos: checkboxes interactivos
-  • URLs bookmarkeables: ?range=7d&models=claude-sonnet-4-6
+  • URLs bookmarkeables: ?range=7d&models=claude-sonnet-5
 
 Presiona Ctrl+C en el terminal para detener el servidor.
 ```

package/habilidades/tdd-workflow/SKILL.md

@@ -1,7 +1,7 @@
 ---
 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"
+version: "1.2.2"
 herramientasPermitidas: [Read, Bash]
 evolvable: true  # default para skill estandar
 exclusiones:
@@ -536,6 +536,38 @@ archivo creaba el flag, sin ejecutar ninguna assertion. Fix: env var
 
 ---
 
+## Tests E2E de UI con Playwright — gotchas de actionability
+
+Dos fallos recurrentes al automatizar UIs con Playwright donde el test "debería
+pasar" pero hace timeout o no observa el efecto esperado:
+
+- **`fill()` hace timeout en un input que el motor considera "not editable" aunque
+  sea interactivo para el usuario** (widgets custom: input dentro de un overlay/
+  option marcado `[disabled]`, combos con buscador, etc.). Playwright aplica
+  checks de actionability (visible, enabled, editable) y se niega a escribir.
+  Fix: setear el valor con el **setter nativo** y despachar el evento `input` vía
+  `evaluate`, en vez de `fill()`:
+
+  ```js
+  await page.locator('#busqueda').evaluate((el, v) => {
+    const setter = Object.getOwnPropertyDescriptor(
+      window.HTMLInputElement.prototype, 'value').set;
+    setter.call(el, v);
+    el.dispatchEvent(new Event('input', { bubbles: true }));
+  }, 'texto');
+  ```
+
+- **Un click en «Guardar»/«Enviar» que no dispara su request** suele tener un
+  **paso de confirmación intermedio** (diálogo «¿Confirmar?», modal con timeout),
+  no un bug del submit. Antes de concluir "no persiste": verificar en la pestaña
+  de red si hubo (o no) la petición, y buscar un diálogo de confirmación que el
+  test deba cerrar dentro de su timeout. Un submit que pasa por confirmación
+  necesita el click de confirmación en la aserción, no solo el del botón inicial.
+
+Regla general: ante un test E2E que falla, distinguir **bug del producto** de
+**gap del test** verificando el estado real (red, DOM, BD) antes de declarar el
+veredicto — un timeout de actionability casi nunca es un bug de la app.
+
 ## Tests E2E de CLIs interactivos sin PTY real
 
 ### El problema

package/habilidades/tdd-workflow/recursos/gherkin-bdd.md

@@ -1,111 +1,111 @@
-# Etapa Gherkin (BDD) — de criterios de aceptación a tests ejecutables
-
-Etapa opt-in previa al ciclo RED→GREEN→REFACTOR que convierte los criterios de
-aceptación del CONTEXTO.md/PRD en escenarios **Given–When–Then** ejecutables.
-Cierra el hueco entre "lo que el negocio pidió" y "lo que los tests verifican":
-cada escenario es a la vez especificación legible por el usuario y esqueleto
-del test.
-
-Inspirada en el flujo de Robert C. Martin (spec → hard spec → Gherkin → TDD →
-mutation testing): el Gherkin es la "hard spec" verificable; el ciclo TDD la
-implementa; el mutation testing (`Skill("calidad-mutation-testing")`) verifica
-la suite resultante.
-
-## Cuándo usar la etapa (y cuándo no)
-
-**Usar cuando**: la fase tiene criterios de aceptación de negocio (PRD o
-CONTEXTO.md con decisiones cerradas), el comportamiento tiene reglas con casos
-distinguibles (descuentos, permisos, estados), o el usuario validará la spec
-sin leer código.
-
-**NO usar cuando**: la fase es técnica pura (refactor, migración, infra), los
-criterios son triviales (CRUD sin reglas), o no hay quien lea los escenarios —
-Gherkin sin lector de negocio es ceremonia que duplica los tests.
-
-## Formato
-
-```gherkin
-# language: es
-Característica: Descuento por nivel de cliente
-  Como cliente premium quiero recibir mi descuento automático
-  para no capturar cupones manualmente.
-
-  Escenario: Cliente premium recibe 15% en compras normales
-    Dado un cliente con nivel "premium"
-    Cuando realiza una compra de $100.00 MXN
-    Entonces el descuento aplicado es de $15.00 MXN
-
-  Esquema del escenario: Descuento por nivel
-    Dado un cliente con nivel "<nivel>"
-    Cuando realiza una compra de $<monto> MXN
-    Entonces el descuento aplicado es de $<descuento> MXN
-
-    Ejemplos:
-      | nivel    | monto  | descuento |
-      | normal   | 100.00 | 0.00      |
-      | premium  | 100.00 | 15.00     |
-      | mayorista| 100.00 | 22.00     |
-```
-
-Reglas de redacción:
-
-- **Un comportamiento por escenario** — si necesitas "Y cuando..." encadenados,
-  son dos escenarios.
-- **Lenguaje del dominio, no de la implementación**: "Dado un cliente premium",
-  NUNCA "Dado un row en la tabla clientes con tipo=2".
-- **Valores concretos** en los ejemplos — los criterios vagos ("un monto
-  válido") no son verificables.
-- **Esquema del escenario** para reglas con tabla de casos — es la forma
-  natural de los tests de frontera de `pruebas.md`.
-- Español de México (`# language: es`) — los escenarios los lee el usuario.
-
-## Derivación desde CONTEXTO.md / PRD
-
-1. Tomar cada criterio de aceptación cerrado del CONTEXTO.md (o historia del PRD).
-2. Reescribirlo como 1-N escenarios: el caso feliz + las fronteras + el caso de error.
-3. Presentar los escenarios al usuario para validación ANTES de implementar —
-   este es el checkpoint humano del flujo: corregir una spec cuesta una
-   conversación; corregir la implementación cuesta un refactor.
-4. Los escenarios validados se guardan en `tests/features/<dominio>.feature`
-   y el PLAN.md referencia qué tarea implementa cada escenario.
-
-## Runners por stack
-
-| Stack | Runner | Binding típico |
-|-------|--------|----------------|
-| Python | `pytest-bdd` (o `behave`) | `@scenario("features/descuento.feature", "Cliente premium...")` + steps con `@given/@when/@then` |
-| JS/TS | `@cucumber/cucumber` | steps en `features/steps/*.ts` con `Given/When/Then` |
-| C#/.NET | Reqnroll (sucesor de SpecFlow) | bindings `[Given]/[When]/[Then]` |
-| Java | Cucumber-JVM | anotaciones `@Given/@When/@Then` |
-
-Verificar versión vigente con Context7 antes de instalar (regla `usar-context7.md`).
-
-Los steps son **pegamento delgado**: parsean el Gherkin y llaman al mismo
-código de test que usaría el ciclo TDD (factories incluidas). La lógica de
-verificación vive en los asserts, no en los steps.
-
-## Integración con el ciclo TDD
-
-```
-CONTEXTO.md/PRD → escenarios Gherkin → validación del usuario (checkpoint)
-      → por cada escenario: RED (step sin implementar falla)
-      → GREEN (implementación mínima) → REFACTOR
-      → al cierre de fase: mutation testing opcional sobre el diff
-```
-
-Cada escenario Gherkin ES un test RED al inicio: el runner reporta steps sin
-implementar como fallos — exactamente la fase RED del ciclo. No escribir tests
-unitarios duplicados del mismo criterio: el escenario cubre el comportamiento
-de negocio; los tests unitarios cubren los detalles internos que el Gherkin
-no expresa (errores de infraestructura, edge cases técnicos).
-
-## Anti-patrones
-
-- **Gherkin imperativo de UI**: "Cuando hago clic en el botón #submit" — eso
-  es un script de Selenium disfrazado. Los escenarios describen comportamiento
-  de dominio; la UI cambia sin que la regla de negocio cambie.
-- **Escenarios escritos DESPUÉS de implementar** para "documentar" — pierde el
-  checkpoint de validación, que es el valor de la etapa.
-- **Steps con lógica de negocio** — la duplican; los steps solo traducen.
-- **Un .feature gigante por módulo** — un archivo por característica, como el
-  código.
+# Etapa Gherkin (BDD) — de criterios de aceptación a tests ejecutables
+
+Etapa opt-in previa al ciclo RED→GREEN→REFACTOR que convierte los criterios de
+aceptación del CONTEXTO.md/PRD en escenarios **Given–When–Then** ejecutables.
+Cierra el hueco entre "lo que el negocio pidió" y "lo que los tests verifican":
+cada escenario es a la vez especificación legible por el usuario y esqueleto
+del test.
+
+Inspirada en el flujo de Robert C. Martin (spec → hard spec → Gherkin → TDD →
+mutation testing): el Gherkin es la "hard spec" verificable; el ciclo TDD la
+implementa; el mutation testing (`Skill("calidad-mutation-testing")`) verifica
+la suite resultante.
+
+## Cuándo usar la etapa (y cuándo no)
+
+**Usar cuando**: la fase tiene criterios de aceptación de negocio (PRD o
+CONTEXTO.md con decisiones cerradas), el comportamiento tiene reglas con casos
+distinguibles (descuentos, permisos, estados), o el usuario validará la spec
+sin leer código.
+
+**NO usar cuando**: la fase es técnica pura (refactor, migración, infra), los
+criterios son triviales (CRUD sin reglas), o no hay quien lea los escenarios —
+Gherkin sin lector de negocio es ceremonia que duplica los tests.
+
+## Formato
+
+```gherkin
+# language: es
+Característica: Descuento por nivel de cliente
+  Como cliente premium quiero recibir mi descuento automático
+  para no capturar cupones manualmente.
+
+  Escenario: Cliente premium recibe 15% en compras normales
+    Dado un cliente con nivel "premium"
+    Cuando realiza una compra de $100.00 MXN
+    Entonces el descuento aplicado es de $15.00 MXN
+
+  Esquema del escenario: Descuento por nivel
+    Dado un cliente con nivel "<nivel>"
+    Cuando realiza una compra de $<monto> MXN
+    Entonces el descuento aplicado es de $<descuento> MXN
+
+    Ejemplos:
+      | nivel    | monto  | descuento |
+      | normal   | 100.00 | 0.00      |
+      | premium  | 100.00 | 15.00     |
+      | mayorista| 100.00 | 22.00     |
+```
+
+Reglas de redacción:
+
+- **Un comportamiento por escenario** — si necesitas "Y cuando..." encadenados,
+  son dos escenarios.
+- **Lenguaje del dominio, no de la implementación**: "Dado un cliente premium",
+  NUNCA "Dado un row en la tabla clientes con tipo=2".
+- **Valores concretos** en los ejemplos — los criterios vagos ("un monto
+  válido") no son verificables.
+- **Esquema del escenario** para reglas con tabla de casos — es la forma
+  natural de los tests de frontera de `pruebas.md`.
+- Español de México (`# language: es`) — los escenarios los lee el usuario.
+
+## Derivación desde CONTEXTO.md / PRD
+
+1. Tomar cada criterio de aceptación cerrado del CONTEXTO.md (o historia del PRD).
+2. Reescribirlo como 1-N escenarios: el caso feliz + las fronteras + el caso de error.
+3. Presentar los escenarios al usuario para validación ANTES de implementar —
+   este es el checkpoint humano del flujo: corregir una spec cuesta una
+   conversación; corregir la implementación cuesta un refactor.
+4. Los escenarios validados se guardan en `tests/features/<dominio>.feature`
+   y el PLAN.md referencia qué tarea implementa cada escenario.
+
+## Runners por stack
+
+| Stack | Runner | Binding típico |
+|-------|--------|----------------|
+| Python | `pytest-bdd` (o `behave`) | `@scenario("features/descuento.feature", "Cliente premium...")` + steps con `@given/@when/@then` |
+| JS/TS | `@cucumber/cucumber` | steps en `features/steps/*.ts` con `Given/When/Then` |
+| C#/.NET | Reqnroll (sucesor de SpecFlow) | bindings `[Given]/[When]/[Then]` |
+| Java | Cucumber-JVM | anotaciones `@Given/@When/@Then` |
+
+Verificar versión vigente con Context7 antes de instalar (regla `usar-context7.md`).
+
+Los steps son **pegamento delgado**: parsean el Gherkin y llaman al mismo
+código de test que usaría el ciclo TDD (factories incluidas). La lógica de
+verificación vive en los asserts, no en los steps.
+
+## Integración con el ciclo TDD
+
+```
+CONTEXTO.md/PRD → escenarios Gherkin → validación del usuario (checkpoint)
+      → por cada escenario: RED (step sin implementar falla)
+      → GREEN (implementación mínima) → REFACTOR
+      → al cierre de fase: mutation testing opcional sobre el diff
+```
+
+Cada escenario Gherkin ES un test RED al inicio: el runner reporta steps sin
+implementar como fallos — exactamente la fase RED del ciclo. No escribir tests
+unitarios duplicados del mismo criterio: el escenario cubre el comportamiento
+de negocio; los tests unitarios cubren los detalles internos que el Gherkin
+no expresa (errores de infraestructura, edge cases técnicos).
+
+## Anti-patrones
+
+- **Gherkin imperativo de UI**: "Cuando hago clic en el botón #submit" — eso
+  es un script de Selenium disfrazado. Los escenarios describen comportamiento
+  de dominio; la UI cambia sin que la regla de negocio cambie.
+- **Escenarios escritos DESPUÉS de implementar** para "documentar" — pierde el
+  checkpoint de validación, que es el valor de la etapa.
+- **Steps con lógica de negocio** — la duplican; los steps solo traducen.
+- **Un .feature gigante por módulo** — un archivo por característica, como el
+  código.