bcquality/custom/knowledge/architecture/feature-branch-must-merge-to-track-branch.md

name	title	category	severity
feature-branch-must-merge-to-track-branch	Feature branches must merge into the project's declared track branch	architecture	required

Feature branches must merge into the project's declared track branch

Rule

When a project declares a track branch in CLAUDE.md, all feature branches MUST merge into that track branch — not into main directly. main is reserved for releases and hotfixes.

Track branch declaration

The track branch is declared once in CLAUDE.md:

# Declares the integration target for this development sprint/module
trackBranch: purchase

If no trackBranch is declared, main is the default and feature branches merge there directly.

Why

In multi-module or multi-sprint projects, a named track branch acts as an integration buffer:

Without track branch	With track branch
Every feature branch merges to main	Features collect on track branch
main accumulates partial, in-flight work	main stays clean for hotfixes
A hotfix requires reverting or cherry-picking	A hotfix branches from main unaffected

The rule protects the invariant: main is deployable at any moment.

Merge requirements

1. Feature branch must compile and pass before merge
2. Merge uses --no-ff to preserve branch history in the log
3. After merge: BC dev status is set to Done (see [[git-lifecycle-must-sync-bc-status]])

The branching model

main
 └── <track-branch>          (e.g. "purchase" — lives for one sprint/module)
       └── feature/<name>    ← development happens here
       └── feature/<name>
       └── bugfix/<name>
 └── hotfix/<name>           ← branches from main, merges back to main

At release: track-branch → main (via PR, after full QA).

Non-compliant

# Merging a feature directly to main when a track branch is declared in CLAUDE.md
git checkout main
git merge feature/my-feature   # violates rule

Compliant

# Read track branch from CLAUDE.md → merge there
git checkout purchase
git merge --no-ff feature/my-feature
# Then sync BC: gitHubDevStatus = "Done"

Scope

Applies to every CURABIS project with a trackBranch declaration in CLAUDE.md. Projects without a declaration use main as the track branch — no change needed.