@modus-ai/modus 0.2.4 → 0.2.6

package/templates/skills/modus-agents/skill-creator/SKILL.md

@@ -13,7 +13,7 @@ disable: false
 
 ## 职责
 
-从项目代码和工作流产物中提炼业务知识，生成或更新标准格式的 Skill 文件（v2/14节），并维护知识全景目录（`knowledge-catalog.md`）。支持五种调用模式，覆盖从初始化到持续积累的完整知识生命周期。
+从项目代码和工作流产物中提炼业务知识，生成或更新标准格式的 Skill 文件（v3/17节，当前默认），并维护知识全景目录（`knowledge-catalog.md`）。支持五种调用模式，覆盖从初始化到持续积累的完整知识生命周期。
 
 ---
 
@@ -21,7 +21,7 @@ disable: false
 
 ### 模式 A：全量初始化（来自 /modus:init）
 
-为每个确认的业务域从零生成 `modus-biz-{domain}/SKILL.md`，初始 `status: draft`，`format_version: v2`。
+为每个确认的业务域从零生成 `modus-biz-{domain}/SKILL.md`，初始 `status: draft`，`format_version: v3`（17节标准格式，详见 modus-init SKILL 区块 C）。
 
 ### 模式 B：增量更新（来自 /plan 或 /spec 前置，含 hash 快速检查）
 
@@ -46,8 +46,12 @@ disable: false
 **hash 检查（防腐校验通过后执行）：**
 
 ```bash
-# 计算当前 key_files 内容的 SHA-1 摘要
-shasum -a 1 {file1} {file2} ... | awk '{print $1}' | sort | shasum -a 1 | awk '{print $1}'
+# 标准全局 hash 计算命令（必须与 modus-init 区块 B、modus-plan Step 4-2 使用完全相同的算法）
+# 算法：按文件路径排序 → 输出 "SHA-1:文件路径" 字符串 → 整体再 hash
+# 禁止使用「仅 hash 值排序 hash」或「内容拼接整体 hash」的替代算法
+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}'
 ```
 
 **对比结果分级处理：**
@@ -84,16 +88,16 @@ Step B-10-6：触发跨域联动提示（检查引用了本域的其他 Skill，
 ### 模式 C：后置回写（来自 /plan、/spec 归档后）
 
 将本次工作中新确立的决策、规则、接口契约追加或更新到对应 Skill 文件。  
-从产出物（design.md、specs/*/spec.md）提取带类型标签的知识：
+从产出物（design-brief.md、specs/*/spec.md）提取带类型标签的知识：
 - delta spec 的 ADDED Requirements → `[process]` / `[model]` 追加到业务 Skill
 - delta spec 的 MODIFIED Requirements → 更新对应 `[guideline]`
-- design.md 的架构决策章节 → `[decision]` 追加到对应业务 Skill 或 modus-tech-wiki
+- design-brief.md 的架构决策章节 → `[decision]` 追加到对应业务 Skill 或 modus-tech-wiki
 
 ### 模式 D：知识提取（来自 Harness ARCHIVE 阶段）
 
 从 Harness 全流程产物中系统性提取知识条目，判断提升路径，写回 Skill 并更新 catalog。
 
-**输入产物：** `01-analysis.md`、`02-sprint-contract.md`、`cr-report.md`、`07-deploy-status.md`
+**输入产物：** `01-analysis.md`、`02-sprint-contract.md`、`03-test-report.md`、`04-perf-report.md`、`05-security-report.md`、`cr-report.md`、`07-deploy-status.md`
 
 **提取规则：**
 
@@ -101,9 +105,17 @@ Step B-10-6：触发跨域联动提示（检查引用了本域的其他 Skill，
 |---------|---------|---------|---------|
 | 01-analysis.md 的风险点 | 业务边界条件、并发风险 | `[pitfall]` | modus-biz-{domain} |
 | 02-sprint-contract.md 的架构决策 | 技术选型原因 | `[decision]` | modus-tech-wiki |
+| 03-test-report.md 的失败用例与边界条件 | 未覆盖的测试场景、发现的 bug 规律 | `[pitfall]` | modus-biz-{domain} |
+| 04-perf-report.md 的高/中风险项 | N+1 查询、大数据量无分页、慢查询模式 | `[pitfall]` | modus-tech-wiki |
+| 05-security-report.md 的严重/高风险项 | 多租户隔离漏洞、权限缺失、敏感信息泄露 | `[pitfall]` `[invariant]` | modus-team-conventions |
 | cr-report.md 的 P1/P2 问题 | 规范违反模式 | `[pitfall]` `[guideline]` | modus-team-conventions |
 | 07-deploy-status.md 的部署注意事项 | 环境特殊配置 | `[guideline]` | modus-tech-wiki |
 
+**03/04/05 报告提取优先级：**
+- `05-security-report.md` 的严重/高危问题必须提取，不可跳过（涉及安全不变量）
+- `04-perf-report.md` 的高风险项（N+1、无分页大查询）必须提取，中风险项选择性提取
+- `03-test-report.md` 仅提取因测试失败而发现的新 pitfall，已通过的用例不提取
+
 **成熟度提升判定（统一使用 status 字段）：**
 - 本次工作流成功验证了某条知识 → `draft` 升为 `verified`，更新 `last_referenced` 和 `usage_count +1`
 - 若该知识已是 `verified` 且跨不同工作流被引用 ≥2 次 → 升为 `proven`
@@ -111,7 +123,10 @@ Step B-10-6：触发跨域联动提示（检查引用了本域的其他 Skill，
 **hash 更新（ARCHIVE 阶段必做）：**
 
 ```bash
-shasum -a 1 {key_files...} | awk '{print $1}' | sort | shasum -a 1 | awk '{print $1}'
+# 标准全局 hash 计算命令（与 modus-init 区块 B 规定的算法完全一致）
+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}'
 ```
 
 将新 hash 写入 SKILL.md frontmatter 的 `last_hash` 字段。
@@ -679,7 +694,7 @@ Step 4 扩展：upstream/downstream 双向同步（append-only，Git 无冲突
 
 ### Step 6：质量自检（生成后执行）
 
-00-skills-builder 在完成 Skill 生成后，执行自动质量自检：
+`modus-skill-creator`（SubAgent 00）在完成 Skill 生成后，执行自动质量自检：
 
 ```
 质量自检清单（v3 版本，含新节检查）：
@@ -1042,7 +1057,7 @@ layer: "1"
 - 更新时必须更新 `updated` 日期和 `last_referenced`
 - 模式 D 每次执行后必须同步更新 `modus/knowledge-catalog.md`
 - 统一使用 `status` 字段（不使用 `maturity`），枚举值：`draft | verified | proven | stale | archived`
-- 新生成的 Skill 默认写入 `format_version: v2`；存量 7 节 Skill 迁移前标记 `format_version: v1`
+- 新生成的 Skill 默认写入 `format_version: v3`（17节标准格式）；存量 14 节 Skill 保留 `format_version: v2`；存量 7 节 Skill 迁移前标记 `format_version: v1`
 
 ---
 
@@ -1050,8 +1065,11 @@ layer: "1"
 
 ```
 verified 达标条件（全部满足方可从 draft 升为 verified）：
-  ✅ 条件 1：所有无条件生成节（Section 9/10/13/15/16/17）内容非空且非合法初始占位符
-             注：「暂无发现，随工作流积累」是合法初始内容 → 质量自检通过
+  ✅ 条件 1：分两类检查
+             【必须有实质内容的节】Section 2（枚举）、Section 3（业务规则）、Section 5（API）
+               → 不得为空或仅含「暂无发现」占位符（这些节在项目中必然有真实内容可填）
+             【允许占位符的节】Section 9/10/13/15/16/17（积累型知识）
+               → 「暂无发现，随工作流积累」是合法初始内容，不阻碍 verified 升级
   ✅ 条件 2：质量自检清单（见 Step 6）零 ⚠️ 警告
              新增检查项：Section 17 开发场景速查 ≥ 3 行
   ✅ 条件 3：key_files hash 与当前代码库一致（无 stale 状态）

package/templates/skills/modus-agents/tester/SKILL.md

@@ -1,91 +1,137 @@
 ---
 name: modus-tester
-description: Use this skill when the Harness orchestrator needs to generate unit tests for code changes. Covers Happy Path, boundary conditions, exception paths, and concurrency scenarios. Generates 03-test-report.md. Triggered by modus-harness in parallel with SubAgents 04 and 05 after Gate A passes.
+description: Use this skill when the Harness orchestrator needs to generate unit tests for changed code after Gate A. Covers three test paths (Happy Path / boundary / exception), uses MockBean isolation, inherits project base test class, and generates 03-test-report.md with HANDOFF block. Triggered by modus-harness in parallel with perf-auditor and security-auditor after Gate A passes.
 allowed-tools: Read, Write, Glob, Bash
 disable: false
 ---
 
 # modus-tester（代码测试 SubAgent）
 
-**调用方：** Harness Orchestrator（与 04/05 并行启动）  
-**输入：** `02-sprint-contract.md` + 代码变更  
-**产出物：** `modus/plans/active/{story-id}/03-test-report.md` + 单元测试代码
+**调用方：** Harness Orchestrator（Gate A 通过后，与 04/05 并行触发）  
+**输入：** `02-sprint-contract.md`（变更文件列表）+ 代码变更 + 业务 Skill（≤ 2 个）  
+**产出物：** `modus/plans/active/{story-id}/03-test-report.md` + 测试代码
 
 ## 职责
 
-为本次代码变更生成单元测试，验证核心业务逻辑有测试覆盖，输出测试报告。
+为本次代码变更生成单元测试，覆盖核心业务逻辑的三条测试路径（Happy Path / 边界条件 / 异常路径），使用 Mock 隔离外部依赖，确保测试独立可重复运行。
 
 ---
 
 ## 执行流程
 
-### Step 1：分析代码变更
+### Step 1：确定测试目标
 
-读取 `02-sprint-contract.md`，识别需要测试的关键方法：
-- Service/Manager 层的核心业务方法
-- 有复杂条件分支的逻辑
-- `01-analysis.md` 中标注的验收标准对应的逻辑
+读取 `02-sprint-contract.md` 的 `changed_files`，识别需要测试的类：
 
-### Step 2：生成测试用例
+**优先级（高 → 低）：**
+1. Service / Manager 类（核心业务逻辑，必须测试）
+2. 含复杂条件分支的 Util / Helper 类
+3. Controller / Facade（仅测试参数校验和权限逻辑）
+4. Mapper 接口（通常跳过，属于集成测试范围）
 
-按照 **Happy Path → 边界条件 → 异常路径** 三段式结构设计测试：
+### Step 2：三路径测试生成
 
-**Happy Path（正常流程）**
-- 主流程成功执行
-- 返回值正确
+对每个测试目标，生成以下三类测试用例：
 
-**边界条件（Boundary）**
-- null / 空值 / 空集合 / 零值
-- 最小值 / 最大值
-- 单条记录 / 批量记录
+**Path 1 — Happy Path（正常流程）**
+```java
+@Test
+void {method}_success() {
+    // Given: 构造合法的输入数据
+    // When: 调用被测方法
+    // Then: 验证返回结果符合预期
+}
+```
+
+**Path 2 — 边界条件（Boundary）**
+```java
+@Test
+void {method}_withNullInput_throws() { ... }
+
+@Test
+void {method}_withEmptyList_returnsEmpty() { ... }
+
+@Test
+void {method}_withMaxValue_succeeds() { ... }
+```
+
+**Path 3 — 异常路径（Exception）**
+```java
+@Test
+void {method}_whenDistributedLockFails_throws() { ... }
+
+@Test
+void {method}_whenDownstreamRpcTimeout_throwsServiceException() { ... }
+
+@Test
+void {method}_whenDatabaseError_rollsBack() { ... }
+```
+
+### Step 3：测试代码规范
 
-**异常路径（Exception）**
-- 依赖服务调用失败
-- 数据不存在
-- 业务规则校验失败（如余额不足、状态不合法）
-- 并发场景（如分布式锁被占用）
+**Mock 隔离原则：**
+- 使用 `@MockBean`（Spring）或 `@Mock`（Mockito）隔离所有外部依赖
+- 不使用 `@SpringBootTest`（启动全量容器，速度慢），优先使用 `@ExtendWith(MockitoExtension.class)` 或项目已有的轻量基类
+- 数据库操作全部 Mock，不依赖真实数据库
 
-### Step 3：编写测试代码
+**继承项目基类：**
+- 读取项目已有的测试基类（如 `AbstractBaseTest`、`BaseServiceTest`），继承或参照其 Mock 配置
+- 若无基类，使用 `@ExtendWith(MockitoExtension.class)`
 
-遵循项目测试规范（从业务 Skill 或现有测试文件中提取），通用原则：
-- 使用 Mock 隔离外部依赖（DB、RPC、MQ 等）
-- 每个测试方法只测一个场景
-- 测试方法命名清晰表达场景：`test_{methodName}_{scenario}_{expectedResult}`
-- 断言明确，不只断言 "no exception"
+**断言规范：**
+- 使用 AssertJ 或 JUnit 5 标准断言（`assertThat`/`assertEquals`）
+- 异常测试用 `assertThrows`，验证异常类型和消息
 
-### Step 4：运行测试（如可执行环境允许）
+### Step 4：执行测试验证
 
-如果有可用的测试执行环境：
-- 执行新增的测试用例
-- 记录通过/失败状态
+```bash
+{constitution.test_command}  # 如 mvn test -pl {module} -Dtest={TestClass}
+```
+
+测试失败 → 修复测试代码（不修改业务代码）后重试。
 
 ---
 
 ## 产出物格式（03-test-report.md）
 
 ```markdown
-# 测试报告
-
-## 测试覆盖摘要
-- 新增测试用例: {N} 个
-- 覆盖方法: {N} 个
-- 通过: {N} | 失败: {N} | 跳过: {N}
+<!--HANDOFF
+agent: "03-tester"
+story_id: "{story-id}"
+gate_status: "passed"
+tests_generated: {N}
+tests_passed: {N}
+coverage_targets:
+  - "{ClassName}.{method}(): {覆盖的路径描述}"
+-->
+
+# 测试报告 — {Story 标题}
+
+## 测试摘要
+- 生成测试用例: {N} 个
+- 通过: {N} 个 | 失败: {N} 个
+- 覆盖的核心逻辑: {列表}
 
 ## 测试用例列表
 
 ### {ClassName}Test
-| 测试方法 | 场景 | 状态 |
-|----------|------|------|
-| test_createOrder_success | 正常创建订单 | ✅ |
-| test_createOrder_insufficientBalance | 余额不足 | ✅ |
-| test_createOrder_concurrentLock | 并发锁冲突 | ✅ |
-
-## 覆盖率分析
-- 核心业务逻辑：{N}% 覆盖
-- 未覆盖的分支：{描述原因}
-
-## 验收标准覆盖
-| 验收场景 | 对应测试 | 状态 |
-|----------|----------|------|
-| {从 01-analysis.md 提取} | {测试方法名} | ✅/❌ |
+
+| 测试用例 | 路径类型 | 测试场景 | 结果 |
+|---------|---------|---------|------|
+| {method}_success | Happy Path | {场景} | ✅ |
+| {method}_withNull_throws | Boundary | null 输入 | ✅ |
+| {method}_whenLockFail | Exception | 分布式锁获取失败 | ✅ |
+
+## 未覆盖说明
+
+{若有意跳过某些场景，说明原因（如：Mapper 接口属于集成测试范畴，本次跳过）}
 ```
+
+---
+
+## 质量标准
+
+- Service / Manager 类的核心业务方法必须有 Happy Path 覆盖
+- 01-analysis.md 中标注的并发/事务风险点必须有对应的异常路径测试
+- 所有测试必须在 Mock 隔离下独立通过，不依赖外部环境
+- **HANDOFF 块必须位于文件最顶部**，`gate_status` 仅在所有测试通过时为 `passed`