oxe-cc 1.4.1 → 1.5.0

package/docs/TEAM-ADOPTION.md

@@ -0,0 +1,153 @@
+# OXE — Adoção em Times
+
+> Para times de 2–20 devs usando OXE em projetos compartilhados.
+
+---
+
+## Fluxo branch/PR recomendado
+
+Cada feature ou fix percorre este caminho:
+
+```
+git checkout -b feature/minha-feature
+/oxe-spec   → define critérios de aceite em .oxe/SPEC.md
+/oxe-plan   → gera .oxe/PLAN.md com ondas e tarefas
+/oxe-execute → implementa onda a onda
+/oxe-verify  → valida critérios do SPEC com evidências
+npx oxe-cc runtime promote --dir . --target pr_draft  → abre PR draft
+```
+
+O PR draft já vem com `.oxe/VERIFY.md` como evidência de qualidade. O reviewer usa `/oxe-verify --audit` para validação adversarial antes de aprovar.
+
+**Regra de ouro:** nunca mergear sem `VERIFY.md` existente e fase `verify_complete` no STATE.md.
+
+---
+
+## Ship local vs. promote remoto
+
+| Situação | Comando | Quando usar |
+|----------|---------|-------------|
+| Tarefa solo, ciclo completo local | `/oxe-quick` | Tasks S/M sem necessidade de review formal |
+| Feature com review de time | `/oxe-verify` + `runtime promote --target pr_draft` | Qualquer feature que vai para revisão |
+| Hotfix urgente | `/oxe-execute --task T1` + `/oxe-verify` + `runtime promote --target pr_draft` | Correções urgentes com rastreabilidade |
+| Experimento / POC | `/oxe-spec` + `/oxe-plan` + `/oxe-execute` sem promote | Validações rápidas, sem PR |
+
+`/oxe-ship` (comando legado) equivale a `/oxe-verify` + `git add/commit/push` sem passar pelo gate de promoção formal. Prefira `runtime promote` quando rastreabilidade importa.
+
+---
+
+## Sessões e workstreams sem poluir `.oxe/`
+
+### Sessões
+
+Cada sessão de trabalho tem um ID único. Para manter o diretório `.oxe/` limpo:
+
+```bash
+# Nomear sessão explicitamente
+npx oxe-cc runtime session start --name "feat-auth-2fa"
+
+# Ver sessão ativa
+npx oxe-cc runtime session status
+
+# Fechar sessão ao final do dia / feature
+npx oxe-cc runtime session close
+```
+
+**Não deixar sessões abertas.** Sessões esquecidas acumulam gates `stale` e bloqueiam relatórios de status do time.
+
+### Workstreams paralelos
+
+Para times trabalhando em features paralelas no mesmo repo:
+
+```bash
+# Workstream A (feature de autenticação)
+npx oxe-cc runtime workstream create --name auth --branch feature/auth-2fa
+
+# Workstream B (feature de dashboard)
+npx oxe-cc runtime workstream create --name dashboard --branch feature/dashboard-v2
+```
+
+Cada workstream mantém STATE.md e gates separados. Use `npx oxe-cc status --workstream auth` para ver o estado de um workstream específico sem poluir a view padrão.
+
+**Regra:** um workstream por feature branch. Nunca compartilhar um workstream entre duas features não relacionadas.
+
+---
+
+## Governança mínima
+
+### Quando exigir `discuss_before_plan`
+
+Ative quando a feature afeta:
+- Contratos de API públicos ou schemas compartilhados
+- Decisões de arquitetura que impactam outros times
+- Mudanças em infraestrutura ou pipelines de CI/CD
+
+```json
+// .oxe/config.json
+{
+  "governance": {
+    "discuss_before_plan": ["contracts/**", "infra/**", "*.schema.json"]
+  }
+}
+```
+
+Sem esse gate, o planner vai direto para PLAN.md sem esperar alinhamento.
+
+### Quando ativar `strict`
+
+Modo `strict` exige evidências formais para cada critério A* do SPEC antes de autorizar promoção. Use em:
+- Releases com SLA de qualidade (produção, clientes enterprise)
+- Features de segurança ou compliance
+- Qualquer ciclo onde um reviewer externo vai auditar
+
+```json
+{
+  "verification": {
+    "strict": true
+  }
+}
+```
+
+Em modo `strict`, `runtime promote` falha se qualquer critério A* não tiver evidência verificada.
+
+### Quando usar multi-agent
+
+Use orquestração multi-agent (`/oxe-plan --multi-agent`) quando:
+- A feature tem ondas independentes que podem ser paralelizadas
+- Time tem múltiplos devs disponíveis para executar simultaneamente
+- Tarefa de refactor em múltiplos módulos sem dependência entre eles
+
+Não use multi-agent para:
+- Features com dependências sequenciais fortes entre tarefas
+- Mudanças em arquivos compartilhados (conflitos de merge)
+- Ciclos onde um único dev vai executar tudo
+
+### Quando não usar OXE
+
+- Scripts one-off que não vão para produção
+- Experimentos de < 30 minutos sem necessidade de rastreabilidade
+- Mudanças em documentação pura (typos, formatação)
+
+Para esses casos, trabalhe direto sem o ciclo spec→plan→execute→verify.
+
+---
+
+## Checklist de integração para times novos
+
+```
+[ ] oxe-cc doctor retorna ✓ para todos os checks
+[ ] .oxe/config.json criado com profile do time
+[ ] Todos os devs têm o wrapper da IDE configurado (/oxe no Cursor, etc.)
+[ ] Branch protection rule exige VERIFY.md antes de merge
+[ ] Primeiro ciclo completo feito em pair programming
+[ ] Operador de gate designado (quem aprova runtime gates)
+```
+
+---
+
+## Referências
+
+- **Primeiros 15 minutos** → [`QUICKSTART.md`](../QUICKSTART.md)
+- **Por papel** → [`docs/ROLES.md`](ROLES.md)
+- **Exemplo completo** → [`docs/WALKTHROUGH.md`](WALKTHROUGH.md)
+- **Incidentes e gates** → [`docs/INCIDENT-PLAYBOOK.md`](INCIDENT-PLAYBOOK.md)

package/docs/WALKTHROUGH.md

@@ -0,0 +1,241 @@
+# OXE — Walkthrough Reproduzível
+
+> Feature: "Adicionar endpoint REST `GET /api/items` de listagem paginada"
+>
+> Tempo estimado: 20 minutos. Todos os comandos são reproduzíveis — copie e execute.
+
+---
+
+## Pré-requisitos
+
+```bash
+npx oxe-cc doctor
+# ✓ Node 18+
+# ✓ Workflows presentes
+# ✓ Estrutura base .oxe/
+```
+
+Se algum item falhar, siga o conselho exibido antes de continuar.
+
+---
+
+## Passo 1 — Descobrir onde você está
+
+```
+/oxe
+```
+
+**Output esperado (projeto novo):**
+```
+Estado atual: init
+Próximo passo recomendado: /oxe-scan
+Motivo: nenhum mapeamento de codebase encontrado em .oxe/codebase/
+```
+
+**Artefato gerado:** nenhum (apenas diagnóstico)
+
+---
+
+## Passo 2 — Mapear o codebase
+
+```
+/oxe-scan
+```
+
+**Output esperado:**
+```
+Scan completo.
+Arquivos mapeados: 47
+Módulos detectados: routes/, controllers/, services/, tests/
+Artefato: .oxe/codebase/map.json
+```
+
+**Artefato gerado:** `.oxe/codebase/map.json`
+
+---
+
+## Passo 3 — Gerar critérios de aceite
+
+```
+/oxe-spec
+
+> Adicionar endpoint GET /api/items com paginação (page, limit). Retornar lista de items e metadados de paginação.
+```
+
+**Output esperado:**
+```
+SPEC.md gerado.
+Critérios A* (bloqueantes):
+  A1. GET /api/items retorna 200 com lista de items
+  A2. Parâmetros page e limit são aceitos e validados
+  A3. Resposta inclui { items: [...], total, page, limit }
+  A4. Testes de integração cobrem os 3 critérios acima
+
+Critérios B (desejáveis):
+  B1. Cursor inválido retorna 400 com mensagem clara
+  B2. Documentação OpenAPI atualizada
+```
+
+**Artefato gerado:** `.oxe/SPEC.md`
+
+Revise os critérios. Se estiverem corretos, avance.
+
+---
+
+## Passo 4 — Planejar a implementação
+
+```
+/oxe-plan
+```
+
+**Output esperado:**
+```
+PLAN.md gerado.
+Onda 1 (obrigatória):
+  T1. Criar route GET /api/items em routes/items.js
+  T2. Implementar ItemsController.list() com paginação
+  T3. Implementar ItemsService.findPaginated(page, limit)
+  T4. Escrever testes de integração para os 3 critérios A*
+
+Hipótese crítica: ItemsService tem acesso ao repositório de dados correto
+Arquivos-alvo: routes/items.js, controllers/items.js, services/items.js, tests/items.test.js
+```
+
+**Artefato gerado:** `.oxe/PLAN.md`
+
+---
+
+## Passo 5 — Implementar
+
+```
+/oxe-execute
+```
+
+O executor vai implementar T1→T4 em sequência, marcando cada tarefa concluída.
+
+**Output esperado ao final:**
+```
+Onda 1 completa.
+T1 ✓ routes/items.js — route criada
+T2 ✓ controllers/items.js — ItemsController.list() implementado
+T3 ✓ services/items.js — ItemsService.findPaginated() implementado
+T4 ✓ tests/items.test.js — 4 testes de integração passando
+
+Estado: execute_complete
+```
+
+**Para executar uma tarefa específica:**
+```
+/oxe-execute --task T3
+```
+
+---
+
+## Passo 6 — Verificar
+
+```
+/oxe-verify
+```
+
+**Output esperado:**
+```
+Verificação completa.
+
+A1 ✓ GET /api/items retorna 200 — evidência: tests/items.test.js:12
+A2 ✓ Parâmetros page e limit validados — evidência: controllers/items.js:34
+A3 ✓ Resposta inclui {items, total, page, limit} — evidência: controllers/items.js:41
+A4 ✓ Testes cobrem A1–A3 — evidência: tests/items.test.js (4 testes)
+
+Riscos residuais: nenhum
+Estado: verify_complete
+```
+
+**Artefato gerado:** `.oxe/VERIFY.md`
+
+---
+
+## Passo 7 — Gate de aprovação (opcional, runtime-first)
+
+Se o projeto usa runtime gates:
+
+```bash
+npx oxe-cc runtime gates list --dir .
+```
+
+**Output esperado:**
+```
+Gates pendentes: 1
+  ⏳ gate-001  tipo: verify_complete  estado: pending
+               ação sugerida: approve
+               impacto: bloqueia promoção para pr_draft
+```
+
+Para aprovar:
+```bash
+npx oxe-cc runtime gates resolve --dir . --gate gate-001 --decision approve --actor "seu-nome"
+```
+
+**Output esperado:**
+```
+✓ Gate gate-001 aprovado.
+Run pode avançar para promoção — nenhum gate restante.
+```
+
+---
+
+## Passo 8 — Promover para PR draft
+
+```bash
+npx oxe-cc runtime promote --dir . --target pr_draft
+```
+
+**Output esperado:**
+```
+Promoção para pr_draft iniciada.
+Branch: feature/items-endpoint
+VERIFY.md incluído como evidência
+PR draft criado: https://github.com/seu-org/repo/pull/42
+```
+
+---
+
+## Estado final dos artefatos
+
+```
+.oxe/
+├── STATE.md          # fase: verify_complete (ou pr_draft após promote)
+├── SPEC.md           # critérios A1–A4 + B1–B2
+├── PLAN.md           # ondas e tarefas T1–T4
+├── VERIFY.md         # evidências para cada critério A*
+└── codebase/
+    └── map.json      # mapa do projeto
+```
+
+---
+
+## Validação rápida
+
+```bash
+npx oxe-cc status
+```
+
+**Output esperado:**
+```
+Estado: verify_complete
+Próximo passo: runtime promote --target pr_draft (ou abrir PR manualmente)
+SPEC: 4 critérios A* — todos verificados
+VERIFY.md: presente
+Gates pendentes: 0
+```
+
+---
+
+## Se algo der errado
+
+| Sintoma | Comando |
+|---------|---------|
+| Travado em uma tarefa | `/oxe-debug` |
+| Critério A* não verificado | `/oxe-verify` + revisar implementação |
+| Gate stale (>24h) | Ver [`docs/INCIDENT-PLAYBOOK.md`](INCIDENT-PLAYBOOK.md) |
+| Plano desatualizado | `/oxe-plan` novamente (sobrescreve PLAN.md) |
+| Estado incoerente | `npx oxe-cc status --full` + `/oxe` para rediagnóstico |

package/lib/runtime/scheduler/multi-agent-coordinator.d.ts

@@ -17,6 +17,7 @@ export interface CoordinationOptions {
     sessionId: string | null;
     runId: string;
     onEvent?: SchedulerContext['onEvent'];
+    heartbeatTimeoutMs?: number;
 }
 export interface ArbitrationRecord {
     work_item_id: string;
@@ -48,12 +49,36 @@ export interface MultiAgentStatusSnapshot {
         assigned_task_ids: string[];
         completed: string[];
         failed: string[];
+        timed_out: boolean;
+        reassigned_task_ids: string[];
     }>;
     orphan_reassignments: Array<{
         from_agent_id: string;
         to_agent_id: string;
         work_item_ids: string[];
     }>;
+    timed_out_agents: Array<{
+        agent_id: string;
+        work_item_ids: string[];
+        detected_at: string;
+    }>;
+    updated_at: string;
+}
+export interface MultiAgentOperationalSummary {
+    run_id: string;
+    mode: CoordinationMode;
+    workspace_isolation_enforced: boolean;
+    agent_count: number;
+    completed_count: number;
+    failed_count: number;
+    blocked_count: number;
+    ownership_count: number;
+    handoff_count: number;
+    arbitration_count: number;
+    orphan_reassignment_count: number;
+    timeout_count: number;
+    participating_agents: string[];
+    health: 'healthy' | 'degraded';
     updated_at: string;
 }
 export interface CoordinationResult {
@@ -70,9 +95,12 @@ export interface CoordinationResult {
     handoffs?: CooperativeHandoff[];
     arbitration_results?: ArbitrationRecord[];
     state?: MultiAgentStatusSnapshot;
+    summary?: MultiAgentOperationalSummary;
 }
 export declare class MultiAgentCoordinator {
     run(graph: ExecutionGraph, opts: CoordinationOptions): Promise<CoordinationResult>;
 }
 export declare function multiAgentStatePath(projectRoot: string, runId: string): string;
+export declare function multiAgentSummaryPath(projectRoot: string, runId: string): string;
 export declare function loadMultiAgentState(projectRoot: string, runId: string): MultiAgentStatusSnapshot | null;
+export declare function loadMultiAgentSummary(projectRoot: string, runId: string): MultiAgentOperationalSummary | null;