# Branching Rules

**Configured merge model: `{{merge_model}}`.** Under `wave-branch`, feature work
integrates through a shared integration branch per wave and only the wave rollup
reaches `{{default_branch}}`. Under `direct-to-main`, feature branches PR straight
into `{{default_branch}}`; the integration-branch sections below then collapse to
"base = `{{default_branch}}`" and the same feature-branch and worktree rules apply.

## Integration (Wave) Branches

Work is organized into **waves** of parallel tasks. Before starting a wave, create
an integration branch from the latest `{{default_branch}}`:

```
{{integration_branch_scheme}}
```

- **All feature branches for the wave PR into the integration branch** — not into
  `{{default_branch}}`.
- At the end of the wave/phase, PR the integration branch into `{{default_branch}}`.
  **Wait for the project owner to approve that merge** before proceeding.

## Feature Branches

- Branch naming scheme: `{{feature_branch_scheme}}` — the branch carries the team
  member's identity and the issue number. **No branch may be created without an
  existing issue** (see [issues.md](issues.md)).
- All feature branches are created from the **current integration branch** for their
  wave, pulled fresh:
  ```bash
  git fetch origin && git checkout -b <feature-branch> origin/<integration-branch>
  ```
- **Branch safety:** before every commit, run `git branch --show-current` and confirm
  you are on your own branch. Never commit to another member's branch.
- **Before submitting a PR**, merge the latest integration branch into your feature
  branch and resolve conflicts:
  ```bash
  git fetch origin && git merge origin/<integration-branch>
  ```

## Worktree Isolation

**Every code-writing agent works in its own git worktree.** The orchestrator creates
it from the main checkout before spawning:

```bash
git -C <main-repo> worktree add <path> -b <branch> origin/<base>
```

- Agents MUST NOT run a bare `git checkout` / `git checkout -B` in the **main repo
  checkout** — it moves the shared HEAD, corrupts sibling worktrees, and lands the
  orchestrator's own commits on the wrong branch. Always go through `worktree add`.
  (`git -C <other-path> checkout` redirected to a different repo, and pathspec
  restores like `git checkout -- <file>`, are fine.)
- An agent never removes the worktree it is standing in (enforced — see
  [hooks.md](hooks.md)).

## Worktree Cleanup

**After every wave completes** (all PRs merged into the integration branch), clean
up stale worktrees from the main checkout:

```bash
git worktree prune
```

Without this, branches used by deleted worktrees remain locked and cannot be checked
out. The orchestrator runs it after shutting down the wave's agents and before
creating the next wave's integration branch.

## Releases

When an integration branch is merged into `{{default_branch}}`, create a release
tagged with the branch name (slashes → hyphens), title = tag, notes = summary of the
wave's work. Release creation requires the project owner's approval (see
[charter.md § Ground Rules](charter.md)).
