ADR 0001: GitHub as the source of truth

Status

Accepted.

Context

The workflow spans agents running on different machines, on Claude, Codex, and pi.dev hosts, with no shared process between them. It has to survive a reviewer crashing mid-review, avoid inventing a queue or database, and stay auditable by a human without a custom dashboard.

Decision

GitHub itself holds every piece of workflow state, across exactly three states. Requested is the ai-review trigger label plus a native requested-reviewer entry, set by review.create through GitHub's requestReviewers API. Claimed is a structured claim-marker comment, <!-- agent-review:claim {"v":1,"reviewer":...,"sha":...,"claimedAt":...} --> (core/claim-marker.ts), posted by review.claim (core/operations/claim.ts); it pins the head SHA at claim time and is the sole record of in-progress work, so a restarted agent re-reads PR comments and resumes its own marker instead of losing or duplicating the claim. Done is a native PR review submitted by review.complete (core/operations/complete.ts) with commit_id set to that pinned SHA; submitting the review natively clears the requested-reviewer entry, so no terminal label or extra call is needed, and the agent then deletes its own marker.

Consequences

Restart-safe by construction, with no queue or database to keep in sync with reality, and every transition stays visible in the ordinary GitHub PR UI. The cost is bounded by GitHub itself: listing work relies on the search API and its eventual consistency, and claim races are resolved by comparing timestamps and comment ids rather than a true lock (see ADR 0004).