# ARNES Framework (agnóstico) — Diseño v0.1

Framework para construir aplicaciones con agentes autónomos, con control estricto de calidad, seguridad y trazabilidad.
Compatible por diseño con **pi.dev** y **opencode** mediante adaptadores.

---

## Objetivo

Permitir que agentes implementen features de forma autónoma **sin perder control**:
- una feature a la vez
- evidencia en disco (no en chat)
- gates obligatorios de revisión, seguridad y QA
- cierre solo con validación completa

---

## Principios

1. **Vendor-neutral**: núcleo independiente de herramienta.
2. **Estado persistente**: todo vive en archivos versionables.
3. **No confianza ciega**: “funciona” debe demostrarse con evidencia ejecutable.
4. **Separación de roles**: quien implementa no aprueba.
5. **Anti-trampa por diseño**: no se puede marcar `done` saltando gates.

---

## Matriz de agentes (6)

1. **leader**
   - Orquesta etapas y handoffs.
   - No implementa código de producto.

2. **architect**
   - Define/ajusta diseño técnico y contratos.
   - Puede editar documentación y diseño.

3. **implementer**
   - Implementa una sola feature + tests.
   - No puede aprobar ni cerrar.

4. **reviewer**
   - Revisión técnica vs arquitectura/convenios.
   - No edita código, solo aprueba/rechaza.

5. **security**
   - Gate de seguridad: secretos, dependencias, SAST básico, hardening checks.
   - No edita código.

6. **qa**
   - Gate de calidad funcional: aceptación, integración/E2E, regresión.
   - No edita código.

---

## Flujo de trabajo (pipeline)

1. `intake` (leader)
2. `design` (architect)
3. `build` (implementer)
4. `review_gate` (reviewer) ✅
5. `security_gate` (security) ✅
6. `qa_gate` (qa) ✅
7. `close` (leader)

**Regla:** no hay `done` si cualquier gate falla.

---

## Anti-trampa (control estricto)

### Reglas de autorización
- Solo `leader` puede mover `in_progress -> done`.
- `implementer` no puede editar archivos de estado final de cierre.
- `reviewer/security/qa` no pueden editar código de producto.

### Evidencia obligatoria por etapa
Cada agente escribe artefactos en disco:
- `work/artifacts/<feature>/implementer.md`
- `work/artifacts/<feature>/reviewer.md`
- `work/artifacts/<feature>/security.md`
- `work/artifacts/<feature>/qa.md`

Respuesta de agente siempre: `done -> <ruta>` o `blocked -> <ruta>`.

### Gates ejecutados fuera del agente
- Verificación disparada por harness/scripts (no por “declaración” del agente).
- Si gate falla, estado vuelve a `blocked` o permanece `in_progress`.

### Trazabilidad y auditoría
- `work/history.md` append-only.
- Checklist de cierre firmado por etapa (aprobado/rechazado + evidencia).
- Cualquier missing evidence = cierre denegado.

---

## Estructura propuesta

```text
.
├── README.md
├── harness/
│   ├── agents.matrix.yml
│   ├── workflow.stages.yml
│   ├── policies/
│   │   ├── security.md
│   │   ├── quality.md
│   │   └── governance.md
│   └── contracts/
│       ├── handoff.md
│       └── evidence.schema.json
├── spec/
│   ├── product.md
│   ├── tech.md
│   └── acceptance.md
├── backlog/
│   └── features.json
├── work/
│   ├── current.md
│   ├── history.md
│   └── artifacts/
└── scripts/
    └── verify.sh
```

---

## Manejo de pérdidas de memoria (context loss)

Sí: el framework está diseñado para eso.

Mecanismos:
1. **Estado en disco** (`work/current.md`, `backlog/features.json`).
2. **Bitácora append-only** (`work/history.md`).
3. **Handoffs explícitos** por archivo, no por chat.
4. **Protocolo de reentrada** al iniciar sesión:
   - leer `work/current.md`
   - leer feature activa
   - ejecutar verificación base
   - continuar desde “próximo paso”

Si se pierde contexto del modelo, el sistema se puede reconstruir desde archivos.

---

## Adaptadores de plataforma

- `platforms/pi/`: prompts, hooks, permisos, comandos compatibles con pi.dev.
- `platforms/opencode/`: prompts, hooks, permisos, comandos compatibles con opencode.

El núcleo no cambia; solo el adaptador.

---

## Criterios de éxito del framework

- No se puede cerrar una feature sin 3 gates en verde (review/security/qa).
- Evidencia completa y auditable por feature.
- Reentrada robusta tras reinicio o pérdida de contexto.
- Portabilidad entre pi.dev y opencode sin rediseñar el núcleo.

---

## Próximos pasos sugeridos

1. Definir `agents.matrix.yml` completo (permisos exactos por rutas).
2. Definir `workflow.stages.yml` con transiciones válidas.
3. Diseñar `features.json` con estados y criterios de aceptación.
4. Especificar `scripts/verify.sh` (lint/test/security/qa gates).
5. Crear adaptadores `platforms/pi` y `platforms/opencode`.