[moz] docs(§21): fix 姜维 S1 分支名前缀按 type + S2 sub Issue body 加 Depends

2026-06-20 21:23:40 +08:00
7 changed files with 10 additions and 154 deletions
@@ -35,4 +35,3 @@ inbox/*.jsonl

 # E2E test data
 data/e2e-*/
-data/_mail/
@@ -713,7 +713,7 @@ agent 的 comment + Gitea 自动引用 = parent Issue 中有完整的 sub 注册
 | 阶段 | 谁创建分支？ | 分支名 |
 |------|-----------|-------|
 | Discussion（Phase 3） | ❌ 不创建分支 | — |
-| Executor（Phase 4） | agent 收到 executor prompt 后自己创建 | `{type}/{sub_issue_number}-{brief}`（type 按 Issue 类型：fix/feat/impl/docs/refactor/test） |
+| Executor（Phase 4） | agent 收到 executor prompt 后自己创建 | `fix/{sub_issue_number}-{brief}` |

 **executor prompt 的 steps 中明确指定分支名**：
 ```
@@ -797,138 +797,6 @@ daemon 监听 Issue 创建 webhook → 解析标题中的 `[parent #N]` → 记

 ---

-## §14b. 分支与 PR 生命周期管理
-
-> 解决分支、PR、Issue 之间的割裂问题，统一定义完整生命周期。
-
-### 14b.1 Sub Issue 的分支/PR 生命周期
-
-```
-① 创建 Sub Issue
-  Agent 在 discussion 阶段创建 sub Issue（assign 自己）
-  → 分支：还不存在
-  → daemon task_state: status=pending, parent_issue=N
-
-② 分支创建（executor 阶段）
-  Agent 收到 executor prompt → git checkout -b {type}/{sub_issue_number}-{brief}
-  → 分支名从 sub Issue number 派生，一一对应
-  → daemon task_state: status=working（通过 dispatch 触发）
-
-③ 编码
-  Agent 在分支上编码 → commit → push
-  → 分支远程存在，Gitea 可见
-
-④ PR 创建
-  Agent 创建 PR（head: {type}/{sub_issue_number}-{brief} → base: main）
-  PR body 必须包含：
-    - `Closes #{sub_issue_number}`（让 Gitea merge 时自动关 sub Issue）
-    - `Parent: #{parent_issue_number}`（关联到 parent）
-    - 改动说明（改了什么、为什么）
-  → webhook: pull_request/opened → daemon task_state: status=review
-
-⑤ CI
-  PR 创建 → CI 自动触发（lint + test + frontend）
-  → 通过：等 Review
-  → 失败：toolchain handler 创建 ci_failure task → agent 修复 → push 到同分支 → CI 重跑
-
-⑥ Review
-  司马懿收到 Review 请求 → 读 PR diff → 提交 Review（Review API）
-  → APPROVED：通知 agent 合并
-  → REQUEST_CHANGES：通知 agent 修改
-
-⑦ 修改（如果有）
-  Agent 在同分支上修改 → commit → push
-  → PR 自动更新（不新建 PR）
-  → CI 重跑 → 司马懿重新 Review
-  → 循环回到 ⑥
-
-⑧ Merge
-  Agent 或 Reviewer merge PR
-  → Gitea 自动关闭 sub Issue（因为 PR body 有 Closes #N）
-  → webhook: pull_request/closed(merged=true)
-  → daemon 终态信号：task_state status=done
-
-⑨ 分支清理
-  Gitea 配置自动删除已合并分支（推荐）
-  Issue 保持 closed 状态（完整历史保留）
-```
-
-### 14b.2 Parent Issue 的生命周期
-
-```
-① 创建（庞统）
-  庞统创建 parent Issue（无 assignee）
-  → 触发 discussion 广播
-  → parent Issue 不创建分支（parent 是讨论和编排层）
-
-② Discussion
-  Agents 讨论、创建 sub Issues、在 parent comment 注册
-
-③ 执行
-  所有 sub Issues 走 §14b.1 生命周期
-
-④ Round Review
-  所有 sub Issues 终态 → 庞统三问
-  → GOAL_ACHIEVED → 庞统关闭 parent Issue
-  → 需要新轮 → 庞统创建新 sub Issues → 回到 ③
-
-⑤ 关闭
-  庞统关闭 parent Issue
-  → webhook: issues/closed → daemon 终态
-```
-
-### 14b.3 核心规则
-
-| 规则 | 定义 | 原因 |
-|------|------|------|
-| 分支 : sub Issue = 1:1 | 每个 sub Issue 一个分支 | 分支名从 Issue number 派生 |
-| 分支 : PR = 1:1 | 每个分支一个 PR | Review 驳回不新建 PR，push 到同分支更新 |
-| sub Issue : PR = 1:1 | 一个 sub Issue 一个 PR | 简单场景。复杂 sub 按需拆多个 sub Issue |
-| PR body 必须含 Closes #N | N = sub Issue 编号 | merge 后自动关 Issue |
-| PR body 必须含 Parent #M | M = parent Issue 编号 | 关联到 parent，方便追溯 |
-| parent Issue 不创建分支 | parent 是讨论编排层 | 代码产出在 sub Issue 的分支 |
-| discussion 不碰 git | 只读 Issue + comment + 创建 sub | 避免讨论阶段产生无意义 commit |
-| 分支名格式 | {type}/{sub_issue_number}-{brief} | 按 Issue 类型：fix/feat/impl/docs/refactor/test |
-| merge 后自动删分支 | Gitea 配置 | 避免分支堆积 |
-
-### 14b.4 多分支并行场景
-
-一个 parent Issue 下多个 sub Issue 同时执行：
-
-```
-parent Issue #100（双均线策略）
-  ├── sub #101 策略编码 → 分支 feat/101-dual-ma → PR #104
-  │   └── CI 跑 + Review → merge → Closes #101
-  ├── sub #102 风控规则 → 分支 feat/102-risk-control → PR #105
-  │   └── CI 跑 + Review → merge → Closes #102
-  └── sub #103 策略测试 → 分支 test/103-strategy-test → PR #106
-      └── CI 跑 + Review → merge → Closes #103
-
-所有 sub 终态 → 庞统 round review → parent Issue #100 关闭
-```
-
-每个 sub Issue 的分支、PR、CI、Review 独立流转，互不干扰。
-
-### 14b.5 PR body 模板
-
-```markdown
-Closes #{sub_issue_number}
-Parent: #{parent_issue_number}
-
-## 改动说明
-<改了什么、为什么>
-
-## 验证
- [ ] CI 通过（lint + test）
- [ ] 本地测试通过（如有）
-
-## 改动文件
- `src/xxx.py`: <改了什么>
- `tests/test_xxx.py`: <新增什么测试>
-```
-
---
-
 ## §15. @mention 通知迁移

 ### 15.1 当前实现
@@ -650,10 +650,9 @@ async def _handle_pull_request_review(payload: Dict[str, Any]) -> None:
    else:  # REQUEST_CHANGES
        tc_steps = [
            "按审查意见逐条修改代码",
-            "文档同步：如审查涉及设计/接口变更，同步更新 docs/design/ 对应文档",
            "push 到原分支 → CI 自动跑",
            "CI 通过后等重新 Review",
-            "提交 action report（POST http://localhost:8083/api/projects/_toolchain/tasks/<task_id>/comments，comment_type=action_report）— 报告中必须说明文档是否需要更新及处理结果",
+            "提交 action report（POST http://localhost:8083/api/projects/_toolchain/tasks/<task_id>/comments，comment_type=action_report）",
        ]
    _send_toolchain_task(
        to_agent=pr_author,
@@ -1035,11 +1034,10 @@ async def _handle_issues(payload: Dict[str, Any]) -> None:
                steps=[
                    f"在开发目录执行 git 操作：\n  a. git checkout main && git pull origin main\n  b. git checkout -b fix/{issue_number}-{brief}",
                    "编码 + 写 UT",
-                    "文档同步：如果本次改动涉及设计变更或接口变更，在同一分支更新 docs/design/ 对应文档。如无需更新，在 action report 中说明「文档无需更新」",
                    f"git add -A && git commit -m \"[moz] fix: {issue_title[:30]}\" && git push origin fix/{issue_number}-{brief}",
-                    f"CI 通过后创建 PR（Gitea API: POST /repos/{repo}/pulls，head: fix/{issue_number}-{brief}, base: main）— PR body 必须含 Closes #{issue_number}",
+                    f"CI 通过后创建 PR（Gitea API: POST /repos/{repo}/pulls，head: fix/{issue_number}-{brief}, base: main）",
                    "等 Review",
-                    "提交 action report（POST http://localhost:8083/api/projects/_toolchain/tasks/<task_id>/comments，comment_type=action_report）— 报告中必须说明文档是否需要更新及处理结果",
+                    "提交 action report（POST http://localhost:8083/api/projects/_toolchain/tasks/<task_id>/comments，comment_type=action_report）",
                ],
                context_data={
                    "issue_number": issue_number,
@@ -1155,8 +1153,7 @@ async def _handle_issue_comment(payload: Dict[str, Any]) -> None:
            steps=[
                "查看完整 CI 日志（PR 页面或 Gitea Actions 页面）",
                "根据 CI 日志判断失败原因类型：\n  a. 代码问题（lint/test 失败）→ 修复失败的测试 → push 到原分支 → CI 自动重跑\n  b. 基础设施问题（runner 环境/Python/venv/Gitea/网络故障）→ 在该仓库创建 Issue 指派 jiangwei-infra（见下方「需要创建 Issue 时」），label 必须包含 type/infrastructure",
-                "文档同步：如修复涉及设计/接口变更，同步更新 docs/design/ 对应文档",
-                "提交 action report（POST http://localhost:8083/api/projects/_toolchain/tasks/<task_id>/comments，comment_type=action_report）— 报告中说明判断的原因类型和执行的操作，以及文档是否需要更新",
+                "提交 action report（POST http://localhost:8083/api/projects/_toolchain/tasks/<task_id>/comments，comment_type=action_report）— 报告中说明判断的原因类型和执行的操作",
            ],
            context_data={
                "pr_number": issue_number,
@@ -152,7 +152,6 @@ class BootstrapBuilder:
            constraints.extend([
                "- 审查结果必须明确 pass/fail",
                "- 评审意见须附证据（文件:行号）",
-                "- 需求-设计-编码一致性：PR 改动是否和 Issue/设计文档描述一致？如改了实现但 docs/design 未同步更新，在 Review 中指出",
            ])
        elif role == "planner":
            constraints.extend([
@@ -186,11 +186,10 @@ class DeliveryChecklistSection:
    priority: int = 55  # CONSTRAINTS(50) 和 EXTENSION(60) 之间

    CHECKLIST_TEXT = (
-        "## 交付检查（强制）\n"
-        "⚠️ 这是必须执行的步骤，不是提醒。代码改动完成后，以下检查每一项都要有明确结论：\n"
-        "- 改了实现 → docs/design/ 对应设计文档是否需要更新？需要则在同一 PR 中更新\n"
-        "- 改了实现 → tests/ 是否有对应测试脚本需要更新？需要则在同一 PR 中更新\n"
-        "- action report 中必须逐项说明上述检查结果（如「文档无需更新」「测试已补充」）\n"
+        "## 交付检查\n"
+        "完成代码改动前确认：\n"
+        "- 改了实现 → docs/design/ 对应设计文档是否需要更新\n"
+        "- 改了实现 → tests/ 是否有对应测试脚本需要更新\n"
        "- 所有成果物变更通过 PR 流程：PR review 把关设计合理性，CI 把关代码质量，CD 把关部署正确性\n"
    )

@@ -513,7 +513,7 @@ class Ticker:

 ### 三问
 1. Goal 还清晰吗？（是否有 goal drift）
-2. 成果物覆盖 goal 了吗？（逐条检查验收标准 + 确认 docs/design 是否同步更新）
+2. 成果物覆盖 goal 了吗？（逐条检查验收标准）
 3. 下一轮需要做什么？（创建新 sub tasks / 标记完成 / 调整方向）

 ### 失败处理
@@ -248,11 +248,6 @@ class ToolchainConstraintsSection:
            '- 不要使用 Mail API（飞鸽传书）发送消息',
            '- 你的所有操作都在 toolchain 流程内，通过 Gitea 留痕',
            "",
-            "### 6. 文档同步（涉及代码改动时）",
-            '- 改了实现 → 检查 docs/design/ 对应设计文档是否需要更新',
-            '- 改了实现 → 检查 tests/ 是否有对应测试脚本需要更新',
-            '- action report 中必须说明文档是否需要更新及处理结果（如「文档无需更新」）',
-            "",
            "### Red Flags（如果脑海中出现以下想法，说明你错了）",
            "",
            '| Agent 想法 | Red Flag 驳回 |',
@@ -264,7 +259,6 @@ class ToolchainConstraintsSection:
            '| “步骤太多了，选几个做就行” | ❌ 错！必须逐条执行，不可跳过 |',
            '| “这个步骤不适用于当前情况” | ❌ 如果确实不适用，在 action report 中说明原因，但其他步骤必须执行 |',
            '| “CI/部署失败不是我代码的问题，我什么也不用做” | ❌ 错！即使是基础设施问题，你也必须创建 Issue 指派 jiangwei-infra（body 含错误来源链接 + 日志 + 判断依据），并在 action report 中说明。不能只报告“不是我的问题”就完事 |',
-            '| "文档以后再说" | ❌ 错！文档同步和代码改动在同一 PR 中完成，action report 中必须说明文档处理情况 |',
            "",
        ]
        return "\n".join(lines)