# Orquestra — harness secuencial para Pi

Orquestra es un harness in-house para instalar en cualquier repo de proyecto y ejecutarlo desde Pi con control de estado, evidencias y gates.

No instala subagentes. El flujo es secuencial: termina un rol/stage, se escribe su artefacto, recién ahí empieza el siguiente.

## Requisitos

- `pi` instalado y disponible en `PATH` antes de ejecutar Orquestra.
- `python3` disponible para scripts del harness.
- Ejecutar Pi desde la raíz del proyecto.
- Arrancar con `./scripts/pi_orquestra.sh` para usar `pi --no-extensions` y cargar solo extensiones Orquestra.
- Extensiones Pi project-local declaradas: `orquestra-status` y `orquestra-web-fetch.ts`.

> Nota honesta: abrir `pi` directo puede cargar extensiones globales. Para Pi limpio, usá `./scripts/pi_orquestra.sh`.

## Objetivo

Permitir trabajo asistido por agentes sin perder control:
- una feature a la vez
- estado persistente en disco
- evidencia auditable, nunca solo chat
- separación de roles
- gates obligatorios de revisión, seguridad y QA
- documentación opcional cuando cambian docs/API/contratos/comportamiento user-facing
- código de producto dentro de `project/` (nunca archivos de código en la raíz)
- cierre solo con `./scripts/verify.sh` en verde

## Roles secuenciales

1. `leader` — selecciona feature, orquesta, cierra.
2. `architect` — diseño/contratos cuando haga falta.
3. `implementer` — cambia código y tests, no aprueba.
4. `reviewer` — gate técnico.
5. `security` — gate de seguridad.
6. `qa` — gate funcional/aceptación.
7. `documenter` — documentación opcional cuando aplique.

Los modelos por rol se definen en `harness/model-routing.yml`; el cambio de modelo ocurre antes de cada stage, nunca en paralelo.

## Pipeline

1. `intake` → `leader`
2. `design` → `architect` opcional
3. `build` → `implementer`
4. `review_gate` → `reviewer`
5. `security_gate` → `security`
6. `qa_gate` → `qa`
7. `document` → `documenter` opcional/condicional
8. `close` → `leader`

No hay `done` si falta cualquier gate obligatorio; `documenter.md` no es requisito de cierre salvo que el cambio necesite documentación.

## Evidencia obligatoria

Cada stage escribe 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>/documenter.md` (opcional/condicional)
- `work/artifacts/<feature>/leader-close.json`

Respuesta estándar por stage:
- `done -> <ruta>`
- `blocked -> <ruta>`

## Estructura mínima

```text
.
├── AGENTS.md
├── README.md
├── harness/
│   ├── agents.matrix.yml
│   ├── workflow.stages.yml
│   ├── model-routing.yml
│   ├── policies/
│   └── contracts/
├── platforms/pi/
│   └── extensions/
│       ├── orquestra-status/
│       └── orquestra-web-fetch.ts
├── spec/
├── project/
├── backlog/features.json
├── work/
│   ├── current.md
│   ├── history.md
│   ├── runtime-status.json
│   └── artifacts/
└── scripts/
    ├── verify.sh
    ├── agent_status.py
    ├── new_ticket.py
    └── pi_orquestra.sh
```

## Instalación y actualización segura

Desde el repo fuente de Orquestra:

```bash
./scripts/install.sh /path/to/project-repo
```

Para actualizar, volvé a ejecutar el mismo comando sobre el repo destino.

Regla base:
- crear si falta
- conservar o mergear si existe
- nunca pisar `work/`, `backlog/`, `spec/` ni artefactos ya producidos

Archivos del harness actualizables: `AGENTS.md`, `README.md`, `HOWTO.md`, `CHECKPOINTS.md`, `harness/`, `scripts/`, `platforms/pi/`.
Datos del proyecto: `project/`, `work/`, `backlog/`, `spec/`.

El instalador crea `project/` si falta y no pisa su contenido. Los archivos de producto/código (`*.py`, `*.js`, `*.ts`, `*.go`, `*.rs`, `*.java`, `*.php`, `*.rb`) son inválidos en la raíz del repo; `./scripts/verify.sh` falla si los encuentra. Durante una sesión Pi, escribir en `project/` o `tests/` requiere una feature activa con `stage=build`, `agent=implementer` y `state=running` en `work/runtime-status.json`.

## Pi

Las extensiones Orquestra esperadas son:

```text
.pi/extensions/orquestra-status/index.ts
.pi/extensions/orquestra-web-fetch.ts
```

Comando manual:

```bash
./scripts/pi_orquestra.sh
# dentro de Pi:
/orquestra-status
```

Fuente de verdad:

```bash
python3 scripts/agent_status.py show
python3 scripts/agent_status.py set ...
python3 scripts/agent_status.py reset
```

## Verificación

```bash
./scripts/verify.sh
```

Comprueba:
- estructura mínima
- `pi` instalado
- launcher limpio `scripts/pi_orquestra.sh`
- extensiones requeridas: `orquestra-status` y `orquestra-web-fetch`
- ausencia de subagentes project-local
- precondiciones de stage en `agent_status.py`
- extensiones project-local no declaradas
- backlog y gates
- `work/runtime-status.json`
- `project/` existente y sin archivos de producto/código en la raíz
- suite del proyecto si existe