Guias
Coordene o trabalho na rede da empresa
Reúna os builders numa rede privada da empresa, reserve itens sem duplicidade e exija recibo de verify no CI.
Crie a rede privada da empresa
A rede coletiva reúne projeções mínimas de vários maestros num repositório privado dedicado. Ela não recebe o estado local inteiro, credenciais nem objetos do panorama.
A empresa governa a política e as inscrições. Cada maestro publica só no caminho da própria inscrição.
Crie antes a organização no GitHub ou o grupo no GitLab e dê à conta usada pelo Orkastery permissão para criar repositório nesse dono. ork network empresa criar cria e relê o repositório privado; a operação falha se a forja devolver outro dono, outro caminho ou visibilidade pública.
A política grava o nível de cobertura, com --nivel observar, avisar ou exigir, e a versão do recibo, com --recibo-versao. A guarda local de reservas continua obrigatória em todos os níveis.
ork network empresa criar --forja github --dono <organizacao> --repositorio <rede> --nivel avisarInscreva cada maestro com duas autoridades
Primeiro, a empresa roda ork network empresa inscrever e registra a identidade esperada do maestro: forja, host e accountId numérico. Essa operação não aceita a inscrição nem cria configuração local.
Depois, o maestro entra na conta esperada e roda ork network empresa aceitar. O aceite relê a inscrição, resolve a conta autenticada e recusa outra forja, outro host ou outro accountId. Antes de aceitar, confira no resumo o destino, a versão da política, os projetos autorizados e as categorias publicadas.
ork network empresa publicar resolve a conta de novo, recompõe e varre a projeção antes de gravar. ork network empresa status mostra a projeção publicada, a fonte e uma publicação pendente.
ork network empresa sair encerra a inscrição quando a política permite. ork network empresa revogar cessa as novas publicações de uma inscrição administrada.
As escritas usam uma única branch, sem force, e cada inscrição tem caminho próprio. Sem alcance à forja, nada entra em fila: o status local fica pendente e orienta conferir login, acesso e alcance.
ork network empresa inscrever --empresa github:<org>/<rede> --inscricao <id> --rede github:<org>/<rede> --projetos github:<org>/<projeto> --account-id <n> --login <login>
ork network empresa aceitar --empresa github:<org>/<rede> --inscricao <id> --rede github:<org>/<rede> --projetos github:<org>/<projeto>
ork network empresa publicar --inscricao <id>
ork network empresa status --inscricao <id>Reserve um item do roadmap para a empresa toda
Com inscrição ativa, ork thread new --roadmap, ork roadmap pegar e ork_thread_new usam a mesma operação: reservam primeiro na rede coletiva, depois localmente, e vinculam a thread à reserva. Sem inscrição ativa, a saída continua a de antes, sem aviso coletivo.
A reserva coletiva tem uma única titular. Outra identidade recebe a inscrição, o login, o projeto e a fase da titular, e só entra como colaboradora (--coordenacao colaborador) ou por acordo autenticado (--coordenacao acordo), com um comentário ou nota da issue de coordenação conferido pela API da forja.
Nos níveis observar e avisar, a cobertura não configurada, não conferida ou com reparo pendente aparece na saída, e a operação segue. Em exigir, nova reserva ou thread sem conferência atual é recusada; só uma exceção autenticada para o projeto e o item, com responsável, justificativa e expiração, libera a operação.
Cada tentativa tem um operationId. Se um efeito posterior falha, o Orkastery desfaz o local e o coletivo na ordem inversa, enquanto as fingerprints conferem; divergência deixa a operação pendente. ork roadmap reconciliar repara, e repetir depois do reparo é seguro.
ork roadmap pegar RM-NNN
ork thread new <nome> --modo auto --roadmap RM-NNN --coordenacao colaborador
ork roadmap reconciliar RM-NNN --operacao op-<id>O que sai da máquina
A projeção é uma lista fechada: campo que não está nela não sai. Saem a versão da política e a inscrição; forja, host, accountId e login atual do maestro; o caminho controlado do repositório; id e estado dos itens; reservas e trabalhos com referência opaca da thread e fase; e padrões relativos de touch_paths, lease e diff.
Não saem configuração local, home, nome de máquina, nome civil, e-mail, token, credencial, clone ou remoto cru, títulos e textos livres, slug, branch, pergunta, runtime, modelo, sessão nem conteúdo de arquivo.
Antes do envio, a projeção passa pela policy dado_privado e pela varredura de segredo. Scanner indisponível ou achado impedem a publicação, sem repetir o valor encontrado.
A publicação grava os contratos ork.rede-empresa-publicacao/v2 e ork.rede-empresa-publicacao/v3 na mesma transação; a v3 acrescenta os caminhos por trabalho.
Aviso de conflito antes do merge
O preflight compara trabalhos de builders diferentes no mesmo projeto. Há conflito quando o item coincide ou quando os globs de caminho se cruzam. Padrão fora da linguagem aceita (segmentos literais, *, ? e **) vira lacuna tipada, não conflito.
A ordem sugerida segue a primeira aparição de cada trabalho no histórico de primeiro pai. Histórico raso ou truncado sai como inconclusivo, e o relógio local não decide a ordem.
A mesma análise aparece em ork network empresa status, ork ship publicar, ork ship pista, ork ci run, no ork_thread_status antes de ork_ship e antes do ork ship direto. Ela é consultiva nos três níveis: não muda gate, autorização, verify, CI, lease, merge nem push.
No CI de PR ou MR, o segredo opcional ORK_REDE_EMPRESA_READ_TOKEN, só com leitura do repositório da rede, deixa o ork ci run anexar o preflight. Sem ele, ou em PR de fork, a saída informa “Checagem coletiva não realizada”, e o resultado do CI não muda.
ork network empresa status --inscricao <id> --json
ork ship pista <thread>Exija recibo de verify no CI
A política de recibo é opt-in por repositório, pela chave ci.politica_recibo do orkastery.yaml. Sem a chave, ork ci run --branch mantém o resultado e o código de saída de antes; valor diferente de observar, avisar ou exigir invalida o manifesto.
observar relata o estado do recibo: presente, ausente, invalido ou sha-divergente. avisar faz o mesmo e escreve anotação e resumo do job no GitHub, ou aviso no log do GitLab. exigir reprova PR ou MR para worktree.base_branch quando o recibo não está presente; push na própria branch protegida não ganha essa reprovação.
ork ci prepare grava no bundle a projeção ork.ci-projecao-replay/v1, sem afirmar HEAD. No checkout do PR ou MR, o runner valida a projeção, reexecuta preparo, claims e comandos pelo mesmo julgamento do verify, num ambiente allowlisted sem token, segredo ou credencial, e emite ork.ci-recibo-runner/v1 com o HEAD executado.
O recibo só fica presente com ao menos uma claim, comandos e preparo idênticos aos do verify do manifesto da branch de destino e rodada integral verde. Falha atual de preparo, claim ou comando reprova nos três níveis, sem exceção de dívida anterior: a baseline projetada vem do próprio PR e não entra no julgamento.
As causas de recibo inválido são fechadas, cada uma com mensagem e ação: ci.recibo.projecao-acima-do-limite, ci.recibo.claim-nao-hermetica, ci.recibo.runner-sem-capacidade, ci.recibo.comando-nao-iniciado, ci.recibo.prazo-excedido e ci.recibo.produto-alterado.
# orkastery.yaml
ci:
context: ork-verify
politica_recibo: exigirTorne o check obrigatório e conheça o limite
O manifesto define o comportamento do job; a regra da forja impede o merge. No GitHub, proteja o orkastery.yaml e o workflow com CODEOWNERS e marque ork-verify como status check obrigatório num ruleset ou numa regra de proteção da branch. No GitLab, proteja a branch base e ligue Pipelines must succeed.
O bundle e o sha256 vêm do próprio PR e podem ser forjados por quem controla a mudança. A âncora no manifesto da branch de destino prova que a receita aceita não esvaziou as claims nem trocou os comandos ou o preparo protegidos.
Ela não prova completude nem autenticidade das claims, nem autoria do bundle ou do código. A garantia contra forja é o recibo assinado da F7 da RM-089, que ainda não saiu.
# CODEOWNERS
/orkastery.yaml @platform-team
/.github/workflows/ci.yml @platform-team