Funcionalidade nucleo v3 - BrunodosSantosVaz/big-bang GitHub Wiki

Núcleo de controle da v3

Funcionalidade BB-F-050 · requisito RF-BB-050 · versão documentada 3.0.0 · código bff42ded9b4d83b4327f4064cc352f49c7659dfa.

Finalidade

Reunir as regras de controle da v3 em módulos puros e testados: quais transições do quadro único são permitidas e com que evidência (states), quem aprova cada portão em cada modo e qual o risco mínimo de uma mudança (policy), como cada ação deixa um recibo auditável (receipts) e como garantir exclusão real sobre um recurso (locks). ADR-0023 e ADR-0025.

Atores

Controlador da esteira v3, comandos bb claim/unclaim/renew/move/reject e os workflows que registram testes, revisões, QA e publicação; IAs e humanos usam o mesmo protocolo.

Pré-condições

Os chamadores reúnem os fatos no GitHub (labels, sub-issues, PR, candidata, decisões) e passam para as regras; as travas precisam de token com permissão de escrever refs no repositório.

Fluxo principal

states.problems(tipo, atual, alvo, fatos) devolve por que uma transição não é permitida (lista vazia libera); policy.approver(modo, portão, risco, contrato) devolve owner, agent ou blocked; receipts.render/parse grava e lê recibos idempotentes por event_id; locks.Locks adquire, renova, retoma e libera travas em refs/bigbang/locks/ com geração como token de cerca. GitHub.pulls pagina a listagem uma vez e normaliza os campos presentes em cada resposta em memória, sem fazer uma consulta individual para cada PR.

Validações

Rejected exige motivo da família reason e retorno permitido pela etapa de origem; Cancelled exige motivo; impedimentos bloqueiam avanços; o rótulo risk:* só eleva o risco calculado pelos caminhos; recibos só valem da conta confiável e com campos obrigatórios; uma ref que não contém trava do Big Bang nunca é tratada como trava. Liberar uma trava grava uma lápide e nunca apaga a ref: uma liberação atrasada não remove a trava de outra sessão e a geração só cresce; trava vencida só é retomada por ordem do dono (--force-claim, com a frase dele) e uma sessão vencida não renova. Pessoas e agentes nunca compartilham o dono de uma trava.

Alternativas e erros

Aquisição concorrente tem um vencedor (criação de ref existente devolve 422); retomada de trava vencida e renovação usam atualização fast-forward, que também devolve 422 se alguém mudou a ref; sessão substituída recebe LockLost e não pode concluir trabalho; modo, portão ou risco desconhecido cai no caso mais restrito. Lápides de trava nunca são apagadas (apagá-las reabriria a corrida e reiniciaria a geração); a capacidade e as posses vencidas leem só as travas das issues abertas.

Permissões

As regras não concedem permissão: o modo autônomo só aprova dentro de um contrato autonomy.toml válido e nunca amplia o próprio alcance; só o controlador escreve as refs de trava. Portões de planejamento usam o risco declarado pelas áreas (médio por padrão); portões de QA e publicação usam os caminhos alterados e, sem eles, falham para alto. AGENTS.md/CLAUDE.md são risco alto e .bigbang/** crítico.

Resultados

Decisões reproduzíveis e auditáveis para o controlador do quadro único, posse com exclusão real e base para reaproveitar evidência de testes do mesmo conteúdo sem repetir a suíte por hábito.

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.

states.py

Implementação revisada.

Símbolo Linha
kind 45
_has 51
targets 56
_returns 68
problems 72
_rejection_problems 103
_preconditions 117
_need 128
_done_subissues 132
_flag_decided 137

policy.py

Implementação revisada.

Símbolo Linha
mode 32
_rank 41
approver 45
_matches 62
risk_floor 68
_area_risk 84
planning_risk 89
delivery_risk 94
effective_risk 104
limits 110
snapshot 127
suite_on_promotion 133
in_window 141
contract_problems 151
strings 160

receipts.py

Implementação revisada.

Símbolo Linha
problems 24
render 34
parse 54
find 71
reuse_problems 76

locks.py

Implementação revisada.

Símbolo Linha
LockHeld 20
LockLost 28
_iso 33
encode 37
decode 41
expired 53
gh_api 57
Locks 81
__init__ 21
_path 85
_call 88
_check 96
_commit 100
_head 105
current 116
_record 122
acquire 126
take_over 143
renew 159
release 173
all 185

claims.py

Implementação revisada.

Símbolo Linha
is_v3 21
_now 30
_iso 34
_label 38
_owner 42
_check_name 47
_open_issue 57
_blockers 64
_held_by 71
_record 81
claim 85
_project 109
renew 120
unclaim 127
force 137
stale 162

gh.py

Implementação revisada.

Símbolo Linha
_labels 14
normalize_issue 18
_milestone 26
_normalize_pull 32
graphql 39
GitHub 57
__init__ 58
call 62
paginate 69
repository_info 82
user 86
branch_rules 90
ruleset 93
environment 97
environment_branch_policies 101
issue 107
issues 111
create_issue 115
update_issue 119
add_labels 122
remove_label 126
ensure_label 129
comments 134
comment 137
sub_issues 143
parent 146
add_sub_issue 150
blocked_by 154
add_blocked_by 157
branches 163
branch_sha 167
create_branch 171
pull 177
merge_pull 183
pull_files 192
add_pr_labels 195
check_runs 198
compare_messages 202
tags 206
ensure_milestone 210
milestone_number 217
close_milestone 223
milestone_issues 226
pulls 230
create_pull 235
merge_branches 245
ahead_by 251
delete_ref 255
all_branches 258
locks 262

Cenários e rastreabilidade

Requisitos · Matriz de rastreabilidade · Referência CLI

Fontes rastreadas

Revisão documental

Versão 2.0.1 · código documentado 9c73feb3e357a1216011eaf64bf4b5d944827087 · Wiki com histórico Git separado. A proposta e a base da Wiki são registradas no manifesto .bigbang-docs.json e no PR correspondente. Índice.

⚠️ **GitHub.com Fallback** ⚠️