Git ref leases
What this is
Section titled “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
Section titled “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
Section titled “Canonical design”The full design is maintained as Markdown in the repository, not on this site.
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. Nothing keeps a precis here in sync with those files, so this page stays a pointer.