dev-playbooks-cn 1.0.16 → 1.0.17

package/package.json

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

package/skills/_shared/references//351/200/232/347/224/250/345/256/210/351/227/250/345/215/217/350/256/256.md

@@ -24,6 +24,81 @@
 
 ---
 
+## 0.5 产出物路径强制约定（Output Path Convention）
+
+> **核心原则**：所有产出物必须输出到正确的目录，禁止输出到项目根目录或其他错误位置。
+
+### 路径映射表（必须遵守）
+
+| 产出物类型 | 正确路径 | 错误路径（禁止） |
+|------------|----------|------------------|
+| 变更文档 | `<change-root>/<change-id>/` | 项目根目录 |
+| 证据文件 | `<change-root>/<change-id>/evidence/` | `./evidence/` |
+| Red 基线 | `<change-root>/<change-id>/evidence/red-baseline/` | `./evidence/red-baseline/` |
+| Green 证据 | `<change-root>/<change-id>/evidence/green-final/` | `./evidence/green-final/` |
+| 规格增量 | `<change-root>/<change-id>/specs/` | `./specs/` |
+| 追溯文档 | `<change-root>/<change-id>/verification.md` | `./verification.md` |
+
+### DevBooks 2.0 默认路径
+
+当使用 DevBooks 2.0 协议时：
+- `<change-root>` = `dev-playbooks/changes`
+- `<truth-root>` = `dev-playbooks/specs`
+
+**示例**：
+```
+项目根目录/
+├── dev-playbooks/                    # DevBooks 根目录
+│   ├── changes/                      # <change-root>
+│   │   └── CHG-001/                  # 变更包目录
+│   │       ├── proposal.md
+│   │       ├── design.md
+│   │       ├── tasks.md
+│   │       ├── verification.md
+│   │       ├── evidence/             # 证据目录
+│   │       │   ├── red-baseline/     # Red 基线
+│   │       │   └── green-final/      # Green 最终
+│   │       └── specs/                # 规格增量
+│   └── specs/                        # <truth-root>
+└── src/                              # 项目代码
+```
+
+### 路径检查协议
+
+**每次写文件前，必须验证**：
+1. 目标路径是否在 `<change-root>/<change-id>/` 下？
+2. 是否意外使用了相对路径（`./`）导致写入项目根目录？
+3. 是否正确解析了 `<change-root>` 的实际值？
+
+**常见错误及修正**：
+```bash
+# ❌ 错误：写入项目根目录
+mkdir -p ./evidence/green-final/
+
+# ✅ 正确：写入变更包目录
+mkdir -p dev-playbooks/changes/CHG-001/evidence/green-final/
+
+# ❌ 错误：相对路径未指定变更包
+tee evidence/test.log
+
+# ✅ 正确：完整路径
+tee dev-playbooks/changes/CHG-001/evidence/green-final/test.log
+```
+
+### 违反路径约定的后果
+
+如果产出物被写入错误位置：
+1. 归档检查会失败（`check_evidence_closure` 找不到证据）
+2. 追溯矩阵会断裂
+3. 变更包不完整，无法通过 strict 模式检查
+
+**发现路径错误时的处理**：
+1. 立即将文件移动到正确位置
+2. 检查同类产出物是否有相同问题
+3. 更新相关引用路径
+
+---
+
 ## 1. 可验证性守门协议（Radical Honesty）
 
 你是"可验证性守门人"。你的职责是把所有输出都锚定到可证据化的事实，避免幻觉、臆测与"自证闭环"。

package/skills/devbooks-code-review/references//344/273/243/347/240/201/350/257/204/345/256/241/346/217/220/347/244/272/350/257/215.md

@@ -103,3 +103,76 @@
    - ⚠️ **APPROVED WITH COMMENTS**：可合并但建议后续改进（列出具体项）
    - 🔄 **REQUEST CHANGES**：需修改后重新评审（列出必须修复项）
    - ❌ **REJECTED**：存在严重问题或设计缺陷，需回到设计阶段
+
+---
+
+## 产出物完整性检查协议（Deliverable Completeness Check）
+
+> **核心原则**：Reviewer 不仅审查代码质量，还需验证 Coder 任务的完整交付。
+
+**在给出 APPROVED 结论前，必须完成以下检查**：
+
+### 1. 任务计划完成度验证
+```bash
+# 检查 tasks.md 完成度
+rg "^- \[ \]" <change-root>/<change-id>/tasks.md
+```
+
+**验证标准**：
+- [ ] tasks.md 中所有任务项已完成（`- [x]`）或有 SKIP-APPROVED 批准
+- [ ] 无遗漏的主线计划项
+
+### 2. 测试通过状态验证
+```bash
+# 验证测试是否全部通过（非 skip）
+npm test 2>&1 | rg -i "pass|fail|skip"
+```
+
+**验证标准**：
+- [ ] 测试全部 PASS（不是 SKIP）
+- [ ] 无 `.only()` 或 `.skip()` 残留
+- [ ] Skip 数量为 0 或有明确说明
+
+### 3. Green 证据验证
+```bash
+# 验证 Green 证据目录存在且有内容
+ls -la <change-root>/<change-id>/evidence/green-final/
+```
+
+**验证标准**：
+- [ ] `evidence/green-final/` 目录存在
+- [ ] 目录中有测试日志文件
+- [ ] 日志中无 FAIL/FAILED/ERROR 模式
+
+### 4. 产出物检查清单
+
+在评审输出中，必须包含以下验证表格：
+
+```markdown
+## 产出物完整性检查
+
+| 检查项 | 状态 | 说明 |
+|--------|------|------|
+| tasks.md 完成度 | ✅/❌ | X/Y 已完成 |
+| 测试全绿（非 Skip） | ✅/❌ | X 通过 / Y 跳过 / Z 失败 |
+| Green 证据存在 | ✅/❌ | evidence/green-final/ 有 N 个文件 |
+| 无失败模式在证据中 | ✅/❌ | 日志无 FAIL/ERROR |
+```
+
+### 5. 评审结论强化
+
+**APPROVED 的前提条件**（全部满足才能给出 APPROVED）：
+1. 代码质量审查通过（原有逻辑）
+2. tasks.md 100% 完成或有 SKIP-APPROVED
+3. 测试全部 PASS（skip 数量为 0）
+4. Green 证据目录存在且无失败模式
+
+**如果以上任一条件不满足**：
+- 必须给出 🔄 **REQUEST CHANGES** 或 ❌ **REJECTED**
+- 明确指出缺失项及修复建议
+
+**禁止行为**：
+- 禁止在任务未完成时给出 APPROVED
+- 禁止在有 skip 测试时给出 APPROVED
+- 禁止在无 Green 证据时给出 APPROVED
+- 禁止仅审查代码质量而忽略产出物完整性

package/skills/devbooks-coder/SKILL.md

@@ -52,6 +52,48 @@ tools:
 
 ---
 
+## 实时进度更新协议（Real-time Progress Update）
+
+> **核心原则**：完成一个任务，立即勾选一个。不要等到全部完成再批量勾选。
+
+**必须遵守**：
+
+### 单任务完成后立即勾选
+
+每完成 tasks.md 中的一个任务项后，**立即**将其从 `- [ ]` 改为 `- [x]`：
+
+```markdown
+# 任务完成前
+- [ ] MP1.1 实现缓存管理器基础结构
+
+# 任务完成后，立即更新
+- [x] MP1.1 实现缓存管理器基础结构
+```
+
+### 为什么必须实时勾选
+
+1. **断点恢复**：中断后可以准确知道从哪里继续
+2. **进度可视**：用户和 AI 都能清楚看到当前进度
+3. **避免遗忘**：批量勾选容易遗漏已完成项
+4. **证据链完整**：每个勾选代表一个完成的里程碑
+
+### 勾选时机
+
+| 时机 | 操作 |
+|------|------|
+| 代码编写完成 | 暂不勾选 |
+| 编译通过 | 暂不勾选 |
+| 相关测试通过 | **立即勾选** |
+| 多个任务一起完成 | 逐个勾选，不要批量 |
+
+### 禁止行为
+
+- ❌ 禁止等所有任务完成后再批量勾选
+- ❌ 禁止"代码写完就算完成"而不勾选
+- ❌ 禁止勾选后又改回未勾选状态（除非回滚代码）
+
+---
+
 ## 输出管理约束（Observation Masking）
 
 防止大量输出污染 context：
@@ -60,18 +102,40 @@ tools:
 |------|----------|
 | 命令输出 > 50 行 | 只保留首尾各 10 行 + 中间摘要 |
 | 测试输出 | 提取关键失败信息，不要全量贴入对话 |
-| 日志输出 | 落盘到 `evidence/`，对话中只引用路径 |
+| 日志输出 | 落盘到 `<change-root>/<change-id>/evidence/`，对话中只引用路径 |
 | 大文件内容 | 引用路径，不要内联 |
 
 **示例**：
 ```
 ❌ 错误：贴入 2000 行测试日志
-✅ 正确：测试失败 3 个，详见 evidence/test-output.log
+✅ 正确：测试失败 3 个，详见 <change-root>/<change-id>/evidence/green-final/test-output.log
         关键错误：FAIL src/order.test.ts:45 - Expected 400, got 500
 ```
 
 ---
 
+## 证据路径强制约定
+
+**Green 证据必须保存到变更包目录**：
+```
+<change-root>/<change-id>/evidence/green-final/
+```
+
+**禁止的路径**：
+- ❌ `./evidence/`（项目根目录）
+- ❌ `evidence/`（相对于当前工作目录）
+
+**正确的路径示例**：
+```bash
+# DevBooks 2.0 默认路径
+dev-playbooks/changes/<change-id>/evidence/green-final/test-$(date +%Y%m%d-%H%M%S).log
+
+# 使用脚本
+devbooks change-evidence <change-id> --label green-final -- npm test
+```
+
+---
+
 ## 关键约束
 
 ### 角色边界约束

package/skills/devbooks-coder/references//344/273/243/347/240/201/345/256/236/347/216/260/346/217/220/347/244/272/350/257/215.md

@@ -18,8 +18,64 @@
 1) **禁止修改 tests/**；如需调整测试只能交还 Test Owner。
 2) **只读设计/规格**：不得用代码实现去反向改写 design/spec 的语义。
 3) **质量优先**：遵循仓库既有风格与最佳实践；避免引入反模式与坏味道。
-4) **确定性锚点**：以测试/静态检查/构建结果为唯一裁判；禁止“自评通过”。
-5) **结构守门**：若出现“代理指标驱动”的要求，先评估对内聚/耦合/可测试性的影响；触发风险信号必须停线并回到设计决策。
+4) **确定性锚点**：以测试/静态检查/构建结果为唯一裁判；禁止"自评通过"。
+5) **结构守门**：若出现"代理指标驱动"的要求，先评估对内聚/耦合/可测试性的影响；触发风险信号必须停线并回到设计决策。
+6) **实时勾选**：完成一个任务项，立即在 tasks.md 中勾选（`- [ ]` → `- [x]`）；禁止批量勾选。
+
+---
+
+## 实时进度更新协议（Real-time Progress Update）
+
+> **最高优先级约束**：这是防止进度丢失的关键机制。
+
+### 核心原则
+
+**完成一个任务，立即勾选一个。不要等到全部完成再批量勾选。**
+
+### 执行流程
+
+```
+开始任务 MP1.1
+    ↓
+编写代码
+    ↓
+运行相关测试，确认通过
+    ↓
+【立即】更新 tasks.md：- [ ] MP1.1 → - [x] MP1.1
+    ↓
+开始下一个任务 MP1.2
+```
+
+### 勾选命令示例
+
+```bash
+# 使用 Edit 工具更新任务状态
+# old_string: "- [ ] MP1.1 实现缓存管理器"
+# new_string: "- [x] MP1.1 实现缓存管理器"
+```
+
+### 禁止的模式
+
+```
+❌ 错误模式：
+完成 MP1.1 → 不勾选，继续 MP1.2
+完成 MP1.2 → 不勾选，继续 MP1.3
+...
+全部完成 → 批量勾选所有任务
+
+✅ 正确模式：
+完成 MP1.1 → 立即勾选 MP1.1
+完成 MP1.2 → 立即勾选 MP1.2
+完成 MP1.3 → 立即勾选 MP1.3
+```
+
+### 为什么这很重要
+
+1. **会话中断**：如果中途中断，未勾选的任务会导致下次不知道从哪继续
+2. **进度丢失**：批量勾选时容易遗漏，造成进度统计不准确
+3. **断点恢复**：实时勾选是断点续做协议的基础
+
+---
 
 质量门禁（必须执行）：
 - 先运行与本次变更相关的 tests/静态检查；保留失败输出作为修复依据。
@@ -68,3 +124,78 @@
 2) 说明每个 Plan 项如何通过对应的锚点（测试/检查）
 3) 提供可运行的验证命令（按分层列出）
 4) 如果发现设计/规格/计划冲突：停止并明确冲突点，提出回写或澄清建议
+
+---
+
+## 完成度验证协议（Completion Verification Protocol）
+
+> **核心原则**：Coder 任务完成不仅是"代码能跑"，而是"可归档交付"。
+
+**在声明任务完成前，必须完成以下检查**：
+
+### 1. 任务计划完成度检查
+```bash
+# 检查 tasks.md 中是否所有任务都已勾选
+rg "^- \[ \]" <change-root>/<change-id>/tasks.md
+# 如果有未完成项，必须先完成或申请 SKIP-APPROVED
+```
+
+**完成标准**：
+- [ ] tasks.md 中所有 `- [ ]` 都已变为 `- [x]`
+- [ ] 或者未完成项有明确的 `<!-- SKIP-APPROVED: 原因 -->` 注释
+
+### 2. 测试全通过检查（非 Skip）
+```bash
+# 运行测试并确认无 skip
+npm test 2>&1 | tee <change-root>/<change-id>/evidence/green-final/test-$(date +%Y%m%d-%H%M%S).log
+
+# 检查是否有 skip（以下任一出现都不算通过）
+rg -i "skip|pending|todo" <test-output> | rg -v "0 skip"
+```
+
+**完成标准**：
+- [ ] 所有测试 PASS（不是 SKIP）
+- [ ] 无 `.only()` 或 `.skip()` 残留
+- [ ] 测试输出已保存到 `evidence/green-final/`
+
+### 3. Green 证据收集
+```bash
+# 使用 change-evidence.sh 收集证据
+devbooks change-evidence <change-id> --label green-final -- npm test
+# 或手动保存到正确路径：
+mkdir -p <change-root>/<change-id>/evidence/green-final/
+```
+
+**完成标准**：
+- [ ] `<change-root>/<change-id>/evidence/green-final/` 目录存在
+- [ ] 目录中至少有一个测试日志文件
+- [ ] 日志中无 FAIL/FAILED/ERROR 模式
+
+### 4. 完成度自检清单
+
+在输出最后，必须包含以下自检表格：
+
+```markdown
+## 完成度检查
+
+| 检查项 | 状态 | 证据 |
+|--------|------|------|
+| tasks.md 100% 完成 | ✅/❌ | X/Y 已完成 |
+| 编译通过 | ✅/❌ | npm run compile 退出码 0 |
+| Lint 通过 | ✅/❌ | npm run lint 退出码 0 |
+| 测试全通过（非 Skip） | ✅/❌ | X 通过 / Y 跳过 / Z 失败 |
+| Green 证据已保存 | ✅/❌ | evidence/green-final/*.log |
+| 无禁止模式 | ✅/❌ | 无 .only/console.log/debugger |
+```
+
+### 5. 结论输出格式
+
+**必须明确给出实现结论**：
+- ✅ **DONE**：所有任务完成，测试全绿，证据已收集，可交付 Reviewer
+- ⚠️ **PARTIAL**：部分完成（列出未完成项及原因），需继续实现
+- ❌ **BLOCKED**：遇到阻塞（列出阻塞原因及建议下一步）
+
+**禁止行为**：
+- 禁止在有未完成任务时声明 DONE
+- 禁止在有 skip 测试时声明 DONE
+- 禁止在无 Green 证据时声明 DONE

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

@@ -32,6 +32,29 @@ tools:
 
 - 测试计划与追溯：`<change-root>/<change-id>/verification.md`
 - 测试代码：按仓库惯例（例如 `tests/**`）
+- Red 基线证据：`<change-root>/<change-id>/evidence/red-baseline/`
+
+---
+
+## 证据路径强制约定
+
+**Red 基线证据必须保存到变更包目录**：
+```
+<change-root>/<change-id>/evidence/red-baseline/
+```
+
+**禁止的路径**：
+- ❌ `./evidence/`（项目根目录）
+- ❌ `evidence/`（相对于当前工作目录）
+
+**正确的路径示例**：
+```bash
+# DevBooks 2.0 默认路径
+dev-playbooks/changes/<change-id>/evidence/red-baseline/test-$(date +%Y%m%d-%H%M%S).log
+
+# 使用脚本
+devbooks change-evidence <change-id> --label red-baseline -- npm test
+```
 
 ---
 

package/skills/devbooks-test-owner/references//346/265/213/350/257/225/344/273/243/347/240/201/346/217/220/347/244/272/350/257/215.md

@@ -125,13 +125,70 @@
   现在开始执行：
   1) 先产出 测试计划指令表（按 A 的要求）
   2) 再直接在仓库中实现测试代码（按 B 的要求）
-  3) 运行测试确认 **Red** 基线，并记录失败证据到 `<change-root>/<change-id>/evidence/`（或同等位置）
+  3) 运行测试确认 **Red** 基线，并记录失败证据到 `<change-root>/<change-id>/evidence/red-baseline/`
   4) 最后输出一段简短摘要：测试覆盖了哪些验收标准、如何运行、哪些被标记为可选/跳过及原因
   5) **明确给出验收结论**：
      - ✅ **PASS**：所有测试已就绪，Red 基线已建立，可交付 Coder 实现
      - ⚠️ **PASS WITH CONDITIONS**：测试已就绪但有待确认项（列出具体条件）
      - ❌ **FAIL**：测试无法完成（列出阻塞原因及建议下一步）
 
+---
+
+## 证据路径强制约定（Evidence Path Convention）
+
+> **核心原则**：所有证据文件必须输出到变更包目录内，禁止输出到项目根目录。
+
+**证据路径模式**（必须遵守）：
+```
+<change-root>/<change-id>/evidence/
+├── red-baseline/           # Red 基线证据（Test Owner 产出）
+│   └── test-YYYYMMDD-HHMMSS.log
+└── green-final/            # Green 最终证据（Coder 产出）
+    └── test-YYYYMMDD-HHMMSS.log
+```
+
+**关键约束**：
+- ❌ 禁止：`./evidence/`（项目根目录）
+- ❌ 禁止：`evidence/`（相对于当前工作目录）
+- ✅ 正确：`<change-root>/<change-id>/evidence/red-baseline/`
+- ✅ 正确：`dev-playbooks/changes/<change-id>/evidence/red-baseline/`
+
+**使用脚本收集证据**：
+```bash
+# 推荐方式：使用 change-evidence.sh
+devbooks change-evidence <change-id> --label red-baseline -- npm test
+
+# 手动方式：确保路径正确
+mkdir -p <change-root>/<change-id>/evidence/red-baseline/
+npm test 2>&1 | tee <change-root>/<change-id>/evidence/red-baseline/test-$(date +%Y%m%d-%H%M%S).log
+```
+
+---
+
+## 完成度检查协议（Test Owner Completion Check）
+
+> **核心原则**：Test Owner 任务完成意味着测试已就绪且 Red 基线已建立。
+
+**在声明 PASS 前，必须完成以下检查**：
+
+### 检查清单
+
+| 检查项 | 状态 | 说明 |
+|--------|------|------|
+| verification.md 已创建 | ✅/❌ | `<change-root>/<change-id>/verification.md` |
+| 追溯矩阵完整 | ✅/❌ | 所有 AC-xxx 都有对应测试 |
+| 测试代码已实现 | ✅/❌ | `tests/` 目录有新增文件 |
+| Red 基线已运行 | ✅/❌ | 测试失败（预期行为） |
+| Red 证据已保存 | ✅/❌ | `evidence/red-baseline/*.log` 存在 |
+
+**禁止行为**：
+- 禁止在无 verification.md 时声明 PASS
+- 禁止在追溯矩阵有 TODO 时声明 PASS
+- 禁止在无 Red 基线证据时声明 PASS
+- 禁止将证据输出到变更包目录之外
+
+---
+
 这是输入材料 和 产物目标路径：
 
 ========================