---
status: accepted
date: 2026-05-03
decision-makers: [janpetervisser]
---

# ADR-0003: One branch per milestone, push only after user test

## Context and Problem Statement

Every `git push` to a feature branch triggers a Vercel preview deployment. On the Hobby plan, preview builds are limited and cost money. How should we structure branches and pushes to minimize preview-build spend while still supporting a fast AI-driven development loop?

## Decision Drivers

- Vercel Hobby plan: preview builds are finite and billed per deployment.
- Small team (primarily solo developer + AI agent): branch overhead should be minimal.
- AI-driven flow: the agent commits frequently in small logical layers; we don't want a push per commit.
- User acceptance is done interactively per milestone, not per story.

## Considered Options

- **Branch per story** — one branch per story, PR per story.
- **Branch per milestone** — one branch for all stories in a milestone, single PR after user test.
- **Trunk-based development** — commit directly to `main` with feature flags.

## Decision Outcome

Chosen option: **Branch per milestone**, because it is the only option that keeps preview-build count proportional to milestones (not stories), while still enabling isolated review via a single PR.

### Consequences

- Good, because preview deployments are rare — only one per milestone reaching review.
- Good, because PR history maps to milestones, not micro-stories.
- Bad, because branches live longer; merge conflicts are larger but less frequent.
- Bad, because a single failed story blocks the milestone PR.

### Confirmation

Before pushing, the developer/agent must confirm explicitly. `git push` is never automated. See `docs/runbooks/branch-and-commit.md`.

## Pros and Cons of the Options

### Branch per story

- Good, because small, focused PRs are easy to review.
- Bad, because each push triggers a preview build — N stories = N builds per milestone.

### Branch per milestone

- Good, because minimal preview builds.
- Good, because the PR represents a coherent feature set.
- Bad, because long-lived branches.

### Trunk-based development

- Good, because no branch management overhead.
- Bad, because requires feature flags to hide incomplete work — too much infrastructure for this scale.

## More Information

Revisit this decision if/when the Vercel account upgrades to Pro (unlimited preview builds). At that point, branch-per-story is the preferred default. Update `docs/runbooks/branch-and-commit.md` and this ADR when that happens.