dev-playbooks-cn 1.2.5 → 1.2.6

package/package.json

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

package/skills/devbooks-code-review/SKILL.md

@@ -10,6 +10,34 @@ allowed-tools:
 
 # DevBooks：代码评审（Reviewer）
 
+## 工作流位置感知（Workflow Position Awareness）
+
+> **核心原则**：Code Review 在 Test Owner 阶段 2 验证之后执行，是归档前的最后一个评审步骤。
+
+### 我在整体工作流中的位置
+
+```
+proposal → design → test-owner(阶段1) → coder → test-owner(阶段2) → [Code Review] → archive
+                                                                          ↓
+                                                              可读性/一致性/依赖审查
+```
+
+### Code Review 的职责边界
+
+| 允许 | 禁止 |
+|------|------|
+| 审查代码可读性/一致性 | ❌ 修改代码文件 |
+| 设置 verification.md Status = Done | ❌ 讨论业务正确性（那是 Test Owner 的事） |
+| 提出改进建议 | ❌ 勾选 AC 覆盖矩阵（那是 Test Owner 的事） |
+
+### 前置条件
+
+- [ ] Test Owner 阶段 2 已完成（AC 矩阵已打勾）
+- [ ] 测试全绿
+- [ ] evidence/green-final/ 存在
+
+---
+
 ## 前置：配置发现（协议无关）
 
 - `<truth-root>`：当前真理目录根

package/skills/devbooks-coder/SKILL.md

@@ -12,6 +12,40 @@ allowed-tools:
 
 # DevBooks：实现负责人（Coder）
 
+## 工作流位置感知（Workflow Position Awareness）
+
+> **核心原则**：Coder 在 Test Owner 阶段 1 之后执行，完成后交给 Test Owner 阶段 2 验证。
+
+### 我在整体工作流中的位置
+
+```
+proposal → design → test-owner(阶段1) → [Coder] → test-owner(阶段2) → code-review → archive
+                                            ↓
+                                    实现代码、让测试变绿
+```
+
+### Coder 的职责边界
+
+| 允许 | 禁止 |
+|------|------|
+| 修改 `src/**` 代码 | ❌ 修改 `tests/**` |
+| 勾选 `tasks.md` 任务项 | ❌ 修改 `verification.md` |
+| 记录偏离到 `deviation-log.md` | ❌ 勾选 AC 覆盖矩阵 |
+| 运行测试验证 | ❌ 设置 verification.md Status |
+
+### Coder 完成后的流程
+
+1. **任务完成**：tasks.md 全部 `[x]`
+2. **测试全绿**：运行 `npm test` 确认通过
+3. **交付 Test Owner**：通知 Test Owner 进入阶段 2 验证
+4. **等待验证结果**：
+   - Test Owner 确认全绿 → 进入 Code Review
+   - Test Owner 发现问题 → Coder 修复
+
+**关键提醒**：Coder 完成后，**不是直接进入 Code Review**，而是先让 Test Owner 验证并打勾。
+
+---
+
 ## 前置：配置发现（协议无关）
 
 - `<truth-root>`：当前真理目录根
@@ -334,8 +368,8 @@ fi
 
 | 我的状态 | 下一步 | 原因 |
 |----------|--------|------|
-| COMPLETED | `devbooks-code-review` | 评审可读性/一致性 |
-| COMPLETED_WITH_DEVIATION | `devbooks-design-backport` | 先回写设计，再评审 |
+| COMPLETED | `devbooks-test-owner`（阶段 2 验证） | 任务完成，需要 Test Owner 验证并打勾 |
+| COMPLETED_WITH_DEVIATION | `devbooks-design-backport` | 先回写设计，再让 Test Owner 验证 |
 | HANDOFF (测试问题) | `devbooks-test-owner` | Coder 不能修改测试 |
 | BLOCKED | 等待用户 | 记录断点区 |
 | FAILED | 修复后重试 | 分析失败原因 |
@@ -344,6 +378,7 @@ fi
 - Coder **永远不能修改** `tests/**`
 - 如发现测试问题，必须 HANDOFF 给 Test Owner（单独会话）
 - 如有偏离，必须先 design-backport 再继续
+- **Coder 完成后必须先经过 Test Owner 阶段 2 验证，再进入 Code Review**
 
 ---
 

package/skills/devbooks-design-backport/SKILL.md

@@ -11,6 +11,40 @@ allowed-tools:
 
 # DevBooks：回写设计文档（Design Backport）
 
+## 工作流位置感知（Workflow Position Awareness）
+
+> **核心原则**：Design Backport 现在**主要由 Spec Gardener 在归档阶段自动调用**，用户通常不需要手动调用。
+
+### 我在整体工作流中的位置
+
+```
+proposal → design → test-owner → coder → test-owner(验证) → code-review → [Archive/Spec Gardener]
+                                    ↓                                              ↓
+                             记录偏离到 deviation-log.md               自动调用 design-backport
+```
+
+### 设计决策：自动回写
+
+**旧流程**（需手动判断）：
+```
+coder 有偏离 → 用户手动调用 design-backport → 再归档
+```
+
+**新流程**（自动处理）：
+```
+coder 有偏离 → 归档时 spec-gardener 自动检测并回写 → 归档
+```
+
+### 何时仍需手动调用
+
+| 场景 | 是否需要手动调用 |
+|------|------------------|
+| 正常流程（偏离记录在 deviation-log.md） | ❌ 归档时自动处理 |
+| 需要立即回写（不等归档） | ✅ 手动调用 |
+| 设计与实现严重冲突需要决策 | ✅ 手动调用并讨论 |
+
+---
+
 ## 前置：配置发现（协议无关）
 
 - `<truth-root>`：当前真理目录根

package/skills/devbooks-design-doc/SKILL.md

@@ -11,6 +11,28 @@ allowed-tools:
 
 # DevBooks：设计文档（Design Doc）
 
+## 工作流位置感知（Workflow Position Awareness）
+
+> **核心原则**：Design Doc 在 Proposal 批准后执行，是实现阶段的起点。
+
+### 我在整体工作流中的位置
+
+```
+proposal → [Design Doc] → spec-contract → implementation-plan → test-owner → coder → ...
+                 ↓
+        定义 What/Constraints/AC
+```
+
+### Design Doc 的产出
+
+- **What**：做什么（不是怎么做）
+- **Constraints**：约束条件
+- **AC-xxx**：验收标准（可测试的）
+
+**关键**：Design Doc 不写实现步骤，那是 implementation-plan 的职责。
+
+---
+
 ## 前置：配置发现（协议无关）
 
 - `<truth-root>`：当前真理目录根

package/skills/devbooks-implementation-plan/SKILL.md

@@ -11,6 +11,42 @@ allowed-tools:
 
 # DevBooks：编码计划（Implementation Plan）
 
+## 工作流位置感知（Workflow Position Awareness）
+
+> **核心原则**：Implementation Plan 在 Design Doc 之后执行，为 Test Owner 和 Coder 提供任务清单。
+
+### 我在整体工作流中的位置
+
+```
+proposal → design → [Implementation Plan] → test-owner(阶段1) → coder → ...
+                            ↓
+                    tasks.md（任务清单）
+```
+
+### Implementation Plan 的职责
+
+| 允许 | 禁止 |
+|------|------|
+| 从 design.md 推导任务 | ❌ 参考 tests/（避免实现偏见） |
+| 绑定验收锚点 (AC-xxx) | ❌ 写实现代码 |
+| 拆分并行任务 | ❌ 执行任务 |
+
+### 产出：tasks.md 结构
+
+```markdown
+## 主线计划区
+- [ ] MP1.1 任务描述 (AC-001)
+- [ ] MP1.2 任务描述 (AC-002)
+
+## 临时计划区
+（紧急任务）
+
+## 断点区
+（中断续做信息）
+```
+
+---
+
 ## 前置：配置发现（协议无关）
 
 - `<truth-root>`：当前真理目录根

package/skills/devbooks-spec-gardener/SKILL.md

@@ -11,6 +11,36 @@ allowed-tools:
 
 # DevBooks：规格园丁（Spec Gardener）
 
+## 工作流位置感知（Workflow Position Awareness）
+
+> **核心原则**：Spec Gardener 是归档阶段的终点，负责将变更包产物合并到真理，**并自动处理任何未完成的回写**。
+
+### 我在整体工作流中的位置
+
+```
+proposal → design → test-owner → coder → test-owner(验证) → code-review → [Spec Gardener/Archive]
+                                                                                    ↓
+                                                               自动回写 + 合并到真理 + 归档
+```
+
+### Spec Gardener 的职责
+
+1. **自动回写检测**：检查 deviation-log.md 是否有未回写记录
+2. **自动执行回写**：如有未回写记录，自动执行设计回写
+3. **合并到真理**：将 specs/contracts/architecture 合并到 truth-root
+4. **归档变更包**：设置 verification.md Status = Archived
+
+### 为什么在归档阶段自动回写？
+
+**设计决策**：用户只需线性调用 skills，不需要判断是否需要回写。
+
+| 场景 | 旧设计（需手动判断） | 新设计（自动处理） |
+|------|---------------------|-------------------|
+| Coder 有偏离 | 用户需调用 design-backport → 再归档 | Spec Gardener 自动检测并回写 |
+| Coder 无偏离 | 直接归档 | 直接归档 |
+
+---
+
 ## 前置：配置发现（协议无关）
 
 - `<truth-root>`：当前真理目录根
@@ -31,6 +61,51 @@ allowed-tools:
 
 ## 核心职责
 
+### 0. 自动回写检测与处理（归档前必做）
+
+> **设计决策**：归档阶段自动处理所有未回写的偏离，用户无需手动调用 design-backport。
+
+**检测流程**：
+
+```
+1. 读取 <change-root>/<change-id>/deviation-log.md
+2. 检查是否有 "| ❌" 未回写记录
+   → 有：执行自动回写（步骤 3-5）
+   → 无：跳过，直接进入合并阶段
+
+3. 对每条未回写记录，判断是否为 Design-level 内容：
+   - DESIGN_GAP, CONSTRAINT_CHANGE, API_CHANGE → 需要回写
+   - 纯实现细节（文件名/类名/临时步骤） → 不回写，标记为 IMPL_ONLY
+
+4. 执行设计回写：
+   - 读取 design.md
+   - 按 design-backport 协议的"可回写内容范围"更新
+   - 在 design.md 末尾添加变更记录
+
+5. 更新 deviation-log.md：
+   - 将已回写的记录标记为 ✅
+   - 记录回写时间和归档批次
+```
+
+**自动回写的内容范围**（继承自 design-backport）：
+
+| 可回写 | 不可回写 |
+|--------|----------|
+| 对外语义/用户可感知行为 | 具体文件路径、类名/函数名 |
+| 系统级不可变约束（Invariants） | PR 切分、任务执行顺序 |
+| 核心数据契约与演进策略 | 过细的算法伪代码 |
+| 跨阶段治理策略 | 脚本命令 |
+| 关键取舍与决策 | 表名/字段名 |
+
+**deviation-log.md 更新格式**：
+
+```markdown
+| 时间 | 类型 | 描述 | 涉及文件 | 已回写 | 回写批次 |
+|------|------|------|----------|:------:|----------|
+| 2024-01-15 10:30 | DESIGN_GAP | 并发场景 | tests/... | ✅ | archive-2024-01-16 |
+| 2024-01-15 11:00 | IMPL_ONLY | 重命名变量 | src/... | ⏭️ | (跳过) |
+```
+
 ### 1. 规格合并与维护
 
 在归档阶段，将变更包中的规格产物合并到 `<truth-root>`：
@@ -106,10 +181,34 @@ allowed-tools:
 
 | 模式 | 触发条件 | 行为 |
 |------|----------|------|
-| **归档模式** | 提供 change-id 且闸门通过 | 将变更包产物合并到 truth-root |
+| **归档模式** | 提供 change-id 且闸门通过 | **自动回写** → 合并到 truth-root → 设置 Status=Archived |
 | **维护模式** | 无 change-id | 执行去重、清理、整理操作 |
 | **检查模式** | 带 --dry-run 参数 | 只输出建议，不实际修改 |
 
+### 归档模式完整流程
+
+```
+1. 前置检查：
+   - [ ] 变更包存在
+   - [ ] verification.md Status = Ready 或 Done
+   - [ ] evidence/green-final/ 存在
+   - [ ] tasks.md 全部 [x]
+
+2. 自动回写（如有需要）：
+   - [ ] 检测 deviation-log.md
+   - [ ] 回写 design.md
+   - [ ] 更新 deviation-log.md 标记
+
+3. 合并到真理：
+   - [ ] 合并 specs/**
+   - [ ] 合并 contracts/**
+   - [ ] 合并 Architecture Impact 到 c4.md
+
+4. 归档：
+   - [ ] 设置 verification.md Status = Archived
+   - [ ] 输出归档报告
+```
+
 ### 检测输出示例
 
 ```

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

@@ -12,6 +12,46 @@ allowed-tools:
 
 # DevBooks：测试负责人（Test Owner）
 
+## 工作流位置感知（Workflow Position Awareness）
+
+> **核心原则**：Test Owner 在整体工作流中承担**双阶段职责**，确保与 Coder 的角色隔离。
+
+### 我在整体工作流中的位置
+
+```
+proposal → design → [Test Owner 阶段1] → coder → [Test Owner 阶段2] → code-review → archive
+                         ↓                           ↓
+                    Red 基线产出              Green 验证 + 打勾
+```
+
+### Test Owner 的双阶段职责
+
+| 阶段 | 触发时机 | 核心职责 | 产出 |
+|------|----------|----------|------|
+| **阶段 1：Red 基线** | design.md 完成后 | 编写测试、产出失败证据 | verification.md (Status=Ready)、Red 基线 |
+| **阶段 2：Green 验证** | Coder 完成后 | 验证测试通过、勾选 AC 覆盖矩阵 | AC 矩阵打勾、Status 保持 Ready（等 Reviewer 设 Done） |
+
+### 阶段 2 详细职责（关键！）
+
+当用户说"Coder 完成了，请验证"或类似请求时，Test Owner 进入**阶段 2**：
+
+1. **运行全部测试**：执行 `npm test` 或项目测试命令
+2. **验证 Green 状态**：确认所有测试通过
+3. **勾选 AC 覆盖矩阵**：在 verification.md 的 AC 覆盖矩阵中将 `[ ]` 改为 `[x]`
+4. **收集 Green 证据**：保存到 `evidence/green-final/`
+5. **输出验证报告**：总结测试结果和覆盖情况
+
+### AC 覆盖矩阵复选框权限（重要！）
+
+| 复选框位置 | 谁可以勾选 | 勾选时机 |
+|------------|-----------|----------|
+| AC 覆盖矩阵中的 `[ ]` | **Test Owner** | 阶段 2 验证 Green 状态后 |
+| Status 字段 `Done` | Reviewer | Code Review 通过后 |
+
+**禁止**：Coder 不能勾选 AC 覆盖矩阵，不能修改 verification.md。
+
+---
+
 ## 前置：配置发现（协议无关）
 
 - `<truth-root>`：当前真理目录根
@@ -339,28 +379,53 @@ devbooks change-evidence <change-id> --label red-baseline -- npm test
 
 ## 完成状态与下一步路由
 
-### 完成状态分类（MECE）
+### 阶段感知（关键！）
+
+Test Owner 有两个阶段，完成状态因阶段而异：
+
+| 当前阶段 | 如何判断 | 完成后下一步 |
+|----------|----------|--------------|
+| **阶段 1** | verification.md 不存在或 Red 基线未产出 | → Coder |
+| **阶段 2** | 用户说"验证/打勾"且 Coder 已完成 | → Code Review |
+
+### 阶段 1 完成状态分类（MECE）
 
 | 状态码 | 状态 | 判定条件 | 下一步 |
 |:------:|------|----------|--------|
-| ✅ | COMPLETED | Red 基线产出，无偏离 | `devbooks-coder`（单独会话） |
-| ⚠️ | COMPLETED_WITH_DEVIATION | Red 基线产出，deviation-log 有未回写记录 | `devbooks-design-backport` |
+| ✅ | PHASE1_COMPLETED | Red 基线产出，无偏离 | `devbooks-coder`（单独会话） |
+| ⚠️ | PHASE1_COMPLETED_WITH_DEVIATION | Red 基线产出，deviation-log 有未回写记录 | `devbooks-design-backport` |
 | ❌ | BLOCKED | 需要外部输入/决策 | 记录断点，等待用户 |
 | 💥 | FAILED | 测试框架问题等 | 修复后重试 |
 
-### 状态判定流程
+### 阶段 2 完成状态分类（MECE）
 
-```
-1. 检查 deviation-log.md 是否有 "| ❌" 记录
-   → 有：COMPLETED_WITH_DEVIATION
+| 状态码 | 状态 | 判定条件 | 下一步 |
+|:------:|------|----------|--------|
+| ✅ | PHASE2_VERIFIED | 测试全绿，AC 矩阵已打勾 | `devbooks-code-review` |
+| ❌ | PHASE2_FAILED | 测试未通过 | 通知 Coder 修复，或 HANDOFF |
+| 🔄 | PHASE2_HANDOFF | 发现测试本身有问题 | 修复测试后重新验证 |
 
-2. 检查 Red 基线是否产出
-   - verification.md 存在且有追溯矩阵
-   - evidence/red-baseline/ 存在
-   → 否：BLOCKED 或 FAILED
+### 阶段判定流程
 
-3. 以上都通过
-   → COMPLETED
+```
+1. 检查当前处于哪个阶段：
+   - verification.md 不存在 → 阶段 1
+   - verification.md 存在但 AC 矩阵全是 [ ] → 阶段 1 或 阶段 2（看用户请求）
+   - 用户明确说"验证/打勾/Coder 完成了" → 阶段 2
+
+2. 阶段 1 状态判定：
+   a. 检查 deviation-log.md 是否有 "| ❌" 记录
+      → 有：PHASE1_COMPLETED_WITH_DEVIATION
+   b. 检查 Red 基线是否产出
+      → 否：BLOCKED 或 FAILED
+   c. 以上都通过 → PHASE1_COMPLETED
+
+3. 阶段 2 状态判定：
+   a. 运行测试，检查是否全绿
+      → 否：PHASE2_FAILED
+   b. 检查测试本身是否有问题
+      → 是：PHASE2_HANDOFF
+   c. 全绿且无问题 → PHASE2_VERIFIED
 ```
 
 ### 路由输出模板（必须使用）
@@ -370,15 +435,21 @@ devbooks change-evidence <change-id> --label red-baseline -- npm test
 ```markdown
 ## 完成状态
 
-**状态**：✅ COMPLETED / ⚠️ COMPLETED_WITH_DEVIATION / ❌ BLOCKED / 💥 FAILED
+**阶段**：阶段 1（Red 基线）/ 阶段 2（Green 验证）
+
+**状态**：✅ PHASE1_COMPLETED / ✅ PHASE2_VERIFIED / ⚠️ ... / ❌ ... / 💥 ...
+
+**Red 基线**：已产出 / 未完成（仅阶段 1）
+
+**Green 验证**：全绿 / 有失败（仅阶段 2）
 
-**Red 基线**：已产出 / 未完成
+**AC 矩阵**：已打勾 N/M / 未打勾（仅阶段 2）
 
 **偏离记录**：有 N 条待回写 / 无
 
 ## 下一步
 
-**推荐**：`devbooks-xxx skill`（单独会话）
+**推荐**：`devbooks-xxx skill`
 
 **原因**：[具体原因]
 
@@ -390,8 +461,11 @@ devbooks change-evidence <change-id> --label red-baseline -- npm test
 
 | 我的状态 | 下一步 | 原因 |
 |----------|--------|------|
-| COMPLETED | `devbooks-coder`（单独会话） | Red 基线已产出，Coder 实现以变绿 |
-| COMPLETED_WITH_DEVIATION | `devbooks-design-backport` | 先回写设计，再交给 Coder |
+| PHASE1_COMPLETED | `devbooks-coder`（单独会话） | Red 基线已产出，Coder 实现以变绿 |
+| PHASE1_COMPLETED_WITH_DEVIATION | `devbooks-design-backport` | 先回写设计，再交给 Coder |
+| PHASE2_VERIFIED | `devbooks-code-review` | 测试全绿，可以进入代码评审 |
+| PHASE2_FAILED | 通知 Coder | 测试未通过，需要 Coder 修复 |
+| PHASE2_HANDOFF | 修复测试 | 测试本身有问题，Test Owner 修复 |
 | BLOCKED | 等待用户 | 记录断点区 |
 | FAILED | 修复后重试 | 分析失败原因 |
 
@@ -399,6 +473,7 @@ devbooks change-evidence <change-id> --label red-baseline -- npm test
 - **角色隔离**：Coder 必须在**单独的会话/实例**中工作
 - Test Owner 和 Coder 不能共享同一会话上下文
 - 如有偏离，必须先 design-backport 再交给 Coder
+- **阶段 2 的 AC 矩阵打勾只能由 Test Owner 执行**
 
 ---