@xulthekl/team-flow 0.32.2 → 0.34.0

package/skills/test-strategy/references/test-quality-rules.md

@@ -0,0 +1,292 @@
+# Test Quality Rules（测试质量规则）
+
+> 来源：glaf4-test scan-generated-tests.py 的通用规则（v0.13 §56）
+> 用途：code-reviewer 在测试审查时参考，build-executor 在生成测试后自检
+
+---
+
+## 一、断言质量规则
+
+### 1. missing-meaningful-assertion
+
+**描述**：测试没有有效断言
+
+**检查**：
+- 测试方法中没有 `assert*`、`verify*`、`expect*` 等断言语句
+- 只有被测方法调用，没有验证结果
+
+**示例（违规）**：
+```java
+@Test
+void testGetUser() {
+    userService.getUser(1L);  // 没有断言
+}
+```
+
+**修正**：
+```java
+@Test
+void testGetUser() {
+    User user = userService.getUser(1L);
+    assertNotNull(user);
+    assertEquals("John", user.getName());
+}
+```
+
+### 2. weak-assertion-only
+
+**描述**：只有弱断言（assertNotNull/isNotNull）
+
+**检查**：
+- 只有 `assertNotNull`、`assertThat(x).isNotNull()`
+- 没有验证具体属性值
+
+**示例（违规）**：
+```java
+@Test
+void testGetUser() {
+    User user = userService.getUser(1L);
+    assertNotNull(user);  // 只验证非空，不验证内容
+}
+```
+
+**修正**：
+```java
+@Test
+void testGetUser() {
+    User user = userService.getUser(1L);
+    assertNotNull(user);
+    assertEquals("John", user.getName());
+    assertEquals(25, user.getAge());
+}
+```
+
+### 3. verify-only-without-assertion
+
+**描述**：只有 mock verify，没有状态断言
+
+**检查**：
+- 只有 `verify(mock).method()`
+- 没有验证返回值或状态变化
+
+**示例（违规）**：
+```java
+@Test
+void testCreateUser() {
+    userService.createUser("John");
+    verify(userRepository).save(any());  // 只验证调用，不验证结果
+}
+```
+
+**修正**：
+```java
+@Test
+void testCreateUser() {
+    User user = userService.createUser("John");
+    assertNotNull(user);
+    assertEquals("John", user.getName());
+    verify(userRepository).save(any());
+}
+```
+
+---
+
+## 二、调试代码残留规则
+
+### 4. system-out / print-stack-trace
+
+**描述**：测试中有调试代码残留
+
+**检查**：
+- `System.out.println`
+- `System.err.println`
+- `e.printStackTrace()`
+- `console.log`（JavaScript）
+- `print()`（Python，非断言）
+
+**示例（违规）**：
+```java
+@Test
+void testGetUser() {
+    User user = userService.getUser(1L);
+    System.out.println("User: " + user);  // 调试代码
+    assertNotNull(user);
+}
+```
+
+**修正**：
+```java
+@Test
+void testGetUser() {
+    User user = userService.getUser(1L);
+    assertNotNull(user);
+    // 如需调试，使用日志框架或断点
+}
+```
+
+---
+
+## 三、测试状态规则
+
+### 5. disabled-test / unfinished-test-todo
+
+**描述**：禁用或未完成的测试
+
+**检查**：
+- `@Disabled`、`@Ignore`
+- `// TODO`、`// FIXME`
+- `pending`、`skip`（JavaScript/Python）
+
+**处理**：
+- 禁用的测试必须有注释说明原因
+- 未完成的测试不应提交到主分支
+
+---
+
+## 四、测试数据规则
+
+### 6. hardcoded-sample-like-value
+
+**描述**：检测到样本数据
+
+**检查**：
+- 手机号：`13xxxxxxxxx`、`15xxxxxxxxx`
+- 身份证：`110101199001011234`
+- 邮箱：`test@example.com`、`xxx@test.com`
+- 姓名：`张三`、`李四`、`John`、`Doe`
+- 地址：`北京市朝阳区xxx`
+- 数字：`123456`、`111111`、`000000`
+
+**处理**：
+- 使用有意义的测试数据（如业务相关的名称）
+- 或使用测试数据工厂（Builder/Fixture）
+
+### 7. real-external-url
+
+**描述**：测试中包含真实外部 URL
+
+**检查**：
+- `http://api.example.com`
+- `https://third-party-service.com`
+- 任何非 localhost/127.0.0.1 的 URL
+
+**处理**：
+- 使用 mock/stub 替代真实外部服务
+- 或使用 `@MockBean` / `WireMock`
+
+---
+
+## 五、测试结构规则
+
+### 8. large-test-class
+
+**描述**：测试类过大
+
+**检查**：
+- 测试方法数 > 20
+- 测试类行数 > 500
+
+**处理**：
+- 按功能拆分测试类
+- 使用 `@Nested` 分组
+
+### 9. generic-test-class-name
+
+**描述**：类名过于泛化
+
+**检查**：
+- `Test`、`Tests`、`TestSuite`
+- `ServiceTest`、`ControllerTest`（无具体功能描述）
+
+**示例（违规）**：
+```java
+class ServiceTest { ... }
+```
+
+**修正**：
+```java
+class UserServiceGetUserTest { ... }
+class UserServiceCreateUserTest { ... }
+```
+
+---
+
+## 六、矩阵对账规则
+
+### 10. case-method-not-found
+
+**描述**：矩阵中的 case 引用了不存在的测试方法
+
+**检查**：
+- test-matrix.md 中声明的 `test_method_name` 在测试代码中不存在
+
+### 11. case-test-file-mismatch
+
+**描述**：矩阵中的 case 与测试文件不匹配
+
+**检查**：
+- case 声明的 `test_tier` 与实际测试文件不符（如 unit case 写到了集成测试文件）
+
+### 12. evidence-not-in-method
+
+**描述**：矩阵中的 evidence 在测试方法中找不到
+
+**检查**：
+- case 声明的 `design_method` 对应的代码模式在测试方法中不存在
+
+### 13. extra-test-methods
+
+**描述**：测试文件中有未在矩阵中声明的方法
+
+**检查**：
+- 测试文件中的方法数 > 矩阵中的 case 数
+
+---
+
+## 七、语言特定规则
+
+### 14. Java 特定
+
+- 禁止 `throws Exception`（应显式捕获和断言异常）
+- 禁止 `System.out.println` 替代断言
+- 单元测试禁止 `@SpringBootTest`
+- 集成测试禁止只 mock 不验证
+
+### 15. JavaScript 特定
+
+- 禁止 `console.log` 替代断言
+- 禁止 `expect(true).toBe(true)`（无意义断言）
+- async 测试必须 await
+
+### 16. Python 特定
+
+- 禁止 `print()` 替代断言
+- 禁止 `assert True`（无意义断言）
+- 测试函数必须以 `test_` 开头
+
+---
+
+## 八、使用方式
+
+### build-executor 自检
+
+implementer 子代理生成测试后，按此规则自检：
+1. 检查断言质量（规则 1-3）
+2. 检查调试代码残留（规则 4）
+3. 检查测试数据（规则 6-7）
+4. 检查测试结构（规则 8-9）
+
+### code-reviewer 审查
+
+code-reviewer 在审查测试代码时，按此规则检查：
+1. 矩阵对账（规则 10-13）
+2. 语言特定规则（规则 14-16）
+3. 测试状态（规则 5）
+
+---
+
+## 变更记录
+
+| 日期 | 版本 | 变更内容 |
+|------|------|---------|
+| 2026-08-04 | v1.0 | 从 glaf4-test scan-generated-tests.py 抽取 15 条通用规则 |

package/skills/workflow-bootstrap/SKILL.md

@@ -62,6 +62,43 @@ Do NOT invoke for:
 
 详细流程（脚本采集项、子代理维度表、侦察内容树、已有文档处理）见 `references/b1-reconnaissance.md`。
 
+### B1.5: Conventions Generator（测试规范生成，v0.34.0 新增）
+
+> 来源：test-capability-enhancement-design v1.0 §四
+> 目的：根据项目技术栈自动生成测试规范 conventions，符合 glaf4-test 要求
+
+**触发条件**：B1 侦察完成后，检查 `.team-flow/conventions/` 是否存在
+
+**存量项目路径**：
+1. 读取 B1 侦察结果中的技术栈信息（从 baseline.md 提取）
+2. 根据技术栈选择 conventions 模板
+3. 复制到项目 `.team-flow/conventions/` 目录
+4. 更新 `.team-flow/conventions/.versions.json`
+5. 更新 `team-flow.config.json` 的 conventions 字段
+
+**全新项目路径**（未检测到技术栈特征）：
+1. 交互式引导用户选择技术栈
+   - 编程语言：Java / JavaScript / Python
+   - 构建工具：Maven / Gradle / npm / yarn / pip / poetry
+   - 测试框架：JUnit 5 + Mockito / Jest / Pytest
+   - 应用框架：Spring Boot / Express / Django / 无框架
+2. 根据用户选择选择 conventions 模板
+3. （可选）生成项目骨架（pom.xml / package.json / requirements.txt）
+4. 生成 conventions 文件
+
+**conventions 模板来源**：
+- plugin 内置模板：`${CLAUDE_PLUGIN_ROOT}/templates/conventions/`
+- 符合 glaf4-test 要求的模板：`${CLAUDE_PLUGIN_ROOT}/templates/conventions/glaf4-compliant/`
+
+**产出**：
+- `.team-flow/conventions/*.md` — 测试规范文件
+- `.team-flow/conventions/.versions.json` — 版本信息
+- `.team-flow/team-flow.config.json` — conventions 路径映射（更新）
+
+**跳过条件**：
+- `.team-flow/conventions/` 已存在 → 提示用户"conventions 已存在，是否更新？"
+- 用户拒绝 → 跳过
+
 ### B2: Architecture Baseline（架构基线文档化）
 
 **条件**：如果 B1 侦察发现项目有一定复杂度（≥5 个模块或 ≥10 个源文件），执行此阶段。否则跳过。
@@ -173,10 +210,10 @@ Step 2: 确定性提取（兜底）
 ## Output Standard
 
 每次交互结束时说明：
-1. 已完成的阶段（B1-B5）
-2. 已产出的制品（baseline.md / ARCHITECTURE.md / PHYSICAL-MODEL.md / schema-baseline.sql / API-INDEX.md / INDEX.md / CONCEPTS.md / 目录结构）
+1. 已完成的阶段（B1-B1.5-B2-B3-B4-B5）
+2. 已产出的制品（baseline.md / conventions / ARCHITECTURE.md / PHYSICAL-MODEL.md / schema-baseline.sql / API-INDEX.md / INDEX.md / CONCEPTS.md / 目录结构）
 3. 下一步建议（调用哪个 skill）
 
 ## Success Output
 
-接入结束时输出：侦察模式、产出清单（baseline.md / ARCHITECTURE.md / DATABASE.md / PHYSICAL-MODEL.md / schema-baseline.sql / API-INDEX.md / INDEX.md / docs/architecture/CONCEPTS.md / 目录结构）、关键发现（技术栈/模块数/架构模式/测试覆盖）、下一步建议。完整模板见 `references/b1-reconnaissance.md`「Success Output 模板」。
+接入结束时输出：侦察模式、产出清单（baseline.md / conventions / ARCHITECTURE.md / DATABASE.md / PHYSICAL-MODEL.md / schema-baseline.sql / API-INDEX.md / INDEX.md / docs/architecture/CONCEPTS.md / 目录结构）、关键发现（技术栈/模块数/架构模式/测试覆盖）、下一步建议。完整模板见 `references/b1-reconnaissance.md`「Success Output 模板」。

package/templates/agent-template.md

@@ -0,0 +1,41 @@
+---
+name: agent-name
+description: "<one-sentence description — who this agent is, when it is dispatched, what it delivers. Single line only; never use <example> blocks or unquoted ASCII ': ' here (see CONTRIBUTING.md §6)>"
+model: inherit
+color: cyan
+tools: ["Read", "Bash", "Grep", "Glob"]
+skills:
+  - agent-name
+---
+
+You are an independent <Role Name>. <One paragraph: WHO you are + WHAT you own/deliver + your operating boundary (read-only vs writable).>
+
+**Your preloaded Skill contains the detailed methodology.** Follow it for HOW. This prompt defines WHO you are and WHAT you must deliver.
+
+## Artifact Ownership
+
+<If the agent owns artifacts: state sole ownership + the SendMessage-resume routing rule. Delete this section for read-only agents.>
+
+## Inputs
+
+| Parameter | Description |
+|-----------|-------------|
+| `change_dir` | change 目录路径 |
+
+## Structured Output Contract
+
+Return the following YAML to the orchestration layer:
+
+```yaml
+status: done | blocked
+summary: "..."
+```
+
+## Red Lines
+
+**DO:**
+- Follow the preloaded Skill's methodology for HOW
+
+**DON'T:**
+- DO NOT modify the `state` or `workflow` field of .team-flow.yaml (orchestrator's exclusive responsibility via `tf state transition`)
+- End your final response with an explicit terminal marker line: `FINAL VERDICT: <DONE | BLOCKED | FAIL>`

package/templates/conventions/_manifest.json

@@ -0,0 +1,39 @@
+{
+  "version": "1.0.0",
+  "updated_at": "2026-08-04",
+  "description": "team-flow conventions 模板清单，符合 glaf4-test 要求",
+  "templates": [
+    {
+      "name": "java-testing.md",
+      "version": "1.0.0",
+      "description": "Java 测试规范（JUnit 5 + Mockito），符合 glaf4-test 要求",
+      "tech_stack": ["java", "junit5", "mockito"],
+      "glaf4_compliant": true,
+      "source": "glaf4-test references + team-flow test-strategy"
+    },
+    {
+      "name": "spring-patterns.md",
+      "version": "1.0.0",
+      "description": "Spring Boot 测试规范，符合 glaf4-test 要求",
+      "tech_stack": ["java", "spring-boot"],
+      "glaf4_compliant": true,
+      "source": "glaf4-test references"
+    },
+    {
+      "name": "js-testing.md",
+      "version": "1.0.0",
+      "description": "JavaScript 测试规范（Jest/Vitest）",
+      "tech_stack": ["javascript", "jest", "vitest"],
+      "glaf4_compliant": false,
+      "source": "team-flow test-strategy"
+    },
+    {
+      "name": "python-testing.md",
+      "version": "1.0.0",
+      "description": "Python 测试规范（Pytest）",
+      "tech_stack": ["python", "pytest"],
+      "glaf4_compliant": false,
+      "source": "team-flow test-strategy"
+    }
+  ]
+}