1---
2name: stage-branch-discipline
3description: Keep a `stage` or integration branch aligned with source PR branches and replay it safely onto the primary branch. Use when work mentions `stage`, an integration branch, stage-only fixes, replaying tested changes into `main`, refreshing stale PR branches, comparing `stage` with PR branches, or closing superseded PRs after splitting a large stage merge into reviewable replacements.
4---
5 
6# Stage Branch Discipline
7 
8## Overview
9 
10Treat `stage` as an integration branch for testing combined changes, not as a place to create a second source of truth. The healthy state is simple: every meaningful change visible on `stage` already exists in some PR branch that can merge to the primary branch. If that rule holds, promoting tested changes is mostly a matter of merge order. If it was broken, first reconstruct which PR branch each stage change belongs to, then compare `stage` against those branches and rebuild a clean merge path.
11 
12## Stage Discipline
13 
14- Do not add unique fixes directly to `stage` if they belong to a specific PR or feature branch.
15- Treat `stage` as the place where branch results are combined and tested, not as the source of truth for follow-up fixes.
16- If testing on `stage` reveals a bug in an existing PR, fix the owning PR branch first. If that branch is no longer usable, create a refreshed replacement PR from the primary branch.
17- Bring the same fix into `stage` only to keep `stage` aligned with the branch that should eventually merge.
18- Prefer “branch first, then stage” over “stage first, then reconstruct later”.
19- If this discipline is followed, `stage` should have no meaningful changes that exist only on `stage`, and the final merge should not require inventing replay logic.
20 
21## Workflow
22 
231. Inventory the delta.
24   Compare the primary branch and `stage` with `git log --first-parent`, `git log --left-right --cherry-pick`, and `git diff --stat`.
25 
262. Classify every change.
27   Separate:
28   - existing open PR branches that already target the primary branch
29   - direct commits on `stage`
30   - stage-only branches that were merged into `stage` but never opened against the primary branch
31   - commits later canceled by explicit reverts
32   Then decide which direct stage commits are legitimate one-off integration commits and which ones are process debt that should have lived in a PR branch.
33 
343. Keep the `stage -> main` or `stage -> primary` umbrella PR out of the merge path.
35   Use it only as evidence of intent. Do not merge it directly if the goal is a clean, reviewable replay onto the primary branch.
36 
374. Refresh stale branches on top of the current primary branch.
38   If an older PR no longer merges cleanly or its checks are stale, create a fresh branch from the primary branch, cherry-pick the relevant commits, and use that refreshed PR as the merge path.
39 
405. Route follow-up fixes back to their source branch.
41   If testing on `stage` uncovers a bug in an already-merged PR branch, fix that branch or replace it with a refreshed PR. Avoid leaving the fix only on `stage`, because that creates hidden history that later has to be reconstructed by hand.
42 
436. Create one worktree per merge unit.
44   For every new PR branch, create a dedicated worktree from the primary branch. For follow-ups to an existing non-primary branch, use a dedicated worktree there too, but prefer replacing it with a fresh primary-based PR if that is cleaner.
45 
467. Merge foundations first.
47   Put tooling and workflow fixes first if later cherry-picks or commits depend on them.
48 
498. Merge behavior, then docs, then cleanup.
50   Recommended order:
51   - tooling foundations
52   - backend or frontend behavior changes
53   - integration or e2e coverage
54   - docs and runbooks
55   - cleanup or dedup fixes
56 
579. Verify the primary branch against `stage` after each wave.
58   Use `git diff primary..stage` and inspect only the remaining files. Also compare `stage` against the source PR branches when recovering from stage-only drift, so you can prove that no functional change was lost. Distinguish between:
59   - true missing functionality
60   - acceptable drift where the primary branch is now better than `stage`
61   - generated file drift
62   - intentional tooling drift
63 
6410. Close superseded PRs explicitly.
65   Leave a short comment that links the replacement PR, then close the old PR. Do the same for the umbrella stage PR once the split merge set has landed.
66 
67## Decision Rules
68 
69- If a stage-only commit is already fully represented by a merged replacement PR, do not replay the original commit just to preserve SHA identity.
70- If a conflict resolution in a refreshed PR already matches `stage`, and a later follow-up commit becomes empty, treat that as confirmation that the desired state is already included.
71- If the primary branch contains a post-stage safety fix, do not regress it just to force byte-for-byte equality with `stage`.
72- If only locale text, generated artifacts, or similar outputs differ, classify that separately from functional behavior.
73- If a bugfix was created only on `stage`, treat that as process debt and move it into the owning PR branch or a refreshed replacement PR before considering the replay complete.
74- If the question is “did we lose anything from those older PRs?”, answer it by diffing the original PR branches against the current primary branch and describing functional loss, generated drift, or improvements in the primary branch.
75 
76## Reporting
77 
78When summarizing the split, produce:
79- merged PRs
80- refreshed or replacement PRs
81- closed superseded PRs
82- remaining diff between the primary branch and `stage`, labeled as functional, generated, or intentional
83 
84## Reference
85 
86For command patterns and closure language, read [references/checklist.md](./references/checklist.md).
87