dev-playbooks-cn 1.5.2 → 1.5.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dev-playbooks-cn",
-  "version": "1.5.2",
+  "version": "1.5.4",
   "description": "AI-driven spec-based development workflow",
   "keywords": [
     "devbooks",

package/skills/devbooks-delivery-workflow/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: devbooks-delivery-workflow
-description: devbooks-delivery-workflow：把一次变更跑成可追溯闭环（Design→Plan→Trace→Verify→Implement→Archive），明确 DoD、追溯矩阵与角色隔离（Test Owner 与 Coder 分离）。用户说"跑一遍闭环/交付验收/追溯矩阵/DoD/关账归档/验收工作流"等时使用。
+description: devbooks-delivery-workflow：完整闭环编排器，在支持子 Agent 的 AI 编程工具中调用，自动编排 Proposal→Design→Spec→Plan→Test→Implement→Review→Archive 全流程。用户说"跑一遍闭环/完整交付/从头到尾跑完/自动化变更流程"等时使用。
 allowed-tools:
   - Glob
   - Grep
@@ -8,9 +8,12 @@ allowed-tools:
   - Write
   - Edit
   - Bash
+  - Task
 ---
 
-# DevBooks：交付验收工作流（闭环骨架）
+# DevBooks：交付验收工作流（完整闭环编排器）
+
+> **定位**：本 Skill 是**编排层**，不是日常手动使用的 Skill。它在支持子 Agent 的 AI 编程工具（如 Claude Code with Task tool）中调用，自动编排完整的变更闭环。
 
 ## 前置：配置发现（协议无关）
 
@@ -28,57 +31,85 @@ allowed-tools:
 - 禁止猜测目录根
 - 禁止跳过规则文档阅读
 
-## 变更包命名规范（必须遵守）
+## 核心职责：完整闭环编排
 
-变更包 ID（change-id）**必须**遵循以下命名规范：
+本 Skill 的核心能力是**编排子 Agent 完成完整变更闭环**。
 
-### 格式
+### 闭环流程（8 个阶段）
 
 ```
-<日期时间>-<动词开头的语义描述>
+┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
+│  1. Propose │ ──▶ │  2. Design  │ ──▶ │  3. Spec    │ ──▶ │  4. Plan    │
+│  (提案)     │     │  (设计)     │     │  (规格)     │     │  (计划)     │
+└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘
+       │                                                           │
+       ▼                                                           ▼
+┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
+│  8. Archive │ ◀── │  7. Review  │ ◀── │  6. Code    │ ◀── │  5. Test    │
+│  (归档)     │     │  (评审)     │     │  (实现)     │     │  (测试)     │
+└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘
 ```
 
-### 规则
+### 阶段详解与对应 Skill
 
-| 组成部分 | 规则 | 示例 |
-|----------|------|------|
-| 日期时间 | `YYYYMMDD-HHMM` 格式 | `20240116-1030` |
-| 分隔符 | 日期时间与语义之间用 `-` 分隔 | `-` |
-| 语义描述 | **必须以动词开头**，使用小写和连字符 | `add-oauth2`, `fix-login-bug` |
+| 阶段 | Skill | 产物 | 角色 |
+|------|-------|------|------|
+| 1. Propose | `devbooks-proposal-author` | proposal.md | Author |
+| 1.5 Challenge（可选） | `devbooks-proposal-challenger` | 质疑意见 | Challenger |
+| 1.6 Judge（可选） | `devbooks-proposal-judge` | 裁决结果 | Judge |
+| 2. Design | `devbooks-design-doc` | design.md | Designer |
+| 3. Spec | `devbooks-spec-contract` | specs/*.md | Spec Owner |
+| 4. Plan | `devbooks-implementation-plan` | tasks.md | Planner |
+| 5. Test | `devbooks-test-owner` | verification.md + tests/ | Test Owner |
+| 6. Code | `devbooks-coder` | src/ 实现 | Coder |
+| 7. Review | `devbooks-code-review` | 评审意见 | Reviewer |
+| 7.5 Test Review（可选） | `devbooks-test-reviewer` | 测试评审 | Test Reviewer |
+| 8. Archive | `devbooks-archiver` | 归档到真理源 | Archiver |
 
-### 合法示例
+### 编排逻辑
 
-```bash
-# ✅ 正确
-20240116-1030-add-oauth2-support
-20240116-1430-fix-user-auth-bug
-20240116-0900-refactor-payment-module
-20240115-2200-update-api-docs
-
-# ❌ 错误
-add-oauth2                    # 缺少日期时间
-20240116-oauth2               # 语义不是动词开头
-2024-01-16-add-oauth2         # 日期格式错误（不应有 -）
-oauth2-20240116               # 顺序错误
+```
+1. 接收用户需求
+2. 调用 proposal-author 创建提案（自动生成 change-id）
+3. [可选] 调用 proposal-challenger 质疑提案
+4. [可选] 调用 proposal-judge 裁决
+5. 调用 design-doc 创建设计文档
+6. [如有对外契约] 调用 spec-contract 定义规格
+7. 调用 implementation-plan 创建实现计划
+8. 调用 test-owner 编写测试（独立 Agent）
+9. 调用 coder 实现功能（独立 Agent）
+10. 调用 code-review 评审代码
+11. [可选] 调用 test-reviewer 评审测试
+12. 调用 archiver 归档到真理源
 ```
 
-### 常用动词
+### 角色隔离约束
+
+**关键原则**：Test Owner 和 Coder 必须使用**独立的 Agent 实例/会话**。
+
+| 角色 | 隔离要求 | 原因 |
+|------|----------|------|
+| Test Owner | 独立 Agent | 防止 Coder 篡改测试 |
+| Coder | 独立 Agent | 防止 Coder 看到测试实现细节 |
+| Reviewer | 独立 Agent（推荐） | 保持评审客观性 |
 
-| 动词 | 用途 |
-|------|------|
-| `add` | 添加新功能 |
-| `fix` | 修复缺陷 |
-| `update` | 更新现有功能 |
-| `refactor` | 重构代码 |
-| `remove` | 删除功能 |
-| `improve` | 改进性能/体验 |
-| `migrate` | 迁移数据/系统 |
+### 闸门检查点
 
-### 为什么这样命名？
+每个阶段完成后，调用 `change-check.sh` 验证：
 
-1. **时间戳在前**：归档目录中自动按时间排序
-2. **动词开头**：清晰表达变更意图，方便代码审查
-3. **小写连字符**：避免跨平台文件名问题
+```bash
+# 提案阶段检查
+change-check.sh <change-id> --mode proposal
+
+# 实现阶段检查（Test Owner）
+change-check.sh <change-id> --mode apply --role test-owner
+
+# 实现阶段检查（Coder）
+change-check.sh <change-id> --mode apply --role coder
+
+# 归档前检查
+change-check.sh <change-id> --mode archive
+```
 
 ## 参考骨架（按需读取）
 

package/skills/devbooks-delivery-workflow/scripts/change-scaffold.sh

@@ -81,6 +81,83 @@ if [[ -z "$change_id" || "$change_id" == "-"* || "$change_id" =~ [[:space:]] ]];
   exit 2
 fi
 
+# Validate change-id format: YYYYMMDD-HHMM-<verb-prefixed-description>
+# 格式：日期时间-动词开头的语义描述
+# 示例：20240116-1030-add-oauth2-support
+validate_change_id_format() {
+  local id="$1"
+
+  # Pattern: 8 digits (date) + hyphen + 4 digits (time) + hyphen + verb-prefixed-description
+  # 日期：YYYYMMDD，时间：HHMM
+  if [[ ! "$id" =~ ^[0-9]{8}-[0-9]{4}-.+ ]]; then
+    return 1
+  fi
+
+  # Extract datetime part for validation
+  local date_part="${id:0:8}"
+  local time_part="${id:9:4}"
+  local desc_part="${id:14}"
+
+  # Validate date (basic check: year 2020-2099, month 01-12, day 01-31)
+  local year="${date_part:0:4}"
+  local month="${date_part:4:2}"
+  local day="${date_part:6:2}"
+
+  # Remove leading zeros for numeric comparison
+  year=$((10#$year))
+  month=$((10#$month))
+  day=$((10#$day))
+
+  if [[ "$year" -lt 2020 || "$year" -gt 2099 ]]; then
+    return 1
+  fi
+  if [[ "$month" -lt 1 || "$month" -gt 12 ]]; then
+    return 1
+  fi
+  if [[ "$day" -lt 1 || "$day" -gt 31 ]]; then
+    return 1
+  fi
+
+  # Validate time (hour 00-23, minute 00-59)
+  local hour="${time_part:0:2}"
+  local minute="${time_part:2:2}"
+
+  hour=$((10#$hour))
+  minute=$((10#$minute))
+
+  if [[ "$hour" -lt 0 || "$hour" -gt 23 ]]; then
+    return 1
+  fi
+  if [[ "$minute" -lt 0 || "$minute" -gt 59 ]]; then
+    return 1
+  fi
+
+  # Validate description starts with a verb (common verbs)
+  # 常用动词：add, fix, update, refactor, remove, improve, migrate, implement, ...
+  local verb_pattern="^(add|fix|update|refactor|remove|improve|migrate|implement|enable|disable|change|create|delete|modify|optimize|resolve|setup|init|configure|introduce|extract|merge|split|move|rename|deprecate|upgrade|downgrade|revert|sync|integrate|unify|standardize|simplify|extend|reduce|enhance|support|handle|validate|test|document|cleanup|prepare|finalize|complete|release|publish|deploy|hotfix|patch|bump)-"
+
+  if [[ ! "$desc_part" =~ $verb_pattern ]]; then
+    return 1
+  fi
+
+  return 0
+}
+
+if ! validate_change_id_format "$change_id"; then
+  echo "error: change-id 格式无效: '$change_id'" >&2
+  echo "" >&2
+  echo "期望格式: YYYYMMDD-HHMM-<动词开头的语义描述>" >&2
+  echo "示例: 20240116-1030-add-oauth2-support" >&2
+  echo "" >&2
+  echo "规则:" >&2
+  echo "  - 日期: YYYYMMDD (如 20240116)" >&2
+  echo "  - 时间: HHMM (如 1030 表示 10:30)" >&2
+  echo "  - 描述: 必须以动词开头 (add/fix/update/refactor/...)" >&2
+  echo "" >&2
+  echo "常用动词: add, fix, update, refactor, remove, improve, migrate, implement" >&2
+  exit 2
+fi
+
 if [[ -z "$project_root" || -z "$change_root" || -z "$truth_root" ]]; then
   usage
   exit 2

package/skills/devbooks-proposal-author/SKILL.md

@@ -32,6 +32,66 @@ allowed-tools:
 1. **提案撰写**：产出清晰、可审查、可落地的变更提案
 2. **设计性决策交互**：对于无法客观判断好坏的设计选择，呈现选项给用户决策，不自行拍板
 
+## 变更包命名规范（强制）
+
+变更包 ID（change-id）**必须**遵循以下命名规范：
+
+### 格式
+
+```
+<日期时间>-<动词开头的语义描述>
+```
+
+### 规则
+
+| 组成部分 | 规则 | 示例 |
+|----------|------|------|
+| 日期时间 | `YYYYMMDD-HHMM` 格式 | `20240116-1030` |
+| 分隔符 | 日期时间与语义之间用 `-` 分隔 | `-` |
+| 语义描述 | **必须以动词开头**，使用小写和连字符 | `add-oauth2`, `fix-login-bug` |
+
+### 示例
+
+```bash
+# ✅ 正确
+20240116-1030-add-oauth2-support
+20240116-1430-fix-user-auth-bug
+20240116-0900-refactor-payment-module
+20240115-2200-update-api-docs
+
+# ❌ 错误
+add-oauth2                    # 缺少日期时间
+20240116-oauth2               # 语义不是动词开头
+2024-01-16-add-oauth2         # 日期格式错误（不应有 -）
+oauth2-20240116               # 顺序错误
+```
+
+### 常用动词
+
+| 动词 | 用途 |
+|------|------|
+| `add` | 添加新功能 |
+| `fix` | 修复缺陷 |
+| `update` | 更新现有功能 |
+| `refactor` | 重构代码 |
+| `remove` | 删除功能 |
+| `improve` | 提升性能/体验 |
+| `migrate` | 迁移数据/系统 |
+
+### 为什么这样命名？
+
+1. **时间戳在前**：归档目录中自动按时间排序
+2. **动词开头**：清晰表达变更意图，方便代码审查
+3. **小写连字符**：避免跨平台文件名问题
+
+### 创建变更包
+
+在确定 change-id 后，调用脚手架脚本初始化变更包：
+
+```bash
+change-scaffold.sh <change-id> --project-root <repo-root> --change-root <change-root> --truth-root <truth-root>
+```
+
 ## 产物落点
 
 - 提案：`<change-root>/<change-id>/proposal.md`

package/skills/devbooks-test-reviewer/SKILL.md

@@ -53,6 +53,34 @@ allowed-tools:
 - 必须对照 `verification.md` 检查测试是否覆盖所有 AC
 - 如发现测试缺失，明确指出缺失的 AC-ID
 
+### CON-ROLE-004：只评审测试代码质量，不评论运行结果
+> 核心理念：Test Reviewer 关注的是"**测试写得好不好**"，而非"**测试跑过没有**"
+
+**禁止**：
+- 讨论测试是 Pass/Fail、Red/Green、Skip
+- 评论"功能未实现"或"依赖功能缺失"
+- 给 Coder 提实现建议（如"实现 xxx 命令"、"添加 xxx 字段"）
+- 引用工作流阶段（如"Red 基线阶段"、"这是预期行为"）
+- 基于测试运行结果判断测试质量
+
+**允许**：
+- 评审测试断言的正确性和清晰度
+- 评审测试结构和组织
+- 评审测试覆盖的场景完整性（基于代码分析，非运行结果）
+
+### CON-ROLE-005：覆盖率 = 测试存在性，非测试通过性
+
+| 覆盖状态 | 定义 | 判断依据 |
+|----------|------|----------|
+| ✅ 已覆盖 | 存在对应 AC 的测试用例 | 测试文件中有对应的 test/it block |
+| ⚠️ 部分覆盖 | 测试存在但场景不完整 | 缺少边界条件、错误路径等 |
+| ❌ 缺失 | 没有对应测试用例 | 找不到对应的测试代码 |
+
+**禁止**将以下状态纳入覆盖率判断：
+- 测试 Skip 状态（skip 的测试仍算"已覆盖"）
+- 测试 Fail 状态（失败的测试仍算"已覆盖"）
+- 测试运行时间或性能
+
 ---
 
 ## 评审维度
@@ -104,11 +132,13 @@ allowed-tools:
 
 ## 覆盖率分析
 
+> **注意**：覆盖状态基于测试代码存在性判断，与测试运行结果（Pass/Fail/Skip）无关。
+
 | AC-ID | 测试文件 | 覆盖状态 | 备注 |
 |-------|----------|----------|------|
-| AC-001 | test-a.ts | ✅ 已覆盖 | - |
-| AC-002 | - | ❌ 缺失 | 需要添加 |
-| AC-003 | test-b.ts | ⚠️ 部分覆盖 | 缺少边界条件 |
+| AC-001 | test-a.ts | ✅ 已覆盖 | 测试用例存在 |
+| AC-002 | - | ❌ 缺失 | 无对应测试代码 |
+| AC-003 | test-b.ts | ⚠️ 部分覆盖 | 测试存在但缺少边界条件 |
 
 ## 问题清单
 
@@ -178,7 +208,7 @@ allowed-tools:
 | Skill 名称 | devbooks-test-reviewer |
 | 阶段 | Apply |
 | 产物 | 评审报告（不写入变更包） |
-| 约束 | CON-ROLE-001~003 |
+| 约束 | CON-ROLE-001~005 |
 
 ---