Decisões arquiteturais
Um ADR registra por que algo foi decidido, no momento em que foi decidido. Eles são imutáveis: nenhum ADR é editado depois de aceito. Quando uma decisão muda, nasce um ADR novo que substitui o anterior — foi o que aconteceu com o 0018, que registra a substituição do NoopDevAgent decidida no 0011.
Consequência prática: um ADR pode descrever um estado que não é mais o atual. Para o estado atual, use Regras de negócio, Arquitetura e o Runbook. Para o raciocínio, venha aqui.
A tabela abaixo é gerada (pnpm docs:generate, ADR 0287): número, título e status de cada ADR, em um tema só. Use o filtro por tema e por status, ou a busca do site. O texto completo de cada decisão está no próprio ADR.
O status vem da seção ## Status do ADR; sem ela, vale aceito. O tema mora em docs/adr/temas.yml, ao lado desta página, e não no ADR, porque ADR aceito nunca é editado (ADR 0202); o pnpm docs:check reprova ADR sem tema.
Temas: Git, repositório e política de branches · Harness de agente, turnos e sessões · O time de agentes — papéis, áreas e handoffs · Gates, QA e revisão de segurança · Execução, política de terminal e aprovações · Onde o código mora — modos de execução · Container do projeto e broker · O runner local · Autenticação, acesso e segredos · Providers de LLM, modelos e gasto · RAG, grafo de conhecimento e artefatos · Interface web e design system · Operação, deploy e instalação · CI, release e cadeia de suprimentos · Documentação
Git, repositório e política de branches
O contrato do provider de git, o nascimento e a adoção do repositório, a proteção e a política de branches.
| # | decisão | status |
|---|---|---|
| 0001 | Formato do contrato normalizado do GitProvider | aceito |
| 0002 | Normalização de erros do GitProvider | aceito |
| 0003 | Política de retry para providers remotos | aceito |
| 0004 | Cadastro de credenciais de git do usuário | aceito |
| 0005 | Bootstrap de Gitflow idempotente e retomável | aceito |
| 0028 | Proteção de branch: divergência entre providers e a matriz de aprovação | aceito |
| 0030 | Política de branches mecanizada | aceito |
| 0044 | Adoção de repositório existente, e o plano como portão | aceito |
| 0056 | O engine trabalha em repositório remoto | aceito |
| 0139 | O alarme de merge de esteira ganha destinatário, e a regra de dev |
aceito |
| 0165 | O repositório nasce no aceite do handoff ao Arquiteto, e a execução não começa sem ele | aceito |
| 0217 | Promoção automática dev → qa enquanto a QA está em fase de teste |
aceito |
| 0235 | A qa é aposentada por hora e a esteira do repositório fica dev → main |
aceito |
| 0236 | O Dependabot dispensa revisão na dev e fica mergeável com os outros checks verdes |
aceito |
| 0255 | A política de PR é obrigatória em todos os repositórios e a PR de regeneração do bot dispensa a escada na dev | aceito |
| 0263 | O projeto do usuário trabalha em trunk, e a pasta acompanha a main | aceito |
| 0267 | O E2E do brabo-qa é portão da main, com aceite justificado | aceito |
| 0276 | A PR declara de que PR de outro repo depende, e um check do App espera o merge | aceito |
| 0284 | A promoção infere as dependências pela ordem dos repos | aceito |
Harness de agente, turnos e sessões
Como um agente roda — contexto, o laço de ferramentas, o turno conversacional, a sessão e seus estados.
| # | decisão | status |
|---|---|---|
| 0006 | Harness de agentes: montagem determinística de contexto | aceito |
| 0007 | ToolLoop, ferramentas, ContextManager (harness com LLM) | aceito |
| 0061 | O tipo da sessão é dado da criação, e a execução continua sendo evento | aceito |
| 0098 | Limites de transporte e janela efetiva de compactação coerentes | aceito |
| 0163 | O clique responde ao ACEITAR o comando, e o turno segue pelo canal | aceito |
| 0175 | O Infra Lead conversa pelo composer, e antes o turno dele passa pelo TurnoAssincrono |
aceito |
| 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 |
aceito |
| 0179 | O laço pergunta ao Jev qual ferramenta, e o modelo do usuário vê só o menu que sobra | aceito |
| 0183 | A sessão encerrada pode ser reaberta: uma saída própria dos terminais, para active, com evento novo |
aceito |
| 0184 | Reabrir sessão: as três decisões do dono, e developer reabre |
aceito |
| 0191 | A mensagem que chega com turno em curso entra numa fila persistida e é lida no fim do turno | aceito |
| 0226 | Diário vivo e retomada dos agentes: o turno interrompido volta uma vez, do plano | aceito |
| 0246 | Anexos do chat: bytes no Postgres, referência no evento, visão por capability | aceito |
| 0247 | Uma mensagem, vários destinatários | aceito |
| 0249 | O raciocínio do agente é gravado e mostrado só a developer ou mais | aceito |
| 0283 | A ADR proposta declara qual ADR substitui (supersedes) |
aceito |
O time de agentes — papéis, áreas e handoffs
Quais agentes existem, o que cada um entrega a quem, a delegação dentro de uma área e o handoff entre eles.
| # | decisão | status |
|---|---|---|
| 0008 | Agente Criativo conversacional no harness + fundação de handoffs | aceito |
| 0009 | Agente PO, backlog (epics/stories/tasks) e rastreabilidade | aceito |
| 0010 | Agente Arquiteto: ADRs via PR real, module_map e validação cruzada | aceito |
| 0014 | InfraAgent e painel do time ao vivo (fechamento da Fase 4a) | aceito |
| 0015 | Psicólogo real: ToolLoop, hipóteses com evidência e triagem de custo | aceito |
| 0016 | Anamnese: perfil de proficiência, patches de instrução e loop fechado | aceito |
| 0022 | Fechamento da Fase 4b (sessão 1): evidência que chega, custo que aparece, análise que sobrevive ao kill | aceito |
| 0023 | Fechamento da Fase 4b (sessão 2): catálogo que funciona, dedup que distingue quem negou, e fila que sobrevive à rodada | aceito |
| 0038 | Hierarquia de agentes: áreas, leads e delegação | aceito |
| 0046 | Promoção de história com autoridade do usuário | aceito |
| 0053 | Dev Lead como área, e paralelismo autorizado pelo usuário | aceito |
| 0068 | Diagrama C4 do Arquiteto | aceito |
| 0069 | Fusão condicional do aceite do handoff com a ativação de execução | aceito |
| 0085 | Fluxo de papéis como registro declarativo (fluxo.yml) | proposto |
| 0086 | O plano do Dev Lead suspende o turno para aprovação | aceito |
| 0087 | O UX Designer entra como agente conversacional | aceito |
| 0088 | Staff: código pronto, dormente para disparo automático | aceito |
| 0089 | analytics e delivery-metricas viram script de relatório |
aceito |
| 0092 | platform nasce como script de relatório sob demanda, não agente |
aceito |
| 0093 | O papel dbre vira dois scripts: linter de migration e relatório de backup |
aceito |
| 0094 | A delegação Dev Lead → dev vira dado, com parecerArtifactId redefinido |
aceito |
| 0109 | Handoff manual a um agente à escolha reusa oferta+aceite, nunca um terceiro estado de handoff | aceito |
| 0182 | A oferta de handoff ganha ciclo de vida: uma pendente por destino, e superseded |
aceito |
| 0185 | "Estou pronto — a necessidade está validada": um clique fecha a prontidão, o gate necessidade-validada e o aceite do PO |
aceito |
| 0186 | O handoff do PO ao Arquiteto é aceito sem clique quando o backlog está coberto e o repositório é local | aceito |
| 0194 | Aprovar o plano do Dev Lead ativa a execução, e a tarefa ganha o módulo que ele atribui | aceito |
| 0212 | A história arquivada: uma coluna, não um estado da máquina | aceito |
| 0213 | O entregável roda na máquina do usuário pelo compose da Infra | aceito |
| 0259 | O módulo de que outros dependem tem dono no plano de execução | aceito |
| 0261 | O Dev Lead é avisado de bloqueios e pede ao Arquiteto por um canal próprio | aceito |
| 0262 | O agente retira a regra de negócio obsoleta, citando a substituta ou a resposta | aceito |
Gates, QA e revisão de segurança
O registro de gates, os vereditos de QA e SecOps e os golden-sets que os medem.
| # | decisão | status |
|---|---|---|
| 0013 | Gates de PR: QAAgent e SecOpsAgent | aceito |
| 0020 | Destravar os gates de QA e SecOps: gitleaks na árvore, pareceres validados e tool call em texto | aceito |
| 0021 | Fechamento da Fase 4a: gate de infra que valida, e painel que diz a verdade | aceito |
| 0054 | Gates como registro declarativo | proposto |
| 0057 | O agente de gate espera a aprovação, como o dev espera | aceito |
| 0067 | O gate sobrevive ao restart | aceito |
| 0090 | QA-estratégia e AppSec como segundo MOMENTO, não agente novo | aceito |
| 0091 | secops-runtime como script de relatório sobre rate_limit_hits |
aceito |
| 0095 | O gate necessidade-validada se fecha com confirmação humana separada, não com o Criativo se autovalidando |
aceito |
| 0123 | Golden-set de casos de regressão para o julgamento semântico do agente de QA Automação | aceito |
| 0168 | O golden-set do QA passa a rodar em CI, agendado e semanal | aceito |
| 0192 | O plano de teste nasce depois da entrega do dev, e o gate implementavel passa a se julgar sobre a história e o module_map |
aceito |
| 0207 | Ciclo de gate parado há mais de 2 h estaciona, e só gesto humano o retoma | aceito |
| 0214 | Pergunta em aberto vira pendência a resolver | aceito |
| 0215 | A decisão do projeto chega ao dev e ao QA | aceito |
| 0258 | A resposta dada pelo chat fecha a pergunta em aberto | aceito |
Execução, política de terminal e aprovações
O dev agent trabalhando, proposed_action, a política de terminal, o escopo de caminho, o modo automático e os tetos absolutos.
| # | decisão | status |
|---|---|---|
| 0011 | Infraestrutura dos dev agents: worktrees, executores git e trava de merge | aceito |
| 0012 | DevAgent real: ToolLoop, orçamento por task e disciplina de bloqueio | aceito |
| 0017 | Lock de inicialização do workspace, Monitor de dev agents e herança de teto | aceito |
| 0018 | NoopDevAgent como modo de execução permanente | aceito |
| 0019 | Destravar o DevAgent real: escrita, terminal, ADR por módulo e orçamento por projeto | aceito |
| 0045 | Reagendamento por evento do dev agent, e o circuit breaker | aceito |
| 0047 | Operabilidade pós-dogfooding: o fechamento da Fase 12 | aceito |
| 0048 | A decisão no event log, e a ordem do gate | aceito |
| 0052 | O dev agent espera a aprovação no meio do laço | aceito |
| 0055 | Escopo de caminho na política de terminal | aceito |
| 0102 | Revisão do ADR 0065: a fronteira de efeito externo deixa de ser deny e vira teto absoluto |
aceito |
| 0167 | O modo automático libera o escopo de caminho, e só ele | aceito |
| 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 | aceito |
| 0204 | O modo automático libera push e PR | aceito |
Onde o código mora — modos de execução
Os três modos de execução, a pasta do usuário, a base de projetos e a conversão de um projeto entre modos.
| # | decisão | status |
|---|---|---|
| 0066 | Nome de pasta legível do workspace | aceito |
| 0072 | O projeto escolhe onde o código mora: pasta do usuário ou pasta gerenciada | aceito |
| 0104 | execution_mode em três valores, e o workspace nasce unverified quando o runner é quem verifica |
aceito |
| 0107 | Navegação de pasta local via o Runner | aceito |
| 0108 | No modo runner, o projeto nasce ao clicar em "Navegar pasta...", não só na confirmação |
aceito |
| 0111 | Converter o execution_mode de um projeto existente: recusar com dev agent ativo, realocar o permissions.json, aposentar a linha do container |
aceito |
| 0141 | A base única dos projetos montados, montada por identidade | aceito |
| 0142 | A validação do workspace montado é adiada até a materialização | aceito |
| 0146 | A base consentida no bootstrap, e mounted como padrão local |
aceito |
Container do projeto e broker
O ciclo de vida do container do projeto, a decisão de imagem, a porta de Docker e o broker que fala com o daemon.
| # | decisão | status |
|---|---|---|
| 0065 | Container por projeto: a fronteira deixa de ser política | aceito |
| 0081 | Ciclo de vida do container: tabela de estado, sem orquestrador | aceito |
| 0083 | A aba Terminal ganha o consumidor real do ciclo de vida, não o terminal | aceito |
| 0128 | A porta de Docker, e a prova de empacotamento que escolheu a implementação | aceito |
| 0130 | O broker de container: quem fala com o Docker do servidor, e por que ele não aceita especificação | aceito |
| 0131 | O Arquiteto roteia módulos para infra: ele CANDIDATA, a Infra ELEGE | aceito |
| 0133 | A Infra elege entre as candidatas do roteamento, e a eleição vira nova versão de artifact.project_image |
aceito |
| 0134 | Dev agents executam DENTRO do container real do projeto, e o terminal ganha um piso de auto-aprovação lá dentro | aceito |
| 0135 | O portão da imagem do Arquiteto (RN-105) passa a valer nos três modos de execução | aceito |
| 0136 | Página global de containers: teto por carga no broker, e container_remove no teto absoluto |
aceito |
| 0137 | O brabo-runner sobe o container do projeto na máquina do usuário |
aceito |
| 0143 | Agentes de dev só depois do container | aceito |
| 0144 | A segunda raiz do broker, e o localizador discriminado que a escolhe | aceito |
| 0180 | O container do projeto roda com o dono da pasta, medido pela api | aceito |
| 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 | aceito |
| 0199 | O recurso mínimo do container é derivado do module_map: cada módulo declara o seu, e a Infra sobe com a soma |
aceito |
| 0208 | A Infra herda a rede que o Arquiteto declarou | aceito |
| 0228 | O container do projeto sobe o app pelo comando declarado e publica porta só no loopback | aceito |
| 0229 | O QA testa numa instância efêmera, com os serviços que a Infra declarou | aceito |
| 0264 | Depois do avanço da pasta, o app reinicia só o processo, sem recriar o container | aceito |
| 0265 | O app declarado pela Infra propõe recriar o container, com a porta na faixa 13000+ | aceito |
O runner local
O CLI na máquina do usuário — o canal, as credenciais, as chaves de dispositivo, a distribuição, a base e o serviço.
| # | decisão | status |
|---|---|---|
| 0103 | Runner local: execução na máquina do usuário por canal Phoenix com ticket de uso único | aceito |
| 0105 | Personal Access Token (brb_…) pro runner, escopado por construção a uma rota |
aceito |
| 0106 | Distribuição do @brabo/runner via tsup e npm publish, versão injetada só em CI |
aceito |
| 0112 | Binário standalone do @brabo/runner via bun build --compile, com o addon nativo .node embutido por extração real para um diretório temporário |
aceito |
| 0118 | Configuração do runner pelo navegador: uma chave de dispositivo Ed25519 como segunda credencial do runner-ticket, um proxy do GitHub Releases para o binário e a File System Access API para uma pasta configurada com um clique |
aceito |
| 0145 | Docker vira pré-requisito real do modo runner |
aceito |
| 0147 | Um agente local, capacidades declaradas na conexão | aceito |
| 0151 | A base consentida no runner, e a criação de pasta pelo canal | proposto |
| 0154 | A chave de dispositivo de máquina | aceito |
| 0174 | O binário standalone do runner deixa de prometer o Mac Intel | aceito |
| 0187 | O binário standalone do runner deixa de prometer o Windows | aceito |
| 0193 | O git credenciado roda no HOST do runner; o código roda no container | aceito |
| 0201 | A revogação mira a CHAVE, e não o par {projeto, usuário} |
aceito |
| 0203 | O fluxo do runner pelo navegador é aposentado, e o caminho é o instalador | aceito |
| 0230 | O runner importa a chave de API de LLM que o usuário já tem na máquina | aceito |
Autenticação, acesso e segredos
Autenticação first-party, papéis e seus tetos, associação ao workspace, endurecimento entre origens e envelopes de segredo.
| # | decisão | status |
|---|---|---|
| 0031 | Auth first-party: argon2id, EdDSA e rotação de refresh | aceito |
| 0032 | O corte do Keycloak: emissor próprio, service token e sessão em cookie | aceito |
| 0037 | O CORS que o engine não tinha, e a porta como parte do contrato | aceito |
| 0050 | Credencial sempre cifrada; verificação vira ação explícita | aceito |
| 0058 | CSP fechado na api, e o escopo de projeto contido na raiz | aceito |
| 0059 | A chave que assina o state do OAuth de git não tem default |
aceito |
| 0084 | Login social (GitHub/GitLab), revisando o backlog dos ADRs 0031/0032 | aceito |
| 0096 | SMTP real no MailSender, atrás de um toggle explícito |
aceito |
| 0127 | Dois tetos de rebaixamento em project_members, e a sobreposição fica |
aceito |
| 0156 | O teto de auto-rebaixamento também na remoção de membro de projeto | aceito |
| 0157 | O teto de auto-movimento no upsert de workspace, e a auto-promoção que era brecha | aceito |
| 0158 | O id da chave mestra gravado no envelope, como observabilidade e nunca como autoridade | aceito |
| 0173 | A remoção de membro de workspace nasce, protegida pela mesma cláusula | aceito |
| 0245 | Acesso rápido por papel só no ambiente local | aceito |
Providers de LLM, modelos e gasto
O contrato de provider, o catálogo de modelos e a curadoria, os bindings de modelo, o metering e os orçamentos.
| # | decisão | status |
|---|---|---|
| 0040 | Moeda do dashboard: USD por ora, câmbio manual por workspace adiado | aceito |
| 0041 | Uma base OpenAI-compatível, um contrato de LLM providers e capabilities que recusam binding | aceito |
| 0042 | Catálogo vivo, ciclo de vida do modelo e preço auditável | aceito |
| 0043 | Seis providers de LLM sobre a base, e a Fase 9b finalmente fechada | aceito |
| 0049 | Curadoria de modelo por workspace | aceito |
| 0051 | Facetas de capability provadas; "para que serve" é curadoria | aceito |
| 0063 | Duas audiências para o mesmo gasto: a fatura do owner e o consumo do membro | aceito |
| 0064 | Escopo de área na cascata de modelo, e o binding de agente global | aceito |
| 0075 | Embeddings no contrato de LLMProvider | aceito |
| 0076 | provider volta a ser dimensão de gasto, e a contenção passa a ser do tipo |
aceito |
| 0077 | Ranking de modelos por capacidade, sem nota inventada | aceito |
| 0110 | Orçamento por área é ADITIVO, ao lado de projeto/sessão — não uma cascata, e não uma tabela nova | aceito |
| 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 |
aceito |
| 0115 | Pull de modelo do Hugging Face: tabela própria, confirmação em dois passos e allowlist de publicadores oficiais — nunca proposed_actions |
aceito |
| 0166 | A preferência de roteamento mora no binding de modelo, viaja com ele, e congela no metering | aceito |
| 0188 | O custo real que o provider devolve vira o número do metering | aceito |
| 0198 | A duplicata semântica de história e regra é avisada por embedding com limiar, e o gasto entra no metering | aceito |
| 0221 | O hub prende a conversa de cada agente ao upstream que a atendeu, por session_id |
aceito |
| 0222 | O 9Router entra como o 10º provider de LLM, com URL por instalação | aceito |
| 0223 | O orçamento de raciocínio é capability POR MODELO, curada à mão | aceito |
| 0224 | O raciocínio é contado no stream e abortado no limite, e o custo é estimado e reconciliado | aceito |
| 0225 | O OpenRouter recebe um teto de preço por chamada (provider.max_price = catálogo × 1,5) |
aceito |
| 0227 | O OpenCode Zen entra como o 11º provider de LLM, só no dialeto OpenAI | aceito |
| 0233 | O membro vê o gasto do projeto por agente e por área, nunca por provider | aceito |
| 0251 | Preço de lista datado no código para provider que não informa preço | aceito |
| 0257 | Na Anthropic direta o raciocínio desligado é por modelo e o esforço reduz o Opus | aceito |
| 0279 | Provider de LLM dublê do regressivo, dentro da api | aceito |
RAG, grafo de conhecimento e artefatos
Chunks e busca híbrida, a medição dela, o grafo Neo4j e os artefatos projetados do event log.
| # | decisão | status |
|---|---|---|
| 0079 | Tabela de chunks: vetor e tsvector na mesma linha |
aceito |
| 0080 | Busca híbrida: pesos, limiar e o que é citação | aceito |
| 0082 | Chat RAG: aba própria de busca híbrida, sem renomear "Chat" | aceito |
| 0099 | Neo4j como grafo de conhecimento e templates de prompt, driver na api | aceito |
| 0100 | rag_search para agentes e modelos Ollama garantidos no boot |
aceito |
| 0101 | Memória relacional como projeção do event log; templates consumidos sem tocar GenServers | aceito |
| 0113 | Pasta local anexada vira chunks.scope = 'local', lida pelo NAVEGADOR, nunca um caminho do host |
aceito |
| 0129 | A telemetria de busca do RAG é TABELA, com os pesos congelados na linha | aceito |
| 0132 | Golden-set de acerto do RAG, e o gate rag-acertivo |
aceito |
| 0138 | O golden-set do RAG passa a rodar em CI, agendado — e continua warn |
aceito |
| 0148 | Os artefatos dos agentes projetados em arquivo, numa pasta docs/ |
aceito |
| 0196 | A Anamnese religada: não roda sem sujeito, e a hipótese aceita vira fato do perfil | aceito |
| 0200 | O contrato entre módulos vira artefato versionado do Arquiteto, e o dev agent o lê em vez do worktree alheio | aceito |
| 0205 | O desvio do agente que a Anamnese observa vira sinal do produto, sem dado pessoal | aceito |
| 0269 | A indexação de docs tem teto próprio de 4 MiB, e o corte é declarado | aceito |
| 0272 | A busca híbrida do RAG limita os trechos por arquivo | aceito |
Interface web e design system
Telas, navegação, temas e a estrutura dos maiores arquivos do app web.
| # | decisão | status |
|---|---|---|
| 0036 | Telas de auth fiéis ao design, e as três fontes que não carregavam | aceito |
| 0060 | A superfície de leitura de código, contida e com orçamento | aceito |
| 0074 | Tema alcançável, e o boot sob CSP | aceito |
| 0078 | Moldura de tela, e o registro de abas diverge do handoff de propósito | aceito |
| 0097 | Leitura direta do schema do engine para o "N agentes online" do dashboard | aceito |
| 0116 | ActionType (e tipos futuros) gerados do contrato OpenAPI, não copiados à mão |
aceito |
| 0122 | SessionPage.tsx dividido em cinco PRs mecânicos, declarados de antemão |
aceito |
| 0124 | Agrupamento de estado do canal de turno extraído para useTurnoDoAgente |
aceito |
| 0125 | ProjectSettingsTab.tsx dividido em um arquivo por seção, atrás de um barrel |
aceito |
| 0126 | A página do projeto navega por um trilho vertical, e a aba Código para de recolher a sidebar sozinha | aceito |
| 0176 | SessionPage.tsx abaixo de 1 000 linhas, em dez PRs mecânicos, e a trava só depois |
aceito |
| 0181 | O tema escuro vira preto neutro, e a dívida de contraste acaba | aceito |
| 0210 | Animação de texto com motion |
aceito |
| 0211 | Uma navegação só: a sidebar absorve o trilho do projeto | aceito |
| 0232 | shadcn/ui com Base UI e Tailwind 4 no apps/web |
aceito |
| 0234 | shiki no Code Block e recharts no Chart, sempre por carga dinâmica |
aceito |
| 0237 | O visual v3 liga o preflight e sobe os raios | aceito |
| 0238 | O grafo de módulos da Arquitetura vira Canvas (@xyflow/react) |
aceito |
| 0239 | CSP frame-src local para o Web preview do entregável |
aceito |
| 0240 | O motivo de controle inerte pode morar num "?" ativo na página de Containers | aceito |
| 0241 | A sidebar adota o block sidebar-07 do shadcn |
aceito |
| 0242 | Containers em tabela linear com @tanstack/react-table |
aceito |
| 0243 | Consequência irreversível pode morar num botão de perigo | aceito |
| 0244 | Coluna das abas do projeto alinhada à esquerda | aceito |
| 0248 | O conteúdo das páginas ocupa a largura inteira | aceito |
| 0250 | O chat da Sessão ocupa a largura inteira | aceito |
Operação, deploy e instalação
Imagens de produção, Kubernetes, observabilidade, backup, o compose de dev e o instalador de uma linha.
| # | decisão | status |
|---|---|---|
| 0024 | Fase 5 (sessão 1): imagens de produção, compose.prod, CI e teste de fumaça | aceito |
| 0025 | Fase 5 (sessão 2): deploy Kubernetes com Kustomize, métrica de fila e overlay local | aceito |
| 0026 | Fase 5 (sessão 3): graceful shutdown, OpenTelemetry, métricas, logs e dashboards | aceito |
| 0027 | Backup/restore, hardening da api, superfície exposta e release | aceito |
| 0035 | Trace sem coletor, e o caminho entre camadas no log | aceito |
| 0070 | Observabilidade no Compose local: métrica e log, sem trace | aceito |
| 0150 | O instalador de uma linha, com fonte escolhida e marcador | proposto |
| 0152 | Backup e restore de volumes, contra compose | proposto |
| 0153 | DEPLOY_ENABLED: o gatilho que dez documentos citam e nenhum cria |
proposto |
| 0155 | A primeira conta nasce no terminal, e o agente local sobe pareado | aceito |
| 0160 | O compose do instalador viaja com ele, como asset assinado | aceito |
| 0161 | A tela só oferece o modo que a instalação executa, e a instalação por Release não tem broker | aceito |
| 0162 | O broker vira a quinta imagem publicada, e o instalador PERGUNTA se o liga | aceito |
| 0169 | O destino S3 do overlay local deixa de ser o MinIO e passa a ser o SeaweedFS | aceito |
| 0170 | O compose de dev vira brabo-dev, e o dev recusa subir ao lado de uma instalação |
aceito |
| 0209 | O engine sobe para Elixir 1.20.4 / OTP 29.1.1 | aceito |
| 0256 | A migração do instalador restaura o banco num banco recém-criado e vazio | aceito |
CI, release e cadeia de suprimentos
O pipeline, as imagens publicadas, a assinatura, a varredura, o pin, as camadas de teste e a estrutura do próprio repositório.
| # | decisão | status |
|---|---|---|
| 0039 | actionlint e a validação do pipeline de CI gerado | aceito |
| 0119 | Imagens publicadas no GHCR a cada tag final, e o overlay de produção preso por digest | aceito |
| 0120 | E2E de navegador contra o compose de produção, num pacote fora do workspace | aceito |
| 0121 | O schema dividido por agregado de domínio, atrás de um barrel | aceito |
| 0140 | Timeout repetido do pnpm audit é risco assumido; achado continua reprovando |
aceito |
| 0149 | Assinatura dos artefatos publicados | proposto |
| 0159 | Imagem de terceiro entra por digest, e o lint reprova quem esquecer | aceito |
| 0172 | O release escaneia com Trivy o que publica, por digest, antes de assinar | aceito |
| 0178 | A tag da imagem de terceiro mora DENTRO da referência, antes do digest | aceito |
| 0197 | A imagem dos workflows vem do compose, e o Dependabot de imagem é ligado | aceito |
| 0252 | O Brabo vira um conjunto de repositórios em viralabs-dev |
aceito |
| 0268 | O brabo-qa tem regressivo por funcionalidade, e o da PR para a dev nunca é exigido |
aceito |
| 0270 | O brabo-contracts é publicado no GitHub Packages, com o shared só de tipos |
aceito |
| 0271 | Cada run do Actions mostra os vínculos entre os repositórios | aceito |
| 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 | aceito |
| 0278 | A mudança é vista num painel do brabo-ci, sem check nas PRs | aceito |
| 0280 | O pin do brabo-ci nos consumidores aponta para uma tag, e a branch decide qual | aceito |
| 0281 | O mapa dos 11 repos tem uma fonte só, o repos.yml do brabo, e o README é gerado dela |
aceito |
| 0282 | A pin dos componentes segue a última Release final | aceito |
| 0285 | A prova de uma aresta do repos.yml é arquivo mais trecho literal, não arquivo:linha |
aceito |
| 0286 | As capturas da doc são geradas pelo brabo-qa e entram no brabo por PR do App | proposto |
| 0289 | A recaptura segue a pin do web e só pede o dono quando a imagem muda | proposto |
Documentação
Como a documentação é gerada, verificada e publicada.
| # | decisão | status |
|---|---|---|
| 0029 | Sincronização contínua da documentação | aceito |
| 0033 | A referência de API sai do código, e o teste de tabela cobra os metadados | aceito |
| 0034 | Documentação publicada por degrau, em subdiretório do Pages | aceito |
| 0071 | Publicação simétrica por degrau, e uma raiz que escolhe | aceito |
| 0073 | O caminho publicado nomeia o ambiente, não a branch | aceito |
| 0117 | website/ ganha lockfile próprio, fora do pnpm audit do produto |
aceito |
| 0202 | O índice de ADR por tema, com o tema fora do ADR | aceito |
| 0206 | A referência da API vira uma página Redoc | aceito |
| 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 | aceito |
| 0218 | Todo ADR se chama "ADR NNNN — título" | aceito |
| 0219 | A referência entra na tradução | aceito |
| 0220 | A página da API sai traduzida por catálogo | aceito |
| 0253 | O site de docs deixa o Docusaurus | aceito |
| 0254 | A doc de cada área mora na raiz dela | aceito |
| 0260 | A doc dos repos de código é só em inglês; o site serve a fonte inglesa com faixa | aceito |
| 0266 | A doc dos repositórios é em pt-BR por padrão, com traduções permitidas nos irmãos | aceito |
| 0273 | A paridade de tradução mede só a doc do brabo | aceito |
| 0274 | Os gerados do brabo leem os irmãos por uma trava de SHAs |
aceito |
| 0275 | Cada irmão confere as próprias refs com símbolo no PR | aceito |
| 0287 | O índice de ADR é gerado, e a referência grande vira índice mais partes | proposto |
| 0288 | O link entre repos nas RNs é a URL do repo dono, e o site a devolve para relativo | proposto |
A convenção
- Um arquivo por decisão, em
docs/adr/NNNN-short-title.md, com numeração sequencial de 4 dígitos, e título# ADR NNNN — <título>(0218). Sem reuso de número, nem quando um ADR é substituído — o próximo é 0290. - Um tema por decisão, escolhido por quem escreve o ADR, no mesmo
PR: uma linha em
docs/adr/temas.yml; a linha do índice é gerada. Quem revisa confirma. Um tema novo é uma mudança na lista emtemas.yml, justificada no PR que o acrescenta; passar de 15 exige um ADR que revise o 0202. - Três seções, só elas: Contexto (o problema ou a força que o motivou), Decisão (o que foi decidido), Consequências (os trade-offs aceitos e o que ficou para depois).
- Sem template de terceiros — nada de Nygard, MADR ou variantes. As três seções bastam.
- Em português, como o resto do projeto.
- ADR aceito não é editado. Um substituído por decisão posterior fica como está; o ADR novo referencia o antigo e explica o que mudou.
O que dá valor a estes ADRs é registrar o que não funcionou: o 0020 documenta nove execuções fracassadas seguidas, e o 0027 registra uma justificativa que foi revista dentro da mesma sessão que a produziu. Uma consequência ruim omitida é a parte que faz falta seis meses depois.