Referência
Fronteira de confiança e procedência do estado
Veja o que um valor do repositório clonado pode decidir e o que cada máquina precisa confirmar.
O que vem do clone não decide execução
Rodar o Orkastery num repositório de terceiros não executa código só por isso. Um valor vindo do clone não vira opção de processo, não vira executável e não vira caminho fora da raiz; os únicos comandos executados por desenho são os declarados.
A fronteira de confiança é a auditoria de cada chamada de processo e de cada caminho que o núcleo monta com dado do clone, com a classe de cada um e sem roteiro de exploração. A matriz completa, módulo por módulo, fica na fonte.
Na versão 0.6.10, entram as correções da auditoria e as regras de procedência do estado, estas como patch de segurança, por decisão do dono.
Em que o núcleo confia
A linha de comando é de quem está no teclado: merece confiança, mas é validada quando vai ao git, como --remoto, --para, --de e os ids de thread. O ambiente e as pastas da conta (~/.orkastery, ~/.claude e ~/.codex) também são confiáveis.
Não merecem confiança o manifesto e o setup versionados (orkastery.yaml e orkastery.setup.json), o estado versionado no clone (.orkastery e os bundles .ork-ci/<thread>.json), as branches de estado (ork/roadmap-reservas, a da fábrica e as ork/*) e o que chega de outra máquina da rede (retratos, reservas e o frontmatter do roadmap). Saída de ferramenta (git, runtime) é dado, nunca código.
Cada chamada de processo e cada caminho da matriz recebem uma destas classes. Toda chamada de processo do núcleo usa vetor de argumentos, sem shell; shell só existe nos comandos declarados e na sonda de sandbox do MCP.
- Declarado: comando que o manifesto ou a claim declara para rodar. É o produto (reexecutar o que se alega), e o
SECURITY.mddocumenta. - Inerte: só constantes, ou dado confiável.
- Defendido: dado externo, mas validado, depois de
--end-of-options, com a ref qualificada ou com o sha conferido. - Corrigido: era injeção de opção, executável escolhido pelo clone ou caminho fora da raiz.
- Corrigido em decisão do dono: fecha um pendente mudando comportamento, e o dono escolheu mesclar como patch de segurança.
- Pendente do dono: fechar exige mudar comportamento documentado ou aceito hoje, e a decisão é do dono.
Comandos declarados
São os únicos que o núcleo executa por desenho, e o SECURITY.md lista todos. A documentação não promete aviso em tempo de execução: trate o orkastery.yaml e o estado de um repositório de terceiros como um Makefile.
ork doctor, ork board, ork thread list, ork init, ork thread new e ork retry plan não executam comando declarado.
verify.build,verify.test,verify.typecheckeverify.preparo, na worktree, porork verify,ork fix open,ork fix reverify,ork retry run(na ação corrigir-dirigido), a baseline doork phase rune o gate doork ship.ci.commande o bundle.ork-ci/<thread>.json, noork ci rundo runner do CI.- As claims (o
claims.jsonle o--verificar) e odoneWhendothread.json, nos mesmos comandos do verify; oork claims addsó as roda com a policy do manifesto. - As correções do GO-FIX e as claims dos achados de auditoria (
board.jsonl), noork fix reverifye na conferência da rodada de auditoria. - O binário do runtime (claude e codex), pelos adaptadores, no
ork phase rune noork retry run.
ork verify <thread>
ork fix reverify <thread>
ork audit verify <rodada>
ork ci run --branch <branch>As cinco regras de procedência
Na versão 0.6.10, cinco regras (P1 a P5) fecham os pendentes que a auditoria deixou com o dono. A ideia é a mesma em todas: o que vem com o repositório não decide executável, caminho fora da raiz nem publicação desta máquina; quando o uso é legítimo, a máquina confirma fora do git, e a recusa é tipada e diz o comando.
- Postura do sandbox (P1): o
runtime.sandboxque dá ao agente acesso total (danger-full-access) só despacha pelo Codex depois deork setup sandbox confirmar <postura>, gravado em.orkastery/private/postura-local.json(0600, fora do git, só para este checkout). Sem isso,ork phase runeork retry runrecusam comruntime.sandbox-nao-confirmado, e oork doctoracusa. - Estado rastreado (P2): estado versionado do
.orkasterynão escolhe cwd, worktree nem executável (estado.rastreado). O cwd vindo dothread.json, do ledger ou da fila, para o agente ou para o git, só vale na raiz do projeto ou numa worktree que o repositório registrou (estado.worktree-nao-registrada). Vale para despacho, retomada, verify, claims, GO-FIX, prova do GO, handoff, liveness,ork ci prepare,ork worktree auditeork worktree release. - Transporte do pulse e do digest (P2): só valem o
pulse-host.jsone omaster-host.jsonlocais, arquivos comuns fora do índice do git (transporte.rastreado). - Ponteiros do recall e do handoff (P2): o
ork recall, oork handoff recalle oork handoff exportsó leem arquivo que, pelo caminho real, fica na raiz do projeto ou na worktree registrada da thread. O recall recusa componteiro.fora-da-raiz, e o export deixa de apontar para fora. - Pasta das worktrees (P3): o
worktree.dirque leva para fora da raiz pelo caminho real (caminho absoluto, subida de pasta, link no caminho ou.git) só cria worktree depois deork setup worktree confirmar, gravado em.orkastery/private/worktree-local.json(0600, fora do git, só para este checkout e esta pasta). Sem isso, a criação recusa comworktree.dir-fora-da-raiz, e oork doctoracusa. As worktrees que já existem seguem valendo, e o MCP segue recusando worktree fora da raiz. - Eval (P4): o
ork evalsó executa o catálogo (cenários de comportamento, hooks ecore/dist) do pacote que está rodando. Um diretório com as pastas skills, references e eval achado a partir do cwd que não é o do pacote recusa comeval.catalogo-alheio, e a mensagem diz como rodar de propósito o eval daquele checkout. O CI do kit, comnode core/dist/index.js evalna raiz, não muda. - Fábrica compartilhada (P5): o
fabrica.compartilhada:truedo manifesto não liga mais a publicação do retrato desta máquina (threads, nome e host) no remoto do clone, nem a leitura das outras máquinas. Só a adesão da máquina liga:ork fabrica entrar, em~/.orkastery/maquina.json, ouORK_FABRICA_COMPARTILHADA=1. Com o pedido no manifesto e sem a adesão, oork doctore oork fabricaavisam comfabrica.nao-confirmada.
ork setup sandbox confirmar danger-full-access
ork setup worktree confirmar
ork fabrica entrar
ork doctor
git rm -r --cached .orkasteryO que a auditoria corrigiu
Na versão 0.6.10, a auditoria corrige estes casos sem mudar comportamento aceito:
- O
mergeShae a branch de destino de umship_donedo ledger só chegam aogit logda detecção de reversão como sha hexadecimal e nome de branch, depois de--end-of-options; antes, um ledger versionado no clone passava uma opção ao git, emork mastereork ship. ork docs sincronizarnão cai mais na base crua do manifesto quando ela não resolve, e, do sha do ledger e do commit do frontmatter, só sha hexadecimal chega ao git.- O manifesto recusa
worktree.base_branchque não vale como nome de branch no git (começa com hífen ou tem .. no nome). - O manifesto recusa
memory.clirelativo: vale nome procurado noPATH, como orkmind, ou caminho absoluto. A sonda do OrkMind, inclusive a doork doctor, ignora entradas relativas doPATHe shebang com interpretador relativo, e oork brainroda o executável com cwd no$HOME, não na raiz do clone. .orkastery,.orkastery/threadse a pasta de uma thread como link simbólico recusam comestado.link, e o append do ledger, das claims e do board usaO_NOFOLLOW; antes, um link versionado levava a escrita para fora da raiz.- O id de uma rodada de auditoria lido do
run.jsonprecisa ser um nome simples (audit.rodada-invalida). - O
SECURITY.mdpassa a listar todos os comandos declarados, inclusiveverify.preparo,ci.command, os bundles.ork-ci/<thread>.jsone odoneWhen.
Barreira de dado privado e DSN fora do ambiente
Na versão 0.6.10, a barreira de dado privado é um comando do núcleo: ork privado varrer procura caminho de home, e-mail fora da lista permitida, hostname no formato de máquina e os termos da lista local, que fica fora do git. As exceções em orkastery.privado.json exigem padrão e valor exato, sem curinga, com caminho apenas como filtro e motivo obrigatório. O relatório diz arquivo, linha, coluna e padrão, nunca o valor, e mascara o nome do arquivo com achado.
Com a policy dado_privado no manifesto, o ork verify varre o diff da thread e reprova com policy.violation em block, e o ork ci prepare recusa gerar o bundle com achado. No CI do núcleo, a varredura é um passo do job documentacao. A lista local só é lida como arquivo comum do usuário atual, sem link e com permissão 0600; ausente, como no CI, só os padrões genéricos rodam, e a saída diz isso.
A DSN da memória ganha uma fonte fora do ambiente dos agentes: memory.database_url_file aponta para ~/.orkastery/segredos/<nome>, e o manifesto não escolhe arquivo fora dessa pasta. As duas fontes são exclusivas, então o ork nunca cai de uma para a outra. Antes de abrir, o núcleo confere pelo lstat cada pasta entre a casa e a pasta de segredos, abre com O_NOFOLLOW e exige arquivo comum, do usuário que roda o ork, com permissão 0600 ou 0400 exata, até 4 KiB e uma linha só com a DSN.
A resposta do processo filho que repita a DSN ou a senha dela é recusada inteira, com memory.transport.secret, brain.transport.secret ou brain.migration.secret, sem o valor. O limite é honesto e está dito: o agente roda com o mesmo usuário do dono e pode ler um arquivo 0600 dele. O ganho é a senha fora de env, da transcrição e do contexto do modelo; isolamento forte pede outro usuário ou um intermediário.
ork privado varrer
ork privado varrer --base origin/main
ork memory statusO que segue com o dono
A auditoria deixou seis itens como pendentes do dono, porque fechá-los mudava comportamento aceito ou documentado. Os cinco primeiros, P1 a P5, ganharam as regras de procedência desta página, mescladas por decisão do dono. A P6 segue pendente.
Na mesma lista, ficam registrados, com risco baixo:
ork retry run --dry-run, na ação corrigir-dirigido, reexecuta claims e verify: são comandos declarados, mas contra a semântica do--dry-run.- O perfil do runtime gravado no ledger escolhe o
CLAUDE_CONFIG_DIRe oCODEX_HOMEde comandos de consulta. - A P6: o
memory.clido manifesto pode ser qualquer nome doPATHou caminho absoluto, inclusive dentro do clone, e omemory.database_url_envnomeia qualquer variável de ambiente. O valor vai ao executável do Brain em toda consulta, e a fonte de arquivomemory.database_url_filesó aceita a pasta de segredos do ork, para não alargar a classe. - O
ci.external_repositoriesaceita segmento de subida de pasta no caminho de uma leitura pela API do GitHub. - O
ork adapter installainda acha o catálogo a partir do projeto, como oork evalachava, mas só copia o adaptador para dentro do próprio projeto e prefere o executável doPATHquando ele existe.
Para quem contribui com o núcleo
As regras para o código em core/src:
- Valor do clone a caminho do git: valide antes da chamada com
remotoValidoouexigirRemoto,branchValidaoushaValido(core/src/branch-de-estado.ts), e ponha--end-of-optionsantes dele. - A ref de branch vai qualificada, e o merge vai pelo sha conferido, nunca pelo nome.
- O executável nunca sai do manifesto por caminho relativo, e o cwd de um executável escolhido por configuração não é a raiz do clone.
- Caminho com id vindo de arquivo tem um segmento só, conferido por regex, e o diretório de estado não é link.
- Append em estado usa
O_NOFOLLOW; escrita de arquivo inteiro vai por um temporário criado com wx e depois renomeado. - Caminho lido de ponteiro guardado no estado é conferido pelo caminho real com
exigirCaminhoContido(core/src/procedencia.ts). Decisão que o manifesto não pode tomar sozinho vira confirmação local em.orkastery/private, comlerArquivoPrivadoegravarArquivoPrivado(core/src/postura-local.ts). - O teste da correção reprova o código anterior; os de referência são
core/test/fronteira-de-confianca.test.ts,core/test/procedencia-e-postura.test.tsecore/test/fronteira-pendentes.test.ts.