# v0.5.2 — Harness-governed engineering audits

v0.5.2 closes the read-only escape that existed in v0.5.1. A request no longer bypasses AEH merely because it does not mutate files. The interactive entrypoint now distinguishes a purely informational question from a read-only engineering operation.

## Intent model

Every conversational request is classified at the top level as:

```text
prompt
  |
  v
engineering intent
  |-- INFORMATIONAL -> direct answer, no mutation
  |-- AUDIT         -> Harness read-only audit pipeline
  `-- CHANGE        -> deterministic QUICK | SPEC triage
```

`AUDIT` is deliberately not a subtype of QUICK. A repository-wide review is valid audit scope even though it would be invalid QUICK scope, and it does not need artificial SDD artifacts merely to run a code review.

Examples:

```text
"What does src/core/run.ts do?"
  -> INFORMATIONAL

"review the repo and validate the code for improvements"
  -> AUDIT

"find bugs and security risks"
  -> AUDIT

"review this module and fix every bug you find"
  -> CHANGE -> QUICK | SPEC
```

The public classifier is:

```bash
aeh intent "review the repo and validate the code for improvements"
```

## Audit workflow

Run an audit explicitly with:

```bash
aeh audit "review the repo and validate the code for improvements"
```

Optional hints include repeated `--file`, `--domain`, `--reviewer` and `--risk low|medium|high` values.

The pipeline is:

```text
AUDIT request
   |
   v
worktree checkpoint
   |
   v
transient TaskContract + SHA-256 seal
   |
   v
hard-frozen control plane
   |
   v
configured deterministic validators
   |
   v
failure classification
   |
   v
read-only reviewer wave
   |
   v
finding normalization + deduplication
   |
   v
severity counts + DebtScore + Quality Gate evaluation
   |
   v
AuditReport
```

Reviewer sessions are clamped to `write=deny`, `gitWrite=deny` and `delegate=deny`. The worktree is also checkpointed before the audit and rolled back afterward, so an accidental tracked mutation by a reviewer or tool does not survive. Any dirty paths that existed before the audit are restored to their exact prior contents.

The transient contract and seal make the audit compatible with the same direct, Paseo and supported Podman execution boundaries used elsewhere in AEH.

## Deterministic failures are evidence

The lead must not silently reinterpret a failing validator as harmless environment noise. Audit reports classify failed checks when possible as:

```text
ASSERTION_FAILURE
ENVIRONMENT_FAILURE
SANDBOX_DENIAL
MISSING_DEPENDENCY
TOOL_FAILURE
```

For example:

```text
spawnSync git EPERM: operation not permitted
  -> SANDBOX_DENIAL
```

That classification does not pretend the affected test passed. The audit remains `DEGRADED` and `productionSafe=false` when a deterministic failure prevents establishing correctness.

## AuditReport

Reports are machine-readable local artifacts:

```text
.harness/audits/<auditId>.json
.harness/audits/latest.json
```

An AuditReport contains:

- frozen controller SHA;
- audited commit/base ref and pre-existing dirty paths;
- deterministic checks plus failure classes;
- reviewer sessions;
- normalized/deduplicated findings;
- severity counts;
- integer DebtPoints and displayed DebtScore;
- Final Quality Gate evaluation;
- conservative `productionSafe` status;
- any paths restored by the read-only rollback boundary.

Audit artifacts are generated state and are gitignored by `aeh init`.

## Audit to remediation

AUDIT itself does not edit files or auto-remediate. If the user later says:

```text
fix these
fix all findings
implement the audit recommendations
```

the persistent lead reads `.harness/audits/latest.json` and the referenced report, reuses the normalized findings as evidence for a new `CHANGE`, and performs normal deterministic change triage.

```text
AuditReport
    |
    v
new CHANGE request
    |
    v
QUICK | SPEC
    |
    v
sealed implementation workflow
```

The audit result does not override safety policy. Security, architecture, schema, public API, cross-module or otherwise unsafe findings still force SPEC when normal change triage requires it.

## Paseo behavior

`aeh start` now writes bootstrap version 2. Existing v0.5.1 lead sessions are intentionally incompatible and are recreated/replaced on the next start so the old broad read-only bypass cannot persist.

The standing interactive invariant is now:

> Every engineering operation must enter through the Harness, whether read-only or mutating. Only purely informational questions may bypass AEH.

Consequently this prompt:

```text
review the repo and validate the code for improvements
```

must route to `aeh audit`; the lead must not answer that it skipped AEH because the work is read-only.

## Control-plane freeze

Self-hosted AEH snapshots now explicitly include `src/audit` and `src/paseo` in the controller trust boundary. Audit policy and the interactive routing code therefore cannot modify themselves and take effect inside the same active audit/run; changes govern only a later invocation after validation.
