# thestoryportal/arhugula-harness architecture

> Architecture diagram of the GitHub repository thestoryportal/arhugula-harness, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thestoryportal/arhugula-harness
- Repository: https://github.com/thestoryportal/arhugula-harness

## Overview

1. **What this repo is**
   This is a Python `uv` workspace for a multi-LLM agent harness called **H_T**. The repo is organized around four design axes — **IS** (information substrate), **AS** (action surface), **CP** (control plane), **OD** (observability/discipline) — plus a **CXA** cross-axis composition layer that stitches the axes together at runtime.

2. **Top-level architectural split**
   The repo has two big kinds of content:
   - **Executable packages** under `harness-runtime/`, `harness-core/`, `harness-is/`, `harness-as/`, `harness-cp/`, `harness-od/`, `harness-cxa/`
   - **Governance/design artifacts** under `design-substrate/` and `.harness/`
   
   The design artifacts are not just docs; they define the contract boundaries that the runtime code and tests are enforcing.

3. **Core runtime is the main orchestrator**
   `harness-runtime/` is the central execution layer. It contains:
   - bootstrap stages that assemble the system in sequence,
   - lifecycle modules for dispatch, routing, pause/resume, HITL, tool execution, validation, and telemetry,
   - CLI and admin entrypoints,
   - configuration loading and runtime wiring.
   
   This is the place where the axes become an operational harness.

4. **Shared domain model lives in `harness-core`**
   `harness-core/` holds the common enumerations and policy/domain primitives used across the workspace, such as workflow events, workload classes, persona tiers, sandbox decision policy, deployment surface, and identity. This package is the lowest-friction shared boundary so the axis packages do not duplicate semantic types.

5. **Information substrate (`harness-is`)**
   `harness-is/` is the durable state and artifact substrate. Its responsibilities include:
   - path and artifact registries,
   - state ledger read/write and JSONL event ledger lifecycle,
   - git-tied checkpoint/rollback behavior,
   - workload manifest and prompt manifest handling.
   
   Architecturally, this is where the system persists and resolves “what exists” before the control plane decides “what should happen next.”

6. **Action surface (`harness-as`)**
   `harness-as/` defines the action-side policy and capability surface:
   - sandbox tier/provider selection,
   - secret fetching rules,
   - MCP transport floors,
   - engine-class composition,
   - blast-radius and gate-level constraints,
   - attribute and span namespace rules.
   
   This layer governs what the harness is allowed to do when it reaches out to sandboxes, tools, model providers, or secrets.

7. **Control plane (`harness-cp`)**
   `harness-cp/` is the decision-making layer for workflow shape and routing:
   - workflow drivers and topology patterns,
   - routing layers and fallback chains,
   - pause/resume protocols,
   - HITL placement and tool-call rewriting,
   - validator framework and fail taxonomy,
   - workload-to-engine-class selection.
   
   If IS is “state,” CP is “policy + routing logic” for the next action in a workflow.

8. **Observability/disciplined execution (`harness-od`)**
   `harness-od/` handles tracing, sampling, redaction, cost attribution, and audit plumbing:
   - OTEL span store/processor components,
   - redaction/token audit logic,
   - cost formula and cost record serialization,
   - multi-tenant trace separation,
   - local collector and sampling mode logic.
   
   This layer is the system’s telemetry and governance boundary; it ensures the harness can observe itself without leaking or collapsing tenant boundaries.

9. **Cross-axis composition (`harness-cxa`)**
   `harness-cxa/` is intentionally small and acts as the bridge between axes. It currently centers on CP audit conversion and seam exports, which suggests CXA is used to normalize or transform artifacts when one axis needs to interpret another axis’ output.

10. **Runtime data flow**
   The typical path is:
   - configuration and workflow manifests are loaded,
   - bootstrap stages wire IS/AS/CP/OD into the runtime,
   - the runtime selects a workflow topology and dispatch strategy,
   - tool/LLM/MCP actions execute through sandbox and provider abstractions,
   - state ledger, audit ledger, spans, and cost records are emitted,
   - pause/resume, HITL, or validator escalation may interrupt and redirect the flow.
   
   So the runtime is not a simple request/response app; it is a stateful orchestration loop with explicit policy checkpoints.

11. **Execution environments and integrations**
   The repo supports multiple execution backends and deployment modes:
   - local self-hosted Docker/compose stack in `deploy/self-hosted-local/`,
   - managed-cloud deployment assets in `deploy/managed-cloud/`,
   - sandbox/tool backends such as Docker, E2B, and gVisor-like execution paths,
   - MCP server/client boundaries,
   - OTEL collectors and Tempo/Grafana-style telemetry plumbing.
   
   These are architectural boundaries because the harness is designed to route work differently depending on trust, sandbox tier, and deployment target.

12. **Workflow and session governance**
   The repository contains substantial workflow-control material in `.harness/`, `.claude/`, and root governance files like `CLAUDE.md`, `AGENTS.md`, and `Phase_7_*`. This indicates the harness is operated through a disciplined session/process model, with explicit phase transitions, clearance artifacts, and roadmap/audit records rather than ad hoc development.

13. **Validation strategy**
   Every package has strong unit coverage, and `harness-runtime/` adds integration suites that exercise full bootstrap, routing, pause/resume, multi-server routing, memory backends, validator escalation, and live execution paths. There are also repo-level scripts and CI workflows under `.github/` and `tools/` for readiness probes, dashboard generation, and live environment checks.

14. **How to draw the architecture**
   A useful diagram would place `harness-runtime` in the center, fed by configuration and workflow manifests from `harness-is`, constrained by policy/capability from `harness-as` and `harness-cp`, and instrumented by `harness-od`. Surround that with deployment/runtime backends, MCP/tool/sandbox providers, and a separate documentation/governance plane (`design-substrate`, `.harness`) that defines and audits the contract surface.

Main entry points: [`harness-runtime/src/harness_runtime`](https://github.com/thestoryportal/arhugula-harness/tree/main/harness-runtime/src/harness_runtime) (Runtime core), [`harness-runtime/src/harness_runtime/bootstrap`](https://github.com/thestoryportal/arhugula-harness/tree/main/harness-runtime/src/harness_runtime/bootstrap) (Bootstrap), [`design-substrate`](https://github.com/thestoryportal/arhugula-harness/tree/main/design-substrate) (Design substrate), [`harness-runtime/src/harness_runtime/lifecycle`](https://github.com/thestoryportal/arhugula-harness/tree/main/harness-runtime/src/harness_runtime/lifecycle) (Lifecycle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_runtime["Runtime"]
  node_n_runtime["Runtime core<br/>orchestrator"]
  node_n_core["Core types<br/>shared-domain"]
  node_n_is[("Information substrate<br/>state-artifact")]
  node_n_as["Action surface<br/>capability-policy"]
  node_n_cp["Control plane<br/>routing-policy"]
  node_n_od["Observability<br/>telemetry-governance"]
  node_n_cxa["CXA bridge<br/>cross-axis-seam"]
  node_n_bootstrap["Bootstrap<br/>startup-stages"]
  node_n_lifecycle["Lifecycle<br/>runtime-steps"]
  node_n_config["Config"]
  node_n_cli["CLI/admin<br/>entrypoints"]
end

subgraph group_g_governance["Governance"]
  node_n_design["Design substrate<br/>spec-adr-plane"]
  node_n_harness["Harness ops<br/>session-governance<br/>[.harness]"]
  node_n_claude["Claude ops<br/>agent-governance<br/>[.claude]"]
end

subgraph group_g_deploy["Deployments"]
  node_n_local_deploy[("Local deploy<br/>self-hosted-stack")]
  node_n_cloud_deploy[("Cloud deploy<br/>managed-cloud")]
end

subgraph group_g_tools["Tooling"]
  node_n_tools_pkg["Repo tools<br/>automation"]
  node_n_github["CI flows<br/>ci-workflows<br/>[workflows]"]
  node_n_examples["Workflow examples"]
end

node_n_design -->|"specifies"| node_n_cp
node_n_design -->|"specifies"| node_n_is
node_n_design -->|"specifies"| node_n_as
node_n_design -->|"specifies"| node_n_od
node_n_design -->|"guides"| node_n_runtime
node_n_harness -->|"tracks"| node_n_design
node_n_claude -->|"operates through"| node_n_harness
node_n_config -->|"feeds"| node_n_runtime
node_n_bootstrap -->|"wires"| node_n_is
node_n_bootstrap -->|"wires"| node_n_as
node_n_bootstrap -->|"wires"| node_n_cp
node_n_bootstrap -->|"wires"| node_n_od
node_n_bootstrap -->|"wires"| node_n_cxa
node_n_runtime -->|"starts with"| node_n_bootstrap
node_n_runtime -->|"drives"| node_n_lifecycle
node_n_runtime -->|"exposes"| node_n_cli
node_n_runtime -->|"loads"| node_n_config
node_n_lifecycle -->|"reads/writes"| node_n_is
node_n_lifecycle -->|"executes via"| node_n_as
node_n_lifecycle -->|"routes by"| node_n_cp
node_n_lifecycle -->|"emits"| node_n_od
node_n_cxa -->|"converts"| node_n_cp
node_n_cxa -->|"seams"| node_n_od
node_n_local_deploy -->|"hosts"| node_n_runtime
node_n_cloud_deploy -->|"hosts"| node_n_runtime
node_n_tools_pkg -->|"checks"| node_n_runtime
node_n_github -->|"runs"| node_n_tools_pkg
node_n_examples -->|"demonstrates"| node_n_cp
node_n_examples -->|"configures"| node_n_config

click node_n_runtime "https://github.com/thestoryportal/arhugula-harness/tree/main/harness-runtime/src/harness_runtime"
click node_n_core "https://github.com/thestoryportal/arhugula-harness/tree/main/harness-core/src/harness_core"
click node_n_is "https://github.com/thestoryportal/arhugula-harness/tree/main/harness-is/src/harness_is"
click node_n_as "https://github.com/thestoryportal/arhugula-harness/tree/main/harness-as/src/harness_as"
click node_n_cp "https://github.com/thestoryportal/arhugula-harness/tree/main/harness-cp/src/harness_cp"
click node_n_od "https://github.com/thestoryportal/arhugula-harness/tree/main/harness-od/src/harness_od"
click node_n_cxa "https://github.com/thestoryportal/arhugula-harness/tree/main/harness-cxa/src/harness_cxa"
click node_n_bootstrap "https://github.com/thestoryportal/arhugula-harness/tree/main/harness-runtime/src/harness_runtime/bootstrap"
click node_n_lifecycle "https://github.com/thestoryportal/arhugula-harness/tree/main/harness-runtime/src/harness_runtime/lifecycle"
click node_n_config "https://github.com/thestoryportal/arhugula-harness/tree/main/harness-runtime/src/harness_runtime/config"
click node_n_cli "https://github.com/thestoryportal/arhugula-harness/tree/main/harness-runtime/src/harness_runtime/cli"
click node_n_design "https://github.com/thestoryportal/arhugula-harness/tree/main/design-substrate"
click node_n_harness "https://github.com/thestoryportal/arhugula-harness/blob/main/.harness"
click node_n_claude "https://github.com/thestoryportal/arhugula-harness/blob/main/.claude"
click node_n_local_deploy "https://github.com/thestoryportal/arhugula-harness/tree/main/deploy/self-hosted-local"
click node_n_cloud_deploy "https://github.com/thestoryportal/arhugula-harness/tree/main/deploy/managed-cloud"
click node_n_tools_pkg "https://github.com/thestoryportal/arhugula-harness/tree/main/tools"
click node_n_github "https://github.com/thestoryportal/arhugula-harness/blob/main/.github/workflows"
click node_n_examples "https://github.com/thestoryportal/arhugula-harness/tree/main/examples"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n_runtime,node_n_core,node_n_is,node_n_as,node_n_cp,node_n_od,node_n_cxa,node_n_bootstrap,node_n_lifecycle,node_n_config,node_n_cli toneBlue
class node_n_design,node_n_harness,node_n_claude toneAmber
class node_n_local_deploy,node_n_cloud_deploy toneMint
class node_n_tools_pkg,node_n_github,node_n_examples toneRose
```

## Components

### Runtime

Executable harness packages and orchestration loop

- [Runtime core](https://github.com/thestoryportal/arhugula-harness/tree/main/harness-runtime/src/harness_runtime): orchestrator · Central bootstrap, lifecycle, CLI, and execution loop for the harness · `harness-runtime/src/harness_runtime`
- [Core types](https://github.com/thestoryportal/arhugula-harness/tree/main/harness-core/src/harness_core): shared-domain · Workspace-wide enums and policy primitives shared across packages · `harness-core/src/harness_core`
- [Information substrate](https://github.com/thestoryportal/arhugula-harness/tree/main/harness-is/src/harness_is): state-artifact · Durable state, path registry, ledgers, manifests, and git-tied checkpoints · `harness-is/src/harness_is`
- [Action surface](https://github.com/thestoryportal/arhugula-harness/tree/main/harness-as/src/harness_as): capability-policy · Sandbox, secrets, provider, transport, and blast-radius policy surface · `harness-as/src/harness_as`
- [Control plane](https://github.com/thestoryportal/arhugula-harness/tree/main/harness-cp/src/harness_cp): routing-policy · Workflow topology, routing, pause/resume, HITL, validators, and engine selection · `harness-cp/src/harness_cp`
- [Observability](https://github.com/thestoryportal/arhugula-harness/tree/main/harness-od/src/harness_od): telemetry-governance · Tracing, sampling, redaction, cost attribution, and tenant-aware audit plumbing · `harness-od/src/harness_od`
- [CXA bridge](https://github.com/thestoryportal/arhugula-harness/tree/main/harness-cxa/src/harness_cxa): cross-axis-seam · Cross-axis composition and artifact conversion between control and observability seams · `harness-cxa/src/harness_cxa`
- [Bootstrap](https://github.com/thestoryportal/arhugula-harness/tree/main/harness-runtime/src/harness_runtime/bootstrap): startup-stages · Sequenced stages that wire IS, AS, CP, OD, and CXA into runtime · `harness-runtime/src/harness_runtime/bootstrap`
- [Lifecycle](https://github.com/thestoryportal/arhugula-harness/tree/main/harness-runtime/src/harness_runtime/lifecycle): runtime-steps · Dispatch, routing, tool execution, pause/resume, HITL, validation, and telemetry handlers · `harness-runtime/src/harness_runtime/lifecycle`
- [Config](https://github.com/thestoryportal/arhugula-harness/tree/main/harness-runtime/src/harness_runtime/config): runtime-config · Configuration loading, path bindings, provider secrets, and sandbox defaults · `harness-runtime/src/harness_runtime/config`
- [CLI/admin](https://github.com/thestoryportal/arhugula-harness/tree/main/harness-runtime/src/harness_runtime/cli): entrypoints · Command-line and administrative entrypoints for running and inspecting the harness · `harness-runtime/src/harness_runtime/cli`

### Governance

Design substrate and harness session artifacts

- [Design substrate](https://github.com/thestoryportal/arhugula-harness/tree/main/design-substrate): spec-adr-plane · Canonical specs, ADRs, implementation plans, and workflow governance artifacts · `design-substrate`
- [Harness ops](https://github.com/thestoryportal/arhugula-harness/blob/main/.harness): session-governance · Phase logs, clearances, worklists, and internal governance artifacts · `.harness`
- [Claude ops](https://github.com/thestoryportal/arhugula-harness/blob/main/.claude): agent-governance · Session commands, skills, and workflow definitions for disciplined operation · `.claude`

### Deployments

Local and managed execution backends

- [Local deploy](https://github.com/thestoryportal/arhugula-harness/tree/main/deploy/self-hosted-local): self-hosted-stack · Docker-compose local runtime with OTEL collector, Grafana, Tempo, and MCP echo server · `deploy/self-hosted-local`
- [Cloud deploy](https://github.com/thestoryportal/arhugula-harness/tree/main/deploy/managed-cloud): managed-cloud · Managed-cloud deployment assets and collector configuration · `deploy/managed-cloud`

### Tooling

Repo automation, checks, and dashboards

- [Repo tools](https://github.com/thestoryportal/arhugula-harness/tree/main/tools): automation · Readiness probes, dashboard generation, live checks, and hook scripts · `tools`
- [CI flows](https://github.com/thestoryportal/arhugula-harness/blob/main/.github/workflows): ci-workflows · Repository CI and deployment workflows plus guard scripts · `.github/workflows`
- [Workflow examples](https://github.com/thestoryportal/arhugula-harness/tree/main/examples): examples · Example workflow topologies and minimal configuration fixtures · `examples`

## Connections

- Design substrate → Control plane: specifies · Design substrate defines control-plane contracts and topology rules
- Design substrate → Information substrate: specifies · Design substrate defines durable-state and manifest contracts
- Design substrate → Action surface: specifies · Design substrate defines capability and sandbox policy boundaries
- Design substrate → Observability: specifies · Design substrate defines observability and discipline contracts
- Design substrate → Runtime core: guides · Runtime implements the architecture captured in design artifacts
- Harness ops → Design substrate: tracks · Harness governance records reviews, clearances, and phase transitions
- Claude ops → Harness ops: operates through · Claude workflow and skill artifacts support disciplined repo operation
- Config → Runtime core: feeds · Configuration is loaded during bootstrap and runtime wiring
- Bootstrap → Information substrate: wires · Bootstrap stage binds the information substrate first
- Bootstrap → Action surface: wires · Bootstrap stage binds action-surface policy and providers
- Bootstrap → Control plane: wires · Bootstrap stage binds control-plane routing and validators
- Bootstrap → Observability: wires · Bootstrap stage binds telemetry and audit subsystems
- Bootstrap → CXA bridge: wires · Bootstrap stage connects cross-axis seam adapters
- Runtime core → Bootstrap: starts with · Runtime initializes by executing ordered bootstrap stages
- Runtime core → Lifecycle: drives · Runtime hands off to lifecycle components for orchestration
- Runtime core → CLI/admin: exposes · Runtime is reachable through CLI and admin entrypoints
- Runtime core → Config: loads · Runtime consumes workspace and environment configuration
- Lifecycle → Information substrate: reads/writes · Lifecycle modules persist and resolve state and manifests
- Lifecycle → Action surface: executes via · Tool, sandbox, secrets, and provider actions flow through AS
- Lifecycle → Control plane: routes by · Routing, pause/resume, HITL, and validation are controlled by CP
- Lifecycle → Observability: emits · Lifecycle emits spans, audits, and cost records into OD
- CXA bridge → Control plane: converts · CXA normalizes control-plane artifacts for cross-axis use
- CXA bridge → Observability: seams · CXA bridges CP and OD audit/telemetry boundaries
- Local deploy → Runtime core: hosts · Local compose stack runs the harness runtime and integrations
- Cloud deploy → Runtime core: hosts · Managed-cloud assets provide alternate runtime deployment
- Repo tools → Runtime core: checks · Repo tools exercise readiness, live paths, and dashboard flows
- CI flows → Repo tools: runs · CI workflows invoke repository scripts and validation checks
- Workflow examples → Control plane: demonstrates · Example workflow topologies show control-plane routing shapes
- Workflow examples → Config: configures · Examples provide minimal TOML and workflow manifests for runs