From f509c370b343b232c6386f07ffd705959e70777b Mon Sep 17 00:00:00 2001
From: Edison Jwa <me@edison.network>
Date: Thu, 11 Jun 2026 12:25:28 +0900
Subject: [PATCH] docs: add branch management workflow guide (TODO-088)

Document branch naming conventions, git worktree setup, PR stacking
patterns, and local CI mirroring recommendations.
---
 docs/references/branch-management-workflow.md | 136 ++++++++++++++++++
 1 file changed, 136 insertions(+)
 create mode 100644 docs/references/branch-management-workflow.md

diff --git a/docs/references/branch-management-workflow.md b/docs/references/branch-management-workflow.md
new file mode 100644
index 0000000..a2abf5d
--- /dev/null
+++ b/docs/references/branch-management-workflow.md
@@ -0,0 +1,136 @@
+# Branch Management Workflow
+
+**Document status:** Active reference
+**Date:** 2026-06-11
+
+## Branch Naming Convention
+
+Branches use `<type>/<short-description>`:
+
+| Prefix | Purpose | Examples |
+|--------|---------|---------|
+| `feat/` | New feature | `feat/file-transfer`, `feat/poke-notifications` |
+| `fix/`  | Bug fix | `fix/ios-audio-playback-capture`, `fix/cross-platform-audio-route` |
+| `docs/` | Documentation only | `docs/codebase-analysis-v2`, `docs/export-compliance-closed-source` |
+| `refactor/` | Code restructuring | `refactor/remove-ios-raw-unit` |
+| `chore/` | Tooling, CI, maintenance | `chore/gitignore-macos-framework-binary`, `chore/upgrade-android-toolchain` |
+| `review-pr-<N>` | Review-specific branch | `review-pr-21`, `review-pr-22` |
+| `pr-<N>` | PR checkout | `pr-34`, `pr-35` |
+| `product/` | Long-lived product milestone | `product/scaffold-v0`, `product/desktop-ui-ux-redesign` |
+
+Scopes in commit messages should match the branch type. Both follow the Conventional Commits convention defined in `docs/governance/git-commit-message-convention.md`.
+
+## Merging Strategy
+
+All PRs merge into the default branch (`main` via GitHub merge commits). Squash merges are not used — branch topology is preserved via `git log --graph`.
+
+## Git Worktree for Parallel Development
+
+This project already uses git worktrees for PR review. Three are currently active:
+
+```
+/chanora                              → docs/codebase-analysis-v2
+/tmp/opencode/chanora-pr34-review     → simplify-project-review
+/tmp/opencode/chanora-pr35-review     → (detached HEAD)
+/tmp/opencode/chanora-pr36-review     → pr-36-review
+```
+
+### Why Worktrees
+
+- Review PRs without stashing or losing your working tree state
+- Run long CI builds in one tree while editing in another
+- Keep multiple feature branches checked out simultaneously
+- Avoid `git stash` / `git checkout` churn
+
+### Common Workflows
+
+**Feature branch:**
+```bash
+git worktree add ../chanora-feat-x feat/my-feature
+cd ../chanora-feat-x
+# work, commit, push, open PR
+```
+
+**Hotfix (from main):**
+```bash
+git worktree add ../chanora-hotfix -b fix/urgent-bug origin/main
+cd ../chanora-hotfix
+# fix, commit, push, open PR
+# merge PR, then: git worktree remove ../chanora-hotfix
+```
+
+**Review branch (checkout a PR):**
+```bash
+gh pr checkout 36 --detach
+# or via worktree:
+git worktree add ../chanora-review-36 pr-36-review
+```
+
+### Cleanup
+
+```bash
+git worktree remove ../chanora-feat-x        # after merge
+git worktree prune                            # clean stale entries
+git branch -d feat/my-feature                 # delete merged branch
+```
+
+## PR Stacking Pattern
+
+This project uses stacked PRs where features are built on top of each other:
+
+```
+main ← #39 (refactor/remove-ios-raw-unit)
+         └─ #38 (fix/ios-audio-session)
+              └─ #37 (feat/desktop-silero-vad)
+```
+
+To create a stacked PR:
+
+1. Branch from the base PR's branch (not `main`)
+2. Push and open PR targeting the base PR's branch
+3. After base merges, rebase onto `main` and update the target
+
+For managing stacks, `gh` CLI is sufficient:
+
+```bash
+# Create dependent branch
+git checkout -b feat/next-thing origin/feat/base-thing
+# After base merges:
+git rebase origin/main && git push --force-with-lease
+# Update PR target via GitHub UI or:
+gh pr edit <number> --base main
+```
+
+## Local CI Mirroring
+
+The project CI (defined in `.github/workflows/`) runs platform builds (Android, Windows, macOS, iOS), clippy, and tests. To mirror locally before pushing:
+
+```bash
+# Rust checks (fast, run always)
+cargo clippy --workspace --all-targets -- -D warnings
+cargo test --workspace
+
+# Flutter checks
+cd flutter && flutter analyze
+
+# Platform builds (run before PR)
+cargo build --target aarch64-linux-android
+cargo build --target x86_64-pc-windows-msvc
+cargo build --target aarch64-apple-darwin
+```
+
+Tip: Use `act` (https://github.com/nektos/act) to run GitHub Actions locally for full CI parity:
+
+```bash
+act pull_request  # runs the PR workflow locally via Docker
+```
+
+## Quick Reference
+
+| Task | Command |
+|------|---------|
+| New feature | `git worktree add ../chanora-X -b feat/X origin/main` |
+| Review PR | `gh pr checkout N` or `git worktree add ../review-N pr-N-review` |
+| Cleanup after merge | `git worktree remove ../chanora-X && git branch -d feat/X` |
+| Check worktrees | `git worktree list` |
+| Local CI | `cargo clippy --workspace --all-targets -- -D warnings && cargo test --workspace` |