oficina-opencode 3.0.4 → 3.0.5

package/README.md

@@ -16,7 +16,7 @@
 <!-- BEGIN GENERATED: facts -->
 | | |
 |---|---|
-| **Paquete** | `oficina-opencode` v3.0.4 |
+| **Paquete** | `oficina-opencode` v3.0.5 |
 | **Tools** | 16 |
 | **Hooks** | 7 |
 | **API de plugin** | `@opencode/plugin@2.1.2` |
@@ -30,7 +30,7 @@
 > **¿Preferís la versión en humano?** → [`docs/QUE-ES.md`](https://github.com/SOCRAMbt/AI-OFFICE/blob/main/docs/QUE-ES.md) — qué es, qué hace y por qué, sin jerga.
 > **¿Preferís el porqué técnico?** → [`docs/ARCHITECTURE.md`](https://github.com/SOCRAMbt/AI-OFFICE/blob/main/docs/ARCHITECTURE.md)
 
-[Documentación](#arquitectura) · [Garantías](https://github.com/SOCRAMbt/AI-OFFICE/blob/main/docs/GARANTIAS.md) · [Compatibilidad](https://github.com/SOCRAMbt/AI-OFFICE/blob/main/docs/COMPATIBILITY.md) · [Instalación](#instalación) · [Uso](#uso) · [CLI](#cli-operación)
+[Documentación](#arquitectura) · [Garantías](https://github.com/SOCRAMbt/AI-OFFICE/blob/main/docs/GARANTIAS.md) · [Compatibilidad](https://github.com/SOCRAMbt/AI-OFFICE/blob/main/docs/COMPATIBILITY.md) · [Prueba E2E](https://github.com/SOCRAMbt/AI-OFFICE/blob/main/docs/PRUEBA-E2E.md) · [Instalación](#instalación) · [Uso](#uso) · [CLI](#cli-operación)
 
 </div>
 

package/docs/PRUEBA-E2E.md

@@ -0,0 +1,479 @@
+# Prueba end-to-end de AI-OFFICE
+
+Runbook ejecutable. Cada nivel dice **qué hacer**, **qué escribir**, **qué esperás** y
+**cómo lo verificás**.
+
+Podés parar en cualquier nivel: cada uno es independiente. El veredicto final sale del
+Nivel 7, que corre un solo comando.
+
+**Tiempo total estimado:** 45-70 minutos (la mayor parte es la corrida real, Nivel 3).
+
+---
+
+## Antes de empezar
+
+### La regla que más importa
+
+> **Abrí OpenCode en `C:\prueba-oficina`.**
+
+No en `C:\Users\Marcos`. El motivo es concreto y no es obvio:
+
+`C:\Users\Marcos` **no** es un proyecto (no tiene `package.json` ni `.git`), pero tiene
+**14 subdirectorios que sí lo son**. `resolveProjectRoot` busca en los subdirectorios y,
+como hay varios candidatos, elige por peso de fuentes. El resultado es aleatorio: podés
+terminar en `C:\Users\Marcos\oficina-plugin` escribiendo la corrida en el repo.
+
+Verificá dónde estás antes de abrir OpenCode:
+
+```powershell
+cd C:\prueba-oficina
+```
+
+### Variables para las sesiones de PowerShell
+
+Copiá esto en la terminal y dejalo abierto:
+
+```powershell
+$OFICINA = "$env:USERPROFILE\.config\opencode\node_modules\.bin\oficina.cmd"
+$REPO    = "C:\Users\Marcos\oficina-plugin"
+$PROY    = "C:\prueba-oficina"
+```
+
+> `oficina` **no está en el PATH**. Por eso la variable `$OFICINA`. Si lo querés en el
+> PATH: `setx PATH "$env:PATH;$env:USERPROFILE\.config\opencode\node_modules\.bin"`.
+
+### Reinstalar el plugin
+
+```powershell
+$cfg = "$env:USERPROFILE\.config\opencode"
+Set-Location $cfg
+npm install oficina-opencode@3.0.4 --no-audit --no-fund --prefer-online
+node ".\node_modules\oficina-opencode\dist\cli.js" install --target $cfg --json
+```
+
+**Cerrá OpenCode y volvé a abrirlo.** El plugin se carga al arrancar la sesión: si lo
+reinstalás con OpenCode abierto, la sesión actual sigue con la versión vieja.
+
+### El proyecto de prueba ya está armado
+
+`C:\prueba-oficina` contiene:
+
+```
+package.json      →  "test": "node test/run.js"
+src/              →  vacío
+test/run.js       →  runner que falla si no corrió ningún test
+```
+
+**Por qué el runner y no `node --test` directo:** `node --test` sale con **exit 0**
+aunque no encuentre un solo archivo de test:
+
+```
+$ node --test "test/**/*.test.js"
+# tests 0
+exit code: 0
+```
+
+Un gate así está **verde antes de que exista el trabajo**. `test/run.js` corrige eso:
+
+| Escenario | Exit |
+|---|---|
+| sin ningún test | **1** (gate rojo) |
+| test que pasa | 0 |
+| test que falla | 1 |
+
+---
+
+## Nivel 0 — Salud del repo (3 min, no necesita OpenCode)
+
+```powershell
+Set-Location $REPO
+npm run typecheck
+npm test
+npm run build
+npm run docs:check
+npm run bench:selection
+npm pack --dry-run
+```
+
+| Comando | Esperado |
+|---|---|
+| `typecheck` | 0 errores |
+| `test` | `Test Files 26 passed (26)` · `Tests 419 passed (419)` |
+| `build` | sin errores |
+| `docs:check` | `README.md: al dia` · `docs/QUE-ES.md: al dia` |
+| `bench:selection` | `completo 71%` y le gana a `keywords 48%` y `solo-nombre 52%` |
+| `pack --dry-run` | 173 archivos, ~328 KB |
+
+> **El `docs:check` es una trampa real.** Si bumpeás la versión y no corrés
+> `npm run docs:sync`, falla. Es el mecanismo de doc autogenerada funcionando.
+
+---
+
+## Nivel 1 — ¿Cargó el plugin? (2 min)
+
+Abrí OpenCode **en `C:\prueba-oficina`** y escribí:
+
+```
+Usá la tool `oficina_board` y mostrame el tablero de la oficina.
+```
+
+| Respuesta | Significado |
+|---|---|
+| Devuelve un tablero | ✅ el plugin cargó |
+| "No tengo la tool `oficina_board`" | ❌ el plugin no cargó |
+
+Verificación en el log:
+
+```powershell
+Get-Content "$env:USERPROFILE\.local\share\opencode\log\opencode.log" -Tail 400 |
+  Select-String "oficina" | Select-Object -Last 5
+```
+
+Buscá esta línea:
+
+```
+INFO oficina:v2: plugin inicializado {"directory":"C:\\prueba-oficina",...,"tools":16}
+```
+
+Si aparece `failed to load plugin target=oficina`, el problema es la versión: OpenCode
+v2 necesita `@opencode/plugin`, no `@opencode-ai/plugin`.
+
+---
+
+## Nivel 2 — El CLI (3 min, en un directorio aparte)
+
+```powershell
+$scratch = "C:\scratch-oficina"
+Remove-Item $scratch -Recurse -Force -ErrorAction SilentlyContinue
+mkdir $scratch -Force
+Set-Content "$scratch\package.json" '{ "name": "scratch" }'
+
+& $OFICINA init "Prueba del CLI" --directory $scratch
+& $OFICINA status --directory $scratch
+& $OFICINA board  --directory $scratch
+& $OFICINA bus    --directory $scratch
+& $OFICINA catalog --agency-root "$env:USERPROFILE\agency-agents" | Select-Object -First 10
+& $OFICINA audit T-99 --directory $scratch
+& $OFICINA verify --directory $scratch
+& $OFICINA reset --directory $scratch
+& $OFICINA reset --directory $scratch --force
+```
+
+| Comando | Esperado |
+|---|---|
+| `init` | JSON con `"ok": true`, `officeDir`, `projectRoot`, `runId` |
+| `status` | `Estado: planning` · `Presupuesto: 0/20 cards` |
+| `board` | tabla vacía, sin error |
+| `bus` | 4 canales en 0 mensajes |
+| `catalog` | lista los agentes. **Necesita `--agency-root`** (si no, "Falta --agency-root.") |
+| `audit T-99` | sale con error: `No existe la card T-99.` (exit 1) |
+| `verify` | sección de gates vacía, sin error |
+| `reset` | **pide confirmación**: "Re-ejecutá con --force para confirmar." |
+| `reset --force` | borra |
+
+---
+
+## Nivel 3 — La corrida real (el evento principal)
+
+### 3.1 Abrí la sesión
+
+```powershell
+cd C:\prueba-oficina
+```
+
+Abrí OpenCode **ahí**. En una segunda terminal dejá `$OFICINA` y `$PROY` definidos, para
+poder mirar la mesa mientras corre.
+
+### 3.2 El objetivo — copiá esto tal cual
+
+```
+/oficina Crear un modulo de utilidades de texto en src/texto.js con dos funciones: slugify(texto), que convierte un titulo en un slug (minusculas, sin acentos, con guiones), y contarPalabras(texto), que cuenta las palabras separadas por espacios. Los tests van en test/texto.test.js y la documentacion de la API en docs/API.md.
+```
+
+### 3.3 Qué mirar en los primeros 60 segundos
+
+**a) El plan.** Tiene que ser un desglose de **3 cards**: implementación, tests,
+documentación. Cada una con criteria de aceptación verificables, scope y gate. Si el
+plan sale con una sola card gigante, no es un error — pero anotá que el plan fue de 1.
+
+**b) El rol que eligió el dispatch.** Este es **el chequeo clave**.
+
+Mirá la salida del dispatch. El rol tiene que ser coherente con las capabilities de la
+card. Un rol de otro dominio es exactamente el bug que arreglé en 3.0.3 (a una card de
+"utilidades de texto" le tocaba un *ServiceNow Developer Mentor*).
+
+Si ves un rol absurdo:
+
+```
+/oficina-stop
+```
+
+o pedí que frene: `oficina_stop` con `action="halt"`.
+
+Un rol **fabricado** (que no viene del catálogo) también es válido — siempre que el
+despacho lo diga explícitamente. Un rol del catálogo con cobertura baja **también**,
+mientras lo diga.
+
+### 3.4 Mientras corre — mirá la mesa
+
+```powershell
+& $OFICINA board  --directory $PROY
+& $OFICINA status --directory $PROY
+```
+
+Los estados de card posibles: `todo`, `in_progress`, `review`, `done`, `blocked`,
+`escalated`.
+
+### 3.5 Cuando termine — el checklist
+
+La corrida dejó esto:
+
+```
+C:\prueba-oficina\.oficina\
+  state.json
+  roster.json
+  cost.json
+  artifacts\T-00\handoff.md
+  artifacts\T-00\gates.md
+  artifacts\T-00\evidence.md
+  evidence\T-00.json
+```
+
+Y los entregables:
+
+```
+C:\prueba-oficina\src\texto.js
+C:\prueba-oficina\test\texto.test.js
+C:\prueba-oficina\docs\API.md
+```
+
+**Los 5 criterios que tiene que cumplir:**
+
+| # | Criterio | Cómo lo verificás |
+|---|---|---|
+| 1 | `src/texto.js` existe y exporta las dos funciones | `node -e "console.log(Object.keys(require('C:/prueba-oficina/src/texto.js')))"` |
+| 2 | `slugify` saca acentos, pasa a minúsculas y une con guiones | `node -e "const {slugify}=require('C:/prueba-oficina/src/texto.js'); console.log(slugify('Hola Mundo Ávil'))"` → `hola-mundo-avil` |
+| 3 | `contarPalabras` cuenta palabras separadas por espacios | `node -e "const {contarPalabras}=require('C:/prueba-oficina/src/texto.js'); console.log(contarPalabras('uno dos  tres'))"` → `3` |
+| 4 | `npm test` corre la suite y sale con exit 0 | `cd C:\prueba-oficina; npm test; echo $LASTEXITCODE` → `0` |
+| 5 | La evidencia incluye la **verificación negativa** | abrir `.oficina\artifacts\T-00\evidence.md` |
+
+El punto 5 es el que más dice: la oficina tiene que **romper el código a propósito** y
+comprobar que el test lo detecta. Si la evidencia solo dice "npm test pasó", la card
+cerró sin probar que el test sirva.
+
+### 3.6 El veredicto automático
+
+```powershell
+Set-Location $REPO
+npx tsx scripts\diagnose-run.ts C:\prueba-oficina
+```
+
+Esperado: **0 fallas**. Si hay fallas, son invariantes rotos (mirá abajo).
+
+---
+
+## Nivel 4 — Adversarial (10 min, mismo proyecto)
+
+Cada prueba es un mensaje para OpenCode. Todas tienen una respuesta **correcta** clara.
+
+### 4.1 El scope se respeta de verdad
+
+En la misma sesión (o una nueva abierta en `C:\prueba-oficina`), escribí:
+
+```
+Toma la card T-00 con oficina_assign y despues intentá escribir un archivo nuevo README.md en la raiz del proyecto, que esta fuera del scope de la card. Decime exactamente que responde el motor.
+```
+
+| Correcto | Incorrecto |
+|---|---|
+| La escritura se **rechaza** con un error de scope | El archivo `README.md` aparece en el proyecto |
+
+Verificalo en disco:
+
+```powershell
+Test-Path C:\prueba-oficina\README.md   # tiene que dar False
+```
+
+### 4.2 Nadie se auto-aprueba
+
+```
+Intentá registrar el review de la card T-00 con tu propio agentId, o sea revisarte a vos mismo. Decime que responde el motor.
+```
+
+| Correcto | Incorrecto |
+|---|---|
+| El motor **rechaza**: el owner no puede ser su propio reviewer | El review queda registrado con owner == reviewer |
+
+### 4.3 El gate es real (rompé el código)
+
+```
+Rompe src/texto.js a proposito, de modo que slugify devuelva siempre la cadena vacia, y corré el gate de esa card. Decime que paso.
+```
+
+| Correcto | Incorrecto |
+|---|---|
+| El gate **falla** y la card vuelve a trabajo | El gate pasa en verde |
+
+**Restaurá el código después** (o volvé a correr `/oficina` para que la oficina lo arregle).
+
+### 4.4 El freno de emergencia
+
+```
+Frená la corrida con oficina_stop, y despues reanudala con action resume.
+```
+
+| Correcto | Incorrecto |
+|---|---|
+| `state.json` muestra `halt` con motivo, y después queda en `null` | El freno no hace nada |
+
+### 4.5 El costo se lleva
+
+```
+Mostrame el costo de la corrida con oficina_cost.
+```
+
+Esperado: el total en USD, las llamadas y los tokens. Con tu modelo (MiniMax M3.1 Flash
+Free) el USD va a ser **$0.0000** — eso es correcto, no un bug. Lo que tiene que estar
+bien es el conteo de llamadas y tokens.
+
+---
+
+## Nivel 5 — Recuperación (5 min, proyecto aparte)
+
+Esta es la prueba de **durabilidad**: que la oficina sobreviva a una muerte.
+
+### 5.1 Preparar y arrancar
+
+```powershell
+$adv = "C:\prueba-oficina-adv"
+Remove-Item $adv -Recurse -Force -ErrorAction SilentlyContinue
+mkdir "$adv\src" -Force
+mkdir "$adv\test" -Force
+Copy-Item "C:\prueba-oficina\package.json" $adv
+Copy-Item "C:\prueba-oficina\test\run.js" "$adv\test\run.js" -Force
+cd $adv
+```
+
+Abrí OpenCode en `C:\prueba-oficina-adv` y:
+
+```
+/oficina Crear un archivo src/saludo.js que exporte una funcion saludo(nombre) que devuelva "Hola, <nombre>!". Con su test en test/saludo.test.js.
+```
+
+### 5.2 Matarla en caliente
+
+Cuando veas que empezó a trabajar (**mientras la card está `in_progress`**), cerrá la
+ventana de OpenCode de golpe. No dejes que termine.
+
+### 5.3 Reanimarla
+
+Abrí OpenCode de nuevo **en el mismo directorio** y escribí:
+
+```
+Revisá el estado de la oficina y decime si la corrida quedó consistente o hay algo roto.
+```
+
+| Correcto | Incorrecto |
+|---|---|
+| La oficina detecta la inconsistencia y la reporta | Dice "todo bien" con una card colgada |
+
+Y desde la terminal:
+
+```powershell
+& $OFICINA board --directory $adv
+& $OFICINA status --directory $adv
+Set-Location $REPO
+npx tsx scripts\diagnose-run.ts C:\prueba-oficina-adv
+```
+
+Lo que tiene que aparecer: la card con su estado real, y el diagnóstico reportando
+inconsistencias (por ejemplo, el owner fantasma) en vez de un "todo bien" falso.
+
+---
+
+## Nivel 6 — Cerrar y limpiar
+
+```powershell
+& $OFICINA reset --directory $PROY --force
+& $OFICINA reset --directory $adv  --force
+Remove-Item C:\scratch-oficina -Recurse -Force -ErrorAction SilentlyContinue
+```
+
+Los artefactos de la corrida se borran con `reset`. Si querés conservarlos para
+analizarlos, **no corras `reset` todavía**: el Nivel 7 los necesita.
+
+---
+
+## Nivel 7 — Veredicto final (1 min)
+
+```powershell
+Set-Location $REPO
+npx tsx scripts\diagnose-run.ts C:\prueba-oficina
+```
+
+Salida con exit code **0** = todos los invariantes se sostienen. Exit 1 = hay al menos
+uno roto.
+
+Los 7 invariantes que verifica:
+
+| # | Invariante | Cómo se viola |
+|---|---|---|
+| 1 | Ninguna card cerrada sin gates en PASS | El gate estaba en FAIL pero la card se cerró |
+| 2 | Ninguna card cerrada sin evidencia para **cada** criterio | Falta evidencia para un criterio de aceptación |
+| 3 | Nadie se auto-aprueba | `owner == reviewer` |
+| 4 | Ninguna card sin owner | Cardcolgada sin nadie que la tome |
+| 5 | Todo owner existe en el roster | El agente murió o el roster se perdió |
+| 6 | Presupuesto respetado | Más cards / llamadas / spawns que los permitidos |
+| 7 | Todo gate `NA` explica por qué | Una fase que nadie corrió, sin motivo |
+
+Las secciones del diagnóstico:
+
+```
+1. ESTADO         objetivo, run, presupuesto, freno
+2. CARDS          cada card con su scope, gate, acceptance, owner, reviewer
+3. EL EQUIPO      qué rol se eligió y si es coherente con la card
+4. ARTEFACTOS     gates, handoff, evidencia por card
+5. EL BUS         mensajes entre agentes
+6. COSTO          USD, llamadas, tokens
+7. RECONCILIACIÓN  estado vs artefactos vs filesystem
+8. INVARIANTES    ← el veredicto
+9. VEREDICTO
+```
+
+---
+
+## Tarjeta de resultados
+
+| Nivel | Qué verificaba | Resultado |
+|---|---|---|
+| 0 | Repo sano | ☐ |
+| 1 | El plugin carga | ☐ |
+| 2 | El CLI responde | ☐ |
+| 3 | La corrida real completa | ☐ |
+| 3.5 | Los 5 criterios del entregable | ☐ |
+| 4.1 | El scope bloquea | ☐ |
+| 4.2 | Nadie se auto-aprueba | ☐ |
+| 4.3 | El gate falla si el código está roto | ☐ |
+| 4.4 | El freno funciona | ☐ |
+| 4.5 | El costo se lleva | ☐ |
+| 5 | La oficina sobrevive a una muerte | ☐ |
+| 7 | 0 fallas en los invariantes | ☐ |
+
+**Si algo falla**, el lugar exacto para mirar es
+`C:\prueba-oficina\.oficina\artifacts\<card>\gates.md` (la salida real de cada comando)
+y `C:\prueba-oficina\.oficina\evidence\<card>.json` (el grafo de evidencia).
+
+---
+
+## Lo que NO se testea acá
+
+- **La suite automatizada** (419 tests) ya cubre: sandbox, guard de scope, herencia de
+  scope en subagentes, concurrencia, atomicidad, evidencia, gates, costo, recovery,
+  matcher, dispatch, router, state machine, CLI, docsync.
+  Corré `npm test` para eso.
+- **El catálogo de 258 agentes**: `oficina catalog --agency-root ...` los lista, y el
+  benchmark mide la calidad del matching (71% hit@1).
+- **La carga bajo OpenCode v1**: el entry `./v1` existe y tiene sus tests, pero tu
+  OpenCode es v2. No es una prioridad.
+- **Multi-proyecto / concurrencia real entre corridas**: el motor lo soporta
+  (`withLock`, leases), pero probarlo requiere dos sesiones simultáneas.

package/docs/QUE-ES.md

@@ -3,7 +3,7 @@
 <!-- BEGIN GENERATED: facts -->
 | | |
 |---|---|
-| **Paquete** | `oficina-opencode` v3.0.4 |
+| **Paquete** | `oficina-opencode` v3.0.5 |
 | **Tools** | 16 |
 | **Hooks** | 7 |
 | **API de plugin** | `@opencode/plugin@2.1.2` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oficina-opencode",
-  "version": "3.0.4",
+  "version": "3.0.5",
   "description": "Oficina de Agents — malla de coordinadores + peer mesh para OpenCode. Orquestación durable de subagentes con bus de mensajes en disco, roster de roles, leases, gates de calidad y escalamiento por invariantes.",
   "license": "MIT",
   "type": "module",