Git Branch And Release Rule
rule_id: R-P01 legacy_id: "005" category: Process status: locked owner: Project Manager / Architect / Release Owner scope: branches, merges, release workflow, master/main gates
1. Rule
<release_upstream> stores release snapshots only.
Daily work goes through <dev_branch>. Release from <dev_branch> to <release_upstream> uses squash merge. After release, merge <release_upstream> back into <dev_branch>.
Main stays in the authority checkout. A mismatch with the REQ-bound branch must be resolved explicitly; never automatically switch branches. See workspace integration.
2. Branch Model
| Branch | Purpose | Protection |
|---|---|---|
<release_upstream> |
production release snapshot | no direct daily work; release/hotfix only |
<dev_branch> |
daily integration | REQ explicitly declared development branch |
REQ binding explicitly declares both destinations, including the remote for a remote release target. Neither field has a default.
3. Short-Lived Branches
| Type | Name | Source | Target |
|---|---|---|---|
| docs/process | docs/<topic> |
<dev_branch> |
<dev_branch> |
| feature | feature/<task-id>-<topic> |
<dev_branch> |
<dev_branch> |
| bugfix | bugfix/<bug-id>-<topic> |
<dev_branch> |
<dev_branch> |
| tech debt | td/<id>-<topic> |
<dev_branch> |
<dev_branch> |
| release candidate | release/<version-or-date> |
<dev_branch> |
<release_upstream> |
| production hotfix | hotfix/<bug-id>-<topic> |
<release_upstream> |
<release_upstream> + <dev_branch> |
4. Stage To Branch
These are optional naming conventions for separately authorized branches, not instructions to switch Main at each stage. Registered Worker branches follow the workspace execution record; Main retains its bound checkout and branch.
| Stage | Output | Branch |
|---|---|---|
| S0/S1 requirement design and initialization | AGENTS.md, project.yaml, project-map.md, REQ-*.md |
docs/req-<id>-<topic> or docs/bootstrap-project |
| S2 design | architecture, state, model, ADR, UI design packages | docs/design-<req-id>-<topic> |
| S3 contracts | FE/BE/SYNC contracts | docs/dev/contracts-<req-id>-<topic> |
| S4 tasks | task board and task files | docs/dev/tasks-<req-id>-<topic> |
| S5 document verification | REV/document-verification evidence | docs/document-verification-<req-id> |
| S6 build | code and tests | feature/<task-id>-<topic> |
| S7 full verification round | REV/QA/E2E evidence | docs/review-<req-id>-round-<n> |
| S8 finding investigation | BUG reports and root-cause evidence | docs/bug-investigation-<req-id>-round-<n> |
| S9 bug resolution | bugfix, targeted re-verification, impact evidence | bugfix/<bug-id>-<topic> |
| S10 acceptance and audit | ACC, release changes, release architecture audit | release/<version-or-date> or docs/release-<topic> |
| S11 human release gateway | release-ready handoff only; no automation branch action | n/a |
5. Implementation Branch Authority
Branch creation requires a permitted Loop transition and an activated assignment whose scope includes the branch operation. This rule defines branch shape; the Loop Definition, runtime, activation, and Hooks enforce timing.
6. Merge Rules
| Operation | Rule |
|---|---|
<dev_branch> -> <release_upstream> |
squash merge only |
<release_upstream> -> <dev_branch> after release |
normal merge |
hotfix/* -> <release_upstream> |
squash merge, then merge back to <dev_branch> |
release/* -> <release_upstream> |
squash merge |
feature/* / bugfix/* -> <dev_branch> |
normal merge commit; retain task evidence, verify, acknowledge and clean the temporary worktree |
7. Release Gates
Before merge to <release_upstream>:
- release audit exists in
docs/reports/release-audits/ - audit result is not
BLOCKED - TASK, REV, and QA evidence exists
- locked contract quality gate evidence exists
- release audit includes release changes, migration, and rollback
- migrations, data repair, and rollback plan are documented if needed
8. Forbidden
- feature branch directly into
<release_upstream> - normal merge commit into
<release_upstream> - daily work on
<release_upstream> - release without release audit
- release with
BLOCKEDaudit - sync commit with unrelated changes
- implementation branch outside an activated assignment
- loop-created squash merge or formal release without human approval
- implementation branch before locked contract
- implementation branch before required UI Design Package Gate
- release branch containing next-batch features
9. Loop Release Boundary
Loop mode may create and manage docs, feature, bugfix, and release-candidate branches for its bound REQ.
After required reports and release audit are complete, it must stop at:
awaiting_human_release
Only an explicit human release approval may authorize squash merge to
<release_upstream>.
10. Human Release Handoff
The handoff identifies the actual bound integration branch, tested commit, project release branch and release evidence. The human release owner performs release and post-release synchronization through the project’s approved process. Do not place automatic checkout, pull, squash or push commands in Main’s engineering continuation. A protected release target requires its own human release decision even when a Worker has passed integration checks.
临时 worktree 与阶段交付
REQ 绑定必须显式提供 --dev-branch <开发主分支> 和 --release-upstream <最终发布上游>，远程发布目标包含 remote；没有 develop 默认值。项目根目录是当前 REQ 唯一权威。
派发前将上游正式 Markdown、代码和测试产出整理提交；不要自动提交用户无关变更。新 worktree 不含主会话未提交或仅暂存的文件。主会话用 runtime worktree-create --assignment-id <id> --root <项目根目录> 从绑定开发分支的明确 commit 创建；不要依赖平台默认分支或复制整个目录。明确不入 Git 的 evidence 单独按依赖交接，不能复制整个控制面。
子会话在子分支提交成果并报告，主会话在项目根目录执行 runtime task-integrate --assignment-id <id>，生成合并提交、校验、接收并及时清理。集成不是 release；临时 worktree 不是交付终点。未回收、分支偏离、积压只提醒，不新增 Stop 或普通工具硬门禁。
Gate 的输入来源由 loop-definition 的 file_sources 契约声明；正式交付读固定 Git tree，明确运行输入读磁盘，Runtime 读权威快照。未提交产出不能帮助阶段通过。允许汇总的 evidence 按 mutable_evidence_kinds 自动同步对应 SHA256；同步不改变结论或代际，也不抹除产品基线漂移。