Migração guiada para a v3

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

Finalidade

Adotar a v3 opcionalmente, sem que bb update mude o fluxo do cliente. Cada parte produz seu próprio PR revisado: config → board → workflow → labels. A esteira legada continua lendo labels em português até a troca final.

Atores

Dono e IA implementadora; revisor independente de cada PR; conta autorizada do GitHub para Project e labels. Decisões e segredos permanecem com o dono.

Pré-condições

Framework atualizado; cópia protegida da configuração e do AGENTS.md; acesso de leitura aos três painéis. Antes de aplicar, rever o plano e escolher um arquivo novo de snapshot. Não migrar no meio de QA/publicação ou de uma sprint ativa. A troca de workflow exige branches epico/* sem commits à frente da develop.

Fluxo principal

bb migrate config --dry-run: traduz os nomes preservando três painéis, epic-branch e labels legacy; remove o trecho do próprio framework herdado em AGENTS.md, incluindo todas as linhas consecutivas da citação; preserva a seção Projeto, suas subseções seguintes e notas independentes do projeto. Aplicar com --snapshot config.json, gerar, revisar e mesclar o PR.
bb migrate board --dry-run: lê os três painéis e mapeia os cartões por evidência. Consulta a listagem paginada de PRs uma vez por execução, normaliza e indexa as branches por issue e reutiliza esse índice nos cartões; o número de consultas de PR não cresce com o número de cartões. Aplicar com --snapshot board.json --yes; cria um Project, confere as automações embutidas e bloqueia se alguma workflow estiver ativa. O dono desativa as workflows na interface do Project e retoma com --project <número> --snapshot board.json --yes. Cada cartão é incluído e recebe diretamente o Status calculado, além do recibo. Ao final, o migrador relê todos os Status, corrige divergências e faz uma segunda leitura de confirmação antes de apontar board.model para single. Revisar e mesclar o PR.
bb migrate workflow --dry-run: confere branches epico/* e lista as mudanças de controles. Aplicar com --snapshot workflow.json, gerar e revisar o PR. O dono confirma gate, ambiente production restrito e PROJECT_*.
bb migrate labels --dry-run: planeja renomes e cópias quando as duas labels existem. Aplicar com --snapshot labels.json --yes, preservando associações antigas quando copiadas; completa o catálogo e grava board.labels=v3. Revisar e mesclar o PR. Conferir um ciclo completo antes de o dono arquivar painéis antigos.

Validações

A ordem é conferida pelo dialeto da configuração, pelo quadro single e pelo workflow grouping. Escritas no GitHub exigem --yes na CLI e todo apply/rollback exige --snapshot. Snapshots existentes não são sobrescritos; depois da criação, o snapshot registra o número do Project para permitir retomada. Workflows ativas bloqueiam a inclusão dos cartões, com orientação para desligá-las em Project → Workflows. A migração só muda bigbang.toml para single depois que uma releitura confirma todos os Status; se a confirmação falhar, a configuração segue apontando para os três quadros. A limpeza de AGENTS.md cobre a citação real de três linhas e a variante de uma linha; termina antes de uma subseção seguinte, inclusive sem linha em branco. O snapshot permite restaurar exatamente a configuração e o AGENTS.md originais. A restauração recusa outra parte ou outro repositório. A migração do quadro usa aprovação de refinamento/protótipo, posse com lease vigente (lock ou comentário confiável com data do servidor), PR aberto/mesclado, workflow agrupador, fechamento, candidata e publicação estável como evidências; não infere aprovação a partir da execução da IA.

Alternativas e erros

--dry-run não grava arquivos, labels, cartões ou recibos. Sem --yes, board/labels mostram apenas o plano. Ao bloquear por workflows ativas, a retomada exige o mesmo snapshot e o número do Project recém-criado; mapa ou quadros divergentes desde o snapshot impedem a retomada. Execução repetida concluída não duplica recibos nem troca o snapshot original. Se a segunda leitura ainda divergir após o reparo, a migração falha sem alterar bigbang.toml; o snapshot, o Project e os recibos ficam disponíveis para diagnóstico e rollback. Para voltar, use --rollback com o snapshot correspondente, em ordem inversa labels → workflow → board → config, por PR revisado. Após rollback, uma nova tentativa calcula evidências atuais e grava recibos com outro identificador; o snapshot anterior permanece protegido. Bugs sem posse ficam Selected, estado permitido pelo núcleo, pois Todo é exclusivo de tarefas. O rollback de labels tolera aplicação parcial e repetição; as associações copiadas incluem issues e PRs. Painéis antigos não são apagados; o Project novo e os recibos de migração permanecem como histórico.

Permissões

A CLI só usa o repositório e o dono configurados. Não aplica rulesets, ambiente ou segredos automaticamente: owner_steps prepara instruções para preservar revisores, políticas e checks. Valores de segredo nunca aparecem no snapshot ou na saída. Nenhuma publicação, aprovação de produção ou decisão humana é concedida pela migração.

Resultados

Configuração v3 em inglês, quadro único com recibos, agrupador com checks e ambiente conferidos pelo dono, e labels v3 com histórico preservado. Cada etapa possui simulação, snapshot e volta. Projetos que não adotarem a migração mantêm o comportamento legado.

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.

migrate.py

Implementação revisada.

Símbolo	Linha
`_iso`	25
`_config_text`	29
`_write_config`	33
`_section_bounds`	41
`set_key`	49
`drop_key`	62
`_require`	68
`_save`	74
`_load_snapshot`	83
`_save_project_number`	96
`clean_agents`	111
`_rollback_order`	116
`config_part`	128
`_labels_of`	164
`labels_part`	168
`_has`	230
`_claimed`	234
`map_card`	262
`_pull_evidence`	304
`_facts`	319
`board_part`	341
`owner_steps`	434
`workflow_part`	450

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

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

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

Correção verificada no piloto

O piloto snake-3310 detectou em #292 uma remoção parcial da citação herdada: a primeira linha saía e duas continuações permaneciam. O teste de regressão reproduz a entrada real antes da correção, incluindo dry-run sem escrita, preservação das subseções e volta exata. A correção fica na develop; não é uma release publicada nem atualiza automaticamente consumidores. A retomada de #259 depende da instrução do dono e de distribuição oficial ou ensaio isolado com a develop.

Funcionalidade migracao v3 - BrunodosSantosVaz/big-bang GitHub Wiki

Migração guiada para a v3

Finalidade

Atores

Pré-condições

Fluxo principal

Validações

Alternativas e erros

Permissões

Resultados

Referência da implementação

migrate.py

board.py

flow_cli.py

gh.py

Cenários e rastreabilidade

Fontes rastreadas

Correção verificada no piloto

Revisão documental

⚠️ GitHub.com Fallback ⚠️

Funcionalidade migracao v3 - BrunodosSantosVaz/big-bang GitHub Wiki

Migração guiada para a v3

Finalidade

Atores

Pré-condições

Fluxo principal

Validações

Alternativas e erros

Permissões

Resultados

Referência da implementação

migrate.py

board.py

flow_cli.py

gh.py

Cenários e rastreabilidade

Fontes rastreadas

Correção verificada no piloto

Revisão documental

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

⚠️ GitHub.com Fallback ⚠️