@modus-ai/modus 0.2.1 → 0.2.2

package/templates/skills/modus-harness-agents/00-skills-builder/SKILL.md

@@ -13,7 +13,7 @@ disable: false
 
 ## 职责
 
-从项目代码和工作流产物中提炼业务知识，生成或更新标准格式的 Skill 文件，并维护知识全景目录（`knowledge-catalog.md`）。支持五种调用模式，覆盖从初始化到持续积累的完整知识生命周期。
+从项目代码和工作流产物中提炼业务知识，生成或更新标准格式的 Skill 文件（v2/14节），并维护知识全景目录（`knowledge-catalog.md`）。支持五种调用模式，覆盖从初始化到持续积累的完整知识生命周期。
 
 ---
 
@@ -21,32 +21,64 @@ disable: false
 
 ### 模式 A：全量初始化（来自 /modus:init）
 
-为每个确认的业务域从零生成 `modus-biz-{domain}/SKILL.md`，初始 maturity 为 `draft`。
+为每个确认的业务域从零生成 `modus-biz-{domain}/SKILL.md`，初始 `status: draft`，`format_version: v2`。
 
 ### 模式 B：增量更新（来自 /plan 或 /spec 前置，含 hash 快速检查）
 
 更新已有 `modus-biz-*/SKILL.md`，刷新过时内容，补充新发现的知识。
 
-**执行前必须先进行 hash 检查，避免不必要的全量扫描：**
+**执行前必须先进行 hash 检查 + 防腐校验，避免不必要的全量扫描：**
 
-#### 模式 B — Step 0：hash 检查（每个域独立检查）
+#### 模式 B — Step 0：使用时防腐校验 + hash 检查
 
-1. 读取 SKILL.md frontmatter 的 `last_hash` 和 `key_files`
-2. 使用 Bash 计算当前 `key_files` 内容的 SHA-1 摘要：
+**防腐校验（先于 hash 检查执行）：**
 
-   ```bash
-   shasum -a 1 {file1} {file2} ... | awk '{print $1}' | sort | shasum -a 1 | awk '{print $1}'
-   ```
+```
+加载前校验流程：
+  1. 读取 Skill frontmatter 中的 status 和 stale_after_days
+  2. 检查是否超期（当前日期 - updated > stale_after_days）：
+     → 超期 → 将 status 降为 stale，强提示：
+       「⚠️ modus-biz-{domain} 已超过 {stale_after_days} 天未更新，已降为 stale 状态，
+         禁止直接引用，请先运行更新或 /modus:verify 确认」
+  3. 读取 key_files_hash（last_hash）与 key_files 列表
+```
 
-3. 对比结果：
-   - **hash 一致（且 last_hash 非空）** → 跳过全量扫描，仅更新 `last_referenced` 字段，输出：  
-     `✓ modus-biz-{domain} 无变化（hash 匹配），跳过更新（节省 ~2000 tokens）`
-   - **hash 不一致 或 last_hash 为空** → 执行下方完整流程
-   - **key_files 为空 或 某文件不存在** → 视为「已变化」，执行完整流程
+**hash 检查（防腐校验通过后执行）：**
+
+```bash
+# 计算当前 key_files 内容的 SHA-1 摘要
+shasum -a 1 {file1} {file2} ... | awk '{print $1}' | sort | shasum -a 1 | awk '{print $1}'
+```
+
+**对比结果分级处理：**
+
+| 结果 | 行为 |
+|------|------|
+| hash 一致 + 未超期 | 直接使用，仅更新 `last_referenced`，输出：`✓ modus-biz-{domain} 无变化（hash 匹配），跳过更新（节省 ~2000 tokens）` |
+| hash 不一致（≤2文件变化） | [warn] 提示「Skill 可能需要更新，继续使用还是先刷新？」，由用户决策 |
+| hash 不一致（>2文件变化） | [stale] 自动将 status 降为 stale，强提示更新，执行完整更新流程 |
+| key_files 为空 或 某文件不存在 | 视为「已变化」，执行完整流程 |
+| last_hash 为空 | 视为「已变化」，执行完整流程 |
 
 #### 模式 B — 完整更新流程（仅 hash 不匹配时执行）
 
-对比现有 Skill 内容与最新代码，**仅修改有变化的部分**，保留无变化的内容。  
+对比现有 Skill 内容与最新代码，**仅修改有变化的部分**，保留无变化的内容。
+
+**Section 10 生成策略（在代码扫描完成后执行）：**
+
+```
+Step B-10-1：轻量读取所有 .codebuddy/skills/modus-biz-*/SKILL.md 的 frontmatter
+             （仅读 name、upstream_skills 字段，每个 Skill 约 20 tokens）
+Step B-10-2：扫描当前域代码中的跨域调用：
+             - @DubboReference / @FeignClient（跨包 Service 引用）
+             - @Autowired + 非本包 Service（Spring 跨域注入）
+             - eventPublisher.publish() / kafkaTemplate.send() / rocketMQTemplate.send()（事件/消息发布）
+Step B-10-3：取 Step B-10-1 和 Step B-10-2 的并集，确认上游依赖域列表
+Step B-10-4：对每个上游域深度读取其 SKILL.md 的 Section 1（域概述）和 Section 5（API 契约）
+Step B-10-5：生成 Section 10 内容（上游依赖域 + 交互方式 + 下游被依赖域）
+Step B-10-6：触发跨域联动提示（检查引用了本域的其他 Skill，提示是否同步检查）
+```
+
 更新完成后，**必须**将新 hash 写入 frontmatter 的 `last_hash` 字段。
 
 ### 模式 C：后置回写（来自 /plan、/spec 归档后）
@@ -57,7 +89,7 @@ disable: false
 - delta spec 的 MODIFIED Requirements → 更新对应 `[guideline]`
 - design.md 的架构决策章节 → `[decision]` 追加到对应业务 Skill 或 modus-tech-wiki
 
-### 模式 D：知识提取（来自 Harness ARCHIVE 阶段）——新增
+### 模式 D：知识提取（来自 Harness ARCHIVE 阶段）
 
 从 Harness 全流程产物中系统性提取知识条目，判断提升路径，写回 Skill 并更新 catalog。
 
@@ -72,24 +104,24 @@ disable: false
 | cr-report.md 的 P1/P2 问题 | 规范违反模式 | `[pitfall]` `[guideline]` | modus-team-conventions |
 | 07-deploy-status.md 的部署注意事项 | 环境特殊配置 | `[guideline]` | modus-tech-wiki |
 
-**成熟度提升判定：**
+**成熟度提升判定（统一使用 status 字段）：**
 - 本次工作流成功验证了某条知识 → `draft` 升为 `verified`，更新 `last_referenced` 和 `usage_count +1`
 - 若该知识已是 `verified` 且跨不同工作流被引用 ≥2 次 → 升为 `proven`
 
 **hash 更新（ARCHIVE 阶段必做）：**
-- 对每个在本次 Harness 中被修改的业务 Skill（modus-biz-*），在写入知识后**重新计算 hash**：
-  ```bash
-  shasum -a 1 {key_files...} | awk '{print $1}' | sort | shasum -a 1 | awk '{print $1}'
-  ```
-- 将新 hash 写入 SKILL.md frontmatter 的 `last_hash` 字段
-- 这确保下次 plan/spec 前置检查时，能正确跳过未变化的 Skill
+
+```bash
+shasum -a 1 {key_files...} | awk '{print $1}' | sort | shasum -a 1 | awk '{print $1}'
+```
+
+将新 hash 写入 SKILL.md frontmatter 的 `last_hash` 字段。
 
 **衰减检查（每次模式 D 执行时顺带检查）：**
 - 扫描 catalog，检查 `last_referenced` 超过阈值的条目
 - `proven` + 超过 12 个月未引用 → 降为 `verified`，追加注释 `⚠️ 12个月未引用，请验证是否仍然适用`
-- `verified` + 超过 6 个月未引用 → 降为 `draft`，追加注释 `⚠️ 6个月未引用，可能已过时`
+- `verified` + 超过 6 个月未引用 → 降为 `stale`（非降为 draft，保留人工标注痕迹），追加注释 `⚠️ 6个月未引用，已降为 stale`
 
-### 模式 E：基础 Skill 初始化（来自 /modus:init）——新增
+### 模式 E：基础 Skill 初始化（来自 /modus:init）
 
 初始化团队约定 Skill（Layer 0-T）和技术知识 Skill（Layer 1）。
 
@@ -106,33 +138,449 @@ disable: false
 
 ## 执行流程
 
-### Step 1：定位相关代码/产物
+### Step 1：定位相关代码/产物（全量扫描）
+
+根据调用模式和传入的域/产物信息，**全量定位**代码文件或产物文件。
+
+#### Step 1.0：语言自动检测前置逻辑
+
+在执行扫描前，先检测项目语言类型：
+
+```
+检测根目录文件：
+  pom.xml 或 build.gradle 存在              → Java 模式（执行完整 10 类流程）
+  requirements.txt 或 pyproject.toml 存在  → 附加 Python 扩展扫描（在 Java 10 类后执行）
+  package.json + (*.vue 或 *.tsx) 存在     → 附加前端扩展扫描（在 Java 10 类后执行）
+  多种同时存在                              → 多语言项目，分模块分别扫描，各自执行对应扫描流程
+```
+
+#### Step 1.1：Java 10 类文件全量扫描（主体，必须执行）
+
+按以下**严格顺序**扫描，每类**全量读取，不跳过，不抽样**：
+
+```
+① Controller/Facade     → API 契约、权限注解（@UserAuthorization/@PreAuthorize）
+② Service/Manager       → 业务规则、事务边界（@Transactional）、分布式锁
+③ Domain/Entity         → 核心字段、业务方法、状态字段
+④ Mapper/DAO            → 数据操作模式（注意：Mapper 必须在 dao 包下）
+⑤ XML Mapper            → 关键 SQL（JOIN/子查询/复杂条件/动态SQL）
+⑥ Enum/Constant         → 完整枚举值和业务含义（状态枚举、类型枚举）
+⑦ DTO/VO/Request/Response → 字段约束、校验规则（@NotNull/@Valid等）
+⑧ Exception/ErrorCode   → 错误码体系（extends RuntimeException / ErrorCode枚举）
+⑨ MQ Consumer/Producer  → 消息契约（@KafkaListener/@RocketMQMessageListener/sendMessage）
+⑩ @Configuration        → 开关配置、扩展点注册（@ConditionalOn*）
+```
+
+**注解式 SQL 补充（⑤ 的补充）：** 除 XML Mapper 外，还需扫描 Mapper 接口中含以下注解且 SQL 长度超过 1 行的方法，一并纳入 Section 12 提炼：
+- `@Select`、`@Insert`、`@Update`、`@Delete`（MyBatis 注解式 SQL）
+
+#### Step 1.2：Python 扩展扫描（6 类，在 Java 10 类完成后附加执行）
 
-根据调用模式和传入的域/产物信息，定位代码文件或产物文件。
+| 优先级 | 文件类型 | 对应 Java 层 | 扫描重点 |
+|--------|---------|------------|---------|
+| ① | `router.py` / `*_handler.py` / `*_view.py` | Controller/Facade | 路由定义、请求参数、响应结构 |
+| ② | `*_service.py` / `*_manager.py` | Service/Manager | 业务规则、调用链 |
+| ③ | `*_model.py` / `*_schema.py` | Domain/Entity + DTO | Pydantic 字段约束、枚举、验证规则 |
+| ④ | `exceptions.py` / `errors.py` | Exception/ErrorCode | 错误码体系、HTTP 状态码映射 |
+| ⑤ | `config.py` / `settings.py` | @Configuration | 环境变量、开关配置 |
+| ⑥ | `requirements.txt` / `pyproject.toml` | pom.xml | 技术栈与关键依赖版本 |
 
-**扫描策略（按优先级）：**
-1. 读取传入的「关键文件列表」
-2. 按包名/目录名模糊匹配（如 `order`、`Order` 相关文件）
-3. 扫描 Controller/Facade 层入口，顺调用链向下读取 Service/Manager/Mapper
+#### Step 1.3：前端扩展扫描（6 类，在 Java 10 类完成后附加执行）
 
-### Step 2：提炼知识内容
+| 优先级 | 文件类型 | 对应 Java 层 | 扫描重点 |
+|--------|---------|------------|---------|
+| ① | `*Page.vue` / `*View.tsx` / `pages/` | Controller/Facade | 页面入口、路由绑定、权限控制 |
+| ② | `components/*.vue` / `components/*.tsx` | — | 公共组件、Props 接口 |
+| ③ | `*Store.ts` / `use*.ts` (Composables) | Service | 状态管理、业务逻辑封装 |
+| ④ | `*Api.ts` / `request/*.ts` / `services/*.ts` | Mapper/DAO | API 调用契约、请求/响应类型 |
+| ⑤ | `types/*.ts` / `*.d.ts` / `enums/*.ts` | DTO/Enum | 类型定义、枚举值、接口契约 |
+| ⑥ | `vite.config.ts` / `env.*` / `config/*.ts` | @Configuration | 构建配置、环境变量、扩展点 |
 
-从代码或产物中提炼以下信息，并打上知识类型标签：
+#### Step 1.4：代码注释全量挖掘（与 1.1-1.3 并行执行，所有语言通用）
 
-**知识五类型（MECE 原则）：**
+在执行 1.1-1.3 文件扫描的同时，对所有已读文件的注释内容执行分类提取：
+
+```
+注释类型分类与映射规则：
+
+① //TODO: / // TODO 注释
+   → 提取完整注释文本 + 所在文件:行号
+   → 写入 Section 13（常见开发陷阱）：
+     [pitfall] {TODO内容}（技术债务，来源: {file}:{line}）
+
+② //FIXME: / // FIXME 注释
+   → 提取完整注释文本 + 所在文件:行号
+   → 写入 Section 13：
+     [pitfall] [已知缺陷] {FIXME内容}（来源: {file}:{line}）
+
+③ //WARN / // 注意 / // 重要 / // ⚠️ 注释
+   → 提取完整注释文本 + 所在文件:行号
+   → 写入 Section 15（业务不变量）：
+     [invariant] {WARN内容}（代码注释推断，来源: {file}:{line}）
+
+④ //HACK / // workaround / // 临时方案 注释
+   → 提取完整注释文本 + 所在文件:行号
+   → 写入 Section 13：
+     [pitfall] [技术债务/临时方案] {HACK内容}（来源: {file}:{line}）
+
+⑤ Javadoc @deprecated 注解
+   → 提取废弃方法名 + @deprecated 说明文本
+   → 写入 Section 9（错误码与异常）附注：
+     [deprecated] {方法名}：{废弃说明}，建议替代：{@see 或说明}
+
+注释汇总统计（Step 1 完成后输出）：
+  发现 TODO {N}条 | FIXME {M}条 | WARN/注意 {W}条 | HACK {H}条 | @deprecated {D}条
+  → TODO > 3 条时：触发知识空白标记，供 modus-init Step 3.5 访谈问卷生成使用
+```
+
+---
+
+### Step 2：提炼知识内容（含 8-17 节 10 类新知识）
+
+从代码或产物中提炼以下信息，并打上知识类型标签。
+
+**知识六类型（MECE 原则）：**
 - `[model]` 实体定义、数据结构、关系图、枚举
 - `[decision]` 技术选型、架构决策及理由
 - `[guideline]` 推荐做法（`recommend`）或禁止做法（`avoid`）
 - `[pitfall]` 已知风险、故障模式、排查步骤
 - `[process]` 业务流程、状态机、操作步骤
+- `[invariant]` 业务不变量：系统必须始终为真的约束，违反即为 Bug（新增）
 
-**核心提炼内容：**
+**核心提炼内容（Section 1-7）：**
 - 核心实体（Entity/Domain）：类名、关键字段（业务含义重要的）、枚举值
 - 业务规则（从 Service/Manager 中提炼）：`if/else` 分支、前置校验、状态流转
 - 关键文件索引：各层次主要类文件路径
 - API 契约（从 Controller/Facade 提炼）：接口路径、关键请求/响应字段
 - 典型代码示例（可选，高价值）：体现项目特有模式的代码片段
 
+---
+
+---
+
+**业务语义挖掘（Step 2 必须执行，在 Section 1-7 提炼完成后立即运行）：**
+
+#### 2A. If/Else 业务分支挖掘
+
+```
+扫描目标：Service / Manager 类中所有 if/else 分支（含 switch/case）
+
+提炼映射规则：
+  if (status == X) throw new XxxException → [invariant] 状态前置约束
+    示例：[invariant] 订单已取消时不允许支付（来源: OrderService:92，错误码: ORDER_CANCELLED）
+
+  if (amount < 0 || amount == 0) throw → [invariant] 数值范围约束
+    示例：[invariant] 订单金额必须 > 0（来源: OrderService:84）
+
+  if (count >= N) throw → [invariant] 数量上限约束
+    示例：[invariant] 同一用户当日限购 5 件（来源: OrderManager:127）
+
+  if (role != X) throw / if (!hasPermission) → 写入 Section 5 权限约束列
+    示例：[权限] 仅 ADMIN 角色可调用 batchCancel 接口
+
+  if (A && B) { multiStepLogic } → [process] 复合前置条件业务流程
+    示例：[process] 同时满足「已支付」且「未发货」时才允许申请退款
+
+重要：每条 if/else 推断的业务规则必须标注来源（文件:行号），便于溯源核实
+```
+
+#### 2B. 校验注解完整提取
+
+```
+扫描目标：所有 DTO / VO / Request 类的字段注解
+
+提炼映射规则（全部写入 Section 5 API 契约的「入参校验规则」列）：
+  @NotNull / @NotBlank / @NotEmpty  → 必填约束：{字段名}（{字段业务含义}）为必填项
+  @Min(value) / @Max(value)         → 数值范围：{字段名} 范围 [{Min}, {Max}]
+  @Size(min, max)                   → 长度约束：{字段名} 长度 [{min}, {max}]
+  @Pattern(regexp = "...")           → 格式约束：{字段名} 格式要求：{正则含义描述}
+  @Valid + 嵌套对象类型              → 嵌套校验：{字段名} 嵌套校验 {嵌套类名}
+  自定义 @Constraint 注解            → 业务级校验：{注解名}，详见 {Validator实现类}
+
+若校验注解中含有 message 属性：提取 message 内容作为「校验失败提示」
+```
+
+#### 2C. 状态机完整性四步法（替换原有不完整逻辑）
+
+```
+四步法还原完整状态机：
+
+Step 2C-1：收集所有枚举值
+  → 找到含 status/state 字段的 Entity，读取对应枚举类的全部枚举值
+
+Step 2C-2：全局搜索 setStatus() / updateStatus() 调用
+  → 提取每处调用的上下文：在哪个方法中、什么 if 条件下、目标状态是什么
+  → 构建「触发方法 → 目标状态」映射表
+
+Step 2C-3：全局搜索 if.*status == / if.*status != 判断
+  → 提取状态前置条件：哪些方法要求当前状态为某值才能执行
+  → 识别禁止转换：if (status == X) throw → 表示 X → Y 转换被明确禁止
+
+Step 2C-4：构建完整转换矩阵（含禁止转换，不允许留空）：
+
+  | 当前状态 | 目标状态 | 触发条件 | 触发方法 | 事务保护 | 是否禁止 |
+  |---------|---------|---------|---------|---------|---------|
+  | CREATED | PAID    | 支付成功回调 | payOrder() | @Transactional | - |
+  | PAID    | COMPLETED | 确认收货 | completeOrder() | @Transactional | - |
+  | COMPLETED | CANCELLED | - | - | - | ❌ 抛 InvalidTransitionException |
+
+  孤立状态（无入/出转换的枚举值）→ 标记为 ⚠️「孤立状态，触发 Step 3.5 访谈」
+```
+
+#### 2D. 自定义校验器扫描
+
+```
+扫描目标：implements Validator / ConstraintValidator 的实现类
+
+提炼规则：
+  → 读取 isValid() / validate() 方法体中的判断逻辑
+  → 将每条判断转为 [invariant] 标签写入 Section 15（业务不变量）
+  → 提取 buildConstraintViolationWithTemplate() 中的错误描述作为不变量说明
+
+示例：
+  IdCardValidator.isValid() 中：if (!IdCardUtils.isValid(value)) → false
+  → [invariant] 身份证号码必须通过算法校验（来源: IdCardValidator，触发: 注册接口）
+```
+
+---
+
+**Section 8-17 扩展知识提炼规则（执行前必须先运行「域适用性前置检测」）：**
+
+#### 8. 状态机（Section 8）
+
+**域适用性前置检测：** 扫描域内 Entity/Domain 类，若存在 `status`/`state` 字段则生成本节；否则**整节省略，禁止填占位符**。
+
+提炼规则：
+- 检测含 `status/state` 字段的 Entity，提取所有 `if status == X` 分支和状态变更方法
+- 生成 Mermaid `stateDiagram-v2` 转换图（优先，ASCII 作备选）
+- 每条转换必须包含：起始状态、目标状态、触发条件、触发方法名、是否有事务保护
+
+#### 9. 错误码与异常（Section 9）
+
+**域适用性前置检测：** 无条件生成；若为空则写「暂无发现，随工作流积累」（此为合法初始内容，质量自检通过）。
+
+提炼规则：
+- 扫描所有 `extends RuntimeException` 类和 `ErrorCode` 枚举
+- 提取码值 + 触发场景 + HTTP 状态码映射 + 处理建议
+
+#### 10. 跨域依赖（Section 10）
+
+**域适用性前置检测：** 无条件生成；若为空则写「暂无发现，随工作流积累」。
+
+**模式 A（全量初始化）：** Section 10 **不由单个 SubAgent 独立生成**，而是由 `modus-init` 主流程在所有 SubAgent 完成后，统一执行一轮跨域依赖分析后回写。
+
+**模式 B（增量更新）：** 按本文档「模式 B — Section 10 生成步骤」执行（Step B-10-1 至 B-10-6）。
+
+**九种跨域依赖识别模式（全部扫描，不可遗漏）：**
+
+```
+① @DubboReference / @FeignClient 注解
+   → 强类型 RPC 依赖，标记交互方式为「RPC」
+   → 提取被调用接口名、调用场景（所在方法名）
+
+② MQ 发布（显式依赖）
+   → kafkaTemplate.send() / rocketMQTemplate.send() / eventPublisher.publishEvent()
+   → 标记方向「本域 → 消费域」，提取 Topic 名称
+
+③ MQ 订阅（反向依赖）
+   → @KafkaListener(topics=...) / @RocketMQMessageListener(topic=...)
+   → 标记方向「生产域 → 本域」，提取 Topic 名称
+
+④ Spring @EventListener（应用内事件总线）
+   → 全局搜索 @EventListener(XxxEvent.class)
+   → 追踪 ApplicationEventPublisher.publishEvent(new XxxEvent()) 的发布域
+   → 完整映射「事件生产域 → 事件消费域」的隐式依赖
+
+⑤ @Autowired / 构造函数注入跨域 Service（新增）
+   → 扫描所有 @Autowired 字段和构造函数参数
+   → 识别注入的 Bean 是否来自其他业务域的包路径
+   → 区分两种情况：
+     「编排层合理调用」: Facade/Controller 层注入其他域 Service（允许，标记为 [orchestration]）
+     「领域层穿透」: Service 直接注入其他域 Service（标记 ⚠️ [domain-leak]，建议重构）
+
+⑥ 共享数据库表访问（新增）
+   → 扫描所有 XML Mapper 和 @TableName 注解
+   → 识别被多个域 Mapper 访问的同一张表
+   → 输出：[shared-table] 表 {table_name} 同时被 {域A} 和 {域B} 访问，存在隐式耦合
+   → 标注「主域」（拥有该表 DDL 的域）和「读域」（只读访问的域）
+
+⑦ 配置驱动的条件依赖（新增）
+   → 扫描 @ConditionalOnBean(XxxBean.class) / @ConditionalOnProperty
+   → 识别当前 Bean 激活依赖的其他域 Bean
+   → 输出：[conditional-dep] 本域的 XxxConfig 仅在 {条件} 时激活，软性依赖 {其他域}
+
+⑧ 静态工具类跨域调用
+   → 扫描 import 语句，识别对其他业务域包路径下工具类的引用
+   → 标记为「工具类依赖」（低风险但需记录）
+
+⑨ 数据库外键/逻辑外键
+   → 扫描 Entity 中的关联 ID 字段（如 userId, paymentId 等，类型为 Long/String）
+   → 推断逻辑外键关系：本域 Entity 持有的其他域实体 ID
+   → 标注「逻辑外键」（非 DB 约束，但代表数据级耦合）
+
+提炼后在 Section 10 按上游/下游结构分类展示：
+  上游依赖（本域调用的其他域）
+  下游被依赖（调用本域的其他域）
+  共享数据（共享表或逻辑外键）
+  条件依赖（需特定配置才激活的依赖）
+```
+
+#### 11. 数据流向（Section 11）
+
+**域适用性前置检测：** 域中存在 `@KafkaListener` / `sendMessage()` / `@RocketMQMessageListener` 才生成；否则整节省略。
+
+提炼规则：
+- 提取 `@KafkaListener`/`@RocketMQMessageListener` topic 订阅
+- 提取 `sendMessage()` / `kafkaTemplate.send()` 发布
+- 提取 `@Async` 方法链
+
+#### 12. 关键 SQL 模式（Section 12）
+
+**域适用性前置检测：** 域中存在 XML Mapper 文件或含任何 SQL 注解时生成（**不再要求「2表JOIN」门槛**，全量记录重要 SQL）；否则整节省略。
+
+**全量 SQL 扫描规则（新增）：**
+
+```
+扫描范围：
+  - 所有 XML Mapper 中的 <select>/<insert>/<update>/<delete> 语句（全量）
+  - @Select/@Insert/@Update/@Delete 注解（超过 1 行的）
+
+对每条 SQL，提取以下信息：
+  - WHERE 条件字段列表 → 推断应有索引（如 WHERE status=? AND tenant_id=? → 建议复合索引 idx_status_tenant）
+  - ORDER BY 字段       → 排序索引分析（ORDER BY create_time DESC → 需要 create_time 索引）
+  - LIMIT/分页          → 是否存在深分页风险（LIMIT offset, size 且 offset 无上限 → 深分页警告）
+  - JOIN 表数量         → 超过 2 表 JOIN 标记为「复杂 SQL」
+  - 子查询              → 标记为「子查询 SQL」，关注 EXISTS/IN 性能
+```
+
+**N+1 查询风险检测（新增）：**
+
+```
+扫描目标：Service / Manager 类中的 for 循环（for/forEach/stream）
+
+检测规则：
+  for 循环体内包含 Mapper.selectXxx() 调用 → [risk:N+1]
+  stream.map(item -> mapper.findById(item.getId())) → [risk:N+1]
+
+输出格式：
+  [risk:N+1] {ClassName}.{methodName}()：
+    循环内调用 {MapperClass}.{queryMethod}()
+    风险：N 个{实体}→ N+1 次 SQL，建议改为批量查询 {MapperClass}.selectByIds(ids)
+    来源: {file}:{line}
+```
+
+**慢查询风险标注规则（新增）：**
+
+```
+以下条件之一触发慢查询风险标注：
+
+① 无 LIMIT 且无 WHERE 限制的全表查询
+   → [risk:slow-query] selectAll()：无分页保护，全表扫描风险（建议加 LIMIT 或时间范围条件）
+
+② WHERE 条件字段无明确索引提示，且条件列数 > 3
+   → [risk:slow-query] {queryId}：多字段 WHERE 条件，可能无法命中索引（建议分析执行计划）
+
+③ LIKE '%keyword%'（前缀模糊匹配）
+   → [risk:slow-query] {queryId}：前缀 LIKE 导致索引失效（建议使用全文索引或 ES）
+
+④ ORDER BY 非索引字段
+   → [risk:slow-query] {queryId}：按非索引字段排序，可能引发 filesort（建议加索引）
+
+⑤ IN 子句的值列表超过 1000 个（循环构建 IN 时）
+   → [risk:slow-query] {queryId}：IN 列表过大可能导致慢查询
+```
+
+提炼规则（原有规则保留并增强）：
+- 读取 XML Mapper + 注解式 SQL（全量，不限复杂度）
+- 每条 SQL 必含：查询语义说明、WHERE 条件字段、推断索引、N+1 风险评估、深分页风险评估
+- 对复杂 SQL（多表JOIN/子查询）额外标注：JOIN 表关系、数据量级预估
+
+#### 13. 常见开发陷阱（Section 13）
+
+**域适用性前置检测：** 无条件生成；若为空则写「暂无发现，随工作流积累」。
+
+提炼规则：
+- 扫描 `// TODO`/`// FIXME`/`// WARN`/`// 注意` 注释，结合代码上下文归纳
+- 扫描已知反模式：
+  - 循环内 DB 调用（for 循环内包含 Mapper.selectXxx 调用）
+  - 缺失 `@Transactional` 的多写操作（多个 Mapper.insertXxx/updateXxx 无事务包裹）
+  - `@Transactional` 同类内部直接调用（未通过 AopContext.currentProxy()）
+
+#### 14. 扩展点（Section 14）
+
+**域适用性前置检测：** 域中存在 `interface + 多实现类` 或 `@ConditionalOn*` 注解才生成；否则整节省略。
+
+提炼规则：
+- 检测 `interface` + 多实现类 + `Map<String, T>` 注入模式（策略模式）
+- 检测 `@ConditionalOn*` 注解（开关式扩展点）
+
+#### 15. 业务不变量（Section 15）—— 新增
+
+**域适用性前置检测：** 无条件生成；若为空则写「暂无发现，随工作流积累」（此为合法初始内容）。
+
+提炼规则（优先级顺序，全部执行）：
+1. **2A if/else 推断结果** → 将所有 `[invariant]` 标签条目写入本节，标注来源行号
+2. **2D 自定义校验器** → 将 isValid()/validate() 中的判断逻辑转为不变量条目
+3. **Step 1.4 代码注释挖掘** → 将 `//WARN / //注意 / //重要` 注释写入本节（标注来源）
+4. **Step 3.5 人工访谈回答** → 将用户补充的业务约束写入本节（标注 `[人工补充: {日期}]`）
+
+每条不变量必含：不变量描述、验证位置（类名:行号或方法名）、违反后果（异常类或错误码）、来源标注
+
+**模式 B 增量更新：** 追加新发现条目至末尾，不覆盖已有条目（特别是人工补充条目）。
+
+#### 16. 领域词汇表（Section 16）—— 新增
+
+**域适用性前置检测：** 无条件生成；若无特殊术语则写「暂无特定领域术语，使用通用定义」（此为合法初始内容）。
+
+提炼规则（按优先级）：
+1. 枚举类的枚举值 + description/desc/label/msg 字段 → 业务术语定义
+2. Domain/Entity 类的类级 Javadoc → 实体中文含义与边界说明
+3. Service/Manager 方法 Javadoc 中出现的业务专名词（如「结算」「对账」「预授权」「防重」）
+4. Step 1.4 代码注释中出现的业务术语（`// 注意：此处的"XX"指的是...` 类注释）
+5. Step 3.5 人工访谈中用户提及的专业术语（标注 `[人工补充]`）
+
+每个术语必含：术语名、定义（1-2句）、与通用概念的区别（若无区别可省略）
+
+#### 17. 新人上手指南（Section 17）—— 新增
+
+**域适用性前置检测：** 无条件生成，必须非空。
+
+**生成规则（从本 Skill 其他节内容自动合成，禁止写空占位符）：**
+
+```
+开发前必读清单（从各节自动提取，至少 3 条）：
+  → 从 Section 8（若存在）：「理解 {Domain}Status 枚举的 {N} 个状态及合法转换（见 Section 8）」
+  → 从 Section 15：「了解 Section 15 的 {invariant_count} 条业务不变量，违反将导致生产事故」
+  → 从 Section 6：「熟悉项目特有编码模式：{Section 6 的核心 guideline 提炼}」
+  → 从 Section 11（若存在）：「确认本地 MQ Topic 和 RPC 地址配置（见 Section 11）」
+
+常见开发场景速查（从 Section 4/5/14 自动合成，至少 3 行）：
+  → 从 Section 8 + Section 4：新增/修改业务状态 → 入口文件 + 关键类 + 注意事项
+  → 从 Section 5 + Section 4：新增查询接口 → 入口 Facade/Controller + 注意多租户
+  → 从 Section 5 + Section 4：新增写入接口 → 入口 Controller/Service + 幂等提醒
+  → 从 Section 14（若存在）：新增扩展实现 → 实现接口 + 注册方式
+
+高频踩坑（从 Section 13 自动提取 TOP 3）：
+  → 取 Section 13 中 [pitfall] 标签的前 3 条
+  → 若 Section 13 为空或仅有「暂无发现」，写「暂无记录，随工作流积累」
+```
+
+---
+
+**Section 内容质量最低门槛（v3 版本，含新节要求）：**
+
+| 节 | 必须包含的最低内容 |
+|----|------------------|
+| Section 3 核心模型 | 每个核心字段必含：Java 类型、是否非空、业务含义、关联枚举（如有） |
+| Section 5 API 契约 | 每个接口必含：入参校验规则（含 2B 注解提取）、成功返回结构、错误码列表、是否需要幂等、权限注解值 |
+| Section 8 状态机 | 每条转换必含：起始状态、目标状态、触发条件、触发方法名、是否有事务保护；禁止转换也必须列出 |
+| Section 12 SQL 模式 | 每条 SQL 必含：查询语义、WHERE 条件字段、推断索引、N+1 风险评估、慢查询风险评估 |
+| Section 15 业务不变量 | 每条不变量必含：描述（精确到具体数值/条件）、验证位置（类名:行号）、违反后果、来源标注 |
+| Section 16 领域词汇表 | 每个术语必含：中文定义（1-2句）；若无特殊术语写合法占位 |
+| Section 17 新人指南 | 必须非空；开发场景速查至少 3 行；高频踩坑至少 1 条或写「暂无记录，随工作流积累」 |
+
+---
+
 ### Step 3：并发冲突检测（写入前必做）
 
 多人协作时，同一个 Skill 可能被并发更新。写入前先检查：
@@ -159,32 +607,117 @@ disable: false
 - **修改已有知识** → 在对应条目后追加 `(已更新: {YYYY-MM-DD})` 注释，不直接覆盖原行
 - **删除过时知识** → 不物理删除，改为在条目前加 `~~` 删除线标记并注明原因
 
-**为什么这样设计：**
-- Git merge 时，append-only 的文件几乎不会产生冲突
-- 保留了变更历史，方便溯源
-- 团队成员可以看到知识演进过程
+---
 
 ### Step 4：写入 Skill 文件
 
-按 Business Skill 标准格式生成或更新文件：
+按 Business Skill v2/14节 标准格式生成或更新文件。
 
 **更新策略（模式 B/C/D）：**
 - 对比现有 Skill 内容和最新信息，识别差异
 - **新增内容追加到文件末尾**，修改内容以注释方式标注（见 Step 3）
 - 更新文件头的 `updated` 日期、`version`（自增）、`last_referenced`、`usage_count`
-- **模式 B/D 完整更新后**：重新计算 `key_files` 内容的 SHA-1 并写入 `last_hash`（模式 C 后置回写不更新 hash，因为它是从产出物提取知识而非扫描代码）
+- **模式 B/D 完整更新后**：重新计算 `key_files` 内容的 SHA-1 并写入 `last_hash`（模式 C 后置回写不更新 hash）
 - 在文件末尾追加「本次更新摘要」注释
 
+**写入 upstream_skills 后立即执行双向同步算法：**
+
+```
+Step 4 扩展：upstream/downstream 双向同步（append-only，Git 无冲突）
+
+算法：
+  1. 读取当前 Skill 的旧 upstream_skills（old_deps，来自现有 frontmatter）
+  2. 确定新 upstream_skills（new_deps，来自 Section 10 生成结果）
+  3. added   = new_deps - old_deps   // 新增依赖
+  4. removed = old_deps - new_deps   // 移除依赖
+
+  对 added 中每个域 B：
+    → 读取 B 的 SKILL.md frontmatter
+    → 若 downstream_skills 不含当前域 A：append 追加（不覆盖任何行）
+    → 输出：「✓ 已将 {A} 追加至 {B} 的 downstream_skills」
+
+  对 removed 中每个域 B：
+    → 读取 B 的 SKILL.md frontmatter
+    → 将 downstream_skills 中的 {A} 改为 ~~{A}~~（{YYYY-MM-DD} 解除依赖）
+    → 输出：「⚠️ 已将 {A} 在 {B} 的 downstream_skills 中标记为已解除」
+
+并发安全保障：所有写入均使用 append-only 或单行替换策略，不重写整个 frontmatter 块
+```
+
+**跨域联动感知（写入完成后触发）：**
+
+扫描所有其他 Skill 的 `upstream_skills` 字段，若存在引用了本域的 Skill，提示：
+
+```
+✅ modus-biz-payment 已更新至 v1.4.0
+
+⚠️ 以下 Skill 的 Section 10 引用了本域，建议检查是否需要同步更新：
+  - modus-biz-order（upstream_skills 包含 payment）
+  - modus-biz-refund（upstream_skills 包含 payment）
+
+是否现在触发这些 Skill 的 Section 10 局部刷新？[y/N]
+```
+
+---
+
 ### Step 5：更新 knowledge-catalog.md
 
-每次写入 Skill 后，同步更新 `modus/knowledge-catalog.md`：
-- 更新对应条目的 `maturity`、`last_referenced`
-- 若有新建 Skill，追加一行
-- 若检测到衰减，在条目后追加 `⚠️` 标记
+每次写入 Skill 后，同步更新 `modus/knowledge-catalog.md`（使用升级后的条目格式）：
+
+```markdown
+- **modus-biz-order**: 订单域 — 创建/状态流转/查询
+  [status: verified] [format: v2/14节] [upstream: user, payment]
+  更新: 2026-01-15  hash: a3f9d2e1  verified_by: 张三
+- **modus-biz-payment**: 支付域 — 发起/回调/退款
+  [status: stale ⚠️ 超过90天未更新] [format: v1/7节 → 建议运行迁移]
+  更新: 2025-09-10
+```
+
+每个条目包含：`[status]`、`[format: v1/v2 + 节数]`、`[upstream 依赖列表]`、更新日期、hash、verified_by（已 verified 时）。
 
 ---
 
-## Skill 文件标准格式
+### Step 6：质量自检（生成后执行）
+
+00-skills-builder 在完成 Skill 生成后，执行自动质量自检：
+
+```
+质量自检清单（v3 版本，含新节检查）：
+
+核心节检查：
+  □ Section 3：是否每个 Entity 字段均有业务含义注释？
+  □ Section 5：是否所有 Facade 方法均列出了错误码？（含 2B 校验注解提取结果）
+  □ Section 8（如存在）：是否所有 status 枚举值均出现在转换矩阵中（含禁止转换）？
+  □ Section 12（如存在）：是否每条 SQL 均有查询语义说明 + N+1 风险评估？
+
+新节检查：
+  □ Section 15（业务不变量）：
+      - 条目数 ≥ 1 或写合法占位 → ✓
+      - 若 2A/2D 扫描有发现但本节为空 → ⚠️ 不变量提炼缺失
+  □ Section 16（领域词汇表）：
+      - 条目数 ≥ 1 或写合法占位 → ✓
+  □ Section 17（新人上手指南）：
+      - 开发场景速查 ≥ 3 行 → ✓
+      - 高频踩坑非空（或写「暂无记录」）→ ✓
+      - 完全为空 → ⚠️ 新人指南未生成，阻断升级 verified
+
+无条件生成节通用规则（9/10/13/15/16）：
+  - 「暂无发现，随工作流积累」是合法初始内容 → 质量自检通过 ✓
+  - 初次生成时此内容正常，不标注 ⚠️
+  - 例外：当 status 为 stale 时再次执行自检，若五节仍为此内容
+    → 标注 ⚠️「知识库超期且无积累，建议重新扫描或人工补充」
+
+质量评分（生成后自动计算并写入 frontmatter）：
+  invariant_count  = Section 15 的 [invariant] 条目数（不含合法占位）
+  glossary_size    = Section 16 的术语条目数（不含合法占位）
+
+发现未达标节时：标注 ⚠️ 并说明缺失内容，不阻断生成但记入 draft 状态。
+Section 17 完全为空时：阻断 verified 升级（必须补全）。
+```
+
+---
+
+## Skill 文件标准格式（v2/14节）
 
 ### Business Skill（modus-biz-{domain}）
 
@@ -194,15 +727,35 @@ name: modus-biz-{domain}
 description: "[MODUS:BIZ] {中文域名}业务知识 — {核心职责一句话描述}"
 version: {N}.0.0
 updated: {YYYY-MM-DD}
-maturity: draft             # draft | verified | proven
+status: draft               # draft | verified | proven | stale | archived（统一使用 status，不使用 maturity）
+format_version: v3          # v1=7节 | v2=14节 | v3=17节（当前默认，含不变量/词汇表/新人指南）
+stale_after_days: 90        # 超过此天数自动降为 stale
 last_referenced: {YYYY-MM-DD}
 usage_count: 0
 last_hash: ""               # SHA-1(key_files 内容)，模式 B/D 更新后自动计算并填入
-key_files:                  # 关键源文件列表，用于 hash 快速检查（最多 10 个）
+last_verified_by: ""        # 最后 verified 确认人（运行 /modus:verify 时填写）
+domain_confidence: 0        # 域置信度评分（0-10），来自 modus-init Step 2 评分矩阵
+invariant_count: 0          # Section 15 业务不变量条目数（由 Skills Builder 自动统计）
+glossary_size: 0            # Section 16 领域词汇表条目数（由 Skills Builder 自动统计）
+hidden_knowledge_rate: 0    # 隐性知识补全率（0-100），来自 modus-init Step 3.5 访谈问卷
+upstream_skills:            # 本 Skill 在 Section 10 中依赖的其他域 Skill（由 Step 4 双向同步维护）
+  - modus-biz-payment
+downstream_skills:          # 依赖本域的其他 Skill（由被依赖方的 Step 4 双向同步维护）
+  - modus-biz-order
+key_files:                  # 关键源文件列表，用于 hash 快速检查（最多 20 个，覆盖全 10 类文件）
+  # 优先级 1：核心业务逻辑（必选）
   - src/.../service/{Domain}Service.java
   - src/.../manager/{Domain}Manager.java
   - src/.../dao/{Domain}Mapper.java
   - src/.../domain/{Domain}.java
+  # 优先级 2：状态与规则（强烈建议）
+  - src/.../enums/{Domain}Status.java      # 状态枚举
+  - src/.../enums/{Domain}Type.java        # 类型枚举
+  - src/.../exception/{Domain}Exception.java
+  # 优先级 3：消息与配置（有则加入）
+  - src/.../mq/{Domain}Consumer.java
+  - src/.../mq/{Domain}Producer.java
+  - src/.../config/{Domain}Config.java
 ---
 
 # {中文域名}业务知识
@@ -233,7 +786,9 @@ COMPLETED(3, "已完成"),
 CANCELLED(4, "已取消")
 \`\`\`
 
-## 3. 业务规则
+## 3. 业务规则 [process] [guideline]
+
+（最低门槛：每个核心字段必含：Java 类型、是否非空、业务含义、关联枚举）
 
 - [process]   {流程规则：如 订单状态只能按 CREATED→PAID→COMPLETED 单向流转}
 - [guideline] {推荐做法：如 退款金额必须 ≤ 原始支付金额，在 Service 层校验}
@@ -251,14 +806,16 @@ CANCELLED(4, "已取消")
 
 ## 5. API 契约 [model]
 
-| 方法 | 路径 | 说明 | 关键参数 |
-|------|------|------|----------|
-| POST | /api/v1/orders | 创建订单 | amount, productId |
-| GET | /api/v1/orders/{id} | 查询订单 | id |
+（最低门槛：每个接口必含：入参校验规则、成功返回结构、错误码列表、是否需要幂等、权限注解值）
+
+| 方法 | 路径 | 说明 | 关键参数 | 权限注解 | 幂等 |
+|------|------|------|----------|----------|------|
+| POST | /api/v1/orders | 创建订单 | amount(必填,>0), productId(必填) | @UserAuthorization | 是 |
+| GET | /api/v1/orders/{id} | 查询订单 | id(必填) | @UserAuthorization | - |
 
 ## 6. 项目特有模式 [decision] [guideline]
 
-- [guideline] 事务使用 `AopContext.currentProxy()` 解决同类调用问题（avoid: @Transactional 直接同类调用）
+- [guideline] 事务使用 `AopContext.currentProxy()` 解决同类调用问题
 - [guideline] 分布式锁使用 `@DistributedLock` 注解，key 格式为 `{domain}:{id}`
 - [guideline] 响应统一用 `BaseRpcResponse.build(data)` 包装
 
@@ -276,13 +833,128 @@ public OrderDTO createOrder(CreateOrderRequest request) {
 }
 \`\`\`
 
+## 8. 状态机 [process]
+
+（前置检测：域中存在含 status/state 字段的 Entity 才生成本节；否则整节省略，禁止填占位符）
+（最低门槛：每条转换必含：起始状态、目标状态、触发条件、触发方法名、是否有事务保护）
+
+\`\`\`mermaid
+stateDiagram-v2
+    [*] --> CREATED : createOrder() @Transactional
+    CREATED --> PAID : payOrder() 支付成功 @Transactional
+    PAID --> COMPLETED : completeOrder() 确认收货 @Transactional
+    CREATED --> CANCELLED : cancelOrder() 超时/主动取消 @Transactional
+\`\`\`
+
+| 起始状态 | 目标状态 | 触发条件 | 触发方法 | 事务保护 |
+|---------|---------|---------|---------|---------|
+| CREATED | PAID | 支付成功回调 | payOrder() | ✓ |
+| PAID | COMPLETED | 用户确认收货 | completeOrder() | ✓ |
+
+## 9. 错误码与异常 [pitfall]
+
+（无条件生成。若为空则写「暂无发现，随工作流积累」——此为合法初始内容）
+
+| 错误码 | 异常类 | 触发场景 | HTTP状态 | 处理建议 |
+|--------|--------|---------|---------|---------|
+| ORDER_NOT_FOUND | OrderNotFoundException | 查询不存在订单 | 404 | 前端展示「订单不存在」 |
+
+## 10. 跨域依赖 [decision]
+
+（无条件生成。若为空则写「暂无发现，随工作流积累」。模式A由主流程统一回写，模式B按Step B-10流程生成）
+
+**上游依赖（本域调用的其他域）：**
+| 依赖域 | 交互方式 | 调用点 | 说明 |
+|--------|---------|-------|------|
+| payment | RPC @DubboReference | OrderService.createOrder() | 发起支付 |
+
+**下游被依赖（调用本域的其他域）：**
+| 调用域 | 交互方式 | 场景 |
+|--------|---------|------|
+| refund | RPC | 查询原订单 |
+
+## 11. 数据流向 [process]
+
+（前置检测：域中存在 @KafkaListener/sendMessage()/@RocketMQMessageListener 才生成；否则整节省略）
+
+| 方向 | Topic | 触发时机 | 生产者/消费者 | 幂等保障 |
+|------|-------|---------|------------|---------|
+| 发布 | order.created | 订单创建成功 | OrderService | 业务唯一键去重 |
+
+## 12. 关键 SQL 模式 [guideline]
+
+（前置检测：域中存在 XML Mapper 或含复杂 SQL 的注解才生成；否则整节省略）
+（最低门槛：每条复杂 SQL 必含：查询语义、JOIN 关系、索引命中路径、数据量级、慢查询风险）
+
+| SQL 标识 | 查询语义 | JOIN 表 | 索引命中 | 数据量级 | 慢查询风险 |
+|---------|---------|--------|---------|---------|---------|
+| selectOrderWithItems | 查询订单及明细 | order+order_item | idx_order_id | ~20行 | 低 |
+
+## 13. 常见开发陷阱 [pitfall]
+
+（无条件生成。若为空则写「暂无发现，随工作流积累」——此为合法初始内容）
+
+- [pitfall] 并发创建时若不加 @DistributedLock 会出现重复订单
+- [pitfall] @Transactional 同类内部调用失效，必须通过 AopContext.currentProxy() 代理调用
+
+## 14. 扩展点 [decision]
+
+（前置检测：域中存在 interface+多实现类 或 @ConditionalOn* 才生成；否则整节省略）
+
+| 扩展点 | 接口/注解 | 当前实现 | 扩展方式 |
+|--------|---------|---------|---------|
+| 支付渠道策略 | PayChannelStrategy | AlipayStrategy, WechatStrategy | Map<String, T> 注入 |
+
+## 15. 业务不变量 [invariant]
+
+（无条件生成。来源：2A if/else 推断 + 2D 自定义校验器 + Step 1.4 注释挖掘 + Step 3.5 人工访谈。）
+
+| 不变量描述 | 验证位置 | 违反后果 | 来源 |
+|---------|---------|---------|------|
+| {从代码推断的业务约束，精确到数值和条件} | {类名:行号} | 抛 {XxxException} / 返回 {ErrorCode} | 代码推断 |
+
+> 若无任何不变量，写「暂无发现，随工作流积累」（此为合法初始内容）。
+
+## 16. 领域词汇表 [model]
+
+（无条件生成。来源：枚举描述 + Javadoc + 代码注释 + Step 3.5 人工访谈。）
+
+| 术语 | 定义 | 与通用概念的区别 |
+|------|------|----------------|
+| {业务专名词} | {1-2句精准定义} | {与通用含义的差异，若无则省略} |
+
+> 若无特殊术语，写「暂无特定领域术语，使用通用定义」（此为合法初始内容）。
+
+## 17. 新人上手指南 [process]
+
+（无条件生成。从本 Skill 已有内容自动合成，禁止留空。）
+
+### 开发前必读清单
+
+- [ ] {从 Section 8 提取的状态机理解要求，若有}
+- [ ] 了解 Section 15 的 {N} 条业务不变量，违反将导致生产事故
+- [ ] 熟悉 Section 6 的项目特有编码模式
+
+### 常见开发场景速查
+
+| 场景 | 入口文件 | 关键类 | 注意事项 |
+|------|---------|-------|----------|
+| {从 Section 4/5/8/14 自动提取，至少 3 行} | | | |
+
+### 高频踩坑（精选自 Section 13 TOP 3）
+
+（自动提取 Section 13 前 3 条 [pitfall]，若无内容写「暂无记录，随工作流积累」）
+
 ---
 <!-- 更新摘要（由 Skills Builder 自动追加）
-[{YYYY-MM-DD}] 模式B更新：新增 OrderStatus.PENDING_REVIEW 枚举值
-[{YYYY-MM-DD}] 模式C回写：新增批量审批接口 POST /orders/batch-approve 的 API 契约
+[{YYYY-MM-DD}] 模式A生成：17节完整格式（v3），扫描{M}个文件，不变量{I}条，词汇{G}个，隐性知识率{H}%
+[{YYYY-MM-DD}] 模式B更新：新增 OrderStatus.PENDING_REVIEW 枚举值，同步更新 Section 8/15/17
+[{YYYY-MM-DD}] 模式C回写：新增批量审批接口 POST /orders/batch-approve 的 API 契约（Section 5）
 -->
 ```
 
+---
+
 ### 团队约定 Skill（modus-team-conventions）
 
 ```markdown
@@ -291,7 +963,8 @@ name: modus-team-conventions
 description: "[MODUS:TEAM] 团队约定 — 代码规范/提交规范/最佳实践"
 version: 1.0.0
 updated: {YYYY-MM-DD}
-maturity: draft
+status: draft
+format_version: v2
 layer: "0-T"
 ---
 
@@ -321,6 +994,8 @@ layer: "0-T"
 - [pitfall] {反模式2：如 禁止直接修改 final 字段绕过业务校验}
 ```
 
+---
+
 ### 技术知识 Skill（modus-tech-wiki）
 
 ```markdown
@@ -329,7 +1004,8 @@ name: modus-tech-wiki
 description: "[MODUS:TECH] 跨项目技术知识 — 架构决策/反模式/性能优化经验"
 version: 1.0.0
 updated: {YYYY-MM-DD}
-maturity: draft
+status: draft
+format_version: v2
 layer: "1"
 ---
 
@@ -365,3 +1041,23 @@ layer: "1"
 - 每条知识条目必须打上五类型标签之一：`[model]` `[decision]` `[guideline]` `[pitfall]` `[process]`
 - 更新时必须更新 `updated` 日期和 `last_referenced`
 - 模式 D 每次执行后必须同步更新 `modus/knowledge-catalog.md`
+- 统一使用 `status` 字段（不使用 `maturity`），枚举值：`draft | verified | proven | stale | archived`
+- 新生成的 Skill 默认写入 `format_version: v2`；存量 7 节 Skill 迁移前标记 `format_version: v1`
+
+---
+
+## draft → verified 升级标准
+
+```
+verified 达标条件（全部满足方可从 draft 升为 verified）：
+  ✅ 条件 1：所有无条件生成节（Section 9/10/13/15/16/17）内容非空且非合法初始占位符
+             注：「暂无发现，随工作流积累」是合法初始内容 → 质量自检通过
+  ✅ 条件 2：质量自检清单（见 Step 6）零 ⚠️ 警告
+             新增检查项：Section 17 开发场景速查 ≥ 3 行
+  ✅ 条件 3：key_files hash 与当前代码库一致（无 stale 状态）
+  ✅ 条件 4：domain_confidence ≥ 4（中置信度以上，低置信度域不允许升为 verified）
+  ✅ 条件 5：至少经过 1 名开发者在真实需求中使用，且未反馈「Skill 中缺少 XX 知识」
+
+升级操作：运行 /modus:verify {skill-name}，由运行者填写 last_verified_by 字段
+升级时自动更新：invariant_count、glossary_size 统计字段
+```