# ADR 0001: Tracer-first, file-backed certification

## Status

Accepted; branch-protection requirements removed by operator decision on 2026-07-12.

## Context

OMS must coordinate ticket work for long periods without becoming a second agent runtime. Its decisions must survive process restarts, remain auditable, and fail closed when execution, verification, quota, remote-identity, or provider evidence is missing. A background service or database would add another authority before the file-backed tracer has proved insufficient.

Release certification also needs evidence from real elapsed operation. Fast-forwarded clocks, mocked timers, and a model's claim that a run completed cannot certify endurance.

## Decision

OMS is tracer-first. One ticket is followed through its durable lifecycle, and each consequential transition is justified by immutable, schema-validated evidence stored under the runtime root.

V1 uses tracked JSON policy and file-backed runtime records. It adds no daemon and no database. Native completion hooks and outbox events drive normal progress; the 15-minute heartbeat and watchdog are recovery mechanisms only. Recovery stops after two unsuccessful heartbeats and requires operator attention.

Merges remain human-held. Automatic merge is disabled and OMS exposes no merge or ready-for-review mutation. Server-side branch protection is not an OMS dependency; repository administrators remain responsible for any controls outside OMS.

Release certification requires manually attested, real elapsed canaries in this order: a 12-hour run, followed by a fresh 24-hour run. The 24-hour canary cannot reuse the 12-hour process, session, lease, or elapsed-time claim.

## Alternatives

- A custom orchestration daemon was rejected because native hooks and one-shot commands cover normal flow while a heartbeat covers recovery.
- A database-backed queue was rejected because atomic, locked file records are sufficient for the current single-host boundary and are easier to audit and recover.
- Polling as the normal execution path was rejected because it duplicates native completion signals and makes latency and failure ownership less clear.
- Automatic merge after deterministic checks was rejected because verification success alone does not prove human review authority, provenance, or endurance certification.
- Simulated or accelerated canaries were rejected because they do not demonstrate real quota windows, process recovery, or elapsed-time stability.

## Consequences

Runtime behavior remains inspectable with ordinary file and Git tools, and each release claim can be traced to immutable evidence. Normal operation does not depend on a resident OMS process. Deterministic recovery is deliberately bounded and may park work for human review instead of guessing.

This design accepts lower throughput and manual merge latency in exchange for a smaller authority surface. OMS itself refuses force-push and merge operations, but without server-side branch protection it cannot prevent repository administrators or other credentials from changing remote history. File-backed coordination remains limited to the reviewed single-host concurrency model; evidence compaction or distributed coordination would require a new decision.

## Follow-ups

- Run and manually attest a real elapsed 12-hour canary.
- Start a fresh run and manually attest a real elapsed 24-hour canary only after the 12-hour canary passes.
- Revisit a daemon, database, or automatic merge only through a superseding ADR backed by observed tracer limitations and new deterministic gates.