rikrdo/mercadodevida
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(POS-FIX-7): completed feature

Browse Source
This commit is contained in:
chattie
2026-08-24 07:23:55 +02:00
parent cd2a8ab54d
commit 2467a02dd4
14 changed files with 305 additions and 81 deletions
Download Patch File Download Diff File Expand all files Collapse all files

71
docs/orquestra_improvements.md Normal file
View File

@@ -0,0 +1,71 @@
# Orquestra — Mejoras Introducidas al Harness
Este documento resume las mejoras iterativas aplicadas al harness Orquestra durante el desarrollo del proyecto MercadoDeVida vNext. Cada mejora incluye el **prompt/replicación** para reproducirla en otro proyecto.
---
## Tabla de Mejoras
| # | Mejora Introducida | Motivo (Problema que Soluciona) | Prompt para Replicar |
|---|---|---|---|
| 1 | **`verify.sh` — Validación exhaustiva del harness** | Sin verificación automatizada, era fácil romper el harness (archivos faltantes, estados inconsistentes, Backlog corrupto). | "Crea `scripts/verify.sh`: valida que existan todos los archivos del harness base (AGENTS.md, agents.matrix.yml, workflow.stages.yml, contracts/, policies/, scripts/, runtime-status.json, backlog/features.json), que no existan carpetas prohibidas (specs/, apps/, src/, lib/), que no haya archivos de código en la raíz, que Pi y Engram estén instalados, que no haya subagentes, que el Backlog tenga esquema válido (features con campos requeridos, estados válidos, un máximo de 1 in_progress), que las features done tengan artefactos de gates aprobados con esquema JSON correcto (agent + verdict=APPROVED), y que runtime-status.json tenga la estructura completa. Debe ser idempotente y tener salida coloreada (verde/rojo). Si falla algún check, exit code != 0." |
| 2 | **`agent_status.py` — Panel de estado runtime con emoji dashboard** | No había forma visual de saber qué feature estaba activa, en qué stage, ni el estado de los gates. | "Crea `scripts/agent_status.py` con tres subcomandos: `show` (muestra panel con feature, stage, agente, estado, gates, timeline), `set` (actualiza work/runtime-status.json con feature_id, stage, agent, state, action, next_agent, waiting_for, y añade evento al timeline), y `reset` (resetea a estado idle). Debe validar args contra los roles y stages definidos en harness. Debe mostrar los gates como emoji indicators (✅ aprobado, ⏳ pendiente, ⚠️ presente, ❌ inválido). Debe validar transiciones: que el stage tenga el owner correcto, que no se marque close sin todos los gates aprobados, etc." |
| 3 | **`close_feature.py` — Script de cierre con validación de gates** | Editar `backlog/features.json` manualmente para cerrar features era propenso a errores e inconsistencias. | "Crea `scripts/close_feature.py <feature_id>`: valida que existan los 4 artefactos de gate (reviewer.json, security.json, qa.json, leader-close.json) con verdict=APPROVED, actualiza el Backlog marcando la feature como done con completed_at y gates true/true/true/true, ejecuta `scripts/commit_feature.sh <feature_id>`, y resetea runtime-status a idle. Si falta algún gate, aborta con mensaje claro. **Nunca permite al implementer cerrar features**." |
| 4 | **`run_stage.py` — Ejecución aislada de stages en proceso Pi fresco** | Ejecutar stages en el mismo proceso Pi acumulaba contexto y rompía el principio de aislamiento. | "Crea `scripts/run_stage.py`: recibe stage name y feature_id, parsea `harness/workflow.stages.yml`, genera un prompt estructurado que incluye owner, inputs, outputs y post_actions del stage, y ejecuta `pi --no-session --no-context-files --no-extensions --no-skills` con las extensiones Engram + orquestra-status + orquestra-web-fetch. El prompt debe incluir reglas: fresh-process (no confiar en chat previo), leer solo archivos declarados, escribir evidencia solo en paths declarados, no editar Backlog directamente, guardar a Engram solo conocimiento durable, responder exactamente `done -> <path>` o `blocked -> <path>`. Debe verificar que existan las extensiones Pi antes de ejecutar." |
| 5 | **`orquestra-status` extension (TypeScript) — Widget UI + Write Guard** | No había visibilidad del estado en la UI de Pi, y era posible escribir código fuera de project/ o cerrar features sin gates. | "Crea `platforms/pi/extensions/orquestra-status/index.ts`: registra un widget que lee `work/runtime-status.json` y muestra feature + stage + agente + estado + gates con emojis, actualizado en cada tool_call. Implementa write/edit guard que bloquea: (a) escrituras fuera de carpetas permitidas (project/, tests/, work/, backlog/, spec/, harness/, scripts/, platforms/, docs/), (b) escrituras directas a backlog/features.json (debe usar close_feature.py), (c) archivos de producto en la raíz, (d) cambios en project/ o tests/ sin feature activa en stage build/agent implementer/state running. Registra comandos `/orquestra-status` y `/orquestra-stage <stage> [feature_id]`." |
| 6 | **`orquestra-web-fetch` extension — Herramienta de web fetch** | No había forma de que los agentes pesquisaran documentación externa, APIs o contextos durante el trabajo. | "Crea `platforms/pi/extensions/orquestra-web-fetch.ts`: registra tool `orquestra_web_fetch` con parámetros url (string) y limit (opcional, 500-20000 chars, default 8000). Hace fetch con timeout 30s, User-Agent 'Orquestra/1.0', extrae title y content del HTML (limpia scripts, styles, tags), y devuelve { content, details: { title, url, characters } }. Registra la tool en la ExtensionAPI." |
| 7 | **`new_ticket.py` — Creación de tickets con normalización de gates** | Crear features manualmente generaba inconsistencias (campos faltantes, gates mal nombrados). | "Crea `scripts/new_ticket.py` con: (a) modo interactivo tipo English caveman (preguntar problema, goal, scope_in, scope_out, acceptance bullets), (b) modo CLI con flags (`--id`, `--type`, `--title`, `--description`, `--priority`, `--risk`), (c) `--start <feature_id>` para promover pending → in_progress con exclusividad (máximo 1 activa), (d) `--normalize-gates` para migrar `gates.review` → `gates.reviewer` en features antiguas. Genera IDs secuenciales (F-001, F-002...). Añade siempre campos requeridos: id, type, title, status, created_at, gates con reviewer/security/qa false." |
| 8 | **`fix_orquestra_violations.py` — Script de auditoría y corrección masiva** | Al integrar el harness en un proyecto existente con work sucio, había features done sin gates, sin artefactos, y runtime desincronizado. | "Crea `scripts/fix_orquestra_violations.py`: detecta y corrige (1) directorio specs/ (plural → legacy/specs-old), (2) features done sin gates válidos → pending, (3) features done sin artefactos → pending, (4) features con `gates.review` obsoleto → normaliza a `gates.reviewer`, (5) features done sin completed_at → añade timestamp, (6) runtime-status.json desincronizado con Backlog → sincroniza. Idempotente, genera summary de cambios." |
| 9 | **`fix_gate_schema.py` — Normalización de esquema de artefactos de gate** | 39 ficheros de gate fueron cerrados con campo `reviewer` en vez de `agent`, causando que verify.sh los rechazara. | "Crea `scripts/fix_gate_schema.py`: para cada work/artifacts/<feature_id>/{reviewer,security,qa}.json, si falta campo `agent` y existe campo `reviewer` con el valor correcto, copiarlo. Si falta `agent` y no hay `reviewer`, ponerlo directamente. Soporta `--dry-run` y lista de features específicas. Idempotente." |
| 10 | **`commit_feature.sh` — Commit automático con mensaje estructurado** | Hacer commit manualmente después de cerrar una feature era inconsistente y fácil de olvidar. | "Crea `scripts/commit_feature.sh <feature_id>`: hace `git add -A`, commit con mensaje `feat(<feature_id>): completed feature` + descripción de work/current.md, intenta push a origin, y maneja gracefully casos sin git repo o sin remote." |
| 11 | **`install.sh` — Instalador portable del harness** | Instalar el harness en nuevos proyectos requería copiar archivos manualmente, con riesgo de sobreescribir estado existente. | "Crea `scripts/install.sh <target_dir>`: copia archivos owned por harness (AGENTS.md, HOWTO.md, CHECKPOINTS.md, harness/, platforms/, docs/, scripts/*.sh/*.py) con overwrite, crea estado de proyecto (backlog, spec, work) solo si no existen (copy_if_missing), añade bloque Orquestra a .gitignore, instala extensiones Pi en .pi/extensions/, y avisa si detecta .pi/subagents (que Orquestra no soporta). Verifica que pi y python3 estén en PATH." |
| 12 | **`pi_orquestra.sh` — Wrapper de entrada limpia** | Arrancar con `pi` directo omitía las extensiones Orquestra y permitía contexto contaminado. | "Crea `scripts/pi_orquestra.sh`: ejecuta `pi` con las extensiones Orquestra y Engram cargadas. Verifica que extensions existan antes de ejecutar. Es el punto de entrada recomendado para trabajar con Orquestra, no `pi` directo." |
| 13 | **`harness/workflow.stages.yml` — Pipeline declarativo con I/O + post_actions** | Los stages eran implícitos; no había forma de saber qué archivos leer/escribir ni qué scripts ejecutar después de cada stage. | "Crea `harness/workflow.stages.yml` con: lista de stages (intake, design, build, review_gate, security_gate, qa_gate, document, close), cada uno con owner, input paths, output paths, y opcionalmente post_actions (scripts a ejecutar). Define close_requirements: reviewer/security/qa verdict=APPROVED + verify.sh green." |
| 14 | **`harness/agents.matrix.yml` — Matriz de roles y permisos** | Sin definición de quién podía editar qué, era difícil hacer enforcement. | "Crea `harness/agents.matrix.yml`: define 7 roles (leader, architect, implementer, reviewer, security, qa, documenter) con can_edit dirs, cannot_edit dirs/patterns, y responsibilities. Incluye sección anti_cheat con reglas: implementer no puede promover a done, done requiere gates aprobados, evidence debe estar en disco." |
| 15 | **Validación de consistencia runtime ↔ backlog en `verify.sh`** | Podía haber una feature `running` en runtime-status.json mientras estaba `done` o `pending` en el Backlog. | "En verify.sh, sección 3: después de validar el Backlog, cargar work/runtime-status.json y verificar que si feature_id está activa, su estado en runtime sea consistente con el Backlog (pending → no running/done, done → existente en Backlog con gates). Si hay inconsistencia, FAIL." |
| 16 | **Reset automático post-backlog-vacío** | Cuando el backlog se vaciaba (todas done), el runtime quedaba desincronizado apuntando a una feature finalizada. | "Cuando `close_feature.py` detecta que el Backlog queda sin features pending, ejecutar `python3 scripts/agent_status.py reset` automáticamente al final del proceso de cierre. Actualizar work/current.md a estado 'ninguna feature activa'." |
---
## Uso
Para replicar estas mejoras en otro proyecto:
```bash
# 1. Clonar/fork del harness base
git clone <orquestra-source> myproject
cd myproject
# 2. Instalar en el proyecto destino
./scripts/install.sh /path/to/target-project
cd /path/to/target-project
# 3. Verificar integridad
./scripts/verify.sh
# 4. Si el proyecto ya tiene trabajo previo (work sucio):
python3 scripts/fix_orquestra_violations.py
python3 scripts/fix_gate_schema.py
./scripts/verify.sh
# 5. Arrancar
./scripts/pi_orquestra.sh
```
## Resumen de 16 Mejoras
| Categoría | Count |
|-----------|-------|
| Scripts de operación (verify, status, close, commit, install) | 6 |
| Pipelines declarativos (workflow, agents.matrix) | 2 |
| Extensiones Pi (status widget + web fetch) | 2 |
| Herramientas de migración/fijación (fix_violations, fix_schema, new_ticket) | 3 |
| Aislamiento y seguridad (run_stage, write guard, reset automático) | 3 |
## Notas de Mantenimiento
- **`verify.sh` es la fuente de verdad** del estado del harness. Debe pasar en verde antes de cualquier trabajo.
- **Nunca editar `backlog/features.json` directamente** — usar siempre `new_ticket.py` o `close_feature.py`.
- **`close_feature.py` no permite bypass de gates** — si un gate falta, el cierre aborta.
- **`run_stage.py` garantiza fresh process** — cada stage se ejecuta en contexto limpio, sin acumulación de chat.
- **La extensión `orquestra-status` bloquea escrituras fuera de `project/`** — si necesitas escribir en otro lugar, primero actualiza el `ALLOWED_WRITE_DIRS` en la extensión.