From 98db4d6376c733b4e7fd251db2c005900603c122 Mon Sep 17 00:00:00 2001
From: Madhura68 <janpetervisser2@gmail.com>
Date: Sun, 3 May 2026 01:11:05 +0200
Subject: [PATCH] docs(adr): add 0003-one-branch-per-milestone

---
 docs/adr/0003-one-branch-per-milestone.md | 61 +++++++++++++++++++++++
 1 file changed, 61 insertions(+)
 create mode 100644 docs/adr/0003-one-branch-per-milestone.md

diff --git a/docs/adr/0003-one-branch-per-milestone.md b/docs/adr/0003-one-branch-per-milestone.md
new file mode 100644
index 0000000..c8f6772
--- /dev/null
+++ b/docs/adr/0003-one-branch-per-milestone.md
@@ -0,0 +1,61 @@
+---
+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.