Pular para o conteúdo

Conceitos

Arquitetura do Orkastery

Entenda quem apresenta, quem executa e quem verifica cada mudança.

Quem conduz, executa e confereO host apresenta a intenção ao núcleo. O núcleo despacha o runtime e recebe código e evidência para verificar. Gates e ledger permanecem no núcleo. 1.Hostpedido e decisõesPedido → núcleo2.Núcleo orkcontratos e estadoDespacho → runtime3.Runtimecódigo e evidência Quem conduz, executa e confereO host apresenta a intenção ao núcleo. O núcleo despacha o runtime e recebe código e evidência para verificar. Gates e ledger permanecem no núcleo. 1.Hostpedido e decisõesPedido → núcleo2.Núcleo orkcontratos e estadoDespacho → runtime3.Runtimecódigo e evidência
Quem conduz, executa e confere. O host apresenta a intenção ao núcleo. O núcleo despacha o runtime e recebe código e evidência para verificar. Gates e ledger permanecem no núcleo.
Isolamento e autorizaçãoA thread define escopo e permissões. A worktree isola o código. Leases coordenam colisões. O gate da entrega reconfere autorização e evidência antes do merge. 1.ThreadescopoLimita a edição2.Worktreecódigo isoladoCoordena acesso3.Leaserecurso compartilhadoReconfere a entrega4.Gateentrega autorizada Isolamento e autorizaçãoA thread define escopo e permissões. A worktree isola o código. Leases coordenam colisões. O gate da entrega reconfere autorização e evidência antes do merge. 1.ThreadescopoLimita a edição2.Worktreecódigo isoladoCoordena acesso3.Leaserecurso compartilhadoReconfere a entrega4.Gateentrega autorizada
Isolamento e autorização. A thread define escopo e permissões. A worktree isola o código. Leases coordenam colisões. O gate da entrega reconfere autorização e evidência antes do merge.

Três camadas, responsabilidades explícitas

O host recebe o pedido e apresenta as decisões. O núcleo ork aplica contratos, registra o estado e confere a evidência. O runtime escreve o produto. Um relato do runtime não substitui a execução dos verificadores.

O núcleo é um CLI determinístico. Adaptadores conectam hosts e runtimes; a regra de negócio permanece no núcleo para que a mesma decisão não mude de sentido entre canais. Não há LLM dentro do núcleo, nem servidor ou banco obrigatório; as dependências de runtime são poucas e têm versão fixa.

Estado e proveniência

O manifesto orkastery.yaml define o projeto. Cada thread tem estado, ledger, claims e prompts com hash em .orkastery. Consulte esses dados pelos comandos do núcleo. Uma conversa pode explicar um estado, mas não é sua fonte de verdade.

ork thread status <thread>
ork phase list <thread>
ork claims list <thread>

Isolamento e decisões

A worktree separa o código de uma thread. Leases coordenam recursos que podem colidir, como caminhos de edição e a árvore de destino do merge. Paralelismo não elimina a necessidade de serializar a entrega.

O modo define os pontos de HITL previstos. Policies block, falhas de verificação e escalações tipadas continuam valendo. Memória oferece contexto; não concede autorização.

Duas medidas com propósitos distintos

O índice de condução deriva dos eventos do ledger e descreve como o ciclo foi conduzido. A nota humana registra a avaliação do dono sobre o resultado. São origens diferentes: nenhuma deve ser inventada ou tratada como medida da outra.

Uma taxa de entregas exige intervalo, população e registros de origem. Esta página não apresenta uma taxa sem essa medição.

Grafo determinístico: o contrato KG1

KG1 define ork.code-artifact-graph/v1 e ork.graph-benchmark/v1, com validação pura e corpus sintético. A mesma entrada, configuração e versão do extrator produzem as mesmas identidades e conteúdo canônico. Cada relação exige evidência localizável e preserva as restrições de acesso das fontes.

O grafo é uma projeção local descartável. O KG1 entrega o contrato, a validação pura e o corpus; a extração é o KG2, o índice com a consulta pelo ork grafo é o KG3, o índice incremental é o KG4 e o consumo pelas fases é o KG5. Não altera orkmind.company-brain/v1 nem substitui o estado do Ork ou o Company Brain. Nenhum benchmark medido comprova economia nesta etapa.

Extração, índice e consulta: KG2 e KG3

O KG2 extrai de um repositório Git local um grafo no mesmo contrato: TypeScript e JavaScript pelo compilador, Markdown com seções, links, frontmatter e IDs citados, e a proveniência de cada aresta. Aresta só existe com prova; o que não se prova fica fora e é declarado, como diagnóstico ou lacuna do relatório de extração. A mesma entrada dá o mesmo grafo e o mesmo digest em qualquer ordem de leitura.

O KG3 guarda esse grafo num índice local do HEAD limpo, fora do git, e o consulta por vizinhança, chamadores, importadores e caminho. A mesma pergunta dá a mesma saída, toda aresta traz extrator e evidência, e a resposta se declara parcial. Registro fora da concessão local não aparece em resposta, contagem nem candidato.

ork grafo indexar --verificar
ork grafo vizinhos <nó> --json

Incremental e consumo pelas fases: KG4 e KG5

O KG4 constrói o índice de uma revisão a partir do índice ancestral e reextrai só o que a mudança alcança, com os mesmos bytes da extração completa; --verificar compara as duas. O KG5 expõe as consultas no MCP do projeto: as tools ork_grafo_* rodam o ork grafo na worktree da thread, num processo filho com prazo e cancelamento, e a resposta tem teto em bytes. O servidor MCP não carrega o grafo.

O consumo fica atrás da flag grafo.mcp do orkastery.yaml, desligada por padrão; sem ela, o MCP lista as mesmas tools de antes. As tools precisam dos analisadores, o typescript e o micromark, que desde a correção de empacotamento da RM-031 são dependências do pacote, com versão exata: o npm install -g os traz. Instalado dentro de um projeto ou pelo npx, o ork fica sem eles, e a recusa é grafo.parser.indisponivel, com a correção no ork grafo status e no ork doctor. O grafo pede Node 20.19, 22.12 ou mais novo.

O pacote de contexto da thread já existe: ork grafo contexto <thread> e a tool ork_grafo_contexto entregam o JSON ork.thread-graph-context/v2, com as sementes do diff da worktree, do GOAL, do PLAN e das claims, a vizinhança de um salto ordenada por relevância e teto de 32.768 bytes por padrão; com a flag ligada, o pedido da fase ganha uma dica curta. Na versão 0.6.10, o índice ganha arestas cites, de caminhos citados literalmente em Markdown e em strings de testes e scripts para arquivos do índice, e o pacote usa a sobra do teto para vizinhos a dois saltos, marcados com salto: 2. Um índice gravado antes das citações pede ork grafo indexar. Numa fixture sintética, o pacote caiu de 22.973 para 3.119 bytes, e dá 3.137 com o segundo salto; em dois casos reais, a cobertura do pacote subiu de 23% para 69% e de 41% para 65%, com precisão menor e o pacote quase dobrando. Nada disso demonstra economia de tokens.

Também na versão 0.6.10, a proveniência é conferida contra a árvore da thread: as consultas por nó (vizinhos, chamadores, importadores e caminho, no ork grafo com --json e nas tools ork_grafo_*) trazem as fontes, com o sha256 e o blob do Git de cada arquivo citado e a situação dele na árvore (igual, modificada ou ausente), e cada aresta diz se a origem, o alvo ou uma das evidências mudou depois do HEAD. No pacote de contexto, só o grupo de fonte mudada ganha essa marca, e, com a árvore limpa, o pacote sai byte a byte igual ao de antes. A árvore só é lida quando o git status diz que ela mudou, e nenhum índice precisa ser refeito por isso. No mesmo índice, a resposta sem corte cresce de 15% a 29% em bytes, e a cortada pelo teto traz 34 arestas em vez de 41. A federação (KG6), a paridade entre hosts (KG7) e a rodada paga do benchmark ainda não existem.

grafo:
  mcp: true