Adaptive Engineering Harness (AEH)

简体中文 · Codex usage guide · Documentation

Status: CURRENT Source: 0.3.0.dev0 (unreleased) · Latest GitHub release: v0.2.0 · M1–M6 merged · Agent-driven flow merged · PyPI not published

AEH is an independent acceptance layer for software changes made with coding agents. Codex can write the change; AEH makes the requirements, tests, evidence, approvals, and final decision explicit and replayable.

Use it when a mistake would cost more than a quick retry: shared contracts, permissions, migrations, money, releases, infrastructure, security, or work performed by a highly autonomous agent.

What changes when you use AEH?

Without AEH, the same agent can implement a change, run its own tests, and tell you that the work is safe. With AEH, acceptance is a separate process:

your intent + authority -> Agent-chosen workflow -> implementation -> AEH checks -> result

AEH records what was requested, locks the relevant test evidence, rejects illegal state changes, and stops at human Gates when authority is required. A confident agent response or a passing test is useful evidence, but neither is treated as proof by itself.

Use AEH with Codex

After AEH is installed in a repository, you can work in natural language. For a normal change, tell Codex:

Use AEH for this change. Decide the lightest safe workflow from the actual scope, create the Change, implement and verify locally, and do not ask me to choose internal stages. Stop before commit, push, PR, merge, release, or any credential-backed Gate.

For a small bug:

Fix the incorrect empty-state message. Treat this as a small bug, add a focused regression test, and work locally only. Let AEH and the Agent choose the workflow from the evidence.

For a sensitive change:

Change the payment permission check using AEH. Preserve raw evidence and stop only when a human Gate actually needs my decision.

See Using AEH with Codex for ready-to-copy prompts, staged authorization examples, and what Codex should report at each stop.

The Agent chooses the lightest safe workflow

AEH is intentionally not equally heavy for every change.

Level	Use it for	Typical path
DIRECT	tiny, low-risk, easily reversible edits	classify → implement → basic verify
LIGHTWEIGHT	ordinary bugs with a focused regression test	targeted ground → bug contract → RED/GREEN → verify
STANDARD	features and cross-file behavior changes	ground → spec → test design → RED/GREEN → review
CRITICAL	security, money, identity, permissions, migration, release, or high-impact automation	STANDARD plus independent human Gates and stronger evidence

EXPLORE is available for experiments that may be discarded or later promoted into a governed change. Users do not need to select these levels: the Agent uses scoped facts and AEH rejects unsupported downgrade attempts.

Install

AEH requires Python 3.10 or newer. No AEH package is currently published to PyPI.

For development or an explicitly trusted checkout:

git clone https://github.com/YIMO691/aeh.git
cd aeh
python -m venv .venv
# Windows: .venv\Scripts\activate
# POSIX:   source .venv/bin/activate
python -m pip install -e .
aeh --help

For a released version, prefer the wheel and recorded SHA-256 from the trusted GitHub Release. Do not infer a PyPI package from the project name.

Bootstrap a repository

Try AEH on a disposable repository first:

aeh bootstrap /path/to/project
aeh doctor /path/to/project

Bootstrap installs a versioned .aeh/ runtime snapshot and managed agent instructions. In a governed repository, Codex reads AGENTS.md, .aeh/profile.yaml, and .aeh/effective-workflow.yaml before implementation.

If you want to drive the lifecycle directly instead of asking Codex, start a Change with the CLI:

cd /path/to/project
aeh change new "fix duplicate claim side effect" --level LIGHTWEIGHT
aeh change status CHG-2026-0001
aeh change continue CHG-2026-0001 --authority /outside/repo/task-authority.yaml

The exact next commands depend on the effective workflow. The engineering guide covers the full CLI lifecycle, repair, upgrade, approvals, CI replay, and coordination.

Authority stays bounded

AEH does not treat “implement this” as permission to publish it. Give the Agent a task boundary once; it should continue inside that boundary and ask again only for a real expansion, failure, or human Gate. Local work and publication remain distinct:

1. inspect and plan;
2. modify and verify locally;
3. commit;
4. push and open a pull request;
5. merge;
6. tag, release, deploy, or publish.

Credential-backed Gates are separate again. A credential should be scoped to one Change and one Gate, kept outside the repository and evidence, and never reused for another Gate.

AEH itself stops at the governed decision boundary. It does not automatically push, create a PR, merge, deploy, or release.

Trust boundary

AEH provides versioned contracts, evidence integrity, test locking, explicit mutation boundaries, constrained process launch, credential-bound approvals, read-only CI replay, and bounded single-host Change coordination.

It does not provide:

• public-key identity, legal non-repudiation, enterprise IAM, or hardware key custody;
• kernel, container, VM, filesystem, network, syscall, or process-tree isolation;
• an unbypassable hosted CI service or automatic branch-protection configuration;
• cross-host or network-filesystem coordination correctness;
• automatic push, PR, merge, deployment, release, or PyPI publication.

HMAC proves possession of a configured shared secret; it does not prove legal identity. Source files alone do not prove that external SCM controls are active. Read M5 security, M6.2 GitHub assurance, and M6.3 coordination for precise boundaries.

Current status

The current source version is 0.3.0.dev0; the latest public release is v0.2.0. M1–M6, M6.3A/B/C, and the Agent-driven flow are merged, while the current source line remains unreleased and PyPI remains unpublished. The current regression baseline is 418 tests: 414 passed and 4 expected Windows symlink-permission cases skipped.

See AEH Current Status for exact merge and CI evidence. The V0.2 roadmap is a completed, version-bound planning record rather than the source of current operational truth.

Documentation

• Using AEH with Codex
• Documentation portal
• About AEH
• Current status
• Current architecture
• Engineering guide
• Security boundary
• Contributing

Version-bound research, handbook, archive, and release evidence are retained for traceability and are not promoted to current truth.

Supported agent surfaces

Agent	Managed surface	Status
Codex	AGENTS.md managed section	Supported
Claude Code	CLAUDE.md managed section	Supported
Other agents	declarative adapter contract	Extensible; not implied supported

Bootstrap preserves user-owned content outside managed sections and fails safe on ambiguous conflicts.

Development

python -m pip install -e .
python -m unittest discover -s tests -p "test_*.py"
python scripts/check_docs.py

See CONTRIBUTING.md before changing contracts or schemas.

License

MIT