# Gauntlet para código producido con IA

Plantilla operativa de Calaverita para convertir un agente de programación en un colaborador verificable. Adáptala al lenguaje, al riesgo y a los comandos reales de tu repositorio.

## 1. Política para `AGENTS.md`

```md
## Contrato de entrega

Antes de modificar:
- Lee la especificación, los tests y los módulos vecinos.
- Declara supuestos si el comportamiento esperado no está definido.
- No amplíes el alcance para "mejorar" código ajeno a la tarea.

Durante el cambio:
- Trabaja en incrementos pequeños y reversibles.
- Añade o modifica primero una prueba que falle por la razón correcta.
- No desactives tests, reglas de lint, controles de seguridad ni umbrales.
- No inventes resultados de comandos que no ejecutaste.

Antes de terminar:
- Ejecuta: `npm run check:fast`.
- Ejecuta: `npm run test:changed`.
- Para cambios de riesgo alto, ejecuta también: `npm run check:deep`.
- Reporta archivos cambiados, pruebas ejecutadas, riesgos y trabajo pendiente.

Zonas que requieren aprobación humana:
- autenticación y autorización;
- pagos, facturación y movimientos de dinero;
- datos personales, secretos y criptografía;
- migraciones destructivas o cambios de esquema;
- concurrencia, colas, caché e idempotencia;
- infraestructura y despliegues a producción.
```

Los nombres de los comandos son una interfaz estable. Cada repositorio decide qué ejecutan.

## 2. Interfaz de scripts

Ejemplo para `package.json`:

```json
{
  "scripts": {
    "typecheck": "tsc --noEmit",
    "lint": "eslint . --max-warnings=0",
    "test": "vitest run",
    "test:coverage": "vitest run --coverage",
    "test:e2e": "playwright test",
    "test:mutation": "stryker run",
    "security:secrets": "gitleaks detect --no-banner",
    "security:sast": "semgrep scan --config auto --error",
    "check:fast": "npm run typecheck && npm run lint && npm run test",
    "check:deep": "npm run check:fast && npm run test:e2e && npm run test:coverage && npm run test:mutation && npm run security:secrets && npm run security:sast"
  }
}
```

Instala y configura cada herramienta antes de publicar estos scripts. Un comando ficticio produce confianza ficticia.

## 3. Workflow para Gitea Actions

Guarda como `.gitea/workflows/quality.yml`:

```yaml
name: quality

on:
  push:
    branches: [main]
  pull_request:

jobs:
  fast-gates:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - run: npm run check:fast

  deep-gates:
    if: gitea.event_name == 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - run: npm run test:e2e
      - run: npm run test:coverage
      - run: npm run security:secrets
      - run: npm run security:sast
```

Ejecuta mutation testing de forma incremental sobre código cambiado o en un job nocturno si el costo no cabe en cada pull request.

## 4. Caso de aceptación independiente

La prueba de aceptación debe describir una obligación del negocio, no copiar la implementación propuesta por el agente.

```gherkin
Feature: reintentos de cobro idempotentes

  Scenario: el proveedor repite un webhook ya procesado
    Given existe un pago confirmado con id externo "pay_123"
    When recibimos de nuevo el webhook "pay_123"
    Then no se crea un segundo movimiento contable
    And la respuesta confirma que el evento ya fue procesado
    And queda una traza auditable del reintento
```

## 5. Revisión proporcional al riesgo

| Riesgo | Ejemplos | Evidencia mínima | Lectura humana |
|---|---|---|---|
| Bajo | documentación, estilos, generación mecánica | lint, build, snapshot o inspección visual | muestra o diff |
| Medio | reglas de negocio, API, integraciones reversibles | unitarias, integración, contrato, SAST | lógica y límites de arquitectura |
| Alto | auth, dinero, PII, migraciones, concurrencia | tests independientes, mutation/property tests, staging, rollback | línea por línea por persona competente |

## 6. Definition of Done

- [ ] La intención y los criterios de aceptación fueron revisados por una persona.
- [ ] El cambio está dentro del alcance y es reversible.
- [ ] Los tests nuevos fallan si se revierte la conducta implementada.
- [ ] Los gates rápidos pasan en local y en CI limpio.
- [ ] No se redujo cobertura ni se relajaron controles sin una decisión explícita.
- [ ] Los límites de módulos y dependencias siguen intactos.
- [ ] Los flujos críticos se probaron manualmente o con fixtures aprobados.
- [ ] El nivel de revisión corresponde al impacto, no al tamaño del diff.
- [ ] Existe observabilidad y una ruta de rollback para producción.
- [ ] Un incidente repetido se convierte en una nueva guía o un nuevo sensor.

## 7. Herramientas de mutation testing

- JavaScript/TypeScript: `npm init stryker@latest` y `npx stryker run`
- Python: `pip install mutmut` y `mutmut run`
- Java/JVM con Maven: `mvn test-compile org.pitest:pitest-maven:mutationCoverage`
- .NET: Stryker.NET mediante `dotnet stryker`

No persigas un porcentaje universal. Empieza por lógica crítica y revisa los mutantes supervivientes: cada uno pregunta si tus tests detectarían un defecto plausible.