View project on GitHub

ADR-055: Repository Runtime Reconciler

Context

ADR-050 makes the repository the symbolic substrate for autonomous work: work units, claims, protocols, evidence, and accepted results live in git. ADR-051 plans the operator experience, ADR-052 defines verifier policy, and ADR-053/054 plan volunteer-scale coordination and identity.

The next missing piece is the runtime loop. Today the repo is reconciled by a mix of GitHub Actions, agent scripts, reapers, generated-artifact refreshers, and human intervention. That works, but it is not yet named as a coherent component. In a repo-as-OS architecture, something must observe symbolic state, derive required actions, execute those actions through adapters, and write evidence back.

That component is the repository runtime reconciler.

WH(Y) Decision Statement

In the context of unsorry treating repository state as the canonical symbolic world for autonomous work,

facing a fragmented runtime where multiple scripts and workflows reconcile pieces of state without a single contract for observe/plan/apply/verify/evidence,

we decided for defining a Repository Runtime Reconciler: an idempotent runtime role that watches repository state and live coordination events, computes desired actions, invokes domain adapters and infrastructure actions, checks verifier policy, and writes outcomes back as PRs, commits, generated status, or evidence records; the reconciler may be implemented by GitHub Actions, local workers, scheduled jobs, or future services, but it must obey the same contract and must not bypass protected-trunk or verifier gates,

and neglected treating every workflow as a one-off script forever (rejected because operators need a common mental model), letting the reconciler commit arbitrary changes directly to trunk (rejected because protected trunk and gates remain authoritative), and making the reconciler a hidden service whose state is not reflected in the repository (rejected because it breaks auditability),

to achieve a clear runtime model for repo-as-OS projects where symbolic state is continuously reconciled into verified repository transitions,

accepting that the first implementation remains distributed across existing scripts and workflows, and that this ADR names the contract before a single binary or service exists.

Reconciler Loop

observe repository + live events
-> plan state transitions
-> acquire lease / authority
-> execute adapter action
-> verify according to ADR-052
-> submit PR or evidence
-> update generated status
-> repeat

All steps must be safe to retry.

Safety Rules

• The reconciler must not treat local state as canonical.
• It must not bypass verifier gates.
• It must write durable evidence for externally visible actions.
• It must expose degraded state when it cannot reconcile.
• It must keep human emergency pause paths available.

References

Status History