Skip to content

ADR 0001: Harness evidence plane

  • Status: Accepted
  • Ticket: FLT-166
  • Date: 2026-07-20

Context

Fleet Harness currently routes work, executes agents, validates their output, and holds work for human approval. Its logs are useful operationally, but they do not form a versioned record that can reconstruct why a run was considered safe. Agent claims, reviewer consensus, capacity observations, and host measurements must not be treated as interchangeable evidence.

Decision

Add an append-only evidence plane beside the existing control plane. This ADR defines contracts only; it does not change routing, execution, validation, or the human gate.

Authority boundaries

State Authority
Requirements, acceptance, and business status Jira ticket and revision
Source, branch, worktree, and landed revision Git
Provider admission and capacity Usage Governor observation at dispatch
What ran and what was measured Append-only harness evidence
Whether work may land Existing human approval gate
BOARD.md and Vikunja Derived projections; never independent authority
Agent claims and council consensus Untrusted inputs; never validation

Every evidence event belongs to a runId and records its schema version. Evidence is written atomically and append-only. Artifacts may live outside the event stream, but are addressed by SHA-256 and protected by the same retention policy.

Data flow

  1. Fleet Harness snapshots the ticket revision, repository state, configuration, and governor capacity at dispatch.
  2. Routing, attempts, reviews, verification, and the human decision emit events.
  3. Agent statements enter claims; host-observed command results enter measurements. Neither collection is inferred from the other.
  4. Verification scopes state both proves and doesNotProve. A missing oracle is unverified, never passed.
  5. An evidence packet is sealed with artifact hashes and presented at the existing human gate. Approval remains necessary even when every automated check passes.

Safety invariants

  • UNKNOWN capacity and stale observations derive UNKNOWN, never HEALTHY.
  • Reviewer or multi-model consensus is review evidence, never validation.
  • Validation is backed by a named oracle and measurement.
  • Every passed verification scope declares limitations.
  • Claims and measurements are stored in separate required collections.
  • Published schema versions are immutable and reject unknown fields. Any shape change, including an additive field, requires a new version plus migration and read compatibility. This keeps evidence writers from smuggling unreviewed data through permissive extension points.

Security and privacy

Evidence is metadata-first. Secrets, credentials, raw environment dumps, and unredacted prompts are prohibited. Sensitive outputs are stored in an access- controlled artifact store and referenced by hash. Writers receive append-only authority; readers and approval actors receive least privilege. Retention and redaction happen before persistence, and audit records identify the requesting ticket, run, actor, machine, and capability bundle.

Compatibility and rollout

harness-run/v1 and verification-scope/v1 are sidecar contracts. Existing APIs, CLI output, routing semantics, provider access, SSH workflows, validation, and approval behavior remain unchanged. Instrumentation begins shadow-only. It may become required only after golden-ticket tests demonstrate equivalent outcomes and acceptable latency. Failure to write evidence must fail closed for a future secured lane, but remains observable and non-blocking during shadow rollout.

Consequences

Runs become reconstructable and harness changes can be regression-tested. Storage, redaction, schema migration, and drift auditing become explicit maintenance work. The design deliberately does not make consensus an oracle or replace Andrew's approval authority.