# Autonomy Completion Invariants Design

Audience: AI coding agents first.

## Goal

Make autonomous runs recover from known harness-infrastructure failures, resume durable progress, and publish terminal truth.

## Scope

- Fix nested Gate 0 fixture isolation from user-global Git hooks.
- Classify exact harness infrastructure timeout evidence before fixer dispatch.
- Regenerate terminal reports from canonical journal state.
- Prove checkpoint resume and end-to-end completion through actual launcher path.
- Do not add watchdogs, daemons, retry layers, or new persistence formats.

## Architecture

### Gate boundary

`lib/gates.sh` remains gate-output authority. Known harness timeout evidence MUST emit `FAILCLASS=infra`; assertion and compilation failures MUST remain `FAILCLASS=check-failed`.

`src/engine/gates.js` MUST route `infra` through existing `gate-red-env` deterministic repair. It MUST NOT dispatch code fixer for unchanged task diff.

### Fixture isolation

`lib/test-gates.sh` fixture repositories MUST set repository-local `core.hooksPath` to an empty fixture directory unless test explicitly installs a hook. Host-global hooks MUST NOT affect deterministic gate tests.

### Durable resume

Existing SQLite journal remains sole progress source. Restart MUST retry quarantined/skipped work while preserving landed tasks. No new checkpoint store.

### Terminal reporting

`src/daemon.js` MUST rewrite report whenever canonical lifecycle is terminal. Existing report presence MUST NOT suppress refresh. Report reducer continues deriving task state from journal and terminal summary.

## Data Flow

1. Gate captures check output and assigns fail class.
2. Runner maps `infra` to existing deterministic retry path; code fixer remains reserved for code failures.
3. Journal records landed, quarantined, skipped, restart, and terminal summary.
4. Restart reads journal and resumes only incomplete work.
5. Daemon terminal scan atomically regenerates report from latest journal.

## Error Handling

- Unknown timeout text stays fail-closed as code/unknown failure.
- Known infrastructure timeout retry exhaustion quarantines with evidence.
- Report write failure remains visible daemon failure; stale success report is forbidden.

## Testing

- RED: global hook fixture causes no-hook Gate 0 test failure; isolated fixture passes.
- RED: exact `local-gate: parse-config timed out` output maps to `infra` and bypasses fixer.
- RED: pre-existing stale report is overwritten after terminal journal entry.
- Regression: restart preserves landed tasks and retries quarantined/skipped tasks.
- Runtime: production bundle selected by `bin/runplan`; blocking plan reaches terminal completion without crash.

## Architecture Decisions

- Reuse fail taxonomy, repair ladder, SQLite journal, and report reducer. Deleting any adds duplicate state logic.
- Collapse checkpoint work into runtime verification: existing resume implementation and integration contract already cover required behavior.
- Reject new autonomy coordinator: decorative layer would not fix observed boundary failures.