dev-playbooks 1.0.13 → 1.0.14

package/README.md

@@ -178,7 +178,6 @@ Run devbooks-spec-gardener skill for change add-oauth2
 | devbooks-proposal-debate-workflow | Triangle debate (Author/Challenger/Judge) |
 | devbooks-design-doc | Create a design doc |
 | devbooks-spec-contract | Define specs & contracts |
-| devbooks-c4-map | Generate a C4 map |
 | devbooks-implementation-plan | Create an implementation plan |
 
 ### Apply stage

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dev-playbooks",
-  "version": "1.0.13",
+  "version": "1.0.14",
   "description": "AI-powered spec-driven development workflow",
   "keywords": [
     "devbooks",

package/skills/Skills-Usage-Guide.md

@@ -171,28 +171,6 @@ If you are not using DevBooks, replace `dev-playbooks/specs` / `dev-playbooks/ch
 
 ---
 
-## `devbooks-c4-map` (C4 Map Maintainer)
-
-- Purpose: maintain/update the authoritative C4 architecture map (truth) and produce a C4 Delta per change.
-- When to use:
-  - Proposal stage: describe boundary/dependency direction changes in `design.md` (C4 Delta only; do not modify current truth)
-  - Review/archive stage: change is implemented; update the authoritative map at `(<truth-root>/architecture/c4.md)`
-- Copy-paste prompts:
-  - Proposal stage (C4 Delta only; do not edit current truth):
-    ```text
-    You are C4 Map Maintainer. Explicitly use `devbooks-c4-map`, but during proposal stage do NOT modify `dev-playbooks/specs/architecture/c4.md` (current truth).
-    First read: `dev-playbooks/specs/architecture/c4.md` (if present) + `dev-playbooks/changes/<change-id>/proposal.md` + `dev-playbooks/changes/<change-id>/design.md`.
-    Output: a **C4 Delta** section that I can paste into `dev-playbooks/changes/<change-id>/design.md` (C1/C2/C3 add/modify/remove + dependency direction changes + suggested architecture guardrails/fitness tests).
-    ```
-  - Review/archive stage (update current truth map):
-    ```text
-    You are C4 Map Maintainer. Explicitly use `devbooks-c4-map`.
-    First read: `dev-playbooks/specs/architecture/c4.md` (if present) + `dev-playbooks/changes/<change-id>/design.md` + relevant code changes (to confirm the change is real).
-    Update (or create a minimal skeleton with TODOs): `dev-playbooks/specs/architecture/c4.md`.
-    ```
-
----
-
 ## `devbooks-implementation-plan` (Planner / tasks.md)
 
 - Purpose: derive an implementation plan `tasks.md` from `design.md` (critical path / side quests / checkpoints), tied to verification anchors (must not reference `tests/`).

package/skills/_shared/mcp-enhancement-template.md

@@ -91,7 +91,6 @@ The following Skills depend on MCP and require the full MCP Enhancement section:
 | devbooks-index-bootstrap | mcp__ckb__getStatus | Index status detection |
 | devbooks-federation | mcp__ckb__*, mcp__github__* | Cross-repo analysis |
 | devbooks-router | mcp__ckb__getStatus | Index availability detection |
-| devbooks-c4-map | mcp__ckb__getArchitecture | Module dependency graph |
 | devbooks-spec-contract | mcp__ckb__findReferences | Reference detection |
 | devbooks-entropy-monitor | mcp__ckb__getHotspots | Hotspot trend analysis |
 | devbooks-delivery-workflow | mcp__ckb__getStatus | Index detection |

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

@@ -1,6 +1,6 @@
 ---
 name: devbooks-brownfield-bootstrap
-description: devbooks-brownfield-bootstrap：存量项目初始化：在当前真理目录为空时生成项目画像、术语表、基线规格与最小验证锚点，避免"边补 specs 边改行为"。用户说"存量初始化/基线 specs/项目画像/建立 glossary/把老项目接入上下文协议"等时使用。
+description: "devbooks-brownfield-bootstrap: Brownfield project initialization. When the truth directory is empty, generate project profile, glossary, baseline specs, and minimum verification anchors to avoid 'patching specs while changing behavior'. Use when user says 'brownfield init/baseline specs/project profile/establish glossary/onboard legacy project to context protocol' etc."
 tools:
   - Glob
   - Grep
@@ -15,217 +15,262 @@ tools:
   - mcp__ckb__getModuleOverview
 ---
 
-# DevBooks：存量项目初始化（Brownfield Bootstrap）
+# DevBooks: Brownfield Bootstrap
 
-## 前置：配置发现（协议无关）
+## Prerequisites: Configuration Discovery (Protocol Agnostic)
 
-- `<truth-root>`：当前真理目录根
-- `<change-root>`：变更包目录根
-- `<devbooks-root>`：DevBooks 管理目录（通常是 `dev-playbooks/`）
+- `<truth-root>`: Current truth directory root
+- `<change-root>`: Change package directory root
+- `<devbooks-root>`: DevBooks management directory (usually `dev-playbooks/`)
 
-执行前**必须**按以下顺序查找配置（找到后停止）：
-1. `.devbooks/config.yaml`（如存在）→ 解析并使用其中的映射
-2. `dev-playbooks/project.md`（如存在）→ DevBooks 2.0 协议，使用默认映射
-4. `project.md`（如存在）→ template 协议，使用默认映射
-5. 若仍无法确定 → **创建 DevBooks 目录结构并初始化基础配置**
+Before execution, **must** search for configuration in the following order (stop when found):
+1. `.devbooks/config.yaml` (if exists) → Parse and use its mappings
+2. `dev-playbooks/project.md` (if exists) → DevBooks 2.0 protocol, use default mappings
+4. `project.md` (if exists) → Template protocol, use default mappings
+5. If still unable to determine → **Create DevBooks directory structure and initialize basic configuration**
 
-**关键约束**：
-- 如果配置中指定了 `agents_doc`（规则文档），**必须先阅读该文档**再执行任何操作
-- 禁止猜测目录根
-- 禁止跳过规则文档阅读
+**Key Constraints**:
+- If configuration specifies `agents_doc` (rules document), **must read that document first** before executing any operations
+- Do not guess directory roots
+- Do not skip reading rules document
 
 ---
 
-## 核心职责
+## Core Responsibilities
 
-存量项目初始化包含以下职责：
+Brownfield project initialization includes the following responsibilities:
 
-### 1. 基础配置文件初始化（新增）
+### 1. Basic Configuration File Initialization
 
-在 `<devbooks-root>/`（通常是 `dev-playbooks/`）下检查并创建：
+Check and create in `<devbooks-root>/` (usually `dev-playbooks/`):
 
-| 文件 | 用途 | 创建条件 |
-|------|------|----------|
-| `constitution.md` | 项目宪法（GIP 原则） | 文件不存在时 |
-| `project.md` | 项目上下文（技术栈/约定） | 文件不存在时 |
+| File | Purpose | Creation Condition |
+|------|---------|-------------------|
+| `constitution.md` | Project constitution (GIP principles) | When file doesn't exist |
+| `project.md` | Project context (tech stack/conventions) | When file doesn't exist |
 
-**创建方式**：
-- **不是简单复制模板**，而是根据代码分析结果定制内容
-- `constitution.md`：基于默认 GIP 原则，可根据项目特性调整
-- `project.md`：根据代码分析结果填充：
-  - 技术栈（语言/框架/数据库）
-  - 开发约定（代码风格/测试策略/Git 工作流）
-  - 领域上下文（核心概念/角色定义）
-  - 目录根映射
+**Creation Method**:
+- **Not simple template copying**, but customized content based on code analysis results
+- `constitution.md`: Based on default GIP principles, can be adjusted according to project characteristics
+- `project.md`: Filled based on code analysis results:
+  - Tech stack (language/framework/database)
+  - Development conventions (code style/testing strategy/Git workflow)
+  - Domain context (core concepts/role definitions)
+  - Directory root mappings
 
-### 2. 项目画像与元数据
+### 2. Project Profile and Metadata
 
-在 `<truth-root>/_meta/` 下生成：
+Generate in `<truth-root>/_meta/`:
 
-| 产物 | 路径 | 说明 |
-|------|------|------|
-| 项目画像 | `_meta/project-profile.md` | 三层架构的详细技术画像 |
-| 术语表 | `_meta/glossary.md` | 统一语言表（可选但推荐） |
-| 领域概念 | `_meta/key-concepts.md` | CKB 提取的概念（增强模式） |
+| Artifact | Path | Description |
+|----------|------|-------------|
+| Project profile | `_meta/project-profile.md` | Detailed technical profile with three-layer architecture |
+| Glossary | `_meta/glossary.md` | Unified language table (optional but recommended) |
+| Domain concepts | `_meta/key-concepts.md` | Concepts extracted by CKB (enhanced mode) |
 
-### 3. 架构分析产物
+### 3. Architecture Analysis Artifacts
 
-在 `<truth-root>/architecture/` 下生成：
+Generate in `<truth-root>/architecture/`:
 
-| 产物 | 路径 | 数据来源 |
-|------|------|----------|
-| 模块依赖图 | `architecture/module-graph.md` | `mcp__ckb__getArchitecture` |
-| 技术债热点 | `architecture/hotspots.md` | `mcp__ckb__getHotspots` |
+| Artifact | Path | Data Source |
+|----------|------|-------------|
+| **C4 Architecture Map** | `architecture/c4.md` | Comprehensive analysis + CKB (enhanced mode) |
+| Module dependency graph | `architecture/module-graph.md` | `mcp__ckb__getArchitecture` |
+| Technical debt hotspots | `architecture/hotspots.md` | `mcp__ckb__getHotspots` |
+| Layering constraints | `architecture/layering-constraints.md` | Code analysis (optional) |
 
-### 4. 基线变更包
+> **Design Decision**: C4 architecture map is now generated by brownfield-bootstrap during initialization. Subsequent architecture changes are recorded in design.md's Architecture Impact section and merged by spec-gardener during archiving.
 
-在 `<change-root>/<baseline-id>/` 下生成：
+### 4. Baseline Change Package
 
-| 产物 | 说明 |
-|------|------|
-| `proposal.md` | 基线范围、In/Out、风险 |
-| `design.md` | 现状盘点（capability inventory） |
-| `specs/<cap>/spec.md` | 基线 spec deltas（ADDED 为主） |
-| `verification.md` | 最小验证锚点计划 |
+Generate in `<change-root>/<baseline-id>/`:
+
+| Artifact | Description |
+|----------|-------------|
+| `proposal.md` | Baseline scope, In/Out, risks |
+| `design.md` | Current state inventory (capability inventory) |
+| `specs/<cap>/spec.md` | Baseline spec deltas (mainly ADDED) |
+| `verification.md` | Minimum verification anchor plan |
 
 ---
 
-## COD 模型生成（Code Overview & Dependencies）
+## COD Model Generation (Code Overview & Dependencies)
+
+Automatically generate project's "code map" during initialization (requires CKB MCP Server available, otherwise skip):
+
+### Auto-generated Artifacts
+
+| Artifact | Path | Data Source |
+|----------|------|-------------|
+| **C4 Architecture Map** | `<truth-root>/architecture/c4.md` | Comprehensive analysis |
+| Module dependency graph | `<truth-root>/architecture/module-graph.md` | `mcp__ckb__getArchitecture` |
+| Technical debt hotspots | `<truth-root>/architecture/hotspots.md` | `mcp__ckb__getHotspots` |
+| Domain concepts | `<truth-root>/_meta/key-concepts.md` | `mcp__ckb__listKeyConcepts` |
+| Project profile | `<truth-root>/_meta/project-profile.md` | Comprehensive analysis |
+
+### C4 Architecture Map Generation Rules
+
+C4 map generated during initialization should include:
+
+1. **Context Level**: System's relationship with external actors (users, external systems)
+2. **Container Level**: Containers within the system (applications, databases, services)
+3. **Component Level**: Components within main containers (modules, classes)
+
+**Output Format**:
+
+```markdown
+# C4 Architecture Map
 
-在初始化时自动生成项目的"代码地图"（需要 CKB MCP Server 可用，否则跳过）：
+## System Context
 
-### 自动生成产物
+[Describe system boundaries and external interactions]
 
-| 产物 | 路径 | 数据来源 |
-|------|------|----------|
-| 模块依赖图 | `<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>/_meta/project-profile.md` | 综合分析 |
+## Container Diagram
+
+| Container | Tech Stack | Responsibility |
+|-----------|------------|----------------|
+| <name> | <tech> | <responsibility> |
+
+## Component Diagram
+
+### <Container Name>
+
+| Component | Responsibility | Dependencies |
+|-----------|----------------|--------------|
+| <name> | <responsibility> | <dependencies> |
+
+## Architecture Guardrails
+
+### Layering Constraints
+
+| Layer | Can Depend On | Cannot Depend On |
+|-------|---------------|------------------|
+| <layer> | <allowed> | <forbidden> |
+```
 
-### 热点计算公式
+### Hotspot Calculation Formula
 
 ```
-热点分数 = 变更频率 × 圈复杂度
+Hotspot Score = Change Frequency × Cyclomatic Complexity
 ```
 
-- **高热点**（分数 > 阈值）：频繁修改 + 高复杂度 = Bug 密集区
-- **休眠债务**（高复杂度 + 低频率）：暂时安全但需关注
-- **活跃健康**（高频率 + 低复杂度）：正常维护区域
+- **High Hotspot** (score > threshold): Frequent changes + high complexity = Bug-dense area
+- **Dormant Debt** (high complexity + low frequency): Temporarily safe but needs attention
+- **Active Healthy** (high frequency + low complexity): Normal maintenance area
 
-### 边界识别
+### Boundary Identification
 
-自动区分：
-- **用户代码**：`src/`、`lib/`、`app/` 等（可修改）
-- **库代码**：`node_modules/`、`vendor/`、`.venv/` 等（不可变接口）
-- **生成代码**：`dist/`、`build/`、`*.generated.*` 等（禁止手动修改）
+Automatically distinguish:
+- **User Code**: `src/`, `lib/`, `app/` etc. (modifiable)
+- **Library Code**: `node_modules/`, `vendor/`, `.venv/` etc. (immutable interface)
+- **Generated Code**: `dist/`, `build/`, `*.generated.*` etc. (manual modification prohibited)
 
-### 执行流程
+### Execution Flow
 
-1) **检查图索引**：调用 `mcp__ckb__getStatus`
-   - 若 SCIP 可用 → 使用图基分析
-   - 若不可用 → 提示生成索引或使用 Git 历史分析
+1) **Check Graph Index**: Call `mcp__ckb__getStatus`
+   - If SCIP available → Use graph-based analysis
+   - If unavailable → Prompt to generate index or use Git history analysis
 
-2) **生成 COD 产物**：
+2) **Generate COD Artifacts**:
    ```bash
-   # 获取模块架构
+   # Get module architecture
    mcp__ckb__getArchitecture(depth=2, includeExternalDeps=false)
 
-   # 获取热点（近 30 天）
+   # Get hotspots (last 30 days)
    mcp__ckb__getHotspots(limit=20)
 
-   # 获取领域概念
+   # Get domain concepts
    mcp__ckb__listKeyConcepts(limit=12)
    ```
 
-3) **生成项目画像**：整合以上数据 + 传统分析
+3) **Generate Project Profile**: Integrate above data + traditional analysis
 
-## 参考骨架与模板
+## Reference Scaffolds and Templates
 
-- 工作流：`references/存量项目初始化.md`
-- 代码导航策略：`references/代码导航策略.md`
-- **项目画像模板（三层架构）**：`templates/project-profile-template.md`
-- 一次性提示词：`references/存量项目初始化提示词.md`
-- 模板（按需）：`references/术语表模板.md`
+- Workflow: `references/brownfield-bootstrap.md`
+- Code navigation strategy: `references/code-navigation-strategy.md`
+- **Project profile template (three-layer architecture)**: `templates/project-profile-template.md`
+- One-time prompt: `references/brownfield-bootstrap-prompt.md`
+- Template (as needed): `references/glossary-template.md`
 
 ---
 
-## 上下文感知
+## Context Awareness
 
-本 Skill 在执行前自动检测上下文，选择合适的初始化范围。
+This Skill automatically detects context before execution and selects the appropriate initialization scope.
 
-检测规则参考：`skills/_shared/context-detection-template.md`
+Detection rules reference: `skills/_shared/context-detection-template.md`
 
-### 检测流程
+### Detection Flow
 
-1. 检测 `<devbooks-root>/constitution.md` 是否存在
-2. 检测 `<devbooks-root>/project.md` 是否存在
-3. 检测 `<truth-root>/` 是否为空或基本为空
-4. 检测 CKB 索引是否可用
-5. 检测项目规模和语言栈
+1. Detect if `<devbooks-root>/constitution.md` exists
+2. Detect if `<devbooks-root>/project.md` exists
+3. Detect if `<truth-root>/` is empty or basically empty
+4. Detect if CKB index is available
+5. Detect project scale and language stack
 
-### 本 Skill 支持的模式
+### Modes Supported by This Skill
 
-| 模式 | 触发条件 | 行为 |
-|------|----------|------|
-| **全新初始化** | devbooks-root 不存在或为空 | 创建完整目录结构 + constitution + project + 画像 |
-| **补充配置** | constitution/project 缺失 | 只补充缺失的配置文件 |
-| **完整初始化** | truth-root 为空 | 生成所有基础产物（画像/基线/验证） |
-| **增量初始化** | truth-root 部分存在 | 只补充缺失产物 |
-| **增强模式** | CKB 索引可用 | 使用图分析生成更精确的画像 |
-| **基础模式** | CKB 索引不可用 | 使用传统分析方法 |
+| Mode | Trigger Condition | Behavior |
+|------|-------------------|----------|
+| **Full New Init** | devbooks-root doesn't exist or is empty | Create complete directory structure + constitution + project + profile |
+| **Supplement Config** | constitution/project missing | Only supplement missing configuration files |
+| **Complete Init** | truth-root is empty | Generate all basic artifacts (profile/baseline/verification) |
+| **Incremental Init** | truth-root partially exists | Only supplement missing artifacts |
+| **Enhanced Mode** | CKB index available | Use graph analysis to generate more precise profile |
+| **Basic Mode** | CKB index unavailable | Use traditional analysis methods |
 
-### 检测输出示例
+### Detection Output Example
 
 ```
-检测结果：
-- devbooks-root：存在
-- constitution.md：不存在 → 将创建
-- project.md：不存在 → 将创建
-- truth-root：为空
-- CKB 索引：可用
-- 项目规模：中型（~50K LOC）
-- 运行模式：补充配置 + 完整初始化 + 增强模式
+Detection Results:
+- devbooks-root: Exists
+- constitution.md: Doesn't exist → Will create
+- project.md: Doesn't exist → Will create
+- truth-root: Empty
+- CKB index: Available
+- Project scale: Medium (~50K LOC)
+- Running mode: Supplement Config + Complete Init + Enhanced Mode
 ```
 
 ---
 
-## MCP 增强
+## MCP Enhancement
 
-本 Skill 支持 MCP 运行时增强，自动检测并启用高级功能。
+This Skill supports MCP runtime enhancement, automatically detecting and enabling advanced features.
 
-MCP 增强规则参考：`skills/_shared/mcp-enhancement-template.md`
+MCP enhancement rules reference: `skills/_shared/mcp-enhancement-template.md`
 
-### 依赖的 MCP 服务
+### Required MCP Services
 
-| 服务 | 用途 | 超时 |
-|------|------|------|
-| `mcp__ckb__getStatus` | 检测 CKB 索引可用性 | 2s |
-| `mcp__ckb__getArchitecture` | 获取模块依赖图 | 2s |
-| `mcp__ckb__getHotspots` | 获取技术债热点 | 2s |
-| `mcp__ckb__listKeyConcepts` | 获取领域概念 | 2s |
-| `mcp__ckb__getModuleOverview` | 获取模块概览 | 2s |
+| Service | Purpose | Timeout |
+|---------|---------|---------|
+| `mcp__ckb__getStatus` | Detect CKB index availability | 2s |
+| `mcp__ckb__getArchitecture` | Get module dependency graph | 2s |
+| `mcp__ckb__getHotspots` | Get technical debt hotspots | 2s |
+| `mcp__ckb__listKeyConcepts` | Get domain concepts | 2s |
+| `mcp__ckb__getModuleOverview` | Get module overview | 2s |
 
-### 检测流程
+### Detection Flow
 
-1. 调用 `mcp__ckb__getStatus`（2s 超时）
-2. 若 CKB 可用 → 使用图基分析生成 COD 产物
-3. 若超时或失败 → 降级到传统分析（Git 历史 + 文件统计）
+1. Call `mcp__ckb__getStatus` (2s timeout)
+2. If CKB available → Use graph-based analysis to generate COD artifacts
+3. If timeout or failure → Degrade to traditional analysis (Git history + file statistics)
 
-### 增强模式 vs 基础模式
+### Enhanced Mode vs Basic Mode
 
-| 功能 | 增强模式 | 基础模式 |
-|------|----------|----------|
-| 模块依赖图 | CKB getArchitecture | 目录结构推断 |
-| 技术债热点 | CKB getHotspots | Git log 统计 |
-| 领域概念 | CKB listKeyConcepts | 命名分析 |
-| 边界识别 | 精确模块边界 | 目录约定 |
+| Feature | Enhanced Mode | Basic Mode |
+|---------|---------------|------------|
+| Module dependency graph | CKB getArchitecture | Directory structure inference |
+| Technical debt hotspots | CKB getHotspots | Git log statistics |
+| Domain concepts | CKB listKeyConcepts | Naming analysis |
+| Boundary identification | Precise module boundaries | Directory conventions |
 
-### 降级提示
+### Degradation Notice
 
-当 MCP 不可用时，输出以下提示：
+When MCP is unavailable, output the following notice:
 
 ```
-⚠️ CKB 不可用，使用传统分析方法生成项目画像。
-如需更精确的架构分析，请运行 devbooks-index-bootstrap skill 生成索引。
+Warning: CKB unavailable, using traditional analysis methods to generate project profile.
+For more precise architecture analysis, run devbooks-index-bootstrap skill to generate index.
 ```

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

@@ -35,7 +35,7 @@ Before execution, **must** search for configuration in the following order (stop
 - Code formatting
 
 ### 2. Dependency Health Review
-- Layer constraint compliance (see devbooks-c4-map)
+- Layer constraint compliance (see `<truth-root>/architecture/c4.md`)
 - Circular dependency detection
 - Internal module encapsulation (prohibit deep imports of *Internal files)
 - Dependency direction correctness

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

@@ -74,6 +74,81 @@ The following change types **require** updating corresponding documentation:
 | New commands/CLI parameters | User guide |
 | External API changes | API documentation |
 
+## Architecture Impact Statement (Required)
+
+Design documents **must** include an "Architecture Impact" section declaring the impact of this change on system architecture. This is a key mechanism to ensure architecture changes go through verification closed-loops.
+
+> **Design Decision**: C4 architecture changes are no longer written directly to the truth directory by a standalone `devbooks-c4-map` skill. Instead, they are part of design.md and merged into truth by `devbooks-spec-gardener` after change acceptance.
+
+### Template
+
+```markdown
+## Architecture Impact
+
+<!-- Required: Choose one of the following -->
+
+### No Architecture Changes
+
+- [x] This change does not affect module boundaries, dependency directions, or component structure
+- Reason: <Brief explanation of why there's no architecture impact>
+
+### Has Architecture Changes
+
+#### C4 Level Impact
+
+| Level | Change Type | Impact Description |
+|-------|-------------|-------------------|
+| Context | None / Add / Modify / Delete | <description> |
+| Container | None / Add / Modify / Delete | <description> |
+| Component | None / Add / Modify / Delete | <description> |
+
+#### Container Changes
+
+- [Add/Modify/Delete] `<container-name>`: <change description>
+
+#### Component Changes
+
+- [Add/Modify/Delete] `<component-name>` in `<container>`: <change description>
+
+#### Dependency Changes
+
+| Source | Target | Change Type | Notes |
+|--------|--------|-------------|-------|
+| `<source>` | `<target>` | Add/Delete/Direction Change | <notes> |
+
+#### Layering Constraint Impact
+
+- [ ] This change follows existing layering constraints
+- [ ] This change requires modifying layering constraints (explain below)
+
+Layering constraint modification notes: <if any>
+```
+
+### Detection Rules
+
+When executing design-doc skill, **must check** the following conditions to determine architecture changes:
+
+| Check Item | Detection Method | Has Architecture Change |
+|------------|------------------|------------------------|
+| New/deleted directories | Check changed file paths | May affect module boundaries |
+| Cross-module imports | Check import statement changes | May affect dependency direction |
+| New external dependencies | Check package.json/go.mod etc. | Affects Container level |
+| New services/processes | Check Dockerfile/docker-compose | Affects Container level |
+| New API endpoint groups | Check route definitions | May affect Component level |
+
+### Trigger Rules
+
+The following change types **require** filling in architecture change details:
+
+| Change Type | Requirement |
+|-------------|-------------|
+| New module/directory | Must describe Component changes |
+| New service/container | Must describe Container changes |
+| Modified inter-module dependencies | Must describe dependency changes |
+| Introduced new external system | Must describe Context changes |
+
+---
+
 ## Execution Method
 
 1) First read and follow: `_shared/references/universal-gating-protocol.md` (verifiability + structural quality gates).

package/skills/devbooks-router/SKILL.md

@@ -108,7 +108,7 @@ impact_profile:
 | Impact Field | Value | Auto-Append Skill |
 |--------------|-------|-------------------|
 | `external_api: true` | - | `devbooks-spec-contract` |
-| `architecture_boundary: true` | - | `devbooks-c4-map` |
+| `architecture_boundary: true` | - | `devbooks-design-doc` (ensure Architecture Impact section is complete) |
 | `cross_repo: true` | - | `devbooks-federation` |
 | `risk_level: high` | - | `devbooks-proposal-debate-workflow` |
 | `affected_modules` count > 5 | - | `devbooks-impact-analysis` (deep analysis) |
@@ -125,7 +125,7 @@ impact_profile:
 
 ### Recommended (Based on Impact Analysis)
 4. `devbooks-spec-contract skill` → specs/** (detected external_api: true)
-5. `devbooks-c4-map skill` → architecture/c4.md (detected architecture_boundary: true)
+5. `devbooks-design-doc skill` → design.md Architecture Impact section (detected architecture_boundary: true)
 
 ### Optional
 6. `devbooks-impact-analysis skill` → Deep impact analysis (affected_modules > 5)
@@ -182,7 +182,7 @@ Append as needed (add only when conditions are met):
 - **Obvious risks/controversies/trade-offs**: `devbooks-proposal-debate-workflow` (Author/Challenger/Judge, write back to Decision Log after debate)
 - **External behavior/contract/data invariant changes**: `devbooks-spec-contract` → `(<change-root>/<change-id>/specs/**)` + `design.md` Contract section
   - If you need "deterministic spec delta file creation/avoid path errors": `change-spec-delta-scaffold.sh <change-id> <capability> ...`
-- **Module boundary/dependency direction/architecture shape changes**: `devbooks-c4-map` → `(<truth-root>/architecture/c4.md)`
+- **Module boundary/dependency direction/architecture shape changes**: Ensure `devbooks-design-doc` outputs complete Architecture Impact section → merged to `(<truth-root>/architecture/c4.md)` by `devbooks-spec-gardener` during archiving
 
 Hard constraint reminders:
 - Proposal phase prohibits writing implementation code; implementation happens in apply phase with tests/gates as completion criteria.

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

@@ -27,6 +27,62 @@ Before execution, **must** search for configuration in the following order (stop
 - Do not guess directory roots
 - Do not skip reading the rules document
 
+---
+
+## Core Responsibilities
+
+### 1. Spec Merge and Maintenance
+
+During archive phase, merge change package spec artifacts into `<truth-root>`:
+
+| Source Path | Target Path | Merge Strategy |
+|-------------|-------------|----------------|
+| `<change-root>/<change-id>/specs/**` | `<truth-root>/specs/**` | Incremental merge |
+| `<change-root>/<change-id>/contracts/**` | `<truth-root>/contracts/**` | Versioned merge |
+
+### 2. C4 Architecture Map Merge (New)
+
+> **Design Decision**: C4 architecture changes are now recorded in design.md's Architecture Impact section and merged into truth by spec-gardener during archiving.
+
+During archive phase, detect and merge architecture changes:
+
+| Detection Source | Target Path | Merge Logic |
+|------------------|-------------|-------------|
+| "Architecture Impact" section in `<change-root>/<change-id>/design.md` | `<truth-root>/architecture/c4.md` | Incremental update |
+
+**C4 Merge Flow**:
+
+1. **Detect Architecture Changes**: Parse "Architecture Impact" section in `design.md`
+2. **Determine If Merge Needed**:
+   - If "No Architecture Changes" is checked → Skip merge
+   - If "Has Architecture Changes" → Execute merge
+3. **Execute Merge**:
+   - Read `<truth-root>/architecture/c4.md` (create if doesn't exist)
+   - Update corresponding sections based on Architecture Impact descriptions
+   - Update Container/Component tables
+   - Update dependency relationships
+   - Update layering constraints (if changed)
+4. **Record Merge Log**: Append change record at end of c4.md
+
+**Merge Output Format** (appended to c4.md):
+
+```markdown
+## Change History
+
+| Date | Change ID | Impact Summary |
+|------|-----------|----------------|
+| <date> | <change-id> | <brief description of architecture changes> |
+```
+
+### 3. Deduplication and Cleanup
+
+Execute in maintenance mode:
+
+- Detect duplicate spec definitions
+- Clean up obsolete/deprecated specs
+- Organize directory structure
+- Fix consistency issues
+
 ## Execution Method
 
 1) First read and follow: `_shared/references/universal-gating-protocol.md` (verifiability + structural quality gates).

package/templates/dev-playbooks/README.md

@@ -178,7 +178,6 @@ Run devbooks-spec-gardener skill for change add-oauth2
 | devbooks-proposal-debate-workflow | Triangle debate (Author/Challenger/Judge) |
 | devbooks-design-doc | Create a design doc |
 | devbooks-spec-contract | Define specs & contracts |
-| devbooks-c4-map | Generate a C4 map |
 | devbooks-implementation-plan | Create an implementation plan |
 
 ### Apply stage

package/templates/dev-playbooks/docs/devbooks-setup-guide.md

@@ -132,8 +132,7 @@ Each change must declare which gates are covered; missing items require reasons:
 | Test Owner | `devbooks-test-owner` | `verification.md` + `tests/` |
 | Coder | `devbooks-coder` | Implement per tasks (no tests) |
 | Reviewer | `devbooks-code-review` | Review feedback |
-| Spec Gardener | `devbooks-spec-gardener` | Archive pruning |
-| C4 Map | `devbooks-c4-map` | `architecture/c4.md` |
+| Spec Gardener | `devbooks-spec-gardener` | Archive pruning + C4 merge |
 | Design Backport | `devbooks-design-backport` | Backport design gaps |
 
 ### Workflow-Based

package/skills/devbooks-c4-map/SKILL.md

@@ -1,151 +0,0 @@
----
-name: devbooks-c4-map
-description: devbooks-c4-map: Maintain/update the project's C4 architecture map (current truth) and output C4 Delta based on changes. Use when user says "draw architecture diagram/C4/boundaries/dependency direction/module map/architecture map maintenance" etc.
-tools:
-  - Glob
-  - Grep
-  - Read
-  - Write
-  - Edit
----
-
-# DevBooks: C4 Architecture Map
-
-## Prerequisites: Configuration Discovery (Protocol Agnostic)
-
-- `<truth-root>`: Current truth directory root
-- `<change-root>`: Change package directory root
-
-Before execution, **must** search for configuration in the following order (stop when found):
-1. `.devbooks/config.yaml` (if exists) → Parse and use the mappings within
-2. `dev-playbooks/project.md` (if exists) → DevBooks 2.0 protocol, use default mappings
-4. `project.md` (if exists) → template protocol, use default mappings
-5. If still unable to determine → **Stop and ask the user**
-
-**Key Constraints**:
-- If `agents_doc` (rules document) is specified in the configuration, **must read that document first** before executing any operations
-- Do not guess directory roots
-- Do not skip reading the rules document
-
-## Artifact Locations
-
-- Authoritative C4 map: `<truth-root>/architecture/c4.md`
-- Layering constraints definition: `<truth-root>/architecture/layering-constraints.md` (optional)
-
-## Layering Dependency Constraints
-
-Drawing from VS Code's layering architecture enforcement mechanism, the C4 map should include a **Layering Constraints** section:
-
-### Layering Constraint Definition Rules
-
-1. **Unidirectional Dependency Principle**: Upper layers may depend on lower layers; lower layers are prohibited from depending on upper layers
-   - Example: `base ← platform ← domain ← application ← ui`
-   - Arrow direction indicates "dependency direction"
-
-2. **Environment Isolation Principle**: The `common` layer can only be referenced by `browser`/`node` layers, not the reverse
-   - `common`: Platform-agnostic code
-   - `browser`: Browser-specific code (DOM API)
-   - `node`: Node.js-specific code (fs, process)
-
-3. **Contrib Reverse Isolation**: Contribution modules can only depend on core; core is prohibited from depending on contribution modules
-   - Example: `workbench/contrib/*` → `workbench/core` (allowed)
-   - Example: `workbench/core` → `workbench/contrib/*` (prohibited)
-
-### Layering Constraints Output Format
-
-The `## Architecture Guardrails` section in `c4.md` must include:
-
-```markdown
-### Layering Constraints
-
-| Layer | May Depend On | Prohibited Dependencies |
-|-------|---------------|------------------------|
-| base | (none) | platform, domain, application, ui |
-| platform | base | domain, application, ui |
-| domain | base, platform | application, ui |
-| application | base, platform, domain | ui |
-| ui | base, platform, domain, application | (none) |
-
-### Environment Constraints
-
-| Environment | May Reference | Prohibited References |
-|-------------|---------------|----------------------|
-| common | (platform-agnostic libraries) | browser/*, node/* |
-| browser | common/* | node/* |
-| node | common/* | browser/* |
-```
-
-## Execution Method
-
-1) First read and follow: `_shared/references/universal-gating-protocol.md` (verifiability + structural quality gating).
-2) Strictly follow the complete prompt output: `references/c4-architecture-map-prompt.md`.
-3) Reference the layering constraints checklist: `references/layered-constraint-checklist.md`.
-
----
-
-## Context Awareness
-
-This Skill automatically detects context before execution and selects the appropriate running mode.
-
-Detection rules reference: `skills/_shared/context-detection-template.md`
-
-### Detection Flow
-
-1. Detect whether `<truth-root>/architecture/c4.md` exists
-2. If change-id is provided, detect whether there are C4-related changes
-3. Select running mode based on detection results
-
-### Modes Supported by This Skill
-
-| Mode | Trigger Condition | Behavior |
-|------|-------------------|----------|
-| **Create Mode** | `c4.md` does not exist | Analyze codebase, generate complete C4 diagrams at all levels (Context/Container/Component) |
-| **Update Mode** | `c4.md` exists, changes need to be reflected | Read change content, output C4 Delta, update architecture diagram |
-
-### Detection Output Example
-
-```
-Detection Results:
-- Artifact existence: c4.md exists
-- Change impact: Component-level changes detected (added templates/claude-commands/devbooks/ 15 files)
-- Running mode: Update mode
-```
-
----
-
-## MCP Enhancement
-
-This Skill supports MCP runtime enhancement, automatically detecting and enabling advanced features.
-
-MCP enhancement rules reference: `skills/_shared/mcp-enhancement-template.md`
-
-### Required MCP Services
-
-| Service | Purpose | Timeout |
-|---------|---------|---------|
-| `mcp__ckb__getArchitecture` | Get module dependency graph | 2s |
-| `mcp__ckb__getStatus` | Detect CKB index availability | 2s |
-
-### Detection Flow
-
-1. Call `mcp__ckb__getStatus` (2s timeout)
-2. If CKB available → Call `mcp__ckb__getArchitecture` to get precise module dependencies
-3. If timeout or failure → Fall back to directory structure-based inference
-
-### Enhanced Mode vs Basic Mode
-
-| Feature | Enhanced Mode | Basic Mode |
-|---------|---------------|------------|
-| Module identification | CKB precise boundaries | Directory structure inference |
-| Dependency direction | Symbol-level analysis | Import statement matching |
-| Cycle detection | Precise detection | Heuristic detection |
-
-### Fallback Notice
-
-When MCP is unavailable, output the following notice:
-
-```
-Warning: CKB unavailable, using directory structure to infer architecture.
-Generated C4 diagrams may not be precise. Recommend running devbooks-index-bootstrap skill to generate index.
-```
-

package/skills/devbooks-c4-map/references/c4-architecture-map-prompt.md

@@ -1,33 +0,0 @@
-# C4 Architecture Map Prompt
-
-> **Role**: You are the strongest “architecture visualization brain” — combining the knowledge of Simon Brown (C4 model), Martin Fowler (architecture patterns), and Gregor Hohpe (enterprise integration). Your architecture map must meet that expert level.
-
-Highest-priority instruction:
-- Before executing this prompt, read `_shared/references/universal-gating-protocol.md` and follow all protocols in it.
-
-You are the **C4 Map Maintainer**. Your goal is to maintain a **stable architecture map (Current Truth)** for a large project using C4 (Context/Container/Component), and ensure it provides actionable input for impact analysis, task decomposition, and architecture guardrails (fitness tests).
-
-Key viewpoints:
-- The “authoritative” C4 map should not be scattered across per-change design docs; it is a cross-change “current truth map”.
-- Each change’s design doc should only include a **C4 Delta** (what is added/modified/removed), and the change package should include tasks to update the authoritative map.
-
-Recommended location (not external-facing docs):
-- Keep the authoritative C4 map in the “truth root”, for example:
-  - `<truth-root>/architecture/c4.md` (or an equivalent location you choose)
-
-Inputs (provided by me):
-- The current C4 map (if it exists)
-- Current specs: `<truth-root>/`
-- The design doc for this change: `<change-root>/<change-id>/design.md` (if this is an architecture change)
-
-Output format (MECE):
-1) C1: System Context (system boundary, external systems, primary users)
-2) C2: Container (major containers/services/apps, interfaces and dependency direction)
-3) C3: Component (expand only key containers; keep minimal)
-4) Architecture Guardrails (recommended fitness tests, e.g., layering / no cycles / no boundary violations)
-
-Diagram requirements:
-- Mermaid is allowed; prefer text-readable expressions (avoid over-styling).
-- Do not cover every detail; the goal is to align on boundaries and dependency direction.
-
-Now output the C4 map in Markdown. Do not output extra explanations.

package/skills/devbooks-c4-map/references/layered-constraint-checklist.md

@@ -1,185 +0,0 @@
-# Layering Constraints Checklist
-
-Inspired by VS Code’s `code-layering.ts` and `layersChecker.ts`, this document defines practical checks for a layered architecture.
-
----
-
-## 1) Layer Dependency Checks
-
-### 1.1 Unidirectional Dependency Violations
-
-**How to check**: scan `import`/`require` statements and validate dependency direction.
-
-```typescript
-// Violation: base layer importing platform layer
-// src/base/utils.ts
-import { ConfigService } from '../platform/config';  // ❌ violation
-
-// Correct: platform layer importing base layer
-// src/platform/config.ts
-import { deepClone } from '../base/utils';  // ✅ allowed
-```
-
-**Example commands** (grep/rg):
-
-```bash
-# Check whether base illegally imports platform
-rg "from ['\"].*platform" src/base/ --type ts
-
-# Check whether common illegally imports browser/node
-rg "from ['\"].*(browser|node)" src/common/ --type ts
-```
-
-### 1.2 Environment Isolation Violations
-
-| Environment | Forbidden APIs | Detection regex |
-|------|-----------|---------|
-| common | DOM API | `document\.|window\.|navigator\.` |
-| common | Node API | `require\(['"]fs['"]\)|process\.|__dirname` |
-| browser | Node API | `require\(['"]fs['"]\)|child_process` |
-| node | DOM API | `document\.|window\.|DOM\.` |
-
-### 1.3 contrib Reverse-Dependency Checks
-
-```bash
-# Check whether core illegally imports contrib
-rg "from ['\"].*contrib" src/core/ --type ts
-rg "from ['\"].*contrib" src/workbench/services/ --type ts
-```
-
----
-
-## 2) Layering Constraints Template
-
-Add this to `<truth-root>/architecture/c4.md`:
-
-```markdown
-## Architecture Guardrails
-
-### Layering Constraints
-
-This project uses an N-layer architecture with dependency direction: `base ← platform ← domain ← application ← ui`
-
-| Layer | Directory | Responsibility | Allowed deps | Forbidden deps |
-|------|------|------|--------|----------|
-| base | src/base/ | Utilities, cross-platform abstractions | (none) | all other layers |
-| platform | src/platform/ | Platform services, dependency injection | base | domain, app, ui |
-| domain | src/domain/ | Business logic, domain model | base, platform | app, ui |
-| application | src/app/ | App services, use-case orchestration | base, platform, domain | ui |
-| ui | src/ui/ | User interface, interaction logic | all layers | (none) |
-
-### Environment Constraints
-
-| Environment directory | Allowed | Forbidden |
-|----------|--------|----------|
-| */common/ | platform-agnostic libs | */browser/*, */node/* |
-| */browser/ | */common/* | */node/* |
-| */node/ | */common/* | */browser/* |
-
-### Validation Commands
-
-```bash
-# Layering violations check
-npm run valid-layers-check
-
-# Or check manually
-rg "from ['\"].*platform" src/base/ --type ts && echo "FAIL: base→platform" || echo "OK"
-```
-```
-
----
-
-## 3) Severity Levels for Layering Violations
-
-| Violation type | Severity | Handling |
-|----------|----------|----------|
-| Lower layer depends on upper layer | **Critical** | must fix immediately; block merge |
-| common depends on browser/node | **Critical** | must fix immediately |
-| Cross-layer deep import of Internal modules | **High** | use public APIs instead |
-| core depends on contrib | **High** | violates extension-point design |
-| Cyclic dependencies | **High** | requires refactoring/decoupling |
-
----
-
-## 4) Integrating Layer Checks
-
-### 4.1 Configure in ESLint (recommended)
-
-```javascript
-// eslint.config.js
-module.exports = {
-  rules: {
-    'import/no-restricted-paths': ['error', {
-      zones: [
-        // base must not import platform
-        { target: './src/base', from: './src/platform', message: 'base cannot import platform' },
-        // platform must not import domain
-        { target: './src/platform', from: './src/domain', message: 'platform cannot import domain' },
-        // common must not import browser/node
-        { target: './src/**/common', from: './src/**/browser', message: 'common cannot import browser' },
-        { target: './src/**/common', from: './src/**/node', message: 'common cannot import node' },
-      ]
-    }]
-  }
-};
-```
-
-### 4.2 Configure in TypeScript
-
-Create a separate `tsconfig` for each layer:
-
-```json
-// tsconfig.base.json
-{
-  "compilerOptions": {
-    "paths": {
-      // base layer can only see itself
-    }
-  },
-  "include": ["src/base/**/*"],
-  "exclude": ["src/platform/**/*", "src/domain/**/*"]
-}
-```
-
-### 4.3 Configure in CI
-
-```yaml
-# .github/workflows/pr.yml
-- name: Check layer constraints
-  run: |
-    # Check for layering violations
-    ./scripts/valid-layers-check.sh || exit 1
-```
-
----
-
-## 5) Layering Refactoring Guide
-
-When a layering violation is found:
-
-1. **Identify the reason**
-   - Is the dependency actually legitimate? (You may need to adjust the layering definition.)
-   - Can you decouple via interface abstractions?
-   - Should the code be moved to the correct layer?
-
-2. **Decoupling strategies**
-   - **Dependency injection**: upper layers inject interfaces; lower layers do not depend on implementations
-   - **Events**: lower layers publish events; upper layers subscribe
-   - **Callbacks**: lower layers accept callback functions and avoid knowing callers
-
-3. **Code movement**
-   - If the code belongs in a lower layer, move it to the correct location
-   - Update all import paths
-   - Run layer checks to confirm the fix
-
----
-
-## 6) Review Checklist
-
-During code review, check:
-
-- [ ] Do new imports follow layer constraints?
-- [ ] Are there deep imports into Internal modules?
-- [ ] Does code under `common/` use platform-specific APIs?
-- [ ] Does `core` import `contrib`?
-- [ ] Are there cyclic dependencies?