Skip to main content

​
ADR 0198: Keep delivery-line proofs as repository commands

Orbit proves reproduction, task-group shape, pull-request head review, and post-merge live state with four read-only repository commands. The commands reuse existing task fields and fails_on_base. They add no proof field on a subtask.

​
Status

In progress. Principle: Deterministic first.

​
Context

BugBot, the merge reviewer, and OpsBot each need a yes-or-no result they can paste. Orbit already has the task engine’s fails_on_base run, CreateTaskGroupRequest rules, the merge skill’s review and leftover rules, and the live /up plus gateway-status checks recorded in ops verified-merges. A new deliverable type, a new Gateway endpoint, or a proof field on a subtask would create a second contract beside those rules. The Orbit Tasks policy forbids proof fields on subtasks. bin/review-check, the Project task check, and doctor already print one structured result, refuse to mutate what they inspect, and say what to do next on failure.

​
Decision

Ship four repository commands that print one JSON object, exit nonzero on failure, and keep side effects behind --dry-run: The commands do not file a task, merge, deploy, or roll back. Instance rollback stays the production-code selector. It is not OpsBot’s production rollback after a bad deploy. bin/bug-repro names current main only when the local origin/main or main SHA matches git ls-remote origin main. It does not fetch. A cached ref that differs is main_stale. bin/deploy-verify tells the operator to set SSL_CERT_FILE to Orbit’s root CA when HTTPS fails certificate verification. An unreachable result from one machine is not a reason to change the live checks. bin/pr-head-check flattens both a bare check-runs object and the one-element array gh api --paginate --slurp wraps around it. It omits --slurp on older gh that do not have the flag. It keeps a review only when its state is APPROVED and its commit_id equals the current full head SHA. COMMENTED, CHANGES_REQUESTED, DISMISSED, and PENDING do not count. The leftover scan skips the detector, the leftover-refusal test, and recorded delivery-line fixtures. A leftover added in product code still fails. This repository does not wake ReviewBot when a GitHub pull_request_review event arrives without a new push; wiring that wake is a follow-up. A review event never bypasses bin/pr-head-check: an APPROVED review and successful Required checks must still match the exact current head.

​
Rejected alternatives

  • A proof field on a subtask: the Orbit Tasks policy forbids it, and fails_on_base already names the failing command.
  • A new CLI or Gateway framework for proofs: bin/review-check and the task check already own this style.
  • Wiring instance:rollback into bin/deploy-verify: a rollback selects one retained release and does not undo deploy steps, environment writes, or data.

​
Consequences

  • BugBot can reproduce on current main without creating a task.
  • Operators can validate a group before tasks-create.
  • A merge reviewer can refuse a stale head without merging.
  • OpsBot can verify a deploy from the same three checks recorded in ops verified-merges, or from a recorded fixture when production is unreachable.

​
Affects

  • Components: apps/e2e
  • ADRs: none
  • Detail: Delivery-line proofs
  • Verify: bin/bug-repro --help; the four command test files; a real JSON result from each command