quality-gate

name	quality-gate
description	Adaptive quality gates with auto-discovered baseline and auditable evidence. Use when the user says "check quality", "run gates", "quality report", "coverage check", or before creating a PR to validate code quality. Policies: zero-tolerance lint, ratchet coverage, no-regression tests.
allowed-tools	Bash(dart *), Bash(flutter *), Bash(npm *), Bash(python *), Bash(ruff *), Bash(eslint *), Read, Grep, Glob

Quality Gate System

Validates code quality with adaptive gates and auditable evidence.

Usage

/quality-gate [mode]

Modes:

• check (default) — Run all gates, report pass/fail
• baseline — Generate or update quality baseline
• report — Generate detailed report in .quality/evidence/

---

Paso 0: Detectar Stack y Baseline

0.1 Detectar stack

Archivo	Stack	Lint command	Test command
pubspec.yaml	Flutter/Dart	dart analyze	flutter test --coverage
package.json	Node/React	npx eslint .	npx jest --coverage
pyproject.toml	Python	ruff check .	pytest --cov
.clasp.json	Apps Script	npm run lint	npm run test

0.2 Cargar baseline

BASELINE=".quality/baselines/$(basename $(pwd)).json"
if [ -f "$BASELINE" ]; then
  echo "Baseline found: $BASELINE"
  cat "$BASELINE"
else
  echo "No baseline found. Run /quality-gate baseline to create one."
fi

---

Paso 1: Gate de Lint (BLOQUEANTE)

Política: Zero-tolerance — 0 errors, 0 warnings.

Flutter/Dart

dart analyze --no-fatal-infos 2>&1
# Exit code != 0 → FAIL

Node/React

npx eslint . --max-warnings=0 2>&1
# Any warning or error → FAIL

Python

ruff check . 2>&1
# Any issue → FAIL

Apps Script

npm run lint 2>&1

Si falla: Reportar errores exactos con ubicación. NO continuar a otros gates.

---

Paso 2: Gate de Tests (BLOQUEANTE)

Política: No-regression — Todos los tests existentes deben pasar.

Flutter

flutter test --coverage 2>&1

Node/React

npx jest --coverage --passWithNoTests 2>&1

Python

pytest --cov --cov-report=term-missing 2>&1

Si falla: Listar tests fallidos con stack trace resumido.

---

Paso 3: Gate de Coverage (BLOQUEANTE)

Política: Ratchet — Coverage nunca puede bajar del baseline.

1. Leer coverage actual del resultado del Paso 2
2. Comparar con baseline:
   • coverage_actual >= coverage_baseline → PASS
   • coverage_actual < coverage_baseline → FAIL
3. Si no hay baseline → PASS pero reportar "No baseline, coverage: X%"

Mínimo absoluto: 85% (configurable)

---

Paso 4: Generar Evidence

Crear reporte auditable:

mkdir -p .quality/evidence/$(date -u +%Y-%m-%d)

Formato del reporte

# Quality Gate Report

**Project**: [nombre]
**Date**: [timestamp]
**Branch**: [rama actual]
**Commit**: [SHA corto]

## Results

| Gate | Policy | Result | Details |
|------|--------|--------|---------|
| Lint | zero-tolerance | PASS/FAIL | X errors, Y warnings |
| Tests | no-regression | PASS/FAIL | X passing, Y failing |
| Coverage | ratchet (baseline: Z%) | PASS/FAIL | Current: X% |

## Overall: PASS / FAIL

## Files with low coverage
| File | Coverage | Lines uncovered |
|------|----------|----------------|

---

Paso 5: Output

Si PASS

✅ QUALITY GATE: ALL PASSED

| Gate | Result | Details |
|------|--------|---------|
| Lint | ✅ PASS | 0 errors, 0 warnings |
| Tests | ✅ PASS | X passing, 0 failing |
| Coverage | ✅ PASS | X% (baseline: Y%) |

Evidence saved to: .quality/evidence/[date]/report.md

Si FAIL

❌ QUALITY GATE: FAILED

| Gate | Result | Details |
|------|--------|---------|
| Lint | ❌ FAIL | X errors, Y warnings |
| Tests | ✅ PASS | ... |
| Coverage | ⚠️ WARN | ... |

Blocking issues:
1. [error details]
2. [error details]

Fix these before committing or creating a PR.

---

Mode: baseline

Cuando se ejecuta con baseline:

1. Ejecutar lint, tests y coverage
2. Guardar resultados como nuevo baseline en .quality/baselines/
3. Formato JSON:

{
  "project": "nombre",
  "stack": "flutter|node|python",
  "timestamp": "ISO8601",
  "metrics": {
    "lint_errors": 0,
    "lint_warnings": 0,
    "test_coverage_pct": 87,
    "tests_passing": 42,
    "tests_failing": 0
  },
  "policies": {
    "lint": "zero-tolerance",
    "coverage": "ratchet",
    "tests": "no-regression"
  }
}

---

Paso 5.5: E2E Gate (opcional, si existe directorio e2e/ o playwright.config.ts)

Detección

1. Detectar config E2E:

   • Flutter: ls e2e/playwright.config.ts
   • React: ls playwright.config.ts o ls e2e/playwright.config.ts

2. Si existe config:

   • Flutter: verificar build/web/index.html → si no existe SKIP con warning "Flutter web build required"
   • React: verificar npm run build exitoso

3. Detectar Seed Strategy:

   • SQL: verificar que existen funciones seed_e2e_* en la DB (buscar en supabase/migrations/)
   • Firestore: verificar que existen fixtures en e2e/seed/fixtures/
   • Si hay seed configurado: reportar "Seed strategy: {SQL|Firestore|MongoDB}"
   • Si NO hay seed pero hay E2E tests: WARNING "E2E tests sin seed strategy — datos pueden no existir"

4. Ejecutar E2E con seed lifecycle:

   • Ejecutar: npx playwright test --reporter=json
   • Playwright beforeAll/afterAll en cada spec gestionan seed/cleanup automáticamente
   • Parse JSON: total, passing, failing
   • Gate: failing == 0 y passing >= baseline.e2e.passing
   • Evidence: copiar JSON summary a .quality/evidence/{feature}/e2e-results.json

5. Verificar cleanup post-ejecución (si seed detectado):

   • SQL: SELECT count(*) FROM clinics WHERE id LIKE 'e2e-%' → debe ser 0
   • Firestore: verificar que no existen docs con prefijo e2e-
   • Si quedan residuos: WARNING "E2E cleanup incompleto — {N} registros huérfanos"

6. Si no existe config: SKIP silencioso (E2E no configurado)

Output

| E2E | no-regression | ✅ PASS | X passing, 0 failing (3 viewports) [seed: SQL] |

o

| E2E | no-regression | ✅ PASS | X passing, 0 failing [seed: Firestore, cleanup: OK] |

o

| E2E | — | ⏭ SKIP | No playwright config found |

o

| E2E | no-regression | ⚠️ WARN | X passing, 0 failing [cleanup: 3 orphaned records] |

---

Paso 5.6: Design Compliance Gate (ratchet progresivo)

Verifica que la compliance de diseño Stitch no retrocede. Aplica enforcement progresivo segun el nivel del proyecto.

Deteccion

1. Cargar baseline de diseño:

   .quality/scripts/design-baseline.sh .
   

   Esto mide: features con UI, HTMLs existentes, paginas con trazabilidad.

2. Determinar enforcement level:

   complianceRate >= 80% → L2 (zero-tolerance en nuevo codigo)
   complianceRate >= 30% → L1 (ratchet — no empeorar)
   complianceRate <  30% → L0 (info — solo reporta, no bloquea)
   

3. Aplicar gate segun nivel:

   Nivel	Gate	Comportamiento
   L0	info	Solo reporta metricas. No bloquea. Muestra "Design debt: N features sin diseño"
   L1	ratchet	Compara con baseline. Si complianceRate baja → FAIL. Archivos modificados en la PR deben mantener o mejorar trazabilidad
   L2	zero-tolerance	Todo archivo nuevo en presentation/pages/ DEBE tener traceability comment + HTML en doc/design/. Sin excepciones

4. Ratchet check (L1/L2):

   .quality/scripts/design-baseline.sh . --update
   # Exit code 1 = ratchet violation
   

Retrofit: Grandfathering de codigo legacy

Para proyectos con mucho codigo pre-v4.2.0:

1. Ejecutar /check-designs → genera reporte de compliance actual
2. Ejecutar .quality/scripts/design-baseline.sh . --init → establece baseline actual
3. Los archivos existentes quedan "grandfathered" en el baseline
4. A partir de ese momento:
   • Archivos nuevos: enforcement segun nivel actual
   • Archivos existentes modificados (git diff): si se toca un archivo legacy en presentation/pages/, AG-08 Check 6 solo aplica a archivos en el diff (no a todo el proyecto)
   • complianceRate solo puede subir: cada feature que se alinee a Stitch sube el rate

Escalado automatico de nivel

El nivel sube automaticamente cuando el complianceRate cruza umbrales:

Proyecto nuevo → empieza en L0 (0% compliance)
  → Primer /plan con Stitch → sube compliance
  → Al alcanzar 30% → upgrade automatico a L1
  → Al alcanzar 80% → upgrade automatico a L2
  → Ya no puede bajar de nivel (ratchet en el nivel tambien)

Output

| Design Compliance | ratchet (L1) | ✅ PASS | 45% → 48% (3 features migradas) |

o

| Design Compliance | info (L0) | ℹ️ INFO | 12% compliance, 15 features sin diseño |

o

| Design Compliance | ratchet (L1) | ❌ FAIL | 45% → 42% — ratchet violation |

---

Checklist

• Stack detectado correctamente
• Baseline cargado (si existe)
• Lint ejecutado con zero-tolerance
• Tests ejecutados sin regresiones
• Coverage comparado con baseline
• E2E ejecutados (si config existe)
• Design compliance medida y comparada con baseline
• Evidence generado y guardado
• Resultado reportado claramente