docs(agents): require feature branches off dev for all work

Align AGENTS, Cursor rule, PROJECT, README, templates, and CURRENT with strategy A: no direct commits on dev/test/main; all work branches from dev. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-13 02:44:39 +00:00
parent 8ff4d338d5
commit 5e5bc1f03b
8 changed files with 54 additions and 28 deletions
@@ -10,18 +10,18 @@ alwaysApply: true
 ## 一、 Git 固定三分支体系

 1. **开发分支 (`dev`)**:
-   - 所有代码日常开发在此分支进行。
-   - 细小变更直接在 `dev` 上分批逐步提交。
-   - 独立大功能可从 `dev` 检出子分支 `feature/<name>` 或 `fix/<name>`，在本地测试完成后合并回 `dev`（`--no-ff`），并删除临时子分支。
+   - **合入基线**，不是日常 commit 目标。
+   - **禁止**在 `dev` 上直接开发提交（含 docs/chore）。
+   - 一律从最新 `dev` 检出 `feature/<name>` 或 `fix/<name>`，在 feature 分支上渐进式提交；自测后占集成槽位，`--no-ff` 合回 `dev`，并删除临时子分支（见 [AGENTS.md](../../AGENTS.md) §6.2）。

 2. **测试分支 (`test`)**:
   - 当 `dev` 积累了一定的功能阶段后，合并至 `test` 分支，创建阶段候选节点 Tag（如 `rc-vX.Y.Z-beta.1`）。
   - 用于较长时间的真实环境部署、全链路集成测试、运维稳定性检验。
-   - 严禁在 `test` 分支进行未经规划的大规模功能开发。
+   - **严禁**在 `test` 分支进行开发或直接 commit。

 3. **主分支 (`main`)**:
   - 生产发布分支（Release）。
-   - 严禁直接在 `main` 上开发！
+   - **严禁**直接在 `main` 上开发或 commit！
   - 只有 `test` 分支的代码经过实际运维和测试充分验证达到发布标准后，方可将对应验证节点合并回 `main` 分支，并打正式发布 Tag（如 `v1.0.0`）。

 ---
@@ -1,5 +1,7 @@
 # 研发分支与多套独立环境运行规范 (Branch & Environment Rules)

+> **HISTORICAL**：日常开发分支策略已由 [AGENTS.md](../../../AGENTS.md) §6.2、[PROJECT.md](../../../PROJECT.md) §4 与 [`.cursor/rules/git-workflow-and-environments.mdc`](../../../.cursor/rules/git-workflow-and-environments.mdc) 取代为「一律从 `dev` 开 `feature/*` 或 `fix/*`，禁止在三大主干直接 commit」。本文档保留作环境矩阵与历史流程参考。
+
 本规范为本系统代码仓库的强制性规范，涵盖 **Git 3 分支流转模型**、**任务功能拆分与渐进式提交**、**三套环境独立运行（知识库共享 + 对话与数据库隔离）** 以及 **运维操作指引**。

 ---
@@ -1,13 +1,13 @@
 # 当前焦点

 **更新**: 2026-09-13  
-**production_ready**: no（CI 真实 PI E2E + 前端人工抽检待完成）
+**production_ready**: no（对话刷新恢复、CI 真实 PI E2E、前端人工抽检待完成）

 ## 焦点

-1. **CI**: `TEST_DATABASE_URL` + 真实 PI E2E 实录
-2. **前端**: 版本冲突刷新、终止 preview 人工抽检
-3. **BACKLOG**: session cookie / bundle 拆分 / 容量治理（见 [backlog](../backlog/chat-agent-p6-backlog.md)）
+1. **CHAT**: [刷新恢复整改待实施](short-term/2026-09-13-chat-history-refresh-remediation.md)（发布 blocker）
+2. **CI**: `TEST_DATABASE_URL` + 真实 PI E2E 实录
+3. **前端**: 版本冲突刷新、终止 preview 人工抽检

 ## 并行认领

@@ -15,7 +15,7 @@
 |-------|------|--------|----------|-------|--------|
 | — | — | — | — | — | — |

-> 新任务开始前登记。同一 `mutex` 同时仅一个 `in_progress`。
+> 新任务开始前登记。`branch` 必须为 `feature/<slug>` 或 `fix/<slug>`，**禁止** `dev` / `test` / `main`。同一 `mutex` 同时仅一个 `in_progress`。

 ## 集成槽位

@@ -10,8 +10,10 @@

 ## 代码与分支

- [ ] 非 trivial 改动已 merge `--no-ff` 到 dev（或 handoff 说明未 merge 原因）
- [ ] 无未 push 的 dev 关键提交（若用户要求同步远端）
+- [ ] 确认未在 `dev` / `test` / `main` 上直接 commit（工作均在 `feature/*` 或 `fix/*`）
+- [ ] 已占集成槽位并 `merge --no-ff` 合回 `dev`（或 handoff 说明未 merge 原因）
+- [ ] feature/fix 分支已删除或 worktree 已 remove（若已合入）
+- [ ] 无未 push 的关键提交（若用户要求同步远端）

 ## 文档

@@ -4,7 +4,7 @@ status: planned
 created: YYYY-MM-DD
 updated: YYYY-MM-DD
 owner: agent
-branch: feature/<slug>
+branch: feature/<slug>   # 必填：feature/* 或 fix/*；禁止 dev / test / main
 worktree: "-"
 mutex: <module>
 ---
@@ -105,17 +105,36 @@

 **同一 mutex 同时仅一个 `in_progress`**。冲突 → 写 handoff blocker，禁止覆盖他人未合并改动。

-### 6.2 分支与 Worktree
+### 6.2 分支与 Worktree（策略 A：一律从 dev 开分支）

- 非 trivial 改动必须独立分支，禁止多人直推同一 dev 工作区抢改。
- **多 Agent 并行时强制 worktree**：`.worktrees/<branch-slug>/`（已 gitignore）
- 脚本：`./scripts/agent-worktree.sh create|list|remove`
+> **禁止**在 `dev` / `test` / `main` 三大主干上直接 `git commit`（含代码、配置、文档）。  
+> `dev` 仅作合入点；`test`/`main` 仅作环境晋升合入，禁止开发。

-| Worktree 允许 | Worktree 禁止 |
-|---------------|---------------|
-| 编码、`go test -short ./...` | `env-service.sh * start/stop/restart` |
+**任务开始（先于改码）：**
+
+1. 更新本地 `dev`：`git checkout dev && git pull`（若已配置远端）
+2. 从 `dev` 创建分支：`feature/<slug>`（新能力）或 `fix/<slug>`（缺陷）；slug 与 short-term 任务名对齐
+3. 多 Agent 并行：用 `./scripts/agent-worktree.sh create feature/<slug>`（worktree 内编码）
+4. 单 Agent：可在主仓 `git checkout -b feature/<slug>`，**不得**留在 `dev` 上改码提交
+
+**合回 dev（占集成槽位，见 §6.3）：**
+
+```bash
+git checkout dev
+git merge --no-ff feature/<slug> -m "merge: feature/<slug>"
+# 冒烟通过后
+git branch -d feature/<slug>   # 或 agent-worktree.sh remove
+```
+
+| 允许 | 禁止 |
+|------|------|
+| 在 `feature/*` / `fix/*` 上 commit | 在 `dev` / `test` / `main` 上 commit |
+| worktree 内 `go test -short ./...` | worktree 内 `env-service.sh * start/stop/restart` |
+| 占槽后在主仓 merge 入 `dev` | 多人直推同一 `dev` 工作区抢改 |
 | 连主仓已起服务 `:8080` | 各 worktree 各起 docker |

+脚本：`./scripts/agent-worktree.sh create|list|remove`
+
 ### 6.3 集成槽位（合入 dev + 容器验证）

 > **编码与 worktree 单测可并行；合入 dev + 共享容器验证必须串行。**
@@ -161,11 +180,12 @@ audit（问题）→ remediation（方案）→ ops/short-term（任务）
 ## 8. Git 与提交

 - 遵循 **Conventional Commits**：`feat` / `fix` / `refactor` / `test` / `docs` / `chore` / `ci`
- **原子提交**：一个逻辑变更一批
- merge 回 dev 用 `--no-ff`
+- **原子提交**：一个逻辑变更一批；提交发生在 `feature/*` 或 `fix/*` 上，不在三大主干
+- **合回 dev**：占集成槽位后 `merge --no-ff`（见 §6.2、§6.3）
+- **晋升**：`dev` → `test`（rc tag）→ `main`（release tag）；仅在规划的环境合并时动 `test`/`main`
 - **用户未要求**：不擅自 push
 - **用户已要求 push/同步远端**：必须自主完成
- **禁止**：在 `git config` 写入 token；硬重置/强推/删库仅在用户明确授权时
+- **禁止**：在 `dev`/`test`/`main` 上直接开发 commit；在 `git config` 写入 token；硬重置/强推/删库仅在用户明确授权时

 ---

@@ -52,6 +52,8 @@

 **红线**：知识库共享；对话与业务 DB **严格隔离**，禁止跨环境读写。

+**分支红线**：三大主干（`dev`/`test`/`main`）禁止直接开发 commit；一律从 `dev` 开 `feature/*` 或 `fix/*`，合回 `dev` 须占集成槽位（见 [AGENTS.md](./AGENTS.md) §6）。
+
 ---

 ## 5. 文档地图（SSOT）
@@ -124,11 +126,11 @@ cd web && npm test && npm run build
 - 发布缺口 SSOT：[gap-matrix](./.doc/remediation/gap-matrix.md)
 - 模块完成度：[FEATURE-MATRIX](./.doc/status/FEATURE-MATRIX.md)
 - 最新测试报告：[2026-09-13-codex-audit-p0-remediation-test-report.md](./.doc/test-reports/2026-09-13-codex-audit-p0-remediation-test-report.md)
- **剩余 blocker**: CI 真实 PI E2E + 前端人工抽检（main 本地冒烟已通过）
+- **剩余 blocker**: 对话刷新恢复与历史读取授权一致性 + CI 真实 PI E2E + 前端人工抽检（main 本地冒烟已通过）

 ---

 ## 10. 语言与提交

 - 对用户：**简体中文**
- 提交：Conventional Commits；在 `dev` 上渐进式分批提交
+- 提交：Conventional Commits；在 `feature/*` 或 `fix/*` 上渐进式分批提交，合回 `dev` 用 `--no-ff`（禁止在三大主干直接 commit）
@@ -12,9 +12,9 @@

 | 分支名 | 定位 | 职责与准入规则 |
 | :--- | :--- | :--- |
-| **`dev`** | **开发分支** | **日常开发基线**。所有代码开发均在此分支或其衍生子分支（`feature/*`, `fix/*`）进行，子分支自测后合并回 `dev`。支持一个任务按功能拆解并逐步渐进式提交。 |
-| **`test`** | **测试分支** | **准生产实测分支**。当 `dev` 积累了一定功能阶段后合并至此，建立发布候选节点（`rc-vX.Y.Z`），进行真实环境部署与长期集成测试与运维检验。 |
-| **`main`** | **主分支** | **生产发布分支**。严禁直接提交。仅在 `test` 分支经过真实运维和测试验证达到发布标准后，将对应节点合并回 `main` 并打正式版本 Tag（`vX.Y.Z`）。 |
+| **`dev`** | **开发合入基线** | 禁止直接 commit。从最新 `dev` 开 `feature/*` 或 `fix/*` 开发，自测后占集成槽位 `--no-ff` 合回 `dev`。 |
+| **`test`** | **测试分支** | 准生产实测；`dev` 阶段合并 + rc tag。**严禁**在此分支开发或 commit。 |
+| **`main`** | **主分支** | 生产发布；仅 `test` 验证通过后合并。**严禁**直接开发或 commit。 |

 完整的分支流转模型、热修复流程与提交规范请参阅：[PROJECT.md](./PROJECT.md) §4（SSOT）。