Coding Owl is archived. It did not fulfill its core loop, so rather than pivoting or refactoring it, I am building something new from scratch with the lessons learned. Why Coding Owl is archived

ADR-0016

Rebase the Job branch onto its base at the start of every Run

Context

A Job can span several nights (ADR-0011), and its base branch moves while it does. That undermines two things at once. Verification (ADR-0013) run against a week-old base can fail for reasons that have nothing to do with the Job, and pass for reasons that will not survive contact with current code. And the diff presented for review is against a base nobody is on any more.

Decision

At the start of every Run, Owl fetches and rebases the Job’s branch onto the Project’s base branch.

The fetch updates the remote-tracking ref of the base branch, refs/remotes/<remote>/<base>, and nothing else. The rebase then targets:

  • refs/remotes/<remote>/<base> when the fetch succeeded, so that the branch is replayed onto what the remote knows rather than onto what the user last pulled;
  • refs/heads/<base>, the local base branch, when the Project has no remote or the fetch failed.

The local base branch is never moved by Owl: it is the user’s, and a fetch that reaches the remote makes the rebase independent of it.

  • Clean rebase - the Run proceeds, and Verification runs against the rebased state.
  • Conflict - git rebase --abort, and the Job moves to blocked naming the conflicting paths and the ref the rebase was onto.

The first Run of a Job has nothing to rebase; its branch is cut fresh from the base.

Consequences

  • A green Job is green against today’s base, which is the only claim worth making.
  • The review diff is linear and against current main.
  • Rebasing rewrites the commits the Agent made. Since ADR-0026 gives every Run a fresh context, nothing carries a memory of the old shas; the next Run reads the handoff document and the rebased log as it finds them. A handoff that names a sha will not resolve after a rebase, so it should describe work in prose.
  • The daemon rewrites git history unattended. That is bounded by the fact that the branch is Owl’s own, exists only for this Job, and is never pushed (ADR-0015). Owl must never rebase anything else.
  • Abort handling has to be solid: a Run must never begin on top of a worktree left mid-rebase. Garbage collection (ADR-0015) should detect and report that state rather than trying to resolve it.
  • “Conflict blocks the Job” means an active Project can block a long-running Job repeatedly. That is the honest signal, and the fix is smaller Jobs.

Alternatives considered

Merge the base in instead of rebasing. Does not rewrite the Agent’s commits, which mattered while Sessions were resumed across nights. ADR-0026 removed that concern entirely, leaving only the objection that merge commits clutter a short-lived branch that exists to be reviewed once.

Leave the branch alone. Perfectly predictable, and no unattended git operation can surprise anyone. Rejected because it makes Verification a claim about a base that no longer exists, which is the one thing the gate in ADR-0013 was added to prevent.