dev-playbooks-cn 2.5.3 → 2.6.0

package/skills/devbooks-archiver/references//345/275/222/346/241/243/346/265/201/347/250/213/344/270/216/350/247/204/345/210/231.md

@@ -0,0 +1,401 @@
+# 归档流程与规则
+
+## 🚨 绝对禁令（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 是归档阶段的唯一入口，负责完成从代码评审到变更包归档的所有收尾工作。
+
+### 我在整体工作流中的位置
+
+```
+proposal → design → test-owner(P1) → coder → test-owner(P2) → code-review → [Archiver]
+                                                                                  ↓
+                                               自动回写 → 规格合并 → 文档检查 → 移动归档
+```
+
+### 为什么重命名为 Archiver？
+
+| 旧名称 | 新名称 | 变更原因 |
+|--------|--------|----------|
+| `spec-gardener` | `archiver` | 职责已扩展，不仅是规格合并，而是完整的归档闭环 |
+
+### Archiver 的完整职责
+
+| 阶段 | 职责 | 说明 |
+|------|------|------|
+| 1 | 设计回写（Design Backport） | 检测实现过程中的新约束/冲突/缺口，回写到 design.md |
+| 2 | 规格合并 | 将 specs/contracts 合并到 truth-root |
+| 3 | 架构合并 | 将 design.md 的 Architecture Impact 合并到 c4.md |
+| 4 | 文档同步检查 | 检查 design.md 的 Documentation Impact 是否已处理 |
+| 5 | 变更包归档移动 | 将变更包移动到 `<change-root>/archive/` |
+
+注意：Archiver 现在承担了原 `devbooks-design-backport` skill 的职责，作为归档闭环的一部分自动执行。
+
+---
+
+## 前置：配置发现（协议无关）
+
+- `<truth-root>`：当前真理目录根
+- `<change-root>`：变更包目录根
+
+执行前必须按以下顺序查找配置（找到后停止）：
+1. `.devbooks/config.yaml`（如存在）→ 解析并使用其中的映射
+2. `dev-playbooks/project.md`（如存在）→ Dev-Playbooks 协议，使用默认映射
+3. `project.md`（如存在）→ template 协议，使用默认映射
+4. 若仍无法确定 → 停止并询问用户
+
+关键约束：
+- 如果配置中指定了 `agents_doc`（规则文档），必须先阅读该文档再执行任何操作
+- 禁止猜测目录根
+- 禁止跳过规则文档阅读
+
+---
+
+## 归档完整流程
+
+### 第 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/ 存在且非空
+- [ ] tasks.md 所有任务已完成（[x]）
+- [ ] 代码评审已通过（verification.md Status = Done 由 Reviewer 设置）
+```
+
+若检查失败 → 停止并输出缺失项，建议用户先完成前置步骤。
+
+### 第 2 步：自动回写检测与处理
+
+> 设计决策：归档阶段自动处理所有未回写的偏离，用户无需手动调用 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 切分、任务执行顺序 |
+| 核心数据契约与演进策略 | 过细的算法伪代码 |
+| 跨阶段治理策略 | 脚本命令 |
+| 关键取舍与决策 | 表名/字段名 |
+
+### 第 3 步：规格合并
+
+将变更包中的规格产物合并到 `<truth-root>`：
+
+| 源路径 | 目标路径 | 合并策略 |
+|--------|----------|----------|
+| `<change-root>/<change-id>/specs/**` | `<truth-root>/specs/**` | 增量合并 |
+| `<change-root>/<change-id>/contracts/**` | `<truth-root>/contracts/**` | 版本化合并 |
+
+Spec 元信息更新（合并时必须执行）：
+
+```yaml
+---
+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 在归档时合并到真理。
+
+C4 合并流程：
+
+1. 检测架构变更：解析 `design.md` 中的 "Architecture Impact" 章节
+2. 判断是否需要合并：
+   - 若 "无架构变更" 被勾选 → 跳过合并
+   - 若 "有架构变更" → 执行合并
+3. 执行合并：
+   - 读取 `<truth-root>/architecture/c4.md`（若不存在则创建）
+   - 根据 Architecture Impact 中的变更描述更新对应章节
+   - 更新 Container/Component 表格
+   - 更新依赖关系
+   - 更新分层约束（如有变更）
+4. 记录合并日志：在 c4.md 末尾添加变更记录
+
+### 第 5 步：文档一致性检查
+
+在归档前运行文档一致性检查：
+
+```
+devbooks-docs-consistency --check
+```
+
+检查结果仅记录与提示，不阻塞归档。
+
+### 第 6 步：文档同步检查
+
+检查 design.md 的 "Documentation Impact" 章节：
+
+```markdown
+检查项：
+- [ ] 若声明了"需要更新的文档"，验证这些文档已更新
+- [ ] 若勾选了"无需更新"，确认合理性
+- [ ] 输出文档同步状态报告
+```
+
+若有未处理的文档更新：
+- 输出警告，列出需要更新的文档
+- 不阻塞归档，但在归档报告中标记为 "文档待更新"
+
+### 第 7 步：变更包归档移动
+
+将已完成的变更包移动到归档目录：
+
+```bash
+# 源路径
+<change-root>/<change-id>/
+
+# 目标路径
+<change-root>/archive/<change-id>/
+```
+
+移动流程：
+
+1. 创建归档目录（如不存在）：`<change-root>/archive/`
+2. 设置最终状态：在 verification.md 中设置 `Status: Archived`
+3. 添加归档时间戳：在 verification.md 末尾添加 `Archived-At: <timestamp>`
+4. 移动变更包：`mv <change-root>/<change-id>/ <change-root>/archive/<change-id>/`
+5. 输出归档完成报告
+
+verification.md 归档状态更新示例：
+
+```markdown
+---
+status: Archived
+archived-at: 2024-01-16T10:30:00Z
+archived-by: devbooks-archiver
+---
+```
+
+---
+
+## 执行方式
+
+1) 先阅读并遵守：`~/.claude/skills/_shared/references/AI行为规范.md`（可验证性 + 结构质量守门）。
+2) 严格按完整提示词执行：`references/归档器提示词.md`。
+
+---
+
+## 上下文感知
+
+本 Skill 在执行前自动检测上下文，选择合适的运行模式。
+
+检测规则参考：`skills/_shared/上下文检测模板.md`
+
+### 检测流程
+
+1. 检测 `<truth-root>/` 目录状态
+2. 若提供 change-id，检测变更包归档条件
+3. 检测重复/过时规格（维护模式）
+
+### 本 Skill 支持的模式
+
+| 模式 | 触发条件 | 行为 |
+|------|----------|------|
+| 归档模式 | 提供 change-id 且闸门通过 | 执行完整归档流程（7步：0-6） |
+| 维护模式 | 无 change-id | 执行 truth-root 去重、清理、整理 |
+| 检查模式 | 带 --dry-run 参数 | 只输出计划，不实际修改/移动 |
+
+### 归档模式完整流程图
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      归档模式流程                            │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  0. 运行强制验证脚本（MANDATORY）                             │
+│     └─ change-check.sh <change-id> --mode strict           │
+│              │                                               │
+│              ├─ 返回非零 → ❌ 停止，输出错误                  │
+│              │                                               │
+│              ▼ 返回 0                                        │
+│  1. 前置检查（二次确认）                                      │
+│     ├─ 变更包存在？                                          │
+│     ├─ verification.md Status = Ready/Done？                │
+│     ├─ evidence/green-final/ 存在？                          │
+│     └─ tasks.md 全部完成？                                   │
+│              │                                               │
+│              ▼                                               │
+│  2. 自动回写                                                 │
+│     ├─ 读取 deviation-log.md                                │
+│     ├─ 检测未回写记录                                        │
+│     └─ 执行回写 → 更新标记                                   │
+│              │                                               │
+│              ▼                                               │
+│  3. 规格合并                                                 │
+│     ├─ specs/** → truth-root/specs/**                       │
+│     └─ contracts/** → truth-root/contracts/**               │
+│              │                                               │
+│              ▼                                               │
+│  4. 架构合并                                                 │
+│     └─ Architecture Impact → c4.md                          │
+│              │                                               │
+│              ▼                                               │
+│  5. 文档同步检查                                             │
+│     └─ 检查 Documentation Impact 是否已处理                  │
+│              │                                               │
+│              ▼                                               │
+│  6. 变更包归档移动                                           │
+│     ├─ 设置 Status: Archived                                │
+│     └─ mv <change-id>/ → archive/<change-id>/               │
+│              │                                               │
+│              ▼                                               │
+│  ✅ 输出归档完成报告                                         │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 检测输出示例
+
+```
+检测结果：
+- truth-root：存在，包含 12 个 spec 文件
+- 变更包：存在，闸门全绿
+- 回写状态：2 条待回写记录
+- 运行模式：归档模式（完整流程）
+```
+
+---
+
+## 归档报告模板
+
+```markdown
+## 归档报告
+
+### 变更包信息
+- Change ID: <change-id>
+- 归档时间: <timestamp>
+
+### 执行摘要
+| 步骤 | 状态 | 说明 |
+|------|------|------|
+| 前置检查 | ✅ | 全部通过 |
+| 自动回写 | ✅ | 回写 2 条记录 |
+| 规格合并 | ✅ | 合并 3 个 spec 文件 |
+| 架构合并 | ⏭️ | 无架构变更 |
+| 文档检查 | ⚠️ | README.md 待更新 |
+| 归档移动 | ✅ | 已移动到 archive/ |
+
+### 归档位置
+`<change-root>/archive/<change-id>/`
+
+### 后续建议
+- [ ] 更新 README.md（文档检查警告）
+```
+
+---
+
+## 维护模式职责
+
+在维护模式下（无 change-id）执行：
+
+- 检测重复的规格定义
+- 清理过时/废弃的规格
+- 整理目录结构
+- 修复一致性问题

package/skills/devbooks-brownfield-bootstrap/SKILL.md

@@ -13,6 +13,25 @@ allowed-tools:
 
 # DevBooks：存量项目初始化（Brownfield Bootstrap）
 
+## 渐进披露
+### 基础层（必读）
+目标：明确本 Skill 的核心产出与使用范围。
+输入：用户目标、现有文档、变更包上下文或项目路径。
+输出：可执行产物、下一步指引或记录路径。
+边界：不替代其他角色职责，不触碰 tests/。
+证据：引用产出物路径或执行记录。
+
+### 进阶层（可选）
+适用：需要细化策略、边界或风险提示时补充。
+
+### 扩展层（可选）
+适用：需要与外部系统或可选工具协同时补充。
+
+## 推荐 MCP 能力类型
+- 代码检索（code-search）
+- 引用追踪（reference-tracking）
+- 影响分析（impact-analysis）
+
 ## 前置：配置发现（协议无关）
 
 - `<truth-root>`：当前真理目录根
@@ -63,7 +82,7 @@ allowed-tools:
 | 项目画像 | `_meta/project-profile.md` | 三层架构的详细技术画像 |
 | 术语表 | `_meta/glossary.md` | 统一语言表（可选但推荐） |
 | 文档维护元数据 | `_meta/docs-maintenance.md` | 文档风格与维护配置 |
-| 领域概念 | `_meta/key-concepts.md` | CKB 提取的概念（增强模式） |
+| 领域概念 | `_meta/key-concepts.md` | 基于代码语义的概念提取（可选） |
 
 ### 3. 架构分析产物
 
@@ -71,9 +90,9 @@ allowed-tools:
 
 | 产物 | 路径 | 数据来源 |
 |------|------|----------|
-| **C4 架构地图** | `architecture/c4.md` | 综合分析 + CKB（增强模式） |
-| 模块依赖图 | `architecture/module-graph.md` | `mcp__ckb__getArchitecture` |
-| 技术债热点 | `architecture/hotspots.md` | `mcp__ckb__getHotspots` |
+| **C4 架构地图** | `architecture/c4.md` | 综合分析（可选结合结构化能力） |
+| 模块依赖图 | `architecture/module-graph.md` | 结构化依赖分析（可选） |
+| 技术债热点 | `architecture/hotspots.md` | 变更历史 + 复杂度分析（可选） |
 | 分层约束 | `architecture/layering-constraints.md` | 代码分析（可选） |
 
 > **设计决策**：C4 架构地图现在由 brownfield-bootstrap 在初始化时生成，后续架构变更通过 design.md 的 Architecture Impact 章节记录，由 archiver 在归档时合并。
@@ -93,16 +112,16 @@ allowed-tools:
 
 ## COD 模型生成（Code Overview & Dependencies）
 
-在初始化时自动生成项目的"代码地图"（需要 CKB MCP Server 可用，否则跳过）：
+在初始化时可选生成项目的“代码地图”（取决于可用的结构化代码分析能力）：
 
 ### 自动生成产物
 
 | 产物 | 路径 | 数据来源 |
 |------|------|----------|
 | **C4 架构地图** | `<truth-root>/architecture/c4.md` | 综合分析 |
-| 模块依赖图 | `<truth-root>/architecture/module-graph.md` | `mcp__ckb__getArchitecture` |
-| 技术债热点 | `<truth-root>/architecture/hotspots.md` | `mcp__ckb__getHotspots` |
-| 领域概念 | `<truth-root>/_meta/key-concepts.md` | `mcp__ckb__listKeyConcepts` |
+| 模块依赖图 | `<truth-root>/architecture/module-graph.md` | 结构化依赖分析（可选） |
+| 技术债热点 | `<truth-root>/architecture/hotspots.md` | 变更历史 + 复杂度分析（可选） |
+| 领域概念 | `<truth-root>/_meta/key-concepts.md` | 代码语义概念提取（可选） |
 | 项目画像 | `<truth-root>/_meta/project-profile.md` | 综合分析 |
 
 ### C4 架构地图生成规则
@@ -164,22 +183,8 @@ allowed-tools:
 
 ### 执行流程
 
-1) **检查图索引**：调用 `mcp__ckb__getStatus`
-   - 若 SCIP 可用 → 使用图基分析
-   - 若不可用 → 提示生成索引或使用 Git 历史分析
-
-2) **生成 COD 产物**：
-   ```bash
-   # 获取模块架构
-   mcp__ckb__getArchitecture(depth=2, includeExternalDeps=false)
-
-   # 获取热点（近 30 天）
-   mcp__ckb__getHotspots(limit=20)
-
-   # 获取领域概念
-   mcp__ckb__listKeyConcepts(limit=12)
-   ```
-
+1) **检查可用能力**：确认是否具备结构化代码分析能力（如依赖关系或引用追踪）。
+2) **生成 COD 产物**：基于可用的代码检索、引用追踪与变更历史分析生成模块依赖、热点与概念。
 3) **生成项目画像**：整合以上数据 + 传统分析
 
 ## 参考骨架与模板
@@ -203,7 +208,7 @@ allowed-tools:
 1. 检测 `<devbooks-root>/constitution.md` 是否存在
 2. 检测 `<devbooks-root>/project.md` 是否存在
 3. 检测 `<truth-root>/` 是否为空或基本为空
-4. 检测 CKB 索引是否可用
+4. 检测结构化代码分析能力是否可用
 5. 检测项目规模和语言栈
 
 ### 本 Skill 支持的模式
@@ -214,8 +219,8 @@ allowed-tools:
 | **补充配置** | constitution/project 缺失 | 只补充缺失的配置文件 |
 | **完整初始化** | truth-root 为空 | 生成所有基础产物（画像/基线/验证） |
 | **增量初始化** | truth-root 部分存在 | 只补充缺失产物 |
-| **增强模式** | CKB 索引可用 | 使用图分析生成更精确的画像 |
-| **基础模式** | CKB 索引不可用 | 使用传统分析方法 |
+| **结构化分析** | 结构化能力可用 | 使用依赖关系与引用追踪增强画像 |
+| **文本分析** | 仅文本检索可用 | 使用传统分析方法 |
 
 ### 检测输出示例
 
@@ -225,13 +230,7 @@ allowed-tools:
 - constitution.md：不存在 → 将创建
 - project.md：不存在 → 将创建
 - truth-root：为空
-- CKB 索引：可用
+- 结构化能力：可用
 - 项目规模：中型（~50K LOC）
-- 运行模式：补充配置 + 完整初始化 + 增强模式
+- 运行模式：补充配置 + 完整初始化 + 结构化分析
 ```
-
----
-
-## MCP 说明
-
-本 Skill 不依赖 MCP 服务，无需运行时检测。

package/skills/devbooks-brownfield-bootstrap/scripts/cod-update.sh

@@ -181,8 +181,6 @@ EOF
 
     echo "" >> "$temp_file"
     echo "---" >> "$temp_file"
-    echo "" >> "$temp_file"
-    echo "> 提示：手动生成 SCIP 索引以获得更精确的依赖分析（参考 docs/推荐MCP.md）" >> "$temp_file"
 
     # 只在内容变化时更新
     if [ -f "$output" ]; then

package/skills/devbooks-coder/SKILL.md

@@ -13,30 +13,37 @@ allowed-tools:
 
 # DevBooks：实现负责人（Coder）
 
+## 渐进披露
+### 基础层（必读）
+目标：明确本 Skill 的核心产出与使用范围。
+输入：用户目标、现有文档、变更包上下文或项目路径。
+输出：可执行产物、下一步指引或记录路径。
+边界：不替代其他角色职责，不触碰 tests/。
+证据：引用产出物路径或执行记录。
+
+### 进阶层（可选）
+适用：需要细化策略、边界或风险提示时补充。
+
+### 扩展层（可选）
+适用：需要与外部系统或可选工具协同时补充。
+
+## 推荐 MCP 能力类型
+- 代码检索（code-search）
+- 引用追踪（reference-tracking）
+- 影响分析（impact-analysis）
+
 ## 快速开始
 
 我的职责：
 1. **严格按 tasks.md 实现功能**
-2. **运行快轨测试**（@smoke + @critical）
-3. **触发 @full 测试**（CI 异步）
-4. **禁止修改 tests/**
-
-## 工作流位置
-
-```
-proposal → design → [TEST-OWNER] → [CODER] → [TEST-OWNER] → code-review → archive
-                                      ↓              ↓
-                               实现+快轨测试    证据审计+打勾
-                              (@smoke/@critical)  (不重跑@full)
-```
+2. **运行验证计划中的验收锚点**（tests/、静态检查、构建等）
+3. **保存 Green 证据**到变更包 `evidence/green-final/`
+4. **禁止修改 tests/**（如需改测试交还 Test Owner）
 
-## AI 时代优化
+## 角色隔离（强制）
 
-| 旧设计 | 新设计 | 原因 |
-|--------|--------|------|
-| Test Owner 和 Coder 必须单独会话 | 同一会话，用 `[TEST-OWNER]` / `[CODER]` 模式标签切换 | 减少上下文重建成本 |
-| Coder 跑完整测试等待结果 | Coder 跑快轨（`@smoke`/`@critical`），`@full` 异步触发 | 快速迭代 |
-| 完成后直接交给 Test Owner | 完成后状态为 `Implementation Done`，等 @full 通过 | 异步不阻塞，归档同步 |
+- Coder 与 Test Owner 必须独立对话/独立实例。
+- 本 Skill 仅以 Coder 角色执行，不切换到其他角色。
 
 ---