@modus-ai/modus 0.2.4 → 0.2.5

package/templates/skills/modus-init/SKILL.md

@@ -3,6 +3,27 @@ name: modus-init
 description: Use this skill when executing /modus:init command to scan the codebase, classify business domains, and generate Business Skill files, team-conventions Skill, tech-wiki Skill, and knowledge-catalog index. Trigger on /modus:init command or when user asks to initialize Modus or build business Skills from scratch.
 allowed-tools: Read, Write, Glob, Bash
 disable: false
+supported_platforms:
+  claude:
+    status: full       # 全功能支持：SubAgent 并行扫描、多轮访谈、Bash 工具可用
+    notes: "推荐平台。所有步骤均可完整执行，Bash 可直接运行 mvn/npm 命令检测项目结构。"
+  codebuddy:
+    status: full       # 全功能支持
+    notes: "推荐平台。与 Claude 能力对等，Skill 生成格式与 .codebuddy/ 目录结构完全兼容。"
+  cursor:
+    status: partial    # 部分支持：无 SubAgent、无 Bash，Skill 以 .mdc 规则文件输出
+    notes: "Cursor 不支持 SubAgent，init 流程退化为单 Agent 串行执行；Bash 工具不可用，目录扫描依赖 Glob/Read 工具。生成的 Skill 以 .cursor/rules/modus-biz-*.mdc 格式输出，不支持 v3/17节完整格式。"
+    limitations:
+      - "无 SubAgent：5 轮扫描由单 Agent 串行执行，速度较慢"
+      - "无 Bash：无法直接执行构建命令，技术栈检测依赖文件内容推断"
+      - "Skill 格式降级：输出为 .mdc 规则文件，不支持 frontmatter 防腐字段"
+  copilot:
+    status: minimal    # 最小支持：所有内容合并为单文件
+    notes: "GitHub Copilot 仅支持单文件 copilot-instructions.md，init 将核心知识摘要合并输出，不支持分域 Skill 和防腐机制。"
+    limitations:
+      - "所有 Skill 合并为单个 copilot-instructions.md，无法按需加载"
+      - "不支持防腐机制（无 hash/stale 字段）"
+      - "不支持 Harness SubAgent"
 ---
 
 # modus-init
@@ -15,13 +36,72 @@ disable: false
 
 ---
 
+## 本文件结构索引（Agent 必读）
+
+> 本文件共分三个区块，请根据当前任务按需加载，避免无效 token 消耗：
+
+| 区块 | 内容 | Agent 读取时机 | 典型使用场景 |
+|------|------|----------------|------------|
+| **区块 A：执行流程**（Step 0-11） | Agent 执行 `/modus:init` 时的完整步骤指令 | **每次执行 `/modus:init` 必须完整读取** | 全新初始化、重新初始化（模式 1-4）、补全新节 |
+| **区块 B：防腐机制总览** | 防腐字段说明、双级 hash 规则、活跃度感知衰减、status 全链路图、同步副本管理规约 | 执行 Step 5 生成 Skill 前必读；执行 `/modus:verify`、`/modus:refresh` 前必读 | hash 不一致处理、status 升降级、副本同步问题排查 |
+| **区块 C：Business Skill 标准格式**（v3/17节模板） | 多语言适配说明 + 生成每个业务 Skill 时的完整格式参考 | 执行 Step 5 时按需读取对应节的格式要求；辅助命令 `/modus:verify`、`/modus:refresh` 执行时读取 | 格式参考、节内容门槛检查、信号词归属判断 |
+
+---
+<!-- ============================================================ -->
+<!-- 区块 A：执行流程（执行 /modus:init 时完整读取）             -->
+<!-- ============================================================ -->
+
 ## 执行流程
 
-### Step 0：读取项目宪法
+### Step 0：读取项目宪法 + 重新初始化检查
 
 读取 `modus/config.yaml`（若存在），提取 `constitution` 字段中的硬性约束，作为整个初始化过程的最高优先级约束。
 
-若 `modus/config.yaml` 不存在，将在 Step 9 创建默认配置。
+若 `modus/config.yaml` 不存在，将在 Step 10 创建默认配置。
+
+#### 重新初始化分支检查（Step 0 末尾执行）
+
+在进入 Step 1 之前，检查是否已有业务 Skill：
+
+```bash
+# 检查是否存在已有的业务 Skill（支持 Bash 的平台）
+ls .codebuddy/skills/modus-biz-* 2>/dev/null
+```
+
+> **Cursor 平台替代**（无 Bash）：使用 Glob 工具匹配 `.codebuddy/skills/modus-biz-*/SKILL.md`；若 Glob 返回结果即表示存在已有 Skill。
+
+**若发现已存在 `modus-biz-*` 目录：**
+
+```
+当前已有以下业务 Skill：
+  modus-biz-order    v1.2.0  [verified]  更新: 2025-11-20  (v2/14节格式)
+  modus-biz-payment  v1.0.0  [draft]     更新: 2025-10-05  (v1/7节格式 → ⚠️ 建议迁移)
+  modus-biz-user     v2.1.0  [proven]    更新: 2025-12-01  (v2/14节格式)
+
+请选择重初始化模式：
+  1. 全量重建        — 全部删除重新生成（会覆盖所有人工标注）
+  2. 仅更新指定域    — 选择哪些域重新扫描
+  3. 新增缺失域      — 只为新发现的域生成 Skill
+  4. 补全新节（推荐）— 保留已有内容，扫描代码补充生成缺失节 ✨
+     v1(7节) → v2(14节)：补全 8-14 节
+     v2(14节) → v3(17节)：补全 15-17 节（业务不变量/词汇表/新人指南）
+```
+
+**各模式执行规则：**
+- **全量重建（模式 1）**：清空 `.codebuddy/skills/modus-biz-*/`，然后从 Step 1 开始全量执行
+- **仅更新指定域（模式 2）**：用户选定域后，对这些域重新执行 Step 2→Step 5；其余域保持不变
+- **新增缺失域（模式 3）**：执行 Step 2 扫描，仅对新发现的域执行 Step 5 生成，已有域跳过
+- **补全新节（模式 4，推荐）**：
+  - 读取已有 Skill 的已有节，**不修改任何已有内容**
+  - 仅追加缺失节（满足域适用性条件的节，不满足则跳过，不填占位符）
+  - 对 v2 → v3 迁移：补充 Section 15（业务不变量）、Section 16（领域词汇表）、Section 17（新人上手指南）
+  - 同步扩展 frontmatter 的 `key_files`（补充优先级 2/3 类文件，上限 20 个）
+  - 更新 `format_version`（v1→v2 或 v2→v3）、`version`（小版本 +1）和 `updated` 日期
+  - 迁移完成后自动触发 Step 6 多平台同步
+
+无论何种模式，都在最后更新 `modus/knowledge-catalog.md` 的索引信息。
+
+**若未发现已有 Skill：** 继续 Step 1 开始全新初始化流程。
 
 ### Step 1：扫描已有 AI 工具配置
 
@@ -96,17 +176,59 @@ disable: false
 
 启动一个「项目分析 SubAgent」，执行以下 **5 轮结构化扫描**（替代原有的简单目录读取）：
 
+#### 扫描前置：读取 scanRules 配置
+
+在开始轮次 1 前，读取 `modus/config.yaml` 中的 `scanRules` 字段（若存在），构建本次扫描的规则集：
+
+```
+scanRules.include_extensions（用户配置）
+  ||（合并）
+默认后缀：[.java, .kt, .py, .ts, .tsx, .js, .go, .rs, .php, .rb, .swift, .scala]
+
+scanRules.exclude_patterns（用户配置）
+  ||（合并）
+默认排除：[target/**, build/**, dist/**, node_modules/**, .idea/**, .vscode/**,
+           generated/**, **/*Generated.java, *.lock, .git/**, .github/**]
+  ||（合并）
+项目根目录 .gitignore / .modus-ignore（若存在）
+
+最终公式：扫描文件 = (include_extensions 匹配) - (exclude_patterns 排除)
+```
+
+若 `scanRules` 不存在，使用全部默认值，不向用户提示。
+若存在用户自定义规则，输出一行说明：`[读取自定义扫描规则：排除 N 个额外路径，包含 M 个扩展名]`
+
 #### 轮次 1：模块发现
 
+**进度输出（轮次开始时）：**
+```
+[1/5 模块发现] 扫描中...
+```
+
 递归枚举项目中所有构建单元：
 - Java/Kotlin：递归发现所有 Maven Module（`pom.xml`）或 Gradle 子项目（`settings.gradle`）
 - Python：发现所有包目录（含 `__init__.py` 或 `pyproject.toml`）
 - 前端：发现所有独立 Node Package（`package.json`）
 
+**进度输出（轮次完成时）：**
+```
+[1/5 模块发现] ✓ 发现 {N} 个构建模块 — {模块名1}, {模块名2}...
+```
+
+**失败回退：** 若无法识别任何构建单元，输出：
+```
+[1/5 模块发现] ⚠️ 未发现标准构建文件（pom.xml/package.json），将以目录结构为单位扫描。
+```
+
 输出：模块列表（含模块名、路径、构建文件路径）
 
 #### 轮次 2：包级清单
 
+**进度输出（轮次开始时）：**
+```
+[2/5 包级清单] 扫描中...（{N} 个模块）
+```
+
 对每个模块，逐包统计：
 - 文件数量
 - 类型分布（`Controller/Facade` / `Service/Manager` / `Mapper/DAO` / `Domain/Entity` / `Enum/Constant` / `DTO/VO` / `Exception/ErrorCode` / `MQ Consumer/Producer` / `XML Mapper` / `@Configuration`）
@@ -125,15 +247,64 @@ disable: false
   ...（全量展示，不截断）
 ```
 
-#### 轮次 3：域语义分析
+**进度输出（轮次完成时）：**
+```
+[2/5 包级清单] ✓ 扫描 {N} 个文件，发现 {M} 个候选域（其中 {K} 个小包候选）
+```
 
-按命名模式 + 调用链分析推断域归属：
+#### 轮次 3：域语义分析（方法签名级）
+
+按**三层递进**推断域归属，对非标准命名（如 `UserModuleV2Manager`、`BizOpportunityFacade`）也能准确识别：
+
+**层 A：包名语义词匹配**（快速初判）
 - 分析包名中的业务语义词（如 `order`、`pay`、`user`）
-- 扫描 Service 类中的方法命名，归纳核心职责
-- 识别 Facade/Controller 入口，确认域的对外暴露点
+- 若包名与已知业务词完全匹配，直接归入对应域（置信度 High）
+
+**层 B：公开方法签名分析**（语义细化）
+- 对 Service/Manager/Facade 类，提取所有 `public` 方法签名：
+  - 方法名（提取语义动词 + 名词，如 `confirmOrder` → 操作=confirm，对象=Order）
+  - 返回类型（List/PageResult/void → 推断是查询/写操作/事件）
+  - 参数中的 DTO/Entity 名称（如 `CreateOrderRequest` → 明确归入 order 域）
+- 从方法语义词聚类推断域：同包内方法名含有同一业务名词 ≥ 3 个 → 确认域归属
+
+**输出格式（增强版，包含代表性方法签名）：**
+
+```
+域识别结果（共 {N} 个域）：
+
+  order（订单域）  [置信度 High]
+    核心方法：createOrder(CreateOrderReq) → OrderVO
+             cancelOrder(Long orderId) → void
+             getOrderDetail(Long orderId) → OrderDetailVO
+             batchConfirmOrder(List<Long>) → BatchResultVO
+             queryOrderPage(OrderPageQuery) → PageResult<OrderVO>
+    → 关键文件：OrderService, OrderManager, OrderMapper
+
+  payment（支付域）  [置信度 Medium — 包名为 pay，方法含 payment/refund/callback]
+    核心方法：initPayment(PaymentInitReq) → PaymentVO
+             handleCallback(PayCallbackReq) → void
+    → 关键文件：PaymentService, PaymentMapper
+```
+
+**层 C：回退策略**（当 A/B 均无法确定时）
+- 若类名含有多个语义域的词（如 `OrderPaymentService`），标记为"待人工确认"的跨域类
+- 若整个包只有 1-2 个文件，标记为"⚠️ 小包候选，建议合并到相近域"
+- 输出候选归属列表，等待轮次 5 跨域依赖分析后再最终确认
+
+**进度输出（在轮次3开始处添加，在输出域清单后标注完成）：**
+```
+[3/5 域语义分析] 分析方法签名中...
+...（域识别结果）...
+[3/5 域语义分析] ✓ 确认 {N} 个域（{M} 个待人工确认）
+```
 
 #### 轮次 4：跨域依赖
 
+**进度输出：**
+```
+[4/5 跨域依赖] 扫描 RPC / MQ 调用链...
+```
+
 扫描 RPC 调用、MQ Topic 订阅/发布，绘制域间依赖关系：
 - `@DubboReference` / `@FeignClient` — 识别跨域 RPC 依赖
 - `eventPublisher.publish()` / `kafkaTemplate.send()` / `rocketMQTemplate.send()` — 识别 MQ 发布
@@ -143,6 +314,11 @@ disable: false
 
 #### 轮次 5：数据库表所有权图谱（新增）
 
+**进度输出：**
+```
+[5/5 表所有权] 扫描 Mapper 文件...
+```
+
 扫描所有 XML Mapper 中的表名 + `@TableName` 注解，构建全局表归属地图：
 
 ```
@@ -161,10 +337,23 @@ disable: false
   → 提示「发现 {N} 个无域归属的表，需人工决策归属：{表名列表}」
 ```
 
-#### 轮次 3 末尾：域置信度评分矩阵（新增）
+**进度输出（5轮全部完成后）：**
+```
+[4/5 跨域依赖] ✓ 绘制 {N} 条依赖关系
+[5/5 表所有权] ✓ 覆盖 {M} 张表，发现 {K} 个共享表
+
+扫描完成 ─────────────────────────────────────────────
+确认域：{N} 个 | 待确认：{M} 个 | 孤立表：{K} 张
+下一步：展示域汇总，等待用户确认
+──────────────────────────────────────────────────────
+```
+
+#### 5 轮扫描完成后：域置信度评分矩阵
 
 完成轮次 1-5 后，对每个候选域执行置信度评分（满分 10 分）：
 
+> **执行时机说明**：置信度评分矩阵依赖全部 5 轮的扫描结果（尤其是轮次 4 的跨域依赖和轮次 5 的表所有权），必须在 5 轮全部完成后执行，而非轮次 3 结束后立即执行。
+
 | 评分维度 | 评分规则 | 说明 |
 |---------|---------|------|
 | ① 包名语义内聚度 | 高=2 / 中=1 / 低=0 | 包名与业务术语匹配度 |
@@ -350,11 +539,11 @@ disable: false
 所有域问卷回答完成后，统计：
   已回答问题数 / 总问题数 = 隐性知识补全率
   
-  隐性知识补全率 < 60% → 在 Step 10 完成报告中标注 ⚠️，提示「知识库完整度偏低，建议重新运行访谈」
-  隐性知识补全率 ≥ 60% → 正常进入 Step 4
+  隐性知识补全率 < 60% → 在 Step 11 完成报告中标注 ⚠️，提示「知识库完整度偏低，建议重新运行访谈」
+  隐性知识补全率 ≥ 60% → 正常进入 Step 5
 ```
 
-**如无任何知识空白被发现（全量扫描无触发条件）：** 跳过问卷，直接进入 Step 4，输出：
+**如无任何知识空白被发现（全量扫描无触发条件）：** 跳过问卷，直接进入 Step 5，输出：
 
 ```
 ✓ {domain-name} 域扫描完整，未发现知识空白，跳过访谈问卷
@@ -432,20 +621,96 @@ SubAgent-3 (user域)    ──► 扫描用户全量文件（含Enum/MQ/Config
 1. 汇总 Step 2 轮次 4 的跨域依赖关系图
 2. 对每个域 Skill 的 Section 10 进行回写，填入上游依赖域和下游被依赖域
 3. 同步更新各 Skill frontmatter 的 `upstream_skills` 和 `downstream_skills` 字段
-4. 执行 upstream/downstream 双向同步（详见 `00-skills-builder` Step 4 扩展算法）
+4. 执行 upstream/downstream 双向同步（详见 `modus-skill-creator`（SubAgent 00）Step 4 扩展算法）
 
 **聚合等待：** 所有 SubAgent 完成后，收集各 SubAgent 的完成状态摘要，在主流程中汇总展示：
 
 ```
-✓ modus-biz-order   已生成（14节，18个key_files，6条业务规则，5个API，状态机含4个状态）
-✓ modus-biz-payment 已生成（14节，12个key_files，5条业务规则，3个API，⚠️ 共87个文件，已覆盖50个）
-✓ modus-biz-user    已生成（14节，10个key_files，4条业务规则，6个API）
+✓ modus-biz-order   已生成（v3/17节，18个key_files，6条业务规则，5个API，状态机含4个状态）
+✓ modus-biz-payment 已生成（v3/17节，12个key_files，5条业务规则，3个API，⚠️ 共87个文件，已覆盖50个）
+✓ modus-biz-user    已生成（v3/17节，10个key_files，4条业务规则，6个API）
 
 跨域依赖 Section 10 回写完成：
   order.upstream_skills   = [payment, user]
   payment.downstream_skills = [order, refund]
 ```
 
+### Step 5 补充：生成 Business Skill 时必须填写完整 frontmatter（防腐机制核心）
+
+在生成每个业务 Skill（`.codebuddy/skills/modus-biz-{domain}/SKILL.md`）时，**必须**在 frontmatter 中填写以下**完整字段清单**。这些字段是知识防腐机制的核心，缺一不可：
+
+#### 一、基础元数据字段（必填）
+- `name`: Skill 唯一标识符（与目录名一致）
+- `description`: 一句话描述，必须包含 `[MODUS:BIZ]` 标记
+- `version`: 语义化版本号（初始 1.0.0）
+- `updated`: 最后更新日期（YYYY-MM-DD）
+- `status`: 成熟度状态（初始 draft）
+- `format_version`: 节结构版本（当前 v3）
+- `stale_after_days`: 过期天数阈值（默认 90）
+
+#### 二、防腐机制核心字段（必填，缺少则无法检测代码变更）
+- **`last_referenced`**: 最后引用时间（初始值 = `updated` 日期）
+  - 用途：计算知识衰减，超过 `stale_after_days` 自动降级
+- **`usage_count`**: 使用次数（初始值 = 0）
+  - 用途：成熟度升级判定（draft→verified→proven）
+- **`last_hash`**: 全局 SHA-1（按区块 B 标准算法：对每个文件单独 SHA-1，将「路径:SHA-1」对按文件路径字母序排序后拼接，再整体计算 SHA-1）
+  - 用途：**快速比对**入口——先比对全局 hash，一致则跳过；不一致时展开 `file_hashes` 逐文件比对，精准输出「变更文件清单」
+  - 计算时机：**init 生成 Skill 时即计算并写入**；后续命令引用时重新计算并比对
+  - ⚠️ **所有命令必须使用统一算法**，详见下方「标准 hash 计算算法」区块
+- **`file_hashes`**: 文件级 hash map（`{路径: SHA-1}` 格式，与 `key_files` 中每个文件一一对应）
+  - 用途：全局 hash 不一致时逐文件展开比对，精准定位哪个文件发生了变更，而非笼统标为 stale
+  - 计算时机：与 `last_hash` 同步计算写入；key_files 中每个文件单独计算 SHA-1
+- **`last_verified_by`**: 最后确认人（初始值 = ""，留空）
+  - 用途：记录人工验证信息，升为 verified 时填写
+- **`verified_at`**: 最后验证日期（初始值 = ""，留空）
+  - 用途：记录人工验证时间，由 `/modus:verify` 在升为 verified 时自动写入（YYYY-MM-DD 格式）
+
+#### 三、key_files 填写规则（最多 20 个，用于 hash 检测）
+- 上限 **20 个**文件（覆盖全部 10 类文件类型）
+- 按以下优先级选取（满 20 个时从后往前截断）：
+  - **优先级 1（必选）**：Service、Manager、Mapper/DAO、Domain/Entity
+  - **优先级 2（强烈建议）**：Enum/Constant（状态/类型枚举）、Exception/ErrorCode
+  - **优先级 3（有则加入）**：MQ Consumer/Producer、@Configuration
+- 对每个文件单独计算 SHA-1，按「路径:SHA-1」字母序排序后整体 SHA-1 得到 `last_hash`（禁止内容直接拼接，详见区块 B）
+- 确保 Enum/MQ/ErrorCode/Config 的变化能被 hash 检查感知
+
+#### 四、质量评分字段（必填，用于知识库质量报告）
+- **`domain_confidence`**: 本域的置信度评分（0-10），来自 Step 2 置信度评分矩阵
+- **`invariant_count`**: 生成的业务不变量条目数（Section 15）
+- **`glossary_size`**: 领域词汇表条目数（Section 16）
+- **`hidden_knowledge_rate`**: 隐性知识补全率（0-100，来自 Step 4 访谈问卷）
+- **`contract_version`**: 本域对外暴露接口的当前版本（初始 "1.0"）；接口升级时更新，下游调用域在自己的 Section 10 中记录此版本号
+
+#### 五、跨域依赖字段（由 Section 10 回写阶段自动填入）
+- **`upstream_skills`**: 本域依赖的其他域 Skill 列表
+- **`downstream_skills`**: 依赖本域的其他域 Skill 列表
+- **`stale_cascade`**: 联动失效标记（初始 false）；当任一 upstream_skills 的 hash 变更时自动置为 true
+
+#### 六、外部依赖感知字段（新增，init 自动从 pom.xml/package.json 提取）
+- **`external_deps`**: 本域规范依赖的外部库版本范围（map 格式）
+  - 计算时机：init 生成 Skill 时自动扫描 `pom.xml` 或 `package.json`，提取该域代码中 import 频率最高的第三方库
+  - 格式：`{lib-name}: "semver-range"` — 如 `spring-boot: "~2.7"`、`mybatis-plus: ">=3.5"`
+  - 衰减规则：当 `pom.xml` / `package.json` 中被记录的库发生 **major version 升级**（如 2.x → 3.x）时，自动将本 Skill 降级为 `stale`，并追加注释 `⚠️ 外部依赖 {lib} 升级（{old} → {new}），规范需验证`
+  - 检测时机：`/modus:init`（含 `--lint` 模式）及 `modus update` 执行时
+
+  **自动提取逻辑：** 对每个域，扫描其 `key_files` 中 import 语句，统计来自 `pom.xml` 中 `<dependencies>` 的第三方库（排除 java.*、springframework.*）引用频次，取前 5 个高频库记录版本范围。
+
+  **示例：**
+  ```yaml
+  external_deps:
+    spring-boot: "~2.7"         # 整个项目级别的关键框架
+    mybatis-plus: ">=3.5 <4.0"  # 该域 Mapper 依赖
+    dubbo: "~3.1"               # 该域跨域 RPC 依赖
+  ```
+
+**⛔ 重要提示：** 如果 frontmatter 缺少上述任一防腐字段（特别是 `last_referenced`、`usage_count`、`last_hash`、`file_hashes`、`key_files`），将导致：
+- 无法自动检测代码变更
+- 无法触发 Skill 更新
+- 无法计算知识衰减
+- 防腐机制完全失效
+
+---
+
 ### Step 6：多平台同步（Business Skills）
 
 Business Skills 全部生成后，读取 `modus/config.yaml` 的 `platforms` 字段，将每个业务 Skill 同步到其他已选平台。
@@ -453,25 +718,34 @@ Business Skills 全部生成后，读取 `modus/config.yaml` 的 `platforms` 字
 **读取 platforms 配置：**
 
 ```bash
-# 检查已选平台
+# 检查已选平台（支持 Bash 的平台）
 grep -A5 "^platforms:" modus/config.yaml
 ```
 
+> **Cursor 平台替代**（无 Bash）：使用 Read 工具读取 `modus/config.yaml` 完整内容，解析其中的 `platforms:` 列表。
+
 **各平台同步规则（仅处理 codebuddy 以外的平台）：**
 
 #### Claude Code（`.claude/agents/modus-biz-{domain}.md`）
 
-对每个业务域，创建 Claude Sub-Agent 定义文件：
+对每个业务域，创建 Claude Sub-Agent 定义文件（包含 `<!-- modus:meta -->` 机器可读注释）：
 
 ```markdown
 ---
 name: modus-biz-{domain}
 description: Business knowledge for the {domain} domain — {核心职责一句话}
 ---
+<!-- modus:meta
+last_hash: "{从 CodeBuddy 主文件读取的 last_hash 值}"
+status: "{从 CodeBuddy 主文件读取的 status 值}"
+updated: "{从 CodeBuddy 主文件读取的 updated 日期}"
+-->
 
 {.codebuddy/skills/modus-biz-{domain}/SKILL.md 的完整内容}
 ```
 
+> 注意：`<!-- modus:meta -->` 注释供工具层快速读取核心防腐字段，每次同步时自动从 CodeBuddy 主文件更新，禁止手动修改。
+
 #### Cursor（`.cursor/rules/modus-biz-{domain}.mdc`）
 
 对每个业务域，创建 Cursor 规则文件（带 frontmatter）：
@@ -556,48 +830,25 @@ alwaysApply: false
 
 ### Step 9：生成知识全景目录（knowledge-catalog.md）
 
-在 `modus/knowledge-catalog.md` 创建全景索引，使用升级后的条目格式：
+在 `modus/knowledge-catalog.md` 创建全景索引。
 
-```markdown
-# Modus 知识全景目录
-# 所有 Modus 命令启动时先读此文件（~200 tokens），按需加载完整 Skill
+> **单一真相来源**：目录结构、层级定义、字段格式以 `modus/templates/knowledge-catalog.md` 模板文件为准，本 Step 不再内嵌重复结构。执行时读取该模板文件并按以下规则替换占位符后写入目标路径。
 
-updated: {YYYY-MM-DD}
+**操作步骤：**
+1. 读取 `{MODUS_PACKAGE}/templates/knowledge-catalog.md`（安装包模板）
+2. 将 Layer 2 的 `{domain}` 条目替换为 Step 2/3/4 扫描到的实际业务域列表，每域一行
+3. 完成以下占位符替换：
 
-## 团队约定 (Layer 0-T)
-- **modus-team-conventions**: 代码规范/提交规范/最佳实践
-  [status: draft] [format: v2/14节] [upstream: -]
-  更新: {日期}
-
-## 技术知识 (Layer 1)
-- **modus-tech-wiki**: 跨项目技术经验（反模式、架构决策、性能优化）
-  [status: draft] [format: v2/14节] [upstream: -]
-  更新: {日期}
-
-## 业务知识 (Layer 2)
-- **modus-biz-order**: 订单域 — 创建/状态流转/查询
-  [status: draft] [format: v2/14节] [upstream: payment, user]
-  更新: {日期}  hash: {初始hash}
-- **modus-biz-payment**: 支付域 — 发起/回调/退款
-  [status: draft] [format: v2/14节] [upstream: -]
-  更新: {日期}  hash: {初始hash}
-- **modus-biz-user**: 用户域 — 注册/登录/权限
-  [status: draft] [format: v2/14节] [upstream: -]
-  更新: {日期}  hash: {初始hash}
-
-## 使用说明
-Skill status 生命周期（统一使用 status 字段）：
-- draft    → 初始生成，未经验证
-- verified → 经至少1名开发者在真实需求中验证，且无知识缺失反馈（运行 /modus:verify 升级）
-- proven   → 经≥2个不同工作流验证有效
-- stale    → hash 不匹配或超过 stale_after_days，需更新（禁止直接引用）
-- archived → 域已废弃，不再维护
-
-衰减规则：
-- proven  + 超过 12 个月未引用 → verified
-- verified + 超过 6 个月未引用 → stale（保留人工标注痕迹，非降为 draft）
-- stale   + 超过 stale_after_days → archived（需人工二次确认）
-```
+**写入前必须完成的字段替换（断言，不可遗漏）：**
+- `{YYYY-MM-DD}` → 实际执行日期（如 `2026-05-06`）
+- `{日期}` → 实际执行日期
+- `{domain}` → 扫描到的实际域名（如 `order`、`payment`、`user`）；每个域生成独立条目
+- `{中文域名}` → 对应域的中文名称（如 `订单`、`支付`、`用户`）
+- `{核心职责一句话}` → 对应域的简短职责描述
+- `{依赖域列表，无则写-}` → upstream_skills 依赖关系（Step 2 扫描结果）
+- `{last_hash 前8位}` → 运行 hash 计算后的实际值前 8 位；若无法计算，写入 `⚠️ PENDING` 并在知识目录顶部说明原因
+- `{待填入}` → 域依赖图（从 upstream 字段推导：payment --> order, user 等）
+- 写入后执行自检：`grep -n '{' modus/knowledge-catalog.md | grep -v '<!--'` 输出应为空（注释中的占位符示例不算）
 
 ### Step 10：初始化 modus/config.yaml（若不存在）
 
@@ -681,94 +932,234 @@ constitution:
 ```
 
 ---
+<!-- ============================================================ -->
+<!-- 区块 B：防腐机制总览（执行 Step 5 / verify / refresh 时读取）-->
+<!-- ============================================================ -->
+
+## 防腐机制总览（Skill Anti-corruption Reference）
 
-## 重新初始化（已有 Skill 时）
+> 本章节是防腐机制的**唯一权威来源**。`knowledge-catalog.md`、`modus-init-flow.md` 等其他文档如有冲突，以本章节为准。
 
-如果 `.codebuddy/skills/` 下已存在 `modus-biz-*` 目录：
+### 防腐机制全链路图
 
-提示用户当前已有哪些业务 Skill 及其最后更新时间、status 和 format_version：
+```mermaid
+flowchart TD
+    CMD["Modus 命令加载 Skill\n(vibe/plan/spec/harness)"]
+    CMD --> HASH1["第一步：全局 hash 快速比对\n重算 key_files 拼接 SHA-1"]
 
+    HASH1 -->|"全局 hash 一致"| DECAY["衰减检查\n(基于 last_referenced + usage_count)"]
+    HASH1 -->|"全局 hash 不一致"| HASH2["第二步：file_hashes 逐文件比对\n输出变更文件清单"]
+
+    HASH2 --> STALE_H["status → stale\n警告：列出具体变更文件"]
+    STALE_H -->|"用户确认继续"| USE["使用当前 Skill（可能过时）"]
+    STALE_H -->|"运行 /modus:refresh"| REFRESH["增量更新 Skill\nstatus → draft"]
+
+    DECAY --> ACTIVE{"活跃度判断\n(usage_count)"}
+    ACTIVE -->|"≥10 活跃域"| THRESH_A["衰减阈值\nverified→stale: 12个月\nproven→verified: 24个月"]
+    ACTIVE -->|"3-9 正常域"| THRESH_N["衰减阈值\nverified→stale: 6个月\nproven→verified: 12个月"]
+    ACTIVE -->|"≤2 冷门域"| THRESH_C["衰减阈值\nverified→stale: 3个月\nproven→verified: 6个月"]
+
+    THRESH_A --> DECAY_CHECK{"距 last_referenced\n是否超过阈值？"}
+    THRESH_N --> DECAY_CHECK
+    THRESH_C --> DECAY_CHECK
+
+    DECAY_CHECK -->|"未超过"| VALID["Skill 有效\n更新 last_referenced = 今日"]
+    DECAY_CHECK -->|"已超过"| STALE_D["status 自动降级\nproven→verified 或 verified→stale"]
+
+    VALID --> USE
+
+    subgraph lifecycle [Status 生命周期]
+        direction LR
+        DRAFT["draft\n初始/刷新后"]
+        VERIFIED["verified\n真实使用验证"]
+        PROVEN["proven\n≥2个工作流验证"]
+        STALE_S["stale\nhash不匹配或衰减超期"]
+        ARCHIVED["archived\n废弃（需人工确认）"]
+
+        DRAFT -->|"/modus:verify\n满足对应门槛"| VERIFIED
+        VERIFIED -->|"usage_count≥2\n不同工作流"| PROVEN
+        PROVEN -.->|"超过衰减阈值"| VERIFIED
+        VERIFIED -.->|"超过衰减阈值"| STALE_S
+        STALE_S -->|"/modus:refresh"| DRAFT
+        STALE_S -.->|"超过stale_after_days"| ARCHIVED
+    end
 ```
-当前已有以下业务 Skill：
-  modus-biz-order    v1.2.0  [verified]  更新: 2025-11-20  (v2/14节格式)
-  modus-biz-payment  v1.0.0  [draft]     更新: 2025-10-05  (v1/7节格式 → ⚠️ 建议迁移)
-  modus-biz-user     v2.1.0  [proven]    更新: 2025-12-01  (v2/14节格式)
 
-请选择重初始化模式：
-  1. 全量重建        — 全部删除重新生成（会覆盖所有人工标注）
-  2. 仅更新指定域    — 选择哪些域重新扫描
-  3. 新增缺失域      — 只为新发现的域生成 Skill
-  4. 补全新节（推荐）— 保留已有内容，扫描代码补充生成缺失节 ✨
-     v1(7节) → v2(14节)：补全 8-14 节
-     v2(14节) → v3(17节)：补全 15-17 节（业务不变量/词汇表/新人指南）
+### 防腐字段说明
+
+每个 Business Skill frontmatter 必须包含以下防腐字段：
+
+| 字段 | 类型 | 初始值 | 用途 |
+|------|------|--------|------|
+| `last_referenced` | date (YYYY-MM-DD) | = `updated` 日期 | 计算知识衰减；每次被 vibe/plan/spec/harness 引用时更新为当日 |
+| `usage_count` | integer | 0 | 成熟度升级判定；每次成功引用完成开发任务后 +1 |
+| `last_hash` | string (SHA-1) | 生成时计算的真实全局 hash | 快速检测是否有变更；不一致时展开 `file_hashes` 逐文件比对 |
+| `file_hashes` | map[path→SHA-1] | `{}` (空 map) | 文件级 hash 映射；全局 hash 不一致时使用，精准输出「变更文件清单」 |
+| `key_files` | list | 按优先级选取的源文件路径 | hash 计算的输入；最多 20 个，覆盖全部 10 类文件 |
+| `last_verified_by` | string | "" (空) | 记录最后人工验证人；升为 verified 时填写 |
+
+### Status 生命周期
+
+```
+draft → verified → proven
+             ↑         |  (超过阈值未引用，见下表)
+             └─────────┘
+
+verified + 超过阈值未引用 → stale（阈值按 usage_count 分 3/6/12 个月，见下表）
+stale   + 超过 stale_after_days 天 → archived（需人工二次确认）
+```
+
+> 以下表格为权威衰减阈值定义，ASCII 图仅示意流向；
+
+| status | 含义 | 升级条件 | 禁止行为 |
+|--------|------|---------|---------|
+| `draft` | 初始生成，未经验证 | 运行 `/modus:verify` 且满足四项条件 → `verified` | - |
+| `verified` | 经至少 1 次真实使用验证 | `usage_count ≥ 2` 且不同工作流 → `proven` | - |
+| `proven` | 经 ≥2 个不同工作流验证 | - | - |
+| `stale` | hash 不匹配或衰减超期 | 运行 `/modus:refresh` 更新后 → `draft` | **禁止直接引用** |
+| `archived` | 域已废弃 | - | **禁止引用** |
+
+### 衰减规则（活跃度感知，基于 last_referenced + usage_count）
+
+衰减阈值根据 `usage_count` 动态调整，高频使用的域享有更长保鲜期：
+
+| 活跃度 | usage_count | verified → stale 阈值 | proven → verified 阈值 |
+|--------|------------|----------------------|----------------------|
+| 活跃域 | ≥ 10       | **12 个月**            | **24 个月**            |
+| 正常域 | 3-9        | **6 个月**（默认）        | **12 个月**（默认）       |
+| 冷门域 | ≤ 2        | **3 个月**             | **6 个月**             |
+
+- `proven` + 距 `last_referenced` 超过阈值（见表）→ 自动降为 `verified`
+- `verified` + 距 `last_referenced` 超过阈值（见表）→ 自动降为 `stale`（保留人工标注痕迹，不降回 `draft`）
+- `stale` + 距 `last_referenced` 超过 `stale_after_days`（默认 90 天）→ 建议降为 `archived`（需人工确认）
+
+> **说明**：活跃度分级在每次 Modus 命令加载 Skill 时实时判断，无需手动维护。
+
+### hash 检测触发时机
+
+每次 Modus 命令（`/modus:vibe`、`/modus:plan`、`/modus:spec`、`/modus:harness`）加载某域 Skill 时：
+
+> **标准 hash 计算算法（所有命令必须统一使用）：**
+> 1. 对 key_files 中每个文件**单独**计算 SHA-1（用于 `file_hashes` 逐文件比对）
+> 2. 将「文件路径:SHA-1」对按**文件路径字母序排序**后拼接成字符串，再整体计算一次 SHA-1，得到 `last_hash`
+>
+> ```bash
+> # 标准全局 hash 计算命令（顺序无关，与 file_hashes 完全兼容）
+> for f in $(echo "{key_files}" | tr ' ' '\n' | sort); do
+>   echo "$(shasum -a 1 "$f" | awk '{print $1}'):$f"
+> done | shasum -a 1 | awk '{print $1}'
+> ```
+>
+> **禁止使用「内容拼接后整体计算」的方式**（受文件顺序影响，且无法与 file_hashes 兼容）。
+
+```
+1. 读取 Skill frontmatter 中的 last_hash、file_hashes 和 key_files
+
+2. 【第一步：全局快速比对】
+   按上方标准算法重新计算全局 SHA-1，与 last_hash 比对：
+   ├── 一致 → Skill 有效，正常使用，更新 last_referenced 为今日
+   └── 不一致 → 进入第二步（逐文件比对）
+
+3. 【第二步：文件级精准比对】（仅在全局 hash 不一致时执行）
+   逐文件重新计算 SHA-1，与 file_hashes 中对应值比对，输出变更清单：
+   ⚠️ modus-biz-{domain} 检测到代码变更（{N} 个文件）：
+     ✗ src/.../OrderService.java   — 已变更（业务规则/状态机可能过期）
+     ✗ src/.../OrderStatus.java    — 已变更（枚举值可能新增/修改）
+     ✓ src/.../OrderMapper.java    — 无变更
+   建议运行 /modus:refresh {domain} 增量更新 Skill
+   继续使用当前 Skill（内容可能过时）？[y/N]
+
+   → 将 status 降为 stale，更新 last_referenced 为今日
 ```
 
-**选择「补全新节」时的执行规则：**
-- 读取已有 Skill 的已有节，**不修改任何已有内容**
-- 仅追加缺失节（满足域适用性条件的节，不满足则跳过，不填占位符）
-- 对 v2 → v3 迁移：补充 Section 15（业务不变量）、Section 16（领域词汇表）、Section 17（新人上手指南）
-- 同步扩展 frontmatter 的 `key_files`（补充优先级 2/3 类文件，上限 20 个）
-- 更新 `format_version`（v1→v2 或 v2→v3）、`version`（小版本 +1）和 `updated` 日期
+### 同步副本管理规约
+
+> 本节规定多平台同步副本（Claude Agent 文件、Cursor 规则等）的防腐字段处理标准，所有平台同步操作均须遵守。
 
-**迁移完成后：** 自动触发 Step 5 多平台同步逻辑（更新 Claude Code、Cursor、Copilot 对应文件）
+#### 双重 frontmatter 的结构问题
 
-无论何种选择，都更新 `modus/knowledge-catalog.md` 的索引信息。
+通过 Step 6 多平台同步生成的 Claude Agent 文件（`.claude/agents/modus-biz-{domain}.md`）采用**双重 frontmatter 格式**：
 
+```markdown
+---
+name: modus-biz-{domain}          ← Claude Agent 顶层 frontmatter（Claude 平台解析）
+description: ...
 ---
 
-### Step 5 补充：生成 Business Skill 时必须填写完整 frontmatter（防腐机制核心）
+---
+name: modus-biz-{domain}          ← Skill frontmatter（被解析为 Markdown 正文，非顶层 YAML）
+last_hash: "xxx"
+last_referenced: ...
+...
+---
 
-在生成每个业务 Skill（`.codebuddy/skills/modus-biz-{domain}/SKILL.md`）时，**必须**在 frontmatter 中填写以下**完整字段清单**。这些字段是知识防腐机制的核心，缺一不可：
+# 业务知识正文 ...
+```
 
-#### 一、基础元数据字段（必填）
-- `name`: Skill 唯一标识符（与目录名一致）
-- `description`: 一句话描述，必须包含 `[MODUS:BIZ]` 标记
-- `version`: 语义化版本号（初始 1.0.0）
-- `updated`: 最后更新日期（YYYY-MM-DD）
-- `status`: 成熟度状态（初始 draft）
-- `format_version`: 节结构版本（当前 v3）
-- `stale_after_days`: 过期天数阈值（默认 90）
+**结构约束**：防腐字段（`last_hash`、`file_hashes`、`last_referenced`、`usage_count` 等）在 Claude Agent 文件中位于正文区，**无法被标准 YAML 解析器从顶层 frontmatter 中读取**。
 
-#### 二、防腐机制核心字段（必填，缺少则无法检测代码变更）
-- **`last_referenced`**: 最后引用时间（初始值 = `updated` 日期）
-  - 用途：计算知识衰减，超过 `stale_after_days` 自动降级
-- **`usage_count`**: 使用次数（初始值 = 0）
-  - 用途：成熟度升级判定（draft→verified→proven）
-- **`last_hash`**: key_files 内容 SHA-1 哈希值（初始值 = ""，留空）
-  - 用途：检测代码变更，触发 Skill 更新
-  - 计算时机：首次被 plan/spec/harness 引用时自动计算并写入
-- **`last_verified_by`**: 最后确认人（初始值 = ""，留空）
-  - 用途：记录人工验证信息，升为 verified 时填写
+#### 机器可读 meta 注释（供工具层解析）
 
-#### 三、key_files 填写规则（最多 20 个，用于 hash 检测）
-- 上限 **20 个**文件（覆盖全部 10 类文件类型）
-- 按以下优先级选取（满 20 个时从后往前截断）：
-  - **优先级 1（必选）**：Service、Manager、Mapper/DAO、Domain/Entity
-  - **优先级 2（强烈建议）**：Enum/Constant（状态/类型枚举）、Exception/ErrorCode
-  - **优先级 3（有则加入）**：MQ Consumer/Producer、@Configuration
-- 这些文件的内容拼接后计算 SHA-1 得到 `last_hash`
-- 确保 Enum/MQ/ErrorCode/Config 的变化能被 hash 检查感知
+为使工具层能从 Claude Agent 文件中快速读取核心防腐字段，**每个 Claude Agent 文件的顶层 frontmatter 之后、第二个 frontmatter 之前**，插入一段 HTML 注释：
 
-#### 四、质量评分字段（必填，用于知识库质量报告）
-- **`domain_confidence`**: 本域的置信度评分（0-10），来自 Step 2 置信度评分矩阵
-- **`invariant_count`**: 生成的业务不变量条目数（Section 15）
-- **`glossary_size`**: 领域词汇表条目数（Section 16）
-- **`hidden_knowledge_rate`**: 隐性知识补全率（0-100，来自 Step 4 访谈问卷）
+```markdown
+---
+name: modus-biz-{domain}
+description: ...
+---
+<!-- modus:meta
+last_hash: "{last_hash_value}"
+status: "{status_value}"
+updated: "{updated_date}"
+-->
 
-#### 五、跨域依赖字段（由 Section 10 回写阶段自动填入）
-- **`upstream_skills`**: 本域依赖的其他域 Skill 列表
-- **`downstream_skills`**: 依赖本域的其他域 Skill 列表
+---
+name: modus-biz-{domain}
+...
+```
 
-**重要提示：** 如果 frontmatter 缺少上述任一防腐字段（特别是 `last_referenced`、`usage_count`、`last_hash`、`key_files`），将导致：
-- 无法自动检测代码变更
-- 无法触发 Skill 更新
-- 无法计算知识衰减
-- 防腐机制完全失效
+**规则**：
+- `<!-- modus:meta ... -->` 注释在每次 Step 6 同步时自动从 CodeBuddy 主文件写入
+- 工具层优先读取此注释，不解析第二层 frontmatter
+- 注释内容与 CodeBuddy 主文件保持严格一致，不允许手动修改
+
+#### 权威源与副本的责任边界
+
+| 文件 | 角色 | 防腐字段权威性 | 更新方式 |
+|------|------|-------------|---------|
+| `.codebuddy/skills/modus-biz-{domain}/SKILL.md` | **权威源** | 所有防腐字段的唯一权威存储 | 命令直接写入 |
+| `.claude/agents/modus-biz-{domain}.md` | 只读快照 | 仅通过 `<!-- modus:meta -->` 注释暴露核心字段 | Step 6 同步时自动更新 |
+| `.cursor/rules/modus-biz-{domain}.mdc` | 只读快照 | 不存储防腐字段（仅业务上下文） | Step 6 同步时自动更新 |
+
+**关键原则**：
+- 所有防腐机制的触发（hash 比对、衰减计算、`usage_count` 更新）**均只操作 CodeBuddy 权威源文件**
+- 副本文件发生变更不触发防腐机制，不影响 status
+- 若副本与权威源不一致（如手动修改副本），以权威源为准，下次 Step 6 同步时强制覆盖
 
 ---
+<!-- ============================================================ -->
+<!-- 区块 C：Business Skill 标准格式参考（执行 Step 5 时按需读取）-->
+<!-- ============================================================ -->
 
 ## Business Skill 标准格式参考（v3/17节）
 
+### 多语言适配说明
+
+本模板以 **Java + Spring Boot + MyBatis** 为默认实现（最常见的企业 Java 技术栈）。对于其他语言/框架的项目，按以下规则调整：
+
+| 调整点 | Java（默认） | Go + Gin/gRPC | Python + FastAPI |
+|--------|------------|--------------|-----------------|
+| **Section 3 字段表** | Java 类型（`Long`、`String`） | Go 类型（`int64`、`string`） | Pydantic 模型字段（含 `Field(...)` 校验） |
+| **Section 6 特有模式** | `AopContext.currentProxy()`、`@Transactional`、`BaseRpcResponse` | 中间件链（`middleware`）、`defer` 错误处理、gRPC status codes | `async/await` 模式、依赖注入（`Depends()`）、Pydantic 校验器 |
+| **Section 7 代码示例** | Java 类风格 | Go 函数风格（接收者方法） | Python async 函数风格 |
+| **Section 8 状态机** | 包含 `@Transactional` 注解 | 包含数据库事务块（`db.Begin()`/`tx.Commit()`） | 包含 SQLAlchemy 事务上下文 |
+| **Section 12 SQL 模式** | MyBatis XML Mapper | GORM / sqlx 查询 | SQLAlchemy ORM / 原生 SQL |
+| **key_files 文件类型** | `.java` | `.go` | `.py` |
+
+> **操作指引**：当 Step 2 检测到项目为 Go/Python 项目时，生成 Business Skill 前须先调整以上差异项，其余节格式保持不变。
+
+---
+
 ```markdown
 ---
 name: modus-biz-{domain}
@@ -780,12 +1171,14 @@ format_version: v3          # v1=7节 | v2=14节 | v3=17节（当前默认，含
 stale_after_days: 90        # 超过此天数自动降为 stale（默认 90 天）
 last_referenced: {YYYY-MM-DD}
 usage_count: 0
-last_hash: ""               # SHA-1(key_files 内容拼接)，前置更新时自动计算并填入
+last_hash: ""               # 全局 SHA-1（key_files 所有内容拼接后计算）；init 时写入，引用时快速比对
+file_hashes: {}             # 文件级 hash map：{路径: SHA-1}，与 key_files 一一对应；全局 hash 不一致时展开精准比对
 last_verified_by: ""        # 最后确认人（升为 verified 时填写）
 domain_confidence: 0        # 域置信度评分（0-10），来自 Step 2 评分矩阵
 invariant_count: 0          # Section 15 业务不变量条目数
 glossary_size: 0            # Section 16 领域词汇表条目数
 hidden_knowledge_rate: 0    # 隐性知识补全率（0-100），来自 Step 4 访谈问卷
+contract_version: "1.0"     # 本域对外暴露接口的当前版本；升级接口时同步更新，下游调用域在 Section 10 中记录此版本
 upstream_skills:            # 本 Skill 在 Section 10 中依赖的其他域 Skill
   - modus-biz-payment
   - modus-biz-user
@@ -811,6 +1204,27 @@ key_files:                  # 关键源文件列表，用于 hash 检查（最
 
 > 由 Modus Skills Builder 自动生成。[MODUS:BIZ]
 
+---
+
+> **渐进加载模式（Agent 按任务类型选择，降低 token 消耗）：**
+>
+> | 模式 | 读取范围 | 预估 token | 适用场景 |
+> |------|---------|-----------|---------|
+> | **极简模式** | Section 1、2、15 | ~500 tokens | 快速了解业务边界和不变量约束 |
+> | **开发模式** | Section 1-8、10 | ~1500 tokens | 新增功能、接口开发 |
+> | **审查模式** | Section 3、8、13、15 | ~1000 tokens | Code Review、架构评审 |
+> | **排查模式** | Section 9、13 + Section 8 | ~600 tokens | 线上 Bug 排查、异常分析 |
+> | **完整模式** | 全量（Section 1-17） | ~3500 tokens | 首次接触本域、生成设计文档 |
+>
+> **员工速读导航：**
+> 初次接触本域 → 推荐阅读顺序：**Section 16（词汇表）→ Section 17.B（新人手册）→ Section 8（状态机）→ Section 3（业务规则）**
+> 排查线上问题 → 重点读：**Section 9（错误码）→ Section 13（开发陷阱）→ Section 15（业务不变量）**
+>
+> **Skill 状态：** `[SKILL_STATUS]` | **最后更新：** `[UPDATED]` | **hash：** `[HASH_PREFIX]`
+> 若 status 为 `stale`，禁止直接引用，先运行 `/modus:refresh {domain}`
+
+---
+
 ## 1. 域概述
 
 {业务域的职责边界和核心价值，2-3 句话，人类可读}
@@ -837,12 +1251,44 @@ CANCELLED(4, "已取消")
 
 ## 3. 业务规则 [process] [guideline]
 
+**Section 3 子节划分规范（必须按此结构组织，禁止混写）：**
+
+### 核心字段说明
+
 Section 3 最低内容门槛：每个核心字段必含：Java 类型、是否非空、业务含义、关联枚举（如有）
 
-- [process]   {流程规则：如 订单状态只能按 CREATED→PAID→COMPLETED 单向流转}
+| 字段 | Java 类型 | 非空 | 业务含义 | 关联枚举 |
+|------|----------|------|----------|----------|
+| {fieldName} | {类型} | ✓/- | {业务含义} | {枚举类名，无则-} |
+
+### 业务流程规则 [process]
+
+- [process] {流程规则：如 订单状态只能按 CREATED→PAID→COMPLETED 单向流转}
+
+### 推荐做法 [guideline]
+
 - [guideline] {推荐做法：如 退款金额必须 ≤ 原始支付金额，在 Service 层校验}
-- [pitfall]   {已知坑：如 并发创建时若不加锁会出现重复订单}
-- [decision]  {架构决策：如 选择 MQ 异步通知而非同步 RPC，原因是解耦和削峰}
+
+### 架构决策 [decision]
+
+- [decision] {架构决策：如 选择 MQ 异步通知而非同步 RPC，原因是解耦和削峰}
+
+> **⚠️ 内容边界约束（含信号词分流指引）：**
+>
+> 当不确定某条内容该写在哪个 Section 时，根据以下**信号词**判断归属：
+>
+> | 信号词模式 | 正确归属 | 典型例子 |
+> |----------|---------|---------|
+> | 「必须/禁止 + 违反=Bug/生产事故」 | Section 15 `[invariant]` | 「退款金额必须 ≤ 原始支付金额，否则为严重 Bug」 |
+> | 「推荐/建议/最佳实践」 | Section 3 `[guideline]` | 「建议在 Service 层做二次校验，而非只依赖前端」 |
+> | 「如果 A 发生则执行 B 流程」 | Section 3 `[process]` | 「支付超时后订单状态自动流转至 CANCELLED」 |
+> | 「选择方案 A 而非 B，因为...」 | Section 3 `[decision]` | 「选用 MQ 异步通知而非同步 RPC，原因是解耦削峰」 |
+> | 「曾经踩过/容易犯/易错点」 | Section 13 `[pitfall]` | 「曾因未加分布式锁导致重复订单，教训：必须加锁」 |
+> | 「新人首次开发前需了解/开发时注意」 | Section 17 | 「新人必读：状态枚举只存 code 值而非 name()」 |
+>
+> - `[process]`/`[guideline]`/`[decision]` 写本节，`[pitfall]` 写 Section 13，`[invariant]` 写 Section 15
+> - 禁止在 Section 3 中混入「不变量」内容（如「金额必须 > 0」——这是约束而非规则，属 Section 15）
+> - 若某子节无内容，可省略该子节标题
 
 ## 4. 关键文件索引 [model]
 
@@ -870,15 +1316,27 @@ Section 5 最低内容门槛：每个接口必含：入参校验规则、成功
 
 ## 7. 典型代码示例
 
+**Section 7 最低内容门槛：**
+- 示例代码必须来自实际扫描的源码（不能是纯伪代码框架）
+- 每段示例必须附带关键步骤的内联说明注释
+- 至少包含 1 个「写入/变更」场景 + 1 个「查询/权限」场景（若存在）
+- 示例中必须体现 Section 6 中列出的项目特有模式（如 AopContext、BaseRpcResponse 等）
+
 \`\`\`java
-// 订单创建的标准模式
+// 订单创建的标准模式（来自 OrderService.createOrder()）
 public OrderDTO createOrder(CreateOrderRequest request) {
-    // 1. 参数校验（Service 层）
-    // 2. 业务校验（余额、库存）
-    // 3. 创建 Domain 对象
-    // 4. 持久化
-    // 5. 发送 MQ 通知
-    // 6. 返回 DTO
+    // 1. 参数校验（Service 层，非 Controller 层）
+    validateCreateRequest(request);
+    // 2. 业务校验（余额、库存、限购等）
+    checkBusinessRules(request);
+    // 3. 创建 Domain 对象（领域逻辑封装在 Domain 中，不直接操作 Entity）
+    Order order = Order.create(request);
+    // 4. 持久化（通过 Mapper，注意：Mapper 必须在 dao 包下）
+    orderMapper.insert(order);
+    // 5. 发送 MQ 通知（异步，不影响主流程事务）
+    orderEventPublisher.publish(new OrderCreatedEvent(order));
+    // 6. 返回 DTO（使用 BaseRpcResponse 包装）
+    return BaseRpcResponse.build(OrderConverter.toDTO(order));
 }
 \`\`\`
 
@@ -897,13 +1355,52 @@ stateDiagram-v2
     REFUNDING --> REFUNDED : processRefund() @Transactional
     CREATED --> CANCELLED : cancelOrder() 超时/主动取消 @Transactional
     PAID --> CANCELLED : cancelOrder() 支付后取消（触发退款）
+    CREATED --> CREATE_FAILED : [异常流] 创建失败 (虚线)
+    PAID --> PAY_FAILED : [异常流] 支付失败回调 (虚线)
 \`\`\`
 
+> **图例说明：** 实线 = 正常流转；虚线 = 异常流/超时流（在实际 Mermaid 中用 `-->` 配合状态名区分，说明见下方子节）
+
+### 正常流转表
+
 | 起始状态 | 目标状态 | 触发条件 | 触发方法 | 事务保护 |
 |---------|---------|---------|---------|---------|
 | CREATED | PAID | 支付成功回调 | payOrder() | ✓ @Transactional |
 | PAID | COMPLETED | 用户确认收货 | completeOrder() | ✓ @Transactional |
 
+### 异常流（失败态处理）
+
+**前置检测条件：** 域中存在 `FAILED`/`ERROR`/`EXCEPTION` 类后缀状态，或 try-catch 中有状态变更操作，才生成本子节；否则省略。
+
+| 起始状态 | 失败目标状态 | 触发条件 | 触发方法 | 失败后处理 |
+|---------|-----------|---------|---------|----------|
+| CREATING | CREATE_FAILED | 数据库写入异常/库存不足 | createOrder() catch 块 | 记录失败原因，前端展示错误信息 |
+| PAYING | PAY_FAILED | 支付网关超时/余额不足 | payOrder() catch 块 | 订单回退可支付状态，允许重新支付 |
+
+> 若无失败态枚举值，写「暂无发现，随工作流积累」。
+
+### 超时自动流转
+
+**前置检测条件：** 域中存在定时任务（`@XxlJob`/`@Scheduled`/`XXXTimeoutJob`），或有 TTL 相关业务逻辑，才生成本子节；否则省略。
+
+| 当前状态 | 超时时长 | 流转目标 | 触发方式 | 补偿操作 |
+|---------|---------|---------|---------|---------|
+| CREATED | 30 分钟未支付 | CANCELLED | OrderTimeoutJob @XxlJob | 释放库存，发送取消通知 |
+| REFUNDING | 24 小时未处理 | 需人工介入 | RefundTimeoutJob @XxlJob | 创建人工工单，发送告警 |
+
+> 若无超时自动流转，写「暂无发现，随工作流积累」。
+
+### 补偿机制（MQ 失败重试与死信）
+
+**前置检测条件：** 域中存在 MQ 消费者（`@KafkaListener`/`@RocketMQMessageListener`），才生成本子节；否则省略。
+
+| 消息类型 | 正常消费 | 失败处理 | 重试策略 | 超限处理 |
+|---------|---------|---------|---------|---------|
+| payment.success | 订单状态流转至 PAID | 记录失败日志，状态不变 | 重试 3 次，间隔 1/2/5 分钟 | 进入死信队列，人工处理 |
+| order.timeout | 订单状态流转至 CANCELLED | 幂等检查通过则忽略 | 重试 1 次 | 记录告警日志 |
+
+> 若无 MQ 消费，写「暂无发现，随工作流积累」。
+
 ## 9. 错误码与异常 [pitfall]
 
 （无条件生成。若为空则写「暂无发现，随工作流积累」，此为合法初始内容，质量自检通过。）
@@ -918,19 +1415,27 @@ stateDiagram-v2
 （无条件生成。若为空则写「暂无发现，随工作流积累」，此为合法初始内容。由主流程 Section 10 回写阶段统一填入。）
 
 **上游依赖（本域调用的其他域）：**
-| 依赖域 | 交互方式 | 调用点 | 说明 |
-|--------|---------|-------|------|
-| payment | RPC @DubboReference | OrderService.createOrder() | 发起支付 |
-| user | RPC @DubboReference | OrderService.checkUser() | 校验用户状态 |
+| 依赖域 | 交互方式 | 调用点 | 接口版本 | 降级预案 | 说明 |
+|--------|---------|-------|---------|---------|------|
+| payment | RPC @DubboReference | OrderService.createOrder() | v2.1 | 超时 3s 后返回支付处理中，异步重试 | 发起支付 |
+| user | RPC @DubboReference | OrderService.checkUser() | v1.0 | 超时降级：跳过用户状态校验，记录告警 | 校验用户状态 |
 
 **下游被依赖（调用本域的其他域）：**
-| 调用域 | 交互方式 | 场景 |
-|--------|---------|------|
-| refund | RPC | 退款申请时查询原订单 |
+| 调用域 | 交互方式 | 接口版本（本域提供）| 场景 |
+|--------|---------|-----------------|------|
+| refund | RPC | v1.2 | 退款申请时查询原订单信息 |
+
+> **契约版本维护规则：**
+> - 本域对外暴露接口的当前版本记录在 frontmatter 的 `contract_version` 字段
+> - 调用方在本节上游依赖表中记录**调用时使用的版本号**
+> - 接口升级时：① 更新 `contract_version` ② 通知下游调用域更新其 Section 10 记录 ③ 触发 hash 更新
 
 ## 11. 数据流向 [process]
 
-**前置检测条件：** 域中存在 `@KafkaListener` / `sendMessage()` / `@RocketMQMessageListener` 才生成本节；否则整节省略。
+**前置检测条件：** 域中存在以下任意一项即生成本节；否则整节省略：
+- MQ 消息：`@KafkaListener` / `@RocketMQMessageListener` / `kafkaTemplate.send()` / `rocketMQTemplate.send()`
+- Spring 事件：`ApplicationEventPublisher.publishEvent()` / `@EventListener` / `implements *EventListener` 接口
+- 其他异步数据流：`@Async` + 跨域调用、`CompletableFuture` 跨域通信
 
 | 方向 | Topic/方法 | 触发时机 | 消费者/生产者 | 幂等保障 |
 |------|-----------|---------|------------|---------|
@@ -958,7 +1463,11 @@ Section 12 最低内容门槛：每条复杂 SQL 必含：查询语义说明、J
 
 ## 14. 扩展点 [decision]
 
-**前置检测条件：** 域中存在 `interface + 多实现类` 或 `@ConditionalOn*` 注解才生成本节；否则整节省略。
+**前置检测条件：** 域中存在以下任意一项即生成本节；否则整节省略：
+- 标准扩展点：`interface + ≥2 个实现类`（策略模式、模板方法模式）
+- 配置条件化：`@ConditionalOn*` 注解（Spring Boot 条件化装配）
+- 项目级接口：`项目定义的 *EventListener` / `*Handler` / `*Strategy` / `*Processor` 接口 + ≥1 个实现类
+- 插件化机制：`@Plugin` / `@Extension` / SPI `ServiceLoader` 加载点
 
 | 扩展点 | 接口/注解 | 当前实现 | 扩展方式 |
 |--------|---------|---------|---------|
@@ -991,27 +1500,84 @@ Section 12 最低内容门槛：每条复杂 SQL 必含：查询语义说明、J
 
 ## 17. 新人上手指南 [process]
 
-（无条件生成。基于本 Skill 内容自动合成，目标：读完本节即可开始在本域开发，无需找业务方答疑。）
+（无条件生成。本节分为两个独立子节，分别服务不同受众：Agent 快速定位 + 员工新人入门。）
+
+---
+
+### 17.A — Agent 快速定位指南（机器优先）
+
+> 适用受众：AI Agent 执行任务时，根据任务类型找到最小必读路径。
+
+#### 按任务类型的最小读取路径
+
+| 任务类型 | 必读 Section | 关键文件 | 核心约束提示 |
+|---------|------------|---------|------------|
+| **新增 API 接口** | 5（API契约）→ 3（业务规则）→ 15（不变量） | `{Domain}Controller.java` / `{Domain}Facade.java` | 确认权限注解、幂等需求（见 Section 5）|
+| **修改业务规则** | 3（业务规则）→ 8（状态机）→ 15（不变量） | `{Domain}Service.java` / `{Domain}Manager.java` | 修改后同步维护 Section 15 不变量 |
+| **新增/修改状态流转** | 8（状态机）→ 3（流程规则）→ 9（错误码） | `{Domain}Status.java` / `{Domain}Service.java` | 同步更新 Section 8 状态图和转换表 |
+| **Code Review** | 15（不变量）→ 13（陷阱）→ 8（状态机）→ 3（规则） | — | 重点检查不变量是否有校验代码 |
+| **排查线上 Bug** | 9（错误码）→ 13（陷阱）→ 8（状态机） | — | 优先查错误码，再对照状态机异常流 |
+| **新增 MQ 消息** | 11（数据流向）→ 3（规则）→ 15（不变量） | `{Domain}Consumer.java` / `{Domain}Producer.java` | 确认幂等保障机制（见 Section 11）|
+| **修改数据库查询** | 12（SQL模式）→ 4（文件索引）→ 2（核心实体） | `{Domain}Mapper.java` / XML Mapper | 注意慢查询风险（见 Section 12）|
+
+---
+
+### 17.B — 员工新人入门手册（人类优先）
+
+> 适用受众：初次接触本域的研发同学，目标是读完本节即可开始独立开发，无需找业务方反复答疑。
+
+#### 开发前必读清单
+
+> 建议逐项确认后再开始开发：
+
+1. 理解 `{Domain}Status` 枚举的 {N} 个状态及合法转换（见 Section 8 状态机）
+2. 了解 Section 15 的 {M} 条业务不变量，违反将导致生产事故
+3. 熟悉 Section 6 的项目特有编码模式（如 `AopContext.currentProxy()`、`BaseRpcResponse.build()`）
+4. 阅读「高频踩坑」中摘录的前 3 条 Section 13 陷阱
 
-### 开发前必读清单
+#### 本域关键设计决策历史
 
-- [ ] 理解 {Domain}Status 枚举的 {N} 个状态及合法转换（见 Section 8）
-- [ ] 了解 Section 15 的 {M} 条业务不变量，违反将导致生产事故
-- [ ] 熟悉 Section 6 的项目特有模式（如 AopContext.currentProxy()）
-- [ ] 确认本地环境的依赖配置（MQ Topic、RPC 地址等，见 Section 11）
+（自动从 Section 3 `[decision]` 条目中提取，补充设计背景；无内容时写「暂无记录，随工作流积累」）
 
-### 常见开发场景速查
+> **为什么这样设计？**（帮助新人理解现有架构，而不是仅知道怎么做）
 
-| 场景 | 入口文件 | 关键类 | 注意事项 |
-|------|---------|-------|---------|
-| 新增业务状态 | {Domain}Status.java | {Domain}Status / {Domain}Service | 必须同步更新状态机校验逻辑（见 Section 8）|
-| 新增查询接口 | {Domain}Facade.java | {Domain}QueryService | 注意多租户 tenantId 过滤 |
-| 新增写入接口 | {Domain}Controller.java | {Domain}Service | 确认是否需要幂等保护（见 Section 5）|
-| 修改业务规则 | {Domain}Service.java | {Domain}Manager | 更新后同步维护 Section 15 不变量 |
+| 设计决策 | 选择方案 | 未选方案 | 设计理由 |
+|---------|---------|---------|---------|
+| {决策描述，如「通知方式」} | {选用方案，如「MQ 异步」} | {弃用方案，如「同步 RPC」} | {简要理由，如「解耦 + 削峰，支付服务故障不影响订单主流程」} |
 
-### 高频踩坑（新人必看，精选自 Section 13）
+#### 本地环境搭建 Checklist
 
-（自动提取 Section 13 前 3 条 [pitfall]，无内容时写「暂无记录，随工作流积累」）
+（基于 Section 11 数据流向和 Section 10 跨域依赖自动生成；无相关配置时写「无特殊本地配置要求」）
+
+> **说明：** 以下为纯文字编号清单，本地启动前逐项确认：
+
+1. **MQ Topic 配置**：确认 `application-local.yml` 中 Topic 名称与联调环境一致
+   - 本域订阅 Topic：{来自 Section 11 的订阅 Topic 列表，无则写「-」}
+   - 本域发布 Topic：{来自 Section 11 的发布 Topic 列表，无则写「-」}
+2. **RPC 依赖服务**：确认以下服务在本地可访问（或已 Mock）
+   - {来自 Section 10 的上游依赖域列表，无则写「-」}
+3. **数据库**：确认本地 DB 已执行最新 migration，重点关注以下表
+   - {来自 Section 2 核心实体对应的主表，无则写「-」}
+4. **配置开关**：确认以下特性开关状态
+   - {来自 Section 14 扩展点的条件化配置，无则写「-」}
+
+#### 首次开发任务推荐
+
+（推荐从最简单的查询接口入手，逐步熟悉域内结构）
+
+推荐路径：**查询接口** → **写入接口** → **状态流转** → **跨域集成**
+
+#### 常见问题 FAQ
+
+（来自 Step 4 访谈问卷的回答摘要；无内容时写「暂无记录，随工作流积累」）
+
+| 问题 | 答案 | 来源 |
+|------|------|------|
+| {高频问题，如「为什么枚举存 code 不存 name？」} | {答案} | {代码推断 / [人工补充: {日期}]} |
+
+#### 高频踩坑（精选自 Section 13 前 3 条）
+
+（自动提取 Section 13 前 3 条 `[pitfall]`，无内容时写「暂无记录，随工作流积累」）
 
 1. ...
 2. ...
@@ -1034,19 +1600,31 @@ Section 12 最低内容门槛：每条复杂 SQL 必含：查询语义说明、J
 **执行逻辑：**
 
 ```
+0. 判断当前 draft 状态类型（影响 verified 门槛）：
+   - draft(fresh)：usage_count = 0（Skill 刚生成，尚未用于真实任务）
+   - draft(used) ：usage_count ≥ 1（已用于至少一次开发，有反馈基础）
+
 1. 读取 .codebuddy/skills/{skill-name}/SKILL.md 的 frontmatter
+
 2. 运行质量自检清单：
    □ Section 3：每个 Entity 字段均有业务含义注释？
    □ Section 5：所有 Facade 方法均列出了错误码？
    □ Section 8（如存在）：所有 status 枚举值均出现在状态图中？
    □ Section 12（如存在）：每条 SQL 均有查询语义说明？
    □ 无条件生成节（9/10/13）：
-       - 「暂无发现，随工作流积累」是合法初始内容 → 质量自检通过 ✓
-       - 仅在 status 为 stale 时再次执行自检，若三节仍为此内容
-         → 标注 ⚠️「知识库超期且无积累，建议重新扫描或人工补充」
+       - draft(fresh)：「暂无发现，随工作流积累」是合法初始内容 → 自检通过 ✓
+       - draft(used) ：若三节仍为「暂无发现」→ 标注 ⚠️「已使用但知识未积累，建议补充后再 verify」
+
+3. 检查 verified 升级条件：
 
-3. 检查 verified 四项条件：
-   条件 1：所有无条件生成节（9/10/13）非空且非占位符
+   【draft(fresh) 门槛（宽松）】
+   条件 1：所有节结构存在且符合标准格式（无条件节可为「暂无发现」）
+   条件 2：质量自检清单零 ⚠️ 警告
+   条件 3：计算 key_files 当前 hash，与 last_hash 一致
+   条件 4：人工确认（见下方交互）
+
+   【draft(used) 门槛（严格）】
+   条件 1：所有无条件生成节（9/10/13）非「暂无发现」占位符，有真实内容
    条件 2：质量自检清单零 ⚠️ 警告
    条件 3：计算 key_files 当前 hash，与 last_hash 一致（无 stale）
    条件 4：人工确认（见下方交互）
@@ -1058,7 +1636,7 @@ Section 12 最低内容门槛：每条复杂 SQL 必含：查询语义说明、J
   → 用户回复 y：
       记录：last_verified_by: {运行者用户标识或 "self-verified"}
             verified_at: {今日 YYYY-MM-DD}
-      条件 4 ✅ 通过，继续检查 verified 合计结论
+      条件 4 ✅ 通过
 
   → 用户回复 N 或跳过：
       输出：「条件 4 未满足（尚无开发者真实使用反馈）
@@ -1069,27 +1647,60 @@ Section 12 最低内容门槛：每条复杂 SQL 必含：查询语义说明、J
    last_verified_by: {运行者标识}
    updated: {今日日期}
    version: 小版本 +1（如 v1.0.0 → v1.0.1）
-5. 未通过 → 列出未达标条件，不修改 status
+5. 未通过 → 列出未达标条件，并说明属于 draft(fresh) 还是 draft(used) 门槛，不修改 status
 ```
 
 ---
 
 ### `/modus:refresh {domain}`
 
-**定义**：对大域未覆盖的文件执行补充扫描，增量合并至已有 Skill。
+**定义**：重新扫描指定域的代码文件，检测变更并增量更新已有 Skill。
+
+**触发场景：**
+- 代码发生较大变更，`last_hash` 已失效（status = stale）
+- 想主动刷新某域的业务知识（如新增了大量接口、重构了状态机）
 
 **执行逻辑：**
 
 ```
-1. 读取 .codebuddy/skills/modus-biz-{domain}/SKILL.md 末尾的「未覆盖文件列表」
-   （由 Step 4 大域分批策略生成的 ⚠️ 提示块）
-2. 若无未覆盖文件列表 → 输出「{domain} 已全量覆盖，无需补扫」
-3. 若有 → 启动补充扫描 SubAgent，按 10 类优先级顺序读取剩余文件
-4. 将新发现的知识增量合并至已有 Skill（不覆盖已有内容，append-only）
-5. 更新 ⚠️ 提示块：
-   - 已补扫文件标记 ✓
-   - 剩余未扫文件更新列表
-   - 若所有文件已覆盖，移除 ⚠️ 提示块
-6. 重新计算 key_files hash 并写入 last_hash
-7. 更新 updated 日期和 version（小版本 +1）
+1. 读取 .codebuddy/skills/modus-biz-{domain}/SKILL.md 的 frontmatter：
+   - key_files 列表
+   - last_hash（上次生成时的 SHA-1 值）
+   - status（若已为 archived，询问用户是否继续）
+
+2. 重新计算当前 key_files 的 SHA-1 hash（按区块 B 标准算法）：
+   - 逐一对 key_files 中的每个文件单独计算 SHA-1
+   - 将「文件路径:SHA-1」对按文件路径字母序排序后拼接，再整体计算 SHA-1 得到 last_hash
+
+3. 比对 hash：
+   - 若 hash 一致 → 输出「{domain} 代码无变更，Skill 仍为最新，无需刷新」
+   - 若 hash 不一致 → 继续执行补扫流程
+
+4. 启动补充扫描 SubAgent，按 10 类文件类型重新扫描：
+   - 优先扫描 key_files 中已有文件（比对变更内容）
+   - 再扫描该域目录下新增但不在 key_files 中的文件
+   - 按 git 最近修改时间排序，优先读取最近变更的文件
+
+5. 将新发现的知识增量合并至已有 Skill（append-only，不覆盖已有人工标注内容）：
+   - 新增的枚举值补充至 Section 2
+   - 新增的业务规则补充至 Section 3
+   - 新增的 API 补充至 Section 5
+   - 新增的陷阱补充至 Section 13
+   - 新增的不变量补充至 Section 15
+
+6. 更新 frontmatter：
+   - 重新计算并写入新的 last_hash
+   - 若 status 为 stale → 升级为 draft（需人工重新 /modus:verify 才能到 verified）
+   - 更新 updated 日期
+   - version 小版本 +1（如 1.2.0 → 1.2.1）
+
+7. 触发多平台同步（若 platforms 已配置）：
+   - 更新 Claude Agent 文件、Cursor 规则等
+
+8. 输出刷新摘要：
+   ✓ {domain} 域刷新完成
+     代码变更：hash 从 {old_hash[:8]} → {new_hash[:8]}
+     补充内容：Section 2（+2条枚举）、Section 13（+1条陷阱）
+     Skill 版本：v{old} → v{new}
+     status：stale → draft（运行 /modus:verify 升级为 verified）
 ```