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

Framework para construir aplicaciones con agentes autónomos, con control estricto de calidad, seguridad y trazabilidad.

Convención recomendada: el código real del proyecto vive dentro de `project/`.
Cada proyecto real debe vivir en **su propio repo git**, distinto del repo fuente de ARNES.
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 (8)

1. **leader**
   - Orquesta etapas y handoffs.
   - Da órdenes internas en English caveman.

2. **triager**
   - Convierte requests en tickets claros.
   - Escribe tickets en English caveman.

3. **architect**
   - Define/ajusta diseño técnico y contratos.

4. **implementer**
   - Implementa feature + tests.
   - No puede aprobar ni cerrar.

5. **reviewer**
   - Gate técnico.

6. **security**
   - Gate de seguridad.

7. **qa**
   - Gate funcional.

8. **documenter**
   - Documenta fix/feature/bug y actualiza docs.

---

## Flujo de trabajo (pipeline)

1. `triage_translate` (leader/triager)
2. `intake` (leader)
3. `design` (architect)
4. `build` (implementer)
5. `review_gate` (reviewer) ✅
6. `security_gate` (security) ✅
7. `qa_gate` (qa) ✅
8. `documentation_gate` (documenter) ✅
9. `close` (leader)
10. `publish` (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.json`
- `work/artifacts/<feature>/security.json`
- `work/artifacts/<feature>/qa.json`
- `work/artifacts/<feature>/leader-close.json`
- `work/artifacts/<feature>/publish.json`

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
.
├── project/                 # código real del proyecto
│   └── README.md
├── README.md
├── AGENTS.md
├── CHECKPOINTS.md
├── harness/
│   ├── agents.matrix.yml
│   ├── workflow.stages.yml
│   ├── models.profiles.yml
│   ├── policies/
│   └── contracts/
├── spec/
│   ├── product.md
│   ├── tech.md
│   ├── acceptance.md
│   ├── sdd/
│   └── bdd/
├── backlog/
│   └── features.json
├── work/
│   ├── current.md
│   ├── history.md
│   ├── runtime-status.json
│   └── artifacts/
├── scripts/
│   ├── start.sh
│   ├── new_ticket.py
│   ├── agent_status.py
│   └── verify.sh
├── defaults/
│   └── flask-skeleton/
└── platforms/
```

---

## Estado runtime visible

- Estado en tiempo real: `work/runtime-status.json`
- CLI: `python3 scripts/agent_status.py show|set|reset`

## Overlays por proyecto (sin contaminar el core)

- Reglas locales: `AGENTS.local.md` (opcional)
- Checks locales: `scripts/verify.local.sh` (opcional)
- El template base sigue agnóstico.

## Lenguaje y modelos

- Política de lenguaje: `harness/policies/language.md` (English caveman interno)
- Routing de modelos: `harness/models.profiles.yml`
- Reglas de routing: `harness/policies/model-routing.md`

## 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.

---

## Inicio rápido

- Instalar ARNES en repo externo: `./scripts/install_into_repo.sh /path/to/project-repo`
- Ejecuta wizard: `./scripts/start.sh`
- Crear ticket: `python3 scripts/new_ticket.py`
- Publicar ticket: `python3 scripts/publish_ticket.py --feature-id F-001`
- Guía breve: `HOWTO.md`
- Starter pack: `starter-pack/README.md`
- Adaptación del template: `TEMPLATE.md`
- Índice de docs: `docs/README.md`
- Layout del repo: `docs/repository-layout.md`
- Referencia de scripts: `docs/scripts-reference.md`
- Manual Skeleton (uso + mejoras): `docs/skeleton-manual.md`

## Tipos de tarea / ticket

`python3 scripts/new_ticket.py` soporta estos tipos:

- `feature`: nueva capacidad
- `fix`: corrección de comportamiento roto
- `bug`: incidencia reportada o defecto claro
- `chore`: trabajo interno, refactor, setup, mantenimiento

Además guarda campos estructurados:
- `problem`
- `goal`
- `scope_in`
- `scope_out`
- `priority`
- `risk`
- `acceptance`

Convención recomendada:
- usar `feature` para trabajo nuevo visible
- usar `fix` o `bug` para reparación
- usar `chore` para cambios internos sin valor funcional directo

## Próximos pasos sugeridos

1. Instalar/copiar ARNES en un repo de proyecto real distinto del repo fuente.
2. Definir el backlog inicial del proyecto real.
3. Configurar overlay opcional (`AGENTS.local.md`, `scripts/verify.local.sh`).
4. Ejecutar `./scripts/verify.sh` y `python3 scripts/agent_status.py show`.
5. Empezar la primera feature `pending` con pipeline completo y terminar con commit+push del ticket.
