BK-157 · Superfície única de visibilidade/orquestração Studio + OpenGravity + CLI

Criado em: 2026-03-19

Escopo: cerebro / studio / OpenGravity

Responsável: codex

Prioridade: média

Status: CONCLUÍDO em 2026-04-09

1. Problema

Hoje a coordenação real dos agentes/programadores ainda depende de copy/paste manual entre chat, terminal, Studio e OpenGravity.

Na prática isso gera:

• perda de contexto sobre quem está fazendo o quê;
• dificuldade para saber qual prompt ainda está "em andamento" e qual já respondeu;
• risco de enviar novo prompt para a mesma frente antes da resposta anterior;
• dificuldade para enxergar ownership, branch, repo, locks e estado de fechamento;
• baixa visibilidade do trabalho que já está rodando fora desta conversa.

O objetivo deste BK é abrir a trilha para uma superfície única, operacional e confiável, onde seja possível acompanhar os agentes/programadores sem depender de retransmissão manual pelo operador humano.

2. Resultado esperado

Ter uma superfície única de acompanhamento, preferencialmente via Studio e/ou OpenGravity, capaz de mostrar pelo menos:

• agente/programador;
• função atual;
• repositório alvo;
• BK ativo;
• branch atual;
• arquivos tocados;
• heartbeat/presença;
• status da frente (ativo, aguardando resposta, pronto para revisão, pronto para fechamento, bloqueado);
• locks relacionados;
• pendências de fechamento/governança.

3. Tese de implementação

Não começar por automação total de fechamento nem por "agent fleet" visual bonito. O primeiro ganho real é observabilidade operacional unificada.

Tese:

1. reaproveitar o que já existe;
2. consolidar metadados de presença/execução;
3. exibir isso em uma superfície única;
4. só depois pensar em ações operacionais de fechamento ou despacho.

Base já existente para reaproveitar:

• tools/cli_session_presence.sh
• docs/ORQUESTRACAO_MULTI_CLI.md
• runtime do Studio
• estado/health do Cérebro
• módulo OpenGravity
• docs/LOCK.md
• docs/BACKLOG.md

4. Decisão de Arquitetura (2026-04-09)

4.1 Superfície Principal

O Studio é a superfície principal. O OpenGravity é um módulo complementar.

Justificativa:

• O Studio já oferece interface HTTP acessível (porta 9903), WebSocket para eventos em tempo real, histórico de sessões persistido, e integração nativa com o kernel do Cérebro.
• O OpenGravity, embora seja um agente completo (bot, memória, ferramentas), opera como fonte de eventos e não como superfície de visibilidade consolidada.
• A CLI (tools/cli_orchestrator.sh, tools/cli_session_presence.sh) permanece como infraestrutura de execução, mas a visualização centralizada deve residir no Studio.

4.2 Fontes de Estado

| Fonte | Tipo | Conteúdo | Como consumir |

|-------|------|----------|----------------|

| tools/cli_session_presence.sh | Arquivo + WS | agent, function, repo, BK, branch, status, heartbeat, timestamp | Script de registro + consumo via studio_ws events |

| docs/LOCK.md | Arquivo markdown | caminho_repo, BK, responsavel, status, observacao | Parse do quadro canonico |

| docs/BACKLOG.md | Arquivo markdown | Itens de backlog vivo e status | Parse do indice central |

| kernel/observability.js | Runtime JS | Eventos de LLM (llm_start, llm_attempt, llm_finish, llm_fail) | Consumir via observability-summary.js |

| studio/server.js | Runtime HTTP/WS | Sessões ativas, histórico, health | API REST + WS events |

| OpenGravity | Módulo externo | Eventos de agente (via Telegram ou arquivo) | Consumir como fonte de eventos, não como superfície |

4.3 Contrato Mínimo de Eventos

Para o painel read-only, o Studio deve expor:

```json

{

"type": "orchestration_state",

"timestamp": "2026-04-09T18:50:00Z",

"agents": [

{

"id": "codex",

"function": "documentacao",

"repo": "cerebro",

"bk": "BK-157",

"branch": "vps/BK-157-studio-opengravity-orchestration-visibility",

"status": "ativo",

"files": ["docs/LOCK.md", "docs/BACKLOG.md"],

"heartbeat": "2026-04-09T18:49:00Z"

}

],

"locks": [...],

"backlog_pending": [...]

}

```

Este contrato pode ser consumido via:

• studio_ws event orchestration_state (push)
• GET /api/orchestration/state (pull, para dashboard read-only)

5. MVP Read-Only (2026-04-09)

O MVP read-only já existe parcialmente no Studio:

5.1 O que já existe

• Aba Locks no Studio (/locks) — quadro canonico de locks com status.
• Aba Backlog no Studio (/backlog) — indice de backlogs com status.
• Aba Changelog no Studio (/changelog) — indice de entregas.
• Observabilidade (/observabilidade) — eventos de LLM, métricas, status.
• Terminal com histórico de sessões — sessão ativa, engine, histórico.

5.2 O que falta (próximos passos)

• Painel unificado de "agentes ativos" consolidando cli_session_presence + locks + backlog.
• Exibição de heartbeat/presença em tempo real.
• Alertas visuais de conflito (dois agents no mesmo arquivo, branch divergente da main, etc.).
• Integração do OpenGravity como fonte de eventos no mesmo painel.

6. Próximos Passos (follow-ups)

| ID | Descrição | Dependência | Prioridade |

|----|-----------|--------------|------------|

| OG-01 | Painel unificado de agentes ativos no Studio (read-only) | BK-157 (este) | alta |

| OG-02 | Exibir heartbeat/presença em tempo real | OG-01 | média |

| OG-03 | Alertas visuais de conflito (locks, branch drift) | OG-01 | média |

| OG-04 | Integrar eventos do OpenGravity como fonte no painel | BK-157 + BK-114 | baixa |

| OG-05 | API /api/orchestration/state para consumo externo | OG-01 | baixa |

7. Critérios de Aceite (cumpridos em 2026-04-09)

• [x] Artefato técnico de arquitetura criado (docs/architecture/BK-157-STUDIO-OPENGRAVITY-CLI-MVP.md).
• [x] Fontes de estado mapeadas e documentadas.
• [x] Contrato mínimo de eventos definido.
• [x] MVP read-only explicitado (o que já existe no Studio, o que falta).
• [x] Decisão explícita: Studio é a superfície principal, OpenGravity é módulo complementar.
• [x] Próximos passos identificados em follow-ups.

8. Path List (lock-files)

```

/root/cerebro/docs/LOCK.md

/root/cerebro/docs/BACKLOG.md

/root/cerebro/docs/CHANGELOG.md

/root/cerebro/docs/architecture/BK-157-STUDIO-OPENGRAVITY-CLI-MVP.md

/root/cerebro/docs/changelog/2026/CL-2026-04-09-BK-157.md

/root/cerebro/docs/backlog/BK-157-studio-opengravity-orchestration-visibility.md

```

9. Referências

• /root/cerebro/docs/ORQUESTRACAO_MULTI_CLI.md
• /root/cerebro/docs/BACKLOG.md
• /root/cerebro/docs/LOCK.md
• /root/cerebro/OpenGravity/
• /root/cerebro/studio/
• /root/cerebro/kernel/observability.js
• /root/cerebro/tools/cli_session_presence.sh