07 · ORGs e ADRs

Cada família conta desde 0001 e nenhuma usa número da outra: uma versão nova da arquitetura pode acrescentar a ORG-0026 a stacks que já existem, sem tocar na numeração das ADRs delas. Não há faixa reservada nem limite de quantas decisões cada lado pode ter. Quem lê o identificador sabe na hora de onde a decisão veio.

A cópia das ORGs na stack

• A pasta docs/decisoes/organizacao/ tem o mesmo caminho aqui e na stack. A stack recebe a pasta inteira, na versão do arquivo ARQUITETURA: ao nascer (eng/new-stack.sh) e a cada change arquitetura-X-Y-Z (18);
• A cópia nunca é editada à mão, como vendor/hibex/. Uma ORG errada ou que não serve vira pedido para cá;
• A cópia local é de propósito: o agente lê as regras sem rede, sem acesso a este repositório e exatamente na versão que a stack adotou, que pode não ser a mais nova;
• O índice da stack, docs/decisoes/README.md, lista as duas famílias, as ORGs primeiro. Quem procura "o que já está decidido" lê um índice só.

Estados

Uma ADR aceita não se reescreve: vira substituída, com link para a que a substitui. Revisões que só re-fundamentam levam uma linha "Revisão: data — motivo" no cabeçalho. Vale para as duas famílias.

Toda ORG é fixa: não tem lacuna. Quando uma regra deixa algo para a stack escolher, a ORG diz o que é obrigatório e uma ADR pré-escrita recebe a escolha (ver As ADRs pré-escritas).

Para cada ORG, a decisão em resumo. O texto completo de cada uma (contexto, decisão, alternativas, consequências) está em docs/decisoes/organizacao/.

ORG-0001 — Registrar decisões em dois níveis

• Toda decisão técnica com alternativas vira registro: ORG se vale para toda stack (aqui), ADR se vale só para a stack (lá), cada família com a sua sequência desde 0001, a partir do template.md da família, e entra no índice docs/decisoes/README.md;
• Registro do agente nasce proposto; só o mantenedor aceita; aceito não se reescreve — vira substituído, com link;
• Divisão: ORG/ADR = como e por quê (técnico); spec = o que o produto faz; solução = como foi montado em detalhe; guia = como operar;
• As ORGs chegam à stack como cópia, em docs/decisoes/organizacao/, nunca editada à mão.

ORG-0002 — Uma ADR nunca contradiz uma ORG

• Uma ADR decide dentro do que as ORGs deixam em aberto; nunca afrouxa, contorna nem suspende uma ORG, nem "por enquanto";
• Quando a stack precisa de algo que uma ORG não permite, o caminho é um pedido a este repositório, anotado em docs/decisoes/pedidos-a-arquitetura.md da stack. Até uma versão nova da arquitetura mudar a ORG, vale a ORG;
• Toda ADR diz quais ORGs cumpre (campo Cumpre no cabeçalho); a revisão de toda change confere que nenhuma ADR nova ou alterada contradiz uma ORG;
• Quando uma versão nova substitui uma ORG, a change arquitetura-X-Y-Z revê as ADRs que a cumpriam.

ORG-0003 — Idioma e terminologia

• pt-BR em documentação, specs, telas e respostas do agente; inglês em identificadores; termos técnicos consagrados sem tradução; SHALL/MUST/WHEN/THEN em inglês;
• A terminologia do domínio mora na stack, em docs/produto/glossario.md: começa vazia e cresce a cada change que cria termo.

ORG-0004 — Sistema de documentação

• README.md (porta de entrada), docs/ARCHITECTURE.md (visão viva de alto nível), docs/stack.md (ficha), docs/produto/ (visão de produto), docs/decisoes/, docs/solucoes/, docs/guias/, docs/acesso/, docs/design-system/;
• O que vai em cada um e quando atualizar: ver 08;
• Toda change atualiza a documentação que toca na mesma change.

ORG-0005 — Diagramas

• Todo documento grande abre com um diagrama. Recomendado: rabisco desenhado por código, no estilo de rabisco do design system (o kit vem no modelo), para o que se lê muito e muda pouco. Permitido: Mermaid, para o que muda em quase toda change ou precisa sair rápido (sequências, trechos do ARCHITECTURE.md). Nenhum dos dois é proibido;
• O texto ao redor diz o mesmo que o diagrama; imagem que não é diagrama é, de preferência, SVG desenhado por código; quando precisa de um gerador de imagens, nasce como prompt num arquivo sidecar <imagem>.prompt.md e a imagem é gerada pelo mantenedor.

ORG-0006 — Estrutura de diretórios

• O esqueleto de 05 · Anatomia: docs/, openspec/, e2e/, deploy/<app>/, eng/, vendor/hibex/, compose.yaml, .claude/, .github/;
• Os módulos de código e o que cada um contém são da stack (ADR-0001 pré-escrita);
• Criar pasta fora da estrutura exige motivo (e ADR, se for um tipo novo de pasta).

ORG-0007 — Agentes de IA e controle humano

• AGENTS.md é a fonte das regras do agente; CLAUDE.md só o importa (@AGENTS.md);
• Git de escrita, GitHub, deploy, infraestrutura real e segredos: só o mantenedor — garantido por hook onde dá;
• Protocolo de entrega: ambiente local no ar com dados, resumo por tela do que mudou, instruções de commit e de deploy.

ORG-0008 — OpenSpec para toda mudança

• Ciclo explore (opcional) → propose → revisão → apply → sync → archive; nenhum código de produto antes da aprovação;
• Também são change: atualizar o design system, a arquitetura, versão maior de dependência;
• Versão do OpenSpec CLI fixada (eng/tools.versions); openspec validate --strict na CI quebrando o build.

ORG-0009 — Desenvolvimento orientado a testes (TDD)

• Toda tarefa de código começa por um teste que falha pelo motivo certo, em qualquer camada (unidade, integração ou E2E); depois o código mínimo; depois a refatoração;
• O tasks.md de toda change lista a tarefa de teste antes da tarefa de código, e eng/tdd-order.sh confere a ordem na CI;
• Cada cenário de spec tem cobertura declarada no tasks.md (unidade, integração ou caso E2E).

ORG-0010 — Versões fixas

• Toda ferramenta, biblioteca, imagem, action e CLI com versão exata, numa fonte única; eng/pinned-versions.sh na CI.

ORG-0011 — Plataforma Linux e pré-requisitos

• Linux; scripts em bash, com verificação de pré-requisitos e ERRO: claro; credenciais só por variável de ambiente ou prompt;
• A lista de pré-requisitos, com versões, mora no README da stack ({{LACUNA:prereq.*}} no modelo).

ORG-0012 — Integração contínua

• GitHub Actions, runner e actions fixados; passos mínimos: lacunas, versões fixas, ordem do TDD, build + testes, verificador do design system, openspec validate --strict;
• A regressão E2E na CI fica para quando a stack decidir (ADR própria); até lá, roda na estação de trabalho no fim de cada change.

ORG-0013 — Stack tecnológica escolhida uma vez, por critérios

• A stack escolhe linguagem, runtime, framework e UI uma vez, pelos critérios de 06, e registra a escolha e as alternativas na ADR-0001 pré-escrita.

ORG-0014 — Persistência

• Sem banco padrão: armazenamentos escolhidos pelos critérios de 06; evolução do formato dos dados versionada no repositório (migrations ou equivalente); um dono do schema; armazenamento descartável em container no dev e nos testes; sem banco em memória que finge ser outro;
• A escolha vai para a ADR-0002 pré-escrita.

ORG-0015 — Testes de unidade e integração

• As três camadas de 10; integração contra dependências reais em container (armazenamentos, Keycloak na versão do toolbox); suporte de teste por aplicação;
• Frameworks, bibliotecas e como recortar a suíte vão para a ADR-0003 pré-escrita.

ORG-0016 — Testes fim a fim hierárquicos

• Playwright Test + Node, em e2e/, em TypeScript, com o Chromium da versão do Playwright; agrupamento → cenário → caso; setups em cascata executados sob demanda; casos independentes entre si; capturas ligadas aos casos; modos verificar / demonstrar / capturar;
• um processo, sem retentativas, sem comparação visual; roda na estação (CI só por ADR da stack);
• o ambiente não presume SQL nem um banco só: armazenamentos, dados-base, preparadores e simuladores de serviços externos são pontos de encaixe, que a stack preenche na ADR-0004 pré-escrita;
• O detalhe está em 11.

ORG-0017 — Aplicações e endereços

• Uma aplicação = uma imagem, um serviço Kamal, um endereço, uma família de cor; acesso restrito, público ou misto, declarado (12); endereços pela política de domínios do toolbox (<app>.hibex.app para usuário final, <app>.<plataforma>.hibex.net para colaboradores, exceções em hibex.co com ADR);
• A lista de aplicações vai para a ADR-0005 pré-escrita.

ORG-0018 — Containers: Docker e Compose

• Uma imagem por aplicação, multi-stage, usuário não-root, só a porta da aplicação exposta, contexto de build na raiz; compose.yaml com o ambiente local descartável (sem volume nomeado, credenciais óbvias), observabilidade num perfil;
• Dois caminhos locais: aplicações nativas + infraestrutura em container (recomendado) ou tudo em container (valida a imagem);
• Imagens base e versões vão para a ADR-0006 pré-escrita.

ORG-0019 — Implantação com Kamal e segredos no Bitwarden

• Kamal por aplicação a partir de deploy/<app>/; imagens no ghcr.io; kamal-proxy com TLS; healthcheck em /up; armazenamentos e backup como accessories; segredos só por referência (kamal secrets fetch --adapter bitwarden-sm); DEPLOYMENT_ENVIRONMENT declarado;
• Hosts, prefixos e donos dos accessories vão para a ADR-0007 pré-escrita.

ORG-0020 — Identidade e acesso com Keycloak

• Toda área restrita é autenticada no Keycloak do toolbox; realm por população; client confidencial com Authorization Code + PKCE; permissões como client roles <recurso>:<ação>; perfis como client roles compostos perfil:<nome>; atribuição só por grupo (ou default roles para "todo usuário"); configuração como código em eng/auth/; realms de desenvolvimento com um usuário por perfil; documento de acesso por aplicação;
• Aplicação pública não tem client, mas declara o que expõe;
• Realms, clients, permissões, perfis, grupos e IdPs vão para a ADR-0008 pré-escrita.

ORG-0021 — Observabilidade

• Contrato: log JSON no stdout com traceId; métricas Prometheus numa porta interna não publicada; traces OTLP para o Alloy do toolbox; /up sem autenticação; service.name = nome da aplicação; deployment.environment = local | production; export não bloqueante;
• As bibliotecas que implementam o contrato vão para a ADR-0009 pré-escrita.

ORG-0022 — Backup e restauração

• Todo armazenamento com dados de produção tem backup diário em volume da VPS, retenção 7 dias / 4 semanas / 6 meses; a ferramenta de backup na mesma versão maior do servidor; restauração por script versionado que confere o arquivo e exige --confirmar; restauração testada fora da produção;
• A ferramenta para cada armazenamento vai para a ADR-0010 pré-escrita.

ORG-0023 — Design system da Hibex

• Cópia em vendor/hibex/, por script do mantenedor, nunca editada; entrega pelo build só com a família da aplicação; verificador na CI quebrando o build; o que falta vira hibex-pendente: NNNN + pedido; atualização por change; aviso de ambiente fora da produção;
• A família de cor de cada aplicação vai para a ADR-0005 pré-escrita.

ORG-0024 — Tempo e fuso horário

• Instante gravado em UTC; o fuso pessoal do usuário é a única lente de exibição; data civil (sem fuso) só quando o dado é civil por natureza, declarado na ADR própria.

ORG-0025 — Acervo de capturas de tela

• Uma stack que mantém acervo usa as capturas do E2E em modo capturar, PNGs em Git LFS em docs/screenshots/<tela>/, e só as telas afetadas por change entram no acervo;
• Sem acervo, o mecanismo de captura continua disponível para acompanhar o desenvolvimento, sem versionar nada;
• Manter ou não o acervo é escolha da stack, na ADR-0011 pré-escrita ("não mantemos" é uma resposta válida).

O modelo zerado traz as onze primeiras ADRs da stack já escritas: contexto, a ORG que cada uma cumpre e as alternativas usuais, com a escolha em {{LACUNA:…}}. Nascem propostas; a Fase 1 preenche cada lacuna a partir da ficha (06), e o mantenedor aceita. A primeira ADR própria da stack é a ADR-0012.

Se uma versão nova da arquitetura trouxer uma ADR pré-escrita nova, ela entra na stack com o próximo número livre da stack, e não com um número fixo: a numeração das ADRs é sempre da stack.