# v0.6 — Orchestration & Context Architecture

v0.6 changes the interactive model from a persistent lead that personally performs setup, discovery and specification authoring into a thin semantic orchestrator backed by bounded agents and durable Harness state.

## Thin lead

The interactive lead owns user intent, high-level routing, true ambiguity and final semantic acceptance. It delegates operational work:

```text
User
  |
  v
AEH Lead
  |-- explorer              repository discovery
  |-- environment-manager   doctor/setup/Paseo recovery
  |-- planner               decomposition + triage evidence
  |-- spec-manager          OpenSpec authoring
  `-- AEH                  implementation/validation/review/delivery
```

The lead should receive compact structured outcomes instead of retaining raw shell logs, full source files or long environment-repair transcripts.

## Paseo-native orchestration first

When the current Paseo agent exposes its orchestration tools, the lead prefers `create_agent`, `send_agent_prompt`, `get_agent_status`, `get_agent_activity` and lifecycle controls, and uses `/paseo-handoff` for responsibility transfer. `/paseo-committee` and `/paseo-advisor` may provide advisory reasoning but never override deterministic AEH gates.

AEH still contains a CLI-based Paseo adapter because an external Node control-plane process cannot invoke tools local to the conversational agent. That adapter is now a compatibility fallback rather than the lead's normal orchestration mechanism.

The fallback negotiates the installed Paseo surface at runtime with `paseo --version` and help output. It does not assume `--quiet`, JSON output or daemon JSON support. This specifically avoids the failure mode where an older Paseo such as 0.3.1 rejects a flag expected by a newer CLI.

Recoverable daemon states such as stale PID, unreachable daemon or connection refused are stopped/restarted and verified before lead/worker launch.

## Fresh lead sessions

`aeh start` now creates a fresh lead by default:

```bash
aeh start
```

Explicit reuse is:

```bash
aeh start --resume
```

This prevents a new invocation from inheriting stale conversational assumptions, obsolete bootstrap instructions or unnecessary historical context. Durable Git/TaskContract/seal/run/audit/delivery state remains reusable even when the conversation is fresh.

## Context pressure and automatic lead rotation

Default policy:

```text
<70%     normal
70-80%   PRESSURE: stop exploratory work and increase delegation
>=80%    HANDOFF_REQUIRED: write handoff and rotate to a fresh lead
>=90%    HARD_HANDOFF: no further engineering work in the old lead
```

The public check is:

```bash
aeh context guard --agent "$PASEO_AGENT_ID"
```

When Paseo exposes a usable context ratio and the guard runs inside a managed Paseo lead, AEH writes:

```text
.harness/paseo/handoffs/lead-<timestamp>.json
```

and automatically creates a fresh lead. The artifact records prior/new lead IDs, context usage, branch, latest run/audit/delivery references, and an optional semantic brief. The fresh lead is bootstrapped from this deterministic artifact and its referenced sealed state. Normal compaction-and-continue is not the preferred path once the handoff threshold is crossed.

If the installed Paseo version does not expose a stable context ratio, AEH returns `UNKNOWN`; it does not fabricate token usage. Fresh-on-start and delegation-first behavior still reduce accumulation.

## OpenSpec as SPEC authoring backend

For non-QUICK changes, the lead no longer writes proposal/spec/design/tasks itself. `spec-manager` owns SPEC authoring with OpenSpec.

```text
CHANGE
  |
  v
SPEC
  |
  v
spec-manager
  |
  |-- aeh spec prepare
  |-- openspec status / instructions
  |-- proposal/specs/design/tasks
  |-- openspec validate --strict
  `-- aeh spec compile
          |
          v
      AEH proposal/spec/design/tasks/Gherkin
      + TaskContract
      + stable requirement IDs
      + validator traceability
          |
          v
         seal
```

Commands:

```bash
aeh spec prepare READABILITY-001 --title "Improve readability"
aeh spec compile READABILITY-001 --title "Improve readability"
aeh sdd validate READABILITY-001
aeh seal READABILITY-001
aeh run READABILITY-001
```

OpenSpec is an **authoring source before freeze**. The compiled native AEH SDD/TaskContract and seal remain normative during implementation. OpenSpec apply commands do not replace AEH's worker, validation, review-convergence or delivery lifecycle.

The compiler records `authoring.provider=openspec`, change name and SHA-256 provenance. It maps OpenSpec `### Requirement:` / `#### Scenario:` content into stable AEH requirement IDs and Gherkin acceptance. Refactor/tooling changes without a delta spec receive an explicit behavior-preservation requirement.

A requirement validator may not be invented. AEH uses configured deterministic validators first, otherwise derives a project test/typecheck/build command from known project metadata. If it cannot establish executable requirement evidence, SPEC compilation fails instead of emitting a phantom validator.

## Built-in orchestration preset

New projects extend:

```jsonc
{
  "extends": ["aeh:orchestration"]
}
```

This extends `aeh:default`, makes lead/planner delegation-first, and adds:

- `environment-manager`;
- `spec-manager`.

OpenSpec is included in the declarative toolchain and automatically selected when `sdd.authoring.provider: openspec` is active.

## Trust boundary

The authority order remains unchanged:

1. user intent / true product decisions;
2. sealed compiled AEH SDD + TaskContract;
3. deterministic validators/evidence;
4. quality/review gates;
5. LLM summaries and advisory tools.

Paseo skills improve communication and lifecycle control; they do not become gate authority. OpenSpec improves specification authoring; it does not become mutable execution truth after the AEH seal.
