# v0.5 — Architecture Close, Scale and Organization Governance

v0.5 closes the original single-host architecture and adds the first scale/governance layer. The deterministic Harness remains the only acceptance authority: planner/reviewer/remote-worker output is evidence or proposed change, never an acceptance decision.

## v0.4.17 — Control-Plane Snapshot & Hard Freeze

Every run materializes `.harness/controller/<task>/files` plus a manifest containing per-file SHA-256, a composite SHA-256, AEH version and controller Git SHA when available. The snapshot includes project config, agent topology, generated topology, toolchain source/lock, policy directories, schemas and skills. When AEH modifies itself, controller source modules are frozen as well.

Agent skill text is loaded from the snapshot. OPA reads policies through the frozen policy root. If live controller files change during the run, the run records controller drift but continues to use the old snapshot. The changed controller becomes eligible only on the next run.

## v0.4.18 — Executable Multi-Worker Planner Waves

SPEC tasks with planning enabled are decomposed by the configured planner into a typed task DAG. The plan is rejected unless task IDs/dependencies/agents/scopes are valid and every TaskContract requirement is assigned to at least one implementation task.

Each local delegation executes in its own detached Git worktree. Accepted earlier-wave patches are materialized first, the frozen task/controller context is copied, and a baseline commit is created. The worker returns a binary patch. Within each wave the coordinator checks every patch before applying any patch, then applies all accepted patches and runs a deterministic barrier. Only a PASS barrier unlocks the next wave.

Graphify is conservative scheduling evidence: scope overlap, shared structural nodes, communities, graph distance and high-centrality nodes can serialize tasks. Graphify cannot override the explicit dependency DAG or redefine desired architecture.

## v0.4.19 — Requirement Evidence Graph

`.harness/evidence/<task>.json` records nodes for requirements, planner tasks, changed files, deterministic checks, review findings, agent sessions, commit and pull request. Requirement coverage requires both:

1. a task assigned to the requirement that produced a concrete changed file; and
2. PASS results for all validators declared by the requirement.

When `evidence.requireComplete=true`, incomplete coverage is a deterministic failure and enters the normal autonomous remediation/escalation lifecycle.

## v0.4.20 — Worker Sandbox Hardening

Podman remains optional globally but can be required by policy or task risk. Supported OpenCode sandbox runs default to a read-only container root, rootless user namespace, `cap-drop=ALL`, no-new-privileges, PID limits, ephemeral HOME and tmpfs. Network is denied when project policy or the logical agent denies network. CPU/RAM/tmpfs and immutable image digests are configurable. Only explicitly allowlisted environment/credential variables cross the boundary; SSH agents, host sockets and credentials are not projected implicitly.

Both the logical-agent prompt path and the legacy Podman worker executor use the hardened policy.

## Scale and organization governance

### Distributed workers

The distributed protocol has filesystem and HTTP queue transports. Jobs are leased with expiry/reclaim semantics. A remote worker clones the frozen base ref, materializes accepted prior-wave patches, executes one delegated task and returns a binary patch plus session metadata. The coordinator rechecks scope and patch applicability and runs all deterministic barriers.

Remote workers are deliberately **untrusted patch producers**. They do not become validation or normative authorities. Git credentials remain on worker nodes and are not serialized into jobs.

Commands:

```bash
aeh worker serve . --port 8787 --host 0.0.0.0
aeh worker run . --worker-id node-01
```

For remote HTTP workers set `distributed.provider: http`, `distributed.endpoint` and optionally `distributed.tokenEnv` on worker/coordinator configs as appropriate.

### Organization policy bundles

Organization bundles contain `bundle.json`, file hashes, optional inheritance and policy directories. Sources may be local or remote and can pin the manifest SHA-256. Optional Cosign blob verification can require a configured public key and signature. Resolved bundles are cached under `.harness/policy-bundles` and frozen into the active controller snapshot before execution.

```bash
aeh policy sync
```

### Statistical eval dashboards

Repeated evals compute pass-rate Wilson intervals plus mean/median/standard deviation/confidence intervals for score, duration, tokens, cost, repairs and human interventions.

```bash
aeh eval repeat EVAL-001 --variant balanced --runs 10
aeh eval dashboard EVAL-001
```

### Native structured runtime adapters and resume

The agent contract layer exposes JSON Schemas in addition to Zod schemas. Runtimes that support native output schemas receive them; Zod remains the final parser/validator. Codex and OpenCode direct sessions expose resume/session primitives, while Paseo sessions resume through `send/wait/logs`. Ephemeral Podman sessions intentionally do not pretend they can resume host sessions without an explicit persisted session volume.

### MCP benchmark and packs

The MCP benchmark records a baseline serialized-config token estimate, local/remote reachability latency, permission-surface heuristic and stale-data risk. This is intentionally not yet a claim about exact runtime tool-schema tokens; runtime-native introspection is the next benchmark refinement.

```bash
aeh mcp benchmark
```

Default named packs remain least-privilege: research, browser and GitHub read-only are enabled as catalog groupings; observability stays opt-in.

## Default execution flow

```text
Intent / GitHub Issue
        ↓
Toolchain doctor/setup
        ↓
QUICK or SPEC
        ↓
Seal normative task inputs
        ↓
Resolve org policies + topology
        ↓
Freeze control plane
        ↓
Planner DAG
        ↓
Isolated local/remote worker waves
        ↓
Deterministic barriers
        ↓
Requirement evidence gate
        ↓
Reviewer quality convergence
        ↓
Regression rollback / model escalation / replan as needed
        ↓
Final quality gate + lead acceptance
        ↓
Deterministic delivery
        ↓
Final evidence graph + controller drift record
```

The user remains human-on-exception: product decisions, contradictory normative requirements and genuinely unavailable external resources are escalation states; implementation defects, review debt, worker failures and strategy churn remain autonomous recovery concerns.
