✅ Verification — Tests, CI/CD y Definition of Done

Objetivo: Entender los dos extremos del mal scope y cómo los verification gates los previenen.

Los agentes de IA tienden a:

• Under-finish: Declarar una tarea "lista" cuando falta manejo de errores, validación de inputs o tests.
• Overreach: Implementar features futuras que no estaban en scope, rompiendo el principio de "una cosa a la vez".

La causa raíz: Sin gates explícitas, el agente define "listo" como "el código compila" o "la función principal funciona". Necesitamos elevar el umbral de "listo" a "pasa todos los checks automatizados".

Objetivo: Definir una secuencia de checks que todo código debe pasar antes de considerarse entregable.

Las 4 gates esenciales:

• 1. Tests: Unitarios, de integración y E2E. Mínimo: los tests existentes deben seguir pasando.
• 2. Lint: Estilo de código consistente. Ej: ruff (Python), eslint (JS), clippy (Rust).
• 3. Type Check: Verificación estática de tipos. Ej: mypy, tsc --noEmit, cargo check.
• 4. Build: El proyecto compila/empaqueta sin errores. Incluye assets si aplica.

Gate opcional avanzada:

• 5. Security scan: bandit (Python), npm audit, cargo audit
• 6. Coverage threshold: Mínimo 70% de cobertura para nuevos archivos

#!/bin/bash
# verify.sh — Verification Gates
set -e

echo "🧪 Running tests..."
pytest tests/ -q

echo "🔍 Running linter..."
ruff check src/

echo "📋 Running type checker..."
mypy src/

echo "🛠️ Running build..."
python -m build

echo "✅ All gates passed"

Objetivo: Automatizar las verification gates para que se ejecuten en cada push y pull request.

Un pipeline de CI bien diseñado:

• Se ejecuta en cada push a cualquier branch
• Bloquea merge si alguna gate falla
• Genera reportes de cobertura y lint visibles en PRs
• Es rápido: <5 minutos para feedback inmediato

name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      - run: pip install -e ".[dev]"
      - run: pytest tests/ --cov=src --cov-report=xml
      - run: ruff check src/
      - run: mypy src/
      - name: Upload coverage
        uses: codecov/codecov-action@v4

Badges en README.md: Un agente (o un humano) puede ver el estado de salud del repo en un vistazo.

[![CI](https://github.com/user/repo/actions/workflows/ci.yml/badge.svg)](https://github.com/user/repo/actions/workflows/ci.yml)
[![Coverage](https://codecov.io/gh/user/repo/branch/main/graph/badge.svg)](https://codecov.io/gh/user/repo)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

Objetivo: Crear un checklist explícito que el agente debe completar antes de declarar una tarea terminada.

El Definition of Done elimina la ambigüedad. Si todos los items están marcados, la tarea está realmente lista.

DoD mínimo recomendado:

• La implementación cumple con la especificación de TASK.md
• Tests unitarios cubren el caso feliz y al menos 2 casos de error
• Todos los tests existentes siguen pasando
• El linter no reporta errores ni warnings nuevos
• El type checker pasa sin errores
• La documentación relevante está actualizada (AGENTS.md, docs/)
• Los commits tienen mensajes descriptivos siguiendo convención
• El repo está en estado limpio y restartable
• Se actualizó TASK.md moviendo la tarea a "Completado"

Anti-patrón: Un DoD que nunca se consulta. Para que funcione, debe estar en AGENTS.md y el agente debe leerlo antes de decir "listo".