docs: 分支策略（简化版 GitFlow）文档

AGENTS.md

@@ -43,6 +43,7 @@ scripts/verify.sh    确定性验证脚本
 6. **验证优先于声称完成**：任何"完成/通过"声明都必须以 `scripts/verify.sh` 的新鲜输出为证据。
 7. **Commit 格式**：`type(scope): description`，一次提交一个变更集。
 8. **新 feature 模式**：在 `feature/<name>/` 下用 `mcl.android.feature` 插件，暴露 `<Name>Screen` 组合函数 + `<NAME>_ROUTE` 路由常量 + `<Name>ViewModel`，并在 `app` 的 `AppNavHost` 注册路由。
+9. **Git 分支流**：`feature/<name>` 从 `dev` 拉、merge 回 `dev`；`dev` 稳定后经确认再 merge 到 `main`（详见 [docs/gitflow.md](docs/gitflow.md)，决策记录 ADR-0005）。
 
 ## 文档地图
 
@@ -50,6 +51,7 @@ scripts/verify.sh    确定性验证脚本
 |------|------|
 | 架构与模块依赖 | [docs/architecture.md](docs/architecture.md) |
 | 编码规范 / 命名 / commit | [docs/conventions.md](docs/conventions.md) |
+| Git 分支策略（简化版 GitFlow） | [docs/gitflow.md](docs/gitflow.md) |
 | 测试策略与命令 | [docs/testing.md](docs/testing.md) |
 | 构建 / 签名 / 发布 | [docs/deployment.md](docs/deployment.md) |
 | 工作状态与遗留项 | [docs/progress.md](docs/progress.md) |

docs/conventions.md

@@ -29,6 +29,7 @@
 
 - Commit 格式 `type(scope): description`，type 如 `feat`/`fix`/`refactor`/`docs`/`build`/`test`/`chore`；一次提交一个变更集。
 - 提交前跑 `./gradlew spotlessApply` 与 `bash scripts/verify.sh`。
+- 分支流采用简化版 GitFlow：feature 从 `dev` 拉、merge 回 `dev`，`dev` 稳定后经确认再进 `main`。详见 [gitflow.md](gitflow.md)（决策记录 ADR-0005）。
 
 ## 文档
 

docs/decisions/0005-branching-strategy.md

@@ -0,0 +1,30 @@
+# ADR 0005：分支策略（简化版 GitFlow）
+
+- **状态**：已接受
+- **日期**：2026-09-04
+
+## 背景
+
+项目进入多模块骨架建设阶段，单人/小团队开发。需要明确一套分支流，既保证 `main` 始终可发布，又不引入超过当前规模的开销。当前 `dev` 与 `main` 处于同一 commit（尚未分叉），正是定策略的时机。
+
+## 决策
+
+采用**简化版 GitFlow**：
+
+- `feature/<name>` 从 `dev` 拉取，完成后 **merge 回 `dev`**（不直接进 `main`）。
+- `dev` 作为集成点，保持可构建；所有 feature 先合入这里。
+- `dev` 稳定后，**经人工确认**再 merge 回 `main`。
+- 当前阶段**不引入 `release/*`**；`hotfix/<name>`（从 `main` 拉，合回 `main` + `dev`）按需使用。
+
+日常操作细节见 [docs/gitflow.md](../gitflow.md)。
+
+## 理由
+
+- 严格 GitFlow 中，`main` 只经 `release/*` / `hotfix/*` 进入，feature 永不直接碰 `main`。在基础建设阶段，`release/*` 分支是纯负担。
+- 简化版保留了两个关键性质：**`dev` 是集成点**（隔离未稳定代码）、**`main` 只放可发布状态**，同时免去 release 分支的管理开销。
+- 与 `feature/<name>/` 模块目录名对齐的命名，让分支与代码结构一一对应。
+
+## 后果
+
+- `main` 始终为可发布状态；进入 `main` 的合并必须人工确认。
+- 未来团队扩大或进入正式发布周期，可平滑升级为完整 GitFlow（引入 `release/*`、正式版本 tag），无需推翻现有模型。

docs/gitflow.md

@@ -0,0 +1,76 @@
+# Git 分支策略（简化版 GitFlow）
+
+本文档是项目分支流的**唯一事实源**。决策背景与理由见 [decisions/0005-branching-strategy.md](decisions/0005-branching-strategy.md)。
+
+## 分支角色
+
+| 分支 | 从哪拉 | merge 回 | 用途 |
+|------|--------|----------|------|
+| `main` | — | — | 可发布稳定版；只经 `dev`（或 `hotfix`）进入，不直接收 feature |
+| `dev` | `main` | — | 集成点；所有 feature 先合到这里 |
+| `feature/<name>` | `dev` | `dev` | 单一功能/模块开发，完成后合回 dev |
+| `hotfix/<name>` | `main` | `main` + `dev` | 线上紧急修复（按需，当前阶段少用） |
+
+> 当前不引入 `release/*`：基础建设阶段收益低。进入正式发布周期后再升级（见 ADR-0005「后果」）。
+
+## 完整流程
+
+```text
+main ───────────────────────────────●  稳定/可发布（只经 dev 或 hotfix 进入）
+                                     ▲ merge（需你确认）
+dev  ──●────●────●───────────────────┘  集成点（接收所有 feature）
+       │    │    │
+  feature/  feature/  feature/        从 dev 拉，merge 回 dev
+  auth      checkin   plan
+```
+
+## 命名约定
+
+- `feature/<name>` 的 `<name>` 与 `feature/<name>/` 模块目录名一致（如 `feature/auth`）；非模块功能用 kebab-case 短名（如 `feature/onboarding-flow`）。
+- `<name>` 一律 kebab-case：小写、短横线分隔，不混用下划线。
+
+## 各分支规则
+
+- **feature**：从 dev 拉 → 开发 → 跑 `bash scripts/verify.sh` → merge 回 dev。一次 feature 一个主题。
+- **dev**：集成点，保持可构建；合入前必须通过完整验证。
+- **main**：只放可发布状态；进入 main 必须经人工确认。
+
+## 自动化边界
+
+| 动作 | Claude 行为 |
+|------|-------------|
+| 从 dev 拉 `feature/<name>` | ✅ 自动 |
+| 按 `type(scope): description` 提交 | ✅ 自动 |
+| 跑 `scripts/verify.sh` 作为「完成」证据 | ✅ 自动 |
+| merge 回 `dev` | ⚠️ 默认先给 diff，确认后合 |
+| merge 到 `main` | ❌ 永远先问你，绝不自动 |
+| rebase / force-push | ❌ 需显式确认 |
+| 删除远程分支 | ⚠️ 确认后执行 |
+
+## 操作清单
+
+```bash
+# 开始一个 feature（以 auth 为例）
+git checkout dev && git pull
+git checkout -b feature/auth
+
+# ...开发、按 type(scope): description 提交...
+
+# 完成后合并回 dev
+bash scripts/verify.sh                    # 必须先通过
+git checkout dev && git pull
+git merge --no-ff feature/auth            # --no-ff 保留 feature 边界，便于追溯
+git push origin dev
+
+# dev 稳定后合入 main（需你确认）
+git checkout main && git pull
+git merge --no-ff dev
+git push origin main
+# 发布时按需打 tag：git tag -a v0.x.y -m "..." && git push origin --tags
+```
+
+## 关联
+
+- 决策记录：[decisions/0005-branching-strategy.md](decisions/0005-branching-strategy.md)
+- 提交格式：[conventions.md](conventions.md)
+- 构建与发布：[deployment.md](deployment.md)