# Harness Engineering Starter Kit

Plantilla de Calaverita para diseñar el harness externo de un agente de programación. No presupone una marca de agente ni un lenguaje.

## 1. Resultado que queremos regular

Completa esto antes de añadir herramientas:

```yaml
system:
  name: ""
  business_outcome: ""

risk:
  low: ["documentación", "estilos", "refactors mecánicos"]
  medium: ["reglas de negocio", "integraciones reversibles"]
  high: ["auth", "pagos", "PII", "migraciones", "concurrencia"]

human_attention:
  always_required: []
  sample_review: []
  automation_allowed: []
```

## 2. Inventario de guías y sensores

| Dimensión | Guía antes de actuar | Sensor después de actuar | Momento | Responsable |
|---|---|---|---|---|
| Comportamiento | spec y aceptación | tests, fixture aprobado, QA | sesión + CI | producto/QA |
| Mantenibilidad | convenciones y ejemplos | lint, complejidad, duplicación | sesión | plataforma |
| Arquitectura | mapa y dependencias permitidas | structural tests | sesión + CI | arquitectura |
| Seguridad | modelo de amenazas y zonas prohibidas | SAST, secretos, revisión | sesión + CI | AppSec |
| Operación | SLO y observabilidad esperada | logs, métricas, trazas | staging + producción | SRE |

Una fila sin guía obliga a corregir tarde. Una fila sin sensor expresa un deseo que nadie verifica.

## 3. Estructura mínima del repositorio

```text
AGENTS.md
ARCHITECTURE.md
docs/
├── product/
│   ├── index.md
│   └── acceptance/
├── engineering/
│   ├── testing.md
│   ├── security.md
│   └── observability.md
├── plans/
│   ├── active/
│   └── completed/
└── decisions/
scripts/
├── check-fast
├── check-deep
└── check-architecture
```

`AGENTS.md` debe ser un mapa corto hacia fuentes canónicas, no una enciclopedia.

## 4. Contrato para `AGENTS.md`

```md
## Ruta de trabajo

Antes de cambiar:
1. Ejecuta `./scripts/check-fast`.
2. Lee la spec y el módulo afectado en `ARCHITECTURE.md`.
3. Declara supuestos y clasifica el riesgo.

Durante el cambio:
- Trabaja en incrementos reversibles.
- Sigue las dependencias permitidas.
- No relajes reglas ni umbrales para lograr verde.
- Si un sensor falla, corrige la causa o escala el conflicto.

Antes de entregar:
1. Ejecuta `./scripts/check-fast`.
2. Para riesgo medio o alto, ejecuta `./scripts/check-deep`.
3. Reporta evidencia, riesgos residuales y revisión humana requerida.
```

## 5. Registro de sensores

Guarda como `docs/engineering/sensors.yml`:

```yaml
sensors:
  - id: typecheck
    regulates: maintainability
    command: npm run typecheck
    cadence: every_change
    max_runtime_seconds: 30
    owner: platform
    response: fix

  - id: dependency-boundaries
    regulates: architecture
    command: npm run test:architecture
    cadence: every_change
    max_runtime_seconds: 30
    owner: architecture
    response: fix_or_escalate

  - id: mutation-critical
    regulates: behaviour
    command: npm run test:mutation:changed
    cadence: pull_request
    max_runtime_seconds: 900
    owner: quality
    response: review_survivors
```

Cada sensor necesita propósito, costo, propietario y respuesta. Si nadie sabe qué hacer cuando falla, sólo produce ruido.

## 6. Error diseñado para autocorrección

Mal:

```text
Dependency rule failed.
```

Mejor:

```text
ARCH-012: src/ui no puede importar src/repository.
Usa el servicio público de src/application.
Referencia: ARCHITECTURE.md#dependency-direction
No añadas una excepción. Si el caso requiere una nueva frontera, solicita revisión.
```

## 7. Bucle de aprendizaje

Después de un defecto o corrección repetida:

1. Describe el fallo observable.
2. Decide si faltó una guía, un sensor o ambos.
3. Añade el control más barato que detecte la clase de fallo.
4. Incluye un caso que demuestre que el control dispara.
5. Registra propietario y fecha de revisión.
6. Retira controles que nunca aportan señal.

## 8. Salud del harness

Revisa mensualmente:

- sensores que nunca fallan;
- sensores que siempre fallan;
- reglas desactivadas o umbrales elevados;
- tiempo y costo por ciclo;
- falsos positivos;
- defectos que escaparon a producción;
- correcciones humanas repetidas;
- documentación sin propietario o caducada;
- conflictos entre sensores;
- porcentaje de fallos que el agente autocorrige antes de revisión.

Siempre verde puede significar alta calidad o un detector inútil. Siempre rojo puede significar código malo o un detector demasiado sensible.

## 9. Plan de cuatro semanas

### Semana 1 — Legibilidad

- Unifica instalación, build y tests.
- Crea un `AGENTS.md` corto.
- Documenta arquitectura y aceptación crítica.
- Asegura que el agente pueda arrancar y observar la aplicación.

### Semana 2 — Feedback rápido

- Integra tipos, lint, unitarias, secretos y dependencias.
- Diseña errores con instrucciones de corrección.
- Ejecuta los mismos comandos en local y CI.

### Semana 3 — Riesgos difíciles

- Añade contratos, E2E selectivo y pruebas de arquitectura.
- Introduce mutation testing incremental.
- Define dónde la revisión humana es obligatoria.

### Semana 4 — Drift y producción

- Programa revisiones de dependencias, seguridad y modularidad.
- Expón logs, métricas y trazas al flujo de diagnóstico.
- Convierte los fallos repetidos en guías o sensores.
- Mide el costo y la señal de cada control.