Git ref leases

What this is

A distributed coordination protocol for SDLC workflows. Git refs under a reserved refs/sdlc/… namespace are the distributed lease primitive; compare-and-swap updates via --force-with-lease provide atomic claim, renew, steal, and release. The configured ref authority (a GitHub remote, another Git server, or a local bare repo) is the source of truth.

The protocol is harness-agnostic: any worker — Claude Code, another agent, a CLI, a GitHub Action — can participate by following the same deterministic protocol against the same refs.

The lease ref is authoritative for task claims. A task’s status: frontmatter is a workflow cache of the same fact; the ref at refs/sdlc/tasks/<id> is the truth two racing operators resolve against (see Data model).

The lease op surface

The lease capability lives in the registry as a services/lease op family (solutions/ontological/lib/services/lease/). The ops are hidden plumbing — absent from sdlc --help, revealed by --help --advanced, and reached directly by skills and lefthook. The noun nests on two axes (D-H7FS-op-substrate-surface §2):

Path	Role
lease task claim · acquire · reacquire · transition · fence · archive	the task-lifecycle leases skills drive through pickup, work, review
lease op claim	a fresh operation lease (CAS-CREATE)
lease heartbeat / lease heartbeat-loop	bump expires_at; the loop is a defineService lifecycle that keeps a lease alive while a task runs
lease list · inspect · reconcile · parse-footer · release · migrate	enumerate, render, detect anomalies, read a PR footer, archive-then-delete, one-shot cutover

heartbeat (a single CAS round-trip op) is deliberately distinct from heartbeat-loop (a non-returning service) — a loop can’t be a plain op without hanging invokeOp (see Harness-agnostic). Every lease op resolves when addressed directly; see the Ops reference for the full list.

Canonical design

The full design is maintained as Markdown in the repository, not on this site. Past versions of this page tried to be a self-contained precis and went stale; pointing at the source-of-truth files avoids that.

• docs/planning/decisions/github-ref-leases/README.md — overview, core ideas, reading guide, cross-cutting decisions log.
• docs/planning/decisions/github-ref-leases/protocol.md — the main spec: ref operation primitives, lease schemas, control plane, lifecycle (Model B), fencing, follow-up convention, security model.
• docs/planning/decisions/github-ref-leases/distributed-participation.md — how independent workers participate against a shared ref authority.
• docs/planning/decisions/github-ref-leases/offline-mode.md — offline-speculative mechanics: local ref namespaces, branch naming, reconnect/publish algorithm, partition timing.
• docs/planning/decisions/github-ref-leases/reference.md — the condensed reference for the protocol’s primitives and schemas.

Start with the README. It carries a recommended reading order, a roll-up of cross-cutting decisions, and a list of expansion areas.

Why a pointer rather than a copy

Earlier versions inlined a precis of the design. Every revision to the canonical docs left this page stale, with no mechanism keeping the two in sync. The refs/heads/sdlc/... → refs/sdlc/... namespace move, the schema collapse (schema_version + lease_protocol_version → sdlc_version), and the lifecycle commitment (Model B) all silently diverged here. Pointing at the canonical files — and at the generated Ops reference for the surface — keeps the site honest.