rdbms-playground/docs/adr/0059-dev-workflow.md

# ADR-0059: Branch-and-PR working method — worktrees, merge commits, and reserve-first ADR numbering

## Status

Accepted — **2026-06-23**, on branch `chore/dev-workflow` (pending merge).
Number **0059**, the second ADR reserved via the reserve-first flow this
ADR itself defines (the first was ADR-0058). Updates the **Numbering
discipline** section of **ADR-0000** (supersedes its placeholder-until-merge
default with reserve-first). Does not affect the subproject ADR namespaces
(`docs/website/adr/`, `docs/ci/adr/`).

## Context

The repository is now public, and feature work is moving from
commit-straight-to-`main` toward branches. A public, multi-branch project
needs a written, trackable working method instead of ad-hoc habits.

The sharp edge that forced the issue is **ADR numbering**. ADR numbers are
a single global integer sequence; two branches that each grab "the next
number" collide on merge (this happened, and was the original motivation
for ADR-0000's numbering rules). The deeper problem is fundamental:

> A contiguous integer requires a single allocator. Plain git branches have
> **no shared allocator** until they reconverge at merge — so any number
> claimed independently on a branch is speculative and can collide.

Earlier work papered over this for two long-lived subprojects by giving
them their **own namespaces** (`ADR-website-NNN`, `ADR-ci-NNN`), which is
right for a nameable body of decisions but doesn't generalise to every
feature branch. ADR-0000 also wrote a **placeholder-until-merge** default
("assign the number at merge"), but it had never actually been exercised,
and exercising it revealed two fatal frictions:

1. **ADR numbers are referenced from the first commit onward** — in commit
   messages (which are immutable under our no-rewrite rule, so a wrong
   number there is wrong *forever*), in other ADRs, in the PR. A number
   that only crystallises at merge leaves every earlier reference dangling.
2. ADRs are *not* low-collision in practice: they're born precisely on the
   **long-lived feature branches most likely to run in parallel**, so
   "rare collision" is not a safe assumption.

So the requirement is a number that is **stable from creation, contiguous,
and collision-free** — which is only possible by acquiring a lock *up
front*. The insight that unlocks it: **`main` is the registry and an atomic
`git push` is the lock** — git serialises ref updates, so a push is a
compare-and-swap. We just have to acquire it *before* referencing the
number, not at merge.

This is a **genuine-choice** area (reasonable practitioners run GitHub
Flow, Git Flow, trunk-based, etc.); the decisions below adapt mainstream
practice to this repo's constraints (append-only history, self-hosted
Gitea, solo-with-subagents development) rather than claiming a canonical
default.

## Decision

### D1 — Everything lands via a PR onto a protected `main`

`main` is always-green and protected; no direct pushes (one narrow
exception — D4). Every change is a branch + pull request onto `main`. One
logical change per branch/PR. Branch names carry a conventional prefix
(`feat/ fix/ docs/ chore/ refactor/ test/ ci/`) aligned with the commit
type. PRs reference their issue (`Closes #N`); the review we already
perform (the Devil's-Advocate / `/runda` pass) is pasted into the PR so the
public repo carries the audit trail.

### D2 — One worktree per branch (never switch the primary checkout)

Each branch is developed in its **own git worktree**, a sibling of the
primary checkout named `<repo>-worktree-<last-segment-of-branch>` (the
convention already in use for the `website` and `ci` worktrees). Switching
the primary checkout's branch while another shell sits in the same
directory is how work gets clobbered — worktrees make that impossible.
Helpers:

- **`scripts/wt-new.sh <branch>`** — fetch `main`, create the branch off
  `origin/main` (with `--no-track`, so it doesn't inherit `origin/main` as
  upstream — otherwise a bare `git push` errors on the name mismatch and
  suggests the dangerous `HEAD:main`), and add the sibling worktree; prints
  its path. First push is `git push -u origin <branch>`.
- **`scripts/wt-rm.sh <branch>`** — remove the worktree for the **named**
  branch, and nothing else. It does **not** scan for "merged" worktrees to
  auto-remove: long-lived branches (`website`, the `ci` line) are merged
  into `main` too, so a merged-detection sweep would wrongly delete them
  (caught immediately on review, before any real use — the initial design
  was an auto-sweep `wt-clean`). Naming the target is the safety. Git's own
  refusals do the rest: it won't remove a dirty worktree (no `--force`),
  and it deletes the local branch only if it is merged into `origin/main`
  (otherwise the worktree goes but the branch + its unmerged commits stay).
  Stale bookkeeping for a hand-deleted directory is the built-in
  `git worktree prune`'s job.

### D3 — Merge commits (`--no-ff`); never rebase or squash

Branches land with a **merge commit** (`--no-ff`). This is the only
strategy consistent with the project's append-only / no-history-rewrite
rule: squash and rebase-merge both rewrite history. Fast-forward-only is
out because it would require rebasing branches onto `main`. History gains
merge bubbles; that is the accepted cost of never rewriting.

### D4 — Reserve-first ADR numbering via `adr-reserve.sh`

ADR numbers are **reserved up front, the moment you know an ADR is
needed** — which may be mid-branch or late, so reservation is decoupled
from branch creation. `scripts/adr-reserve.sh <slug> [title]`:

1. reads an append-only ledger (`docs/adr/RESERVATIONS.log`) plus the
   existing `NNNN-*.md` ADRs on `main`; next = highest + 1;
2. appends `<NNNN> <slug> <date> <title>`, commits, and **pushes to
   `main`**;
3. if the push is rejected because `main` moved (someone reserved first),
   it re-fetches, recomputes, and retries — the push is the compare-and-swap,
   so allocations are unique by construction, not by luck.

It runs from any branch/worktree without touching the working tree (it does
the allocation in a throwaway worktree on a detached `origin/main`), and on
a *non-race* rejection (e.g. protection misconfigured) it **aborts loudly**
rather than spinning. The number is therefore **stable from the moment it
returns** — safe to cite in immutable commit messages and other ADRs from
the first commit, which is what the references-problem (Context) demands.

The ADR file is created as `docs/adr/NNNN-<slug>.md` in the working branch
and its README index row is added there as normal work; the ledger line on
`main` is the allocation record and never conflicts with feature work
(feature branches don't touch it). The ledger may be pruned later; it's a
lock record, not state. **Collisions** (two reservations in the same
instant) are resolved automatically by the retry; the README index edit is
a secondary tripwire if one ever slips through.

This **supersedes ADR-0000's placeholder-until-merge default.** Subproject
namespaces (`ADR-website-NNN`, `ADR-ci-NNN`) are unchanged — they solve a
different problem (a nameable long-lived body of decisions) and stay.

### D5 — Branch protection configuration

On `main` (Gitea → Settings → Branches):

- **Require pull requests** + **require the CI status check** (`ci / gate*`)
  to pass before merge, and **block merge of out-of-date branches** (this
  is what makes "`main` is the lock" airtight for the substantive merges).
- **Whitelist the repo owner for direct push.** This is the one narrow
  carve-out that lets `adr-reserve.sh` push the append-only ledger line
  directly; everything substantive still goes through a PR. Without it the
  reserve script aborts with a clear "is the owner whitelisted?" message.

### D6 — Who does what

**Pushing and merging are human steps**; automated agents prepare branches,
edits, PR text, and commit-message proposals but never push or merge. The
reserve script is **run by the human** (so the ledger push originates from
the human's invocation, consistent with that rule) — agents may write and
test the script but not run its pushing path.

## Forks (all user-chosen, 2026-06-22/23)

- **Merge commits (`--no-ff`)** over squash or fast-forward-only — the only
  option consistent with append-only history (D3).
- **Strict everything-via-PR** over allowing trivial direct commits — one
  carve-out only, the reservation line (D1/D4/D5).
- **Branch protection enforced in Gitea** over convention-only — mechanical
  guarantee for a public repo (D5).
- **Reserve-first contiguous integers** over: number-on-merge (rejected —
  breaks immutable references), Gitea-issue-number ids (rejected — non-
  contiguous, overlaps the legacy 0001–0057 range), or an allocator bot
  (rejected — machinery + a PR-rule exemption). Reserve-first keeps the
  short stable "ADR 0059" reference and needs no new infrastructure beyond
  one script (D4).
- **Worktrees prescribed** over single-checkout branch switching — prevents
  the same-directory clobber hazard (D2).

## Consequences

- A written, public-facing **`CONTRIBUTING.md`** (lean: setup, the CI gate,
  branch/PR conventions, the user-facing copy rules, "significant changes
  get an ADR"). The maintainer-facing mechanics (worktrees, the reserve
  lock, the whitelist) live here and in `CLAUDE.md`, not in CONTRIBUTING.
- Three scripts enter `scripts/`: `adr-reserve.sh`, `wt-new.sh`,
  `wt-rm.sh`, each with a local-`origin` test harness
  (`test-adr-reserve.sh`, `test-wt.sh`) — the reserve script's allocation,
  idempotence, race-retry discriminator, and hard-abort paths are all
  covered (the real-remote push is exercised by the human running it).
- `docs/adr/RESERVATIONS.log` appears on `main` as the allocation ledger.
- ADR-0000's Numbering-discipline section is updated to point here.
- `CLAUDE.md` gains the operational rules an agent must follow.

## Out of scope

- **Migrating the legacy `0001–0057` ADRs** to any new scheme — they keep
  their numbers; reserve-first applies going forward (next is `0060`).
- **Automating PR creation/merge** — humans push and merge (D6).
- **A CONTRIBUTING-side description of the reserve lock** — it's maintainer
  infrastructure, not contributor guidance (kept here instead).

## Amendment 1 (2026-06-25): docs direct-push carve-out

Extends the D5 owner-whitelist: **handoff / session docs (and small docs
amendments like this one) are owner-direct-pushed to `main`, not PR'd.**

Discovered while preparing the first handoff under this flow: a **docs-only
PR cannot merge** under the protection rules. `ci.yaml` `paths-ignore`s
`docs/**` and `**/*.md`, so a docs-only change posts **no `ci / gate` run**;
but D5 requires `ci / gate*` before merge — so the required check never
arrives and the PR stalls on "expected/waiting". Rather than weaken the gate
or add CI machinery, this trivial low-risk class (handoffs, session notes,
small docs fixes) rides the existing owner-direct-push carve-out: the owner
is already whitelisted, and a docs-only push to `main` is itself
`paths-ignore`d, so it burns no CI.

Substantive changes — code, and the ADRs/docs that accompany code — still go
through a PR as normal (their non-docs files trigger the gate). **If
docs-via-PR is ever wanted** (e.g. a docs-only ADR through review), the clean
fix is a "skipped → success" gate shim (a job that reports `ci / gate`
success when the real gate is path-skipped) or dropping the docs
`paths-ignore`; until then, direct-push is the sanctioned path for docs-only
changes.