View project on GitHub

ADR-056: Repo-as-OS Control Plane and Operator Interface

Context

ADR-050 through ADR-055 describe a repo-as-OS architecture for autonomous work: the repository stores symbolic state, agents transform it, verifier tiers govern acceptance, claims/identity manage scale, and a reconciler applies runtime actions. What remains is the human-facing control plane.

If the repository is the symbolic operating system, the operator interface must not be a pile of disconnected scripts. It should expose the repository’s state as a coherent control surface: what work exists, what is claimed, what agents are doing, what gates are blocked, what risks are accepted, what evidence exists, and which actions are safe.

The control plane should let humans express intent and supervise automation without making them manually reconstruct state from shell commands, workflow logs, and branch history.

WH(Y) Decision Statement

In the context of unsorry evolving toward a repository-backed operating model for autonomous work,

facing the need for contributors and operators to understand and steer the system without becoming accidental system administrators of every underlying workflow, runner, lease, and verifier,

we decided for planning a Repo-as-OS Control Plane: a role-based operator interface that projects repository state, live reconciler state, claims, agents, verification tiers, evidence, incidents, and settings drift into one coherent view; operators may express high-level intent such as pause volunteer claims, inspect blocked work, approve an APPROVAL tier change, or refresh stale artifacts, but every meaningful action must resolve into a recorded repository transition, approval, or evidence event,

and neglected making the control plane the source of truth (rejected because the repository remains canonical), hiding unsafe or degraded states behind a polished dashboard (rejected because operators need honest status), and exposing raw shell/procedure as the primary interface (rejected because the goal is symbolic management),

to achieve a modern operator experience where the repository is the semantic OS and the interface is a projection plus intent surface over that state,

accepting that the first version may be generated Markdown/JSON and a lightweight dashboard rather than a full interactive product, and that control plane actions must be limited until identity, quotas, and reconciler policies are implemented.

Control Plane Layers

Initial Operator Actions

• pause or resume volunteer claiming,
• inspect live claims and stale leases,
• inspect open PRs by verifier tier,
• view blocked work and failure reasons,
• view settings drift and trust-bearing warnings,
• record approval for APPROVAL tier work,
• trigger deterministic generated-artifact refresh,
• open an incident record,
• export an evidence pack.

References

Status History