dev-playbooks-cn 2.5.3 → 2.6.0

package/skills/devbooks-delivery-workflow/references//347/274/226/346/216/222/347/246/201/344/273/244/344/270/216/351/230/266/346/256/265/350/241/250.md

@@ -0,0 +1,185 @@
+# 编排禁令与阶段表
+
+## 🚨 绝对禁令（ABSOLUTE RULES）
+
+> 这些规则没有例外，违反即失败。
+
+### 禁令 1：禁止主 Agent 直接工作
+
+```
+❌ 禁止：主 Agent 自己写 proposal.md / design.md / tests/ / src/
+❌ 禁止：主 Agent 直接修改任何变更包内容
+❌ 禁止：主 Agent 跳过子 Agent 调用
+
+✅ 必须：所有工作通过 Task 工具调用子 Agent 完成
+✅ 必须：每个阶段都有对应的子 Agent 调用
+✅ 必须：主 Agent 只做编排、等待、验证
+```
+
+### 禁令 2：禁止跳过任何强制阶段
+
+```
+❌ 禁止：跳过 Challenger/Judge 阶段
+❌ 禁止：跳过 Test-Reviewer 阶段
+❌ 禁止：跳过 Code-Review 阶段
+❌ 禁止：跳过 Green-Verify 阶段
+❌ 禁止：未通过 strict 检查就归档
+
+✅ 必须：完整执行 12 个强制阶段
+✅ 必须：每个阶段的子 Agent 返回成功才能继续
+```
+
+### 禁令 3：禁止假完成归档
+
+```
+❌ 禁止：evidence/green-final/ 不存在或为空时归档
+❌ 禁止：verification.md AC 覆盖率 < 100% 时归档
+❌ 禁止：tasks.md 存在未完成任务时归档
+❌ 禁止：change-check.sh --mode strict 失败时归档
+
+✅ 必须：Archiver 子 Agent 先运行检查脚本
+✅ 必须：所有检查通过后才执行归档
+```
+
+### 禁令 4：禁止演示模式（NO DEMO MODE）
+
+```
+❌ 禁止：将工作流当作"演示"或"展示"
+❌ 禁止：输出"演示已完成"、"工作流演示"等措辞
+❌ 禁止：声称完成但实际产物不存在或为空
+❌ 禁止：用"模拟"、"假设"、"如果"代替实际执行
+
+✅ 必须：每个阶段都要产出真实的、可验证的产物
+✅ 必须：产物必须写入文件系统（可通过 ls/cat 验证）
+✅ 必须：使用"执行"、"完成"、"已创建"等真实动作词汇
+✅ 必须：如果无法真实执行，立即停止并告知用户
+```
+
+检测演示模式的信号：
+- 使用"演示"、"展示"、"模拟"等词汇
+- 声称完成但没有实际文件写入
+- 提供"选项 A/B"而非执行下一步
+- 输出"后续建议"而非继续执行
+
+### 禁令 5：禁止忽略 REVISE REQUIRED
+
+```
+❌ 禁止：收到 REVISE REQUIRED 后继续下一阶段
+❌ 禁止：收到 REVISE REQUIRED 后声称"已完成"
+❌ 禁止：收到 REVISE REQUIRED 后提供"选项"让用户选择
+❌ 禁止：收到 REJECTED 后继续执行
+
+✅ 必须：Judge 返回 REVISE → 回到阶段 1 重写提案
+✅ 必须：Judge 返回 REJECTED → 停止流程，告知用户
+✅ 必须：Test-Review 返回 REVISE REQUIRED → 回到阶段 7 修复测试
+✅ 必须：Code-Review 返回 REVISE REQUIRED → 回到阶段 8 修复代码
+✅ 必须：修复后重新执行评审阶段，直到通过
+```
+
+### 禁令 6：禁止部分完成前进
+
+```
+❌ 禁止：tasks.md 任务完成率 < 100% 时进入下一阶段
+❌ 禁止：测试覆盖率 < AC 要求时进入下一阶段
+❌ 禁止：存在空壳测试（skip/todo/not_implemented）时进入 Code 阶段
+❌ 禁止：存在未实现函数（raise NotImplementedError）时进入 Review 阶段
+
+✅ 必须：阶段 7 完成时，所有测试必须是真实的、可执行的
+✅ 必须：阶段 8 完成时，tasks.md 所有任务 100% 完成
+✅ 必须：如果发现范围过大，必须拆分变更包，不能部分完成
+```
+
+---
+
+## 前置：配置发现
+
+执行前必须按以下顺序查找配置：
+1. `.devbooks/config.yaml`（如存在）→ 解析并使用其中的映射
+2. `dev-playbooks/project.md`（如存在）→ Dev-Playbooks 协议
+3. `project.md`（如存在）→ template 协议
+4. 若仍无法确定 → 停止并询问用户
+
+---
+
+## 完整闭环流程（12 个强制阶段）
+
+```
+┌──────────────────────────────────────────────────────────────────────────┐
+│                         强制流程（无可选阶段）                              │
+├──────────────────────────────────────────────────────────────────────────┤
+│                                                                          │
+│  ┌─────────┐   ┌───────────┐   ┌─────────┐   ┌─────────┐                │
+│  │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-reviewer | 代码评审意见 | ✅ |
+| 11 | Green-Verify | `devbooks-test-owner` | devbooks-test-owner | evidence/green-final/ | ✅ |
+| 12 | Archive | `devbooks-archiver` | devbooks-archiver | 归档到 archive/ | ✅ |
+
+---
+
+## 上下文感知
+
+### 检测流程
+
+1. 检测变更包是否存在
+2. 检测当前阶段（哪些阶段已完成）
+3. 从断点继续执行
+
+### 断点续跑
+
+若变更包已存在部分产物，从最近完成的阶段继续：
+
+```
+检测结果：
+- 变更包：存在
+- 已完成阶段：1-6（proposal, challenge, judge, design, spec, plan）
+- 下一阶段：7（Test-Red）
+- 运行模式：断点续跑
+```
+
+---
+
+## 可选检查脚本
+
+脚本位于本 Skill 的 `scripts/` 目录：
+
+- 初始化变更包骨架：`change-scaffold.sh`
+- 一键校验变更包：`change-check.sh`
+- 结构守门决策校验：`guardrail-check.sh`
+- 证据采集：`change-evidence.sh`
+- 进度仪表板：`progress-dashboard.sh`

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

@@ -12,6 +12,25 @@ allowed-tools:
 
 # DevBooks：设计文档（Design Doc）
 
+## 渐进披露
+### 基础层（必读）
+目标：明确本 Skill 的核心产出与使用范围。
+输入：用户目标、现有文档、变更包上下文或项目路径。
+输出：可执行产物、下一步指引或记录路径。
+边界：不替代其他角色职责，不触碰 tests/。
+证据：引用产出物路径或执行记录。
+
+### 进阶层（可选）
+适用：需要细化策略、边界或风险提示时补充。
+
+### 扩展层（可选）
+适用：需要与外部系统或可选工具协同时补充。
+
+## 推荐 MCP 能力类型
+- 代码检索（code-search）
+- 引用追踪（reference-tracking）
+- 影响分析（impact-analysis）
+
 ## 工作流位置感知（Workflow Position Awareness）
 
 > **核心原则**：Design Doc 在 Proposal 批准后执行，是实现阶段的起点。
@@ -251,7 +270,3 @@ design-doc → [spec-contract] → implementation-plan → test-owner → coder
 ## 方法论参考
 
 - 完备性思维框架：[完备性思维框架](../_shared/references/完备性思维框架.md)
-
-## MCP 说明
-
-本 Skill 不依赖 MCP 服务，无需运行时检测。

package/skills/devbooks-docs-consistency/SKILL.md

@@ -13,6 +13,25 @@ allowed-tools:
 
 # DevBooks：文档一致性（Docs Consistency）
 
+## 渐进披露
+### 基础层（必读）
+目标：明确本 Skill 的核心产出与使用范围。
+输入：用户目标、现有文档、变更包上下文或项目路径。
+输出：可执行产物、下一步指引或记录路径。
+边界：不替代其他角色职责，不触碰 tests/。
+证据：引用产出物路径或执行记录。
+
+### 进阶层（可选）
+适用：需要细化策略、边界或风险提示时补充。
+
+### 扩展层（可选）
+适用：需要与外部系统或可选工具协同时补充。
+
+## 推荐 MCP 能力类型
+- 代码检索（code-search）
+- 引用追踪（reference-tracking）
+- 影响分析（impact-analysis）
+
 ## 前置：配置发现（协议无关）
 
 执行前**必须**按以下顺序查找配置（找到后停止）：
@@ -135,12 +154,6 @@ bash scripts/completeness-checker.sh --input README.md --config references/compl
 
 ---
 
-## MCP 说明
-
-本 Skill 不依赖 MCP 服务，无需运行时检测。
-
----
-
 ## 元数据
 
 | 字段 | 值 |

package/skills/devbooks-entropy-monitor/SKILL.md

@@ -11,6 +11,25 @@ allowed-tools:
 
 # DevBooks：系统熵度量与预警（Entropy Monitor）
 
+## 渐进披露
+### 基础层（必读）
+目标：明确本 Skill 的核心产出与使用范围。
+输入：用户目标、现有文档、变更包上下文或项目路径。
+输出：可执行产物、下一步指引或记录路径。
+边界：不替代其他角色职责，不触碰 tests/。
+证据：引用产出物路径或执行记录。
+
+### 进阶层（可选）
+适用：需要细化策略、边界或风险提示时补充。
+
+### 扩展层（可选）
+适用：需要与外部系统或可选工具协同时补充。
+
+## 推荐 MCP 能力类型
+- 代码检索（code-search）
+- 引用追踪（reference-tracking）
+- 影响分析（impact-analysis）
+
 > 来源：《人月神话》第16章"没有银弹" — "软件实体的复杂性是根本属性...控制复杂性是软件开发的关键"
 
 ## 前置：配置发现（协议无关）
@@ -148,9 +167,3 @@ allowed-tools:
 - 超阈值指标：2 个（圈复杂度 P95、热点文件占比）
 - 运行模式：增量采集 + 预警模式
 ```
-
----
-
-## MCP 说明
-
-本 Skill 不依赖 MCP 服务，无需运行时检测。

package/skills/devbooks-impact-analysis/SKILL.md

@@ -11,6 +11,25 @@ allowed-tools:
 
 # DevBooks：影响分析（Impact Analysis）
 
+## 渐进披露
+### 基础层（必读）
+目标：明确本 Skill 的核心产出与使用范围。
+输入：用户目标、现有文档、变更包上下文或项目路径。
+输出：可执行产物、下一步指引或记录路径。
+边界：不替代其他角色职责，不触碰 tests/。
+证据：引用产出物路径或执行记录。
+
+### 进阶层（可选）
+适用：需要细化策略、边界或风险提示时补充。
+
+### 扩展层（可选）
+适用：需要与外部系统或可选工具协同时补充。
+
+## 推荐 MCP 能力类型
+- 代码检索（code-search）
+- 引用追踪（reference-tracking）
+- 影响分析（impact-analysis）
+
 ## 前置：配置发现（协议无关）
 
 - `<truth-root>`：当前真理目录根
@@ -55,7 +74,7 @@ allowed-tools:
 ```
 用户：分析一下修改 UserService 的影响
 
-AI：[使用 Grep/CKB 分析引用]
+AI：[使用代码检索/引用追踪分析]
     [使用 Edit 工具写入 proposal.md]
 
     影响分析已写入 `changes/refactor-user/proposal.md` 的 Impact 部分。
@@ -108,7 +127,7 @@ AI：[使用 Grep/CKB 分析引用]
 
 1. 检测变更包是否存在
 2. 检测 `proposal.md` 中是否已有 Impact 章节
-3. 检测是否有 CKB 索引可用（增强分析能力）
+3. 检测是否有结构化引用追踪能力可用（用于更精确分析）
 
 ### 本 Skill 支持的模式
 
@@ -116,20 +135,14 @@ AI：[使用 Grep/CKB 分析引用]
 |------|----------|------|
 | **新建分析** | Impact 章节不存在 | 执行完整影响分析 |
 | **增量分析** | Impact 已存在，有新变更 | 更新受影响文件列表 |
-| **增强分析** | CKB 索引可用 | 使用调用图进行精确分析 |
-| **基础分析** | CKB 索引不可用 | 使用 Grep 文本搜索分析 |
+| **结构化分析** | 结构化引用追踪可用 | 使用调用关系进行精确分析 |
+| **文本分析** | 仅文本检索可用 | 使用 Grep 文本搜索分析 |
 
 ### 检测输出示例
 
 ```
 检测结果：
 - proposal.md：存在，Impact 章节缺失
-- CKB 索引：可用
-- 运行模式：新建分析 + 增强模式
+- 引用追踪能力：可用
+- 运行模式：新建分析 + 结构化分析
 ```
-
----
-
-## MCP 说明
-
-本 Skill 不依赖 MCP 服务，无需运行时检测。

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

@@ -12,6 +12,25 @@ allowed-tools:
 
 # DevBooks：编码计划（Implementation Plan）
 
+## 渐进披露
+### 基础层（必读）
+目标：明确本 Skill 的核心产出与使用范围。
+输入：用户目标、现有文档、变更包上下文或项目路径。
+输出：可执行产物、下一步指引或记录路径。
+边界：不替代其他角色职责，不触碰 tests/。
+证据：引用产出物路径或执行记录。
+
+### 进阶层（可选）
+适用：需要细化策略、边界或风险提示时补充。
+
+### 扩展层（可选）
+适用：需要与外部系统或可选工具协同时补充。
+
+## 推荐 MCP 能力类型
+- 代码检索（code-search）
+- 引用追踪（reference-tracking）
+- 影响分析（impact-analysis）
+
 ## 工作流位置感知（Workflow Position Awareness）
 
 > **核心原则**：Implementation Plan 在 Design Doc 之后执行，为 Test Owner 和 Coder 提供任务清单。
@@ -151,9 +170,3 @@ implementation-plan → test-owner (会话A) → coder (会话B)
 运行 devbooks-coder skill 处理变更 <change-id>
 ```
 ```
-
----
-
-## MCP 说明
-
-本 Skill 不依赖 MCP 服务，无需运行时检测。

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

@@ -12,6 +12,25 @@ allowed-tools:
 
 # DevBooks：提案撰写（Proposal Author）
 
+## 渐进披露
+### 基础层（必读）
+目标：明确本 Skill 的核心产出与使用范围。
+输入：用户目标、现有文档、变更包上下文或项目路径。
+输出：可执行产物、下一步指引或记录路径。
+边界：不替代其他角色职责，不触碰 tests/。
+证据：引用产出物路径或执行记录。
+
+### 进阶层（可选）
+适用：需要细化策略、边界或风险提示时补充。
+
+### 扩展层（可选）
+适用：需要与外部系统或可选工具协同时补充。
+
+## 推荐 MCP 能力类型
+- 代码检索（code-search）
+- 引用追踪（reference-tracking）
+- 影响分析（impact-analysis）
+
 ## 前置：配置发现（协议无关）
 
 - `<truth-root>`：当前真理目录根
@@ -181,7 +200,3 @@ proposal-author → [impact-analysis] → design-doc → [spec-contract] → imp
 在完成提案草案后，执行 Challenger 审视，重点检查遗漏的约束与不确定性，并参考完备性方法论。
 
 - 方法论参考：[完备性思维框架](../_shared/references/完备性思维框架.md)
-
-## MCP 说明
-
-本 Skill 不依赖 MCP 服务，无需运行时检测。

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

@@ -10,6 +10,25 @@ allowed-tools:
 
 # DevBooks：提案质疑 + 查漏补缺（Proposal Challenger）
 
+## 渐进披露
+### 基础层（必读）
+目标：明确本 Skill 的核心产出与使用范围。
+输入：用户目标、现有文档、变更包上下文或项目路径。
+输出：可执行产物、下一步指引或记录路径。
+边界：不替代其他角色职责，不触碰 tests/。
+证据：引用产出物路径或执行记录。
+
+### 进阶层（可选）
+适用：需要细化策略、边界或风险提示时补充。
+
+### 扩展层（可选）
+适用：需要与外部系统或可选工具协同时补充。
+
+## 推荐 MCP 能力类型
+- 代码检索（code-search）
+- 引用追踪（reference-tracking）
+- 影响分析（impact-analysis）
+
 ## 前置：配置发现（协议无关）
 
 - `<truth-root>`：当前真理目录根
@@ -76,9 +95,3 @@ allowed-tools:
 - 质疑历史：无
 - 运行模式：首次质疑
 ```
-
----
-
-## MCP 说明
-
-本 Skill 不依赖 MCP 服务，无需运行时检测。

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

@@ -12,6 +12,25 @@ allowed-tools:
 
 # DevBooks：提案裁决（Proposal Judge）
 
+## 渐进披露
+### 基础层（必读）
+目标：明确本 Skill 的核心产出与使用范围。
+输入：用户目标、现有文档、变更包上下文或项目路径。
+输出：可执行产物、下一步指引或记录路径。
+边界：不替代其他角色职责，不触碰 tests/。
+证据：引用产出物路径或执行记录。
+
+### 进阶层（可选）
+适用：需要细化策略、边界或风险提示时补充。
+
+### 扩展层（可选）
+适用：需要与外部系统或可选工具协同时补充。
+
+## 推荐 MCP 能力类型
+- 代码检索（code-search）
+- 引用追踪（reference-tracking）
+- 影响分析（impact-analysis）
+
 ## 前置：配置发现（协议无关）
 
 - `<truth-root>`：当前真理目录根
@@ -68,9 +87,3 @@ allowed-tools:
 - 角色隔离：✓
 - 运行模式：首次裁决
 ```
-
----
-
-## MCP 说明
-
-本 Skill 不依赖 MCP 服务，无需运行时检测。

package/skills/devbooks-reviewer/SKILL.md

@@ -11,6 +11,25 @@ allowed-tools:
 
 # DevBooks：代码评审（Reviewer）
 
+## 渐进披露
+### 基础层（必读）
+目标：明确本 Skill 的核心产出与使用范围。
+输入：用户目标、现有文档、变更包上下文或项目路径。
+输出：可执行产物、下一步指引或记录路径。
+边界：不替代其他角色职责，不触碰 tests/。
+证据：引用产出物路径或执行记录。
+
+### 进阶层（可选）
+适用：需要细化策略、边界或风险提示时补充。
+
+### 扩展层（可选）
+适用：需要与外部系统或可选工具协同时补充。
+
+## 推荐 MCP 能力类型
+- 代码检索（code-search）
+- 引用追踪（reference-tracking）
+- 影响分析（impact-analysis）
+
 ## 工作流位置感知（Workflow Position Awareness）
 
 > **核心原则**：Code Review 在 Test Owner 阶段 2 验证之后执行，是归档前的最后一个评审步骤。
@@ -143,7 +162,7 @@ override dispose() {
 
 1. 检测变更包是否存在
 2. 检测是否有代码变更（git diff）
-3. 检测热点文件（通过 CKB getHotspots）
+3. 检测热点文件（基于变更历史与复杂度分析）
 
 ### 本 Skill 支持的模式
 
@@ -204,9 +223,3 @@ Review 通过后，Reviewer 必须执行：
 运行 devbooks-archiver skill 处理变更 <change-id>
 ```
 ```
-
----
-
-## MCP 说明
-
-本 Skill 不依赖 MCP 服务，无需运行时检测。