fix(design): §17 M1 §5.2 三分路展开 + M2 约束编号 #5 + S1/S2 一致性

docs/design/17-toolchain-handler-enforcement.md

@@ -222,7 +222,7 @@ class ToolchainContextSection:
 - action report 就是你的完成凭证
 - 不要发送 Mail（飞鸽传书），你的所有操作在 toolchain 流程内完成
 
-### 6. 所有协作通过 Gitea 完成
+### 5. 所有协作通过 Gitea 完成
 - 如果遇到问题需要其他角色支持，在关联的 PR/Issue 上创建 comment @对方
 - 不要使用 Mail API（飞鸽传书）发送消息
 - 你的所有操作都在 toolchain 流程内，通过 Gitea 留痕
@@ -373,11 +373,25 @@ def verify_completion(self, task_id: str, db_path: Path) -> VerifyResult:
 
 ### 5.2 on_failure 处理
 
-verify 失败时的处理逻辑（现有逻辑保留）：
+**设计原则**：toolchain 事件全生命周期在 toolchain 流程内闭环，不走 Mail API。失败本身按错误类型分类，路由到不同的 Gitea 管理动作。
 
-1. 标 task 为 `failed`
-2. 通过 on_failure 三分路处理（PR comment / Gitea Issue / toolchain task）
-3. 通知内容包含：事件类型、事件详情、失败原因、Gitea 链接、行动指引
+#### 错误分类三分路
+
+| 错误类型 | 例子 | 处理方式 | 管道 |
+|---------|------|---------|------|
+| **业务失败** | verify 不过（no action_report）、Agent 忽略步骤 | 在关联 PR/Issue 上创建 comment @原始 assignee | Gitea webhook → §25 @mention → toolchain task |
+| **系统失败** | spawner crash、timeout、max_retries、业务失败连续 3 次 | 创建 Gitea Issue 指派 pangtong-fujunshi | Gitea webhook → issue_assigned → toolchain task |
+| **基础设施失败** | Gitea API 不可用、网络不通 | `_send_toolchain_task` 直接创建 toolchain task 指派 jiangwei-infra | toolchain 内部直接创建 |
+
+三条路全在 toolchain 流程内，Mail 完全不参与。
+
+#### 防递归保护
+
+基础设施失败创建的 toolchain task（action_type=infrastructure_failure），其 verify_completion 始终返回 `VerifyResult(True)`，不再触发 on_failure。
+
+#### 完整设计
+
+三分路的详细伪代码、失败上限、决策依据见 §5.2.1~§5.2.3（on_failure 分路处理详细设计）。
 
 ### 5.3 action_report comment 格式
 
@@ -421,7 +435,7 @@ Agent 可能写了 action_report 但没真做。缓解机制：
 | Issue 指派 → 开发者 | issue_assigned | toolchain | 6 步 | 创建分支 + 编码 + push + CI + PR + report |
 | 部署失败 → 运维 | deploy_failure | toolchain | 4 步 | 查日志 + 排查 + 修+重部署 + report |
 | @mention → 被@者 | mention | toolchain | 按 guidance | 按 mention 模板的 response_guidance + report |
-| PR 合并 → PR 作者 | review_merged | toolchain | 0 步 | 纯通知，走 Gitea PR comment（verify 始终通过） |
+| PR 合并 → PR 作者 | review_merged | toolchain | 0 步 | 纯通知，走 _send_toolchain_task（steps 为空，verify 始终通过） |
 
 **D17-2: 所有 toolchain 场景走 ToolchainHandler**
 
@@ -561,6 +575,8 @@ context:
 
 **实现差异**：review_merged 的 verify_completion 始终通过（`VerifyResult(True)`），不需要 action_report。这是 ToolchainHandler 内部的语义区分，不影响 MailHandler。
 
+**spawn 说明**：review_merged 仍会触发 spawn（Agent 只需阅读通知），verify auto-pass 后标 done。未来可优化为 ticker 直接 auto-done 跳过 spawn。
+
 ---
 
 ## §7. _send_toolchain_task 函数设计