Concepts
Orkastery architecture
Understand who presents, executes and verifies each change.
Three layers with explicit responsibilities
The host receives the request and presents decisions. The ork core applies contracts, records state and checks evidence. The runtime writes the product. A runtime report does not replace running the checks.
The core is a deterministic CLI. Adapters connect hosts and runtimes; business rules remain in the core so the same decision keeps its meaning across channels. There is no LLM inside the core and no required server or database; runtime dependencies are few and pinned.
State and provenance
The orkastery.yaml manifest defines the project. Each thread has state, a ledger, claims and hashed prompts under .orkastery. Query these through core commands. A conversation may explain state, but is not its source of truth.
ork thread status <thread>
ork phase list <thread>
ork claims list <thread>Isolation and decisions
A worktree separates a thread’s code. Leases coordinate resources that could collide, such as edited paths and the merge destination tree. Parallel work still requires serialized delivery.
The mode sets the scheduled HITL points. Blocking policies, verification failures and typed escalations still apply. Memory provides context; it does not grant authorization.
Two measures with different purposes
The conduction index derives from ledger events and describes how the cycle was conducted. The human score records the owner’s assessment of the result. They have different sources: neither should be invented or used as a measure of the other.
A delivery rate requires a time interval, a defined population and source records. This page does not report a rate without that measurement.
Deterministic graph: the KG1 contract
KG1 defines ork.code-artifact-graph/v1 and ork.graph-benchmark/v1, with pure validation and a synthetic corpus. Identical input, configuration and extractor versions produce identical identities and canonical content. Each relationship requires locatable evidence and preserves source access restrictions.
The graph is a disposable local projection. KG1 provides the contract, pure validation and the corpus; extraction is KG2, the index with ork grafo queries is KG3, the incremental index is KG4 and phase consumption is KG5. It does not change orkmind.company-brain/v1 or replace Ork state or Company Brain. No measured benchmark demonstrates savings at this stage.
Extraction, index and queries: KG2 and KG3
KG2 extracts a graph in the same contract from a local Git repository: TypeScript and JavaScript through the compiler, Markdown with sections, links, frontmatter and cited IDs, and provenance for every edge. An edge exists only with proof; anything unproven stays out and is declared as a diagnostic or as a gap in the extraction report. The same input yields the same graph and digest in any read order.
KG3 stores that graph in a local index for a clean HEAD, outside git, and queries it for neighbors, callers, importers and paths. The same question produces the same output, every edge carries its extractor and evidence, and answers declare themselves partial. Records outside the local grant appear in no answer, count or candidate.
ork grafo indexar --verificar
ork grafo vizinhos <node> --jsonIncremental index and phase consumption: KG4 and KG5
KG4 builds a revision’s index from the ancestor index and re-extracts only what the change reaches, with the same bytes as a full extraction; --verificar compares both. KG5 exposes the queries in the project MCP server: the ork_grafo_* tools run ork grafo in the thread worktree, in a child process with a deadline and cancellation, and the answer has a byte cap. The MCP server does not load the graph.
Consumption sits behind the grafo.mcp flag in orkastery.yaml, off by default; without it, MCP lists the same tools as before. The tools need the analyzers, typescript and micromark, which have been package dependencies with exact versions since the RM-031 packaging fix: npm install -g brings them. Installed inside a project or through npx, ork goes without them, and the refusal is grafo.parser.indisponivel, with the fix in ork grafo status and ork doctor. The graph needs Node 20.19, 22.12 or later.
The context package for a thread now exists: ork grafo contexto <thread> and the ork_grafo_contexto tool return the ork.thread-graph-context/v2 JSON, seeded from the worktree diff, GOAL, PLAN and claims, with a one-hop neighborhood ranked by relevance and a 32,768-byte cap by default; with the flag on, the phase request gets a short hint. In version 0.6.10, the index gains cites edges, from paths cited literally in Markdown and in test and script strings to files in the index, and the package spends what is left of the cap on neighbors two hops away, marked with salto: 2. An index written before the citations needs ork grafo indexar. On a synthetic fixture the package dropped from 22,973 to 3,119 bytes, and it is 3,137 with the second hop; on two real cases, the package’s coverage rose from 23% to 69% and from 41% to 65%, with lower precision and a package almost twice as large. None of this demonstrates token savings.
Also in version 0.6.10, provenance is checked against the thread’s tree: node queries (neighbors, callers, importers and path, in ork grafo with --json and in the ork_grafo_* tools) bring the sources, with the sha256 and Git blob of each cited file and its state in the tree (igual, modificada or ausente: unchanged, modified or missing), and each edge says whether its origin, its target or a piece of its evidence changed after HEAD. In the context package, only a group whose source changed gets that mark, and with a clean tree the package is byte for byte the same as before. The tree is read only when git status says it changed, and no index has to be rebuilt for this. On the same index, an uncut answer grows 15% to 29% in bytes, and the one cut by the cap returns 34 edges instead of 41. Federation (KG6), host parity (KG7) and the paid benchmark run do not exist yet.
grafo:
mcp: true