Skip to content

Reference

Contracts and capabilities

Interpret snapshots, runtime capabilities and metrics without treating reports as authority.

Maestro overview

ork.maestro-snapshot/v1 is a read projection. Its sections declare source, timestamp, fingerprint, state and coverage. empty means observed emptiness; unavailable means an inaccessible source. Pagination and omissions are part of the contract. The snapshot does not create a cycle, approve a gate or prove SHIP. The snapshot also carries project.root, shown with ~, project.remote, without credentials, and notConsulted, listing what the overview did not read. Zero threads in the overview never means an empty roadmap.

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

Activation proof per host

prova-ativacao.cjs opens a new non-interactive session in the installed host, on a disposable copy of the project, and asks for orkastery maestro. The check judges only what is deterministic: the contracted entry point was exposed and called, and the result meets its contract, with the expected project and what was not consulted. The answer must name the project and must not conclude that the roadmap is empty. The proof hosts are claude-code, openclaw and codex. In Codex, the entry point is mcp__orkastery__ork_maestro, the project MCP server reaches the session through -c, and the exposed tools come from that server’s tools/list; the ephemeral session must not remain in $CODEX_HOME/sessions.

The script also checks that the query did not write to the project state and that the host’s global configuration did not change. The ork.prova-ativacao/v1 receipt is redacted. Exit codes: 0 passed, 1 failed, 2 host missing or outside the proof, 3 pending human action. The proof neither consents to MCP nor restarts a gateway for anyone.

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

Project registry and query header

ork.projetos/v1 is this machine’s registry in ~/.orkastery/projetos.json, with mode 0600 and no secrets: name, abbrev, root, remote without user or password, timestamps and the registration source. A missing, corrupted or foreign-contract file counts as an empty registry. ork.consulta/v1 is the header of ork maestro, ork board, ork board plan, ork fabrica, ork roadmap status and, in version 0.6.10, ork roadmap reservas: the project read, how it was chosen, what was read and what was not.

The projeto.desconhecido, projeto.ambiguo, projeto.sem-manifesto, projeto.escolha, projeto.nenhum and projeto.fora-do-servidor refusals include the candidates and the fix. Consumers read the registry without writing, check the contract and never pick the first copy of an ambiguous name. In version 0.6.10, ork privado is one of the commands that do not read a project: it scans the repository of the current directory and does not resolve a global target.

Without the remote, naoLido says nothing was read from ork/fabrica-estado; in version 0.6.10, for reservations, it says the same about ork/roadmap-reservas, and their JSON carries the leitura field (lido-agora, copia-local, sem-copia or sem-remoto): only lido-agora or copia-local without a reservation turn into the message that no item is reserved. For reservations, projeto.remoto is the remote read (--remoto, or origin); in ork board and ork fabrica, it is the manifest’s fabrica.remoto.

Also in version 0.6.10, the other commands that read a project end with the same first line, Projeto consultado, on stderr, when the reader cannot know which project was read: in a host (ORK_PROJETO_EXPLICITO=1) or with the project outside the current directory. The line comes once per command, also when it fails, before the error message, and stdout, JSON included, does not change. In that line and in the header, the remote is the display one: without user and password, without query and fragment, with ~ in place of the account folder in a local path, and omitted when it still looks like a secret.

In version 0.6.10, a dispatched session (ork phase run, ork retry run and ork audit run) gets an empty ORK_PROJETO and ORK_PROJETO_EXPLICITO=0 in its environment: its project is that of its own cwd, the thread’s worktree, and the host mode of whoever dispatched it does not follow it. In Codex, both values override the inherited environment; in claude-bg, they go through --settings, which wins over the daemon’s environment. The ork fabrica publicar child inherits the same.

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

Orkastery Network contracts

ork.rede/v1 is this machine’s membership, in ~/.orkastery/rede.json; membro false is the explicit exit and overrides inherited membership. ork.rede-maquina/v1 is the snapshot published at maquinas/<maquina>.json in the private home: the generic machine alias, installation id, the same alias in the legacy hostname field, forges with the login, runtimes and hosts with version, projects with a credential-free remote, ork version and heartbeat. ork.rede-status/v1 is the reading from ork network status --json: home, this machine, sources, members, gaps and what was not consulted.

Without --maquina, ORK_MAQUINA or an alias already recorded, joining refuses with rede.maquina-generica. The real hostname is never a fallback and never goes into the JSON, the file name or the commit.

A new optional field does not change the version. The reader ignores a malformed snapshot, one with another machine’s name or one with invisible characters, and turns it into a gap; the writer publishes only what the reader accepts. The home speaks HTTPS only, and ork never reads a token.

ork network status --json

Asynchronous verify over MCP

ork.verify-mcp/v1 is the contract of ork_verify and ork_verify_status. The response carries rodadaId, threadId, the dispatch binding, state, lane and the timestamps, and reutilizada is true when a live round already existed for the thread. The model does not choose root, command, PID, timeout or lease: the server pins project, thread, host and dispatch.

The states are na-fila, rodando, concluido and falhou. In concluido, the verdict is the same result and the same text as ork verify in the CLI, for the same HEAD, claims, manifest and CHECK mode. In falhou, the reason is typed (verify.processo-morto, verify.worker-failed or verify.lease-perdida) and the result is never green; the fila-pesada.ocupada and conducao.em-andamento refusals come whole in falha.recusa. The status query is read-only: it does not start, repeat or change the verdict.

Capability and permission are distinct

The playbook describes transport, native tools and phase limits. PLAN does not edit the product; GO receives the worktree; CHECK requires independent review. A claim output schema contains candidates: a model response neither registers nor verifies the assertion. Installed configuration does not prove live validation.

Grok Build is not in the playbook’s capability matrix yet: a runtime only enters it with the live validation trial, which is RM-067’s F5. In version 0.6.10, dispatch, setup and fallback, the sandbox with a workspace floor, project instructions, per-profile accounts, the core’s MCP server outside the sandbox and the session inventory already apply to it; the exhausted-quota format and the login check remain gaps.

Metrics with coverage and provenance

ork.ledger-stats/v1 aggregates recorded facts over a half-open UTC interval. Tokens and duration have explicit coverage; missing values remain missing. custoReferencia is a scenario estimate, not an invoice. Throughput depends on ship_done; do not count a local commit as remote delivery.

hitlDeConducao measures the time stalled by questions that ork itself opened to the owner: requests, answered, unanswered and open, stalled time in the period, the median and longest wait among answered ones, and the 5-minute target, null when there is no sample. An informed decision stops nothing and is excluded. ork pulse and ork roadmap status carry the same calculation in the optional hitlDeConducao field, with abertas, seteDias and acimaDaMeta; the field appears only with an open question or with a question and answer during the week, and the network view does not add it up.

ork ledger stats --desde 7d --json

Forge and durable authorization

In version 0.6.10, the core recognizes the project’s forge, GitHub or GitLab, through its logged-in CLI, gh or glab, and never reads or passes a token. The optional forja: block in orkastery.yaml declares tipo, host, porta, caminho_base, ssh_host, ssh_porta and ca; without it, everything comes from the origin remote and probing. The forge is resolved by the manifest, by the known host or by probing only the CLI with a login on the host, never by the host name; with no answer, forja.desconhecida, and with two, forja.ambigua.

ci.produtor states who approves the required check, github-actions by default, and on GitLab only the project pipeline job counts as the gitlab-ci producer. ork ci status moves to ork.ci-status/v2, with provider, fonte and produtor, and v1 is still read. ork ship publicar refuses an Enterprise remote without forja: and without a CLI login before any write (forja.desconhecida), and registrar-pr --repo has no fallback host: without a reading, entrega.sem-leitura.

Durable authorization is the ork.autorizacao-duravel/v1 contract, in .orkastery/monitor/autorizacao.json, outside git. It applies only on this machine and in this project, with an ISO deadline carrying an explicit offset, for up to 31 days, and a closed list of actions: limpar, registrar, master, merge and despachar. An action outside the contract invalidates the whole file, and without authorization the heartbeat does not act.

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

CI receipt and collective preflight

ci.politica_recibo accepts observar, avisar or exigir. Without the key, the result and exit code of ork ci run --branch stay as before; with it, every result carries the level and the receipt state. The bundle stays on ork.ci-bundle/v1, and the optional recibo field becomes ork.ci-projecao-replay/v1; the previous form is only read for compatibility and does not satisfy the proof.

The runner emits ork.ci-recibo-runner/v1 inside ork.ci-run/v1, with head, thread, claimsSha256, rodadaSha256, check, resultado and sha256, and reserves the assinatura field for F7. presente requires the same HEAD in the receipt, in the result’s commit and in the checkout, at least one claim, commands and preparation identical to the verify in the target branch’s manifest and a complete green round. An unreadable target ref or manifest fails closed, and external branches and forks get no exception.

Trust boundary: the anchor in the target manifest proves that the accepted recipe did not empty the claims or swap the commands or the preparation. It does not prove that the claims are complete or authentic, who wrote the bundle or the code’s integrity; protection against forgery belongs to F7’s signed receipt.

With an active enrollment on the company network, the delivery surfaces read a collective snapshot and run the same conflict and suggested-order analysis, advisory at all three levels. In a PR or MR, ork ci run only refreshes the network cache with ORK_REDE_EMPRESA_READ_TOKEN and outside forks; the secret travels through the Git environment and never enters argv, output, the bundle or a publication.

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