@hunter-harness/workflow-harness 0.4.8 → 0.4.9

package/harness/bundles/java/pi/harness-execute/protocols.md

@@ -0,0 +1,141 @@
+---
+description: harness-execute 的原生执行协议。内化 TDD 与变更簇审查能力，但不运行时依赖 Superpowers。
+---
+
+# harness-execute 原生执行协议
+
+本文件定义 `/harness-execute` 的内置执行协议。它吸收 test-driven-development 与 subagent-driven-development 的有效做法，但正式流程不调用 Superpowers，也不把外部 skill 是否存在作为执行条件。
+
+## 协议一：run-tdd-protocol
+
+用于每个变更簇。目标是保留 RED→GREEN→REFACTOR 的行为约束，同时允许 harness 按证据分级处理缺失测试基础设施的现实情况。
+
+### RED 三态
+
+| RED 类型 | 何时使用 | 证据要求 |
+|----------|----------|----------|
+| 真实 RED | 测试基础设施可用，能写测试并运行失败 | 测试编译通过，失败断言指向目标行为 |
+| 静态 RED | 测试基础设施不可用或目标层无法真实验证 | 记录降级原因、静态验证场景、待 harness-execute 验证场景 |
+| 复用 RED | 计划和测试场景已明确失败场景，且本轮只执行同一场景的实现 | 引用 test-scenarios 编号与前序证据，仍需在 run 日志登记 |
+
+RED 失败原因必须与目标 bug 或需求直接相关。无效 RED（测试搭建错误、private 访问限制、mock/stubbing 错误、依赖注入失败、NPE 来自测试夹具）不得进入 GREEN。
+
+### GREEN
+
+GREEN 只做让当前变更簇通过的最小实现。不得顺手处理无关重构、顺手扩范围、或把未确认业务决策写入代码。
+
+### REFACTOR
+
+REFACTOR 只允许不改变行为的整理。若重构改变行为，必须回到 RED/GREEN。重构后重新运行当前变更簇对应验证；若无法运行真实测试，必须更新静态验证说明。
+
+### 证据写入
+
+每个变更簇结束必须写入或更新：
+
+- `evidence/verification-ledger.json`：构建/测试命令、证据、diffHash、复用状态。
+- `evidence/run-task-status.md`：任务状态、对应场景、未验证项。
+- `events.ndjson`：关键 command / verification / issue / artifact 事件；RED 类型、GREEN 结果、REFACTOR 结果和验证证据放入事件 `note`。
+
+执行日志是上述事件在阶段边界生成的只读投影，不作为变更簇的直接输出目标。
+
+禁止把静态验证写成“测试通过”。静态 RED/GREEN 的最终状态至少是 🟡WARN，除非后续真实验证已完成。
+
+上述分级只评估 `ownerPhase=run` 的任务和场景。`ownerPhase=test` 的验证按计划留给测试阶段时，记录为“待测试阶段执行”，不得将编码阶段降级为 WARN；后续阶段未开始不是当前阶段的风险。
+
+## 协议二：change-cluster-review-protocol
+
+用于高风险变更簇后的轻量审查。它内化 subagent-driven-development 的“新上下文审查”价值，但不把每个变更簇的 subagent 审查设为默认流程。
+
+### 触发条件
+
+满足**全部**条件时启用：
+
+- 变更簇命中高风险（数据迁移、权限、安全、并发、幂等、核心契约变更、缺真实测试证据等，见原触发列表任一）
+- 当前宿主已显式提供隔离 reviewer 能力；需要固定 reviewer 时，单次 `check-agents` 返回 `executionMode=delegated`
+
+未满足时记录“跳过变更簇隔离审查：低风险 / 正常 inline / 后续 harness-review 覆盖”，不得视为降级或显示不可用告警。
+
+### 审查方式
+
+`executionMode=delegated` 时委派只读 `harness-reviewer` 审查当前变更簇 diff。**不 retry**；spawn 失败或无效返回 → 主会话 checklist 自审，记一次 `issue` 事件。
+
+审查范围只限当前变更簇：
+
+- 是否偏离 plan / implementation-detail。
+- 是否遗漏 test-scenarios 中的 P0/P1 场景。
+- 是否破坏 API、数据、权限、安全或兼容契约。
+- 是否引入非计划文件、临时 debug、敏感信息或过程性注释。
+
+### 输出
+
+审查结论写入当前 run 日志：
+
+```markdown
+### 变更簇审查 — <cluster>
+- 触发原因: <risk trigger>
+- 方式: reviewer / 主会话自审 / 跳过
+- 结论: OK / YELLOW / RED
+- 问题: <文件:行 + 建议>
+```
+
+RED 问题必须在当前 run 中处理或明确记录为未处理风险；YELLOW 问题可交给后续 `/harness-review`。
+
+## fixback 证据契约
+
+> `launch-review` 的返回体里带 `evidenceContract` 字段，内容与本节一致。这里写一份是因为
+> 光靠运行时返回，调用方往往已经动手改代码了才看到。
+
+### 命令链
+
+```text
+run-start（修复前，采 RED）→ 改代码 → run-start（修复后，采 GREEN）
+  → evidence-template ×2 → register-evidence ×2 → resolve-issue
+  → run-start（受影响链）→ evidence-template --kind verification
+  → evidence-template --kind review → close
+```
+
+### 别手写证据 JSON
+
+证据文件的 `provenance` 需要 `sessionId` / `commandHash` / `resultDigest` / `runReceiptPath`
+四个字段，全部能从 `session.json` 直接读出来。用模板生成，不要手抄：
+
+```text
+python <skills-root>/scripts/harness_fixback.py evidence-template \
+  --change-dir <change-dir> --kind red|green|verification|review \
+  --session <sessionId> --out <证据 JSON 路径> --json
+```
+
+输出即可直接喂给 `register-evidence`。撞 `FIXBACK_RUN_PROVENANCE_INVALID` 时，错误体会点名
+**哪个字段、期望什么、实际什么**——按它改，不要去读实现反推。
+
+### `--product-identity`
+
+产品身份指纹，把 RED/GREEN 绑定到同一产品状态。规范取值是**当前 git HEAD**。省略即自动推导，
+`launch-review` 会在返回体的 `resolvedProductIdentity` 里回显；`close --final-product-identity`
+**原样引用那个值**，不要另行推导——推导方式不同就会撞 `FIXBACK_GREEN_IDENTITY_MISMATCH`。
+
+### RED 必须在修复之前
+
+RED 证明问题真实存在，GREEN 证明修复真的生效。先改完再把改动回退来凑 RED，证明的只是回退后的
+状态，不是原始缺陷，中途还会留下脏工作树。
+
+### close 的两张收据与 review-findings.json
+
+`close` 要 `--affected-receipt`（`kind=verification`，受影响链的托管会话）和 `--review-receipt`
+（`kind=review`，指向 `reports/review/review-findings.json`）。
+
+review 收据的放行规则按 **disposition**，不按 severity：
+
+| disposition | 是否阻塞 | 说明 |
+|---|---|---|
+| `OPEN` / 未登记 | ❌ 阻塞 | 还没人处置，必须先给结论 |
+| `FIXED` / `NOT_APPLICABLE` | ✅ 放行 | 已闭环 |
+| `ACCEPTED_RISK` / `DEFERRED` | ✅ 放行 | 记入收据 `residualRisks` 留痕 |
+
+> ⚠️ **不要为了让 close 通过而清空或删改 `review-findings.json`。** 它是发现的真相源，写空等于
+> 抹掉整轮审查的审计轨迹。处置结论属于另一个 sidecar：
+>
+> ```text
+> python <skills-root>/scripts/harness_review.py write-dispositions \
+>   --change-dir <change-dir> --input <dispositions.json>
+> ```

package/harness/bundles/java/pi/harness-execute/testing-checklist.md

@@ -0,0 +1,320 @@
+---
+description: harness-execute 的 Phase 0 环境准备 + Playwright 探测 + 关门检查清单。仅在执行测试前的环境准备阶段读取。
+---
+
+# harness-execute 检查清单 — Phase 0 环境准备 + 关门检查
+
+这 7 项确认完了再开始测试。每一项背后都有踩坑经历。
+
+#### 0.0 加载项目配置（如存在）与确定变更名
+
+先检查当前项目的测试配置文件（按优先级查找）：
+
+1. **优先**：`.harness/config/harness-test-config.md`（集中配置目录）
+2. **兼容**：`harness-execute/harness-test-config.md（兼容旧路径）`（旧路径，过渡期仍支持）
+
+如果任一文件存在，**必须先读取并应用其中的配置**。配置文件通常包含：
+
+- **登录端点**：本地无法直接登录时，远程 SSO/Gateway 的登录 URL
+- **测试账号**：各权限级别的用户名密码（如 admin、一层组织管理员等）
+- **真实测试数据**：有效的部门编码和名称、项目 ID、规则 ID 等
+- **环境调整**：需要使用的 profile、需要临时放行的 URL 路径、需要跳过的模块
+- **避坑补充**：本项目特有的已知问题和解决方案
+
+**Profile 选择**（从配置文件读取，如无配置则询问用户）：
+
+| Profile | 适用场景 | 配置文件 |
+|---------|---------|---------|
+| `local` | 连接远程数据库/Redis | `application-local.yml` |
+| `local-dev` | 完全本地隔离 | `application-local-dev.yml` |
+
+> **关键**：不指定 profile 时默认使用 `application.yml` 中的配置（可能指向生产环境），必须显式指定。启动命令必须包含 `--spring.profiles.active=<profile>`。
+
+然后确定变更名：用 Glob 搜索 `.harness/changes/*/plans/*-plan.md`（**排除 `.harness/archive/*/`**），读取 frontmatter 提取 `change-name`。
+
+#### 0.0y：命令执行模式 preflight（⚠️ 必须在编译/启动服务/生成 runner 之前执行）
+
+- [ ] 检查 PowerShell 基础命令：`powershell.exe -NoProfile -Command "$PSVersionTable.PSVersion"` 返回 exitCode=0
+- [ ] 检查 Node 绝对路径：`powershell.exe -NoProfile -Command "& 'C:\nvm4w\nodejs\node.exe' --version"` 返回 exitCode=0
+- [ ] 检查 Maven 可用性：`powershell.exe -NoProfile -Command "mvn -version"` 返回 exitCode=0
+- [ ] 读取 `.mvn/maven.config`，Maven 命令不重复或覆盖已有 `-s` / `-o` / 仓库设置
+- [ ] 离线依赖缺失时仅在项目规则允许联网时执行至多一次非离线 `-nsu` 恢复；失败后停止，禁止切换参数反复重试
+- [ ] 检查安全分类器：上述任一命令是否返回"安全分类器暂时不可用" / Auto mode 拦截 → **不应出现**
+- [ ] 将通过的 `nodeAbsolutePath` / `powershellVersion` / `mvnVersion` 写入 `.harness/changes/<change-name>/runtime/preflight.json`
+- [ ] **任一情况触发硬停**：原文输出"❌ 命令执行模式不可用：PowerShell/Node runner 无法稳定执行..."，**不得继续编译/启动服务/生成 runner，不得长时间等待，不得盲目降级到 Playwright MCP**
+- [ ] 用户确认切换权限模式后，**重新执行 0.0y**；重试 ≤ 1 次
+
+#### 0.0x：fallback 执行器探测（仅在 Node runner 不可用时执行）
+
+- [ ] 如果 0.0y 已确认 PowerShell Node API runner 可用：标记 `NOT_NEEDED`，**跳过本阶段**，直接使用 Node runner
+- [ ] 仅当 Node runner 不可用时，检查 PowerShell batch runner (`.ps1`) 是否可用
+- [ ] 仅当 PowerShell batch 也不可用时，检查 Claude Code 是否暴露 Playwright MCP 工具（`mcp__plugin_playwright_playwright__*` 存在）
+- [ ] 检查 `claude mcp list` 中是否有 playwright（如果可以执行命令）
+- [ ] 检查 `@playwright/mcp` 是否可启动
+- [ ] 检查当前 skill 的 `allowed-tools` 是否允许 Playwright 相关工具
+- [ ] 输出 fallback 执行器可用性表格（见 testing-reference.md）
+- [ ] 记录决策：PowerShell Node API runner / PowerShell batch / Playwright MCP browser_evaluate / curl fallback
+- [ ] 如果 fallback 不可用，必须写明原因，不得静默改用 curl
+
+#### 0.1 编译确认
+
+```powershell
+powershell.exe -Command "Test-Path 'target/classes/<package>/<ChangedClass>.class'"
+```
+编译产物时间戳早于源文件 → 重新编译：
+```powershell
+powershell.exe -Command "mvn compile -pl <module> -o -q"
+```
+
+**编译成功必须有证据**：
+- mvn 输出包含 `BUILD SUCCESS` 才能继续测试
+- 如果命令被 hook 拒绝（`Denied` / `PreToolUse:Bash hook error`），停止流程
+- 不得在编译失败时继续宣称"准备进入测试阶段"
+
+#### 0.1b 依赖模块预安装检查
+
+> **强制检查，不可跳过。** 即使服务已运行，worktree 中的编译仍可能缺少依赖（服务可能从主目录启动）。
+
+**在编译前检查上游依赖模块是否已安装到本地仓库**：
+
+```powershell
+powershell.exe -Command "Test-Path '$env:USERPROFILE\.m2\repository\<group-path>\<module>\*\*.jar'"
+```
+
+如果缺失，先安装上游依赖：
+```powershell
+powershell.exe -Command "mvn install -pl <upstream-modules> -am -DskipTests -nsu"
+```
+
+#### 0.2 认证方案确认
+
+| 方案 | 适用场景 | 操作 |
+|------|----------|------|
+| A. 配置放行 | 纯本地开发 | `application-local.yml` 的 `permit-all-urls` |
+| B. 本地 Token | 有本地 SSO | 通过本地登录接口获取 |
+| C. 权限降级 | 临时测试 | 无认证上下文时降级为 admin |
+
+> ⚠️ 方案 A 或 C 时，测试完成后确认还原配置。
+
+#### 0.3 请求头确认
+
+所有 HTTP 请求必须带：`Content-Type: application/json; charset=UTF-8` 及 build-profile 的 `httpHeaders`。
+
+#### 0.4 编码确认
+
+Windows 环境特别注意：
+- 不要用 `curl` 发送含中文的请求体（curl 在 Windows 默认用 GBK 编码）
+- 优先用 PowerShell Node API runner；单次临时请求可用 PowerShell `Invoke-RestMethod`
+- curl 仅作为最后兜底，且必须用 UTF-8 JSON body file
+
+#### 0.5 服务确认、Service Decision Gate 与启动等待
+
+检查服务是否运行（优先使用已知接口，不依赖 `/actuator/health`）：
+
+```powershell
+powershell.exe -NoProfile -Command "Test-NetConnection -ComputerName localhost -Port <port>"
+powershell.exe -NoProfile -Command "try { (Invoke-WebRequest -Uri 'http://127.0.0.1:<port>/<context-path>/meta' -UseBasicParsing -TimeoutSec 3).StatusCode } catch { $_.Exception.Message }"
+```
+
+**如果端口已有 <service-module-from-build-profile> 进程，必须先进入 Service Decision Gate，禁止先跑业务接口。**
+
+需要展示：pid、profile、startTime、commandLine、healthResult、serviceFingerprint(match/missing/mismatch)、当前源码是否晚于服务启动时间。
+
+询问用户：
+
+```text
+1. 直接复用当前服务
+2. 重启服务，使用 known-good-test-profile
+3. 跳过接口测试，只执行单元测试
+4. 停止测试
+```
+
+只有 service-fingerprint 与当前真实 diffHash/profile/sdkUrl/startCommandHash 完全匹配时，才允许自动复用。否则必须询问。
+
+**如果服务未运行**，询问用户：
+
+```text
+服务未启动（端口 <port> 无响应）。请选择：
+1. AI 启动 — 使用 known-good-test-profile，serviceState=AI_STARTED
+2. 用户手动启动 — 启动后告诉我继续，serviceState=USER_STARTED
+3. 跳过接口测试 — 只运行单元测试，serviceState=NOT_STARTED
+4. 停止测试
+```
+
+**如果用户选择 AI 启动或 AI 重启**：
+1. 从 `known-good-test-profile` 读取 module/profile/port/healthUrl/sdkUrl。
+2. 生成 ASCII overlay：`C:/temp/harness-execute-overlay/<change-name>/application-harness-execute.yml`。
+3. 禁止默认直接 Edit tracked `application-local-dev.yml`。
+4. 默认启动命令：
+   ```powershell
+   powershell.exe -NoProfile -Command "mvn spring-boot:run -pl <module-from-build-profile> -Dspring-boot.run.profiles=local-dev -Dspring-boot.run.jvmArguments='-Dspring.config.additional-location=file:C:/temp/harness-execute-overlay/<change-name>/application-harness-execute.yml'"
+   ```
+5. 写入 `service.pid`、`service-start-command.txt`、`service-start.log`、`service-fingerprint.json`。
+6. 服务启动等待：0–30s 每 2s 探测；30–120s 每 5s 探测；>10s 必须输出状态行；>120s 读取最近 200 行日志。
+7. 发现 `BindException` / `Could not resolve placeholder` / `Connection refused during bean init` / `BeanCreationException` / `Failed to start bean` / `BUILD FAILURE` 立即失败。
+
+#### 0.5x 重入沿用（同一变更 harness-execute 再次执行时）
+
+满足以下**全部**条件时，可沿用上次服务决策，不重复询问：
+
+1. 重入：同一 change-name 的 harness-execute 再次执行（非首次）
+2. 环境未变：PG 可用性、目标端口、执行器可用性与上次一致
+3. 上次已确认执行器/服务方案（如"AI_STARTED，known-good-test-profile，端口 N"）
+4. 当前源码未改服务启动逻辑（如未改 main 启动路径、未改端口/profile 配置、未改 spring-boot:run 启动相关代码）
+
+沿用时执行日志记录：`重入沿用上次服务决策 + 环境未变（PG=<同上次>、端口=<同上次>、执行器=<同上次>）`。
+
+**不适用重入沿用**（仍须询问/重启）：
+- service-fingerprint 不匹配（diffHash 变化说明源码改了）
+- 环境已变（PG 从不可用变可用、端口被占、执行器丢失）
+- 上次 serviceState=USER_STARTED（用户手动启动，状态未知）
+- 源码改动影响服务启动逻辑
+
+#### 0.5d 服务生命周期收尾（即使测试失败也要进入 finally 清理）
+
+测试结束前必须按 serviceState 分支处理：
+
+- `AI_STARTED` → 默认 `Stop-Process -Id <pid> -Force`，删除 `service.pid`，记录 `testServiceStopped=✅`。
+- `AI_RESTARTED_FROM_USER_SERVICE` → 默认停止新服务，报告中明确 `restoredOriginalService=❌ not supported`。
+- `USER_STARTED` → 保留进程，报告中提示用户可手动停止。
+- `REUSED_EXISTING` → 保留进程，除非用户明确要求关闭。
+
+测试报告与 `summary-data.json` 的服务生命周期投影必须包含：
+
+```md
+## 服务生命周期
+| 项 | 值 |
+|---|---|
+| originalServicePid | ... / N/A |
+| originalServiceStopped | ✅ / ❌ / N/A |
+| testServicePid | ... / N/A |
+| testServiceStopped | ✅ / ❌ / N/A |
+| restoredOriginalService | ❌ not supported / N/A |
+| finalPortState | no service / service running |
+```
+
+> 不要使用 Monitor 工具等待健康检查，直接用 PowerShell 检查已知接口。`/actuator/health` 可能返回 404。
+
+#### 0.5b 配置文件完整性检查
+
+**如果使用 worktree**，检查配置文件是否完整：
+
+```powershell
+powershell.exe -Command "Test-Path '<worktree-path>/<module>/src/main/resources/application-<profile>.yml'"
+```
+
+如果缺失，从主目录复制：
+```powershell
+powershell.exe -Command "Copy-Item '<main-dir>/<module>/src/main/resources/application-<profile>.yml' '<worktree-path>/<module>/src/main/resources/' -Force"
+```
+
+**检查关键配置项**（读取配置文件内容确认）：
+- `workflow.baseUrl`（或类似条件属性）— 缺失会导致 Bean 创建失败
+- `spring.cloud.nacos.discovery.register-enabled: false` — 缺失会导致线上流量路由到本地
+- `udp.security.permit-all-urls` — 需包含本次测试的接口路径
+
+#### 0.5c Playwright 远程访问确认
+
+如果接口测试需要通过 Playwright 访问远程服务（如远程 SSO 获取 token），确认 Playwright MCP 配置允许目标地址。
+
+检查 `.mcp.json` 或全局 MCP 配置中 Playwright 的 `allowedOrigins`：
+```json
+{
+  "playwright": {
+    "allowedOrigins": ["http://localhost:*", "http://<remote-ip>:*"]
+  }
+}
+```
+
+> 如果 Playwright 无法访问远程地址，降级为 PowerShell Invoke-RestMethod 获取 token。
+
+#### 0.6 Nacos 风险确认
+
+确认 `application-local.yml` 中 `spring.cloud.nacos.discovery.register-enabled: false`。
+
+## 接口测试执行检查
+
+### Token 缓存与复用
+
+- [ ] 检查 `.harness/changes/<change-name>/runtime/credential-cache.json` 是否存在
+- [ ] 如果存在 → 读取已有 token，用**本地轻量接口**（直连本地 baseURL）验证有效性
+- [ ] 验证通过 → 复用，不重新登录、不访问远程 SSO
+- [ ] 验证失败（401/expired） → 才访问远程 SSO 重新获取后写回 cache
+- [ ] 同一上下文中，前面已获取过 token 时必须优先复用
+- [ ] **同一次测试流程内只允许因 token 失效重新获取 1 次**；超过 1 次 → 🟡 WARN，记录原因
+- [ ] API runner 用 request context / node fetch 直连本地 baseURL，**不依赖浏览器当前页面 origin**
+- [ ] **不得因浏览器 origin 在 SSO 就重新获取 token**；禁止"SSO 取 token→导航 localhost→重新取 token"
+- [ ] **不得在报告、execution-log、对话总结中输出明文 token**
+
+### 单元测试复用（ledger 驱动）
+
+- [ ] Phase 1 前通过共享状态目录解析器读取 `evidence/verification-ledger.json`
+- [ ] 判断是否复用 run 的 unitTest：diffHash 一致 + module/profile 一致 + scope 一致或更严格 + run 后无行为性修改 + run 实际跑了全量 mvn test
+- [ ] 复用 → 跳过重跑，标记"✅ 复用 harness-execute 单元测试结果"
+- [ ] 不复用 → 重跑 `mvn test -pl <module>`，结果写回 ledger 的 `unitTest` 项
+- [ ] HTTP/API 契约结果写入 `apiTest`；真实浏览器/真实栈 Playwright 结果写入 `browserTest`，两者不得互相覆盖
+
+### 批量 Runner（强制单次 PowerShell + Node 绝对路径执行）
+
+- [ ] 0.0y preflight 已通过，`preflight.json` 包含 `nodeAbsolutePath`
+- [ ] 生成 `.harness/changes/<change-name>/runtime/api-test-runner.mjs`，**按 setup / test / cleanup 三阶段结构**编写
+- [ ] payload 来自 `<XxxSaveReqVO>` / Controller / 真实样例，runner 注释/JSON 中标注字段来源；**禁止临场猜字段、禁止先跑失败接口再补**
+- [ ] 唯一前缀 `JAVATEST_<change-name>_<timestamp>_<random>`，priority/projectSubtype 用随机或避让策略，防 `priority=1` 冲突
+- [ ] 通过**一次命令**执行（PowerShell + node 绝对路径）：
+   ```powershell
+   powershell.exe -NoProfile -ExecutionPolicy Bypass -Command "& '<nodeAbsolutePath>' '.harness/changes/<change-name>/runtime/api-test-runner.mjs'"
+   ```
+- [ ] **禁止**裸 `node ...`、禁止用 Bash 执行 node
+- [ ] runner 失败 ≤ 1 次重试；仍失败 → 提示用户切换权限模式或手动执行，**不得继续盲目重试或长时间等待**
+- [ ] runner 输出 `.harness/changes/<change-name>/runtime/api-test-results.json`，包含
+      `passed/failed/blocked/skipped/setupErrors/cleanupResult/tokenRefreshCount`
+- [ ] **setup 失败时依赖该数据的场景必须标 🟡 BLOCKED，不得用 null ID 继续请求**
+- [ ] 主会话只 Read JSON 生成摘要，不再调用 MCP
+- [ ] **只有 Node runner 不可执行才降级**：PowerShell batch (.ps1) → 多次 MCP `browser_evaluate` → curl
+- [ ] **如果 Node 在 PowerShell 可用，禁止使用 Playwright MCP 逐条执行接口测试**
+- [ ] runner 直连本地 baseURL，复用 token，不依赖浏览器 origin
+- [ ] 记录每个请求的 durationMs、status、code、message、assertionResult
+- [ ] 支持失败时继续执行后续非依赖场景
+- [ ] 报告区分四种执行器：**PowerShell Node API runner / PowerShell batch / Playwright MCP browser_evaluate / curl**（不得与"Playwright"混写）
+
+### 测试数据命名
+
+- [ ] 所有测试数据使用前缀 `JAVATEST_<change-name>_<timestamp>_<random>`
+- [ ] 测试报告记录测试数据表（ID、Code、用途、是否需要清理）
+- [ ] 测试结束后清理可清理的数据
+- [ ] 不能清理的记录遗留数据和原因
+
+### 请求耗时
+
+- [ ] 每个请求记录 durationMs
+- [ ] durationMs > 10000 → 🟡SLOW，说明原因
+- [ ] durationMs > 30000 → ❌TIMEOUT_RISK，说明原因
+
+## 关门检查（⚠️ 结束前强制执行）
+
+- [ ] `powershell.exe -NoProfile -Command "git status --porcelain"`
+- [ ] `powershell.exe -NoProfile -Command "git diff --stat"`
+- [ ] `powershell.exe -NoProfile -Command "git diff --check"`（如果失败 → 最终结果 ❌FAIL）
+- [ ] 检查报告和日志是否包含明文 token/password/secret/access-key/client-secret
+- [ ] 检查 `.harness/changes/<change>/runtime/` 是否不会被提交（.gitignore 确认）
+- [ ] **服务生命周期收尾**：AI_STARTED→Stop-Process / USER_STARTED→提示 / REUSED_EXISTING→保留或确认 / NOT_STARTED→N/A
+- [ ] 检查测试数据是否需要清理
+- [ ] 检查请求执行器结果是否完整（4 种执行器，未与 API runner 混写）
+- [ ] 检查是否存在慢请求或超时风险
+- [ ] **API 维度状态正确**：5 PASS + 9 BLOCKED + 1 FAIL → `apiTest=PARTIAL`，不得写成 `NOT_RUN`
+- [ ] 如果存在未清理测试数据、fallback 请求执行器、慢请求或环境变更 → 至少 🟡WARN
+
+## 关键原则
+
+- 如果有项目配置文件，优先从 `.harness/config/harness-test-config.md` 读取并应用（含 `known-good-test-profile`）
+- 环境准备（阶段 0）的 **0.0y 命令执行模式 preflight + 7 项检查 + Playwright 探测** 必须在测试之前全部通过
+- 单元测试优先于接口测试（先跑 `mvn test`，通过后再跑接口）
+- 接口测试优先级：**PowerShell Node API runner > PowerShell batch > Playwright MCP browser_evaluate > curl**
+- 单用例失败不阻塞后续用例；setup 失败时依赖场景必须标 🟡 BLOCKED，**不得用 null ID 继续请求**
+- 失败类型必须区分：代码 Bug vs 测试脚本问题 vs 预存问题
+- 测试数据使用唯一前缀命名 + 唯一字段（priority/projectSubtype）随机或避让，测试后确认清理或记录遗留
+- 测试报告持久化到 `.harness/changes/<change-name>/reports/test/test-report-YYYYMMDD-HHmm.md`（时间戳区分多次运行）
+- 请求执行器必须在报告中明确记录（四种执行器，含降级原因）
+- 请求耗时统计必须包含在报告中
+- 服务由 AI 启动的情况，测试结束默认 Stop-Process；**即使测试失败也要进入 finally 清理**
+- `summary-data.json` 与平台监控中的 `apiTest` 状态必须使用 OK/PARTIAL/BLOCKED/NOT_RUN/FAIL（不得把 PARTIAL 写成 NOT_RUN）

package/harness/bundles/java/pi/harness-execute/testing-pitfalls-java.md

@@ -0,0 +1,16 @@
+# Java 通用踩坑（overlay）
+
+> 项目专属端口/模块/tenant 值 → [[PROJECT-PROFILE-EXAMPLE.md|PROJECT-PROFILE-EXAMPLE]] / `build-profile.json`
+
+| # | 规则 | 现象 | 原因 | 处理 |
+|---|------|------|------|------|
+| 1 | Maven 用 PowerShell | Bash 被拒/乱码 | 中文路径 + hook | `powershell.exe -NoProfile -Command "mvn ..."` |
+| 2 | `-pl` 限定模块 | 无关子模块编译失败 | `-am` 拉起坏 POM | 用 `-pl <module>`，慎用 `-am` |
+| 3 | settings 相对路径 | Maven 输出乱码 | settings 含中文绝对路径 | `.mvn/maven.config` 用相对 `-s` |
+| 4 | 改代码后先 compile | 测试结果不变 | IDE 热重载未生效 | 测试前 `mvn compile -o` |
+| 5 | 禁止 Bash 跑 node | runner 失败 | disallowed-tools | PowerShell + 绝对路径 node |
+| 6 | Mock Mapper ≠ DB 验证 | 假绿 | 纯 Mock 返回值 | 🟡 静态验证，交 harness-execute |
+| 7 | 请求体禁止临场猜 | 大面积 400 | 字段与 VO 不一致 | 从 Controller/VO/契约生成 |
+| 8 | 唯一字段加前缀 | 409/冲突 BLOCKED | 测试数据撞库 | `TEST_<change>_<ts>_<rand>` |
+| 9 | runtime overlay | tracked 配置被改 | 直接 Edit yml | additional-location 叠加 |
+| 10 | Service Gate 先决策 | 旧服务 500 | 端口已有进程 | ensure → needs-user-decision 才问 |