Add three-branch support to Makefile.agents.mk

[sebastientaggart]

Summary

Makefile.agents.mk only supports trunk and two-branch workflows. It has INTEGRATION_BRANCH and PRODUCTION_BRANCH but no concept of a staging/test branch (BRANCH_TEST). Projects using the three-branch model (feature → dev → staging → main) have no Makefile targets for the promotion steps.

Background

The skills (/ship, /release, /version) already handle three-branch mode through their prompts, but the Makefile targets don't support it. This was discovered when make merge failed due to a hardcoded development default — that specific bug is fixed, but the missing three-branch support remains.

Related: the INTEGRATION_BRANCH ?= development default was a mismatch with projects using dev as their integration branch. That's been fixed by requiring consumer projects to override the variable before the include.

What needs to change

1. Add STAGING_BRANCH variable to Makefile.agents.mk

Add a new optional variable alongside the existing ones:

```makefile
INTEGRATION_BRANCH ?= development
PRODUCTION_BRANCH ?= main
STAGING_BRANCH ?= # empty = two-branch or trunk mode
FEATURE_PREFIX ?= feature/
```

2. Add promote target

A target to promote the integration branch into the staging branch. This creates a PR from INTEGRATION_BRANCH → STAGING_BRANCH:

```makefile

Promote integration branch to staging. Creates a PR: INTEGRATION_BRANCH → STAGING_BRANCH.

Only available in three-branch mode (STAGING_BRANCH is set).

promote:
ifndef STAGING_BRANCH
$(error promote requires STAGING_BRANCH to be set (three-branch mode))
endif
gh pr create --base $(STAGING_BRANCH) --head $(INTEGRATION_BRANCH)
--title "Promote $(INTEGRATION_BRANCH) → $(STAGING_BRANCH)" --fill
```

3. Update guard rails in existing targets

The pr, abandon, and merge targets check against PRODUCTION_BRANCH and INTEGRATION_BRANCH as protected branches. When STAGING_BRANCH is set, it should also be protected:

```makefile

In pr, abandon, merge targets, add STAGING_BRANCH to the guard:

if [ -n "$(STAGING_BRANCH)" ] && [ "$$branch" = "$(STAGING_BRANCH)" ]; then
echo "Error: cannot operate from $$branch."; exit 1;
fi;
```

4. Update deploy-preview semantics

In three-branch mode, deploy-preview should push the staging branch (not the integration branch), since staging is the pre-production environment:

```makefile

In consumer Makefiles:

Two-branch: deploy-preview pushes INTEGRATION_BRANCH

Three-branch: deploy-preview pushes STAGING_BRANCH

```

Document this distinction in the header comments of Makefile.agents.mk.

5. Add .PHONY declarations

Add promote to the .PHONY list.

Acceptance criteria

• STAGING_BRANCH variable added, empty by default (backwards compatible)
• promote target creates a PR from integration → staging
• promote errors clearly when STAGING_BRANCH is not set
• Protected branch guards include STAGING_BRANCH when set
• Header comments document the three-branch configuration
• Existing two-branch and trunk workflows are unaffected (no behavior change when STAGING_BRANCH is empty)

[sebastientaggart]

Resuming work. Implementing all five changes: STAGING_BRANCH variable, promote target, protected branch guards, deploy-preview semantics, and header documentation.