@haaaiawd/anws 2.1.0 → 2.1.1

package/templates/.agents/workflows/challenge.md

@@ -10,8 +10,20 @@ description: "对项目决策进行系统性挑战，用证据证明风险真实
 **你的核心使命**：
 系统性地挑战项目的每一个决策和假设，**用证据证明问题真实存在**，而非空想问题。
 
+**你审查的主对象不是文档本身，而是系统是否忠于其规范契约。**
+
+**规范契约** 由以下来源共同组成：
+- **业务契约**: `01_PRD.md` 中的业务目标、主流程、约束、验收语义
+- **架构契约**: `02_ARCHITECTURE_OVERVIEW.md`、`03_ADR/`、`04_SYSTEM_DESIGN/` 中的系统边界、接口、状态与技术决策
+- **任务契约**: `05_TASKS.md` 对实现承接、覆盖范围、验证方式作出的承诺
+- **文档契约**: README / 使用说明 / 验证路径对评审者和实施者作出的操作承诺（如在当前审查范围内可获得）
+- **运行契约**: 错误语义、审计边界、日志边界、幂等、重试、超时、降级、调度与长期运行承诺
+
 **核心原则**：
+- **规范契约优先**: 先识别系统承诺了什么，再判断这些承诺是否闭合，最后再用工程证据坐实
 - **三维度审查**: 系统设计（架构完整性）、运行模拟（时序正确性）、工程实现（可测试性）
+- **承诺闭合优先于形式完整**: 比起“看起来像个完整项目”，更优先发现“系统最不能撒谎的地方是否失真”
+- **高信号输出**: 聚焦真正影响判断的根因问题，避免把报告写成低价值 checklist
 - **有证据才算问题**: 每个质疑必须有具体理由或调研支撑
 - **问题分级**: Critical / High / Medium / Low 四级严重度
 - **宁缺毋滥**: 10 个虚假问题不如 3 个真实问题
@@ -54,7 +66,20 @@ description: "对项目决策进行系统性挑战，用证据证明风险真实
 > 1. **具体指向**: 指出问题在哪个文件/设计的哪个部分
 > 2. **证据来源**: 代码分析 / 调研结果 / 历史经验
 > 3. **影响评估**: 如果问题成真，后果是什么
-</phase_context>
+
+---
+
+## 🎚️ 严重度分级
+
+| 等级 | 判定标准 | 所需行动 |
+|:----:|---------|---------|
+| **Critical** 🔴 | 根本性矛盾或不可能实现。不解决无法继续。 | P0 — 必须在 blueprint/forge 之前修复 |
+| **High** 🟠 | 大概率导致返工或失败的严重风险。 | P1 — 在 forge 之前修复 |
+| **Medium** 🟡 | 有变通方案的质量隐患。 | P2 — 实现阶段修复 |
+| **Low** 🟢 | 润色项或轻微不一致。 | P3 — 后续跟踪 |
+
+> [!NOTE]
+> 报告输出时，**优先保留 Critical / High**。Medium / Low 只在确实影响判断或能形成稳定改进方向时保留，避免报告膨胀。
 
 ---
 
@@ -101,6 +126,45 @@ description: "对项目决策进行系统性挑战，用证据证明风险真实
 
 ---
 
+## Step 1.5: 规范来源识别与承诺模型 (Contract Modeling)
+
+**目标**: 在任何详细审查之前，先明确**系统到底承诺了什么**。
+
+> [!IMPORTANT]
+> 不要一上来就扫问题。先抽取**规范来源集合**与**承诺模型**。
+> 这是本工作流的第一性动作。
+
+1.  **识别规范来源**:
+    - `01_PRD.md` → 业务契约
+    - `02_ARCHITECTURE_OVERVIEW.md` + `03_ADR/` + `04_SYSTEM_DESIGN/` → 架构契约
+    - `05_TASKS.md` → 任务契约
+    - 当前审查范围内可读到的 README / 验证说明 / 配置说明 → 文档契约
+
+2.  **构建最小语义模型**（内部使用，不必原样照抄到最终报告）:
+    - **规范来源清单**: 每类契约来自哪些文件
+    - **承诺清单**: 每条关键承诺的来源、对象、失败后果
+    - **任务承接映射**: 若 `05_TASKS.md` 存在，记录哪些承诺已被任务覆盖，哪些没有
+
+3.  **至少抽取以下承诺类型**:
+    - **结果承诺**: 系统最终要达成什么业务结果
+    - **状态承诺**: 状态机、资源生命周期、越序约束是否明确
+    - **时间承诺**: 时间窗口、TTL、过期、调度、保留期
+    - **错误承诺**: 错误码、错误结构、默认失败路径是否一致
+    - **安全承诺**: 鉴权、授权、数据隔离、敏感信息边界
+    - **审计承诺**: 哪些操作应留痕、留痕粒度、问责边界
+    - **运行承诺**: 幂等、重试、超时、降级、可观测性
+
+4.  **输出一个简明承诺模型摘要**:
+    ```markdown
+    | 承诺类型 | 承诺摘要 | 契约来源 | 失真风险 |
+    |---------|---------|---------|---------|
+    | 错误承诺 | 所有 API 失败路径返回统一错误结构 | PRD §X / ADR-00Y | 客户端分叉处理 |
+    | 审计承诺 | 所有关键业务读写操作需留痕 | PRD §Y / System Design §Z | 无法问责 / 排障 |
+    | 运行承诺 | 写操作可安全重试且不重复副作用 | PRD §A / Architecture §B | 重复扣款/发货 |
+    ```
+
+---
+
 ## Step 2: Pre-Mortem (预演失败)
 
 **目标**: 从未来回看，分析可能的失败原因——**但必须有逻辑依据**。
@@ -117,19 +181,27 @@ description: "对项目决策进行系统性挑战，用证据证明风险真实
 1.  **设定场景**:
     > 6 个月后，项目失败了。为什么？
 
-2.  **思考引导** (每个失败原因都要回答):
+2.  **优先追问以下失真类型**:
+    - **写操作副作用失真**: 重试后是否可能重复产生副作用？
+    - **状态/时间口径失真**: 状态转换、时间字段、窗口计算是否偏离契约？
+    - **失败语义失真**: 默认 401/404/校验失败路径是否仍符合统一承诺？
+    - **审计/观测失真**: 留痕边界是否缩水？日志是否引入新的泄露面？
+    - **任务承接失真**: 关键承诺是否根本没有落入实现任务？
+
+3.  **思考引导** (每个失败原因都要回答):
     1. "这个失败原因的 Root Cause 是什么？"
-    2. "有什么证据表明这会发生？"
-    3. "发生概率有多高？(高/中/低)"
-    4. "如果发生了，影响有多大？"
-    5. "有没有已知的类似失败案例？"
+    2. "它违背了哪条规范契约？"
+    3. "有什么证据表明这会发生？"
+    4. "发生概率有多高？(高/中/低)"
+    5. "如果发生了，影响有多大？"
+    6. "有没有已知的类似失败案例？"
 
-3.  **输出格式**:
+4.  **输出格式**:
     ```markdown
-    | 失败原因 | Root Cause | 证据 | 概率 |
-    |---------|-----------|------|:----:|
-    | 用户不使用 | 需求未经验证 | PRD 中没有用户调研数据 | 🔴高 |
-    | API 超时 | 第三方依赖 | RFC 依赖外部 API 但无降级策略 | 🟡中 |
+    | 失败原因 | 失真契约 | Root Cause | 证据 | 概率 |
+    |---------|---------|-----------|------|:----:|
+    | 重复发货 | 写操作承诺 | 无幂等键 / 无去重状态 | PRD + API 设计未定义重试语义 | 🔴高 |
+    | 错误响应分叉 | 错误契约 | 默认失败路径未统一包装 | 401/404 由框架默认返回 | 🟡中 |
     ```
 
 ---
@@ -169,6 +241,10 @@ description: "对项目决策进行系统性挑战，用证据证明风险真实
 - 输入: `{TARGET_DIR}` 下的 `01_PRD.md`, `02_ARCHITECTURE_OVERVIEW.md`, `03_ADR/`, `04_SYSTEM_DESIGN/`
 - 输出: 设计审查发现清单（含严重度分级 + 文档关联）
 
+**使用方式要求**:
+- 将 `design-reviewer` 视为**规范契约的设计证据层**，不是最终结论本身
+- 优先要求其证明：哪些契约在系统边界、接口、状态、时序、错误路径上没有闭合
+
 **收集发现**，暂存待 Step 5 合并。
 
 ---
@@ -192,82 +268,62 @@ description: "对项目决策进行系统性挑战，用证据证明风险真实
 - 输入: `{TARGET_DIR}` 下的 `05_TASKS.md`, `01_PRD.md`, `02_ARCHITECTURE_OVERVIEW.md`, `03_ADR/`
 - 输出: 任务审查报告（6-Pass + REQ 覆盖率 + US 完整性 + 问题清单）
 
+**使用方式要求**:
+- 将 `task-reviewer` 视为**规范契约在任务层的承接证据**
+- 优先确认：关键承诺是否有实现任务、验证任务、边界/失败路径任务，以及是否存在幽灵任务稀释主轴
+
 **收集发现**，暂存待 Step 5 合并。如跳过，记录 `Task review skipped`（附原因）。
 
 ---
 
-## Step 4: 假设验证 (Assumption Validation)
-
-**目标**: 识别隐含假设，并尝试**证伪**。
+## Step 4: 承诺闭合验证与假设证伪 (Closure Validation)
 
+**目标**: 识别隐含假设，并验证关键承诺在边界条件下是否**真正闭合**。
 
 > **为什么？** 隐含假设是最危险的，因为它们通常不会被记录和验证。
 
-1.  **故障模式检查清单**:
+1.  **承诺闭合检查清单**:
 
-    | 检查项 | 问题 | RFC 位置 |
-    |---------|------|:-------:|
-    | **事务处理** | 数据库操作是否有事务包装？中间失败能回滚吗？ | |
-    | **重试机制** | 外部服务调用失败时怎么办？ | |
-    | **降级策略** | 主服务不可用时有 Fallback 吗？ | |
-    | **超时处理** | 慢操作有超时限制吗？ | |
-    | **并发控制** | 多用户/多线程考虑了吗？ | |
-    | **边界情况** | 空数据、超大数据、异常输入？ | |
-    | **错误信息** | 失败时用户看到什么？ | |
+    | 检查维度 | 核心问题 | 契约位置 |
+    |---------|---------|:-------:|
+    | **重复态** | 同一请求再来一次，是否仍忠于原承诺？ | |
+    | **失败态** | 超时、部分失败、外部依赖失败时，承诺是否仍成立？ | |
+    | **默认态** | 框架默认错误路径 / 默认资源路径是否与系统契约一致？ | |
+    | **运行态** | 调度、清理、保留期、长期运行行为是否有闭环？ | |
+    | **并发态** | 多用户/并发冲突时，状态与副作用是否可控？ | |
+    | **观测态** | 是否留有足够日志/审计证据，同时不扩大泄露面？ | |
 
-2.  **设计完整性检查**:
+2.  **技术与运行健壮性检查**:
 
-    | 检查项 | 问题 | RFC 位置 |
+    | 检查项 | 问题 | 契约位置 |
     |---------|------|:-------:|
-    | **接口定义** | 所有 API 都有完整的输入/输出 Schema 吗？ | |
+    | **事务处理** | 关键写操作是否有原子性保障？中间失败能回滚吗？ | |
+    | **重试机制** | 外部服务调用失败时怎么办？是否会扩大副作用？ | |
+    | **降级策略** | 主服务不可用时有 Fallback 吗？ | |
+    | **超时处理** | 慢操作有超时限制吗？ | |
+    | **接口定义** | 所有关键 API 都有完整输入/输出/错误 Schema 吗？ | |
     | **配置管理** | 秘钥/配置如何管理？硬编码了吗？ | |
-    | **日志监控** | 关键操作有日志吗？如何调试？ | |
+    | **日志监控** | 关键操作有日志吗？日志是否越界记录敏感信息？ | |
     | **版本控制** | 数据格式/升级如何处理？ | |
     | **Prompt 模板** | LLM 的 Prompt 有完整定义吗？ | |
     | **工具定义** | LLM Tool Use 有 JSON Schema 吗？ | |
 
-3.  **输出格式**:
-    ```markdown
-    ### 技术健壮性审计
-    
-    | 方面 | 当前设计 | 评估 | 问题 |
-    |------|---------|:----:|------|
-    | 事务处理 | 全量删除+插入 | 🟡 | 不是原子操作 |
-    | 重试机制 | 无 | ❌ | LLM 调用失败怎么办？ |
-    | Prompt 模板 | 未定义 | ❌ | 需要详细设计 |
-    ```
-
----
-
-**假设类型清单**:
-1. **技术假设**: "框架X支持功能Y"、"API性能满足需求"
-2. **用户假设**: "用户熟悉操作模式"、"用户需求稳定"
-3. **资源假设**: "团队技能足够"、"开发时间充足"
-4. **环境假设**: "网络稳定"、"第三方服务可靠"
-5. **业务假设**: "需求不会变化"、"商业模式可行"
-
-**验证方法**:
-
-**方法 A - 文档交叉验证**:
-扫描所有设计文档，检查假设是否在多处被提及但未被验证
-
-**方法 B - 外部调研**:
-搜索相关技术的已知问题、限制、最佳实践
+3.  **记录验证结果**（内部分析可详细，最终报告只保留高信号摘要）:
 
-3.  **记录验证结果**:
     ```markdown
-    | 假设 | 验证方法 | 结果 | 状态 |
-    |------|---------|------|:----:|
-    | API 支持批量操作 | 查阅官方文档 | 确实支持，文档链接: ... | ✅ 已验证 |
-    | 用户熟悉该操作模式 | 无数据 | 需要用户调研 | ⚠️ 未验证 |
-    | 性能满足需求 | 无基准测试 | 需要 POC | ⚠️ 未验证 |
+    | 项目 | 结论 | 证据 | 对应问题 |
+    |------|------|------|----------|
+    | 重复态 | Pass / Partial / Fail | ... | CH-01 |
+    | 失败态 | Pass / Partial / Fail | ... | CH-02 |
+    | 默认态 | Pass / Partial / Fail | ... | CH-03 |
+    | 运行态 | Pass / Partial / Fail | ... | CH-04 |
     ```
 
 ---
 
 ## Step 5: 生成质疑报告 (Challenge Report)
 
-**目标**: 输出结构化报告，每个问题都有证据支撑。
+**目标**: 输出结构化报告，每个问题都有证据支撑，并采用**问题发现优先**的紧凑结构。
 
 保存报告到 `{TARGET_DIR}/07_CHALLENGE_REPORT.md`
 
@@ -284,92 +340,64 @@ description: "对项目决策进行系统性挑战，用证据证明风险真实
 
 ## 📋 问题总览
 
-> 此目录随每轮审查同步维护。已解决的轮次仅保留此摘要行，详细内容在确认修复后删除。
-
-### 第一轮（{日期}，{X}/{Y} 已修复）
-
-| ID | 严重度 | 摘要 | 状态 |
-|----|--------|------|------|
-| C1-CX | 🔴 | [同级别问题的精简一行摘要] | ✅ 全部修复 / ⏳ 待修复 |
-| H1-HX | 🟠 | [同级别问题的精简一行摘要] | ✅ 全部修复 / ⏳ 待修复 |
-| M1-MX | 🟡 | [同级别问题的精简一行摘要] | ✅ 全部修复 / ⏳ 实现时处理 |
-
----
-
-## 🎯 审查方法论
-
-本次审查模式: **{REVIEW_MODE}**（DESIGN / TASKS / FULL）
-
-1. **设计审查** (design-reviewer skill) — {执行 / 跳过} — 系统设计 / 运行模拟 / 工程实现 三维度
-2. **任务审查** (task-reviewer skill) — {执行 / 跳过 / 自适应升级} — 重复 / 歧义 / 欠详述 / 不一致 / 覆盖率 / 质量粒度 六大 Pass
-3. **Pre-Mortem** — 预演失败 + 假设验证
-4. **合并评定** — 统一严重度分级 + 综合判断
-
----
-
-## 🔥 第{N}轮详细审查（当前活跃）
+> 已解决轮次仅保留摘要。当前活跃轮只保留影响判断的高信号问题。
 
-### 📊 本轮问题统计
+### 第{N}轮（当前活跃）
 
-| 严重度 | 数量 | 占比 |
-|--------|------|------|
-| Critical | X | X% |
-| High | X | X% |
-| Medium | X | X% |
-| Low | X | X% |
-| **Total** | **X** | **100%** |
-
-| 维度 | 问题数 |
-|------|--------|
-| 设计审查 (design-reviewer) | X |
-| 任务审查 (task-reviewer) | X |
-| Pre-Mortem + 假设验证 | X |
+| 严重度 | 数量 | 摘要 | 状态 |
+|--------|------|------|------|
+| Critical | X | [本轮 Critical 问题的合并摘要] | ⏳ 待处理 |
+| High | X | [本轮 High 问题的合并摘要] | ⏳ 待处理 |
+| Medium | X | [本轮 Medium 问题的合并摘要] | ⏳ 待处理 |
+| Low | X | [本轮 Low 问题的合并摘要或省略说明] | ⏳ 待处理 |
 
 ---
 
-# 🔴 Critical 级别
-
-### C1. [问题标题]
-
-**严重度**: Critical  
-**文档**: [文档位置]  
-**ADR 影响**: [如涉及 ADR 修改,列出需要修改的 ADR 文件和引用该 ADR 的 SYSTEM_DESIGN 列表]
-
-**问题描述**:
-[详细描述，引用具体代码或设计]
-
-**影响**:
-- [具体后果]
-
-**建议**:
-[解决方案，可提供多个选项]
-
----
+## 📊 审查摘要
 
-## 🟠 High 级别
+**审查模式**: `{REVIEW_MODE}`  
+**整体判断**: 🟢 可继续 / 🟡 需先修复高优先问题 / 🔴 暂不建议继续  
+**高信号结论**: [用 2-4 句总结最值得关心的问题，不展开方法过程]
 
-### H1. [问题标题]
+| 指标 | 数值 |
+|------|------|
+| Critical | X |
+| High | X |
+| Medium | X |
+| Low | X |
+| Total Findings | X |
 
-...
+| 证据来源 | 结论 |
+|----------|------|
+| design-reviewer | {执行 / 跳过} |
+| task-reviewer | {执行 / 跳过 / 自适应升级} |
+| Pre-Mortem | {关键结论一句话} |
+| 承诺闭合检查 | {Pass / Partial / Fail} |
 
 ---
 
-## 🟡 Medium / 🟢 Low 级别
-
-...
+## 🔍 核心发现清单
 
+| ID | 类别 | 严重度 | 契约/Pass | 位置 | 发现 | 影响 | 建议 |
+|----|------|--------|-----------|------|------|------|------|
+| CH-01 | 承诺失真 | Critical | 错误承诺 | PRD §X / ADR §Y | 默认失败路径未统一，契约未闭合 | 客户端错误处理分叉 | 统一错误语义并补验证任务 |
+| CH-02 | 任务承接 | High | E1 | 05_TASKS.md §X | P0 需求无对应任务 | 核心能力无法落地 | 补充实现与验证任务 |
+| CH-03 | 设计闭合 | Medium | RS-5 | 04_SYSTEM_DESIGN/... | 故障传播路径未说明 | 出现级联失败时难以恢复 | 增加降级与超时策略 |
+ 
+> 仅保留真正影响判断的问题。低价值措辞、泛泛而谈的担忧不要写进表。
+ 
 ---
 
-## 📋 建议行动清单
+## 建议行动清单
 
 ### P0 - 立即处理 (阻塞)
-1. [C级问题] - [建议方案]
+1. [CH-01] - [建议方案]
 
 ### P1 - 近期处理 (重要)
-1. [H级问题] - [建议方案]
+1. [CH-02] - [建议方案]
 
 ### P2 - 持续改进 (优化)
-1. [M/L级问题] - [建议方案]
+1. [CH-03] - [建议方案]
 
 ---
 
@@ -379,40 +407,30 @@ description: "对项目决策进行系统性挑战，用证据证明风险真实
 - [ ] 🟡 项目可继续，但需先解决 P0 问题
 - [ ] 🔴 项目需要重新评估
 
-**判断依据**: [基于问题数量、严重度和影响范围的综合评估]
+**判断依据**: [基于关键问题数量、严重度和影响范围的综合评估]
 
 ---
 
-## 📚 附录
-
-### A. Pre-Mortem 分析
-
-| 失败场景 | Root Cause | 概率 | 对应问题 |
-|---------|-----------|:----:|----------|
-| ... | ... | 🔴/🟡/🟢 | C1, H3 |
+## 📚 附录（按需）
 
-### B. 假设验证结果
+### A. 承诺闭合与假设验证摘要
 
-| 假设 | 验证方法 | 结果 | 风险 |
-|------|---------|------|:----:|
-| ... | ... | ... | ✅/⚠️/❌ |
+| 项目 | 结论 | 证据 | 对应问题 |
+|------|------|------|----------|
+| 重复态 | Pass / Partial / Fail | ... | CH-01 |
+| 失败态 | Pass / Partial / Fail | ... | CH-02 |
+| 默认态 | Pass / Partial / Fail | ... | CH-03 |
+| 运行态 | Pass / Partial / Fail | ... | CH-04 |
 
-### C. ADR 影响追踪
+### B. ADR 影响追踪
 
-> **提醒**: 如果本次审查发现需要修改 ADR,请检查以下引用链:
+> **提醒**: 如果本次审查发现需要修改 ADR，请检查以下引用链：
 
 | ADR 文件 | 引用该 ADR 的 SYSTEM_DESIGN | 影响说明 |
 |---------|---------------------------|---------|
 | [ADR-XXX](../03_ADR/ADR_XXX.md) | [system-1.md](../04_SYSTEM_DESIGN/system-1.md) §8 | [说明] |
-
-**修改 ADR 后的行动**:
-1. 更新 ADR 文件
-2. 检查上表中所有引用该 ADR 的 SYSTEM_DESIGN
-3. 确认这些系统设计是否需要相应调整
 ```
 
----
-
 ## Step 6: 轮次归档协议 (Round Archive Protocol)
 
 **目标**: 保持报告精简，已解决的轮次只保留摘要。
@@ -449,10 +467,13 @@ description: "对项目决策进行系统性挑战，用证据证明风险真实
 
 <completion_criteria>
 - ✅ 深度阅读了项目设计文档
+- ✅ 已识别规范来源集合并提炼关键承诺模型
 - ✅ Pre-Mortem 分析有逻辑依据
 - ✅ 每个质疑点都有证据支撑
+- ✅ 已完成承诺闭合验证（至少覆盖重复态 / 失败态 / 默认态 / 运行态）
 - ✅ 技术健壮性审计已完成
 - ✅ Top 3 假设已尝试验证
+- ✅ 承诺型质疑优先于载体型质疑输出
 - ✅ 质疑报告格式完整（含问题总览目录）
 - ✅ 上一轮已解决问题的详情已归档（仅保留总览行）
 - ✅ 用户已阅读并决定下一步

package/templates/.agents/workflows/change.md

@@ -1,5 +1,5 @@
 ---
-description: "处理当前版本内的局部修订请求，允许修改已有任务的细节和补充必要的承接项。适用于任务执行过程中发现描述不准确、验收标准需调整等场景。禁止创建新功能或添加无关新任务，超出范围时引导用户运行 /genesis。"
+description: "处理当前版本内的局部修订与 task 调整请求。只要变更不偏离 ADR 与架构基线，就优先由 /change 处理。适用于普通文件、设计、任务定义修订，以及验收标准、估时、优先级、任务编排和必要承接项补充等场景；超出范围时引导用户运行 /genesis。"
 ---
 
 # /change

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

@@ -321,6 +321,30 @@ description: "为单个系统设计详细的技术文档。适用于架构拆解
 
 ---
 
+### 3.1 可选 Skills 与参考资源 (Optional Skills & Reference Resources)
+
+> [!IMPORTANT]
+> **这些资源是辅助输入，不是强制依赖，也不是系统事实来源。**
+
+使用原则:
+- 可以按系统类型选择已有 skills、方法论或外部参考资源辅助设计
+- 这些输入只能作为启发、校验或补充，不得替代当前项目的 PRD、ADR 和 Architecture Overview
+- 最终方案必须收敛为当前系统自己的边界、约束、组件分层和 Trade-offs
+- 禁止直接复制第三方模式而不做本地化说明
+
+**前端系统示例**:
+- 工程实践类 skill: `vercel-react-best-practices`
+- 视觉与体验类 skill: `frontend-design`
+- 组件与交互参考: `shadcn/ui`、`Aceternity UI`、`Magic UI`、其他 Tailwind-first 资源
+
+**如何使用这些资源**:
+- 用 `vercel-react-best-practices` 校验 React 组件边界、渲染策略、性能模式是否合理
+- 用 `frontend-design` 辅助配色、排版、层级、动效和整体体验方向
+- 用 `shadcn/ui`、`Aceternity UI` 等资源获取组件模式或视觉灵感
+- 在最终文档中明确写出: 哪些做法被采纳、哪些被舍弃、为什么
+
+---
+
 ## Step 4: 设计 (Design via sequential-thinking)
 
 **目标**: 基于调研和上下文，深度设计系统架构

package/templates/.agents/workflows/forge.md

@@ -115,6 +115,14 @@ description: "按照架构文档和任务清单将设计锻造为代码。适用
      - 如全部完成 → **新波次** → 继续 Step 1
    - 如果不存在 → **新开始** → 继续 Step 1
 
+7. **Git 上下文检查**:
+   - 读取当前 branch
+   - 如当前在 `main` 且本次不是单文件小修 → 先创建并切换到 `feature/{topic-slug}`
+   - 如当前已在 `feature/*` 且本波次仍属于同一交付主题 → 继续在当前 branch 上推进
+   - 如当前已在 `feature/*` 但本波次目标已切换为另一独立主题 → 新建并切换到新的 `feature/{topic-slug}`
+   - 同一交付目标下的多波次，默认持续使用同一个 `feature/*` branch，直到 Step 5 完成里程碑结算
+   - 如本波次属于高风险改造（跨系统 / 预计改动 > 5 文件 / 涉及公共接口）→ 在当前工作 branch 上先创建 checkpoint commit：`checkpoint: before {topic}`
+
 ---
 
 ## Step 1: 波次规划 (Wave Planning)
@@ -134,7 +142,7 @@ description: "按照架构文档和任务清单将设计锻造为代码。适用
 
 ### 1.2 分组与建议
 
-按以下策略组织一个波次:
+按以下策略组织一个波次：
 
 | 策略             | 说明                                         |
 | ---------------- | -------------------------------------------- |
@@ -144,7 +152,7 @@ description: "按照架构文档和任务清单将设计锻造为代码。适用
 
 ### 1.3 波次确认
 
-向用户展示:
+向用户展示：
 
 ```markdown
 ## 📋 Wave {N} 建议
@@ -190,7 +198,7 @@ T{X.Y.Z}, T{X.Y.Z}, T{X.Y.Z}
 |  **L2 任务级**  | 每个任务的 `**输入**` 字段指定的精确文档章节                             | 实现细节             |
 
 > [!IMPORTANT]
-> **L1.5 加载规则（CRITICAL）**:
+> **L1.5 加载规则（CRITICAL）**：
 >
 > - `{system}.md`（L0 导航层）**始终加载** ← 这是默认行为
 > - `{system}.detail.md`（L1 实现层）**仅当任务 `**输入**` 字段明确引用时才加载**
@@ -203,7 +211,7 @@ T{X.Y.Z}, T{X.Y.Z}, T{X.Y.Z}
 ### 加载步骤
 
 1. **L0**: 读取 `{TARGET_DIR}/02_ARCHITECTURE_OVERVIEW.md` 的系统清单部分
-2. **L1**: 根据本波任务涉及的系统，读取对应的:
+2. **L1**: 根据本波任务涉及的系统，读取对应的：
    - `{TARGET_DIR}/04_SYSTEM_DESIGN/{system-id}.md`
    - `{TARGET_DIR}/03_ADR/` 中相关的 ADR（由任务的"输入"字段指引）
 
@@ -216,7 +224,7 @@ T{X.Y.Z}, T{X.Y.Z}, T{X.Y.Z}
 > [!IMPORTANT]
 > **严格按以下流程执行每个任务，不跳步。**
 
-对本波次中的每个任务，执行以下循环:
+对本波次中的每个任务，执行以下循环：
 
 ---
 
@@ -248,7 +256,7 @@ T{X.Y.Z}, T{X.Y.Z}, T{X.Y.Z}
 >
 > **为什么？** 错误的理解导致返工，提前发现问题比事后修复便宜 10 倍。
 
-**思考引导** (必须逐个回答):
+**思考引导** (必须逐个回答)：
 1. "这个任务要我做什么？输出哪些文件？"
 2. "与哪些已有代码/接口交互？接口签名是什么？"
 3. "验收标准里最关键的约束是什么？"
@@ -273,7 +281,7 @@ T{X.Y.Z}, T{X.Y.Z}, T{X.Y.Z}
 
 ### 3.4 验证 (Verify)
 
-**根据任务的验证类型执行相应验证**，并按类型分类证据:
+**根据任务的验证类型执行相应验证**，并按类型分类证据：
 
 > [!IMPORTANT]
 > **验证类型决定验证方式和证据要求**：
@@ -292,13 +300,13 @@ T{X.Y.Z}, T{X.Y.Z}, T{X.Y.Z}
 
 **验证类型**: [单元测试 | 集成测试 | E2E测试 | 编译检查 | Lint检查 | 手动验证]
 
-**自动验证** (单元测试/集成测试/E2E/编译/Lint):
+**自动验证** (单元测试/集成测试/E2E/编译/Lint)：
 | 验收标准 | 命令 | 输出摘要 | 状态 |
 | -------- | ---- | -------- | :--: |
 | 测试通过 | `npm test` | 12 passed, 0 failed | ✅ |
 | 构建成功 | `npm run build` | Build succeeded | ✅ |
 
-**手动验证**:
+**手动验证**：
 | 验收标准 | 说明 | 状态 |
 | -------- | ---- | :--: |
 | 页面显示正确 | 需要打开浏览器确认渲染效果 | ⏳ |
@@ -314,7 +322,7 @@ T{X.Y.Z}, T{X.Y.Z}, T{X.Y.Z}
 
 ### 3.5 遵从性检查 (Compliance Check)
 
-**检查清单** (每条都要回答):
+**检查清单** (每条都要回答)：
 
 | #   | 检查项                              | 通过？ |
 | --- | ----------------------------------- | :----: |
@@ -333,11 +341,16 @@ T{X.Y.Z}, T{X.Y.Z}, T{X.Y.Z}
 
 ### 3.6 提交 (Commit)
 
-1. **Git commit**:
-   - 消息格式: `feat(system-id): T{X.Y.Z} — 任务标题`
+1. **Git commit**：
+   - Task commit 一律落在**当前工作 branch** 上
+   - 默认当前工作 branch 为本次交付对应的 `feature/*`；只有 Step 0 明确判定为单文件小修时才允许留在 `main`
+   - 消息格式: `{type}({scope}): T{X.Y.Z} — 任务标题`
+   - `type` ∈ `feat | fix | refactor | docs | test | chore`
+   - `scope` 默认使用 `system-id`；workflow/skill 改动可用对应名称
    - 例: `feat(core): T2.1.1 — 地形与资源数据模型`
+   - 例: `fix(challenge): T4.2.3 — 严重度语义对齐`
 
-2. **任务完成持久化** (立即回写):
+2. **任务完成持久化** (立即回写)：
 
    > [!IMPORTANT]
    > **每完成一个 task 并通过验证，立即回写 `05_TASKS.md`**。
@@ -361,7 +374,7 @@ T{X.Y.Z}, T{X.Y.Z}, T{X.Y.Z}
 
 ### 4.1 更新状态
 
-**更新 `AGENTS.md`**:
+**更新 `AGENTS.md`**：
 
 1. 更新 `🌊 Wave` 块为下一波的初始状态（如果已知下一波任务），或标记当前波已完成：
 ```markdown
@@ -372,7 +385,7 @@ T{X.Y.Z}, T{X.Y.Z}, T{X.Y.Z}
 
 ### 4.2 波次回顾
 
-向用户简要汇报:
+向用户简要汇报：
 
 ```markdown
 ## 🌊 Wave {N} 完成
@@ -385,13 +398,16 @@ T{X.Y.Z}, T{X.Y.Z}, T{X.Y.Z}
 
 ### 4.3 Git commit 状态更新
 
-```
-chore: Wave {N} settlement — update task progress
+- Wave settlement commit 与本波次 task commits 一样，落在当前工作 branch 上
+- 如下一波仍属于同一交付主题，默认继续沿用当前 `feature/*` branch
+
+```markdown
+chore(wave): settle wave {N} progress
 ```
 
 ### 4.4 下一步判定
 
-**人类检查点** ⚠️:
+**人类检查点** ⚠️：
 
 - 还有未完成任务 → 询问用户："继续下一波？" → 回到 **Step 1**
 - 当前 Sprint 所有任务完成 → 进入 **Step 5**
@@ -407,7 +423,15 @@ chore: Wave {N} settlement — update task progress
 
 1. **集成验证**: 运行集成测试（如有），确保跨系统功能正常
 2. **更新 AGENTS.md**: 清除"当前波次"信息，更新已完成的 Sprint/Phase
-3. **汇报用户**: 列出已完成的 Sprint/Phase 概要
+3. **Git 里程碑锚点**：
+   - Sprint/Phase 完成 → `milestone: {name} complete`
+   - 对应版本发布 → `release: vX.Y.Z`
+   - 如存在明确版本号，可打 tag：`vX.Y.Z`
+   - 以上里程碑 commit / tag 默认创建在当前工作 branch 上
+4. **合流主线**：
+   - 当前 feature branch 达到可验收里程碑后，合并回 `main`
+   - 合并策略遵循仓库既有规范（merge / squash / rebase），但 `main` 最终应指向该里程碑的稳定状态
+5. **汇报用户**: 列出已完成的 Sprint/Phase 概要
 
 ---
 
@@ -415,7 +439,7 @@ chore: Wave {N} settlement — update task progress
 - ✅ 每个任务的验收标准全部通过
 - ✅ 每个任务的遵从性检查全部通过
 - ✅ 所有代码已 git commit，message 包含 Task ID
-- ✅ 05_TASKS.md checkbox 已更新
+- ✅ 所有任务已完成持久化（05_TASKS.md）
 - ✅ AGENTS.md 当前状态已更新
 - ✅ 用户已确认波次完成
 </completion_criteria>