npm - dev-playbooks-cn - Versions diffs - 1.2.8 → 1.4.0 - Mend

dev-playbooks-cn 1.2.8 → 1.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (10) hide show

package/package.json CHANGED Viewed

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

package/skills/_shared/references/spec-/347/273/223/346/236/204/346/250/241/346/235/277.md ADDED Viewed

@@ -0,0 +1,161 @@
+# Spec 结构模板
+> 本模板定义了 Spec 真理文件的标准结构，确保 Spec 可被验证、可被追溯、可被测试生成。
+## 文件位置
+```
+<truth-root>/specs/<capability>/spec.md
+```
+## 标准结构
+```markdown
+---
+# 元信息（必填）
+capability: <能力名称>
+owner: @<负责人>
+last_verified: YYYY-MM-DD
+last_referenced_by: <最后引用的 change-id>
+health: active | stale | deprecated
+freshness_check: monthly | quarterly | on-change
+---
+# <Capability 名称> 规格
+## Glossary（术语表）
+> 本能力专属术语，与 `<truth-root>/_meta/glossary.md` 保持一致。
+| 术语 | 定义 | 约束 |
+|------|------|------|
+| Order | 订单实体 | 必须有至少一个 OrderItem |
+| OrderItem | 订单项 | qty > 0, price >= 0 |
+## Invariants（不变量）
+> 必须始终成立的约束，违反即为系统 Bug。
+| ID | 描述 | 验证方式 |
+|----|------|----------|
+| INV-001 | 订单总额 = SUM(item.price * item.qty) | A（自动测试） |
+| INV-002 | 库存数量 >= 0 | A（自动测试） |
+| INV-003 | 已发货订单不可取消 | A（状态机测试） |
+## Contracts（契约）
+### Preconditions（前置条件）
+| ID | 操作 | 条件 | 违反时行为 |
+|----|------|------|-----------|
+| PRE-001 | 创建订单 | user.isAuthenticated | 返回 401 |
+| PRE-002 | 支付订单 | order.status == 'pending' | 返回 400 |
+### Postconditions（后置条件）
+| ID | 操作 | 保证 |
+|----|------|------|
+| POST-001 | 创建订单成功 | 生成唯一 order.id |
+| POST-002 | 支付成功 | inventory.decreased(qty) |
+## State Machine（状态机）
+> 如果本能力涉及状态流转，必须定义状态机。
+### 状态集
+```
+States: {Created, Paid, Shipped, Done, Cancelled}
+```
+### 转换规则
+| 当前状态 | 动作 | 目标状态 | 条件 |
+|----------|------|----------|------|
+| Created | pay | Paid | payment.success |
+| Created | cancel | Cancelled | - |
+| Paid | ship | Shipped | inventory.reserved |
+| Paid | refund | Cancelled | - |
+| Shipped | deliver | Done | - |
+### 禁止转换
+| 当前状态 | 动作 | 原因 |
+|----------|------|------|
+| Shipped | cancel | 违反 INV-003 |
+| Done | * | 终态，不可转出 |
+| Cancelled | * | 终态，不可转出 |
+## Requirements（需求）
+### REQ-001: <需求标题>
+**描述**：<一句话描述>
+**SHALL/SHOULD/MAY**：
+- 系统 **SHALL** ...
+- 系统 **SHOULD** ...
+**Trace**：AC-001（来自 design.md）
+#### Scenario: <场景名>
+- **GIVEN** 用户已登录且购物车非空
+- **WHEN** 用户点击"提交订单"
+- **THEN** 系统创建订单并返回订单 ID
+**数据实例**（边界条件）：
+| 输入 | 预期输出 | 说明 |
+|------|----------|------|
+| qty=1, price=100 | total=100 | 正常值 |
+| qty=0 | 拒绝 | 边界-零值 |
+| qty=-1 | 拒绝 | 边界-负值 |
+---
+## 变更历史
+| 日期 | 变更包 | 变更内容 |
+|------|--------|----------|
+| 2024-01-16 | 20240116-1030-add-cancel | 新增取消订单场景 |
+```
+## 使用指南
+### 1. 谁来写 Spec？
+- **spec-contract skill**：负责创建/更新 spec delta
+- **archiver skill**：负责将 spec delta 合并到 truth-root
+### 2. 谁来读 Spec？
+| Skill | 读取目的 |
+|-------|----------|
+| design-doc | 检查设计是否与现有 Spec 冲突，引用 REQ-xxx |
+| test-owner | 从契约/状态机生成测试 |
+| impact-analysis | 识别受影响的 Spec |
+| code-review | 检查术语一致性 |
+| archiver | 更新元信息，建立引用链 |
+### 3. 测试生成映射
+| Spec 元素 | 生成的测试类型 |
+|-----------|---------------|
+| INV-xxx | 不变量测试 |
+| PRE-xxx | 前置条件测试（满足+违反） |
+| POST-xxx | 后置条件测试 |
+| State Transition | 状态转换测试 |
+| Forbidden Transition | 禁止转换测试 |
+| Data Instance Table | 参数化测试用例 |
+### 4. 健康度检测
+Spec 文件的 `health` 字段由 entropy-monitor 自动检测：
+| 条件 | health 状态 |
+|------|-------------|
+| last_verified < 90 天 | `active` |
+| last_verified > 90 天 | `stale`（需要 review） |
+| 明确标记废弃 | `deprecated` |
+| last_referenced_by 为空超过 6 个月 | 建议删除 |

package/skills/devbooks-archiver/SKILL.md CHANGED Viewed

@@ -120,6 +120,32 @@ proposal → design → test-owner(P1) → coder → test-owner(P2) → code-rev
 | `<change-root>/<change-id>/specs/**` | `<truth-root>/specs/**` | 增量合并 |
 | `<change-root>/<change-id>/contracts/**` | `<truth-root>/contracts/**` | 版本化合并 |
+**Spec 元信息更新**（合并时必须执行）：
+在合并 spec 到 truth-root 时，必须更新以下元信息：
+```yaml
+# 在每个被合并/引用的 spec 文件头部更新
+---
+last_referenced_by: <change-id>           # 最后引用此 spec 的变更包
+last_verified: <归档日期>                  # 最后验证日期
+health: active                            # 健康状态：active | stale | deprecated
+---
+```
+**元信息更新规则**：
+| 场景 | 更新行为 |
+|------|----------|
+| 新增 Spec | 创建完整元信息头 |
+| 修改已有 Spec | 更新 `last_referenced_by` 和 `last_verified` |
+| Spec 被设计文档引用但未修改 | 仅更新 `last_referenced_by` |
+| 标记为废弃 | 设置 `health: deprecated` |
+**建立引用追溯链**：
+归档时，archiver 会自动扫描 design.md 中声明的 "受影响的 Spec"（Affected Specs），并更新这些 Spec 的 `last_referenced_by` 字段，即使它们没有被直接修改。这建立了从 Spec 到变更包的反向追溯链。
 ### 第 4 步：架构合并
 > **设计决策**：C4 架构变更通过 design.md 的 Architecture Impact 章节记录，由 Archiver 在归档时合并到真理。

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 CHANGED Viewed

@@ -13,6 +13,10 @@
 - 统一语言表（如存在）：`<truth-root>/_meta/glossary.md`
 - 高 ROI 坑库（如存在）：`<truth-root>/engineering/pitfalls.md`
+**必须读取的 Spec 真理**（评审前强制检查）：
+- `<truth-root>/specs/**`：现有规格文件
+- 目的：验证代码命名/结构是否与 Spec 中定义的术语和契约一致
 硬约束（必须遵守）：
 1) 只输出审查意见与修改建议；不直接改 tests/ 或设计文档。
 2) 不讨论业务逻辑正确性（由测试/规格裁判）；只讨论可维护性与工程质量。
@@ -64,6 +68,12 @@
 - 是否存在同一概念在不同模块中使用不同命名？（如 User/Account/Member 混用）
 - Entity 与 ValueObject 的区分是否正确？（Entity 有 ID，VO 无 ID 且不可变）
+**Spec 真理术语对照**（必须检查）：
+- 代码中的命名是否与 `<truth-root>/specs/` 中定义的术语一致？
+- 状态名/枚举值是否与 Spec 中的状态机定义一致？
+- 方法名是否反映 Spec 中的动作/转换？（如 `cancel()` 对应 `order --[cancel]--> cancelled`）
+- 若发现命名不一致，标记为"术语漂移风险"并建议统一
 ---
 ## Invariant 保护（必须检查）

package/skills/devbooks-coder/SKILL.md CHANGED Viewed

@@ -14,16 +14,27 @@ allowed-tools:
 ## 工作流位置感知（Workflow Position Awareness）
-> **核心原则**：Coder 在 Test Owner 阶段 1 之后执行，完成后交给 Test Owner 阶段 2 验证。
+> **核心原则**：Coder 在 Test Owner 阶段 1 之后执行，通过**模式标签**（而非会话隔离）实现思维清晰。
 ### 我在整体工作流中的位置
 ```
-proposal → design → test-owner(阶段1) → [Coder] → test-owner(阶段2) → code-review → archive
-                                            ↓
-                                    实现代码、让测试变绿
+proposal → design → [TEST-OWNER] → [CODER] → [TEST-OWNER] → code-review → archive
+                                      ↓              ↓
+                               实现+快轨测试    证据审计+打勾
+                              (@smoke/@critical)  (不重跑@full)
 ```
+### AI 时代个人开发优化
+> **重要变更**：本协议针对 AI 编程 + 个人开发场景优化，**去掉了"单独会话"的硬性要求**。
+| 旧设计 | 新设计 | 原因 |
+|--------|--------|------|
+| Test Owner 和 Coder 必须单独会话 | 同一会话，用 `[TEST-OWNER]` / `[CODER]` 模式标签切换 | 减少上下文重建成本 |
+| Coder 跑完整测试等待结果 | Coder 跑快轨（`@smoke`/`@critical`），`@full` 异步触发 | 快速迭代 |
+| 完成后直接交给 Test Owner | 完成后状态为 `Implementation Done`，等 @full 通过 | 异步不阻塞，归档同步 |
 ### Coder 的职责边界
 | 允许 | 禁止 |
@@ -31,18 +42,60 @@ proposal → design → test-owner(阶段1) → [Coder] → test-owner(阶段2)
 | 修改 `src/**` 代码 | ❌ 修改 `tests/**` |
 | 勾选 `tasks.md` 任务项 | ❌ 修改 `verification.md` |
 | 记录偏离到 `deviation-log.md` | ❌ 勾选 AC 覆盖矩阵 |
-| 运行测试验证 | ❌ 设置 verification.md Status |
+| 运行快轨测试（`@smoke`/`@critical`） | ❌ 设置 verification.md Status 为 Verified/Done |
+| 触发 `@full` 测试（CI/后台） | ❌ 等待 @full 完成（可以开始下一个变更） |
 ### Coder 完成后的流程
-1. **任务完成**：tasks.md 全部 `[x]`
-2. **测试全绿**：运行 `npm test` 确认通过
-3. **交付 Test Owner**：通知 Test Owner 进入阶段 2 验证
-4. **等待验证结果**：
-   - Test Owner 确认全绿 → 进入 Code Review
-   - Test Owner 发现问题 → Coder 修复
+1. **快轨测试绿**：`@smoke` + `@critical` 通过
+2. **触发 @full**：提交代码，CI 开始异步运行 @full 测试
+3. **状态变更**：设置变更状态为 `Implementation Done`
+4. **可以开始下一个变更**（不阻塞）
+5. **等待 @full 结果**：
+   - @full 通过 → Test Owner 进入阶段 2 审计证据
+   - @full 失败 → Coder 修复
+**关键提醒**：
+- Coder 完成后，状态是 `Implementation Done`，**不是直接进入 Code Review**
+- 开发迭代是异步的（可以开始下一个变更），但归档是同步的（必须等 @full 通过）
+---
+## 测试分层与运行策略（关键！）
+> **核心原则**：Coder 只运行快轨测试，@full 测试异步触发，不阻塞开发迭代。
+### 测试分层标签
+| 标签 | 用途 | Coder 何时运行 | 预期耗时 |
+|------|------|----------------|----------|
+| `@smoke` | 快速反馈，核心路径 | 每次代码修改后 | 秒级 |
+| `@critical` | 关键功能验证 | 准备提交前 | 分钟级 |
+| `@full` | 完整验收测试 | **不运行**，触发 CI 异步执行 | 可以慢 |
-**关键提醒**：Coder 完成后，**不是直接进入 Code Review**，而是先让 Test Owner 验证并打勾。
+### Coder 的测试运行策略
+```bash
+# 开发过程中：频繁运行 @smoke
+npm test -- --grep "@smoke"
+# 准备提交前：运行 @critical
+npm test -- --grep "@smoke|@critical"
+# 提交后：CI 自动运行 @full（Coder 不等待）
+git push  # 触发 CI
+# → Coder 可以开始下一个任务
+```
+### 异步与同步的边界
+| 动作 | 阻塞/异步 | 说明 |
+|------|-----------|------|
+| `@smoke` 测试 | 同步 | 每次修改后立即运行 |
+| `@critical` 测试 | 同步 | 提交前必须通过 |
+| `@full` 测试 | **异步** | CI 后台运行，不阻塞 Coder |
+| 开始下一个变更 | **不阻塞** | Coder 可以立即开始 |
+| 归档 | **阻塞** | 必须等 @full 通过 |
 ---
@@ -319,26 +372,29 @@ fi
 | 状态码 | 状态 | 判定条件 | 下一步 |
 |:------:|------|----------|--------|
-| ✅ | COMPLETED | 所有任务完成，无偏离 | `devbooks-code-review` |
-| ⚠️ | COMPLETED_WITH_DEVIATION | 任务完成，deviation-log 有未回写记录 | `devbooks-design-backport` |
-| 🔄 | HANDOFF | 发现测试问题需要修改 | `devbooks-test-owner` |
+| ✅ | IMPLEMENTATION_DONE | 快轨测试绿，@full 已触发，无偏离 | 切换到 `[TEST-OWNER]` 等待 @full |
+| ⚠️ | IMPLEMENTATION_DONE_WITH_DEVIATION | 快轨绿，deviation-log 有未回写记录 | `devbooks-design-backport` |
+| 🔄 | HANDOFF | 发现测试问题需要修改 | 切换到 `[TEST-OWNER]` 模式修复测试 |
 | ❌ | BLOCKED | 需要外部输入/决策 | 记录断点，等待用户 |
-| 💥 | FAILED | 闸门未通过 | 修复后重试 |
+| 💥 | FAILED | 快轨测试未通过 | 修复后重试 |
 ### 状态判定流程
 ```
 1. 检查 deviation-log.md 是否有 "| ❌" 记录
-   → 有：COMPLETED_WITH_DEVIATION
+   → 有：IMPLEMENTATION_DONE_WITH_DEVIATION
 2. 检查是否需要修改 tests/
-   → 是：HANDOFF to test-owner
+   → 是：HANDOFF to [TEST-OWNER] 模式
+3. 检查快轨测试（@smoke + @critical）是否全部通过
+   → 否：FAILED
-3. 检查 tasks.md 是否全部完成
-   → 否：BLOCKED 或 FAILED
+4. 检查 tasks.md 是否全部完成
+   → 否：BLOCKED 或继续实现
-4. 以上都通过
-   → COMPLETED
+5. 以上都通过，触发 @full
+   → IMPLEMENTATION_DONE
 ```
 ### 路由输出模板（必须使用）
@@ -348,37 +404,41 @@ fi
 ```markdown
 ## 完成状态
-**状态**：✅ COMPLETED / ⚠️ COMPLETED_WITH_DEVIATION / 🔄 HANDOFF / ❌ BLOCKED / 💥 FAILED
+**状态**：✅ IMPLEMENTATION_DONE / ⚠️ ... / 🔄 HANDOFF / ❌ BLOCKED / 💥 FAILED
 **任务进度**：X/Y 已完成
+**快轨测试**：@smoke ✅ / @critical ✅
+**@full 测试**：已触发（CI 异步运行中）
 **偏离记录**：有 N 条待回写 / 无
 ## 下一步
-**推荐**：`devbooks-xxx skill`
+**推荐**：切换到 `[TEST-OWNER]` 模式等待 @full / `devbooks-xxx skill`
 **原因**：[具体原因]
-### 如何调用
-运行 devbooks-xxx skill 处理变更 <change-id>
+**注意**：可以开始下一个变更，不需要等待 @full 完成
 ```
 ### 具体路由规则
 | 我的状态 | 下一步 | 原因 |
 |----------|--------|------|
-| COMPLETED | `devbooks-test-owner`（阶段 2 验证） | 任务完成，需要 Test Owner 验证并打勾 |
-| COMPLETED_WITH_DEVIATION | `devbooks-design-backport` | 先回写设计，再让 Test Owner 验证 |
-| HANDOFF (测试问题) | `devbooks-test-owner` | Coder 不能修改测试 |
+| IMPLEMENTATION_DONE | 切换到 `[TEST-OWNER]` 模式（等 @full） | 快轨绿，等 @full 通过后审计证据 |
+| IMPLEMENTATION_DONE_WITH_DEVIATION | `devbooks-design-backport` | 先回写设计 |
+| HANDOFF (测试问题) | 切换到 `[TEST-OWNER]` 模式 | Coder 不能修改测试 |
 | BLOCKED | 等待用户 | 记录断点区 |
 | FAILED | 修复后重试 | 分析失败原因 |
 **关键约束**：
 - Coder **永远不能修改** `tests/**`
-- 如发现测试问题，必须 HANDOFF 给 Test Owner（单独会话）
+- 如发现测试问题，必须切换到 `[TEST-OWNER]` 模式处理
 - 如有偏离，必须先 design-backport 再继续
-- **Coder 完成后必须先经过 Test Owner 阶段 2 验证，再进入 Code Review**
+- **Coder 完成后状态是 `Implementation Done`，必须等 @full 通过后才能进入 Test Owner 阶段 2**
+- **模式切换替代会话隔离**：使用 `[TEST-OWNER]` / `[CODER]` 标签切换模式
 ---

package/skills/devbooks-design-doc/references//350/256/276/350/256/241/346/226/207/346/241/243/346/217/220/347/244/272/350/257/215.md CHANGED Viewed

@@ -18,6 +18,10 @@
 - 聊天记录
 - 统一语言表（如存在）：`<truth-root>/_meta/glossary.md`
+**必须读取的 Spec 真理**（设计前强制检查）：
+- `<truth-root>/specs/**`：现有规格文件（REQ/Invariants/Contracts）
+- 目的：确保本次设计不与现有规格冲突，并显式引用受影响的规格
 任务：
 1) 输出设计文档（不是编码计划、不是代码实现）。
 2) 文档必须达到“可驱动验收、可驱动计划拆解”的颗粒度：清晰边界、契约、红线、验收。
@@ -181,9 +185,15 @@ Acceptance Criteria 写法要求：
 - 不输出实现步骤、PR 切分建议、生产代码具体文件路径与函数体代码
 - 不输出可运行伪代码；如必须描述算法，只写 Inputs/Outputs/Invariants/复杂度上限/降级策略
-补充要求（用于大型项目的“可追溯性”）：
-- 在文档中显式列出本次变更影响的“能力/模块/对外契约”（仅列名称与边界，不写实现）
-- 若涉及对外接口/API/事件/数据结构：必须在“核心数据与事件契约”章节写清楚版本化策略（schema_version、兼容窗口、迁移/回放原则）
-- 若涉及架构边界变化：在“目标架构”章节增加一个 **C4 Delta（可选）** 小节：说明 C1/C2/C3 哪些元素被新增/修改/移除（不要求画完整图；完整图由架构地图维护）
+补充要求（用于大型项目的"可追溯性"）：
+- 在文档中显式列出本次变更影响的"能力/模块/对外契约"（仅列名称与边界，不写实现）
+- 若涉及对外接口/API/事件/数据结构：必须在"核心数据与事件契约"章节写清楚版本化策略（schema_version、兼容窗口、迁移/回放原则）
+- 若涉及架构边界变化：在"目标架构"章节增加一个 **C4 Delta（可选）** 小节：说明 C1/C2/C3 哪些元素被新增/修改/移除（不要求画完整图；完整图由架构地图维护）
+**Spec 真理引用要求**（可追溯性核心）：
+- **必须声明受影响的现有 Spec**：列出本次设计影响的 `<truth-root>/specs/` 下的规格文件
+- **必须引用 REQ/Invariant**：设计中涉及的每个约束必须追溯到 Spec 中的 REQ-xxx 或 INV-xxx
+- **Gap 声明**：如果本次设计无法满足某个现有 REQ，必须显式声明为 Gap 并说明原因
+- **术语一致性**：设计中使用的领域术语必须与 `<truth-root>/_meta/glossary.md` 一致；如需引入新术语，必须在设计文档中声明并建议添加到 glossary
 现在开始输出该《设计文档》Markdown，不要输出额外解释。

package/skills/devbooks-impact-analysis/references//345/275/261/345/223/215/345/210/206/346/236/220/346/217/220/347/244/272/350/257/215.md CHANGED Viewed

@@ -17,6 +17,10 @@
 - 当前真理源：`<truth-root>/`
 - 代码库（只读分析）
+**必须读取的 Spec 真理**（分析前强制检查）：
+- `<truth-root>/specs/**`：现有规格文件
+- 目的：识别本次变更影响哪些现有 Specs（REQ/Invariants/Contracts）
 硬约束（必须遵守）：
 - 先影响分析，后写代码
 - 禁止“装饰性/表层重构”（除非直接降低本次改动风险）
@@ -53,6 +57,19 @@
        - 外部系统/API 变更是否被 ACL 隔离？（外部模型变化不应直接传播到内部模型）
        - 是否存在直接调用外部 API 而未经过适配层的代码？
        - 若新增外部依赖：建议的 ACL 接口定义
+   - **F. 受影响的 Spec 真理**（必须分析）：
+     - 列出本次变更影响的 `<truth-root>/specs/` 下的规格文件
+     - 对每个受影响 Spec，标注影响类型：
+       - `[BREAK]`：破坏现有 REQ/Invariant（需要更新 Spec 或重新设计）
+       - `[EXTEND]`：扩展现有能力（需要新增 REQ/Scenario）
+       - `[DEPRECATE]`：废弃现有能力（需要标记 Spec 为 deprecated）
+     - 输出格式：
+       ```
+       Affected Specs:
+       - [EXTEND] specs/order/spec.md - 新增取消订单场景
+       - [BREAK] specs/payment/spec.md - INV-002 "已支付不可取消" 需要修改
+       - [DEPRECATE] specs/legacy-checkout/spec.md - 整体废弃
+       ```
 4) 兼容性与风险（Compatibility & Risks）
    - Breaking 变化（如有必须显式标注）
    - 迁移/回滚路径

package/skills/devbooks-spec-contract/references//350/247/204/346/240/274/345/217/230/346/233/264/346/217/220/347/244/272/350/257/215.md CHANGED Viewed

@@ -18,6 +18,10 @@
 - 项目画像（如存在，优先遵循其中的格式约定）：`<truth-root>/_meta/project-profile.md`
 - 统一语言表（如存在）：`<truth-root>/_meta/glossary.md`
+**Spec 真理冲突检测**（写入前必须完成）：
+- **必须读取现有 Spec**：在写 spec delta 前，必须读取 `<truth-root>/specs/**` 所有现有规格
+- **目的**：检测新 spec delta 是否与现有 Specs 存在冲突
 硬约束（必须遵守）：
 - 你输出的是 **spec delta**，不是设计文档、不是编码计划、不是代码实现
 - 不写实现细节（类名/函数名/具体文件路径/库调用）
@@ -26,6 +30,13 @@
 - 避免重复能力：先搜索/复用/修改已有 capability spec，必要时才新增 capability
 - 统一语言：若 `<truth-root>/_meta/glossary.md` 存在，必须使用其中的术语；禁止发明新词汇
+**概念完整性守护**（冲突检测规则）：
+- **术语冲突检测**：新 spec 中的术语是否与现有 spec 使用的术语命名不一致？（如 `Order.status` vs `Order.state`）
+- **规则冲突检测**：新 spec 的规则是否与现有 spec 的规则矛盾？（如"已支付可取消" vs "已支付不可取消"）
+- **边界冲突检测**：新 spec 的职责边界是否与现有 spec 重叠？（如两个 spec 都声称拥有 payment 逻辑）
+- **Invariant 兼容检测**：新 spec 是否破坏现有 spec 声明的 Invariants？
+- **冲突报告**：如检测到冲突，必须在 spec delta 开头声明冲突并建议解决方案；冲突未解决前禁止归档
 研讨会（内部步骤，不单独输出）：
 - 在写 spec 前先做“虚拟三剑客研讨会”（业务/开发/测试），把共识与边缘实例融入 Requirement/Scenario；不要单独输出研讨会纪要

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

@@ -14,44 +14,98 @@ allowed-tools:
 ## 工作流位置感知（Workflow Position Awareness）
-> **核心原则**：Test Owner 在整体工作流中承担**双阶段职责**，确保与 Coder 的角色隔离。
+> **核心原则**：Test Owner 在整体工作流中承担**双阶段职责**，通过**模式标签**（而非会话隔离）实现思维清晰。
 ### 我在整体工作流中的位置
 ```
-proposal → design → [Test Owner 阶段1] → coder → [Test Owner 阶段2] → code-review → archive
-                         ↓                           ↓
-                    Red 基线产出              Green 验证 + 打勾
+proposal → design → [TEST-OWNER] → [CODER] → [TEST-OWNER] → code-review → archive
+                         ↓              ↓           ↓
+                    Red 基线      实现+快轨     证据审计+打勾
+                   (增量测试)    (@smoke)     (不重跑@full)
 ```
+### AI 时代个人开发优化
+> **重要变更**：本协议针对 AI 编程 + 个人开发场景优化，**去掉了"单独会话"的硬性要求**。
+| 旧设计 | 新设计 | 原因 |
+|--------|--------|------|
+| Test Owner 和 Coder 必须单独会话 | 同一会话，用 `[TEST-OWNER]` / `[CODER]` 模式标签切换 | 减少上下文重建成本 |
+| 阶段2 重跑完整测试 | 阶段2 默认**审计证据**，可选抽样重跑 | 避免慢测试多次运行 |
+| 测试无分层要求 | 强制测试分层：`@smoke`/`@critical`/`@full` | 快速反馈循环 |
 ### Test Owner 的双阶段职责
-| 阶段 | 触发时机 | 核心职责 | 产出 |
-|------|----------|----------|------|
-| **阶段 1：Red 基线** | design.md 完成后 | 编写测试、产出失败证据 | verification.md (Status=Ready)、Red 基线 |
-| **阶段 2：Green 验证** | Coder 完成后 | 验证测试通过、勾选 AC 覆盖矩阵 | AC 矩阵打勾、Status 保持 Ready（等 Reviewer 设 Done） |
+| 阶段 | 触发时机 | 核心职责 | 测试运行方式 | 产出 |
+|------|----------|----------|--------------|------|
+| **阶段 1：Red 基线** | design.md 完成后 | 编写测试、产出失败证据 | 只跑**增量测试**（新写的/P0） | verification.md (Status=Ready)、Red 基线 |
+| **阶段 2：Green 验证** | Coder 完成 + @full 通过后 | **审计证据**、勾选 AC 覆盖矩阵 | 默认不重跑，可选抽样 | AC 矩阵打勾、Status=Verified |
 ### 阶段 2 详细职责（关键！）
 当用户说"Coder 完成了，请验证"或类似请求时，Test Owner 进入**阶段 2**：
-1. **运行全部测试**：执行 `npm test` 或项目测试命令
-2. **验证 Green 状态**：确认所有测试通过
-3. **勾选 AC 覆盖矩阵**：在 verification.md 的 AC 覆盖矩阵中将 `[ ]` 改为 `[x]`
-4. **收集 Green 证据**：保存到 `evidence/green-final/`
-5. **输出验证报告**：总结测试结果和覆盖情况
+1. **检查前置条件**：确认 @full 测试已通过（查看 CI 结果或 `evidence/green-final/`）
+2. **审计证据**（默认模式）：
+   - 检查 `evidence/green-final/` 目录下的测试日志
+   - 验证 commit hash 与当前代码一致
+   - 确认测试覆盖了所有 AC
+3. **可选抽样重跑**：对高风险 AC 或有疑问的测试进行抽样验证
+4. **勾选 AC 覆盖矩阵**：在 verification.md 的 AC 覆盖矩阵中将 `[ ]` 改为 `[x]`
+5. **设置状态为 Verified**：表示测试验证通过，等待 Code Review
 ### AC 覆盖矩阵复选框权限（重要！）
 | 复选框位置 | 谁可以勾选 | 勾选时机 |
 |------------|-----------|----------|
-| AC 覆盖矩阵中的 `[ ]` | **Test Owner** | 阶段 2 验证 Green 状态后 |
+| AC 覆盖矩阵中的 `[ ]` | **Test Owner** | 阶段 2 审计证据确认后 |
+| Status 字段 `Verified` | **Test Owner** | 阶段 2 完成后 |
 | Status 字段 `Done` | Reviewer | Code Review 通过后 |
 **禁止**：Coder 不能勾选 AC 覆盖矩阵，不能修改 verification.md。
 ---
+## 测试分层与运行策略（关键！）
+> **核心原则**：测试分层是解决"慢测试阻塞开发"问题的关键。
+### 测试分层标签（必须使用）
+| 标签 | 用途 | 谁运行 | 预期耗时 | 何时运行 |
+|------|------|--------|----------|----------|
+| `@smoke` | 快速反馈，核心路径 | Coder 频繁运行 | 秒级 | 每次代码修改后 |
+| `@critical` | 关键功能验证 | Coder 提交前运行 | 分钟级 | 准备提交时 |
+| `@full` | 完整验收测试 | CI 异步运行 | 可以慢（小时级） | 后台/CI |
+### 各阶段测试运行策略
+| 阶段 | 运行什么 | 目的 | 阻塞/异步 |
+|------|----------|------|-----------|
+| **Test Owner 阶段1** | 只跑**新写的测试** | 确认 Red 状态 | 同步（但只是增量） |
+| **Coder 开发中** | `@smoke` | 快速反馈循环 | 同步 |
+| **Coder 提交前** | `@critical` | 关键路径验证 | 同步 |
+| **Coder 完成时** | `@full`（触发 CI） | 完整验收 | **异步**（不阻塞开发） |
+| **Test Owner 阶段2** | **不运行**（审计证据） | 独立验证 | N/A |
+### 异步与同步的边界（关键！）
+```
+✅ 异步的：开发迭代（Coder 完成后可以开始下一个变更，不等 @full）
+❌ 同步的：归档门禁（归档必须等 @full 通过）
+时间线示例：
+T1: Coder 完成实现，触发 @full 异步测试 → 状态 = Implementation Done
+T2: Coder 可以开始下一个变更（不阻塞）
+T3: @full 测试通过 → 状态 = 可进入阶段2
+T4: Test Owner 审计证据 + 打勾 → 状态 = Verified
+T5: Code Review → 状态 = Done
+T6: 归档（此时 @full 一定已通过）
+```
+---
 ## 前置：配置发现（协议无关）
 - `<truth-root>`：当前真理目录根
@@ -86,10 +140,15 @@ Test Owner 必须产出结构化的 `verification.md`，同时作为测试计划
 |------|------|-----------|
 | `Draft` | 初始状态 | 自动生成 |
 | `Ready` | 测试计划就绪 | **Test Owner** |
+| `Implementation Done` | 实现完成，等待 @full 测试 | **Coder** |
+| `Verified` | @full 通过 + 证据审计完成 | **Test Owner** |
 | `Done` | Review 通过 | Reviewer（禁止 Test Owner/Coder） |
-| `Archived` | 已归档 | Spec Gardener |
+| `Archived` | 已归档 | Archiver |
-**约束**：Test Owner 完成测试计划后，应将 Status 设为 `Ready`。
+**关键约束**：
+- `Verified` 状态要求 @full 测试必须已通过
+- 只有 `Verified` 或 `Done` 状态的变更才能归档
+- Test Owner 完成测试计划后设 `Ready`，完成证据审计后设 `Verified`
 ```markdown
 # 验证计划：<change-id>
@@ -385,14 +444,14 @@ Test Owner 有两个阶段，完成状态因阶段而异：
 | 当前阶段 | 如何判断 | 完成后下一步 |
 |----------|----------|--------------|
-| **阶段 1** | verification.md 不存在或 Red 基线未产出 | → Coder |
-| **阶段 2** | 用户说"验证/打勾"且 Coder 已完成 | → Code Review |
+| **阶段 1** | verification.md 不存在或 Red 基线未产出 | → `[CODER]` 模式 |
+| **阶段 2** | 用户说"验证/打勾"且 @full 测试已通过 | → Code Review |
 ### 阶段 1 完成状态分类（MECE）
 | 状态码 | 状态 | 判定条件 | 下一步 |
 |:------:|------|----------|--------|
-| ✅ | PHASE1_COMPLETED | Red 基线产出，无偏离 | `devbooks-coder`（单独会话） |
+| ✅ | PHASE1_COMPLETED | Red 基线产出，无偏离 | 切换到 `[CODER]` 模式 |
 | ⚠️ | PHASE1_COMPLETED_WITH_DEVIATION | Red 基线产出，deviation-log 有未回写记录 | `devbooks-design-backport` |
 | ❌ | BLOCKED | 需要外部输入/决策 | 记录断点，等待用户 |
 | 💥 | FAILED | 测试框架问题等 | 修复后重试 |
@@ -401,8 +460,9 @@ Test Owner 有两个阶段，完成状态因阶段而异：
 | 状态码 | 状态 | 判定条件 | 下一步 |
 |:------:|------|----------|--------|
-| ✅ | PHASE2_VERIFIED | 测试全绿，AC 矩阵已打勾 | `devbooks-code-review` |
-| ❌ | PHASE2_FAILED | 测试未通过 | 通知 Coder 修复，或 HANDOFF |
+| ✅ | PHASE2_VERIFIED | 证据审计通过，AC 矩阵已打勾 | `devbooks-code-review` |
+| ⏳ | PHASE2_WAITING | @full 测试仍在运行 | 等待 CI 完成 |
+| ❌ | PHASE2_FAILED | @full 测试未通过 | 通知 Coder 修复 |
 | 🔄 | PHASE2_HANDOFF | 发现测试本身有问题 | 修复测试后重新验证 |
 ### 阶段判定流程
@@ -421,11 +481,13 @@ Test Owner 有两个阶段，完成状态因阶段而异：
    c. 以上都通过 → PHASE1_COMPLETED
 3. 阶段 2 状态判定：
-   a. 运行测试，检查是否全绿
+   a. 检查 @full 测试是否已完成
+      → 否：PHASE2_WAITING
+   b. 检查 @full 测试是否通过
       → 否：PHASE2_FAILED
-   b. 检查测试本身是否有问题
+   c. 检查测试本身是否有问题
       → 是：PHASE2_HANDOFF
-   c. 全绿且无问题 → PHASE2_VERIFIED
+   d. 审计证据，确认覆盖 → PHASE2_VERIFIED
 ```
 ### 路由输出模板（必须使用）
@@ -437,11 +499,13 @@ Test Owner 有两个阶段，完成状态因阶段而异：
 **阶段**：阶段 1（Red 基线）/ 阶段 2（Green 验证）
-**状态**：✅ PHASE1_COMPLETED / ✅ PHASE2_VERIFIED / ⚠️ ... / ❌ ... / 💥 ...
+**状态**：✅ PHASE1_COMPLETED / ✅ PHASE2_VERIFIED / ⏳ PHASE2_WAITING / ...
 **Red 基线**：已产出 / 未完成（仅阶段 1）
-**Green 验证**：全绿 / 有失败（仅阶段 2）
+**@full 测试**：已通过 / 运行中 / 失败（仅阶段 2）
+**证据审计**：已完成 / 待审计（仅阶段 2）
 **AC 矩阵**：已打勾 N/M / 未打勾（仅阶段 2）
@@ -449,31 +513,29 @@ Test Owner 有两个阶段，完成状态因阶段而异：
 ## 下一步
-**推荐**：`devbooks-xxx skill`
+**推荐**：切换到 `[CODER]` 模式 / `devbooks-xxx skill`
 **原因**：[具体原因]
-### 如何调用
-运行 devbooks-xxx skill 处理变更 <change-id>
 ```
 ### 具体路由规则
 | 我的状态 | 下一步 | 原因 |
 |----------|--------|------|
-| PHASE1_COMPLETED | `devbooks-coder`（单独会话） | Red 基线已产出，Coder 实现以变绿 |
+| PHASE1_COMPLETED | 切换到 `[CODER]` 模式 | Red 基线已产出，Coder 实现以变绿 |
 | PHASE1_COMPLETED_WITH_DEVIATION | `devbooks-design-backport` | 先回写设计，再交给 Coder |
-| PHASE2_VERIFIED | `devbooks-code-review` | 测试全绿，可以进入代码评审 |
-| PHASE2_FAILED | 通知 Coder | 测试未通过，需要 Coder 修复 |
+| PHASE2_VERIFIED | `devbooks-code-review` | 证据审计通过，可以进入代码评审 |
+| PHASE2_WAITING | 等待 CI | @full 测试仍在运行 |
+| PHASE2_FAILED | 通知 Coder 修复 | 测试未通过，需要 Coder 修复 |
 | PHASE2_HANDOFF | 修复测试 | 测试本身有问题，Test Owner 修复 |
 | BLOCKED | 等待用户 | 记录断点区 |
 | FAILED | 修复后重试 | 分析失败原因 |
 **关键约束**：
-- **角色隔离**：Coder 必须在**单独的会话/实例**中工作
-- Test Owner 和 Coder 不能共享同一会话上下文
+- **模式切换替代会话隔离**：使用 `[TEST-OWNER]` / `[CODER]` 标签切换模式
 - 如有偏离，必须先 design-backport 再交给 Coder
 - **阶段 2 的 AC 矩阵打勾只能由 Test Owner 执行**
+- **阶段 2 必须等 @full 测试通过后才能打勾**
 ---

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 CHANGED Viewed

@@ -11,6 +11,10 @@
   - 设计/规格文档
   - 测试驱动/验收方法论（参考：`references/测试驱动.md`）
+  **必须读取的 Spec 真理**（测试前强制检查）：
+  - `<truth-root>/specs/**`：现有规格文件
+  - 目的：从 Spec 中的契约（Preconditions/Postconditions/Invariants）和状态机自动生成测试骨架
   产物落点（目录约定，协议无关）：
   - 测试计划与追溯文档推荐保存为：`<change-root>/<change-id>/verification.md`
   - 测试代码变更仍落在仓库惯例目录（例如 `tests/`），但追溯矩阵与人工验收清单优先放在本次变更包内（verification.md），避免散落到对外 docs
@@ -57,7 +61,7 @@
   在完成 A 后，开始在仓库中实现测试代码（只写测试，不写业务实现），要求：
   【核心理念（必须遵守）】
-  1) **测试=可执行契约（Executable Spec）**：从“设计要求/验收标准/不变量”推导测试，而不是从“现有代码结构”推导测
+  1) **测试=可执行契约（Executable Spec）**：从"设计要求/验收标准/不变量"推导测试，而不是从"现有代码结构"推导测
   试。
   2) **行为优先、实现无关**：优先断言输出行为/数据契约/事件内容/不变量；避免断言私有函数调用次数、内部步骤顺序等实
   现细节。
@@ -65,6 +69,16 @@
   归。
   4) **少而硬（风险驱动）**：优先覆盖最危险的失败模式（隔离、幂等/重放、质量闸门、错误级联阻断、契约漂移）。
+  **从 Spec 真理生成契约测试**（必须遵守）：
+  - **Invariants → 不变量测试**：Spec 中每个 `[Invariant]` 或 `INV-xxx` 必须生成对应的不变量测试
+  - **Preconditions → 前置条件测试**：Spec 中每个 `PRE-xxx` 生成两类测试：(1) 满足条件时正常执行 (2) 违反条件时正确拒绝
+  - **Postconditions → 后置条件测试**：Spec 中每个 `POST-xxx` 生成结果验证测试
+  - **State Machine → 状态转换测试**：如 Spec 包含状态机定义，必须生成：
+    - 所有合法转换路径的测试
+    - 所有禁止转换的拒绝测试
+    - 终态不可转出的测试
+  - **REQ 覆盖追溯**：每个测试必须在注释或 verification.md 中标注其覆盖的 REQ-xxx/INV-xxx/PRE-xxx/POST-xxx
   **测试覆盖率分级要求**（辩论修订版）：
   > 来源：《重构》辩论修订版——从"一刀切80%"改为"分级要求"