Conceitos
Arquitetura do Orkastery
Entenda quem apresenta, quem executa e quem verifica cada mudança.
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ó> --jsonIncremental 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