Arquitetura do núcleo do BeeverForge

Visão geral da arquitetura

O núcleo do BeeverForge recebe tickets de um quadro e conduz agentes de programação existentes pelo planejamento, implementação, validação, revisão, pull request, merge e observação da implantação. É um orquestrador: não contém um agente de programação próprio.

Esta seção descreve o núcleo como ele existe no repositório no commit indicado nas fontes de cada página. Quando um registro de design descreve algo que o código ainda não faz, a página informa isso.

Modelo de controle#

O README do projeto enuncia o modelo como “As políticas autorizam, as pessoas avaliam.” O manifesto do projeto, .beeverforge/project.yaml, declara a política de merge, o piso de qualidade e a cadeia de promoção. Dentro dessas políticas, a fábrica age sem pedir aprovação a cada passo; as pessoas julgam o resultado.

Um projeto que não declara um controle test não é considerado aprovado. Antes da passada de implementação, depois do dimensionamento, o executor verifica o piso e recusa o job, informando o controle que falta e como declará-lo.
A política de merge padrão é human: uma pessoa faz o merge do pull request. O merge automático só acontece quando um projeto define merge_policy: auto e todas as condições para isso são atendidas.
A promoção para produção aguarda uma aprovação humana. A aprovação chega ao workflow como uma resposta selada de uso único (veja A caixa e o piso de qualidade).
Quando um job não pode continuar, ele fica em espera no cartão com as opções que uma pessoa pode escolher, em vez de esperar em silêncio.

Modelo de camadas#

O documento de visão do núcleo representa o sistema como aplicações sobre uma camada de ações, um núcleo que decide, um motor que o conduz e provedores alcançados por portas. As capacidades são representadas como uma fronteira, não como uma camada: o núcleo e o motor alcançam os provedores pelo mesmo tipo de porta.

Camadas como aparecem no documento de visão, marcadas conforme o quanto o código realiza cada uma.

Camada	Onde está no código	Estado
Aplicações	`beeverforge/product/`, `beeverforge/techlead/`, `beeverforge/api/`	Realizado. O painel, o tech-lead e o papel de produto opcional.
Camada de ações	`beeverforge/actions/`	Realizado. Um catálogo pelo qual tanto a API do painel quanto a CLI executam.
Núcleo	`beeverforge/contracts/`, `beeverforge/policy/`, `beeverforge/lifecycle/`	Realizado em parte. O ciclo de vida do cartão é decidido por tabelas puras. O kernel de decisão puro para jobs proposto no ADR-0033 não existe; as transições dos jobs ainda são decididas dentro do executor e do workflow.
Motor	`beeverforge/runtime/temporal/`	Realizado sobre o Temporal. O motor não está atrás de uma porta própria.
Capacidades e provedores	`beeverforge/adapters/`	Realizado. Cada provedor é escolhido por um registro a partir da configuração.

O próprio documento de fronteiras do núcleo descreve orchestrator/machine.py como política do núcleo e execução do motor que hoje estão fundidas. A visão de um núcleo que só decide e de um motor que só executa é a direção do ADR-0033, registrado como proposto.

Forma de implantação#

As máquinas do próprio operador. A instalação padrão é docker compose em uma única máquina e não exige conta em nuvem (ADR-0040). Uma nuvem só é alcançada por pacotes complementares.
Serviços. O arquivo compose executa um banco de dados Postgres para o motor, um servidor Temporal, a interface web do Temporal, o worker e o painel. As portas publicadas são vinculadas a 127.0.0.1 por padrão.
O motor. O Temporal guarda o estado dos jobs. Cada job é um workflow durável: suas esperas e temporizadores sobrevivem a um reinício do worker, e um job cujo worker se perde durante a passada do agente fica em espera para que uma pessoa o retome ou pule.
A caixa. O worker executa cada job em uma caixa. O tipo padrão é container: um contêiner Docker descartável iniciado como irmão no daemon do host, pelo socket do Docker que o arquivo compose monta no worker.
Um único tenant, vários projetos. Uma instalação atende uma equipe com um registro de projetos. O registro contém qualquer número de projetos, cada um com seu próprio repositório, quadro e manifesto (ADR-0001, D-14).
Um job por vez por padrão. O número de jobs em andamento é BEEVERFORGE_MAX_CONCURRENT_JOBS, com padrão 1.

A instalação padrão. As portas publicadas ficam vinculadas a 127.0.0.1; a rede da caixa é descrita em A caixa e o piso de qualidade.

O worker tem o socket do Docker do host, o que lhe dá controle do daemon do Docker do host. A caixa padrão tem acesso total à rede de saída. Ambos são descritos com seus limites em A caixa e o piso de qualidade.

Fora do núcleo#

Os agentes de programação. O núcleo conduz ferramentas de linha de comando de agentes existentes por um único contrato de adaptador. Os tipos de harness da árvore são claude_code (o padrão), codex, kimi e opencode. Cada um chama o serviço do seu fornecedor; esse endpoint é um destino de rede de que toda instalação precisa.
Canais de chat. O núcleo é completo sem um conector de chat (ADR-0038). O único canal e notificador da árvore é o painel. Os adaptadores de Slack e Telegram são distribuídos em um pacote complementar separado e se registram pelo mesmo mecanismo de extensão de qualquer outro adaptador.
Executores e armazenamentos em nuvem. O núcleo não inclui nenhum executor de caixas remotas. O executor de tarefas remotas, a tabela de métricas em nuvem, o armazenamento remoto de sessões e o pool de tokens em nuvem são declarados como tipos de complementos.