@haaaiawd/anws 1.1.0 → 1.2.0

package/templates/.agent/workflows/blueprint.md

@@ -183,9 +183,54 @@ graph TD
 
 ---
 
-## Step 6: 生成文档
+## Step 5.5: User Story Overlay (交叉验证)
+
+**目标**: 从**用户价值维度**验证任务完备性。WBS 按系统拆解，这一步从 User Story 视角交叉检查。
+
+> [!IMPORTANT]
+> **User Story Overlay 是覆盖率安全网**
+>
+> WBS 确保每个系统都有任务，但无法保证每个用户故事都能端到端跑通。
+> 这一步能捕获"系统内任务齐全，但跨系统 User Story 链断裂"的问题。
+
+### 执行步骤
+
+1. **读取 PRD 的 User Stories**: 从 `{TARGET_DIR}/01_PRD.md` 提取所有 `US-XXX`
+2. **构建映射**: 将每个 US 涉及的系统 → 对应的 tasks（通过 REQ 追溯 + 系统归属匹配）
+3. **验证三项闭环**:
+   - 每个 US 是否有足够的 tasks 覆盖其**所有涉及系统**？
+   - 每个 US 的 task 链是否能形成**可独立验证**的闭环？
+   - 高优先级 US (P0) 的 task 是否分布在靠前的 Sprint？
+
+4. **生成 User Story View**: 追加到 `05_TASKS.md` 末尾
+
+### User Story View 格式
+
+```markdown
+## 🎯 User Story Overlay
+
+### US-001: [标题] (P1)
+**涉及任务**: T2.1.1 → T2.1.2 → T7.2.1 → T6.1.2
+**关键路径**: T2.1.1 → T2.1.2 → T7.2.1
+**独立可测**: ✅ S1 结束即可演示
+**覆盖状态**: ✅ 完整
+
+### US-003: [标题] (P2)
+**涉及任务**: T3.2.1
+**关键路径**: T3.1.1 → T3.2.1
+**独立可测**: ❌ 缺少 T4.x 衔接
+**覆盖状态**: ⚠️ 不完整 — 缺少 executor 侧任务
+```
+
+### 覆盖 GAP 处理
+
+- 如有不完整的 US → 在 Overlay 中标注 `⚠️`，并在任务清单中补充缺失的 task
+- 如有 US 的 task 全部在后期 Sprint → 建议前移部分 task 以实现早期验证
+- 补充的 task 必须遵守 Step 2 的任务格式模板
+
+---
 
-**目标**: 保存最终的任务清单，并**更新 AGENTS.md**。
+## Step 6: 生成文档
 
 **目标**: 保存最终的任务清单，并**更新 .agent/rules/agents.md**。
 
@@ -208,6 +253,7 @@ graph TD
 - ✅ 每个任务是否有 Context 和 Acceptance Criteria？
 - ✅ 任务间的输入/输出是否对齐（接口追溯）？
 - ✅ 是否生成了 Mermaid 依赖图？
+- ✅ User Story Overlay 已生成，覆盖 GAP 已补充？
 - ✅ 已更新 .agent/rules/agents.md（含初始波次建议）？
 
 ---
@@ -234,6 +280,23 @@ graph TD
 
 ---
 
+### Agent Context 自更新
+
+**更新 `.agent/rules/agents.md` 的 `AUTO:BEGIN` ~ `AUTO:END` 区块**:
+
+在 `### 当前任务状态` 下写入：
+
+```markdown
+### 当前任务状态
+- 任务清单: genesis/v{N}/05_TASKS.md
+- 总任务数: {N}, P0: {X}, P1: {Y}, P2: {Z}
+- Sprint 数: {S}
+- Wave 1 建议: T{X.Y.Z}, T{X.Y.Z}, T{X.Y.Z}
+- 最近更新: {Today}
+```
+
+---
+
 <completion_criteria>
 - ✅ 定位到最新架构版本 `v{N}`
 - ✅ 任务清单 `05_TASKS.md` 已生成
@@ -241,6 +304,17 @@ graph TD
 - ✅ 任务间输入/输出已对齐（接口追溯）
 - ✅ 每个 Sprint 有退出标准和 INT 集成验证任务
 - ✅ 生成了 Mermaid 依赖图
+- ✅ User Story Overlay 已生成并验证覆盖完整性
 - ✅ 已更新 .agent/rules/agents.md（含初始波次建议）
+- ✅ 更新了 agents.md AUTO:BEGIN 区块 (当前任务状态)
 - ✅ 用户已确认
-</completion_criteria>
+</completion_criteria>
+
+---
+
+## 🔀 Handoffs
+
+完成本工作流后，根据情况选择：
+
+- **质疑设计与任务** → `/challenge` — 对设计和任务清单进行系统性审查
+- **开始编码执行** → `/forge` — 按任务清单开始波次执行

package/templates/.agent/workflows/challenge.md

@@ -133,108 +133,65 @@ description: 对项目决策进行系统性挑战，通过三维度审查框架
 
 ---
 
-## Step 3: 三维度审查 (Three-Dimensional Review)
+## Step 2.5: 审查模式判定 (Review Mode Detection)
 
-**目标**: 从系统设计、运行模拟、工程实现三个维度逐一审查，**每个质疑都要有据可依**。
+**目标**: 在开始任何审查之前，先确定**本次应该审查什么**——避免无脑双跑。
 
-> [!IMPORTANT]
-> 你**必须**按照以下三个维度进行审查：
->
-> **维度1: 系统设计** - 架构完整性、边界清晰度、一致性
-> **维度2: 运行模拟** - 时序正确性、状态同步、边界条件  
-> **维度3: 工程实现** - 可测试性、可维护性、性能、安全
+根据上下文信号推断模式：
 
-### 3.1 系统设计维度审查
+| 信号 | 推断模式 |
+|------|---------|
+| `05_TASKS.md` 不存在 | `DESIGN` — 只能审查设计 |
+| 用户明确提到任务/任务清单有问题 | `TASKS` |
+| 用户明确说「全面审查」或「都看看」 | `FULL` |
+| `05_TASKS.md` 存在，但用户无明确指向 | `DESIGN`，任务审查**按需自适应升级** |
+| 本轮是修复后的复查，上轮有任务类问题 | `FULL` |
 
-**目标**: 检查架构的完整性和一致性
+**如果模式仍不明确，直接询问用户**：
 
-**审查重点**:
-1. **架构一致性**: 不同文档中的系统描述是否一致？
-2. **边界清晰度**: 每个系统的职责边界是否清晰？有无重叠或遗漏？
-3. **依赖合理性**: 系统间依赖关系是否合理？有无循环依赖？
-4. **接口完整性**: 跨系统接口是否完整定义？
-5. **状态管理**: 系统状态变化是否有明确定义？
+> 本次审查侧重什么？
+> 1. **设计/架构**（design-reviewer）— 架构完整性、接口、运行时行为
+> 2. **任务清单**（task-reviewer）— 任务质量、REQ 覆盖、US 完整性
+> 3. **全面审查**（两者都跑）
 
-**思考引导**:
-1. "这个架构设计背后的核心假设是什么？"
-2. "如果假设不成立会怎样？"
-3. "系统边界定义中有没有歧义或矛盾？"
-4. "接口设计是否考虑了所有边界情况？"
-5. "状态转换是否有清晰的规则？"
+**设置** `REVIEW_MODE` = `DESIGN` / `TASKS` / `FULL`，后续步骤依据此值触发。
 
-### 3.2 运行模拟维度审查
+---
 
-**目标**: 在脑中"运行"系统，发现时序和状态问题
+## Step 3: 设计审查 (Design Review)
 
-> [!IMPORTANT]
-> 你**必须**使用 `sequentialthinking` 进行 **3-5 步**思考。
-> 
-> **为什么？** 运行时问题往往隐藏很深，需要快速模拟推演。复杂情况可循环。
+**触发条件**: `REVIEW_MODE` = `DESIGN` 或 `FULL`
 
-**审查重点**:
-1. **时序一致性**: 时序模型是否自洽？有无"先后顺序"矛盾？
-2. **状态同步**: 分布式状态如何同步？会不会出现不一致？
-3. **并发处理**: 并发操作如何处理？有无竞态条件？
-4. **边界条件**: "空状态"、"满状态"、"异常状态"如何处理？
-5. **故障传播**: 一个组件失败会如何影响其他组件？
+> 如果 `REVIEW_MODE` = `TASKS`，**跳过本步骤**，直接进入 Step 3.5。
 
-**思考引导**:
-1. "如果我跟踪一个典型操作的完整流程，会经过哪些步骤？"
-2. "在每个步骤，系统状态如何变化？"
-3. "如果某个步骤失败，系统会处于什么状态？"
-4. "两个并发操作会如何相互影响？"
-5. "边界条件下系统行为是否定义清楚？"
+调用 `design-reviewer` skill：
+- 输入: `{TARGET_DIR}` 下的 `01_PRD.md`, `02_ARCHITECTURE_OVERVIEW.md`, `03_ADR/`, `04_SYSTEM_DESIGN/`
+- 输出: 设计审查发现清单（含严重度分级 + 文档关联）
 
-### 3.3 工程实现维度审查
+**收集发现**，暂存待 Step 5 合并。
 
-**目标**: 检查设计的可实现性和工程质量
+---
 
-> [!IMPORTANT]
-> 你**必须**使用 `sequentialthinking` 进行 **3-5 步**思考。
-> 
-> **为什么？** 好的设计必须是可实现、可测试、可维护的。
-
-**审查重点**:
-1. **可测试性**: 设计是否便于编写测试？关键逻辑能否单元测试？
-2. **可维护性**: 代码结构是否清晰？修改是否容易？
-3. **性能**: 有无明显的性能瓶颈？
-4. **安全性**: 有无安全漏洞？敏感数据如何保护？
-5. **可观测性**: 如何监控和调试？日志是否充分？
-
-**思考引导**:
-1. "这个设计如何编写单元测试？"
-2. "如果需要修改某个功能，影响范围有多大？"
-3. "有哪些潜在的性能瓶颈？"
-4. "敏感数据（密钥、用户信息）如何保护？"
-5. "系统出问题时如何快速定位？"
-
-**问题分级标准**:
-- **Critical**: 根本性矛盾，不解决无法实现
-- **High**: 严重问题，会导致功能失效或重大返工
-- **Medium**: 中等问题，影响质量但有变通方案
-- **Low**: 轻微问题，优化空间
-
-**输出格式**：
-```markdown
-### [维度] - [问题编号]: [问题标题]
+## Step 3.5: 任务审查 (Task Review)
 
-**严重度**: Critical / High / Medium / Low  
-**文档**: [具体文档位置]
+**触发条件**（满足任一即执行，`05_TASKS.md` 必须存在）：
 
-**问题描述**:
-[详细描述问题，引用具体代码或设计]
+1. `REVIEW_MODE` = `TASKS` 或 `FULL`
+2. **自适应升级**：`REVIEW_MODE` = `DESIGN`，且 design-reviewer 的发现满足以下任一条件：
+   - 存在「架构组件在任务中无覆盖」类问题（对应 task-reviewer Pass D2）
+   - Critical/High 级设计问题超过 3 条，需确认是否已有任务跟进
 
-**证据来源**: 
-- 文档分析: [PRD/Architecture/ADR 中的具体内容]
-- 推理过程: [基于 sequentialthinking 的分析]
-- 类比参考: [类似系统的已知问题]
+**自适应升级时，询问用户**：
 
-**影响**:
-- [如果问题成真的具体后果]
+> 设计审查发现 {N} 个问题可能涉及任务覆盖不足，是否追加任务审查？
+> 1. 是，追加 task-reviewer
+> 2. 否，继续
 
-**建议**:
-[如何验证或解决，可提供多个方案]
-```
+如触发，调用 `task-reviewer` skill：
+- 输入: `{TARGET_DIR}` 下的 `05_TASKS.md`, `01_PRD.md`, `02_ARCHITECTURE_OVERVIEW.md`, `03_ADR/`
+- 输出: 任务审查报告（6-Pass + REQ 覆盖率 + US 完整性 + 问题清单）
+
+**收集发现**，暂存待 Step 5 合并。如跳过，记录 `Task review skipped`（附原因）。
 
 ---
 
@@ -340,11 +297,12 @@ description: 对项目决策进行系统性挑战，通过三维度审查框架
 
 ## 🎯 审查方法论
 
-本次审查采用三维度分析框架:
+本次审查模式: **{REVIEW_MODE}**（DESIGN / TASKS / FULL）
 
-1. **系统设计维度** - 架构完整性、边界清晰度、一致性
-2. **运行模拟维度** - 时序正确性、状态同步、边界条件
-3. **工程实现维度** - 可测试性、可维护性、性能、安全
+1. **设计审查** (design-reviewer skill) — {执行 / 跳过} — 系统设计 / 运行模拟 / 工程实现 三维度
+2. **任务审查** (task-reviewer skill) — {执行 / 跳过 / 自适应升级} — 重复 / 歧义 / 欠详述 / 不一致 / 覆盖率 / 质量粒度 六大 Pass
+3. **Pre-Mortem** — 预演失败 + 假设验证
+4. **合并评定** — 统一严重度分级 + 综合判断
 
 ---
 
@@ -362,9 +320,9 @@ description: 对项目决策进行系统性挑战，通过三维度审查框架
 
 | 维度 | 问题数 |
 |------|--------|
-| 系统设计 | X |
-| 运行模拟 | X |
-| 工程实现 | X |
+| 设计审查 (design-reviewer) | X |
+| 任务审查 (task-reviewer) | X |
+| Pre-Mortem + 假设验证 | X |
 
 ---
 
@@ -484,3 +442,12 @@ description: 对项目决策进行系统性挑战，通过三维度审查框架
 - ✅ 上一轮已解决问题的详情已归档（仅保留总览行）
 - ✅ 用户已阅读并决定下一步
 </completion_criteria>
+
+---
+
+## 🔀 Handoffs
+
+完成本工作流后，根据情况选择：
+
+- **修复发现的问题** → `/change` — 根据 challenge 报告修复问题 *(存在需要修复的问题时)*
+- **开始编码执行** → `/forge` — 无阻塞问题，开始波次执行 *(无 CRITICAL 问题时)*

package/templates/.agent/workflows/change.md

@@ -292,3 +292,11 @@ description: 处理微调级变更请求，通过 7 问题法严格评估，仅
 - ✅ 未创建任何新任务
 - ✅ 未添加任何 AI 自认为好的功能
 </completion_criteria>
+
+---
+
+## 🔀 Handoffs
+
+完成本工作流后，根据情况选择：
+
+- **继续编码执行** → `/forge` — 变更完成，继续波次执行

package/templates/.agent/workflows/craft.md

@@ -623,4 +623,12 @@ description: [一句话描述]
 
 ---
 
+## 🔀 Handoffs
+
+完成本工作流后，根据情况选择：
+
+- **测试新创建的工作流** → `/quickstart` — 用 quickstart 流程测试新工作流 *(创建完成后需要验证时)*
+
+---
+
 // turbo-all

package/templates/.agent/workflows/design-system.md

@@ -353,47 +353,93 @@ description: 为单个系统设计详细的技术文档，通过调研最佳实
 **目标**: 使用模板产出完整的系统设计文档
 
 > [!IMPORTANT]
-> 你**必须**使用 `.agent/skills/system-designer/references/system-design-template.md` 模板。
->
-> **为什么？** 统一结构，保证文档质量和完整性。
+> 本步骤最多产出**两个文件**：
+> - **必须**: `{system-id}.md`（L0 导航层）
+> - **按需**: `{system-id}.detail.md`（L1 实现层，当触发 R1-R5 任意一条时）
 
 **步骤**:
 
+### 5.0 拆分检测（Split Detection）
+
+> [!IMPORTANT]
+> **在加载模板之前，先评估是否需要创建 L1 文件。**
+
+检查本次设计草稿是否触发了以下任意一条规则：
+
+| 规则   | 检测项                              | 触发？ |
+| ------ | ----------------------------------- | :----: |
+| **R1** | 任何单个函数/算法伪代码 > 30 行     |  ✅/❌   |
+| **R2** | 所有代码块合计行数 > 200 行         |  ✅/❌   |
+| **R3** | 含配置常量字典且条目 > 5 个         |  ✅/❌   |
+| **R4** | 版本历史注释（`# vX.X 变更`）> 5 处 |  ✅/❌   |
+| **R5** | 预计文档总行数 > 500 行             |  ✅/❌   |
+
+**决策**:
+- 任意触发 → **是**: 创建两个文件（L0 + L1）
+- 全部未触发 → **否**: 只创建一个文件（L0）
+
+*Self-Correction*: "我这个系统触发了 {规则列表}，需要/不需要 detail 文件。"
+
+---
+
 ### 5.1 加载模板
+
+**加载 L0 模板**（必须）:
 读取 `.agent/skills/system-designer/references/system-design-template.md`
 
+**加载 L1 模板**（如果 5.0 决策为「需要」）:
+读取 `.agent/skills/system-designer/references/system-design-detail-template.md`
+
+---
+
 ### 5.2 填充内容
 
-**必需章节**（必须填写）:
+**L0 必需章节**（填入 `{system-id}.md`，必须填写）:
 1. 概览 (Overview)
 2. 目标与非目标 (Goals & Non-Goals)
 3. 背景与上下文 (Background & Context)
-4. 系统架构 (Architecture) - 包含架构图
-5. 接口设计 (Interface Design)
-6. 数据模型 (Data Model)
+4. 系统架构 (Architecture) - 包含 Mermaid 架构图
+5. **接口设计 (Interface Design)** — 用**操作契约表格**代替函数伪代码（见 SKILL.md 守则7）
+6. **数据模型 (Data Model)** — 只放**属性字段声明**，不写方法体（见 SKILL.md 守则8）
 7. 技术选型 (Technology Stack)
 8. **Trade-offs & Alternatives** ⭐ 核心
 9. 安全性考虑 (Security Considerations)
 10. 性能考虑 (Performance Considerations)
 11. 测试策略 (Testing Strategy)
 
-**可选章节**（小项目可简化）:
-12. 部署与运维 (Deployment & Operations) - 可简化
-13. 未来考虑 (Future Considerations) - 可省略
-14. 附录 (Appendix) - 可省略
+**L0 可选章节**（小项目可简化）:
+12. 部署与运维 (Deployment & Operations)
+13. 未来考虑 (Future Considerations)
+14. 附录 (Appendix)
+
+**L1 章节**（填入 `{system-id}.detail.md`，仅当 5.0 决策为「需要」）:
+- §1 配置常量（UNIT_CONFIG 等字典/表格）
+- §2 完整数据结构（含方法体的 @dataclass）
+- §3 核心算法伪代码（完整函数体，按操作契约表格对应）
+- §4 决策树详细逻辑（对应 L0 Mermaid 图的展开）
+- §5 边缘情况与注意事项（从旧文档 `# ⚠️ 注意` 类注释提取）
+- 版本历史表格（集中放在 L1 末尾）
 
 **关键要求**:
-- **架构图**: 必须使用Mermaid绘制
-- **Trade-offs**: 每个重要技术选型都要说明"为什么选A不选B"
-- **追溯链**: 在相关章节引用PRD需求 [REQ-XXX]
-- **约束继承**: 从PRD和ADR继承约束
+- **L0 架构图**: 必须使用 Mermaid 绘制
+- **L0 决策树**: 用 Mermaid `flowchart TD`，不用伪代码
+- **Trade-offs**: 每个重要技术选型都要说明"为什么选 A 不选 B"
+- **追溯链**: 在相关章节引用 PRD 需求 [REQ-XXX]
+- **约束继承**: 从 PRD 和 ADR 继承约束
+
+---
 
 ### 5.3 保存文档
+
+**保存 L0 文件**（必须）:
 将内容保存到 `genesis/v{N}/04_SYSTEM_DESIGN/{system-id}.md`
 
+**保存 L1 文件**（如果 5.0 决策为「需要」）:
+将内容保存到 `genesis/v{N}/04_SYSTEM_DESIGN/{system-id}.detail.md`
+
 **示例路径**:
-- `genesis/v{N}/04_SYSTEM_DESIGN/frontend-system.md`
-- `genesis/v{N}/04_SYSTEM_DESIGN/backend-api-system.md`
+- L0: `genesis/v{N}/04_SYSTEM_DESIGN/core.md`
+- L1: `genesis/v{N}/04_SYSTEM_DESIGN/core.detail.md`
 
 ---
 
@@ -453,6 +499,21 @@ description: 为单个系统设计详细的技术文档，通过调研最佳实
 
 ---
 
+### Agent Context 自更新
+
+**更新 `.agent/rules/agents.md` 的 `AUTO:BEGIN` ~ `AUTO:END` 区块**:
+
+在 `### 系统边界` 下追加或更新当前设计系统的信息：
+
+```markdown
+### 系统边界
+- {system-id}: {一句话职责} — 详细设计见 `genesis/v{N}/04_SYSTEM_DESIGN/{system-id}.md`
+```
+
+> 仅追加，不覆盖已有系统的条目（除非同一 system-id 有更新值）。
+
+---
+
 <completion_criteria>
 - ✅ 系统ID已确认
 - ✅ 上下文已加载（PRD + Architecture Overview + 相关ADR）
@@ -460,6 +521,7 @@ description: 为单个系统设计详细的技术文档，通过调研最佳实
 - ✅ 调研已完成 (/explore)
 - ✅ 设计已完成 (sequentialthinking 5-7步)
 - ✅ 文档已生成 (使用模板)
+- ✅ 更新了 agents.md AUTO:BEGIN 区块 (系统边界)
 - ✅ 用户已确认
 </completion_criteria>
 
@@ -494,4 +556,13 @@ A: 结构保持一致，但可以简化内容。可省略章节: 13 (未来考
 
 ---
 
+## 🔀 Handoffs
+
+完成本工作流后，根据情况选择：
+
+- **生成任务清单** → `/blueprint` — 将架构拆解为可执行任务
+- **质疑设计决策** → `/challenge` — 对当前系统设计进行系统性挑战
+
+---
+
 // turbo-all

package/templates/.agent/workflows/explore.md

@@ -1,5 +1,6 @@
 ---
 description: 深度探索复杂问题，通过"向外搜索 + 向内发散"双向螺旋产出结构化洞察，适用于技术调研、方案选型和头脑风暴。
+
 ---
 
 # /explore
@@ -304,4 +305,12 @@ description: 深度探索复杂问题，通过"向外搜索 + 向内发散"双
 
 ---
 
+## 🔀 Handoffs
+
+完成本工作流后，根据情况选择：
+
+- **将调研结果应用到项目** → `/genesis` — 基于调研结论启动或更新项目架构 *(调研结论需要落地时)*
+
+---
+
 // turbo-all

package/templates/.agent/workflows/forge.md

@@ -136,11 +136,11 @@ description: 按照架构文档和任务清单将设计锻造为代码，通过
 
 按以下策略组织一个波次:
 
-| 策略 | 说明 |
-|------|------|
-| **同系统优先** | 属于同一 System 的任务分到一波（共享上下文） |
-| **文档依赖收敛** | 引用相同文档的任务分到一波（减少加载量） |
-| **2-5 个/波** | 过多→上下文溢出；过少→效率低 |
+| 策略             | 说明                                         |
+| ---------------- | -------------------------------------------- |
+| **同系统优先**   | 属于同一 System 的任务分到一波（共享上下文） |
+| **文档依赖收敛** | 引用相同文档的任务分到一波（减少加载量）     |
+| **2-5 个/波**    | 过多→上下文溢出；过少→效率低                 |
 
 ### 1.3 波次确认
 
@@ -149,10 +149,10 @@ description: 按照架构文档和任务清单将设计锻造为代码，通过
 ```markdown
 ## 📋 Wave {N} 建议
 
-| 任务 ID | 标题 | 依赖文档 | 估时 |
-|---------|------|---------|:----:|
-| T{X.Y.Z} | ... | `04_SYSTEM_DESIGN/core.md` §... | Xh |
-| ... | ... | ... | ... |
+| 任务 ID  | 标题 | 依赖文档                        | 估时  |
+| -------- | ---- | ------------------------------- | :---: |
+| T{X.Y.Z} | ...  | `04_SYSTEM_DESIGN/core.md` §... |  Xh   |
+| ...      | ...  | ...                             |  ...  |
 
 **波次总估时**: ~Xh
 **需加载文档**: [文档列表]
@@ -182,13 +182,23 @@ T{X.Y.Z}, T{X.Y.Z}, T{X.Y.Z}
 
 ### 加载层级
 
-| 层级 | 内容 | 目的 |
-|:----:|------|------|
-| **L0 全局** | `02_ARCHITECTURE_OVERVIEW.md` — 仅系统清单和总体架构图部分 | 定位感 |
-| **L1 波级** | 本波涉及系统的 `04_SYSTEM_DESIGN/{system}.md` + 相关 ADR | 设计规范 |
-| **L2 任务级** | 每个任务的 `**输入**` 字段指定的精确文档章节 | 实现细节 |
+|      层级       | 内容                                                                     | 目的                 |
+| :-------------: | ------------------------------------------------------------------------ | -------------------- |
+|   **L0 全局**   | `02_ARCHITECTURE_OVERVIEW.md` — 仅系统清单和总体架构图部分               | 定位感               |
+|   **L1 波级**   | 本波涉及系统的 `04_SYSTEM_DESIGN/{system}.md`（L0 导航层）+ 相关 ADR     | 设计规范、接口契约   |
+| **L1.5 实现级** | 本波任务 `**输入**` 字段中明确引用的 `{system}.detail.md` **对应 §章节** | 算法伪代码、配置常量 |
+|  **L2 任务级**  | 每个任务的 `**输入**` 字段指定的精确文档章节                             | 实现细节             |
 
-**L2 在 Step 3 的每个任务开始时按需加载，不在此处全部加载。**
+> [!IMPORTANT]
+> **L1.5 加载规则（CRITICAL）**:
+>
+> - `{system}.md`（L0 导航层）**始终加载** ← 这是默认行为
+> - `{system}.detail.md`（L1 实现层）**仅当任务 `**输入**` 字段明确引用时才加载**
+> - 如果任务 `**输入**` 写的是 "`core.md` §战斗系统" → 只加载 `core.md` 对应章节
+> - 如果任务 `**输入**` 写的是 "`core.detail.md` §3.5" → 才加载 `core.detail.md` 对应章节
+> - **禁止**"以防万一"加载整个 `.detail.md`
+
+**L1.5 在 Step 3 的每个任务开始时按需加载，不在此处全部加载。**
 
 ### 加载步骤
 
@@ -249,21 +259,36 @@ T{X.Y.Z}, T{X.Y.Z}, T{X.Y.Z}
 
 ### 3.4 验证 (Verify)
 
-**逐条验证验收标准**:
+**逐条验证验收标准**，并按类型分类证据:
+
+> [!IMPORTANT]
+> **验收标准分为两类，处理方式不同**:
+>
+> | 类型 | 标记 | 要求 |
+> |------|:----:|------|
+> | 🔧 可执行验证 | ✅/❌ | 必须实际运行命令/测试，贴出终端输出作为证据 |
+> | 👁️ 需人工确认 | ⏳ | 不允许 AI 自行判定为 ✅，标记为 ⏳ 等待用户确认 |
 
 ```markdown
 ### ✅ 验证报告: T{X.Y.Z}
 
-| 验收标准 | 状态 | 证据 |
-|---------|:----:|------|
-| [验收标准1] | ✅/❌ | [如何验证的] |
-| [验收标准2] | ✅/❌ | [如何验证的] |
+**可执行验证**:
+| 验收标准 | 命令/检查     | 输出摘要                    | 状态  |
+| -------- | ------------- | --------------------------- | :---: |
+| 启动正常 | `npm run dev` | Server running on port 3000 |   ✅   |
+| 测试通过 | `npm test`    | 12 passed, 0 failed         |   ✅   |
+
+**需人工确认**:
+| 验收标准     | 说明                       | 状态  |
+| ------------ | -------------------------- | :---: |
+| 页面显示正确 | 需要打开浏览器确认渲染效果 |   ⏳   |
 ```
 
 按任务的 `**验证说明**` 字段执行检查。
 
-- 全部 ✅ → 继续 3.5
-- 有 ❌ → **修复后重新验证**，不得跳过
+- 可执行验证全部 ✅ 且无人工确认项 → 继续 3.5
+- 可执行验证全部 ✅ 但有人工确认项 → 继续 3.5（人工项随后确认）
+- 可执行验证有 ❌ → **修复后重新验证**，不得跳过
 
 ---
 
@@ -271,13 +296,15 @@ T{X.Y.Z}, T{X.Y.Z}, T{X.Y.Z}
 
 **检查清单** (每条都要回答):
 
-| # | 检查项 | 通过？ |
-|---|--------|:-----:|
-| 1 | 代码接口与 SYSTEM_DESIGN 定义一致？ | ✅/❌ |
-| 2 | 未引入 ADR 未批准的依赖？ | ✅/❌ |
-| 3 | 未添加任务范围外的功能？ | ✅/❌ |
-| 4 | 代码风格与项目一致，lint 通过？ | ✅/❌ |
-| 5 | 所有验收标准已验证通过？ | ✅/❌ |
+| #   | 检查项                              | 通过？ |
+| --- | ----------------------------------- | :----: |
+| 1   | 代码接口与 SYSTEM_DESIGN 定义一致？ |  ✅/❌   |
+| 2   | 未引入 ADR 未批准的依赖？           |  ✅/❌   |
+| 3   | 未添加任务范围外的功能？            |  ✅/❌   |
+| 4   | 代码风格与项目一致，lint 通过？     |  ✅/❌   |
+| 5   | 所有验收标准已验证通过？            |  ✅/❌   |
+| 6   | 所有可执行验收标准有终端输出证据？  |  ✅/❌   |
+| 7   | 需人工确认的验收标准已标记 ⏳？      |  ✅/❌   |
 
 - 全部 ✅ → 继续 3.6
 - 有 ❌ → **修复**
@@ -290,8 +317,16 @@ T{X.Y.Z}, T{X.Y.Z}, T{X.Y.Z}
    - 消息格式: `feat(system-id): T{X.Y.Z} — 任务标题`
    - 例: `feat(core): T2.1.1 — 地形与资源数据模型`
 
-2. **更新 05_TASKS.md**:
-   将该任务的 `- [ ]` 改为 `- [x]`
+2. **任务完成持久化** (立即回写):
+
+   > [!IMPORTANT]
+   > **每完成一个 task 并通过验证，立即回写 `05_TASKS.md`**。
+   > 这是进度持久化的核心机制——即使 AI 上下文丢失或会话崩溃，
+   > 下次加载 TASKS.md 就能看到精确进度。
+   > 配合 agents.md 的 Wave 块形成**双层恢复机制**: 粗粒度(Wave) + 细粒度(Task checkbox)。
+
+   - 将该任务的 `- [ ]` 改为 `- [x]`
+   - 确保回写后的 `05_TASKS.md` 与实际进度一致
 
 3. **继续下一个任务** → 回到 3.1
 
@@ -361,3 +396,12 @@ chore: Wave {N} settlement — update task progress
 - ✅ .agent/rules/agents.md 当前状态已更新
 - ✅ 用户已确认波次完成
 </completion_criteria>
+
+---
+
+## 🔀 Handoffs
+
+完成本工作流后，根据情况选择：
+
+- **微调任务** → `/change` — 发现问题需要微调任务 *(执行中发现任务描述不准确时)*
+- **质量审查** → `/challenge` — 完成阶段后对成果进行审查 *(完成一个 Sprint 后可选)*