dev-playbooks-cn 1.5.5 → 1.6.0

package/README.md

@@ -97,6 +97,20 @@ dev-playbooks-cn init --tools claude --scope project  # 项目级
 dev-playbooks-cn init --tools claude --scope global   # 全局
 ```
 
+### 更新
+
+使用 `update` 命令同时更新 CLI 和项目中的 Skills：
+
+```bash
+dev-playbooks-cn update
+```
+
+更新命令会：
+1. **检查 CLI 新版本**：自动检测 npm 上是否有新版本，交互式询问是否更新
+2. **更新项目文件**：更新 Skills、规则文件、指令文件等
+
+> **提示**：不再需要手动运行 `npm install -g dev-playbooks-cn`，`update` 命令会自动处理。
+
 ### 快速集成
 
 DevBooks 使用两个目录根：

package/package.json

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

package/skills/devbooks-archiver/SKILL.md

@@ -12,6 +12,36 @@ allowed-tools:
 
 # DevBooks：归档器（Archiver）
 
+## 🚨 绝对禁令（ABSOLUTE RULES）
+
+> **这些规则没有例外，违反即失败。**
+
+### 禁令 1：禁止跳过脚本验证
+
+```
+❌ 禁止：不运行 change-check.sh 就执行归档
+❌ 禁止：change-check.sh 返回非零就继续归档
+❌ 禁止：手动跳过或绕过脚本检查
+
+✅ 必须：归档前运行 change-check.sh --mode strict
+✅ 必须：脚本返回 0 才能继续
+✅ 必须：脚本失败时停止并输出完整错误信息
+```
+
+### 禁令 2：禁止假完成归档
+
+```
+❌ 禁止：evidence/green-final/ 不存在或为空时归档
+❌ 禁止：verification.md AC 覆盖率 < 100% 时归档
+❌ 禁止：tasks.md 存在未完成任务时归档
+
+✅ 必须：所有检查项全部通过
+✅ 必须：Green 证据目录非空
+✅ 必须：AC 覆盖率 100%
+```
+
+---
+
 ## 工作流位置感知（Workflow Position Awareness）
 
 > **核心原则**：Archiver 是归档阶段的**唯一入口**，负责完成从代码评审到变更包归档的所有收尾工作。
@@ -62,10 +92,48 @@ proposal → design → test-owner(P1) → coder → test-owner(P2) → code-rev
 
 ## 归档完整流程
 
-### 第 1 步：前置检查
+### 第 0 步：运行强制验证脚本（MANDATORY）
+
+> **这是归档的第一个动作，不可跳过。**
+
+```bash
+# 必须运行此命令
+change-check.sh <change-id> --mode strict
+```
+
+**执行规则**：
+
+| 脚本返回值 | 行为 |
+|-----------|------|
+| `0` (成功) | 继续执行后续步骤 |
+| 非零 (失败) | **立即停止**，输出完整错误信息，不执行任何归档操作 |
+
+**脚本检查内容**（--mode strict）：
+
+- 变更包存在性
+- verification.md 状态和 AC 覆盖率
+- evidence/green-final/ 存在且非空
+- tasks.md 任务完成率
+- 所有闸门检查
+
+**失败时的输出格式**：
+
+```
+❌ 归档前置检查失败
+
+脚本输出：
+<change-check.sh 的完整输出>
+
+建议操作：
+- 根据上述错误修复问题
+- 重新运行 change-check.sh --mode strict
+- 确认所有检查通过后再次尝试归档
+```
+
+### 第 1 步：前置检查（脚本通过后的二次确认）
 
 ```markdown
-前置检查清单：
+前置检查清单（验证脚本已检查，此为二次确认）：
 - [ ] 变更包存在（<change-root>/<change-id>/）
 - [ ] verification.md Status = Ready 或 Done
 - [ ] evidence/green-final/ 存在且非空
@@ -234,7 +302,7 @@ archived-by: devbooks-archiver
 
 | 模式 | 触发条件 | 行为 |
 |------|----------|------|
-| **归档模式** | 提供 change-id 且闸门通过 | 执行完整归档流程（6步） |
+| **归档模式** | 提供 change-id 且闸门通过 | 执行完整归档流程（7步：0-6） |
 | **维护模式** | 无 change-id | 执行 truth-root 去重、清理、整理 |
 | **检查模式** | 带 --dry-run 参数 | 只输出计划，不实际修改/移动 |
 
@@ -245,7 +313,13 @@ archived-by: devbooks-archiver
 │                      归档模式流程                            │
 ├─────────────────────────────────────────────────────────────┤
 │                                                             │
-│  1. 前置检查                                                 │
+│  0. 运行强制验证脚本（MANDATORY）                             │
+│     └─ change-check.sh <change-id> --mode strict           │
+│              │                                               │
+│              ├─ 返回非零 → ❌ 停止，输出错误                  │
+│              │                                               │
+│              ▼ 返回 0                                        │
+│  1. 前置检查（二次确认）                                      │
 │     ├─ 变更包存在？                                          │
 │     ├─ verification.md Status = Ready/Done？                │
 │     ├─ evidence/green-final/ 存在？                          │

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

@@ -13,253 +13,363 @@ allowed-tools:
 
 # DevBooks：交付验收工作流（完整闭环编排器）
 
-> **定位**：本 Skill 是**编排层**，不是日常手动使用的 Skill。它在支持子 Agent 的 AI 编程工具（如 Claude Code with Task tool）中调用，自动编排完整的变更闭环。
+> **定位**：本 Skill 是**纯编排层**，不是执行层。它只负责**调用子 Agent**，绝不自己执行任何变更工作。
 
-## 前置：配置发现（协议无关）
+---
 
-- `<truth-root>`：当前真理目录根
-- `<change-root>`：变更包目录根
+## 🚨 绝对禁令（ABSOLUTE RULES）
 
-执行前**必须**按以下顺序查找配置（找到后停止）：
-1. `.devbooks/config.yaml`（如存在）→ 解析并使用其中的映射
-2. `dev-playbooks/project.md`（如存在）→ Dev-Playbooks 协议，使用默认映射
-3. `project.md`（如存在）→ template 协议，使用默认映射
-4. 若仍无法确定 → **停止并询问用户**
+> **这些规则没有例外，违反即失败。**
 
-**关键约束**：
-- 如果配置中指定了 `agents_doc`（规则文档），**必须先阅读该文档**再执行任何操作
-- 禁止猜测目录根
-- 禁止跳过规则文档阅读
+### 禁令 1：禁止主 Agent 直接工作
 
-## 核心职责：完整闭环编排
+```
+❌ 禁止：主 Agent 自己写 proposal.md / design.md / tests/ / src/
+❌ 禁止：主 Agent 直接修改任何变更包内容
+❌ 禁止：主 Agent 跳过子 Agent 调用
 
-本 Skill 的核心能力是**编排子 Agent 完成完整变更闭环**。
+✅ 必须：所有工作通过 Task 工具调用子 Agent 完成
+✅ 必须：每个阶段都有对应的子 Agent 调用
+✅ 必须：主 Agent 只做编排、等待、验证
+```
 
-### 闭环流程（8 个阶段）
+### 禁令 2：禁止跳过任何强制阶段
 
 ```
-┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
-│  1. Propose │ ──▶ │  2. Design  │ ──▶ │  3. Spec    │ ──▶ │  4. Plan    │
-│  (提案)     │     │  (设计)     │     │  (规格)     │     │  (计划)     │
-└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘
-       │                                                           │
-       ▼                                                           ▼
-┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
-│  8. Archive │ ◀── │  7. Review  │ ◀── │  6. Code    │ ◀── │  5. Test    │
-│  (归档)     │     │  (评审)     │     │  (实现)     │     │  (测试)     │
-└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘
+❌ 禁止：跳过 Challenger/Judge 阶段
+❌ 禁止：跳过 Test-Reviewer 阶段
+❌ 禁止：跳过 Code-Review 阶段
+❌ 禁止：跳过 Green-Verify 阶段
+❌ 禁止：未通过 strict 检查就归档
+
+✅ 必须：完整执行 12 个强制阶段
+✅ 必须：每个阶段的子 Agent 返回成功才能继续
 ```
 
-### 阶段详解与对应 Skill
+### 禁令 3：禁止假完成归档
+
+```
+❌ 禁止：evidence/green-final/ 不存在或为空时归档
+❌ 禁止：verification.md AC 覆盖率 < 100% 时归档
+❌ 禁止：tasks.md 存在未完成任务时归档
+❌ 禁止：change-check.sh --mode strict 失败时归档
+
+✅ 必须：Archiver 子 Agent 先运行检查脚本
+✅ 必须：所有检查通过后才执行归档
+```
+
+---
+
+## 前置：配置发现（协议无关）
+
+执行前**必须**按以下顺序查找配置：
+1. `.devbooks/config.yaml`（如存在）→ 解析并使用其中的映射
+2. `dev-playbooks/project.md`（如存在）→ Dev-Playbooks 协议
+3. `project.md`（如存在）→ template 协议
+4. 若仍无法确定 → **停止并询问用户**
 
-| 阶段 | 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 |
+---
 
-### 编排逻辑
+## 完整闭环流程（12 个强制阶段）
 
 ```
-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 归档到真理源
+┌──────────────────────────────────────────────────────────────────────────┐
+│                         强制流程（无可选阶段）                              │
+├──────────────────────────────────────────────────────────────────────────┤
+│                                                                          │
+│  ┌─────────┐   ┌───────────┐   ┌─────────┐   ┌─────────┐                │
+│  │1.Propose│──▶│2.Challenge│──▶│ 3.Judge │──▶│4.Design │                │
+│  └─────────┘   └───────────┘   └─────────┘   └─────────┘                │
+│       │                                            │                     │
+│       │              ┌─────────────────────────────┘                     │
+│       │              ▼                                                   │
+│       │        ┌─────────┐   ┌─────────┐   ┌─────────┐                  │
+│       │        │ 5.Spec  │──▶│ 6.Plan  │──▶│7.Test-R │                  │
+│       │        └─────────┘   └─────────┘   └─────────┘                  │
+│       │                                          │                       │
+│       │              ┌───────────────────────────┘                       │
+│       │              ▼                                                   │
+│       │        ┌─────────┐   ┌──────────┐   ┌──────────┐                │
+│       │        │ 8.Code  │──▶│9.TestRev │──▶│10.CodeRev│                │
+│       │        └─────────┘   └──────────┘   └──────────┘                │
+│       │                                            │                     │
+│       │              ┌─────────────────────────────┘                     │
+│       │              ▼                                                   │
+│       │        ┌───────────┐   ┌─────────┐                              │
+│       └───────▶│11.GreenV  │──▶│12.Archive│                              │
+│                └───────────┘   └─────────┘                              │
+│                                                                          │
+└──────────────────────────────────────────────────────────────────────────┘
 ```
 
-### 角色隔离约束
+### 阶段详解与子 Agent 调用
+
+| # | 阶段 | 子 Agent | Skill | 产物 | 强制 |
+|---|------|----------|-------|------|------|
+| 1 | Propose | `devbooks-proposal-author` | devbooks-proposal-author | proposal.md | ✅ |
+| 2 | Challenge | `devbooks-challenger` | devbooks-proposal-challenger | 质疑意见 | ✅ |
+| 3 | Judge | `devbooks-judge` | devbooks-proposal-judge | Decision Log | ✅ |
+| 4 | Design | `devbooks-designer` | devbooks-design-doc | design.md | ✅ |
+| 5 | Spec | `devbooks-spec-owner` | devbooks-spec-contract | specs/*.md | ✅ |
+| 6 | Plan | `devbooks-planner` | devbooks-implementation-plan | tasks.md | ✅ |
+| 7 | Test-Red | `devbooks-test-owner` | devbooks-test-owner | verification.md + tests/ | ✅ |
+| 8 | Code | `devbooks-coder` | devbooks-coder | src/ 实现 | ✅ |
+| 9 | Test-Review | `devbooks-reviewer` | devbooks-test-reviewer | 测试评审意见 | ✅ |
+| 10 | Code-Review | `devbooks-reviewer` | devbooks-code-review | 代码评审意见 | ✅ |
+| 11 | Green-Verify | `devbooks-test-owner` | devbooks-test-owner | evidence/green-final/ | ✅ |
+| 12 | Archive | `devbooks-archiver` | devbooks-archiver | 归档到 archive/ | ✅ |
 
-**关键原则**：Test Owner 和 Coder 必须使用**独立的 Agent 实例/会话**。
+---
 
-| 角色 | 隔离要求 | 原因 |
-|------|----------|------|
-| Test Owner | 独立 Agent | 防止 Coder 篡改测试 |
-| Coder | 独立 Agent | 防止 Coder 看到测试实现细节 |
-| Reviewer | 独立 Agent（推荐） | 保持评审客观性 |
+## 编排逻辑（伪代码）
+
+```python
+def run_delivery_workflow(user_requirement):
+    """
+    主 Agent 只执行此编排逻辑，不做任何实际工作
+    """
+
+    # ==================== 阶段 1: Propose ====================
+    change_id = call_subagent("devbooks-proposal-author", {
+        "task": "创建变更提案",
+        "requirement": user_requirement
+    })
+    verify_output(f"{change_root}/{change_id}/proposal.md")
+
+    # ==================== 阶段 2: Challenge ====================
+    challenge_result = call_subagent("devbooks-challenger", {
+        "task": "质疑提案",
+        "change_id": change_id
+    })
+    # 不跳过，即使没有质疑也要运行
+
+    # ==================== 阶段 3: Judge ====================
+    judge_result = call_subagent("devbooks-judge", {
+        "task": "裁决提案",
+        "change_id": change_id,
+        "challenge_result": challenge_result
+    })
+    if judge_result == "REJECTED":
+        return "提案被拒绝，流程终止"
+    if judge_result == "REVISE":
+        # 回到阶段 1，重新编写提案
+        return run_delivery_workflow(revised_requirement)
+    # judge_result == "APPROVED" 继续
+
+    # ==================== 阶段 4: Design ====================
+    call_subagent("devbooks-designer", {
+        "task": "创建设计文档",
+        "change_id": change_id
+    })
+    verify_output(f"{change_root}/{change_id}/design.md")
+
+    # ==================== 阶段 5: Spec ====================
+    call_subagent("devbooks-spec-owner", {
+        "task": "定义规格契约",
+        "change_id": change_id
+    })
+    # specs/ 目录可能为空（无对外契约时）
+
+    # ==================== 阶段 6: Plan ====================
+    call_subagent("devbooks-planner", {
+        "task": "创建实现计划",
+        "change_id": change_id
+    })
+    verify_output(f"{change_root}/{change_id}/tasks.md")
+
+    # ==================== 阶段 7: Test-Red ====================
+    # 必须使用独立 Agent 会话
+    call_subagent("devbooks-test-owner", {
+        "task": "编写测试并建立 Red 基线",
+        "change_id": change_id,
+        "isolation": "required"  # 强制隔离
+    })
+    verify_output(f"{change_root}/{change_id}/verification.md")
+    verify_output(f"{change_root}/{change_id}/evidence/red-baseline/")
+
+    # ==================== 阶段 8: Code ====================
+    # 必须使用独立 Agent 会话
+    call_subagent("devbooks-coder", {
+        "task": "按 tasks.md 实现功能",
+        "change_id": change_id,
+        "isolation": "required"  # 强制隔离
+    })
+
+    # ==================== 阶段 9: Test-Review ====================
+    test_review_result = call_subagent("devbooks-reviewer", {
+        "task": "评审测试质量",
+        "change_id": change_id,
+        "review_type": "test-review"
+    })
+    if test_review_result == "REVISE REQUIRED":
+        # 回到阶段 7，修复测试问题
+        goto_stage(7)
+
+    # ==================== 阶段 10: Code-Review ====================
+    code_review_result = call_subagent("devbooks-reviewer", {
+        "task": "评审代码质量",
+        "change_id": change_id,
+        "review_type": "code-review"
+    })
+    if code_review_result == "REVISE REQUIRED":
+        # 回到阶段 8，修复代码问题
+        goto_stage(8)
+
+    # ==================== 阶段 11: Green-Verify ====================
+    # 必须使用独立 Agent 会话（与阶段 7 相同的 Test Owner）
+    call_subagent("devbooks-test-owner", {
+        "task": "运行所有测试并收集 Green 证据",
+        "change_id": change_id,
+        "isolation": "required",
+        "phase": "green-verify"
+    })
+    verify_output(f"{change_root}/{change_id}/evidence/green-final/")
+
+    # ==================== 阶段 12: Archive ====================
+    # Archiver 会自动运行 change-check.sh --mode strict
+    call_subagent("devbooks-archiver", {
+        "task": "执行归档",
+        "change_id": change_id
+    })
+
+    return "闭环完成"
+```
 
-### 闸门检查点
+---
 
-每个阶段完成后，调用 `change-check.sh` 验证：
+## 子 Agent 调用模板
 
-```bash
-# 提案阶段检查
-change-check.sh <change-id> --mode proposal
+### 调用格式
 
-# 实现阶段检查（Test Owner）
-change-check.sh <change-id> --mode apply --role test-owner
+使用 Task 工具调用子 Agent：
 
-# 实现阶段检查（Coder）
-change-check.sh <change-id> --mode apply --role coder
+```markdown
+## 调用 devbooks-proposal-author 子 Agent
 
-# 归档前检查
-change-check.sh <change-id> --mode archive
+请执行以下任务：
+- 使用 devbooks-proposal-author skill
+- 为以下需求创建变更提案：[需求描述]
+- 生成符合规范的 change-id
+- 完成后输出 change-id 和 proposal.md 路径
 ```
 
-## 参考骨架（按需读取）
+### 各阶段调用示例
+
+| 阶段 | 子 Agent | 调用 Prompt |
+|------|----------|-------------|
+| 1 | devbooks-proposal-author | "使用 devbooks-proposal-author skill 为 [需求] 创建变更提案" |
+| 2 | devbooks-challenger | "使用 devbooks-proposal-challenger skill 质疑变更 [change-id] 的提案" |
+| 3 | devbooks-judge | "使用 devbooks-proposal-judge skill 裁决变更 [change-id]" |
+| 4 | devbooks-designer | "使用 devbooks-design-doc skill 为变更 [change-id] 创建设计文档" |
+| 5 | devbooks-spec-owner | "使用 devbooks-spec-contract skill 为变更 [change-id] 定义规格" |
+| 6 | devbooks-planner | "使用 devbooks-implementation-plan skill 为变更 [change-id] 创建计划" |
+| 7 | devbooks-test-owner | "使用 devbooks-test-owner skill 为变更 [change-id] 编写测试并建立 Red 基线" |
+| 8 | devbooks-coder | "使用 devbooks-coder skill 为变更 [change-id] 实现功能" |
+| 9 | devbooks-reviewer | "使用 devbooks-test-reviewer skill 评审变更 [change-id] 的测试" |
+| 10 | devbooks-reviewer | "使用 devbooks-code-review skill 评审变更 [change-id] 的代码" |
+| 11 | devbooks-test-owner | "使用 devbooks-test-owner skill 运行变更 [change-id] 的所有测试并收集 Green 证据" |
+| 12 | devbooks-archiver | "使用 devbooks-archiver skill 归档变更 [change-id]" |
 
-- 工作流：`references/交付验收工作流.md`
-- 模板：`references/变更验证与追溯模板.md`
+---
 
-## 可选检查脚本
+## 角色隔离约束
 
-脚本位于本 Skill 的 `scripts/` 目录（可执行；优先"跑脚本拿结果"，而不是把脚本正文读进上下文）。
-
-- 初始化变更包骨架：`change-scaffold.sh <change-id> --project-root <repo-root> --change-root <change-root> --truth-root <truth-root>`
-- 一键校验变更包：`change-check.sh <change-id> --mode <proposal|apply|review|archive|strict> --role <test-owner|coder|reviewer> --project-root <repo-root> --change-root <change-root> --truth-root <truth-root>`
-- 结构守门决策校验（strict 会自动调用）：`guardrail-check.sh <change-id> --project-root <repo-root> --change-root <change-root>`
-- 初始化 spec delta 骨架：`change-spec-delta-scaffold.sh <change-id> <capability> --project-root <repo-root> --change-root <change-root>`
-- 证据采集（把 tests/命令输出落盘到 evidence）：`change-evidence.sh <change-id> --label <name> --project-root <repo-root> --change-root <change-root> -- <command> [args...]`
-- 大规模机械变更（LSC）codemod 脚本骨架：`change-codemod-scaffold.sh <change-id> --name <codemod-name> --project-root <repo-root> --change-root <change-root>`
-- 卫生检查（临时文件/进程清理）：`hygiene-check.sh <change-id> --project-root <repo-root> --change-root <change-root>`
-
-## 质量闸门脚本（v2）
-
-以下脚本用于强化质量闸门，拦截"假完成"：
-
-- 角色交接检查：`handoff-check.sh <change-id> --project-root <repo-root> --change-root <change-root>`
-- 环境声明检查：`env-match-check.sh <change-id> --project-root <repo-root> --change-root <change-root>`
-- 审计全量扫描：`audit-scope.sh <directory> --format <markdown|json>`
-- 进度仪表板：`progress-dashboard.sh <change-id> --project-root <repo-root> --change-root <change-root>`
-- v2 闸门迁移：`migrate-to-v2-gates.sh <change-id> --project-root <repo-root> --change-root <change-root>`
-
-### change-check.sh v2 新增检查项
-
-| 检查项 | 触发模式 | 说明 | AC |
-|--------|----------|------|-----|
-| `check_evidence_closure()` | archive, strict | 验证 `evidence/green-final/` 存在且非空 | AC-001 |
-| `check_task_completion_rate()` | strict | 验证任务完成率 100%（支持 SKIP-APPROVED） | AC-002 |
-| `check_role_boundaries()` | apply --role | 验证角色边界（扩展自 check_no_tests_changed） | AC-003 |
-| `check_skip_approval()` | strict | 验证 P0 任务跳过有审批记录 | AC-005 |
-| `check_env_match()` | archive, strict | 调用 env-match-check.sh 检查环境声明 | AC-006 |
-| `check_test_failure_in_evidence()` | archive, strict | 检测 Green 证据中的失败模式 | AC-007 |
-
-### change-check.sh 基础检查项
-
-| 检查项 | 触发模式 | 说明 |
-|--------|----------|------|
-| `check_proposal()` | 所有模式 | 检查 proposal.md 格式与决策状态 |
-| `check_design()` | 所有模式 | 检查 design.md 结构（AC 列表、Problem Context 等） |
-| `check_tasks()` | 所有模式 | 检查 tasks.md 结构（主线计划区、断点区） |
-| `check_verification()` | 所有模式 | 检查 verification.md 四大必填节 |
-| `check_spec_deltas()` | 所有模式 | 检查 specs/ 目录下 spec delta 格式 |
-| `check_implicit_changes()` | apply, archive, strict | 检测隐式变更（依赖、配置、构建） |
-
-### 角色边界约束
-
-| 角色 | 禁止修改 |
-|------|----------|
-| Coder | `tests/**`、`verification.md`、`.devbooks/` |
-| Test Owner | `src/**` |
-| Reviewer | 代码文件（`.ts`、`.js`、`.py`、`.sh` 等） |
-
-详细说明参见：`docs/quality-gates-guide.md`
-
-## 架构合规检查（依赖卫士）
-
-在合并前进行架构合规检查，防止依赖方向违规。
-
-### guardrail-check.sh 完整选项
-
-```bash
-guardrail-check.sh <change-id> [options]
-
-Options:
-  --project-root <dir>   项目根目录
-  --change-root <dir>    变更包目录
-  --truth-root <dir>     真理目录（包含 architecture/c4.md）
-  --role <role>          角色权限检查 (coder|test-owner|reviewer)
-  --check-lockfile       检查 lockfile 变更是否声明
-  --check-engineering    检查工程系统变更是否声明
-  --check-layers         检查分层约束违规（依赖卫士核心）
-  --check-cycles         检查循环依赖
-  --check-hotspots       警告热点文件变更
-```
+**关键原则**：Test Owner 和 Coder 必须使用**独立的 Agent 实例/会话**。
+
+| 角色 | 隔离要求 | 原因 |
+|------|----------|------|
+| Test Owner (阶段 7, 11) | 独立 Agent | 防止 Coder 篡改测试 |
+| Coder (阶段 8) | 独立 Agent | 防止 Coder 看到测试实现细节 |
+| Reviewer (阶段 9, 10) | 独立 Agent（推荐） | 保持评审客观性 |
 
-### 分层约束检查内容
+---
+
+## 闸门检查点
 
-`--check-layers` 会检测以下违规：
+### 阶段闸门
 
-| 违规类型 | 示例 | 严重程度 |
-|----------|------|----------|
-| 下层引用上层 | `base/` 导入 `platform/` | 🔴 Critical |
-| common 引用 browser/node | `common/` 导入 `browser/` | 🔴 Critical |
-| common 使用 DOM API | `document.` 在 common 中 | 🔴 Critical |
-| core 引用 contrib | 违反扩展点设计 | 🟡 High |
+| 检查点 | 时机 | 命令 |
+|--------|------|------|
+| 提案完成 | 阶段 3 后 | `change-check.sh <change-id> --mode proposal` |
+| 设计完成 | 阶段 6 后 | `change-check.sh <change-id> --mode apply --role test-owner` |
+| 实现完成 | 阶段 10 后 | `change-check.sh <change-id> --mode apply --role coder` |
+| 归档前 | 阶段 12 前 | `change-check.sh <change-id> --mode strict` |
 
-### 推荐用法
+### 归档前强制检查项
 
-```bash
-# 完整架构检查（合并前）
-guardrail-check.sh <change-id> \
-  --truth-root devbooks \
-  --check-layers \
-  --check-cycles \
-  --check-hotspots \
-  --check-lockfile \
-  --check-engineering
+Archiver 子 Agent 必须验证：
 
-# 快速检查（日常开发）
-guardrail-check.sh <change-id> --check-layers --check-cycles
+| 检查项 | 要求 |
+|--------|------|
+| evidence/green-final/ | 存在且非空 |
+| verification.md AC 覆盖 | 100%（所有 AC 有对应测试） |
+| tasks.md 任务完成率 | 100%（所有 [x] 或 SKIP-APPROVED） |
+| change-check.sh --mode strict | 全部通过 |
+
+---
+
+## 错误处理
+
+### Judge 返回 REVISE
+
+```
+阶段 3 返回 REVISE
+    ↓
+通知用户裁决意见
+    ↓
+回到阶段 1，携带修改建议
+    ↓
+重新执行阶段 1-3
 ```
 
-### CI 集成示例
+### Review 返回 REVISE REQUIRED
 
-```yaml
-# .github/workflows/pr.yml
-- name: Architecture Compliance Check
-  run: |
-    ./scripts/guardrail-check.sh ${{ github.event.pull_request.number }} \
-      --truth-root devbooks \
-      --check-layers \
-      --check-cycles
+```
+阶段 9（Test-Review）返回 REVISE REQUIRED
+    ↓
+回到阶段 7，修复测试问题
+    ↓
+重新执行阶段 7-9
+
+阶段 10（Code-Review）返回 REVISE REQUIRED
+    ↓
+回到阶段 8，修复代码问题
+    ↓
+重新执行阶段 8-10
 ```
 
----
+### Archive 检查失败
 
-## 上下文感知
+```
+阶段 12 检查失败
+    ↓
+输出失败原因（缺失 evidence / AC 未覆盖 / 任务未完成）
+    ↓
+回到相应阶段修复
+    ↓
+重新执行到阶段 12
+```
 
-本 Skill 在执行前自动检测上下文，选择合适的工作流阶段。
+---
 
-检测规则参考：`skills/_shared/context-detection-template.md`
+## 上下文感知
 
 ### 检测流程
 
 1. 检测变更包是否存在
-2. 检测当前阶段（proposal/apply/archive）
-3. 检测闸门状态
+2. 检测当前阶段（哪些阶段已完成）
+3. 从断点继续执行
 
-### 本 Skill 支持的模式
+### 断点续跑
 
-| 模式 | 触发条件 | 行为 |
-|------|----------|------|
-| **初始化模式** | 变更包不存在 | 创建变更包骨架 |
-| **检查模式** | 带 --check 参数 | 只运行闸门检查 |
-| **完整闭环** | 无特殊参数 | 执行完整 Design→Archive 流程 |
-
-### 检测输出示例
+若变更包已存在部分产物，从最近完成的阶段继续：
 
 ```
 检测结果：
 - 变更包：存在
-- 当前阶段：apply
-- 闸门状态：proposal ✓, design ✓, tasks ✓
-- 运行模式：检查模式（apply 阶段）
+- 已完成阶段：1-6（proposal, challenge, judge, design, spec, plan）
+- 下一阶段：7（Test-Red）
+- 运行模式：断点续跑
 ```
 
 ---
@@ -268,8 +378,6 @@ guardrail-check.sh <change-id> --check-layers --check-cycles
 
 本 Skill 支持 MCP 运行时增强，自动检测并启用高级功能。
 
-MCP 增强规则参考：`skills/_shared/mcp-enhancement-template.md`
-
 ### 依赖的 MCP 服务
 
 | 服务 | 用途 | 超时 |
@@ -282,19 +390,19 @@ MCP 增强规则参考：`skills/_shared/mcp-enhancement-template.md`
 2. 在工作流状态报告中标注索引可用性
 3. 若不可用 → 建议在 apply 阶段前生成索引
 
-### 增强模式 vs 基础模式
+---
 
-| 功能 | 增强模式 | 基础模式 |
-|------|----------|----------|
-| 架构检查 | 精确依赖分析 | 基于 import 语句 |
-| 热点预警 | CKB 实时分析 | 不可用 |
-| 影响评估 | 调用图分析 | 文件级估算 |
+## 参考骨架（按需读取）
 
-### 降级提示
+- 工作流：`references/交付验收工作流.md`
+- 模板：`references/变更验证与追溯模板.md`
 
-当 MCP 不可用时，输出以下提示：
+## 可选检查脚本
 
-```
-⚠️ CKB 索引不可用，架构检查将使用基础模式。
-建议手动生成 SCIP 索引以启用精确检查。
-```
+脚本位于本 Skill 的 `scripts/` 目录：
+
+- 初始化变更包骨架：`change-scaffold.sh`
+- 一键校验变更包：`change-check.sh`
+- 结构守门决策校验：`guardrail-check.sh`
+- 证据采集：`change-evidence.sh`
+- 进度仪表板：`progress-dashboard.sh`

package/templates/claude-agents/devbooks-archiver.md

@@ -0,0 +1,22 @@
+---
+name: devbooks-archiver
+description: DevBooks Archiver 子代理：执行归档闭环（验证→回写→规格合并→移动归档），必须先通过所有检查。
+skills: devbooks-archiver
+---
+
+# DevBooks Archiver 子代理
+
+此子代理用于在 Task 工具中执行归档任务。
+
+## 使用场景
+
+当主编排器需要委托归档任务给子代理时使用，例如：
+- delivery-workflow 编排器在 Green Verify 通过后调用
+- 在隔离上下文中执行归档
+
+## 约束
+
+- **必须先运行** `change-check.sh --mode strict` 并通过
+- 若检查失败 → 停止归档，输出失败原因
+- 若检查通过 → 执行完整归档流程（6 步）
+- 完成后输出归档报告

package/templates/claude-agents/devbooks-challenger.md

@@ -0,0 +1,21 @@
+---
+name: devbooks-challenger
+description: DevBooks Challenger 子代理：质疑提案，发现风险、遗漏和不一致，输出质疑意见。
+skills: devbooks-proposal-challenger
+---
+
+# DevBooks Challenger 子代理
+
+此子代理用于在 Task 工具中执行提案质疑任务。
+
+## 使用场景
+
+当主编排器需要委托质疑任务给子代理时使用，例如：
+- delivery-workflow 编排器调用以质疑提案
+- 在隔离上下文中执行深度质疑分析
+
+## 约束
+
+- 只输出质疑意见，不修改 proposal.md
+- 必须指出风险、遗漏、不一致
+- 完成后输出 CHALLENGE_REPORT（质疑要点 + 风险等级）

package/templates/claude-agents/devbooks-designer.md

@@ -0,0 +1,22 @@
+---
+name: devbooks-designer
+description: DevBooks Designer 子代理：创建设计文档（design.md），定义 What/Constraints/AC-xxx，不写实现步骤。
+skills: devbooks-design-doc
+---
+
+# DevBooks Designer 子代理
+
+此子代理用于在 Task 工具中执行设计文档撰写任务。
+
+## 使用场景
+
+当主编排器需要委托设计任务给子代理时使用，例如：
+- delivery-workflow 编排器在 Judge 通过后调用
+- 在隔离上下文中执行设计分析
+
+## 约束
+
+- 必须产出 design.md
+- 只定义 What/Constraints/AC-xxx，不写实现步骤
+- AC 必须是可观察的 Pass/Fail 标准
+- 完成后输出 AC 列表摘要

package/templates/claude-agents/devbooks-judge.md

@@ -0,0 +1,22 @@
+---
+name: devbooks-judge
+description: DevBooks Judge 子代理：裁决提案，输出 Approved/Revise/Rejected 决策并写入 Decision Log。
+skills: devbooks-proposal-judge
+---
+
+# DevBooks Judge 子代理
+
+此子代理用于在 Task 工具中执行提案裁决任务。
+
+## 使用场景
+
+当主编排器需要委托裁决任务给子代理时使用，例如：
+- delivery-workflow 编排器在 Challenger 完成后调用
+- 在隔离上下文中执行裁决分析
+
+## 约束
+
+- 必须综合 proposal.md 和 Challenger 意见
+- 必须输出明确决策：APPROVED / REVISE / REJECTED
+- 若 REVISE：指出需修改的具体内容
+- 必须更新 proposal.md 的 Decision Log 章节

package/templates/claude-agents/devbooks-planner.md

@@ -0,0 +1,22 @@
+---
+name: devbooks-planner
+description: DevBooks Planner 子代理：从设计文档推导编码计划（tasks.md），输出可跟踪的主线计划。
+skills: devbooks-implementation-plan
+---
+
+# DevBooks Planner 子代理
+
+此子代理用于在 Task 工具中执行计划编写任务。
+
+## 使用场景
+
+当主编排器需要委托计划编写任务给子代理时使用，例如：
+- delivery-workflow 编排器在 Spec 完成后调用
+- 在隔离上下文中执行计划拆分
+
+## 约束
+
+- 必须产出 tasks.md
+- 只从 design.md 推导，禁止从 tests/ 反推
+- 每个任务必须绑定 AC-xxx
+- 完成后输出任务数量和依赖关系

package/templates/claude-agents/devbooks-proposal-author.md

@@ -0,0 +1,22 @@
+---
+name: devbooks-proposal-author
+description: DevBooks Proposal Author 子代理：创建变更提案（proposal.md），定义 Why/What/Impact，生成 change-id。
+skills: devbooks-proposal-author
+---
+
+# DevBooks Proposal Author 子代理
+
+此子代理用于在 Task 工具中执行提案撰写任务。
+
+## 使用场景
+
+当主编排器需要委托提案撰写任务给子代理时使用，例如：
+- delivery-workflow 编排器调用以创建新变更提案
+- 在隔离上下文中执行提案撰写
+
+## 约束
+
+- 必须产出 proposal.md
+- 必须生成符合规范的 change-id（YYYYMMDD-HHMM-<动词>-描述）
+- 只定义 Why/What/Impact，不写实现代码
+- 完成后输出 change-id 和 proposal.md 路径

package/templates/claude-agents/devbooks-spec-owner.md

@@ -0,0 +1,22 @@
+---
+name: devbooks-spec-owner
+description: DevBooks Spec Owner 子代理：定义对外行为规格与契约（specs/*.md），包括 API/Schema/兼容策略。
+skills: devbooks-spec-contract
+---
+
+# DevBooks Spec Owner 子代理
+
+此子代理用于在 Task 工具中执行规格定义任务。
+
+## 使用场景
+
+当主编排器需要委托规格定义任务给子代理时使用，例如：
+- delivery-workflow 编排器在 Design 完成后调用
+- 在隔离上下文中执行契约设计
+
+## 约束
+
+- 必须产出 specs/**/*.md
+- 定义对外 API/Schema/Event 契约
+- 包含兼容策略和迁移方案
+- 完成后输出受影响的契约列表