Pular para o conteúdo

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 ship recusa 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 agile

Seleçã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, no devmaster.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 agile

Falha, 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$"] }     # Go

Dependê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.cjs

Modelo 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-run

Prova 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