siesa-agents 2.1.72-qa.23 → 2.1.72-qa.25

package/bin/install.js

@@ -30,6 +30,12 @@ class SiesaBmadInstaller {
       '_bmad-output/shared-artifacts'
     ];
 
+    // Archivos sueltos que se copian a la raíz del workspace (no van en folderMappings)
+    // recorder.bat: launcher del Grabador de Localizadores v4, resuelve el kit vía %~dp0
+    this.rootFiles = [
+      'recorder.bat'
+    ];
+
     this.targetDir = process.cwd();
     // Intentar múltiples ubicaciones posibles para el paquete
     this.packageDir = this.findPackageDir();
@@ -537,6 +543,27 @@ class SiesaBmadInstaller {
         console.warn(`⚠️  Carpeta ${mapping.source} no encontrada en el paquete`);
       }
     }
+
+    // Copiar archivos sueltos a la raíz del workspace
+    await this.copyRootFiles();
+  }
+
+  async copyRootFiles() {
+    for (const fileName of this.rootFiles) {
+      const sourcePath = path.join(this.packageDir, fileName);
+      const targetPath = path.join(this.targetDir, fileName);
+
+      if (fs.existsSync(sourcePath)) {
+        try {
+          await fs.copy(sourcePath, targetPath, { overwrite: true });
+          console.log(`  ✓ ${fileName}`);
+        } catch (error) {
+          console.warn(`  ⚠️  Error copiando ${fileName}: ${error.message}`);
+        }
+      } else {
+        console.warn(`  ⚠️  Archivo ${fileName} no encontrado en el paquete`);
+      }
+    }
   }
 
   async update() {

package/package.json

@@ -1,42 +1,43 @@
-{
-  "name": "siesa-agents",
-  "version": "2.1.72-qa.23",
-  "description": "Paquete para instalar y configurar agentes SIESA en tu proyecto",
-  "main": "index.js",
-  "bin": {
-    "siesa-agents": "./bin/install.js"
-  },
-  "scripts": {
-    "postinstall": "node ./bin/install.js",
-    "build": "echo 'Build complete'"
-  },
-  "keywords": [
-    "siesa",
-    "bmad",
-    "agents",
-    "automation",
-    "cli"
-  ],
-  "author": "Sistemas de Información Empresarial",
-  "license": "MIT",
-  "files": [
-    "bmad/**/*",
-    "siesa-agents/**/*",
-    "vscode/**/*",
-    "github/**/*",
-    "claude/**/*",
-    "gemini/**/*",
-    "kiro/**/*",
-    "bin/**/*",
-    "resources/**/*",
-    "README.md",
-    "mcp.json"
-  ],
-  "engines": {
-    "node": ">=14.0.0"
-  },
-  "dependencies": {
-    "fs-extra": "^11.1.1",
-    "path": "^0.12.7"
-  }
-}
+{
+  "name": "siesa-agents",
+  "version": "2.1.72-qa.25",
+  "description": "Paquete para instalar y configurar agentes SIESA en tu proyecto",
+  "main": "index.js",
+  "bin": {
+    "siesa-agents": "./bin/install.js"
+  },
+  "scripts": {
+    "postinstall": "node ./bin/install.js",
+    "build": "echo 'Build complete'"
+  },
+  "keywords": [
+    "siesa",
+    "bmad",
+    "agents",
+    "automation",
+    "cli"
+  ],
+  "author": "Sistemas de Información Empresarial",
+  "license": "MIT",
+  "files": [
+    "bmad/**/*",
+    "siesa-agents/**/*",
+    "vscode/**/*",
+    "github/**/*",
+    "claude/**/*",
+    "gemini/**/*",
+    "kiro/**/*",
+    "bin/**/*",
+    "resources/**/*",
+    "README.md",
+    "mcp.json",
+    "recorder.bat"
+  ],
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "dependencies": {
+    "fs-extra": "^11.1.1",
+    "path": "^0.12.7"
+  }
+}

package/recorder.bat

@@ -0,0 +1,46 @@
+@echo off
+REM ============================================================
+REM  Grabador de Localizadores v4 — Launcher
+REM
+REM  Uso:
+REM    recorder          Modo ERP SIESA (login automatico)
+REM    recorder blank    Lienzo en blanco (sin login)
+REM    recorder fin      Financiero (qa.finance.siesa.dev)
+REM    recorder nom      Nomina (qas.nomina.siesa.dev)
+REM ============================================================
+
+set "KIT_DIR=%~dp0_siesa-agents\resources\playwright-kit"
+
+if not exist "%KIT_DIR%\tools\locator-recorder.spec.ts" (
+    echo [Grabador v4] ERROR: No se encontro playwright-kit en %KIT_DIR%
+    exit /b 1
+)
+
+pushd "%KIT_DIR%"
+
+if /i "%~1"=="blank" (
+    echo [Grabador v4] Lienzo en blanco
+    set "SKIP_LOGIN=1"
+    set "START_URL="
+    npm run recorder
+    set "SKIP_LOGIN="
+) else if /i "%~1"=="fin" (
+    echo [Grabador v4] Financiero — qa.finance.siesa.dev
+    set "SKIP_LOGIN=1"
+    set "START_URL=https://qa.finance.siesa.dev"
+    npm run recorder
+    set "SKIP_LOGIN="
+    set "START_URL="
+) else if /i "%~1"=="nom" (
+    echo [Grabador v4] Nomina — qas.nomina.siesa.dev
+    set "SKIP_LOGIN=1"
+    set "START_URL=https://qas.nomina.siesa.dev/mfe/payroll-frontend/"
+    npm run recorder
+    set "SKIP_LOGIN="
+    set "START_URL="
+) else (
+    echo [Grabador v4] ERP SIESA (login automatico)
+    npm run recorder
+)
+
+popd

package/siesa-agents/bmm/workflows/3-solutioning/quality-process/workflow.md

@@ -1860,6 +1860,16 @@ los promueve con aprobación humana, ejecuta la suite y deja los reportes listos
      DB_ENGINE=<bd>     # texto a buscar en el combo de login (ej: sqlserver)
      ```
    - Confirmar: `✅ .env del Kit configurado (BASE_URL + credenciales).`
+5. **Pre-flight de salud de APIs (recomendado):** antes de generar/ejecutar specs, verificar que el
+   backend del servicio responde — evita gastar una corrida E2E completa contra un API caído (p.ej.
+   el 503 de base-config visto en Country Master). Ejecutar:
+   ```bash
+   python {project-root}/_siesa-agents/scripts/preflight_api_check.py \
+     --base-url {BASE_URL} --endpoints "/" --allow-auth
+   ```
+   Ajustar `--endpoints` (lista separada por comas) a los health/ping reales del servicio bajo prueba.
+   Si retorna exit ≠ 0 (algún endpoint caído), **advertir al usuario** y preguntar si continuar o
+   abortar antes de seguir con la generación.
 
 Notificar:
 ```
@@ -1931,6 +1941,16 @@ y continuar con el gap analysis de `prompt_playwright_impl.md` (flujo previo).
    **C — Out-of-scope**. Escribir el código del Bloque B en `{run_folder}/proposed/*.spec.ts`
    (staging — NUNCA directo a `tests/`).
 
+   **Optimización (esqueleto pre-generado):** en modo YAML, antes de invocar al Generator se puede
+   pre-generar el esqueleto `.spec.ts` (un `describe` + un `test()` por caso, con escenario/pasos/
+   datos como comentarios y un `test.fixme()` placeholder) para que el agente solo complete la lógica
+   de cada test en vez de escribir la estructura desde cero (~40K tokens menos por feature):
+   ```bash
+   python {project-root}/_siesa-agents/scripts/spec_scaffold.py \
+     --input "{selected_yml_path}" --output "{run_folder}/proposed/"
+   ```
+   El Generator luego reemplaza cada `test.fixme(...)` por la implementación real sobre ese esqueleto.
+
 **🔵 Review Gate #1:** presentar el plan/clasificación al usuario antes de generar todo el código.
 
 ---

package/siesa-agents/scripts/bmad_to_agiletest.py

@@ -408,6 +408,14 @@ def augment_trace_with_stories(trace_map: dict, stories: list, test_cases: list)
 
     norm_index = {norm(sid): sid for sid in story_ids}
 
+    # H-10: índice epic_prefix -> [story_ids] para expandir refs a nivel de épica.
+    # Ej: BASE-CNTRY-E001-S001 y BASE-CNTRY-E001-S002 -> {'BASE-CNTRY-E001': [ambas]}
+    epic_to_stories = {}
+    for sid in story_ids:
+        m = re.match(r'(.+-E\d+)-S\d+', sid)
+        if m:
+            epic_to_stories.setdefault(m.group(1), []).append(sid)
+
     for tc in test_cases:
         if not tc.epics:
             continue
@@ -419,6 +427,16 @@ def augment_trace_with_stories(trace_map: dict, stories: list, test_cases: list)
             trace_map.setdefault(sid, [])
             if tc.tc_id not in trace_map[sid]:
                 trace_map[sid].append(tc.tc_id)
+
+        # H-10: refs a nivel de épica (ej. BASE-CNTRY-E001, sin sufijo -S###)
+        # se expanden a TODAS las historias de esa épica. Sin esto, un test_matrix
+        # con `epics: [BASE-CNTRY-E001]` no generaba ningún link TC -> Requisito.
+        for epic_key, sids in epic_to_stories.items():
+            if epic_key in tc.epics:
+                for sid in sids:
+                    trace_map.setdefault(sid, [])
+                    if tc.tc_id not in trace_map[sid]:
+                        trace_map[sid].append(tc.tc_id)
     return trace_map
 
 # ============================================================
@@ -1328,52 +1346,51 @@ def create_in_agiletest(stories, test_cases, trace_map, meta, config, state_dir=
 # ============================================================
 
 def _extract_agiletest_section(content: str, source_label: str, include_secrets: bool):
-    """Extrae y aplica valores de la sección agiletest: de un YAML."""
-    import re as _re
+    """Extrae y aplica valores de la sección agiletest: de un YAML.
 
-    at_match = _re.search(r'^agiletest:\s*\n((?:[ \t]+.+\n?)*)', content, _re.MULTILINE)
-    if not at_match:
+    H-09: se parsea con PyYAML en vez de regex línea-por-línea. El regex anterior
+    `(.+?)` quedaba anclado a fin de línea y capturaba comentarios inline, p.ej.
+    `issue_type_task: "10013"  # Tarea` se cargaba como `10013"  # Tarea`,
+    produciendo HTTP 400 en Jira. PyYAML ignora los comentarios nativamente.
+    """
+    try:
+        import yaml
+        raw = yaml.safe_load(content)
+    except Exception as e:
+        safe_print(f'  [WARN] No se pudo parsear {source_label} como YAML: {e}')
+        return
+    if not isinstance(raw, dict):
+        return
+    at = raw.get('agiletest')
+    if not isinstance(at, dict):
         return
 
-    section = at_match.group(1)
-
-    # Campos no-secretos
-    non_secret_mapping = {
-        'jira_base_url':             'jira_base_url',
-        'jira_project_key':          'jira_project_key',
-        'jira_user_email':           'jira_user_email',
-        'agiletest_base_url':        'agiletest_base_url',
-        'agiletest_project_id':      'agiletest_project_id',
-        'issue_type_task':           'issue_type_task',
-        'issue_type_test_case':      'issue_type_test_case',
-        'issue_type_test_plan':      'issue_type_test_plan',
-        'issue_type_test_execution': 'issue_type_test_execution',
-    }
-    for yaml_key, config_key in non_secret_mapping.items():
-        m = _re.search(rf'^\s+{yaml_key}:\s*["\']?(.+?)["\']?\s*$', section, _re.MULTILINE)
-        if m:
-            CONFIG[config_key] = m.group(1).strip()
+    # Campos no-secretos. Solo se sobreescribe si el valor no está vacío,
+    # para no pisar los defaults / env vars con un placeholder vacío del config.
+    non_secret_keys = [
+        'jira_base_url', 'jira_project_key', 'jira_user_email',
+        'agiletest_base_url', 'agiletest_project_id',
+        'issue_type_task', 'issue_type_test_case',
+        'issue_type_test_plan', 'issue_type_test_execution',
+    ]
+    for key in non_secret_keys:
+        val = at.get(key)
+        if val is not None and str(val).strip() != '':
+            CONFIG[key] = str(val).strip()
 
     # Campos secretos (solo se leen del secrets file, no del config.yaml público)
     if include_secrets:
-        secret_mapping = {
-            'jira_api_token':         'jira_api_token',
-            'agiletest_client_id':    'agiletest_client_id',
-            'agiletest_client_secret':'agiletest_client_secret',
-        }
-        for yaml_key, config_key in secret_mapping.items():
-            m = _re.search(rf'^\s+{yaml_key}:\s*["\']?(.+?)["\']?\s*$', section, _re.MULTILINE)
-            if m:
-                value = m.group(1).strip().strip('"').strip("'")
-                if value:  # ignorar placeholders vacíos
-                    CONFIG[config_key] = value
+        for key in ['jira_api_token', 'agiletest_client_id', 'agiletest_client_secret']:
+            val = at.get(key)
+            if val is not None and str(val).strip() != '':
+                CONFIG[key] = str(val).strip()
 
     # priority_map: P0/P1/P2/P3
-    prio_match = _re.search(r'priority_map:\s*\n((?:\s+P\d:.+\n?)*)', section)
-    if prio_match:
-        import re as _re2
-        for pm in _re2.finditer(r'(P\d):\s*["\']?(.+?)["\']?\s*$', prio_match.group(1), _re2.MULTILINE):
-            CONFIG['priority_map'][pm.group(1)] = pm.group(2).strip()
+    pmap = at.get('priority_map')
+    if isinstance(pmap, dict):
+        for k, v in pmap.items():
+            if v is not None and str(v).strip() != '':
+                CONFIG['priority_map'][str(k)] = str(v).strip()
 
 
 def load_bmm_config(config_path: str):

package/siesa-agents/scripts/preflight_api_check.py

@@ -0,0 +1,115 @@
+"""
+preflight_api_check.py
+----------------------
+Chequeo de salud de las APIs/endpoints de un servicio ANTES de lanzar los specs de
+Playwright (Fase 6 del quality-process). Evita gastar una corrida E2E completa contra
+un backend caído — como el 503 de base-config detectado en Country Master.
+
+Hace un GET a cada endpoint y reporta el status HTTP. Considera "sano":
+  - 2xx / 3xx siempre,
+  - 401 / 403 solo si se pasa --allow-auth (el servicio responde aunque exija auth).
+Marca como caído: 5xx, 4xx (salvo auth permitido), timeouts y errores de conexión.
+
+Exit code:
+  0  -> todos los endpoints sanos.
+  1  -> al menos un endpoint caído (corta el pipeline antes de correr los specs).
+
+Uso:
+    python _siesa-agents/scripts/preflight_api_check.py --base-url https://qa.finance.siesa.dev
+    python _siesa-agents/scripts/preflight_api_check.py --base-url https://qa.finance.siesa.dev \
+        --endpoints /health,/api/base-config/v1/ping --timeout 10 --allow-auth
+
+Solo usa la stdlib (urllib) — no requiere dependencias extra.
+"""
+
+import argparse
+import ssl
+import sys
+import urllib.error
+import urllib.request
+
+
+def join_url(base: str, endpoint: str) -> str:
+    base = base.rstrip('/')
+    endpoint = (endpoint or '').strip()
+    if not endpoint:
+        return base or '/'
+    if endpoint.startswith(('http://', 'https://')):
+        return endpoint
+    if not endpoint.startswith('/'):
+        endpoint = '/' + endpoint
+    return base + endpoint
+
+
+def check(url: str, timeout: float, insecure: bool):
+    """Devuelve (status:int|None, error:str). status None => no respondió."""
+    ctx = ssl.create_default_context()
+    if insecure:
+        ctx.check_hostname = False
+        ctx.verify_mode = ssl.CERT_NONE
+    req = urllib.request.Request(
+        url, method='GET', headers={'User-Agent': 'siesa-preflight/1.0'}
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=timeout, context=ctx) as resp:
+            return resp.status, ''
+    except urllib.error.HTTPError as e:
+        # El servidor respondió con un código de error (4xx/5xx).
+        return e.code, ''
+    except urllib.error.URLError as e:
+        return None, str(e.reason)
+    except Exception as e:  # noqa: BLE001 — cualquier fallo de red cuenta como caído
+        return None, str(e)
+
+
+def is_healthy(status, allow_auth: bool) -> bool:
+    if status is None:
+        return False
+    if 200 <= status < 400:
+        return True
+    if allow_auth and status in (401, 403):
+        return True
+    return False
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description='Chequeo de salud de APIs antes de correr los specs E2E (Fase 6).'
+    )
+    parser.add_argument('--base-url', required=True, help='URL base del servicio (ej: https://qa.finance.siesa.dev)')
+    parser.add_argument('--endpoints', default='/',
+                        help='Lista separada por comas de paths a probar (default: /). '
+                             'Ej: /health,/api/base-config/v1/ping')
+    parser.add_argument('--timeout', type=float, default=10.0, help='Timeout por request en segundos (default: 10)')
+    parser.add_argument('--allow-auth', action='store_true',
+                        help='Trata 401/403 como sano (el servicio responde aunque exija auth)')
+    parser.add_argument('--insecure', action='store_true', help='No verificar el certificado TLS')
+    args = parser.parse_args()
+
+    endpoints = [e for e in (args.endpoints or '/').split(',')]
+    if not endpoints:
+        endpoints = ['/']
+
+    print(f'\n  Preflight de APIs — base: {args.base_url}\n')
+    down = []
+    for ep in endpoints:
+        url = join_url(args.base_url, ep)
+        status, err = check(url, args.timeout, args.insecure)
+        ok = is_healthy(status, args.allow_auth)
+        mark = 'OK  ' if ok else 'DOWN'
+        status_txt = str(status) if status is not None else f'sin respuesta ({err})'
+        print(f'  [{mark}] {status_txt:>22}  {url}')
+        if not ok:
+            down.append(url)
+
+    print()
+    if down:
+        print(f'  RESULTADO: {len(down)} de {len(endpoints)} endpoint(s) caído(s). '
+              f'NO se recomienda correr los specs E2E todavía.')
+        sys.exit(1)
+    print(f'  RESULTADO: los {len(endpoints)} endpoint(s) responden. Listo para correr los specs E2E.')
+    sys.exit(0)
+
+
+if __name__ == '__main__':
+    main()

package/siesa-agents/scripts/requirements.txt

@@ -2,6 +2,7 @@
 # Instalar una sola vez en el entorno donde se corran los scripts:
 #   pip install -r requirements.txt
 #
-# bmad_to_agiletest.py usa yaml.safe_load() para leer test-design.yml (BMAD V7.8).
-# PyYAML no viene en la stdlib de Python, por eso se declara aqui.
+# bmad_to_agiletest.py y spec_scaffold.py usan yaml.safe_load() para leer el
+# test-design.yml (BMAD V7.8). PyYAML no viene en la stdlib, por eso se declara aqui.
+# preflight_api_check.py solo usa la stdlib (urllib) — no requiere nada extra.
 PyYAML>=6.0

package/siesa-agents/scripts/spec_scaffold.py

@@ -0,0 +1,205 @@
+"""
+spec_scaffold.py
+----------------
+Genera el ESQUELETO de archivos `.spec.ts` de Playwright a partir del `test-design.yml`
+(BMAD V7.8). Crea un archivo por feature con un `test.describe` y un `test()` por cada
+caso del `test_matrix`, embebiendo todo el contexto del diseño (escenario, precondiciones,
+pasos atómicos, resultado esperado y datos) como comentarios, más un `test.fixme()`
+placeholder.
+
+El agente Generator (Fase 6 del quality-process) completa la lógica de cada test sobre
+este esqueleto — no tiene que generar la estructura describe/it desde cero, lo que ahorra
+~40K tokens por feature.
+
+Uso:
+    python _siesa-agents/scripts/spec_scaffold.py --input test-design.yml --output tests/
+    python _siesa-agents/scripts/spec_scaffold.py --input test-design.yml --output tests/ --force
+
+Flags:
+    --input    Ruta al test-design.yml (obligatorio).
+    --output   Carpeta destino de los .spec.ts (se crea si no existe). Default: tests/
+    --force    Sobreescribe archivos .spec.ts ya existentes (por defecto NO sobreescribe).
+
+Requiere PyYAML (pip install -r requirements.txt).
+"""
+
+import argparse
+import os
+import re
+import sys
+
+
+def load_yaml(path: str) -> dict:
+    """Carga el test-design.yml como dict. Requiere PyYAML (igual que el resto del kit)."""
+    try:
+        import yaml
+    except ImportError:
+        print('  ERROR: falta PyYAML. Instala con: pip install -r requirements.txt  (o: pip install pyyaml)')
+        sys.exit(1)
+    if not os.path.isfile(path):
+        print(f'  ERROR: no existe el archivo de entrada: {path}')
+        sys.exit(1)
+    with open(path, 'r', encoding='utf-8') as f:
+        data = yaml.safe_load(f)
+    if not isinstance(data, dict):
+        print('  ERROR: el test-design.yml no tiene un mapeo (dict) en la raíz — revisa el YAML.')
+        sys.exit(1)
+    return data
+
+
+def slugify(text: str) -> str:
+    """Convierte un nombre de feature en un nombre de archivo seguro."""
+    s = re.sub(r'[^a-zA-Z0-9]+', '-', (text or '').strip().lower()).strip('-')
+    return s or 'general'
+
+
+def one_line(text: str) -> str:
+    """Colapsa cualquier valor a una sola línea (apto para comentario //)."""
+    return re.sub(r'\s+', ' ', str(text or '').replace('\r', ' ').replace('\n', ' ')).strip()
+
+
+def js_str(text: str) -> str:
+    """Escapa un texto para usarlo dentro de un string JS con comillas simples."""
+    return one_line(text).replace('\\', '\\\\').replace("'", "\\'")
+
+
+def epics_str(value) -> str:
+    if isinstance(value, list):
+        return ', '.join(str(x) for x in value)
+    return str(value or '')
+
+
+def build_test(case: dict) -> list:
+    """Genera las líneas del bloque test() para un caso del test_matrix."""
+    cid = one_line(case.get('id', ''))
+    scenario = one_line(case.get('scenario', ''))
+    level = one_line(case.get('level', ''))
+    priority = one_line(case.get('priority', ''))
+    risk = one_line(case.get('risk', ''))
+    technique = one_line(case.get('technique', ''))
+    interface_type = one_line(case.get('interface_type', ''))
+    epics = epics_str(case.get('epics', []))
+    preconditions = one_line(case.get('preconditions', ''))
+    expected = one_line(case.get('expected_result', ''))
+
+    title = scenario or cid or 'caso sin id'
+    out = []
+    out.append(f'  // ── {cid or "(sin id)"} ──────────────────────────────────────')
+    meta = f'  // Nivel: {level} | Prioridad: {priority} | Riesgo: {risk}'
+    if technique:
+        meta += f' | Técnica: {technique}'
+    if interface_type:
+        meta += f' | Interfaz: {interface_type}'
+    out.append(meta)
+    if epics:
+        out.append(f'  // Épicas/Historias: {epics}')
+    if preconditions and preconditions not in ('—', '-'):
+        out.append(f'  // Precondiciones: {preconditions}')
+    if expected:
+        out.append(f'  // Resultado esperado: {expected}')
+
+    out.append(f"  test('{js_str(cid)} — {js_str(title)}', async ({{ page }}) => {{")
+
+    steps = case.get('steps', []) or []
+    if steps:
+        out.append('    // Pasos del diseño (reemplazar por la implementación real):')
+        for i, s in enumerate(steps, 1):
+            if isinstance(s, dict):
+                accion = one_line(s.get('accion', ''))
+                resultado = one_line(s.get('resultado', ''))
+                datos = one_line(s.get('datos', ''))
+            else:
+                accion, resultado, datos = one_line(s), '', ''
+            note = f'    //   {i}. {accion}'
+            if resultado:
+                note += f'  -> {resultado}'
+            if datos:
+                note += f'  [datos: {datos}]'
+            out.append(note)
+    else:
+        out.append('    // (El diseño no trae pasos atómicos — derivar del escenario.)')
+
+    out.append("    test.fixme(true, 'Pendiente de implementación por el agente Generator (Fase 6).');")
+    out.append('  });')
+    return out
+
+
+def build_spec(feature: str, cases: list) -> str:
+    """Genera el contenido completo de un .spec.ts para una feature."""
+    lines = [
+        '/**',
+        f' * {one_line(feature) or "General"} — esqueleto generado por spec_scaffold.py',
+        ' *',
+        ' * Generado automáticamente desde test-design.yml (BMAD V7.8).',
+        ' * El agente Generator (Fase 6) debe reemplazar cada test.fixme() por la',
+        ' * implementación real de los pasos. No alterar la estructura describe/test',
+        ' * sin actualizar el diseño fuente.',
+        ' */',
+        "import { test, expect } from '@playwright/test';",
+        '',
+        '// Credenciales vía env vars (alineadas con .env.example del Kit Playwright).',
+        'const CRED = {',
+        "  user: process.env.TEST_USER ?? '',",
+        "  pass: process.env.TEST_PASS ?? '',",
+        "  bd: process.env.DB_ENGINE ?? '',",
+        '};',
+        '',
+        f"test.describe('{js_str(feature) or 'General'}', () => {{",
+        '',
+    ]
+    for c in cases:
+        lines.extend(build_test(c))
+        lines.append('')
+    lines.append('});')
+    lines.append('')
+    return '\n'.join(lines)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description='Genera esqueletos .spec.ts desde test-design.yml (BMAD V7.8).')
+    parser.add_argument('--input', required=True, help='Ruta al test-design.yml')
+    parser.add_argument('--output', default='tests/', help='Carpeta destino de los .spec.ts (default: tests/)')
+    parser.add_argument('--force', action='store_true', help='Sobreescribe archivos existentes')
+    args = parser.parse_args()
+
+    design = load_yaml(args.input)
+    matrix = design.get('test_matrix', []) or []
+    if not isinstance(matrix, list) or not matrix:
+        print('  ERROR: el test-design.yml no tiene una sección test_matrix con casos.')
+        sys.exit(1)
+
+    # Agrupar casos por feature, preservando el orden de aparición.
+    by_feature = {}
+    for c in matrix:
+        if not isinstance(c, dict) or not str(c.get('id', '')).strip():
+            continue
+        feature = one_line(c.get('feature', '')) or 'General'
+        by_feature.setdefault(feature, []).append(c)
+
+    if not by_feature:
+        print('  ERROR: no se encontró ningún caso válido (con id) en test_matrix.')
+        sys.exit(1)
+
+    os.makedirs(args.output, exist_ok=True)
+
+    written, skipped, total_cases = 0, 0, 0
+    for feature, cases in by_feature.items():
+        filename = f'{slugify(feature)}.spec.ts'
+        path = os.path.join(args.output, filename)
+        total_cases += len(cases)
+        if os.path.exists(path) and not args.force:
+            skipped += 1
+            print(f'  [SKIP] ya existe (usa --force para sobreescribir): {path}')
+            continue
+        with open(path, 'w', encoding='utf-8') as f:
+            f.write(build_spec(feature, cases))
+        written += 1
+        print(f'  [OK]   {path}  ({len(cases)} casos)')
+
+    print()
+    print(f'  Resumen: {written} spec(s) generado(s), {skipped} omitido(s), '
+          f'{total_cases} casos en {len(by_feature)} feature(s).')
+
+
+if __name__ == '__main__':
+    main()