chore: bootstrap agnostic agent harness framework

README.md

@@ -0,0 +1,170 @@
+# 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`.