Pular para o conteúdo

Referência

Contratos e capacidades

Interprete snapshots, capacidades de runtime e métricas sem atribuir autoridade ao relato.

Panorama Maestro

ork.maestro-snapshot/v1 é uma projeção de leitura. Suas seções declaram fonte, instante, fingerprint, estado e cobertura. empty significa vazio observado; unavailable significa fonte inacessível. Paginação e omissões fazem parte do contrato. O snapshot não cria ciclo, aprova gate ou comprova SHIP. O snapshot também traz project.root, com ~, project.remote, sem credencial, e notConsulted, com o que o panorama não leu. Zero threads no panorama nunca quer dizer roadmap vazio.

ork maestro --json
ork maestro --json --thread <thread>

Prova de ativação por host

prova-ativacao.cjs abre uma sessão nova e não interativa no host instalado, numa cópia descartável do projeto, e pede orkastery maestro. A conferência julga só o determinístico: a entrada contratada foi exposta e chamada, e o resultado cumpre o contrato dela, com o projeto esperado e o que não foi consultado. A resposta tem de nomear o projeto e não pode concluir roadmap vazio. Os hosts da prova são claude-code, openclaw e codex. No Codex, a entrada é mcp__orkastery__ork_maestro, o servidor MCP do projeto vai à sessão por -c e as ferramentas expostas vêm do tools/list desse servidor; a sessão efêmera não pode ficar em $CODEX_HOME/sessions.

O roteiro também confere que a consulta não escreveu no estado do projeto e que a configuração global do host não mudou. O recibo ork.prova-ativacao/v1 sai redigido. Saídas: 0 aprovada, 1 reprovada, 2 host ausente ou fora da prova, 3 pendente de ação humana. A prova não consente MCP nem reinicia gateway por ninguém.

node core/scripts/prova-ativacao.cjs claude-code
node core/scripts/prova-ativacao.cjs codex

Registro de projetos e cabeçalho da consulta

ork.projetos/v1 é o registro desta máquina em ~/.orkastery/projetos.json, com modo 0600 e sem segredo: nome, abbrev, raiz, remoto sem usuário nem senha, datas e a fonte do registro. Arquivo ausente, corrompido ou de outro contrato vale registro vazio. ork.consulta/v1 é o cabeçalho de ork maestro, ork board, ork board plan, ork fabrica, ork roadmap status e, na versão 0.6.10, ork roadmap reservas: o projeto consultado, a origem da escolha, o que foi lido e o que não foi.

As recusas projeto.desconhecido, projeto.ambiguo, projeto.sem-manifesto, projeto.escolha, projeto.nenhum e projeto.fora-do-servidor trazem os candidatos e a correção. Quem consome o registro lê sem gravar, confere o contrato e nunca escolhe a primeira cópia de um nome ambíguo. Na versão 0.6.10, o ork privado é um dos comandos que não leem projeto: ele varre o repositório do diretório atual e não resolve alvo global.

Sem o remoto, o naoLido diz que nada foi lido de ork/fabrica-estado; na versão 0.6.10, nas reservas, diz o mesmo de ork/roadmap-reservas, e o JSON delas traz o campo leitura (lido-agora, copia-local, sem-copia ou sem-remoto): só lido-agora ou copia-local sem reserva viram a mensagem de nenhum item reservado. Nas reservas, projeto.remoto é o remoto lido (--remoto, ou origin); em ork board e ork fabrica, é o fabrica.remoto do manifesto.

Também na versão 0.6.10, os demais comandos que leem um projeto terminam com a mesma primeira linha, Projeto consultado, no stderr, quando o leitor não tem como saber qual projeto foi lido: no host (ORK_PROJETO_EXPLICITO=1) ou com o projeto fora do diretório atual. A linha vem uma vez por comando, também quando ele falha, antes da mensagem de erro, e o stdout, inclusive o JSON, não muda. Nela e no cabeçalho, o remoto é o de exibição: sem usuário e senha, sem query e fragmento, com ~ no lugar da pasta da conta no caminho local, e omitido quando ainda parece segredo.

Na versão 0.6.10, a sessão despachada (ork phase run, ork retry run e ork audit run) recebe ORK_PROJETO vazio e ORK_PROJETO_EXPLICITO=0 no ambiente: o projeto dela é o do próprio cwd, a worktree da thread, e o modo host de quem despachou não a segue. No Codex, os dois valores vão por cima do ambiente herdado; no claude-bg, pelo --settings, que vence o ambiente do daemon. O filho ork fabrica publicar herda o mesmo.

ork projetos --json
ork roadmap status --json
ork roadmap reservas --json

Contratos da Orkastery Network

ork.rede/v1 é a adesão desta máquina, em ~/.orkastery/rede.json; membro false é a saída explícita e vence a adesão herdada. ork.rede-maquina/v1 é o retrato publicado em maquinas/<maquina>.json na casa privada: o alias genérico da máquina, id da instalação, o mesmo alias no campo legado hostname, forjas com o login, runtimes e hosts com versão, projetos com remoto sem credencial, versão do ork e batida. ork.rede-status/v1 é a leitura de ork network status --json: casa, esta máquina, fontes, membros, lacunas e o que não foi consultado.

Sem --maquina, ORK_MAQUINA ou alias já gravado, a entrada recusa com rede.maquina-generica. O hostname real nunca é usado como reserva e nunca vai ao JSON, ao nome do arquivo ou ao commit.

Campo novo e opcional não muda a versão. O leitor ignora retrato malformado, com nome de outra máquina ou com caractere invisível e o transforma em lacuna; o escritor publica só o que o leitor aceita. A casa fala só por HTTPS, e o ork nunca lê token.

ork network status --json

Verify assíncrono no MCP

ork.verify-mcp/v1 é o contrato de ork_verify e ork_verify_status. A resposta traz rodadaId, threadId, o vínculo do despacho, estado, lane e as datas, e reutilizada é true quando já havia uma rodada viva para a thread. O modelo não escolhe raiz, comando, PID, prazo nem lease: o servidor fixa projeto, thread, host e despacho.

Os estados são na-fila, rodando, concluido e falhou. Em concluido, o veredito é o mesmo resultado e o mesmo texto do ork verify no CLI, para o mesmo HEAD, claims, manifesto e modo do CHECK. Em falhou, o motivo é tipado (verify.processo-morto, verify.worker-failed ou verify.lease-perdida) e o resultado nunca é verde; as recusas fila-pesada.ocupada e conducao.em-andamento vêm inteiras em falha.recusa. A consulta é só leitura: não inicia, não repete e não muda o veredito.

Capacidade e permissão são distintas

O playbook descreve transporte, ferramentas nativas e limites por fase. PLAN não edita produto; GO recebe a worktree; CHECK requer revisão independente. Um schema de saída de claims contém candidatos: a resposta do modelo não registra nem verifica a alegação. Configuração instalada não comprova homologação live.

O Grok Build ainda não entra na matriz de capacidades do playbook: um runtime só entra nela com o ensaio real da homologação, que é a F5 da RM-067. Na versão 0.6.10, o despacho, o setup e o fallback, o sandbox com piso workspace, as instruções do projeto, a conta por perfil, o MCP do núcleo fora do sandbox e o inventário de sessões já valem para ele; o formato da cota esgotada e a conferência do login seguem como lacunas.

Métrica com cobertura e origem

ork.ledger-stats/v1 agrega fatos registrados em um intervalo semiaberto UTC. Tokens e duração têm cobertura explícita; ausência continua ausente. custoReferencia é uma estimativa para comparar cenários, não uma fatura. Throughput depende de ship_done; não conte um commit local como entrega remota.

hitlDeConducao mede o tempo parado pelas perguntas que o próprio ork abriu ao dono: pedidos, respondidos, sem resposta e abertos, o tempo parado no período, a mediana e a maior espera das respondidas, e a meta de 5 minutos, com null quando não há amostra. A decisão informada não para nada e fica fora. O ork pulse e o ork roadmap status levam o mesmo cálculo no campo opcional hitlDeConducao, com abertas, seteDias e acimaDaMeta; o campo só aparece com pergunta aberta ou com pergunta e resposta na semana, e a visão da rede não o soma.

ork ledger stats --desde 7d --json

Forja e autorização durável

Na versão 0.6.10, o núcleo reconhece a forja do projeto, GitHub ou GitLab, pela CLI dela já logada, gh ou glab, e nunca lê nem passa token. O bloco opcional forja: do orkastery.yaml declara tipo, host, porta, caminho_base, ssh_host, ssh_porta e ca; sem ele, tudo vem do remoto origin e da sondagem. A forja é resolvida pelo manifesto, pelo host conhecido ou pela sondagem só da CLI com login no host, nunca pelo nome do host; sem resposta, forja.desconhecida, e com duas, forja.ambigua.

O ci.produtor diz quem aprova o check exigido, com github-actions por padrão, e no GitLab só o job da pipeline do projeto conta como produtor gitlab-ci. O ork ci status passa a ork.ci-status/v2, com provider, fonte e produtor, e a v1 continua lida. O ork ship publicar recusa remoto Enterprise sem forja: e sem login da CLI antes de qualquer escrita (forja.desconhecida), e o registrar-pr --repo não tem host de reserva: sem leitura, entrega.sem-leitura.

A autorização durável é o contrato ork.autorizacao-duravel/v1, em .orkastery/monitor/autorizacao.json, fora do git. Ela vale só nesta máquina e neste projeto, com prazo ISO de fuso explícito, por até 31 dias, e uma lista fechada de ações: limpar, registrar, master, merge e despachar. Ação fora do contrato invalida o arquivo inteiro, e sem autorização a batida não age.

ork doctor --json --forja
ork ci status --json
ork conducao autorizacao --json

Recibo no CI e preflight coletivo

ci.politica_recibo aceita observar, avisar ou exigir. Sem a chave, o resultado e o código de saída de ork ci run --branch ficam como antes; com ela, todo resultado traz o nível e o estado do recibo. O bundle segue em ork.ci-bundle/v1, e o campo opcional recibo passa a ser ork.ci-projecao-replay/v1; a forma anterior só é lida por compatibilidade e não satisfaz a prova.

O runner emite ork.ci-recibo-runner/v1 dentro de ork.ci-run/v1, com head, thread, claimsSha256, rodadaSha256, check, resultado e sha256, e reserva o campo assinatura para a F7. presente exige o mesmo HEAD no recibo, no commit do resultado e no checkout, ao menos uma claim, comandos e preparo idênticos aos do verify do manifesto da branch de destino e rodada integral verde. Ref ou manifesto de destino ilegível falha fechado, e branch externa e fork não ganham exceção.

Fronteira de confiança: a âncora no manifesto de destino prova que a receita aceita não esvaziou as claims nem trocou os comandos ou o preparo. Ela não prova completude ou autenticidade das claims, autoria do bundle nem integridade do código; a garantia contra forja é do recibo assinado da F7.

Com inscrição ativa na rede da empresa, as superfícies de entrega leem uma fotografia coletiva e rodam a mesma análise de conflito e ordem sugerida, consultiva nos três níveis. No PR ou MR, ork ci run só atualiza o cache da rede com ORK_REDE_EMPRESA_READ_TOKEN e fora de fork; o segredo segue pelo ambiente do Git e nunca entra em argv, saída, bundle ou publicação.

ork ci prepare <thread>
ork ci run --branch <branch> --json