2.2. Architecture
2.2.1. Infrastructure overview
Before the internals, the whole platform on one page. Read it from the left:
an operator’s question or change request enters through spear-chat and
reaches the reasoning and control plane, which draws on two sources of
evidence kept apart on purpose — the authoritative, normative one (standards,
in warm) and the implementation one (repositories, corpora, local tools and
build outputs, in blue). The model backends only reason; everything that
touches a tree goes through the execution environment and stays inside its
workspace and read/write boundaries. What comes out on the right is either
grounded — an answer, a plan, a change, a validation result — or an explicit
refusal to answer when the evidence is insufficient.
Fig. 2.2 The SPEAR infrastructure. The two sources of truth — specification and implementation — are kept separate and reconciled only in the runtime.
2.2.2. Where each part runs
SPEAR runs on two machines. The operator machine — a workstation, or the
container that stands for one — runs spear-chat and everything that
touches a tree or keeps state: the control plane, the coding core and the
normative runtime, the sandbox in which every tool, build and test runs, the
project trees, the retrieval index and the state directory. The inference
host holds the GPU and runs only the server/ component: llama-server
behind the spear-inference unit, serving the model on :8010, the
embedding worker that indexing calls over SSH, and fine-tuning.
Two things cross between them. Every model call goes through an SSH tunnel
that spear-chat --reds opens from 127.0.0.1:8082 to the host’s
:8010; the prompt carries what the tools read, so that is what the host
sees. Indexing sends document chunks to the embedding worker and gets vectors
back; a query is embedded on the operator machine and never leaves it.
Fig. 2.3 Where each part runs, and what crosses between the two machines.
Setting up the host is Setting up an inference host; the ports and the other endpoints the client can use instead are in Ports and endpoints.
What a turn is told about its workspace — rules, skills, workspace knowledge, project metadata — and the external capabilities it may reach are selected by the control plane per workspace and request class; they are described below (What a turn is shown, Workspace knowledge, External capabilities).
2.2.3. Request classes and execution paths
Every request is classified before anything runs, from the request’s own words and from whether a standard is engaged for the session:
Class |
What it is |
|---|---|
|
names no subject of its own, and no standard is engaged |
|
about the working tree: read it, change it, build it, test it |
|
about what a bound standard requires |
|
a change to the tree that must satisfy the bound standard |
Fig. 2.4 One request, one class, one path.
The class decides the path:
The coding core, behind SpearHost — every request with no standard engaged. A standalone tool-calling loop with six tools whose every call crosses SpearHost, the control plane. The turn ends with implementation evidence computed from the record of what the calls did, never from the model’s account of it (Evidence and verdicts); the checks that may verify it are the project’s declared and probed commands (Projects and corpora). The coding core needs an OpenAI-compatible endpoint; the Anthropic backend serves the general and normative paths. See Implementation mode.
The normative runtime — requests in a session where a standard is engaged.
The provider-neutral AgentRuntime loop with the standard’s tools, provision
records and the answer guards. It answers normative questions, and holds a
change asked for in such a session that is not MIXED to a five-stage workflow.
See Normative mode: authoritative standards and The bound-session change workflow.
The MIXED orchestration — a change that must satisfy the bound standard.
The normative runtime runs first, read-only; its cited provisions become a
constraint packet; the coding core makes the change; a post-check judges the
final source against the packet by deterministic evidence providers. The
verdict composes the implementation evidence with a normative status:
compliance only from normative evidence, otherwise NOT_DEMONSTRATED. See
Mixed mode.
The three paths share the harness underneath — workspace, command policy, sandbox, audit — and none of them lets a model’s statement stand as evidence.
Each path is also given only its own context. A turn starts from its workspace
— the registered project, or an unregistered tree on its own — and a
deterministic selector (context_selection.py) keeps the context its class
and pass call for, of this workspace or explicitly generic: rules, skills,
workspace knowledge, project metadata and external capabilities. Every
eligible skill is offered — there is no similarity gate, only a bound of eight
per turn — and knowledge and capabilities reach the passes that run on the
coding core, never a normative one. The selector also names the tool family;
every decision is traced and none is shown to the model
(What a turn is shown).
2.2.4. Runtime components
CLI / application (rag_chat.py)
|
v
TaskController --- request class, standard binding
|
context selection --- rules, skills, knowledge, metadata, capabilities
| | |
v v v
coding core AgentRuntime MixedOrchestrator
(agent/) (normative runtime) normative pre-pass
| ModelBackend NormativeConstraintSet
v WorkingState coding core
SpearHost ContextEngine post-check
(control_plane) VerificationPolicy composite verdict
target policy CheckpointManager
refusal breaker SessionStore
capability gateway --- MCP providers (stdio)
| |
v v
ToolRouter -- ToolRegistry -- ResultStore
|
v
CommandRunner -- Bubblewrap
The coding core (client/agent/) imports nothing of SPEAR: it calls a
Host interface for every read, write and command, and SpearHost
implements that interface with SPEAR’s policy. Its evidence is turned into the
implementation verdict by completion.py. In front of every mutation,
target_policy.py applies the target policy
(Security model), and refusal_breaker.py stops a turn that
keeps repeating a refused operation (Tool execution harness). The capability
gateway (capability_gateway.py) answers the spear-capability host
command itself, never through a shell. The MIXED orchestration
(mixed_orchestration.py) composes the two runtimes and the normative
evidence modules (normative_constraints, normative_coverage,
normative_predicates, normative_evidence); it changes neither.
The AgentRuntime can also run Explorer and Reviewer roles with isolated
contexts and read-only tools; they are experimental and off by default.
2.2.5. Where state is kept
Sessions, tool results, checkpoints, traces and workspace knowledge live in the state directory, each with its own owner (Directory layout; retention in Runtime internals). Turns are also recorded as trajectories, which the training subsystem curates into datasets outside the turn (Training and fine-tuning).
Contributor internals — task ownership, context composition, dependency direction and the model capability boundary — are described in Runtime internals.
2.2.6. Provenance
The coding core is SPEAR’s own module, built by porting the coding loop and the
coding tools of Hermes Agent (Nous Research, MIT license) function by function,
and verifying the port against results captured from Hermes itself. What sits
around it — SpearHost, the command policy and sandbox, the evidence plane, the
normative runtime and the MIXED orchestration — is SPEAR’s. Every file copied
or adapted, with its upstream revision, its license and its destination, is
listed in THIRD_PARTY_NOTICES.md at the repository root.