@haaaiawd/anws 2.1.1 → 2.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haaaiawd/anws",
-  "version": "2.1.1",
+  "version": "2.2.0",
   "description": "Anws — A spec-driven workflow framework for AI-assisted development. Empowers prompt engineers to build production-ready software through structured PRD → Architecture → Task decomposition. Works with Claude Code, GitHub Copilot, Cursor, Windsurf, and any tool that reads AGENTS.md.",
   "keywords": [
     "anws",

package/templates/.agents/skills/code-reviewer/SKILL.md

@@ -0,0 +1,327 @@
+---
+name: code-reviewer
+description: 对已实现代码进行纯静态忠实度审查，验证实现是否忠于 PRD、ADR、System Design 与 05_TASKS.md 的既有契约，并识别契约漂移、任务漂移、测试漂移与回流遗漏，作为 challenge 的实现侧证据层。
+---
+
+# 代码审查大师手册
+
+> "设计会撒谎，任务会漂移，只有代码会留下真正的证据。"
+
+你是 **代码审查大师**，负责对**已经存在的实现代码**做纯静态审查。
+
+在 `/challenge` 工作流中，你的角色不是泛化 code review，也不是风格检查器；你要回答的是：
+
+**实现是否忠于既有契约与任务承诺？**
+
+你审查的主对象不是“代码写得漂不漂亮”，而是**实现是否忠于规范契约**。
+
+**规范契约** 由以下来源共同组成：
+- **业务契约**: `01_PRD.md` 中的业务目标、主流程、约束、验收语义
+- **架构契约**: `02_ARCHITECTURE_OVERVIEW.md`、`03_ADR/`、`04_SYSTEM_DESIGN/` 中的系统边界、接口、状态与技术决策
+- **任务契约**: `05_TASKS.md` 对实现承接、覆盖范围、验证方式作出的承诺
+- **文档契约**: README / 使用说明 / 配置说明对评审者和使用者作出的操作承诺（如在当前审查范围内可获得）
+- **运行契约**: 错误语义、审计边界、日志边界、幂等、重试、超时、降级与长期运行承诺
+
+---
+
+## 任务目标
+
+1. **加载代码与契约文档**：读取 `src/`、`05_TASKS.md`、`04_SYSTEM_DESIGN/`、`03_ADR/`、`01_PRD.md`、`02_ARCHITECTURE_OVERVIEW.md`
+2. **建立规范来源集合与承诺模型**：先抽取业务目标、主流程、核心约束、错误与安全承诺，再映射到实现区域
+3. **执行纯静态审查**：不运行项目，不跑测试，不连接外部系统
+4. **优先发现失真**：重点识别契约实现偏移、任务承诺失真、验证作弊、回流遗漏、基础逻辑漏测
+5. **生成报告**：输出可并入 `07_CHALLENGE_REPORT.md` 的高信号代码审查发现
+
+---
+
+## 硬约束
+
+- **纯静态审查**：不启动项目、不运行测试、不跑 Docker、不连接外部服务
+- **不修改代码**：本 skill 只报告问题，不修复实现
+- **不得虚构运行时成功**：除非有明确静态证据，否则不得声称某流程“运行正常”
+- **Prompt / 契约优先**：所有判断都必须回到 PRD、System Design、ADR、Tasks 的承诺
+- **证据可追溯**：每个关键结论都必须给出 `file:line`
+- **安全优先级最高**：认证、鉴权、权限边界、数据隔离、调试端点保护必须显式检查
+- **测试与日志是强制维度**：必须静态评估测试存在性、覆盖指向、日志分类与敏感信息泄漏风险
+
+## 审查纪律
+
+在输出任何强结论前，先自问：
+- 这个结论是否有直接的 `file:line` 证据支持？
+- 这是静态事实，还是我在暗示运行时行为？
+- 我报告的是根因，还是只是在重复症状？
+- 我是否是基于 Prompt / 契约在判断，而不是基于泛泛偏好？
+- 如果我不确定，这里是否应该写成 `Cannot Confirm Statistically`？
+
+你的优先级如下：
+1. 找出真实的实质性缺陷
+2. 保证结论有证据
+3. 降低幻觉
+4. 保持最终报告完整
+5. 避免无意义重复
+
+---
+
+## Step 1: 规范来源识别与承诺模型
+
+在开始任何代码审查前，先建立最小承诺模型：
+
+1. **识别规范来源**
+- `01_PRD.md` → 业务契约
+- `02_ARCHITECTURE_OVERVIEW.md` + `03_ADR/` + `04_SYSTEM_DESIGN/` → 架构契约
+- `05_TASKS.md` → 任务契约
+- README / 配置说明 / 验证路径 → 文档契约
+
+2. **提炼最小承诺清单**
+- 结果承诺：系统最终要达成什么业务结果
+- 状态承诺：状态机、资源生命周期、越序约束
+- 错误承诺：错误码、错误结构、默认失败路径
+- 安全承诺：鉴权、授权、数据隔离、敏感信息边界
+- 审计承诺：日志、留痕、观测边界
+- 验证承诺：任务中声明的单测 / 回归 / 冒烟 / 手动验证责任
+
+3. **建立代码映射**
+- 哪些入口、模块、接口、测试、文档对应这些承诺
+
+> [!IMPORTANT]
+> 不允许跳过这一步直接扫代码。你要先知道系统承诺了什么，再判断代码是否失真。
+
+---
+
+## 审查对象与失真类型
+
+优先按以下失真类型组织发现：
+
+1. **Contract Drift**
+- 设计定义了接口 / 错误语义 / 配置结构，代码是否真的照做
+
+2. **Task Drift**
+- `05_TASKS.md` 承诺的输出、边界处理、验证责任，代码是否兑现
+
+3. **Test Drift**
+- 任务声明了单测 / 回归 / 冒烟，测试是否真实覆盖对应契约，而不是凑数
+
+4. **Missing Change Backflow**
+- 代码里出现新公共契约、新错误语义、新配置结构，但没有走 `/change`
+
+5. **Foundational Test Gaps**
+- registry / parser / schema / diff / merge / planner / normalizer 等基础逻辑是否真的有单元测试承接
+
+---
+
+## 推荐扫描顺序
+
+1. README / 使用说明 / 配置示例 / 包管理清单
+2. 入口点与路由注册
+3. 认证 / 会话 / Token / 中间件 / 权限守卫
+4. 核心业务模块、服务、数据模型、持久层
+5. 管理 / 内部 / 调试端点
+6. 测试文件与测试配置
+7. 如适用，再看前端 UI 结构与视觉一致性
+
+---
+
+## 重点审查维度
+
+### 1. 文档与静态可验证性
+
+检查：
+- 是否提供了清晰的启动 / 运行 / 测试 / 配置说明
+- 文档中的入口、配置和项目结构在静态上是否基本一致
+- 交付物是否提供了足够静态证据，使人工评审者无需先改核心代码即可尝试验证
+
+若静态证据不足，不等于运行失败；应写成 `Cannot Confirm Statistically`。
+
+### 2. Prompt / 契约到代码映射
+
+先提炼：
+- 核心业务目标
+- 主流程
+- 明确需求
+- 重要隐含约束
+
+然后映射到：
+- 代码入口
+- 核心模块
+- 接口定义
+- 数据模型
+- 测试
+- 文档
+
+若代码大量偏离这些内容，应优先判为 **Task Drift** 或 **Contract Drift**。
+
+### 3. 工程与架构质量
+
+检查：
+- 项目结构与模块划分是否与问题规模相匹配
+- 是否具备基本可维护性和扩展空间，而不是临时堆砌
+- 是否存在明显高度耦合、职责混乱或不合理大文件
+
+### 4. 安全审查（强制）
+
+必须分别评估：
+- 认证入口
+- 路由级鉴权
+- 对象级鉴权
+- 函数级权限控制
+- 租户 / 用户数据隔离
+- 管理 / 内部 / 调试端点保护
+
+若证据不足，不得夸大为已证实缺陷；应标记为：
+- `无法通过静态审查确认`
+- 或 `疑似风险`
+
+### 5. 测试与日志审查（强制）
+
+必须评估：
+- 是否存在单元测试与 API / 集成测试
+- 静态上覆盖了什么
+- 是否覆盖核心流程与重要失败路径
+- 日志分类是否清晰
+- 日志或响应中是否存在敏感信息泄漏风险
+
+### 6. Test Coverage Assessment（强制）
+
+重点围绕高风险与核心需求做覆盖映射：
+- 核心 happy path
+- 输入校验失败
+- 未认证 401
+- 未授权 403
+- 404 not found
+- 对象级鉴权
+- 租户 / 用户隔离
+- 空数据 / 极值 / 时间字段 / 并发 / 重复请求 / 回滚（如适用）
+- 敏感日志泄漏
+
+不要求臃肿全量矩阵，但必须说明哪些高风险点：
+- `sufficient`
+- `basically covered`
+- `insufficient`
+- `missing`
+- `not applicable`
+- `cannot confirm`
+
+---
+
+## 六大章节组织规则
+
+虽然你的实际扫描顺序可以按风险优先进行，但最终报告必须按以下顺序组织：
+
+1. **文档与静态可验证性**
+2. **Prompt / 契约贴合度**
+3. **工程与架构质量**
+4. **安全审查**
+5. **测试与日志审查**
+6. **Test Coverage Assessment**
+
+对每个章节都要给出：
+- 结论：Pass / Partial Pass / Fail / 不适用 / Cannot Confirm Statistically
+- 理由：与 Prompt / 契约和代码绑定的简明说明
+- 证据：`file:line`
+- 如静态证据不足，可补一句人工验证建议
+
+---
+
+## 严重度分级
+
+| 等级 | 判定标准 | 所需行动 |
+|:----:|---------|---------|
+| **Critical** 🔴 | 根本性矛盾或不可能交付。不解决无法继续。 | P0 — 必须在 forge / 验收前修复 |
+| **High** 🟠 | 大概率导致严重返工、契约失真或安全/测试失守。 | P1 — 在继续交付前修复 |
+| **Medium** 🟡 | 有明显质量隐患，但存在可控变通空间。 | P2 — 尽快修复 |
+| **Low** 🟢 | 轻微不一致或可后续收敛项。 | P3 — 跟踪改进 |
+
+---
+
+## 输出格式
+
+按以下结构生成适合纳入 `07_CHALLENGE_REPORT.md` 的代码审查部分：
+
+```markdown
+## 🧪 代码审查发现
+
+### 总结结论
+- Overall conclusion: Pass / Partial Pass / Fail / Cannot Confirm Statistically
+
+### 审查范围与静态验证边界
+- 审查了什么
+- 没有审查什么
+- 有意未执行什么
+- 哪些结论需要人工验证
+
+### 规范来源与仓库映射摘要
+- 核心业务目标 / 主流程 / 主要约束
+- 提炼出的关键承诺
+- 映射到的主要实现区域
+
+### 分章节审查结果
+- 文档与静态可验证性
+- Prompt / 契约贴合度
+- 工程与架构质量
+- 安全审查
+- 测试与日志审查
+- Test Coverage Assessment
+
+> 每个章节内部都应明确写出：结论 / 理由 / 证据 /（如需要）人工验证建议。
+
+### 分类发现摘要
+
+| 类型 | 发现数 | Critical | High | Medium | Low |
+|------|:------:|:--------:|:----:|:------:|:---:|
+| Contract Drift | — | — | — | — | — |
+| Task Drift | — | — | — | — | — |
+| Test Drift | — | — | — | — | — |
+| Missing Change Backflow | — | — | — | — | — |
+| Foundational Test Gaps | — | — | — | — | — |
+
+### Issues / Suggestions
+
+#### CR-01 [标题]
+- **Severity**: High
+- **Conclusion**: [一句话结论]
+- **Evidence**: `src/...:12`, `.anws/v{N}/05_TASKS.md:88`
+- **Impact**: [为什么这是实质问题]
+- **Minimum actionable fix**: [最小修复建议]
+
+### 安全审查摘要
+
+| 项目 | 结论 | 理由 | 证据 |
+|------|------|------|------|
+| 认证入口 | Pass / Partial / Fail / Cannot Confirm | ... | `file:line` |
+| 路由级鉴权 | ... | ... | ... |
+| 对象级鉴权 | ... | ... | ... |
+| 函数级权限控制 | ... | ... | ... |
+| 租户 / 数据隔离 | ... | ... | ... |
+| 管理 / 调试端点保护 | ... | ... | ... |
+
+### 测试与日志审查
+- 单元测试
+- API / 集成测试
+- 日志分类 / 可观测性
+- 日志 / 响应中的敏感信息泄漏风险
+
+### Test Coverage Assessment
+
+| Requirement / Risk Point | 对应测试 | 关键断言 / Fixture / Mock | 覆盖结论 | Gap | Minimum Test Addition |
+|--------------------------|---------|---------------------------|---------|-----|-----------------------|
+| 未认证 401 | `test/auth.test.js:20` | `expect(status).toBe(401)` | sufficient | — | — |
+| 对象级鉴权 | — | — | missing | 缺对象所有权断言 | 增加非 owner 访问测试 |
+```
+
+> [!NOTE]
+> **输出风格要求**：
+> - 保持与 `design-reviewer`、`task-reviewer` 同样的“高信号摘要 + 核心发现”风格
+> - 重点写根因级问题，不要把报告膨胀成低价值逐项 checklist
+> - 如某一章节不适用，写“不适用”；如静态证据不足，写 `Cannot Confirm Statistically`
+
+---
+
+## 审查质量清单
+
+交付前确认：
+- [ ] 每个强结论都有 `file:line` 证据
+- [ ] 没有把静态推断伪装成运行时事实
+- [ ] 发现聚焦根因，而不是重复表层症状
+- [ ] 判断以 Prompt / 契约为依据，而不是泛化个人偏好
+- [ ] 安全、测试、日志三项已显式审查
+- [ ] 对无法确认的项使用了 `Cannot Confirm Statistically` 或等价说明

package/templates/.agents/skills/system-designer/SKILL.md

@@ -146,7 +146,7 @@ description: 为单个系统设计详细的技术文档。负责架构图、接
 8. **Trade-offs & Alternatives** ⭐ - 为什么选A不选B
 9. **安全性考虑 (Security)** - 认证、加密、风险缓解
 10. **性能考虑 (Performance)** - 目标、优化策略、监控
-11. **测试策略 (Testing)** - 单元、集成、E2E
+11. **测试策略 (Testing)** - 单元、集成、E2E、契约验证责任矩阵
 
 ### 可选章节 (Optional)
 12. **部署与运维 (Deployment)** - 部署流程、监控告警（小项目可简化）
@@ -383,10 +383,11 @@ flowchart TD
 
 在完成系统设计文档后，使用此清单自检：
 
-### 结构完整性
-- [ ] 包含所有11个必需章节
-- [ ] 架构图存在且清晰（Mermaid）
-- [ ] 数据流图存在（如适用）
+### 结构完整性
+- [ ] 包含所有11个必需章节
+- [ ] 架构图存在且清晰（Mermaid）
+- [ ] 数据流图存在（如适用）
+- [ ] 如系统涉及公共契约，11.5 Contract Verification Matrix 已填写
 - [ ] Trade-offs章节至少讨论2个重要决策
 
 ### 内容质量

package/templates/.agents/skills/system-designer/references/system-design-template.md

@@ -440,11 +440,23 @@ classDiagram
 - **Test Scenarios**:
   - [ ] 用户登录完整流程（前端 → 后端 → 数据库）
 
-### 11.4 Performance Testing (性能测试)
-- **Tool**: Locust / k6
-- **Scenarios**:
-  - [ ] 1000 并发用户登录
-  - [ ] Target: p95 < 200ms
+### 11.4 Performance Testing (性能测试)
+- **Tool**: Locust / k6
+- **Scenarios**:
+  - [ ] 1000 并发用户登录
+  - [ ] Target: p95 < 200ms
+
+### 11.5 Contract Verification Matrix (契约-验证责任矩阵)
+
+| 契约 | 风险级别 | 正常态验证 | 失败态验证 | 回归责任 |
+|------|---------|-----------|-----------|---------|
+| `POST /auth/login` | 关键路径 | 集成测试 | 非法凭证返回 401 | 认证主链路最小回归 |
+| JWT 生成规则 | 基础规则层 | 单元测试 | 非法输入/过期边界 | token 相关回归 |
+
+> **要求**:
+> - 每个关键公共契约都应有一条验证责任
+> - 失败态 / 边界态不应省略
+> - Blueprint 和 Challenge 应优先复用本矩阵，而不是完全依赖后续推断
 
 ---
 

package/templates/.agents/skills/task-planner/SKILL.md

@@ -28,19 +28,21 @@ description: 使用WBS方法将系统设计文档分解为层次化任务。支
 ## ⚠️ 核心原则
 
 > [!IMPORTANT]
-> **任务规划的四大原则**：
-> 
-> 1. **WBS层次化** - Work Breakdown Structure三级组织
-> 2. **原子化** - 每个Task 1-2周可完成
-> 3. **可验证** - 每个Task有明确的Done When标准
-> 4. **可追溯** - 每个Task关联PRD需求 [REQ-XXX]
-
-> [!IMPORTANT]
-> **测试规划附加原则**：
-> - 优先选择**最轻但足够**的验证类型
-> - 如 Workflow / ADR 已声明测试策略，必须优先遵循，不得自行改重
-> - **冒烟测试默认仅用于 `INT-S{N}` 或极少数里程碑任务**
-> - **回归测试仅在已有关键能力可能被破坏时生成**，不是所有任务的默认要求
+> **任务规划的四大原则**：
+> 
+> 1. **WBS层次化** - Work Breakdown Structure三级组织
+> 2. **原子化** - 每个 Task 优先控制在 2h-2d
+> 3. **可验证** - 默认使用 Given / When / Then；仅纯技术性基础任务允许清晰 Done When
+> 4. **可追溯** - 每个Task关联PRD需求 [REQ-XXX]
+
+> [!IMPORTANT]
+> **测试规划附加原则**：
+> - 优先选择**最轻但足够**的验证类型
+> - 如 Workflow / ADR 已声明测试策略，必须优先遵循，不得自行改重
+> - **冒烟测试默认仅用于 `INT-S{N}` 或极少数里程碑任务**
+> - **回归测试仅在已有关键能力可能被破坏时生成**，不是所有任务的默认要求
+> - **基础层、共享层、纯逻辑层默认优先单元测试**，主要分支、边界情况与错误路径应尽量覆盖
+> - **公共契约必须有承接**：至少一个实现任务 + 至少一个验证承接点
 
 ❌ **错误做法**：
 - 平铺任务列表（无层次）
@@ -49,11 +51,11 @@ description: 使用WBS方法将系统设计文档分解为层次化任务。支
 - 缺少验收标准
 - 忽略依赖关系
 
-✅ **正确做法**：
-- **三级层次**: System → Phase → Task
-- **合理粒度**: 每个Task 1-2周
-- **清晰验收**: 明确的Done When标准
-- **完整元数据**: ID, [REQ-XXX], 描述, 输入, 输出, 验收, 估时, 依赖, 优先级
+✅ **正确做法**：
+- **三级层次**: System → Phase → Task
+- **合理粒度**: 每个 Task 2h-2d
+- **清晰验收**: 默认 Given / When / Then，必要时使用清晰 Done When
+- **完整元数据**: ID, [REQ-XXX], 描述, 输入, 输出, 验收, 估时, 依赖, 优先级
 
 ---
 
@@ -113,38 +115,41 @@ description: 使用WBS方法将系统设计文档分解为层次化任务。支
 > - ✅ 好: `04_SYSTEM_DESIGN/auth.md` §JWT 签发
 > - ❌ 差: "JWT 相关设计"（无具体文档引用）
 
-**Task结构**:
-```markdown
-- [ ] **T{System}.{Phase}.{Seq}** [REQ-XXX]: 任务描述
-  - **描述**: 简洁说明"做什么"（不是"怎么做"）
-  - **输入**: 设计文档引用 + 前置任务产出（必须包含至少一个文档引用）
-  - **输出**: 产出什么交付物
-  - **📎 参考**: ADR-XXX 或 System Design 章节（如有）
-  - **验收标准**: 
-    - [ ] Done When 1
-    - [ ] Done When 2
-  - **验证类型**: 单元测试 | 集成测试 | E2E测试 | 冒烟测试 | 回归测试 | 手动验证 | 编译检查 | Lint检查
-  - **验证说明**: 如何确认任务完成 (检查什么，如何确认)
-  - **估时**: 预估工时（如: 2h, 1d, 1w）
-  - **依赖**: T{X}.{Y}.{Z} (依赖的Task ID)
-  - **优先级**: P0 | P1 | P2
-```
-
-**示例**:
-```markdown
-- [ ] **T1.1.1** [基础]: 设置 Vite + React 项目
-  - **描述**: 初始化前端项目，配置Vite、React、TypeScript
-  - **输入**: PRD (React技术栈要求)
-  - **输出**: 可运行的Hello World应用 (`src/App.tsx`, `vite.config.ts`)
-  - **验收标准**: 
-    - [ ] `npm run dev` 正常启动
-    - [ ] 页面显示"Hello World"
-    - [ ] TypeScript类型检查通过
-  - **验证类型**: 编译检查
-  - **估时**: 2h
-  - **依赖**: 无
-  - **优先级**: P0
-```
+**Task结构**:
+```markdown
+- [ ] **T{System}.{Phase}.{Seq}** [REQ-XXX]: 任务描述
+  - **描述**: 简洁说明"做什么"（不是"怎么做"）
+  - **输入**: 设计文档引用 + 前置任务产出（必须包含至少一个文档引用）
+  - **输出**: 产出什么交付物
+  - **契约承接**: 本任务实现或验证的公共契约；如无则写“无”
+  - **📎 参考**: ADR-XXX 或 System Design 章节（如有）
+  - **验收标准**: 
+    - Given [前置条件]
+    - When [执行动作]
+    - Then [预期结果]
+    - （仅纯技术性基础任务允许使用清晰 Done When 列表）
+  - **验证类型**: 单元测试 | 集成测试 | E2E测试 | 冒烟测试 | 回归测试 | 手动验证 | 编译检查 | Lint检查
+  - **验证说明**: 如何确认任务完成 (检查什么，如何确认)
+  - **估时**: 预估工时（如: 2h, 6h, 1d, 2d）
+  - **依赖**: T{X}.{Y}.{Z} (依赖的Task ID)
+  - **优先级**: P0 | P1 | P2
+```
+
+**示例**:
+```markdown
+- [ ] **T1.1.1** [基础]: 设置 Vite + React 项目
+  - **描述**: 初始化前端项目，配置Vite、React、TypeScript
+  - **输入**: PRD (React技术栈要求)
+  - **输出**: 可运行的Hello World应用 (`src/App.tsx`, `vite.config.ts`)
+  - **验收标准**: 
+    - [ ] `npm run dev` 正常启动
+    - [ ] 页面显示"Hello World"
+    - [ ] TypeScript类型检查通过
+  - **验证类型**: 编译检查
+  - **估时**: 2h
+  - **依赖**: 无
+  - **优先级**: P0
+```
 
 ### 验证类型选择逻辑
 
@@ -158,11 +163,39 @@ description: 使用WBS方法将系统设计文档分解为层次化任务。支
 5. **修改可能影响已完成关键能力** → 回归测试
 6. **配置、脚手架、基础设施** → 编译检查 / Lint检查 / 手动验证
 
-**选择细则**:
-- 不要因为任务“看起来重要”就默认选择 E2E测试
-- 如果集成测试足以证明任务完成，就不要升级为 E2E测试
-- 如果只是里程碑 readiness 检查，优先使用少量冒烟测试，而不是新建大量 E2E任务
-- 如果只是验证旧能力未被破坏，优先复用已有测试集合作为回归测试
+**选择细则**:
+- 不要因为任务“看起来重要”就默认选择 E2E测试
+- 如果集成测试足以证明任务完成，就不要升级为 E2E测试
+- 如果只是里程碑 readiness 检查，优先使用少量冒烟测试，而不是新建大量 E2E任务
+- 如果只是验证旧能力未被破坏，优先复用已有测试集合作为回归测试
+
+### 契约风险覆盖规则
+
+> [!IMPORTANT]
+> **若任务产出包含新的公共契约或会修改现有公共契约，必须为其分配明确验证承接。**
+
+公共契约至少包括：
+- 操作契约
+- 跨系统接口
+- HTTP API
+- CLI 命令 / 参数语义
+- 配置结构 / 文件格式 / 状态格式
+- 错误语义 / 返回结构
+- 持久化结构
+
+规则：
+- 每个公共契约至少要有一个实现任务承接
+- 每个高风险公共契约至少要有一个验证承接点
+- 不得仅以“实现任务已有代码变更”视为契约闭合
+- 若契约属于基础规则层或低依赖纯逻辑，应优先补充单元测试，而不是直接升级为 E2E
+
+### 基础单测优先原则
+
+> [!IMPORTANT]
+> **对 registry、manifest、parser、planner、schema、diff、merge、normalizer、selector 等基础逻辑，优先生成单元测试任务。**
+
+- 如果这些逻辑是多个上层流程共享的基础设施，其单元测试默认视为必选，不应依赖高层流程测试间接覆盖
+- 如果一个 Sprint 新增了多个基础逻辑点，优先在同 Sprint 或紧邻 Sprint 内生成对应单测任务，不要全部拖到收尾期
 
 ### Sprint 与冒烟测试绑定规则
 
@@ -256,16 +289,16 @@ T1.2.1 (前端UI设计) → T2.2.1 (后端API实现)
 
 ## 📊 任务拆分原则
 
-### 原则1: 1-2周规则
-**规则**: 单个Task应该在1-2周内完成。
+### 原则1: 2h-2d 规则
+**规则**: 单个 Task 应优先落在 2 小时到 2 天内；超过 2 天应继续拆分。
 
 **为什么？** 
 - 太大: 难以估时、风险不可控
 - 太小: 管理成本高、碎片化
 
-**检查**:
-- Task估时 > 2周 → 继续拆分
-- Task估时 < 2小时 → 考虑合并
+**检查**:
+- Task估时 > 2天 → 继续拆分
+- Task估时 < 2小时 → 考虑合并
 
 ---
 
@@ -287,12 +320,13 @@ T1.2.1 (前端UI设计) → T2.2.1 (后端API实现)
 
 ---
 
-### 原则4: 可验证性
-**规则**: 每个Task必须有明确的Done When标准。
-
-**示例**:
-- ✅ 好: "Done When: 单元测试通过, Lint无错误, 页面渲染正常"
-- ❌ 差: "Done When: 差不多完成了"
+### 原则4: 可验证性
+**规则**: 每个 Task 必须有明确、可执行、可观察的验收标准；默认使用 Given / When / Then，纯技术性基础任务可使用清晰 Done When。
+
+**示例**:
+- ✅ 好: "Given 合法输入, When 调用接口, Then 返回 200 且结构符合契约"
+- ✅ 好: "[ ] 单元测试通过（仅用于纯技术性基础任务）"
+- ❌ 差: "Done When: 差不多完成了"
 
 ---
 
@@ -314,14 +348,14 @@ T1.2.1 (前端UI设计) → T2.2.1 (后端API实现)
 
 ---
 
-### 守则2: 验收标准具体化
-**规则**: Done When必须具体、可测试、可观察。
+### 守则2: 验收标准具体化
+**规则**: 默认使用 Given / When / Then；仅当纯技术性基础任务不适合 GWT 时，才退回清晰的 Done When。
 
-**好的验收标准**:
-- [ ] 单元测试通过（`npm test`）
-- [ ] Lint无错误（`npm run lint`）
-- [ ] API返回200状态码
-- [ ] 页面在Chrome/Firefox正常渲染
+**好的验收标准**:
+- Given 输入合法, When 调用接口, Then 返回 200 且结构符合契约
+- Given 非法凭证, When 请求登录, Then 返回 401 且错误语义一致
+- [ ] 单元测试通过（仅用于纯技术性基础任务）
+- [ ] Lint无错误（仅用于纯技术性基础任务）
 
 **差的验收标准**:
 - [ ] 功能正常（太模糊）
@@ -403,7 +437,7 @@ graph TD
 
 | 检查项 | 标准 | 如何修正 |
 |--------|------|---------|
-| 估时 | 1-2周 | 过大→拆分, 过小→合并 |
+| 估时 | 2h-2d | 过大→拆分, 过小→合并 |
 | 交付物 | 单一明确 | 多个→拆分为多个Task |
 | 验收标准 | 3-5条具体标准 | 模糊→细化为可测试条件 |
 | 依赖 | < 5个依赖 | 过多→重新组织Phase |
@@ -526,11 +560,11 @@ Phase 3: 回归测试 (Regression)
 - [ ] 每个System有清晰的Phase划分
 - [ ] 每个Task有完整的元数据
 
-### 任务质量
-- [ ] 每个Task估时 1-2周
-- [ ] 每个Task有3-5条验收标准
-- [ ] 每个Task关联PRD需求 [REQ-XXX]
-- [ ] 每个Task描述清晰（"做什么"）
+### 任务质量
+- [ ] 每个Task估时 2h-2d
+- [ ] 每个Task有3-5条验收标准
+- [ ] 每个Task关联PRD需求 [REQ-XXX]
+- [ ] 每个Task描述清晰（"做什么"）
 
 ### 依赖关系
 - [ ] 提供Mermaid依赖图