Orchestrata Ultimate / Overview

Orchestrata, explained

This page explains orchestrata as one system: what it is for, the parts it is made of, how a request travels through it, where its data lives, where it runs, the tools that surround it, and the refactor it is in the middle of. Read it top to bottom once; after that, the project hub and the table of contents take you to the detail.

How this page was built (2026-10-23). Code facts come from the deployed AST toolkit (/opt/orchestrata-tools) run against the worktree wt-MAP-PRECOMMIT at 8a2cb42ad; no .py file was read by hand. Decisions come from docs/adr/ in the worktree orchestrata-wt-unshipped-scope at 478d9a0ef (and ADR-0103 from branch architecture/domain-model). Runtime facts come from read-only commands run on 2026-10-23 (incus list, systemctl --user, /opt/*/VERSION) and from the measured wiki pages it links. Where a fact was not measured, the text says so.

1. What orchestrata is, and who it is for

Orchestrata is a governance and agentic workflow engine for the three things a software organization produces: code, architecture and communications (starting context). A person states an intent in plain language. The system classifies it, authorizes it against written policy, and routes it through a team of specialist agents called volks, each of which plays a real occupation: intake, business analysis, product management, UX, architecture, code direction, implementation, quality assurance, compliance and documentation. Every stage is a real LLM-backed agent doing real work, and every transition is checked by a Prolog policy engine before it happens.

Three choices make it different from a generic agent framework:

• Governance is a logic program, not a code path. Policy lives in Prolog rule files (constitutional.pl, governance.pl, intent_policy.pl and 26 more). The runtime asks may_execute/2 before acting, and a denial carries a reason. The same rule engine also drives the static gates that judge the codebase itself.
• Specs are authoritative. Every feature starts as a numbered spec under specs/, its requirements get ids, and code declares which ids it implements with @traces. The traceability matrix (RTM) is built from those claims and graded by evidence (section 9).
• Everything runs on real infrastructure. No mocks, fakes or skipped tests; a test runs against a real Redis, a real graph cluster and a real kernel, in an isolated test fleet built for that purpose (section 6).

Who it is for. Orchestrata is built and owned by Mohamed, its sole author. The human states intents, rules on decisions and reviews outcomes; the volks do the work, and the volks' work is real writing in the workspace: specs, code, tests and docs, with session.close committing and tagging (ADR-0124 context). The project's own framing is that it gives an engineer "a tireless, verifiable, multi-agent team" rather than replacing the engineer.

Size. The generated code reference (revision 8a2cb42ad) counts 902 modules and 242,957 lines in orchestrata_ultimate, 182 modules in scripts/, and 1,790 modules in the eight component packages under packages/. The source repository is gitlab.com/MSamy/orchestrata-ultimate-architecture.

2. The core concepts

A newcomer meets about a dozen ideas in the first hour. Each has a glossary entry; here is how they fit together.

Intent. A natural-language request from a person ("build me a task API"). The gateway parses it into an action, a target and a work type; if it cannot classify the text into any actionable work type it asks the person to clarify instead of starting work (gateway/handlers/orchestrator.py, OrchestratorHandler.handle_intent).

Volk. One agent role. At 8a2cb42ad, PipelineRunner._register_volks (kernel/pipeline.py) registers eleven volks with the Postman under these aliases: U:Cx concierge, U:BA analyst, U:PM product manager, U:Ux UX, U:Ar architect, U:Cd code director, J:Junior junior developer, U:SD senior developer, U:Qa QA, U:Cp compliance and U:Do documentor. No volk receives work straight from a person: every intent is addressed to the concierge first. The volks page has each role's prompt suite and handoff contract.

Kernel. The agent runtime: one process started as python -m orchestrata_ultimate.agents.runtime_main, serving CXP on CXP_GRPC_PORT (50053). It boots a PipelineRunner with the volks on a real Postman and runs every intent it receives. The project treats the kernel as required infrastructure: a test-suite run that does not start and verify the kernel is invalid, because kernel-dependent paths otherwise no-op or fall back and the suite goes green without testing the core (docs/kernel-is-required.md; AGENTS.md Hard Rule 7).

Gateway. The single runtime ingress: a WebSocket JSON-RPC 2.0 server (WebSocketGateway, gateway/server.py, SPEC-014) on GATEWAY_PORT 8765 with an HTTP surface on 8766 for health, readiness and metrics. It authenticates each connection, dispatches about 80 RPC methods (gateway.*, orchestrator.*, tui.*, session.*, governance.*, knowledge.*, volk.* and more, counted in ADR-0099), fans events out over pub/sub, and writes an audit trail. Clients never read Redis directly.

CXP and cxpt. CXP, the Cross-agent eXchange Protocol (SPEC-004), is the packet format every hop speaks: a flat packet with eleven core fields (below). cxpt is its transport: the native direct transport that replaced grpc.aio on 2026-08-07, because gRPC's native threads outlived stop() and hung free-threaded interpreter exit (gRPC retirement). Function and log names still say "gRPC" in places; the profiles set CXP_TRANSPORT=cxpt.

Postman. The message router (postman/, alias U:PS): queues, topics, subscriptions, receipts and replay. Volks register their process callables with it, and the pipeline routes packets through postman.route_sync.

Governance. The policy layer (governance/ plus the rule files in src/orchestrata_ultimate/prolog/). SWI-Prolog runs embedded in the kernel through a patched free-threaded janus-swi; rules are consulted from .pl files and only ground facts are asserted (free-threaded Prolog).

Session. A unit of tracked work: the session package, the session CLI that keeps a per-project context.json, the gateway's session.* methods, and Session nodes in the knowledge graph.

The two graphs. orchkg is the operational knowledge graph: code structure, specs and requirements, traces, sessions, audit, conversations. memgraph is the semantic / RAG graph: embedded chunks of code, docs and specs. They are two databases on one Memgraph-fork cluster called orchgraph, and they must never be confused (section 5).

Spec, requirement, @traces, RTM. A spec defines requirement ids; code and tests cite them with @traces(spec=..., story=..., reqs=[...]); the RTM joins the two and grades the evidence (section 9).

ADR, ruling, brief. One-way-door decisions are ADRs in docs/adr/ (105 files at 478d9a0ef); standing user rulings are RUL-001 to RUL-041 in the wiki's rulings canon; a brief is the written task a worker model builds from (section 8).

Components. The ten packages the monolith is being split into under packages/ (contracts, governance, knowledge_graph, kernel, session, volks, gateway, tools, integration, plugin). The split has not cut over yet (section 10).

The packet every hop carries

The CXP packet is the one data structure that crosses every boundary in the request path. Its class docstring calls it a "flat 11-field structure" (core/packet/packet.py, CXPPacket, SPEC-004 US-001); the kernel's MessageDispatcher.dispatch(packet, recipient) (kernel/dispatcher.py) is the seam that delivers it to a volk definition.

The constructor also takes from_instance, to_instance, packet_type, ttl_seconds (default 3600), expires_at, correlation_id, reply_to and tags; metadata.reply_to is how a gateway stamps its reply-consumer id so the kernel can address the answer back to it.

3. The architecture: layers and packages

Six layers, one rule

The code is organized as a modular monolith with six layers and a single rule: imports go down only. A module may import from its own layer or a lower one, never a higher one, and same-layer concrete imports between domain services go through Layer-0 protocols injected by the DI container. The table below is from architecture-standards.md, which mirrors LAYER_ASSIGNMENTS in scripts/architecture_checker.py:

The other top-level packages (semantic_graph, factory, gates, refactor, domaingen, openspec, promotion, harness, tools, integrations, context, planning) do not appear in that table; their layer was not measured for this page.

The packages, by what they are for

The tree under src/orchestrata_ultimate/ has 30 packages (docs/CODEBASE_MAP.md), plus two sibling roots, src/orchestrata_ast (the AST analyzer the graph sync uses) and src/orchestrata_tools. Grouped by purpose (adapted from the starting context):

Every package has a generated page under the code reference and most have a curated narrative under modules/; the hub has the one-line-per-package table that links both.

The runtime components

Five long-running pieces, and the stores under them. The diagram is the component view; section 4 walks the same path as a sequence.

The volks' retrieval from the semantic graph is only partly wired: chunk text is used, vector search is not, and retrieval is not scoped by project or module (RAG context-injection investigation).

If the kernel is unreachable at gateway start, the gateway retries a bounded number of times and then falls back to an in-process PipelineKernelClient (WebSocketGateway._init_kernel). It records the outcome as a mode, grpc, in-process or unavailable, which gateway.info reports, so "connected to the real kernel" and "quietly running the fallback" can be told apart. In the fallback, chat (cxp.send) reports an explicit assistant-unavailable notice instead of a fabricated reply.

Below the monolith, the same code is being re-cut into ten component packages with a drawn dependency DAG (component DAG). That work, and why it has not cut over, is section 10.

4. The request lifecycle

What happens when a person types an intent. The path below is the orchestrator.intent method, traced through the code at 8a2cb42ad with the AST toolkit.

Step by step, with the code that does it:

1. Connect. WebSocketGateway._handle_connection (REQ-014-168) gives the connection a UUID and a correlation id, then waits for authentication before it registers the connection or reads anything else.
2. Authenticate. gateway/auth_handler.py::authenticate (REQ-014-089) reads the first frame within a timeout. It accepts either a JSON-RPC auth.authenticate call or an internal AUTH frame, and validates it in the mode GATEWAY_AUTH_MODE selects: jwt (the default), static or hmac (SPEC-014 FR-005..007). JWTs are HS256, signed with JWT_SECRET, and expire after TOKEN_EXPIRY_SECONDS (default 3600) (gateway/config.py, GatewayConfig). An insecure secret fails closed with InsecureJWTSecretError (SPEC-099). The CLI mints short-lived JWTs itself (kernel/cli_client.py); orchestrata-mcp authenticates with GATEWAY_TOKEN from the deployed environment (ADR-0099).
3. Route the frame. Every inbound frame passes _handle_message, which refreshes the connection's heartbeat first (REQ-014-109), then sends JSON-RPC frames to _handle_jsonrpc and anything else to the legacy message processor. Malformed JSON gets a JSON-RPC parse error.
4. Dispatch. RPCHandler.dispatch (REQ-014-178) looks the method up in its method table (unknown methods get -32601), writes an rpc.<method> audit event, and calls the handler. Since ADR-0099 the table is declarative (gateway/method_table.py, MethodSpec), and every method is approval-gated for MCP unless it is marked read-only.
5. Parse and gate at the edge. OrchestratorHandler.handle_intent parses the text. If the shared evaluator finds no actionable work type it returns needs_disambiguation and starts nothing.
6. Send to the kernel. It subscribes the caller to pipeline.<thread_id> before dispatch, so the first stage events are not lost, then sends a CXPPacket from HUMAN to U:Cx with subject intent, stamped with this gateway's reply-consumer id. The kernel client was built by create_cxp_client at gateway start (_connect_grpc_kernel_once), verified with a bounded health check, not just a connect.
7. Govern at the kernel. agents/kernel_handler.py, _KernelPacketHandler.__call__, runs _govern on every new intent: IntentBroker.validate_only must return allowed. A denial becomes an intent_denied packet with the reason. A gate error (as opposed to a denial) is logged and the intent proceeds; the docstring's reason is that "governance must not reduce availability on its own fault".
8. Acknowledge, then work. For the chat subjects intent and response the kernel acknowledges at once and runs the volk round in the background (the ack-only design of the dispatch-reply hardening). The gateway returns the JSON-RPC result to the client: intent_id, thread_id, dispatched, pipeline_topic, plus a task record.
9. Run the pipeline. PipelineRunner.submit_intent begins a session if one is attached, asks Prolog may_execute(HUMAN, submit_intent) (a block returns no thread), emits the intent event, binds a memory engine to the thread, records the intent's provenance in the operational KG (kernel/pipeline_kg.py, sync_intent_to_kg, which MERGEs an Intent and the PipelineRun it triggered, anchored to a Thread and the Project hub), and routes the packet through the Postman to the concierge. The concierge either answers the person (for example with a clarification question) or the reply is routed on to the next volk.
10. Reply. The background round publishes exactly one terminal packet: the reply, intent_no_reply if the round produced nothing for the person, or intent_failed on an exception or shutdown. The gateway's reply consumer (_consume_kernel_replies) pushes it to the subscribed client.

Other entry points. The TUI uses tui.intent, which runs the full agent pipeline through the TUI handler (gateway/handlers/ultimatetui.py, SPEC-050) rather than the path above. orchestrata-mcp exposes the same methods as MCP tools (for example orchestrator_intent and tui_intent) and forwards each call over the WebSocket, so it passes the same auth, scope guard and audit as the TUI (ADR-0099). On 2026-10-22 the MCP path answered gateway_ping with "GATEWAY_TOKEN is not set" (runtime services), and on 2026-10-23 the prod host's gateway and kernel units were inactive and disabled (systemctl --user is-active, is-enabled); the test fleet's pair was running (section 6).

A third governance seam, off by default. MessageDispatcher in kernel/dispatcher.py takes policy_audit_mode=False: when switched on it evaluates routing and plan fidelity against policy and records the verdict without acting on it (shadow mode). It is not enforcement.

5. Data and knowledge

Four kinds of state, each with its own home.

Redis: hot state and the message bus

Each fleet has its own Redis: redis-queue at 10.53.1.10:6379 in prod, 10.53.2.11 in test and 10.53.3.21 in dev (env/*.env). It carries the Postman's queues, the event streams the gateway pumps to clients (pipeline, kernel and config events; the _pump_*_once functions in gateway/server.py), the ring buffers the gateway replays from, the hot layer of the MemoryEngine, and the SPEC-021 conversation queue orchestrata:conversation:queue, which a Claude hook fills with one message per turn and orchestrata-conversation-consumer drains into orchkg. Turns are not lost while the consumer is off; they wait in the list (runtime services §6). Test Redis keys are namespaced by test id, and a gate enforces it.

orchgraph: the cluster and its two databases

orchgraph is a Memgraph fork run as a Raft HA cluster in the prod Incus project default: three coordinators, orchgraph-coord-1..3 at 10.53.1.160/.109/.198, and two data instances, orchgraph-data-1..2 at 10.53.1.128/.123 (measured with incus list, 2026-10-23). Clients route through neo4j://10.53.1.160:7691; there is no Bolt auth (ratified in the KG migration). Since the 2026-07-26 cut-over from Neo4j the cluster holds two isolated databases:

• orchkg, the operational knowledge graph. Code structure (Module, Class, Function, Method), the spec tier (Spec, Requirement, RequirementItem and TRACES_TO), sessions, CXP packets, gateway audit, conversations and the component DAG. On 2026-10-20 it held 71 Spec, 639 Requirement and 5,786 RequirementItem nodes and 15,366 TRACES_TO edges from this project's code (component DAG). Every node must have a path to the root Project node (the root-connectivity invariant). ADR-0126 (Proposed) records that the KG had lost modules (4,195 present against about 5,220 in the snapshot) because every checkout synced into one project id, and proposes one project per synced branch (orchestrata-ultimate@components, for example).
• memgraph, the semantic / RAG graph. Embedded chunks of code, docs and specs with a vector index, written by the semantic ingest and the wiki indexer, read for context injection (semantic graph).

Two operational facts matter on day one. Reads through the routing URI were measured to diverge after a write, so verification after a prod write uses direct per-instance Bolt reads (main and replica must agree) (component DAG). And orchgraph-backup snapshots every database daily at 03:00 and keeps 14 runs; it is the only backup of orchkg, and between 2026-07-26 and 2026-10-05 it produced no snapshot (runtime services §9). The test and dev fleets each run a single memgraph node (10.53.2.10, 10.53.3.20) holding both databases, and test adds a disposable HA pair (memgraph-ha-main/replica, ADR-0058).

Prolog: the governance rules

The rules live in src/orchestrata_ultimate/prolog/: 29 .pl files at 8a2cb42ad, among them constitutional.pl, governance.pl, intent_policy.pl, pam_rules.pl, policy_layers.pl, routing.pl, explain.pl (proof trees and why-not answers), gate_rules.pl and rtm_constraints.pl. SWI-Prolog runs only embedded: in the kernel, in test and tool processes, through the vendored free-threaded janus-swi; the kernel maps libswipl.so.9.3.8 (ADR-0110). Prolog is a stateless reasoning view and the graph is the sole fact store (ADR-0005): callers assert ground facts and consult rules, and nothing is learned by the engine itself (the Prolog layer does not learn).

ADR-0110 (Accepted 2026-10-19) retired the idle Prolog containers from every fleet, since nothing connected to them. Measured 2026-10-23: the three prod prolog-node-* containers are gone, but prolog at 10.53.2.12 (test) and 10.53.3.22 (dev) are still running, so that ADR is not yet executed for test and dev.

AST snapshots: the code as data

The AST toolkit serializes the source tree into a JSON snapshot (default warm cache plans/ast-ultimate.json) over the roots declared in env/ast-roots.env, which lists 23 roots including the eight packages/*/src trees (ADR-0126). The snapshot feeds three things: the toolkit's own symbols, refs and source queries (the project's rule is to query code, never read .py files by hand); the Prolog gate layer (scripts/gate.py turns the snapshot into facts and evaluates codebase policy as inference); and the orchkg code-intelligence subgraph, kept current on every file save by orchestrata-ast-live-sync (SLO under 5 s, measured 1.31–1.68 s when built). A resident AST daemon per worktree publishes the snapshot from its warm cache (ADR-0097); on 2026-10-23 five orchestrata-ast-daemon@ units were running, one per active worktree.

6. The environments

Three physically isolated fleets, each its own Incus project on its own bridge, separated by Incus network ACLs. Terraform (OpenTofu) owns every fleet and every container address is pinned (ADR-0077, ADR-0080). The hourly drift check that ADR-0077 added has had its timer stopped and disabled since 2026-10-22, when its last run reported drift (runtime services §10).

Where the application itself runs differs per fleet:

• Prod application services are systemd user units on the host, running from the pinned checkout /opt/orchestrata (ADR-0062, RUL-027). On 2026-10-23 /opt/orchestrata/VERSION read commit 4ac0db570. The ten units and why each exists are on the runtime services page; ADR-0123 (Proposed) makes that page the register of host services and proposes that kernel and gateway become on-demand units. On 2026-10-23 the kernel and gateway units were inactive and disabled; the conversation consumer and the backup, retention and history-mining timers were active.
• Test runs the kernel and gateway inside the app container at 10.53.2.13 (orchestrata-kernel.service and orchestrata-gateway.service, both active on 2026-10-23), so the suite talks to test services and never to the prod host's (isolated test fleet). The commit installed in that container was not measured for this page.
• Dev holds infrastructure only, for developer scratch.

How the runtime profile is chosen

Endpoints live in committed, secret-free profiles env/dev.env, env/test.env and env/prod.env. ORCHESTRATA_ENV_PROFILE selects one (default test), and it is layered over a gitignored .env that holds secrets only (AGENTS.md). Prod's secrets live in ~/.config/orchestrata/.env (ADR-0066), and the prod units load .env plus env/prod.env. The test suite does not choose: tests/conftest.py hard-pins env/test.env and refuses to run if any resolved endpoint is on the prod subnet (override only with ORCHESTRATA_ALLOW_PROD_INFRA=1). Required endpoint keys raise when unset; there is no literal fallback, not even localhost (RUL-003).

What is changing. ADR-0124 (Proposed; items 1, 2 and 10 ruled) moves orchestrata's services off the host into a test container and a prod container built from one OpenMandriva image, over always-on memgraph and Redis, with the workspace mounted read-write so the volks can do their work. Its item 10 is "cutover first": the components cut-over (section 10) lands before either container is built. ADR-0111 forbids test runs from creating containers.

7. The tooling around it

Orchestrata is developed with a ring of separately deployed tools. Each lives under /opt, at a pinned release, and is deployed by its own launcher rather than run from a checkout.

orchestrata-tools (/opt/orchestrata-tools). The developer daemons and binaries, deployed code with the served checkout as a runtime parameter (ADR-0067). Its bin/ holds ast, ast-daemon, ast_live_sync, codemod-daemon, observe_pytest, pytest-live, ship and swarm_supervisor; its VERSION read commit 7309a3488, deployed 2026-10-22T19:55:40-04:00. This is where the AST toolkit runs from. The name also belongs to two other things, so keep them apart: the component package orchestrata-tools (packages/tools, import name orchestrata_tools, ADR-0107) and the source root src/orchestrata_tools.

codetools (/opt/codetools). A separate project (codetools, repo ~/workspace/orchestrata.codetools) that provides code tooling as a CLI, an MCP server (ast_query, ast_snapshot, graph_blast, gate_run, the deploy_* verbs and more) and a Claude plugin. codetools ast map regenerates docs/CODEBASE_MAP.md. Host-side orchestrata scripts are moving into it (ADR-0117 for the rename engine, ADR-0118 for tier-1 scripts).

Hermes (/opt/hermes). The Nous Research Hermes agent, deployed at a pinned commit and used as a non-Claude worker through the hermes MCP server (hermes_run, hermes_runs, hermes_status). It runs DeepSeek or OpenRouter models and reports answered_by, fell_back and cost_usd per run; it keeps a persistent curated memory across runs (ADR-0121).

pi-worker (/opt/pi-worker). pi-task runs a Pi worker on one task in a fresh Incus container and returns the result only if a judge in a second fresh container finds the brief's checks hold; an accepted result arrives as a branch pi/<task> and is never merged automatically (pi-harness).

The Claude Code plugin. The orchestrata plugin, version 1.5.0 (~/.claude/plugins/cache/orchestrata/orchestrata/1.5.0), is installed by deploy/install-claude-config.sh as part of a deploy. It carries 65 of the 119 hook commands registered on the host, 10 skills (agent-messaging, canvas, decision, kimi-webbridge, notify, observe-work, orchestrata-provision, session, shell-guards, test-isolation), 7 agent definitions (auditor, builder, lint-fixer, refactorer, reviewer, test-writer, wirer) and 14 commands. Hooks are registered at the user level only and scope themselves to the repo in the current directory (ADR-0070, RUL-035). The Claude configuration section documents every hook, skill and command. The orchestrata MCP server itself is /opt/orchestrata/.venv/bin/orchestrata-mcp.

8. How work flows

Since 2026-10-22 the division of labour is a ruling (ADR-0125, RUL-041): the host Claude session writes no orchestrata code. It measures, writes briefs, runs checks and improves the workflow; worker models write the code: Sonnet subagents, and Qwen or DeepSeek through Hermes and pi-task. Each dispatch is measured, and a workflow change counts as an improvement only if the measurements improve.

• Briefs. A brief lives in plans/briefs/ and must carry the literal labels GOAL:, FILES:, CONSTRAINTS:, DONE WHEN: and VERIFY:, plus a DESIGN_WAIVER: line for builder-type agents (plans/briefs/TEMPLATE-sonnet-agent.md). Brief defects are logged in plans/briefs/IMPROVEMENT-LOG.md. See briefs and the dispatch ledger.
• The loop. Measure before theorizing; write a contract; refute the design; build red-first; verify by execution, never by reading a report; run the battery and fix everything; document. The rules behind it are not style: most exist because something broke silently (starting context). See workflow and workflow improvements.
• Gates. A gate is a mechanical check with a command and no discretion: the battery in scripts/gates.py, the suite preflight, the session hooks and the Prolog gate layer scripts/gate.py, whose verdict can be invalid when its fact base is stale (gates). Defects found and fixed are logged in bug fixes and the bug-fix log.
• Deployment. deploy/ship.sh answers "is this finished?" (gate, push, deploy, verify, promote); deploy/deploy.sh answers "is the running system this commit?". The prod gate is one correctness run of the promoted commit (ADR-0087). See deployment, ship and deploy, deployment sequence, deployment inventory and runtime services.
• Tests. Real infrastructure, no doubles, no pytest-xdist, the kernel required, and runs observed live rather than read from an exit code. The batched runner is scripts/run_tests.py. See tests, the test reference, test reports, the green ledger and durations.
• Definition of Done. Every spec packet ships with @traces, a regenerated RTM, documentation, a wiki update and at least 90% coverage (ADR-0069, RUL-034).

9. Specs, requirements and the RTM

Specs. specs/ has 79 tracked entries (specs index): 71 numbered spec directories from 000-orchestrata-cli to 114-governance-rule-learning (counted with ls on 2026-10-23), plus SPEC_INVENTORY.md, SPEC_STANDARD.md, SPEC_REVIEW_CHECKLIST.md, the codegen/ and spec-review/ folders and three HTML prototypes. A spec directory holds spec.md, a checklists/requirements.md that defines the numbered requirement ids, and often compliance audits and addenda. SPEC_STANDARD.md fixes the template: metadata, overview, at least three user scenarios and so on. Specs are authoritative: design and contract questions are settled from the spec first (RUL-013). Each spec has its own page at /projects/orchestrata-ultimate/specs/<spec-dir>.

Requirement ids. docs/req-id-grammar.md (ratified 2026-08-02) is the grammar: spec-scoped forms such as REQ-001-001 and the canonical story form REQ-022-US-001-001, subsystem tags such as REQ-GATE-001, and cluster forms. scripts/check_req_format.py enforces it as the pre-commit hook req-id-format.

@traces. Code claims a requirement with a decorator from core/base/traces.py. The gateway's connection handler, for instance, carries @traces(spec="014", story="US-011", reqs=["REQ-014-168"]). The scanner harvests these claims, the RTM files under rtm/ and docs/ are generated from them, and scripts/sync_traces_to_graph.py writes them into orchkg as TRACES_TO edges to RequirementItem nodes.

The RTM, graded. A decorator is a claim, not proof. The legacy matrix in docs/rtm.md reported "Coverage 100.0%" while listing 3,087 orphans, and the decorator-claim model was measured at 55% ± 5% accurate on 2026-07-09 (docstring of scripts/generate_rtm_evidence.py). The evidence-graded RTM replaces it: each requirement is graded by the strongest evidence that exists, TESTED (a citing test ran green), FAILING (a citing test ran red), CITED, DECLARED (only @traces claims it) or UNLINKED. The specs index counts 7,347 requirement ids, 3,150 of them (42.9%) cited by at least one src/ decorator and 269 (3.7%) by a test decorator. The RTM page explains generation and totals.

10. The components cut-over

What is being done. The monolith src/orchestrata_ultimate is being re-cut into component packages under packages/, each with its own import name, its own tests and a drawn dependency DAG (component DAG): contracts, governance, knowledge_graph (orchestrata_kg), kernel, session, volks, gateway, tools, the composed release integration (import name orchestrata) and plugin (a packaging track). The source of the lift is the frozen monolith at e57782ea4.

ADR-0103 (Accepted, probationary, 2026-10-15) sets the method. A byte-faithful LIFT of frozen code is a deterministic script's output, not an LLM task (25 of 34 wave-1 files were reproduced byte-identically from the brief alone), and shipping it would carry frozen's debt into the new packages. So there are two copies: the oracle, regenerated on demand and never committed, and the clean target in packages/<c>/src/, which is the deliverable and must pass behavioural parity against the oracle and conform to the target design. The ADR stays probationary until a five-criterion POC passes. The file exists only on branch architecture/domain-model (commit b3ea29a31); it is not in docs/adr/ of the master-line worktrees read for this page.

ADR-0113 (Accepted, 2026-10-19) defines the cut-over and corrects the record. The 2026-10-19 push of the in-progress tree to origin/master (0faca7a7), which prod deployed, is a backup-and-deploy, not the cut-over. The cut-over is the future event where integration passes the fleet tier, the old src/orchestrata_ultimate/* is removed, one merge lands on master and /opt/orchestrata ships from that tree. It also orders integration level 1 to be built now.

INT-01 to INT-25 are the integration increments (packages/integration/increments/README.md). INT-01 is the spec delta (SPEC-125) and release scaffold, and it has landed. INT-02 to INT-24 lift the entry points into the release package: the CLI client and watch stream, the monolithic kernel.cli_main in five parts, the pipeline CLI and KG server, the gateway token minter, the test runner and service starter in five parts each, and the session pipeline CLI. INT-25 is a net-new composition of the session console script. Ruling gate E-1 was cleared on 2026-10-20 (ADR-0115); gates N4 (INT-11) and N-I1 (INT-04) are listed as standing. Measured 2026-10-23: packages/integration holds three Python files at 4ac0db570, so INT-02 to INT-25 have not landed on master. Related decisions: ADR-0107 (tools becomes a package), ADR-0108 (the AST toolkit stays host-side behind a contracts protocol), ADR-0112 (tools reaches Redis and embeddings through contracts protocols), ADR-0114 (orchkg sees the component packages) and ADR-0124 item 10 (cut-over before containers).

Open questions, stated as found.

1. The role of packages/. On 2026-10-22 the question was raised whether packages/ is the single edited source (the reading of ADR-0103 and ADR-0113, and of Python packaging practice) or a versioned deployment copy of src/. It has not been ruled.
2. ADR-0103's POC. Whether the five-criterion POC gate has passed or failed was not measured for this page.
3. Which branch the KG describes. Until ADR-0126 is ruled and implemented, syncs from different checkouts write into one project id.
4. Unpinned components. INT-01's release pins still read <PENDING volks design> for orchestrata-volks and <PENDING tools release id> for codetools.

The open decisions page tracks what awaits a ruling.

11. Where to go next

Pick the path that matches why you are here.

• New to orchestrata. Starting context, then the volks, then the architecture and its full-size diagram. Keep the glossary open.
• About to change code. The code reference for the module you touch, its curated page under the module docs index, the component DAG, then workflow, briefs and gates.
• Operating it. Runtime services, deployment, isolated test fleet, runbooks and running the test suite.
• Checking a requirement. Specs and the RTM.
• Understanding a decision. Decisions, open decisions, the rulings canon and plans.
• Catching up on history. Sessions, tasks and research.

Related

• Orchestrata Ultimate hub
• Table of contents
• Starting context
• Architecture and architecture diagram
• Component DAG
• Runtime services
• Code reference
• Glossary