ADR-0022: Esteira no próprio framework e épico como agrupador

• Situação: aceita
• Data: 2026-10-10
• Dono: Bruno dos Santos Vaz (BrunodosSantosVaz)
• Decisão: #221 (E1); implementação: #224 (E4) e #228 (E8), pendente; release: #220 (v3.0.0).

Contexto e problema

O Big Bang entregava sistemas por uma esteira que ele mesmo não usava: o framework seguia um processo leve (PR para main, depois sincronização). O dono pediu "colocar o Big Bang na própria estrutura Big Bang" (#201) e, ao revisar o modelo de épico, disse:

pra mim o epico seria uma forma de classificar algo e as tarefas ficaram dentro deste epico

No modelo v2 o épico é uma unidade de entrega com branch própria (epico/*), o que gera branches longas, sincronizações por épico e conflitos. No mercado (Jira + Git Flow), o épico é um agrupador de tarefas.

Relação com decisões anteriores

• Substitui, como padrão da v3, o ADR-0003 (branch de épico; a develop nunca recebe código de artefato não publicado) e o ADR-0004 (release a partir da main com os épicos escolhidos). Os dois continuam valendo para o modelo legado ([workflow] model = "epic-branch") durante toda a v3.
• Complementa o ADR-0015 (release por sprint ou por épico): no modelo B, o escopo da release é a develop cortada, e a escolha do que entra em produção é feita por feature flag.
• Substitui, para o próprio framework, o "processo leve" registrado no ADR-0017: o framework passa a usar a própria esteira.

Decisão e justificativa

1. Modelo B (agrupador) passa a ser o padrão da v3:
   • o épico é a issue pai, sem branch;
   • cada tarefa nasce da develop e fecha no merge;
   • a release é cortada da develop (release/x.y.z), homologada sobre a candidata e promovida para a main.
   • Feature flags separam deploy de liberação: tudo o que muda o artefato e não foi homologado vai com a flag desligada. A release só admite testes de aceite pendentes de épicos com flag desligada.
   • Mudança sem release (documentação, esteira) não avança mais a main até a develop, porque a develop pode ter código não lançado. Ela sai de maintenance/* a partir da main, com o mesmo gate, e depois volta para a develop.
   • Correções seguem como hoje: fix/* e hotfix/* nascem da main (a versão em produção), entram numa release de correção e voltam para a develop depois da publicação.
2. O modelo atual (A, epico/*) fica como legado durante toda a v3 ([workflow] model = "epic-branch"). A remoção só acontece numa v4, com nova migração.
3. O framework usa a própria esteira:
   • a configuração fica em .bigbang-framework.toml, nunca em bigbang.toml, porque a ausência desse arquivo sinaliza "não fundado" ao lançador;
   • os arquivos gerados para o framework levam o prefixo bb-framework- e a guarda github.repository;
   • a F5 dos sistemas os remove, e o bb init remove a configuração própria do framework.
4. Rede de proteção do lançador:
   • um teste ponta a ponta (template → bb init → bb gerar --esteira → bb verificar) roda em toda CI;
   • cada entrada da raiz do template tem decisão explícita para a Fundação;
   • as instruções exclusivas do framework no AGENTS.md ficam entre marcadores bigbang:framework e o bb init as remove.

Consequências

• A stack precisa declarar como lê feature flags (F2). Sem isso, o projeto continua no modelo A.
• Fechar a tarefa no merge alimenta o progresso nativo das sub-issues.
• Como palavras de fechamento só agem na branch padrão (main), o controlador fecha a issue explicitamente.
• A primeira release publicada pela esteira própria é a v3.0.0.