@haaaiawd/anws 2.1.2 → 2.2.1

package/templates/.agents/skills/task-planner/references/TASK_TEMPLATE.md

@@ -12,23 +12,33 @@
 - **ID**: 唯一任务标识符（T{System}.{Phase}.{Seq}）
 - **[P]**: 可并行（可独立执行）
 - **[MILESTONE]**: 里程碑 / Sprint 关卡任务（如 `INT-S{N}`）
-- **用户故事**: 映射到 PRD（US01, US02...）
-- **验收标准**: Given / When / Then 或 Done When 形式的完成条件
-- **验证类型**: 单元测试 / 集成测试 / E2E测试 / 冒烟测试 / 回归测试 / 手动验证 / 编译检查 / Lint检查
-- **验证说明**: 如何验证任务完成、需要什么证据
-- **📎 ADR**: 关联的架构决策记录
-- **📎 System**: 关联的系统设计文档
+- **用户故事**: 映射到 PRD（US01, US02...）
+- **验收标准**: Given / When / Then 或 Done When 形式的完成条件
+- **验证类型**: 单元测试 / 集成测试 / E2E测试 / 冒烟测试 / 回归测试 / 手动验证 / 编译检查 / Lint检查
+- **验证说明**: 如何验证任务完成、需要什么证据
+- **契约承接**: 本任务实现或验证的公共契约（如接口、CLI 语义、配置结构、文件格式、错误语义）
+- **📎 ADR**: 关联的架构决策记录
+- **📎 System**: 关联的系统设计文档
+
+### 生成提醒
+- 公共契约至少要有一个实现任务承接
+- 高风险公共契约至少要有一个验证承接点
+- 基础层、共享层、纯逻辑层默认优先单元测试
+- registry / manifest / parser / planner / schema / diff / merge / normalizer / selector 等基础逻辑，主要分支、边界情况和错误路径应尽量由单元测试覆盖
+- 冒烟测试默认收敛到 `INT-S{N}` 或极少数里程碑任务，不要扩散到普通开发任务
+- 任务粒度默认控制在 2h-2d；纯技术性基础任务可使用 Done When，其余任务优先 Given / When / Then
 
 ---
 
 ### 阶段 1：基础阶段
 
-#### T3.1.1 - 数据库 Schema 初始化
-- **用户故事**: US01
-- **描述**: 创建 `users` 表，包含 `id`、`email`、`password_hash`、`created_at` 字段。
-- **输入**: `04_SYSTEM_DESIGN/database.md` §用户表设计
-- **输出**: `migrations/001_create_users.sql`
-- **依赖**: 无
+#### T3.1.1 - 数据库 Schema 初始化
+- **用户故事**: US01
+- **描述**: 创建 `users` 表，包含 `id`、`email`、`password_hash`、`created_at` 字段。
+- **输入**: `04_SYSTEM_DESIGN/database.md` §用户表设计
+- **输出**: `migrations/001_create_users.sql`
+- **契约承接**: 数据库 schema 契约（`users` 表结构）
+- **依赖**: 无
 - **验收标准**:
   - Given 数据库已启动
   - When 执行迁移并查看 `users` 表结构
@@ -37,12 +47,13 @@
 - **验证说明**: 运行迁移并执行 `psql -c "\d users"`，保留终端输出作为证据
 - **📎 ADR**: ADR-003 (密码存储方案)
 
-#### T1.1.1 - [P] 环境配置
-- **用户故事**: US01
-- **描述**: 添加包含 `DATABASE_URL`、`JWT_SECRET` 的 `.env` 文件。
-- **输入**: `02_ARCHITECTURE_OVERVIEW.md` §环境配置
-- **输出**: `.env.example`, `docker-compose.yml`
-- **依赖**: 无
+#### T1.1.1 - [P] 环境配置
+- **用户故事**: US01
+- **描述**: 添加包含 `DATABASE_URL`、`JWT_SECRET` 的 `.env` 文件。
+- **输入**: `02_ARCHITECTURE_OVERVIEW.md` §环境配置
+- **输出**: `.env.example`, `docker-compose.yml`
+- **契约承接**: 环境配置结构契约
+- **依赖**: 无
 - **验收标准**:
   - Given 环境变量模板与容器配置已写入
   - When 执行 `docker-compose up`
@@ -54,12 +65,13 @@
 
 ### 阶段 2：核心逻辑
 
-#### T2.1.1 - 用户注册接口
-- **用户故事**: US01
-- **描述**: 实现 `POST /api/register`，对密码做哈希并保存用户。
-- **输入**: `04_SYSTEM_DESIGN/auth.md` §注册流程, T3.1.1 产出的 `users` 表
-- **输出**: `src/routes/auth.js`, `src/services/user.service.js`
-- **依赖**: T3.1.1
+#### T2.1.1 - 用户注册接口
+- **用户故事**: US01
+- **描述**: 实现 `POST /api/register`，对密码做哈希并保存用户。
+- **输入**: `04_SYSTEM_DESIGN/auth.md` §注册流程, T3.1.1 产出的 `users` 表
+- **输出**: `src/routes/auth.js`, `src/services/user.service.js`
+- **契约承接**: `POST /api/register` HTTP API 契约
+- **依赖**: T3.1.1
 - **验收标准**:
   - Given 注册接口已实现
   - When 发送合法注册请求
@@ -68,12 +80,13 @@
 - **验证说明**: 调用 `POST /api/register` 并检查响应与数据库写入结果
 - **📎 ADR**: ADR-003 (密码存储方案)
 
-#### T2.1.2 - [P] JWT Token 生成
-- **用户故事**: US01
-- **描述**: 创建 `generate_token(user_id)` 辅助函数。
-- **输入**: `04_SYSTEM_DESIGN/auth.md` §JWT 签发, T1.1.1 产出的 `JWT_SECRET` 配置
-- **输出**: `src/utils/jwt.js`
-- **依赖**: T1.1.1
+#### T2.1.2 - [P] JWT Token 生成
+- **用户故事**: US01
+- **描述**: 创建 `generate_token(user_id)` 辅助函数。
+- **输入**: `04_SYSTEM_DESIGN/auth.md` §JWT 签发, T1.1.1 产出的 `JWT_SECRET` 配置
+- **输出**: `src/utils/jwt.js`
+- **契约承接**: JWT 生成规则契约（基础逻辑）
+- **依赖**: T1.1.1
 - **验收标准**:
   - Given JWT 辅助函数已实现
   - When 运行 `test_generate_token()`
@@ -95,12 +108,13 @@
 
 ### 阶段 3：集成阶段
 
-#### T2.2.1 - 登录接口
-- **用户故事**: US01
-- **描述**: 实现 `POST /api/login`，校验凭证并返回 JWT。
-- **输入**: `04_SYSTEM_DESIGN/auth.md` §登录流程, T2.1.1 产出的 `users` 表, T2.1.2 产出的 `generate_token()` 函数
-- **输出**: `/api/login` 端点 (`src/routes/auth.js`)
-- **依赖**: T2.1.1, T2.1.2
+#### T2.2.1 - 登录接口
+- **用户故事**: US01
+- **描述**: 实现 `POST /api/login`，校验凭证并返回 JWT。
+- **输入**: `04_SYSTEM_DESIGN/auth.md` §登录流程, T2.1.1 产出的 `users` 表, T2.1.2 产出的 `generate_token()` 函数
+- **输出**: `/api/login` 端点 (`src/routes/auth.js`)
+- **契约承接**: `POST /api/login` HTTP API 契约；401 错误语义
+- **依赖**: T2.1.1, T2.1.2
 - **验收标准**:
   - Given 登录接口已实现
   - When 使用合法凭证请求登录
@@ -112,19 +126,23 @@
 - **验证说明**: 调用 `/api/login` 并分别检查成功与失败路径
 - **📎 ADR**: ADR-004 (JWT 认证方案)
 
-#### INT-S2 - [MILESTONE] S2 集成验证 — 核心逻辑
-- **用户故事**: US01
-- **描述**: 验证 S2 退出标准：完整认证流程可运行
-- **输入**: `02_ARCHITECTURE_OVERVIEW.md` §认证流程, S2 所有任务的产出
-- **输出**: 集成验证报告
-- **依赖**: T2.1.1, T2.1.2, T2.2.1
-- **验收标准**:
-  1. 运行 `npm run dev` 或等价命令
-  2. 通过 `/api/register` 注册新用户
-  3. 使用合法凭证登录 → 收到 JWT 令牌
-  4. 使用非法凭证登录 → 收到 401 错误
-  5. 所有单元测试通过（`npm test`）
-  6. 无 Linter 错误（`npm run lint`）
+#### INT-S2 - [MILESTONE] S2 集成验证 — 核心逻辑
+- **用户故事**: US01
+- **描述**: 验证 S2 退出标准：完整认证流程可运行
+- **输入**: `02_ARCHITECTURE_OVERVIEW.md` §认证流程, S2 所有任务的产出
+- **输出**: 集成验证报告
+- **契约承接**: 注册/登录主链路契约；关键路径最小冒烟验证
+- **依赖**: T2.1.1, T2.1.2, T2.2.1
+- **验收标准**:
+  - Given S2 所有任务已完成且服务已启动
+  - When 通过 `/api/register` 注册新用户并使用合法凭证登录
+  - Then 收到 JWT 令牌且主链路可运行
+  - Given 非法凭证
+  - When 请求 `/api/login`
+  - Then 返回 401 且错误语义符合契约
+  - Given 本 Sprint 相关自动验证已执行
+  - When 查看测试与 lint 结果
+  - Then 单元测试通过且无 Linter 错误
 - **验证类型**: 集成测试 / 冒烟测试
 - **验证说明**: 按退出标准逐条执行；使用真实注册与登录链路作为最小冒烟检查，并保留日志或截图
 
@@ -160,11 +178,13 @@ T1.1.1 (环境配置) [P]
 在将蓝图标记为完成前：
 - [ ] 所有任务都有唯一 ID
 - [ ] 依赖关系明确（使用 `→` 表示）
-- [ ] 每个任务都有 `验收标准`
-- [ ] 每个任务都有 `验证类型` 与 `验证说明`
-- [ ] **每个任务的「输入」都引用了设计文档**（ADR/System Design/PRD/Architecture）
-- [ ] 任务中不包含实际代码（仅保留 <10 行描述）
-- [ ] 总体估时合理
+- [ ] 每个任务都有 `验收标准`
+- [ ] 每个任务都有 `验证类型` 与 `验证说明`
+- [ ] 每个公共契约都有实现承接，且高风险公共契约有明确验证承接
+- [ ] 基础层低依赖逻辑默认获得单元测试承接，并覆盖主要分支/边界/错误路径
+- [ ] **每个任务的「输入」都引用了设计文档**（ADR/System Design/PRD/Architecture）
+- [ ] 任务中不包含实际代码（仅保留 <10 行描述）
+- [ ] 总体估时合理
 - [ ] 用户已确认该任务清单
 
 ---
@@ -180,13 +200,14 @@ T001 - 构建认证系统
 
 ✅ **好任务示例**：
 ```
-T3.1.1 - 数据库 Schema 初始化
-- 输入: `04_SYSTEM_DESIGN/database.md` §用户表设计
-- 描述: 创建包含 `id`、`email`、`password_hash` 的 `users` 表。
-- 验收标准: Given 迁移完成, When 查看表结构, Then 字段与设计一致。
-- 验证类型: 集成测试
-- 📎 ADR: ADR-003 (密码存储方案)
-```
+T3.1.1 - 数据库 Schema 初始化
+- 输入: `04_SYSTEM_DESIGN/database.md` §用户表设计
+- 描述: 创建包含 `id`、`email`、`password_hash` 的 `users` 表。
+- 契约承接: 数据库 schema 契约
+- 验收标准: Given 迁移完成, When 查看表结构, Then 字段与设计一致。
+- 验证类型: 集成测试
+- 📎 ADR: ADR-003 (密码存储方案)
+```
 
 ---
 

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

@@ -1,6 +1,6 @@
 ---
 name: task-reviewer
-description: 系统性审查 05_TASKS.md 的质量与完备性，作为 challenge 工作流中的规范契约任务承接证据层。通过 6 大检测 Pass 在语义模型上运行，检测重复、歧义、欠详述、不一致、覆盖缺口和质量问题。
+description: 系统性审查 05_TASKS.md 的质量与完备性，作为 challenge 工作流中的规范契约任务承接证据层。通过 7 大检测 Pass 在语义模型上运行，检测重复、歧义、欠详述、不一致、覆盖缺口和质量问题。
 ---
 
 # 任务审查大师手册
@@ -8,16 +8,16 @@ description: 系统性审查 05_TASKS.md 的质量与完备性，作为 challeng
 > "计划的质量取决于最薄弱的那个任务。  
 > 在代码暴露问题之前，找到裂缝。"
 
-你是**任务审查大师**，负责对 `05_TASKS.md` 进行系统性审计——以 PRD、Architecture 和 ADR 文档为基准，运行 **6 大检测 Pass**。你的武器是**语义模型**，而非朴素的字符串匹配。
+你是**任务审查大师**，负责对 `05_TASKS.md` 进行系统性审计——以 PRD、Architecture 和 ADR 文档为基准，运行 **7 大检测 Pass**。你的武器是**语义模型**，而非朴素的字符串匹配。
 在 `/challenge` 工作流中，你的角色是：**为规范契约是否被任务承接、覆盖和验证提供证据**，而不是单独替代 challenge 的总判断。
 你优先要证明的是：关键承诺是否有实现任务、验证任务、边界/失败路径任务，以及是否存在幽灵任务稀释主轴。
 
 ---
 ## 任务目标
 
-1. **加载文档 (必须)**: 读取 `.anws/v{N}/05_TASKS.md`、`01_PRD.md`、`02_ARCHITECTURE_OVERVIEW.md` 以及所有 `03_ADR/*.md`。
-2. **构建语义模型**: 构建 3 个清单模型（见 §语义模型构建）。
-3. **执行 6 大 Pass (A→F)**: 顺序执行每个检测 Pass——每个 Pass 在语义模型上操作。
+1. **加载文档 (必须)**: 读取 `.anws/v{N}/05_TASKS.md`、`01_PRD.md`、`02_ARCHITECTURE_OVERVIEW.md`、所有 `03_ADR/*.md`，以及 `04_SYSTEM_DESIGN/*.md`（如存在）。
+2. **构建语义模型**: 构建 4 个清单模型（见 §语义模型构建）。
+3. **执行 7 大 Pass (A→G)**: 顺序执行每个检测 Pass——每个 Pass 在语义模型上操作。
 4. **严重度分级**: 为每条发现分配严重度（CRITICAL / HIGH / MEDIUM / LOW）。
 5. **生成报告**: 输出任务审查报告（见 §输出格式）。
 6. **展示摘要**: 向用户展示检测汇总表 + 前 10 条发现。
@@ -27,12 +27,13 @@ description: 系统性审查 05_TASKS.md 的质量与完备性，作为 challeng
 - **发现上限**: 最多 50 条。超出时按严重度排序 → 截断 → 追加溢出摘要。
 - **只报告不修复**: 本技能**仅输出报告**。修复由用户或其他工作流完成。
 - **跨文档依赖**: Pass D 和 E **依赖** PRD + Architecture。若缺失，跳过相应 Pass 并注明。
+- **契约证据依赖**: Pass G 默认依赖 `04_SYSTEM_DESIGN/*.md`。若任务涉及公共契约而设计文档缺失，必须报告“证据不足 / 契约定义缺口”，不得静默忽略。
 - **客观性**: 仅标记客观可检测的问题。不要为了填满报告而捏造问题。
 
 ---
 ## 语义模型构建
 
-> 在执行任何 Pass 之前，先构建以下 3 个模型。所有 Pass 在模型上操作，而非原始文本。
+> 在执行任何 Pass 之前，先构建以下 4 个模型。所有 Pass 在模型上操作，而非原始文本。
 
 ### 模型 1: 需求清单 (Requirements Inventory)
 
@@ -71,13 +72,27 @@ T{X.Y.Z}: 标题
   ├── 所属系统: Level 1 WBS 系统名称
   ├── 依赖: [T{A.B.C}, ...]
   ├── 验收标准: [列表]
+  ├── 契约承接: [公共契约列表]
   ├── 预估工时: N
   └── Sprint: S{N}
 ```
 
+### 模型 4: 契约清单 (Contract Inventory)
+
+从 `02_ARCHITECTURE_OVERVIEW.md`、`03_ADR/*.md`、`04_SYSTEM_DESIGN/*.md` 中提取所有公共契约：
+
+```
+CONTRACT-001: CLI / API / 接口 / 配置 / 文件格式 / 错误语义 / 持久化结构
+  ├── 来源文档: Architecture / ADR / System Design
+  ├── 风险级别: 基础规则层 | 跨系统 | 关键路径
+  ├── 实现承接任务: [T{...}, ...]
+  ├── 验证承接任务: [T{...}, INT-S{N}, ...]
+  └── 关注点: [边界情况 / 错误路径 / 回归责任]
+```
+
 ---
 
-## 🔍 6 大检测 Pass
+## 🔍 7 大检测 Pass
 
 ### Pass A: 重复检测 (Duplication Detection)
 
@@ -119,7 +134,7 @@ T{X.Y.Z}: 标题
 | C3 | **幽灵引用** | 任务引用了 Architecture 文档中不存在的组件/接口/API |
 | C4 | **缺失输入/输出** | 任务没有明确的输入或输出字段 |
 | C5 | **缺失验证说明** | 任务没有说明如何验证完成 |
-| C6 | **缺失验证类型** | 任务没有指定验证类型（单元测试/集成测试/E2E测试/手动验证/编译检查/Lint检查） |
+| C6 | **缺失验证类型** | 任务没有指定验证类型（单元测试/集成测试/E2E测试/冒烟测试/回归测试/手动验证/编译检查/Lint检查） |
 
 **严重度规则**: C2 在 P0 任务上 → CRITICAL。C3 一律 → HIGH。C6 在 P0 任务上 → HIGH。
 
@@ -172,13 +187,33 @@ T{X.Y.Z}: 标题
 | F3 | **深度依赖链** | 链长 > 5 → 警告瓶颈风险 |
 | F4 | **孤立任务** | 无依赖方且不被依赖（孤岛）→ 确认是否有意为之 |
 | F5 | **关键路径分析** | 识别最长依赖链 → 标出瓶颈任务 |
-| F6 | **验收标准质量** | Given-When-Then 完整性 + 可执行验证方法 |
+| F6 | **验收标准质量** | 默认检查 Given-When-Then 完整性；纯技术性基础任务允许清晰 Done When + 可执行验证方法 |
 | F7 | **Sprint 均衡度** | Sprint 工作量方差 > 均值 50% → 不均衡警告 |
 
 **严重度规则**: F1 > 16h → HIGH。F3 链 > 7 → HIGH。F5 仅信息 → LOW。
 
 ---
 
+### Pass G: 契约覆盖检测 (Contract Coverage)
+
+**目标**: 确保公共契约与基础单测责任没有漏口。
+
+| # | 检查项 | 如何检查 |
+|---|--------|---------|
+| G1 | **公共契约无实现承接** | Contract Inventory 中的公共契约在 Tasks 中找不到对应实现任务。 |
+| G2 | **公共契约无验证承接** | 契约有实现任务，但没有明确验证类型/验证说明/INT 承接。 |
+| G3 | **高风险契约缺错误路径验证** | API / CLI / 配置 / 文件格式等契约没有失败态、边界态验证责任。 |
+| G4 | **基础逻辑缺单测承接** | registry / manifest / parser / schema / diff / merge / normalizer / planner 等基础逻辑没有单元测试承接。 |
+| G5 | **契约与验证类型错配** | 明显公共契约仅给模糊手动验证或验证层级明显不足。 |
+| G6 | **回归责任缺失** | 变更影响既有关键契约，但任务中无最小回归验证。 |
+
+**严重度规则**: G1 在 P0 或核心契约上 → CRITICAL。G2/G3/G6 → HIGH。G4 共享基础逻辑缺单测 → HIGH。G5 → MEDIUM。
+
+> [!IMPORTANT]
+> **如果任务声明了 `契约承接`，但在 `04_SYSTEM_DESIGN/*.md` / ADR / Architecture 中找不到对应契约来源，应优先报告为设计证据缺口，而不是默认视作任务正确。**
+
+---
+
 ## 📊 输出格式：任务审查报告
 
 按以下结构生成报告：
@@ -186,8 +221,8 @@ T{X.Y.Z}: 标题
 ```markdown
 ## 📊 任务审查报告
 
-> **审查文件**: .anws/v{N}/05_TASKS.md  
-> **对照文档**: 01_PRD.md, 02_ARCHITECTURE_OVERVIEW.md, 03_ADR/*  
+> **审查文件**: .anws/v{N}/05_TASKS.md
+> **对照文档**: 01_PRD.md, 02_ARCHITECTURE_OVERVIEW.md, 03_ADR/*, 04_SYSTEM_DESIGN/*
 > **日期**: {YYYY-MM-DD}
 
 ---
@@ -202,6 +237,7 @@ T{X.Y.Z}: 标题
 | D 不一致性检测 | — | — | — | — | — |
 | E 覆盖率检测 | — | — | — | — | — |
 | F 质量粒度 | — | — | — | — | — |
+| G 契约覆盖 | — | — | — | — | — |
 | **合计** | **—** | **—** | **—** | **—** | **—** |
 
 **整体健康度**: 🟢 健康 / 🟡 需关注 / 🔴 阻塞
@@ -238,6 +274,18 @@ T{X.Y.Z}: 标题
 
 ---
 
+### 契约覆盖率
+
+| 契约 | 类型 | 实现承接 | 验证承接 | 状态 |
+|------|------|---------|---------|:----:|
+| `update --target` 显式选择语义 | CLI | T1.2.1 | T6.2.1 | ✅ |
+| install-lock fallback 重建语义 | 状态/文件格式 | T4.1.1 | T6.2.1 | ✅ |
+| adapter target matrix 映射 | 基础规则层 | T2.1.1 | T6.1.1 | ✅ |
+
+**设计证据来源**: 已读取 / 未读取 `04_SYSTEM_DESIGN/*`
+
+---
+
 ### 关键路径
 
 > 最长依赖链，高亮瓶颈任务。

package/templates/.agents/workflows/blueprint.md

@@ -43,9 +43,10 @@ description: "将架构设计拆解为可执行的 WBS 任务清单。适用于
     - [ ] `{TARGET_DIR}/01_PRD.md` 存在
     - [ ] `{TARGET_DIR}/02_ARCHITECTURE_OVERVIEW.md` 存在
 
-4.  **检查可选文件** (如缺失则提示):
-    - [ ] `{TARGET_DIR}/04_SYSTEM_DESIGN/` 存在
-    - 如缺失: 提示 "建议先运行 `/design-system` 为每个系统生成详细设计。跳过此步可能导致任务粒度过粗。"
+4.  **检查条件性必需文件**:
+    - [ ] `{TARGET_DIR}/04_SYSTEM_DESIGN/` 存在
+    - 如缺失: 提示 "建议先运行 `/design-system` 为每个系统生成详细设计。跳过此步可能导致任务粒度过粗。"
+    - **如果本版本涉及公共接口、CLI 参数语义、配置结构、文件格式、错误语义、跨系统协议或持久化结构** → `04_SYSTEM_DESIGN/` 视为**必需**，缺失时不得继续正常拆解
 
 5.  **如果必需文件缺失**: 报错并提示运行 `/genesis` 更新该版本。
 
@@ -57,11 +58,45 @@ description: "将架构设计拆解为可执行的 WBS 任务清单。适用于
 
 1.  **读取 Architecture**: 读取 `{TARGET_DIR}/02_ARCHITECTURE_OVERVIEW.md`
 2.  **读取 PRD**: 读取 `{TARGET_DIR}/01_PRD.md`
-3.  **读取 ADRs**: 扫描 `{TARGET_DIR}/03_ADR/` 目录
-4.  **加载测试策略约束**:
-    - 如 `{TARGET_DIR}/03_ADR/` 中存在测试策略、质量门禁、验证分层相关 ADR，必须一并读取
-    - 将其中关于单元/集成/E2E/冒烟/回归测试的约束视为 Task 生成输入，而不是事后参考
-5.  **调用技能**: `task-planner`
+3.  **读取 ADRs**: 扫描 `{TARGET_DIR}/03_ADR/` 目录
+4.  **加载测试策略约束**:
+    - 如 `{TARGET_DIR}/03_ADR/` 中存在测试策略、质量门禁、验证分层相关 ADR，必须一并读取
+    - 将其中关于单元/集成/E2E/冒烟/回归测试的约束视为 Task 生成输入，而不是事后参考
+5.  **提取公共契约与验证责任**:
+    - 从 `02_ARCHITECTURE_OVERVIEW.md`、`03_ADR/`、`04_SYSTEM_DESIGN/` 中提取所有公共契约
+    - 至少覆盖：操作契约、跨系统接口、HTTP API、CLI 命令/参数语义、配置结构、文件格式、错误语义、持久化结构
+    - 这些契约必须作为 Task 生成输入，而不是留给 `/forge` 临场猜测
+6.  **调用技能**: `task-planner`
+
+---
+
+## Step 1.5: 契约承接建模 (Contract Mapping)
+
+**目标**: 在任务拆解前，先确认哪些公共契约必须被任务和验证接住。
+
+> [!IMPORTANT]
+> **公共契约必须有承接。**
+>
+> Blueprint 不只要覆盖 REQ 和 User Story，还要确保对外可观察契约不会在实现阶段裸奔。
+>
+> **如果公共契约需要依赖 `04_SYSTEM_DESIGN` 才能被明确定义，而该目录缺失，应直接报告“契约定义缺口”，而不是继续生成看似完整的任务清单。**
+
+执行要求：
+
+1. 从设计文档中提取所有公共契约
+2. 判断每个契约属于：
+   - 基础规则层契约
+   - 跨模块/跨系统契约
+   - 关键用户路径契约
+3. 对每个公共契约至少规划：
+   - 一个实现承接任务
+   - 一个验证承接点（单元测试 / 集成测试 / INT / E2E / 手动验证 之一）
+4. 如契约属于基础层纯逻辑、映射、解析、归一化、注册表、schema、planner、diff/merge 等低依赖逻辑：
+   - 默认优先生成单元测试承接
+   - 主要分支、边界情况和错误路径应尽量被单元测试覆盖
+
+> [!IMPORTANT]
+> **禁止把“公共契约的验证责任”全部拖到高层集成或 E2E。**
 
 ---
 
@@ -74,25 +109,30 @@ description: "将架构设计拆解为可执行的 WBS 任务清单。适用于
 > 每个 Level 3 任务必须包含以下字段。
 
 > [!IMPORTANT]
-> **调用 `task-planner` 时必须显式传递以下约束**:
-> - 当前版本的 PRD、Architecture、ADRs、System Design 是唯一事实来源
-> - 如 ADR 中存在测试策略与质量门禁，`task-planner` 必须优先遵循
-> - 默认按“最轻但足够”的原则选择验证类型
-> - **冒烟测试默认仅放在 `INT-S{N}` 或极少数里程碑任务**
-> - 不得因为“更保险”就把大量任务默认升级成 E2E测试
+> **调用 `task-planner` 时必须显式传递以下约束**:
+> - 当前版本的 PRD、Architecture、ADRs、System Design 是唯一事实来源
+> - 如 ADR 中存在测试策略与质量门禁，`task-planner` 必须优先遵循
+> - 默认按“最轻但足够”的原则选择验证类型
+> - 每个公共契约至少要有一个实现任务承接
+> - 每个高风险公共契约至少要有一个明确的验证承接点
+> - 基础层纯逻辑、规则映射、解析、归一化、注册表、schema、planner、diff/merge 等低依赖逻辑，应默认优先单元测试，且主要分支/边界/错误路径应尽量覆盖
+> - **冒烟测试默认仅放在 `INT-S{N}` 或极少数里程碑任务**
+> - 不得因为“更保险”就把大量任务默认升级成 E2E测试
 
 ### 任务格式模板
 
 ```markdown
-- [ ] **T{X}.{Y}.{Z}** [REQ-XXX]: 任务标题
-  - **描述**: 具体要做什么
-  - **输入**: 设计文档引用 + 前置任务产出（必须包含至少一个文档引用）
-  - **输出**: 产出的文件/组件/接口
-  - **📎 参考**: ADR_XXX_*.md 或 System Design 章节（如有）
-  - **验收标准**:
-    - Given [前置条件]
-    - When [执行动作]
-    - Then [预期结果]
+- [ ] **T{X}.{Y}.{Z}** [REQ-XXX]: 任务标题
+  - **描述**: 具体要做什么
+  - **输入**: 设计文档引用 + 前置任务产出（必须包含至少一个文档引用）
+  - **输出**: 产出的文件/组件/接口
+  - **契约承接**: [本任务实现或验证的公共契约；如无可写“无”]
+  - **📎 参考**: ADR_XXX_*.md 或 System Design 章节（如有）
+  - **验收标准**:
+    - Given [前置条件]
+    - When [执行动作]
+    - Then [预期结果]
+    - （仅当纯技术性基础任务不适合 GWT 时，才允许使用清晰的 Done When 列表）
   - **验证类型**: [单元测试 | 集成测试 | E2E测试 | 冒烟测试 | 回归测试 | 手动验证 | 编译检查 | Lint检查]
   - **验证说明**: [如何检查完成，检查什么，具体命令或步骤]
   - **估时**: Xh
@@ -104,12 +144,25 @@ description: "将架构设计拆解为可执行的 WBS 任务清单。适用于
 > [!IMPORTANT]
 > **Blueprint 必须按测试分层生成任务，而不是把所有验证都塞成 E2E。**
 >
-> 默认采用以下层次：
-> - **单元测试**: 验证局部逻辑
-> - **集成测试**: 验证模块/系统协作
-> - **冒烟测试**: 验证里程碑关口的少量关键路径是否可运行
-> - **E2E测试**: 验证关键用户故事或主业务链路
-> - **回归测试**: 验证新变更未破坏已完成的关键能力
+> 默认采用以下层次：
+> - **单元测试**: 验证局部逻辑；基础层、共享层、纯逻辑层默认优先，且应尽量覆盖主要分支、边界情况和错误路径
+> - **集成测试**: 验证模块/系统协作
+> - **冒烟测试**: 验证里程碑关口的少量关键路径是否可运行
+> - **E2E测试**: 验证关键用户故事或主业务链路
+> - **回归测试**: 验证新变更未破坏已完成的关键能力
+
+### 契约覆盖规则
+
+> [!IMPORTANT]
+> **Blueprint 必须确保公共契约被任务和验证接住。**
+>
+> 公共契约包括：操作契约、跨系统接口、HTTP API、CLI 参数语义、配置结构、文件格式、错误语义、持久化结构。
+
+要求：
+- 每个公共契约至少有一个实现任务承接
+- 每个高风险公共契约至少有一个验证承接点
+- 不得仅因为“后面会有集成测试”就省略基础规则层的单元测试
+- 若某契约会影响既有关键能力，应额外规划最小回归验证责任
 
 ### 冒烟测试使用原则
 
@@ -194,7 +247,7 @@ graph TD
 
 ---
 
-## Step 5: User Story Overlay (交叉验证)
+## Step 5: User Story Overlay (交叉验证)
 
 **目标**: 从**用户价值维度**验证任务完备性。WBS 按系统拆解，这一步从 User Story 视角交叉检查。
 
@@ -213,7 +266,20 @@ graph TD
    - 每个 US 的 task 链是否能形成**可独立验证**的闭环？
    - 高优先级 US (P0) 的 task 是否分布在靠前的 Sprint？
 
-4. **生成 User Story View**: 追加到 `05_TASKS.md` 末尾
+4. **生成 User Story View**: 追加到 `05_TASKS.md` 末尾
+
+5. **生成 Contract Coverage Overlay**: 如存在公共契约，追加到 `05_TASKS.md` 末尾
+
+### Contract Coverage Overlay 格式
+
+```markdown
+## 🔐 Contract Coverage Overlay
+
+| 契约 | 类型 | 实现承接 | 验证承接 | 状态 |
+|------|------|---------|---------|:----:|
+| `update --target` 显式选择语义 | CLI | T1.2.1 | T6.2.1 | ✅ |
+| install-lock fallback 重建语义 | 文件/状态格式 | T4.1.1 | T6.2.1 | ✅ |
+```
 
 ### User Story View 格式
 
@@ -258,14 +324,16 @@ graph TD
 
 ---
 
-## 检查清单
-- ✅ 每个 Sprint 有退出标准和 INT 集成验证任务？
-- ✅ 05_TASKS.md 是否包含所有 WBS 任务？
-- ✅ 每个任务是否有 Context 和 Acceptance Criteria？
-- ✅ 任务间的输入/输出是否对齐（接口追溯）？
-- ✅ 是否生成了 Mermaid 依赖图？
-- ✅ User Story Overlay 已生成，覆盖 GAP 已补充？
-- ✅ 已更新 AGENTS.md（含初始波次建议）？
+## 检查清单
+- ✅ 每个 Sprint 有退出标准和 INT 集成验证任务？
+- ✅ 05_TASKS.md 是否包含所有 WBS 任务？
+- ✅ 每个任务是否有 Context 和 Acceptance Criteria？
+- ✅ 任务间的输入/输出是否对齐（接口追溯）？
+- ✅ 公共契约是否都被实现任务与验证承接点接住？
+- ✅ 基础层低依赖逻辑是否默认获得单元测试承接，且覆盖主要分支/边界/错误路径？
+- ✅ 是否生成了 Mermaid 依赖图？
+- ✅ User Story Overlay 已生成，覆盖 GAP 已补充？
+- ✅ 已更新 AGENTS.md（含初始波次建议）？
 
 ---