Funcionalidade quadro unico - BrunodosSantosVaz/big-bang GitHub Wiki

Quadro único e controlador da v3

Funcionalidade BB-F-051 · requisito RF-BB-051 · versão documentada 3.0.0 · código 57e319627957e7817bb558990c25a864a00c5563.

Finalidade

Substituir os três painéis da v2 por um único Project por repositório (ADR-0023), onde cada cartão mostra o estado registrado nos recibos da própria issue e só muda por transições validadas pelas regras da v3, com portões conforme o modo.

Atores

Dono e IAs pelo comando bb move; o controlador da esteira (eventos de issue, push, pull request e agenda); a Fundação F4 com bb board labels e bb board create.

Pré-condições

Projeto com board.model = single e o número do Project em board.number; token do gh com escopo project; issue com exatamente uma label de tipo (type:epic, type:task, type:test, type:docs ou type:bug).

Fluxo principal

bb board create cria ou completa o Project, liga ao repositório, cria os campos e as visões Board, Table e Roadmap; o adaptador lê as workflows embutidas do Project e permite recarregar os cartões do GitHub sem usar cache; bb move reúne os fatos no GitHub, valida a transição (states) e o aprovador do portão (policy), grava o recibo e aplica os efeitos; o controlador transforma push em Coding, PR aberto em In Review, merge em Done com a issue fechada e a posse liberada, e label de decisão em avanço automático; a agenda reconcilia o quadro e projeta posses vencidas como stale.

Validações

Transição fora das regras, portão do dono sem decisão registrada, impedimento ativo ou retorno de Rejected diferente do registrado são recusados com o motivo; evento repetido com o mesmo identificador não grava nada novo; itens de outros repositórios no Project são ignorados. A leitura atualizada descarta o cache local para conferir os valores persistidos no GitHub. O leitor de workflows informa nome e estado ativo sem alterar as automações. A identidade de quem roda o comando nunca aprova um portão (numa conta pessoal o dono e as IAs a compartilham): portão do dono exige a decisão registrada com bb decision — approved:backlog, approved:refinement, approved:prototype, approved:selection, qa:approved, qa:rejected (reprovação de QA) ou approved:cancel (cancelar épico). Os efeitos acontecem antes do recibo; as tentativas vêm dos recibos e, no limite, o cartão fica em Rejected com blocked. Uma reprovação — ou uma volta sem reprovação (Ready → Refinement, Selected → Ready) — retira as decisões do dono da etapa de retorno em diante (refinamento, protótipo, seleção, QA): uma aprovação de um ciclo anterior nunca aprova o seguinte. O risco de QA e publicação vem dos arquivos dos PRs mesclados do épico e das suas sub-issues; no Flash, um portão de planejamento delegado pelo risco conta como aprovação. O QA nunca é dispensado: com qa:human a homologação é sempre do dono, em qualquer modo e risco; com o QA delegado, o cartão só avança com um recibo de QA aprovado da candidata atual, registrado depois de entrar em QA por um agente declarado em agents.names que não move o cartão nem teve posse no épico ou nas sub-issues (quem entrega nunca homologa). O risco de entrega lê só os PRs atualizados desde a criação do cartão ou da sua sub-issue mais antiga. A capacidade de posses conta as travas das issues abertas, não as labels de projeção; um evento de merge repetido nunca solta uma posse tomada depois do merge.

Na esteira própria do framework, a guarda do conteúdo do PR usa a política identificada pela configuração confiável da base. A ausência de STACK.md no manifesto desse framework só permite conteúdo sem dependências diretas de execução; pacotes sem tabela e ecossistemas não suportados são recusados. Projetos de sistema mantêm a guarda documental anterior, mesmo que o PR acrescente uma configuração exclusiva falsa.

Na origem do framework, a busca de dependências inclui o código e os manifestos dentro de .bigbang/, além da raiz do repositório. Os exemplos de desenvolvimento em .bigbang/tests/ são fixtures de teste e não declaram pacotes de execução. A mesma abrangência vale quando uma tabela STACK.md estiver declarada. Sistemas conservam a exclusão do framework herdado e todos os demais comportamentos anteriores.

Alternativas e erros

Arrastar um cartão no Project de conta pessoal não gera evento: a reconciliação devolve o cartão ao estado registrado e comenta na issue como mover corretamente; recusas do controlador não são erros, apenas não movem. O controlador só ignora recusas das regras; erro de transporte falha o run. A posse só é liberada depois que o cartão saiu de In Review, e um evento closed atrasado de um PR reaberto não muda nada.

Permissões

O controlador é o único escritor das travas e do quadro; label de decisão continua exclusiva do dono (bb decision); o Project público continua somente leitura para visitantes.

Resultados

Um quadro único coerente com o histórico auditável das issues, tarefas fechadas no merge, progresso nativo correto e retrabalho registrado com motivo, origem, retorno e tentativas.

Referência da implementação

Os símbolos abaixo compõem o inventário real do módulo, incluindo auxiliares internos; não representam APIs públicas independentes.

board.py

Implementação revisada.

Símbolo Linha
ensure_labels 96
ensure_fields 101
_iso 109
_trusted 113
history 117
current_state 122
_label_value 131
facts 137
attempts 162
record_qa 178
_independent_qa 196
_born 214
_gate 221
_epic_paths 227
_gate_decision 252
_approval_problems 269
move 294
_effects 363
reconcile 384
create_project 409
ProjectGraphQL 441
__init__ 444
_project 448
_load_fields 461
fields 472
workflows 476
ensure_field 482
_load_items 506
items 533
add 538
set 549
get 564

controller.py

Implementação revisada.

Símbolo Linha
_now 18
_try 22
_state 33
_issue_of 37
_parse_time 42
release_on_merge 46
apply_epic_form 62
handle 85
advance 91

flow_cli.py

Implementação revisada.

Símbolo Linha
register 9
_migrate 127
_load 159
_context 165
_labels 177
_create 184
_refuse_autonomy 199
_autonomy_check 208
_reconcile 216
_show 225
_move 235
_today 244
_sprint_start 249
_branches 260
_merge 268
_release_cut 276
_release_items 289
_release_gate 298
_flag_path 311
_flag_list 316
_flag_switch 327
_flags_by_agent 339
_pr_rules 345
_escaping_links 382
_content_problems 397
_actor 416
_candidate_ready 420
_release_publish 429
_release_maintenance 461
_qa_reject 476
_qa_verdict 488
_cleanup 499
_controller 514
promote 442
open_project 142
create_project 144

Cenários e rastreabilidade

Requisitos · Matriz de rastreabilidade · Referência CLI

Fontes rastreadas