.claude/BRANCHING.md

@@ -71,8 +71,14 @@ correct" rather than erroring.
    is a divergence to reconcile deliberately, not to overwrite.
 2. **`dev` is the default branch.**
    `forge_repo_settings(apply_flow_defaults=true)` — sets the default branch and
-   permits every merge style the chain uses, including `fast-forward-only`, plus
-   rebase-updates (without which the merge queue's core primitive 403s).
+   permits the merge styles the chain uses, plus rebase-updates (without which
+   the merge queue's core primitive 403s).
+
+   The chain uses exactly two: **squash** for `feat/*` → `dev`, and
+   **fast-forward-only** for both promotions. Merge commits and rebase merges
+   are disabled deliberately — see the merge-style table in the root
+   `CLAUDE.md`. If `apply_flow_defaults` re-enables them, that is the tool
+   disagreeing with the policy, not permission to use them.
 3. **Protection.** `forge_branch_protection(branch="dev", apply=true)`, then
    `main`, then `release`.
 

.forgejo/workflows/pr-build.yml

@@ -19,7 +19,7 @@ name: PR build (required check)
 
 on:
   pull_request:
-    branches: [dev, main]
+    branches: [dev, main, release]
 
 concurrency:
   group: pr-build-${{ github.event.pull_request.number }}

CLAUDE.md

@@ -22,6 +22,21 @@ every change, so a stale one is a correctness bug, not a documentation bug.
 `dev`, `main` and `release` are protected: **everything is a PR**, for humans and
 agents alike. Promotion is one PR per hop, `dev` → `main` → `release`.
 
+**Merge style is part of the contract**, and Forgejo enforces it repo-wide —
+it cannot scope styles per branch, so these are the only two enabled:
+
+| Hop | Style |
+|---|---|
+| `feat/*` → `dev` | **squash** |
+| `dev` → `main`, `main` → `release` | **fast-forward only** |
+
+Merge commits and rebase merges are disabled. A promotion therefore never
+creates a commit, which keeps `release ⊆ main ⊆ dev` true permanently: the
+three branches hold identical history, never merely identical trees. Squashing
+into `main` instead would strand `merge-base(dev, main)` and make every later
+promotion re-apply work already there. Rebase-*updates* stay enabled — the
+merge queue 403s without them.
+
 `.claude/BRANCHING.md` is the orchestrator's runbook for that flow — the
 serialised merge queue, promotions, hotfix down-merges — and
 `.claude/ownership.md` is the module map saying which tasks may run