Comandos documentais e comunidade

Funcionalidade BB-F-011 · requisito RF-BB-011 · versão documentada 3.0.0 · código 8aea9ccd1b1589d29928b543f1e395352bf6d15a.

Finalidade

Preparar, ler, propor, validar e publicar documentação; orientar Discussions, auditoria de painéis e Social preview.

Atores

Pessoa responsável pelo projeto, IA com posse confirmada e automações explicitamente autorizadas.

Pré-condições

Repositório e raiz corretos, versão instalada e configuração compatível. Para operações de escrita, exige-se autorização vigente, branch adequada e acesso ao recurso envolvido; consultas não conferem permissão adicional.

Fluxo principal

Resolver o destino, gravar rascunho local, enviar a branch bigbang/proposta-ISSUE-slug, registrar base e commit no manifesto e validar antes de publicar. Nova revisão renova a base quando HEAD coincide com a publicação anterior; proposta pendente preserva base e mudança de terceiro bloqueia o ciclo. Os subcomandos e opções têm nomes em inglês (bb docs propose --wiki … --branch …, bb community welcome-post) com os nomes da v2 como aliases.

Validações

A proposta pertence à Wiki do próprio projeto; nome de página e caminhos são seguros; publicar não usa force. O inventário usa o mesmo digest normalizado da validação para os carimbos Big Bang vX.Y.Z.

Alternativas e erros

Colisão, caminho inválido, Wiki concorrente ou comunidade incompleta retorna falha; imagem preparada não equivale a upload confirmado.

Permissões

Leitura usa permissões mínimas do repositório. Operações locais respeitam a posse e worktree; escrita no GitHub exige acesso explícito. Esta funcionalidade não concede novas permissões a visitantes nem substitui decisões exigidas pelo fluxo.

Resultados

Resultado esperado: Preparar, ler, propor, validar e publicar documentação; orientar Discussions, auditoria de painéis e Social preview. O retorno e os arquivos afetados são conferidos pelos cenários rastreados abaixo; falha impede considerar a operação concluída.

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.

documentation_cli.py

Implementação revisada.

Símbolo	Linha
register	11
_read	61
_path	66
_prepare	71
_write	77
_revision_base	104
_propose	112
_validate	139
_publish	156
_inventory	161
_welcome	168
_project	177
_preview	194

Cenários e rastreabilidade

• .bigbang/tests/test_wiki.py:test_public_reads_pinned_wiki_without_legacy_file
• .bigbang/tests/test_wiki.py:test_cli_proposal_review_and_publication_preserve_original_until_confirmed
• .bigbang/tests/test_wiki.py:test_private_reads_existing_file_and_does_not_access_github
• .bigbang/tests/test_wiki.py:test_public_repository_cannot_bypass_policy_with_private_config
• .bigbang/tests/test_wiki.py:test_private_repository_visibility_keeps_current_policy
• .bigbang/tests/test_wiki.py:test_complete_inventory_passes
• .bigbang/tests/test_wiki.py:test_invented_code_commit_is_rejected
• .bigbang/tests/test_wiki.py:test_absolute_links_to_own_wiki_are_checked
• .bigbang/tests/test_wiki.py:test_unlisted_manual_at_root_is_rejected
• .bigbang/tests/test_wiki.py:test_new_implemented_module_without_documentation_blocks_delivery
• .bigbang/tests/test_wiki.py:test_requirement_must_exist_in_actual_documentation
• .bigbang/tests/test_wiki.py:test_empty_functional_sections_do_not_prove_coverage
• .bigbang/tests/test_wiki.py:test_published_head_must_match_exact_reviewed_commit
• .bigbang/tests/test_wiki.py:test_public_stack_guard_uses_approved_table_from_wiki
• .bigbang/tests/test_wiki.py:test_business_rules_survive_migration_without_changing_acceptance_tests
• .bigbang/tests/test_wiki.py:test_changed_behavior_without_doc_refresh_blocks_delivery
• .bigbang/tests/test_wiki.py:test_algorithm_tagged_source_hash_is_validated_and_tampering_blocks
• .bigbang/tests/test_wiki.py:test_missing_test_symbol_or_functional_flow_blocks
• .bigbang/tests/test_wiki.py:test_broken_image_wikilink_and_anchor_are_detected
• .bigbang/tests/test_wiki.py:test_local_system_docs_block_but_functional_contracts_remain
• .bigbang/tests/test_wiki.py:test_public_missing_manifest_fails_clearly
• .bigbang/tests/test_wiki.py:test_traversal_manifest_cannot_read_outside_wiki
• .bigbang/tests/test_wiki.py:test_uninitialized_wiki_does_not_modify_local_documents
• .bigbang/tests/test_wiki.py:test_publish_fast_forwards_and_rerun_is_idempotent
• .bigbang/tests/test_wiki.py:test_concurrent_owner_change_is_preserved_and_publication_rejected

Requisitos · Matriz de rastreabilidade · Referência CLI

Fontes rastreadas

• .bigbang/bb/documentation_cli.py