Guias
Comprove uma alegação
Use baseline, comandos reproduzíveis e o resultado real da execução.
Meça antes da mudança
Grave a baseline antes de implementar. Ela permite distinguir uma regressão de uma falha anterior. Uma claim associa arquivo, alegação e comando; cadastrá-la não executa o comando nem comprova a alegação.
ork verify <thread> --baseline
ork claims add <thread> src/filtro.ts --claim "o filtro respeita o fuso" --verificar "node --test test/filtro.test.js"Reexecute no estado atual
ork verify reexecuta claims e verificadores do manifesto. Leia a causa, o código de saída e os comandos interrompidos. Timeout é uma execução incompleta, não uma prova de aprovação nem uma explicação automática sobre a causa do defeito.
Quando o runner nomeia as falhas, o verify compara teste a teste dentro do mesmo comando: o nome que só aparece agora é regressão e bloqueia com verify.regression, o que aparece nos dois lados segue como dívida anterior e o que só existia na baseline fica como corrigido. Teste renomeado conta como o antigo corrigido e o novo em regressão. Sem os nomes, vale a comparação por comando, e a saída diz isso em vez de afirmar zero regressões.
ork verify <thread>
ork retry plan <thread>Leia o relatório JUnit de qualquer runner
Para ler o resultado estruturado, troque só o valor do comando por um mapa com comando e junit, o caminho do relatório relativo à worktree. As duas formas convivem no mesmo manifesto, e cada runner escreve o relatório com a própria opção, como no bloco abaixo.
O verify apaga o relatório antes do comando e lê o novo depois. Só vale arquivo regular, dentro da worktree e produzido nessa execução. Relatório ausente, inválido, grande demais, antigo ou alcançado por link não é evidência, e o ledger registra o motivo.
O código de saída continua julgando o comando: o XML nunca transforma vermelho em verde. Com JUnit válido, todas as falhas e erros vão ao ledger, com as contagens e a duração somada, e o texto resume os dez primeiros. Sem relatório, a comparação nominal fica nos até dez nomes que o verify extrai da saída.
No objeto, a chave junit é obrigatória. A única exceção é a lane do Agile que declara recursos; mesmo nela, filtro e relogio exigem o relatório, e a mensagem de erro diz qual chave o pediu.
verify:
build: "npm run build"
test:
comando: "pytest --junitxml reports/pytest.xml"
junit: reports/pytest.xml
pytest --junitxml reports/pytest.xml
vitest run --reporter=junit --outputFile=reports/vitest.xml
JEST_JUNIT_OUTPUT_FILE=reports/jest.xml jest --reporters=default --reporters=jest-junit
PLAYWRIGHT_JUNIT_OUTPUT_NAME=reports/playwright.xml playwright test --reporter=junit
gotestsum --junitfile reports/go.xml -- ./...Verify assíncrono pelo MCP
Pelo MCP, ork_verify inicia a rodada num worker do servidor, fora do sandbox da sessão, e devolve na hora um rodadaId. O worker espera a mesma fila pesada do CLI, usa os prazos do manifesto e grava o mesmo veredito do ork verify. Enquanto a rodada estiver viva, repetir ork_verify devolve o mesmo id, sem abrir uma segunda execução.
ork_verify_status acompanha a rodada: na-fila, rodando, concluido ou falhou. Consulte a cada 30 a 60 segundos. Processo morto, worker que termina sem veredito e lease perdida são falhas tipadas e nunca viram aprovação.
Se a fila não consegue provar que o dono de um lease está vivo, o estado é concurrency.lease-indeterminado: a sessão espera com --esperar, e o lease nunca é apagado nem tomado por inferência. Quando a sessão precisa de uma ação fora da autoridade dela, ork_request_conduction registra um motivo enumerado e um comando de uma linha, sem executá-lo, e o pedido fica com a condução.
Corrija e volte à verificação
Uma falha abre trabalho de correção com escopo explícito. Consulte a rodada antes de reexecutar. Correções que alteram comportamento exigem nova verificação completa; o limite de tentativas e a escalação pertencem ao núcleo.
ork fix open <thread>
ork fix list <thread>
ork fix reverify <thread>Na correção, rode primeiro o que caiu
Um comando com JUnit pode declarar também a chave filtro: o comando do próprio runner com o marcador {testes} uma única vez. Na rodada de correção, o verify troca o marcador pelos nomes que caíram no último verify_run, cada um como argumento separado e escapado.
Os nomes chegam exatamente como o relatório os produziu, sem conversão para o id do framework, então o comando declarado precisa saber consumi-los. A rodada segue estas regras:
- Sem filtro, sem JUnit válido ou sem nomes na rodada anterior, roda o comando completo, como antes.
- Se o comando completo mudou desde a rodada anterior, os nomes não são reaproveitados.
- Passagem filtrada vermelha reprova ali e marca a rodada como parcial, com os nomes no texto e no ledger.
- Passagem filtrada verde segue para o comando completo, e só esse resultado deixa a rodada verde.
- No Agile, cada lane declara o próprio junit e o próprio filtro, e nunca recebe os nomes de outra.
- O
ork shiprecusa recibo parcial, mesmo verde: a suíte inteira verde no HEAD continua obrigatória.
verify:
test:
comando: "pytest --junitxml reports/pytest.xml"
junit: reports/pytest.xml
filtro: "pytest --junitxml reports/pytest.xml {testes}"Agile Check, o CHECK padrão
Na versão 0.6.10, o CHECK padrão é o Agile Check. Ele roda o preparo uma vez, as claims contra o produto dele com a guarda de hash, as lanes de teste e a varredura em paralelo. O Classic Check continua disponível por check.mode: classic no manifesto ou por ork verify --check classic|agile, e a opção da rodada vence o manifesto.
Os dois modos têm a mesma cobertura e o mesmo veredito: o Agile nunca reduz cobertura em silêncio, e a peça indisponível cai para o equivalente do Classic, com a peça, o motivo e o que rodou no lugar registrados em agile.pecas. O preparo roda uma vez, e a claim que começa pelos passos do verify.preparo o reaproveita enquanto a árvore e o hash do produto forem os do fim do preparo; qualquer divergência roda o comando inteiro. As lanes correm em paralelo, e a lane que sobe containers espera a varredura terminar.
Cada verify_run registra o modo da rodada e de onde ele veio (opcao, manifesto ou padrao), a linha check do texto do ork verify mostra o nome do modo, e o ork thread status mostra o do último verify. Sem o bloco check.agile, o Agile roda os mesmos comandos do Classic. Valor fora de agile e classic torna o manifesto inválido.
Desde a 0.6.3, a lane hermética recebe de volta as CPUs reservadas quando a varredura e a integração terminam, e os testes caros criam uma vez por processo os modelos de repositório que cada caso copia. As lanes podem usar tmpfs com ORK_CHECK_TMPFS=auto quando memória, espaço e escrita têm folga; o padrão continua em disco, e todo fallback diz o motivo.
Na 0.6.5, o grupo do Agile mantém a soma das reservas dentro da capacidade medida. O agendador decide pela mediana de várias amostras de carga e steal, sem apagar o pico da evidência. Steal acima do limiar reduz a capacidade de cada peça na proporção medida, e a peça do agendador sai como degradado, com a capacidade usada, em vez de devolver o grupo inteiro à ordem do Classic. Essa ordem só volta quando o grupo paralelo não cabe ou a máquina está ocupada.
A integração reserva a CPU que mede: com perfil compatível, a reserva segue o pico sustentado da lane, e a hermética recebe o restante; sem perfil, a reserva continua conservadora. Nenhum teste sai, o Classic não muda, e a razão contra o Classic só vale com três pares válidos da bancada.
check:
mode: classic
ork verify <thread> --check classic
ork verify <thread> --baseline --check agileSeleção nativa na rodada morna
Uma lane de check.agile.test pode declarar a chave selecao: o comando nativo do runner que escolhe os testes pela mudança, os caminhos que ele garante mapear (mapeia) e os arquivos de configuração que invalidam essa garantia (configuracao). Sem a chave, a lane roda inteira, e verify.test e o Classic não aceitam a declaração.
O comando leva exatamente um marcador: {base} recebe o commit da rodada anterior, para o runner que calcula o diff pelo Git, e {arquivos} recebe cada caminho mudado como argumento separado.
O verify_run grava a seleção e, em cada lane, o modo, o motivo, os arquivos e a base. O texto diz SELECIONADA ou INTEIRA. Rodada selecionada verde pode alimentar a seguinte, mas continua parcial: o ork ship a recusa pelo mesmo contrato da correção nominal.
A seleção só vale quando o último verify_run ficou verde, com o cache reconhecido, commit ancestral do HEAD, o mesmo merge-base e a árvore limpa. Fora disso, a lane roda inteira e registra o motivo:
- cache ausente, inválido, vermelho, de outra base ou fora da ancestralidade;
- mudança no
orkastery.yaml, nodevmaster.yaml, no lockfile ou numa configuração declarada do runner; - caminho mudado fora de mapeia, nenhum caminho verificável ou mapeia vazio;
- rodada fria, que é sempre inteira, ou Classic Check.
check:
mode: agile
agile:
test:
vitest:
comando: "vitest run --reporter=junit --outputFile=reports/vitest.xml"
junit: reports/vitest.xml
selecao:
comando: "vitest run --changed {base} --reporter=junit --outputFile=reports/vitest.xml"
mapeia: [src/**, test/**]
configuracao: [vitest.config.*, vite.config.*]
jest:
comando: "jest --ci --reporters=default --reporters=jest-junit"
junit: reports/jest.xml
selecao:
comando: "jest --findRelatedTests {arquivos} --ci --reporters=default --reporters=jest-junit"
mapeia: [src/**, test/**]
configuracao: [jest.config.*, package.json]
playwright:
comando: "playwright test --reporter=junit"
junit: reports/playwright.xml
selecao:
comando: "playwright test --only-changed={base} --reporter=junit"
mapeia: [src/**, tests/**]
configuracao: [playwright.config.*]Workers e recursos por lane
Ao lançar uma lane, o Agile exporta ORK_WORKERS com a reserva vigente que o agendador deu a ela, sempre com pelo menos um worker; a lane que começa depois de uma devolução recebe o valor novo. O Classic exporta a mesma variável com a capacidade inteira disponível, então o mesmo comando serve nos dois modos, sem mudar a ordem do Classic.
A forma em texto da lane continua válida. No objeto, a chave recursos fica ao lado de comando, junit, filtro, relogio e selecao. Duas lanes com um recurso em comum, como um banco local ou uma porta, não se sobrepõem, e recursos diferentes não criam dependência. A lane adquire o conjunto inteiro antes de ocupar uma vaga, sem espera circular.
Cada runner lê a variável no próprio comando e mantém o fallback quando roda fora do ork. ORK_WORKERS é o contrato público; as demais variáveis da rodada continuam internas.
check:
agile:
test:
rapida: "npm run test:rapida"
e2e:
comando: "PLAYWRIGHT_JUNIT_OUTPUT_NAME=reports/playwright.xml npx playwright test --reporter=junit"
junit: reports/playwright.xml
recursos: [postgres-local, porta-http]
pytest -n "${ORK_WORKERS:-auto}"
playwright test --workers="${ORK_WORKERS:-50%}"
vitest --maxWorkers="${ORK_WORKERS:-50%}"
jest --maxWorkers="${ORK_WORKERS:-50%}"
go test -p "${ORK_WORKERS:-1}"O security scan no CHECK
Com verify.security_scan declarado no manifesto, o ork verify roda o ork security-scan como o quarto comando, depois de build, test e typecheck. Quem julga é a ferramenta, e o agente só lê o resultado. Sem a chave, verify, CI, SHIP e skills seguem como antes; o ork init grava a chave sozinho quando reconhece uma stack JavaScript/TypeScript, Python ou Go.
O scan cobre segredo com o Gitleaks, SAST com o Semgrep, dependência com o Trivy e o auditor da stack, IaC com o Trivy config, workflow com zizmor e actionlint, qualidade com ESLint, Ruff ou golangci-lint, e licença com o Trivy license. As ferramentas rodam por imagens oficiais fixadas por digest, com o repositório montado só para leitura; sem Docker, vale o binário nativo, e sem os dois a ferramenta fica unavailable.
O scan compara o HEAD com a base e classifica cada achado como new, existing ou dismissed. Achado new de segredo entra no laço sempre; new de dependência, SAST, IaC e workflow entra com high ou critical; qualidade e licença ficam em aviso. Achado no laço faz o ork security-scan sair 1 e o verify reprovar, e o CHECK lê o report.json com o security-auditor para dar um veredito por achado.
Sem Docker nem binário, o scan local sai 0 com a ferramenta unavailable, o que não vira limpo no SHIP: com verify.security_scan declarado e sem ci.required_for_ship, o ork ship para com human.pending e só segue com ork ship <thread> --para main --allow-unscanned "<quem autoriza>".
verify:
security_scan: ork security-scan
ork security-scan
ork security-scan --check agileFalha, prazo e comando específico
O verify registra causa, prazo e duração. Timeout é tipado e o prazo vem do manifesto; não deve virar falha genérica. Claims devem rodar o menor comando que prova a mudança. O lint avisa no ork claims add, e o ork ci prepare recusa a suíte local inteira: npm --prefix core test pode depender de recursos ausentes no CI. No lugar da suíte inteira, use só o teste da claim (node --test no arquivo do teste) ou um script hermético do projeto.
O preparo do CI compila uma vez, vincula a identidade do produto e registra executado para distinguir resultado real de comando não executado. Em máquina sob contenção, a saída local pode expirar; isso não dispensa o CI no commit exato nem converte falha em aprovação.
node --test test/filtro.test.js
ork ci prepare <thread>Teste de relógio sob steal da CPU
Numa VPS, o hipervisor pode tomar a CPU (o steal), e um teste que mede relógio reprova sem que o código tenha mudado. O ork verify, no CLI, no MCP e no ork fix reverify, mede o steal no /proc/stat, na rodada e na janela de cada comando, e grava a medida no verify_run (steal, e stealPct em cada comando que falha).
Quando um comando reprova só em teste com relógio e o steal na janela dele passou de 40%, a reprovação vira verify.timeout: sem veredito, o retry reexecuta, e nunca é regressão. Teste com relógio é o caso marcado no manifesto e confirmado pelo JUnit, o que falhou com a assinatura de prazo do node --test (estouro do teste, ou cancelado pelo pai que estourou) ou o que tem entrada vigente no registro de instabilidade; sem JUnit, os nomes vêm do testeQueCaiu do ledger, que também lê o reporter spec do node --test. Asserção comum sob steal alto continua regressão, comando sem teste nomeado nunca é reclassificado e sem /proc/stat nada é atenuado. O ork ci run não mede nem atenua: o CI segue sendo a prova independente.
O registro é o core/instabilidade.json, no contrato ork.instabilidade/v1, lido da worktree que o verify confere. Ele nasce vazio e só aceita entrada com a taxa medida (falhas em rodadas, o comando que mediu e a data) e revalidação em até 30 dias. Arquivo ausente vale registro vazio; com erro de contrato, nenhuma entrada vale; entrada vencida não vale até alguém medir de novo. O registro nunca atenua sozinho: ele só diz que o teste é de relógio.
{
"contrato": "ork.instabilidade/v1",
"entradas": []
}Marque os testes de relógio no relatório
Um comando ou lane com JUnit pode declarar a chave relogio, com uma única estratégia: nome, uma lista de expressões regulares sobre a identidade JUnit; ou marcador ou tag, que dizem que o próprio comando já seleciona só aquela categoria. Sem a declaração, o julgamento do Classic e do Agile não muda.
Sob steal acima do limiar, só a reprovação formada inteira por casos marcados fica sem veredito. Quando a chave filtro existe, o verify roda esses nomes de novo, isolados. Essa segunda rodada é diagnóstico e nunca torna verde o primeiro resultado.
Falha comum no mesmo comando continua regressão, e caso marcado que cai sem steal alto também. Texto e ledger dizem os nomes, o steal medido e o resultado da segunda rodada (passou, reprovou, sem-veredito ou sem-filtro), em relogioSobSteal e retesteDeRelogio.
verify:
test:
comando: "pytest -m desempenho --junitxml reports/pytest.xml"
junit: reports/pytest.xml
relogio: { marcador: desempenho }
relogio: { nome: ["tempo$"] } # Vitest
relogio: { nome: ["latencia"] } # Jest
relogio: { tag: "@tempo" } # Playwright
relogio: { nome: ["/Tempo$"] } # GoDependência opcional ausente é skip
A suíte local inclui integrações que pedem o codex do sandbox em /usr/bin/codex, o interpretador do OrkMind no PATH ou PostgreSQL pelo Docker com pgvector/pgvector:pg16. Cada teste que depende de uma delas sonda antes e, se ela falta, sai como skip com o motivo, em vez de reprovar. A suíte inteira passa com 0 falhas numa máquina sem nenhuma delas, e o fim do relatório conta os skips; uma falha que sobra é de verdade.
ORK_TESTE_EXIGE_AMBIENTE=1 não pula nada: a dependência que faltar reprova. O test:ci liga a variável sozinho. node core/scripts/suite-local.cjs roda a suíte, sai 0 só com 0 falhas e lista cada skip com o motivo. Teste novo que depende de ferramenta externa usa os atalhos semCodexSandbox(), semOrkMind() e semPostgres().
npm --prefix core test
ORK_TESTE_EXIGE_AMBIENTE=1 npm --prefix core test
node core/scripts/suite-local.cjsModelo indisponível e conta da sessão
model_not_found produz runtime.model-unavailable. O retry tenta destinos autorizados com o mesmo prompt, preserva o perfil para outros modelos e registra a troca. Sem destino, escala com a correção de setup; rate limit comum espera sua janela. ork sessions stop, logs e attach procuram a conta correta nos perfis Claude configurados. O inventário global, o ork doctor, o ork pulse e o controle nativo de HITL ainda podem ter cobertura restrita à conta do processo. Um perfil pedido com --perfil que não existe ou é de outro runtime recusa com runtime.profile-invalid e escala ao humano, sem trocar de perfil sozinho.
Quando a sessão morre por cota depois de produzir, o retry não reenvia o prompt original sobre a worktree alterada: ele despacha ou enfileira um prompt derivado com fase, último commit, status, claims e rodada, preservando o prompt e o SHA-256 originais. O checkpoint manda continuar sem repetir GOAL nem PLAN, e a sessão que não produziu nada recebe o prompt original.
runtime.workspace-untrusted (o runtime recusou o diretório da worktree) e runtime.consent-pending (o CLI espera o aceite de termos novos) viram espera do dono, com o comando exato; depois do aceite, ork retry run re-despacha a mesma fase com o mesmo prompt. O runtime.consent-pending cobre também o aviso do modo sem permissões e a ativação do modo auto do --bg, e a prova de que o dono confiou no diretório segue a regra que o Claude Code aplica no --bg: vale o próprio diretório e os de cima até a raiz git, ou o repositório principal da worktree vinculada, mas não o diretório acima da raiz git. O diretório que não existe mais e o diretório home não são do dono e ficam em runtime.unavailable, e a recusa repetida pelo mesmo impedimento não gasta tentativa nem sobe esforço.
ork retry plan <thread>
ork retry run <thread> --dry-runProva local no registro da claim
A policy claim_sem_prova_local (alias claims_failed) vem desligada e só vale se o manifesto a declarar. Com ela, ork claims add roda os comandos da claim uma vez, na worktree da thread e no prazo de verify.timeout_ms. A claim entra de qualquer jeito: comando reprovado grava policy_warn com claims.failed, e estouro de prazo, com verify.timeout. Ela nunca para o registro, nem declarada em block. Como o add fica tão lento quanto o comando, quem decide ligá-la é o dono do projeto. Sem a worktree da thread (apagada), nada roda e o aviso diz isso. Pelo MCP (ork_claim_add), o registro nunca roda o texto da claim, com ou sem a policy: lá a prova é o ork_verify, no sandbox.
O cenário de comportamento fx-pedido-colado prova que um pedido do dono colado em #Auto, com push e merge autorizados, segue sem parar: a dúvida vira decisão informada e um confirmo em texto livre é recusado sem gravar nada.
policies:
claim_sem_prova_local: warn
ork eval --so-cenarios