🏛️ Decisões (ADR) 🏛️ Decisões (ADR) Git, repositório e política de branches Harness de agente, turnos e sessões ADR 0006 — Harness de agentes: montagem determinística de contexto ADR 0007 — ToolLoop, ferramentas, ContextManager (harness com LLM) ADR 0061 — O tipo da sessão é dado da criação, e a execução continua sendo evento ADR 0098 — Limites de transporte e janela efetiva de compactação coerentes ADR 0163 — O clique responde ao ACEITAR o comando, e o turno segue pelo canal ADR 0175 — O Infra Lead conversa pelo composer, e antes o turno dele passa pelo `TurnoAssincrono` ADR 0177 — O idioma das respostas mora em três lugares — conta, sessão e projeto —, em lista aberta de BCP-47 e nunca no `users.locale` ADR 0179 — O laço pergunta ao Jev qual ferramenta, e o modelo do usuário vê só o menu que sobra ADR 0183 — A sessão encerrada pode ser reaberta: uma saída própria dos terminais, para `active`, com evento novo ADR 0184 — Reabrir sessão: as três decisões do dono, e `developer` reabre ADR 0191 — A mensagem que chega com turno em curso entra numa fila persistida e é lida no fim do turno ADR 0226 — Diário vivo e retomada dos agentes: o turno interrompido volta uma vez, do plano ADR 0246 — Anexos do chat: bytes no Postgres, referência no evento, visão por capability ADR 0247 — Uma mensagem, vários destinatários ADR 0249 — O raciocínio do agente é gravado e mostrado só a developer ou mais ADR 0283 — A ADR proposta declara qual ADR substitui (`supersedes`) O time de agentes — papéis, áreas e handoffs ADR 0008 — Agente Criativo conversacional no harness + fundação de handoffs ADR 0009 — Agente PO, backlog (epics/stories/tasks) e rastreabilidade ADR 0010 — Agente Arquiteto: ADRs via PR real, module_map e validação cruzada ADR 0014 — InfraAgent e painel do time ao vivo (fechamento da Fase 4a) ADR 0015 — Psicólogo real: ToolLoop, hipóteses com evidência e triagem de custo ADR 0016 — Anamnese: perfil de proficiência, patches de instrução e loop fechado ADR 0022 — Fechamento da Fase 4b (sessão 1): evidência que chega, custo que aparece, análise que sobrevive ao kill ADR 0023 — Fechamento da Fase 4b (sessão 2): catálogo que funciona, dedup que distingue quem negou, e fila que sobrevive à rodada ADR 0038 — Hierarquia de agentes: áreas, leads e delegação ADR 0046 — Promoção de história com autoridade do usuário ADR 0053 — Dev Lead como área, e paralelismo autorizado pelo usuário ADR 0068 — Diagrama C4 do Arquiteto ADR 0069 — Fusão condicional do aceite do handoff com a ativação de execução ADR 0085 — Fluxo de papéis como registro declarativo (fluxo.yml) ADR 0086 — O plano do Dev Lead suspende o turno para aprovação ADR 0087 — O UX Designer entra como agente conversacional ADR 0088 — Staff: código pronto, dormente para disparo automático ADR 0089 — `analytics` e `delivery-metricas` viram script de relatório ADR 0092 — `platform` nasce como script de relatório sob demanda, não agente ADR 0093 — O papel `dbre` vira dois scripts: linter de migration e relatório de backup ADR 0094 — A delegação Dev Lead → dev vira dado, com `parecerArtifactId` redefinido ADR 0109 — Handoff manual a um agente à escolha reusa oferta+aceite, nunca um terceiro estado de handoff ADR 0182 — A oferta de handoff ganha ciclo de vida: uma pendente por destino, e `superseded` ADR 0185 — "Estou pronto — a necessidade está validada": um clique fecha a prontidão, o gate `necessidade-validada` e o aceite do PO ADR 0186 — O handoff do PO ao Arquiteto é aceito sem clique quando o backlog está coberto e o repositório é local ADR 0194 — Aprovar o plano do Dev Lead ativa a execução, e a tarefa ganha o módulo que ele atribui ADR 0212 — A história arquivada: uma coluna, não um estado da máquina ADR 0213 — O entregável roda na máquina do usuário pelo compose da Infra ADR 0259 — O módulo de que outros dependem tem dono no plano de execução ADR 0261 — O Dev Lead é avisado de bloqueios e pede ao Arquiteto por um canal próprio ADR 0262 — O agente retira a regra de negócio obsoleta, citando a substituta ou a resposta Gates, QA e revisão de segurança Execução, política de terminal e aprovações ADR 0011 — Infraestrutura dos dev agents: worktrees, executores git e trava de merge ADR 0012 — DevAgent real: ToolLoop, orçamento por task e disciplina de bloqueio ADR 0017 — Lock de inicialização do workspace, Monitor de dev agents e herança de teto ADR 0018 — NoopDevAgent como modo de execução permanente ADR 0019 — Destravar o DevAgent real: escrita, terminal, ADR por módulo e orçamento por projeto ADR 0045 — Reagendamento por evento do dev agent, e o circuit breaker ADR 0047 — Operabilidade pós-dogfooding: o fechamento da Fase 12 ADR 0048 — A decisão no event log, e a ordem do gate ADR 0052 — O dev agent espera a aprovação no meio do laço ADR 0055 — Escopo de caminho na política de terminal ADR 0102 — Revisão do ADR 0065: a fronteira de efeito externo deixa de ser `deny` e vira teto absoluto ADR 0167 — O modo automático libera o escopo de caminho, e só ele ADR 0189 — O piloto automático: o modo automático aprova tudo, menos os tetos, o escopo compara com a pasta real de execução, e "Sempre permitir" grava verbo + subcomando ADR 0204 — O modo automático libera push e PR Onde o código mora — modos de execução Container do projeto e broker ADR 0065 — Container por projeto: a fronteira deixa de ser política ADR 0081 — Ciclo de vida do container: tabela de estado, sem orquestrador ADR 0083 — A aba Terminal ganha o consumidor real do ciclo de vida, não o terminal ADR 0128 — A porta de Docker, e a prova de empacotamento que escolheu a implementação ADR 0130 — O broker de container: quem fala com o Docker do servidor, e por que ele não aceita especificação ADR 0131 — O Arquiteto roteia módulos para infra: ele CANDIDATA, a Infra ELEGE ADR 0133 — A Infra elege entre as candidatas do roteamento, e a eleição vira nova versão de `artifact.project_image` ADR 0134 — Dev agents executam DENTRO do container real do projeto, e o terminal ganha um piso de auto-aprovação lá dentro ADR 0135 — O portão da imagem do Arquiteto (RN-105) passa a valer nos três modos de execução ADR 0136 — Página global de containers: teto por carga no broker, e `container_remove` no teto absoluto ADR 0137 — O `brabo-runner` sobe o container do projeto na máquina do usuário ADR 0143 — Agentes de dev só depois do container ADR 0144 — A segunda raiz do broker, e o localizador discriminado que a escolhe ADR 0180 — O container do projeto roda com o dono da pasta, medido pela api ADR 0190 — A Infra sobe o container no aceite do handoff, por passo do servidor e com a autonomia semeada, e é ela quem entrega ao Dev Lead ADR 0199 — O recurso mínimo do container é derivado do `module_map`: cada módulo declara o seu, e a Infra sobe com a soma ADR 0208 — A Infra herda a rede que o Arquiteto declarou ADR 0228 — O container do projeto sobe o app pelo comando declarado e publica porta só no loopback ADR 0229 — O QA testa numa instância efêmera, com os serviços que a Infra declarou ADR 0264 — Depois do avanço da pasta, o app reinicia só o processo, sem recriar o container ADR 0265 — O app declarado pela Infra propõe recriar o container, com a porta na faixa 13000+ O runner local Autenticação, acesso e segredos ADR 0031 — Auth first-party: argon2id, EdDSA e rotação de refresh ADR 0032 — O corte do Keycloak: emissor próprio, service token e sessão em cookie ADR 0037 — O CORS que o engine não tinha, e a porta como parte do contrato ADR 0050 — Credencial sempre cifrada; verificação vira ação explícita ADR 0058 — CSP fechado na api, e o escopo de projeto contido na raiz ADR 0059 — A chave que assina o `state` do OAuth de git não tem default ADR 0084 — Login social (GitHub/GitLab), revisando o backlog dos ADRs 0031/0032 ADR 0096 — SMTP real no `MailSender`, atrás de um toggle explícito ADR 0127 — Dois tetos de rebaixamento em `project_members`, e a sobreposição fica ADR 0156 — O teto de auto-rebaixamento também na remoção de membro de projeto ADR 0157 — O teto de auto-movimento no upsert de workspace, e a auto-promoção que era brecha ADR 0158 — O id da chave mestra gravado no envelope, como observabilidade e nunca como autoridade ADR 0173 — A remoção de membro de workspace nasce, protegida pela mesma cláusula ADR 0245 — Acesso rápido por papel só no ambiente local Providers de LLM, modelos e gasto ADR 0040 — Moeda do dashboard: USD por ora, câmbio manual por workspace adiado ADR 0041 — Uma base OpenAI-compatível, um contrato de LLM providers e capabilities que recusam binding ADR 0042 — Catálogo vivo, ciclo de vida do modelo e preço auditável ADR 0043 — Seis providers de LLM sobre a base, e a Fase 9b finalmente fechada ADR 0049 — Curadoria de modelo por workspace ADR 0051 — Facetas de capability provadas; "para que serve" é curadoria ADR 0063 — Duas audiências para o mesmo gasto: a fatura do owner e o consumo do membro ADR 0064 — Escopo de área na cascata de modelo, e o binding de agente global ADR 0075 — Embeddings no contrato de LLMProvider ADR 0076 — `provider` volta a ser dimensão de gasto, e a contenção passa a ser do tipo ADR 0077 — Ranking de modelos por capacidade, sem nota inventada ADR 0110 — Orçamento por área é ADITIVO, ao lado de projeto/sessão — não uma cascata, e não uma tabela nova ADR 0114 — Detecção de Ollama nativo no bootstrap de dev: perguntar uma vez, persistir no `.env`, pôr os serviços do compose atrás de um profile ADR 0115 — Pull de modelo do Hugging Face: tabela própria, confirmação em dois passos e allowlist de publicadores oficiais — nunca `proposed_actions` ADR 0166 — A preferência de roteamento mora no binding de modelo, viaja com ele, e congela no metering ADR 0188 — O custo real que o provider devolve vira o número do metering ADR 0198 — A duplicata semântica de história e regra é avisada por embedding com limiar, e o gasto entra no metering ADR 0221 — O hub prende a conversa de cada agente ao upstream que a atendeu, por `session_id` ADR 0222 — O 9Router entra como o 10º provider de LLM, com URL por instalação ADR 0223 — O orçamento de raciocínio é capability POR MODELO, curada à mão ADR 0224 — O raciocínio é contado no stream e abortado no limite, e o custo é estimado e reconciliado ADR 0225 — O OpenRouter recebe um teto de preço por chamada (`provider.max_price` = catálogo × 1,5) ADR 0227 — O OpenCode Zen entra como o 11º provider de LLM, só no dialeto OpenAI ADR 0233 — O membro vê o gasto do projeto por agente e por área, nunca por provider ADR 0251 — Preço de lista datado no código para provider que não informa preço ADR 0257 — Na Anthropic direta o raciocínio desligado é por modelo e o esforço reduz o Opus ADR 0279 — Provider de LLM dublê do regressivo, dentro da api RAG, grafo de conhecimento e artefatos ADR 0079 — Tabela de chunks: vetor e `tsvector` na mesma linha ADR 0080 — Busca híbrida: pesos, limiar e o que é citação ADR 0082 — Chat RAG: aba própria de busca híbrida, sem renomear "Chat" ADR 0099 — Neo4j como grafo de conhecimento e templates de prompt, driver na api ADR 0100 — `rag_search` para agentes e modelos Ollama garantidos no boot ADR 0101 — Memória relacional como projeção do event log; templates consumidos sem tocar GenServers ADR 0113 — Pasta local anexada vira `chunks.scope = 'local'`, lida pelo NAVEGADOR, nunca um caminho do host ADR 0129 — A telemetria de busca do RAG é TABELA, com os pesos congelados na linha ADR 0132 — Golden-set de acerto do RAG, e o gate `rag-acertivo` ADR 0138 — O golden-set do RAG passa a rodar em CI, agendado — e continua `warn` ADR 0148 — Os artefatos dos agentes projetados em arquivo, numa pasta `docs/` ADR 0196 — A Anamnese religada: não roda sem sujeito, e a hipótese aceita vira fato do perfil ADR 0200 — O contrato entre módulos vira artefato versionado do Arquiteto, e o dev agent o lê em vez do worktree alheio ADR 0205 — O desvio do agente que a Anamnese observa vira sinal do produto, sem dado pessoal ADR 0269 — A indexação de docs tem teto próprio de 4 MiB, e o corte é declarado ADR 0272 — A busca híbrida do RAG limita os trechos por arquivo Interface web e design system ADR 0036 — Telas de auth fiéis ao design, e as três fontes que não carregavam ADR 0060 — A superfície de leitura de código, contida e com orçamento ADR 0074 — Tema alcançável, e o boot sob CSP ADR 0078 — Moldura de tela, e o registro de abas diverge do handoff de propósito ADR 0097 — Leitura direta do schema do engine para o "N agentes online" do dashboard ADR 0116 — `ActionType` (e tipos futuros) gerados do contrato OpenAPI, não copiados à mão ADR 0122 — `SessionPage.tsx` dividido em cinco PRs mecânicos, declarados de antemão ADR 0124 — Agrupamento de estado do canal de turno extraído para `useTurnoDoAgente` ADR 0125 — `ProjectSettingsTab.tsx` dividido em um arquivo por seção, atrás de um barrel ADR 0126 — A página do projeto navega por um trilho vertical, e a aba Código para de recolher a sidebar sozinha ADR 0176 — `SessionPage.tsx` abaixo de 1 000 linhas, em dez PRs mecânicos, e a trava só depois ADR 0181 — O tema escuro vira preto neutro, e a dívida de contraste acaba ADR 0210 — Animação de texto com `motion` ADR 0211 — Uma navegação só: a sidebar absorve o trilho do projeto ADR 0232 — shadcn/ui com Base UI e Tailwind 4 no `apps/web` ADR 0234 — `shiki` no Code Block e `recharts` no Chart, sempre por carga dinâmica ADR 0237 — O visual v3 liga o preflight e sobe os raios ADR 0238 — O grafo de módulos da Arquitetura vira Canvas (`@xyflow/react`) ADR 0239 — CSP `frame-src` local para o Web preview do entregável ADR 0240 — O motivo de controle inerte pode morar num "?" ativo na página de Containers ADR 0241 — A sidebar adota o block `sidebar-07` do shadcn ADR 0242 — Containers em tabela linear com `@tanstack/react-table` ADR 0243 — Consequência irreversível pode morar num botão de perigo ADR 0244 — Coluna das abas do projeto alinhada à esquerda ADR 0248 — O conteúdo das páginas ocupa a largura inteira ADR 0250 — O chat da Sessão ocupa a largura inteira Operação, deploy e instalação ADR 0024 — Fase 5 (sessão 1): imagens de produção, compose.prod, CI e teste de fumaça ADR 0025 — Fase 5 (sessão 2): deploy Kubernetes com Kustomize, métrica de fila e overlay local ADR 0026 — Fase 5 (sessão 3): graceful shutdown, OpenTelemetry, métricas, logs e dashboards ADR 0027 — Backup/restore, hardening da api, superfície exposta e release ADR 0035 — Trace sem coletor, e o caminho entre camadas no log ADR 0070 — Observabilidade no Compose local: métrica e log, sem trace ADR 0150 — O instalador de uma linha, com fonte escolhida e marcador ADR 0152 — Backup e restore de volumes, contra compose ADR 0153 — `DEPLOY_ENABLED`: o gatilho que dez documentos citam e nenhum cria ADR 0155 — A primeira conta nasce no terminal, e o agente local sobe pareado ADR 0160 — O compose do instalador viaja com ele, como asset assinado ADR 0161 — A tela só oferece o modo que a instalação executa, e a instalação por Release não tem broker ADR 0162 — O broker vira a quinta imagem publicada, e o instalador PERGUNTA se o liga ADR 0169 — O destino S3 do overlay local deixa de ser o MinIO e passa a ser o SeaweedFS ADR 0170 — O compose de dev vira `brabo-dev`, e o dev recusa subir ao lado de uma instalação ADR 0209 — O engine sobe para Elixir 1.20.4 / OTP 29.1.1 ADR 0256 — A migração do instalador restaura o banco num banco recém-criado e vazio CI, release e cadeia de suprimentos ADR 0039 — actionlint e a validação do pipeline de CI gerado ADR 0119 — Imagens publicadas no GHCR a cada tag final, e o overlay de produção preso por digest ADR 0120 — E2E de navegador contra o compose de produção, num pacote fora do workspace ADR 0121 — O schema dividido por agregado de domínio, atrás de um barrel ADR 0140 — Timeout repetido do `pnpm audit` é risco assumido; achado continua reprovando ADR 0149 — Assinatura dos artefatos publicados ADR 0159 — Imagem de terceiro entra por digest, e o lint reprova quem esquecer ADR 0172 — O release escaneia com Trivy o que publica, por digest, antes de assinar ADR 0178 — A tag da imagem de terceiro mora DENTRO da referência, antes do digest ADR 0197 — A imagem dos workflows vem do compose, e o Dependabot de imagem é ligado ADR 0252 — O Brabo vira um conjunto de repositórios em `viralabs-dev` ADR 0268 — O `brabo-qa` tem regressivo por funcionalidade, e o da PR para a `dev` nunca é exigido ADR 0270 — O brabo-contracts é publicado no GitHub Packages, com o `shared` só de tipos ADR 0271 — Cada run do Actions mostra os vínculos entre os repositórios ADR 0277 — O regressivo roda num compose só; o grafo mostra cada funcionalidade por uma matrix de exibição, e o relatório é a fonte da decisão ADR 0278 — A mudança é vista num painel do brabo-ci, sem check nas PRs ADR 0280 — O pin do brabo-ci nos consumidores aponta para uma tag, e a branch decide qual ADR 0281 — O mapa dos 11 repos tem uma fonte só, o `repos.yml` do `brabo`, e o README é gerado dela ADR 0282 — A pin dos componentes segue a última Release final ADR 0285 — A prova de uma aresta do `repos.yml` é arquivo mais trecho literal, não arquivo:linha ADR 0286 — As capturas da doc são geradas pelo brabo-qa e entram no brabo por PR do App Documentação ADR 0029 — Sincronização contínua da documentação ADR 0033 — A referência de API sai do código, e o teste de tabela cobra os metadados ADR 0034 — Documentação publicada por degrau, em subdiretório do Pages ADR 0071 — Publicação simétrica por degrau, e uma raiz que escolhe ADR 0073 — O caminho publicado nomeia o ambiente, não a branch ADR 0117 — `website/` ganha lockfile próprio, fora do `pnpm audit` do produto ADR 0202 — O índice de ADR por tema, com o tema fora do ADR ADR 0206 — A referência da API vira uma página Redoc ADR 0216 — Quatro idiomas, com pt-BR como FONTE e padrão: a documentação e a interface em português, inglês, russo e chinês simplificado ADR 0218 — Todo ADR se chama "ADR NNNN — título" ADR 0219 — A referência entra na tradução ADR 0220 — A página da API sai traduzida por catálogo ADR 0253 — O site de docs deixa o Docusaurus ADR 0254 — A doc de cada área mora na raiz dela ADR 0260 — A doc dos repos de código é só em inglês; o site serve a fonte inglesa com faixa ADR 0266 — A doc dos repositórios é em pt-BR por padrão, com traduções permitidas nos irmãos ADR 0273 — A paridade de tradução mede só a doc do brabo ADR 0274 — Os gerados do `brabo` leem os irmãos por uma trava de SHAs ADR 0275 — Cada irmão confere as próprias refs com símbolo no PR ADR 0287 — O índice de ADR é gerado, e a referência grande vira índice mais partes ADR 0288 — O link entre repos nas RNs é a URL do repo dono, e o site a devolve para relativo
ADR 0280 — O pin do brabo-ci nos consumidores aponta para uma tag, e a branch decide qual
Status: aceito (08/11/2026, decisão do dono, AT-817)Data: 2026-11-08Tema: engenhariaReferencia: ADR 0252 , ADR 0159, ADR 0236. AT-816, AT-819 e AT-827. Sem RN: é CI, não regra do produto.
Contexto
Os pins uses: viralabs-dev/brabo-ci/...@<sha> usavam comentários como # dev, # feature/x ou nenhum. O Dependabot só atualiza pin cujo comentário é uma versão, então os pins congelavam sem aviso.
Havia 5 SHAs diferentes entre os 11 repos, e nada conferia que o comentário correspondia ao SHA.
Decisão
O comentário do pin tem a forma vX.Y.Z ou vX.Y.Z-dev.N, e o SHA é o da tag citada.
Na dev do consumidor, o pin pode apontar para uma tag -dev.N. Na main, só para uma release final.
A promoção dev → main de cada consumidor troca o pin -dev.N pela release final.
A regra é o job informativo pins-do-brabo-ci do reutilizável cadeia.yml (scripts/ci/pins-do-brabo-ci.ts). Ele recebe a branch alvo e roda nos consumidores pelo ci.yml.
Alternativas rejeitadas
(a) Só versão final em dev e main. Uma correção do brabo-ci só chegaria aos consumidores depois da promoção do próprio brabo-ci.(c) -dev.N em qualquer branch. A main rodaria código que só existe na dev.
Consequências
O brabo-ci passa a ser testado cedo nos consumidores.
A promoção ganha um passo, e a regra o cobra.
O Dependabot subir um -dev.N para o próximo ainda não foi medido. O ci_ref continua à mão.
A regra nasce informativa e vira obrigatória depois do repin dos 11 repos.