@hunter-harness/workflow-harness 0.4.3 → 0.4.9

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

@@ -0,0 +1,307 @@
+---
+description: harness-execute 的踩坑规则（来自真实对话日志）。执行测试前必须通读，遇到测试失败时重新参考。
+---
+
+# 避坑规则（32 条）
+
+> 以下规则来自真实对话日志（2026-06-12 ~ 08-17），每个都有明确的现象和根因。
+> 执行 `harness-execute` 时必须通读，避免重蹈覆辙。
+
+| # | 规则 | 现象 | 根因 | 解法 |
+|:--:|------|------|------|------|
+| 1 | 凭证可展示但注意安全 | 对话日志记录了凭证 | Bearer 凭证被粘贴到聊天中 | 凭证可以在对话中展示用于调试，但不要写入持久化文件（测试报告、执行日志等） |
+| 2 | 不用 curl 发中文 | `Invalid UTF-8 start byte 0xb2` | Windows curl 默认 GBK 编码 | 用 PowerShell Invoke-WebRequest 或 Playwright fetch |
+| 3 | 必须带租户标识 | 所有接口 500，或 200 但 `data:null` | 租户上下文为空，或请求头租户值与测试数据行的租户不一致 | 请求头加租户标识（见 build-profile.httpHeaders）；**取值必须等于测试数据实际所属租户**，先查数据行的租户列再填，不要默认写 0 |
+| 4 | 认证降级 | 接口 401 "账号未登录" | 本地无认证服务 | 应用配置放行（如 permit-all-urls）或权限降级 |
+| 5 | 错误码双格式兼容 | 测试断言失败 | 预期 `1_003_002_009`，实际 `1003002009` | 自动兼容下划线和数字两种格式 |
+| 6 | 编译产物确认 | 修改代码后测试结果不变 | IDE 热重载未触发 | 测试前编译（如 `mvn compile -o`） |
+| 7 | 构建工具配置路径用相对 | 构建工具输出 `׻ֹ` 乱码 | 配置文件路径含中文 | 构建工具配置用相对路径（如 `.mvn/maven.config` 用 `-s ../settings.xml`） |
+| 8 | 跳过无关模块 | `mvn compile -am` 在无关子模块报错 | 子模块 POM 无 parent | 用 `-pl <module>` 不 `-am` |
+| 9 | 服务注册只发现不注册 | 线上流量被路由到本地 | register-enabled=true | 确认服务注册开关关闭（如 `register-enabled=false`） |
+| 10 | 先导航再 fetch | `fetch is not defined` | 页面是 about:blank | 先 `browser_navigate` 到服务页面 |
+| 11 | MCP 就绪等待 | `No such tool available` | 服务器仍在连接 | 等 MCP 连接完成再调用 |
+| 12 | 大请求体分批 | `Range of input length [1, 202745]` | 上下文超 API 输入限制 | 超过 200KB 时分批 |
+| 13 | 必填字段先查明 | 创建资源 500 | 不知道必填字段有哪些 | 查看已有代码或数据契约定义 |
+| 14 | 用唯一编码 | 编码冲突错误 | 之前测试已创建同名编码 | 每个用例使用唯一编码，测试后清理 |
+| 15 | permit-all 放行 ≠ 有用户上下文 | 接口返回 500 "系统异常" | 安全层放行但业务层调用权限校验时当前用户为 null | 获取真实凭证带上，或跳过需要用户上下文的接口 |
+| 16 | 远程认证服务获取凭证 | 本地无独立认证服务，无法登录 | 应用服务不提供登录接口 | 通过远程认证服务（如 SSO/Gateway）登录获取凭证，或从项目配置文件中读取已知凭证 |
+| 17 | Windows 禁用 Python3 解析 JSON | 凭证提取静默失败，后续所有请求未认证 | Windows 环境 Python3 可能段错误（segfault） | 用 `grep -o + cut` 或 PowerShell `ConvertFrom-Json` 替代 |
+| 18 | **Bash 不可执行执行器（如 node）** | "Bash 中没有 node" → 错误降级到 Playwright MCP | Windows 中文路径项目下 Bash 被 hook 拒；Node 不在 Bash PATH | 强制 `powershell.exe -NoProfile -ExecutionPolicy Bypass -Command "& '<executorPath>' '...mjs'"`，禁止裸 `node`、禁止用 Bash 执行执行器 |
+| 19 | **Auto mode / 安全分类器降级时静默等待** | 接口测试长时间无响应，最终错误降级到逐条 MCP | PowerShell 命令被安全分类器拦截，Claude 静默重试 + fallback | Phase 0.1 preflight 检测出后**硬停**，原文输出"命令执行模式不可用..."，提示用户切换权限模式 |
+| 20 | **Playwright API 执行器与 Playwright MCP 混写** | 报告写"Playwright ✅ 使用"，实际是逐条 `browser_evaluate` | 两者被笼统称为"Playwright" | 报告中**强制区分**四种执行器：接口测试执行器 / PowerShell batch / Playwright MCP browser_evaluate / curl |
+| 21 | **直接 Edit tracked 应用配置文件** | 测试期间改配置，之后又还原，diff 噪声大 | 把运行时配置覆盖直接写进 tracked 文件 | 生成 ASCII 运行时配置叠加 `C:/temp/harness-execute-overlay/<change>/application-harness-execute.yml`，启动用该绝对路径叠加（如 `-Dspring.config.additional-location=...`） |
+| 22 | **唯一约束字段与本地预存数据冲突** | 大面积唯一约束冲突，9 个场景 BLOCKED | 执行器用硬编码字段值 | 用随机值（如 `900000 + random`）/ 先查避让 / 用唯一隔离值 |
+| 23 | **setup 失败后继续用 null ID 发送请求** | 后续 9 个接口全部 400/500，掩盖真正问题 | 执行器不区分 BLOCKED 状态 | 执行器强制 setup/test/cleanup 三阶段，依赖未满足 → 标 🟡 BLOCKED，**不发起请求** |
+| 24 | **归档数据把 PARTIAL 写成 NOT_RUN** | 平台显示「未执行」，但实际跑了 6 个场景 | 状态枚举不完整，只有 OK/FAIL/NOT_RUN | API 维度状态使用 OK/PARTIAL/BLOCKED/NOT_RUN/FAIL，5 PASS+9 BLOCKED+1 FAIL → `apiTest=PARTIAL` |
+| 25 | **AI 启动的服务测试结束不关闭** | 端口长期占用，下次启动端口占用异常（如 `BindException`） | 没有 service lifecycle 管理 | 通过 `service.pid` + `serviceState` 区分，AI_STARTED 默认 Stop-Process，**即使测试失败也 finally 清理** |
+| 26 | **凭证在同一流程内重复获取** | 浏览器 origin 在认证服务就再走一次登录 | 执行器依赖浏览器当前页面 origin | 执行器用 request context 直连本地 baseURL，凭证从 cache 读，`credentialRefreshCount > 1` → 🟡 WARN |
+| 27 | **服务启动盲等 + 无反馈** | 等待 90s 后才发现启动报错 | 没有启动状态机和异常关键字检测 | 0–30s/2s × 30–120s/5s 状态机；遇启动失败特征（按技术栈，如 BindException/Could not resolve placeholder/BeanCreationException）立即停；> 10s 必须输出一次状态行 |
+| 28 | **已有服务未先决策就跑业务接口** | 旧服务不含新代码，接口 500 后才发现版本不匹配 | 检测到已有应用服务（端口被占）后，未先展示服务决策门就跑业务接口 | 先展示服务决策门，询问复用/重启/跳过/停止；询问前只允许 health/meta 检查 |
+| 29 | **启动命令反复试相对配置叠加 / 中文路径** | 相对路径或中文路径导致应用读不到运行时配置叠加，启动失败 | 默认只用 `C:/temp/harness-execute-overlay/<change>/application-harness-execute.yml` ASCII 绝对路径，并固化已知良好测试配置 |
+| 30 | **伪 diffHash 导致错误复用** | `3files-84plus-5minus` 不能证明代码未变 | 用 `git diff --binary` 生成 patch 并计算 SHA-256，ledger 只认 `sha256:<hash>` |
+| 31 | **尝试破解验证码 / 人机验证** | 认证服务返回"验证码不能为空"，AI 写图像识别脚本反复试坐标（实测 28 次 / 4 种算法全失败） | 测试配置里的账号密码登录流程被加了滑块/图形验证码，配置未同步 | **硬停**。禁止编写或运行任何验证码求解代码；立即标 `apiTest=BLOCKED`，请用户手工提供凭证写入 `runtime/credential-cache.json`，或临时关闭测试环境验证码 |
+| 32 | **预存环境缺陷被当成本次变更的阻塞** | `unitTestFull` 144 个测试挂 1 个，根因是别人提交引入的缺省配置缺失 | 全量验证把预存缺陷和本次 diff 混在一起判定 | 先用 `git log -S` + diff 触点证明与本次变更无关，再按「预存缺陷」上报并请用户决策（修根因 / 记 🟡WARN / 停止），**不得**擅自改 tracked 配置或排除测试 |
+
+
+## 详细说明
+
+### 规则 1：凭证可展示但注意安全
+**严重度**：🟡WARN
+**场景**：测试脚本需要 Bearer 凭证时，需要在对话中展示用于调试
+**正确做法**：凭证可以在对话中展示用于调试和验证。但不要将凭证写入持久化文件（测试报告、执行日志、代码注释等）。测试报告中引用凭证时用前 8 位 + `***` 脱敏。
+
+> 凭证处理遵循 `../protocols/sensitive-info-protocol.md`。
+
+### 规则 2：不用 curl 发中文
+**严重度**：❌FAIL
+**场景**：用 `curl -d '{"name":"张三"}'` 测试接口
+**后果**：Windows curl 默认 GBK 编码，服务器期望 UTF-8，导致 `Invalid UTF-8 start byte 0xb2`
+**正确做法**：用 PowerShell `Invoke-WebRequest` 或 Playwright MCP 的 `browser_evaluate` + `fetch`
+
+### 规则 3：必须带租户标识
+**严重度**：❌FAIL
+**场景**：忘记在请求头中加租户标识
+**后果**：租户上下文为空，所有接口返回 500，错误信息不直观，容易误判为权限问题
+**正确做法**：所有 HTTP 请求头使用 build-profile 的 `httpHeaders`（项目自定义）
+
+### 规则 4：认证降级
+**严重度**：🟡WARN
+**场景**：本地测试时收到 401 "账号未登录"
+**后果**：无法测试需要认证的接口
+**正确做法**：在应用配置文件中配置放行（如 `permit-all-urls`），或降级为高权限账号上下文。测试完成后还原配置。
+
+### 规则 5：错误码双格式兼容
+**严重度**：🟡WARN
+**场景**：测试断言预期 `1_003_002_009`，实际返回 `1003002009`
+**后果**：断言失败，误判为 Bug
+**正确做法**：自动兼容两种格式，比较时统一去掉下划线
+
+### 规则 6：编译产物确认
+**严重度**：🟡WARN
+**场景**：修改代码后运行测试，结果不变
+**后果**：IDE 热重载未触发，测试运行的是旧产物，浪费排查时间
+**正确做法**：测试前执行构建工具编译（如 `mvn compile -o`）确保编译产物最新
+
+### 规则 7：构建工具配置路径用相对
+**严重度**：🟡WARN
+**场景**：构建工具配置文件路径包含中文（如 Maven 的 settings.xml）
+**后果**：构建工具输出乱码字符 `׻ֹ`，编译失败
+**正确做法**：构建工具配置中使用相对路径（如 Maven 的 `.mvn/maven.config` 中 `-s ../settings.xml`）
+
+### 规则 8：跳过无关模块
+**严重度**：🟡WARN
+**场景**：构建工具编译带依赖模块（如 `mvn compile -am`）在无关子模块报错
+**后果**：被不相关的编译错误阻塞
+**正确做法**：只编译目标模块（如 Maven 用 `-pl <module>` 指定模块，不 `-am`）
+
+### 规则 9：服务注册只发现不注册
+**严重度**：❌FAIL
+**场景**：本地启动服务，服务注册开关开启（如 Spring Cloud Nacos 的 `register-enabled=true`）
+**后果**：线上流量可能被网关路由到本地机器
+**正确做法**：确认服务注册开关关闭（如 `spring.cloud.nacos.discovery.register-enabled: false`）
+
+### 规则 10：先导航再 fetch
+**严重度**：🟡WARN
+**场景**：直接调用 Playwright MCP 的 `browser_evaluate` 执行 fetch
+**后果**：`fetch is not defined`，因为页面是 about:blank
+**正确做法**：先 `browser_navigate` 到服务的任意页面，再执行 fetch
+
+### 规则 11：MCP 就绪等待
+**严重度**：🟡WARN
+**场景**：刚启动 Claude Code 就调用 MCP 工具
+**后果**：`No such tool available`，MCP 服务器仍在连接中
+**正确做法**：等待几秒确认 MCP 连接完成后再调用
+
+### 规则 12：大请求体分批
+**严重度**：🟡WARN
+**场景**：请求体超过 200KB
+**后果**：超出 API 输入限制，请求被截断
+**正确做法**：超过 200KB 时分批发送
+
+### 规则 13：必填字段先查明
+**严重度**：🟡WARN
+**场景**：创建资源时 500 错误
+**后果**：不知道必填字段有哪些，反复试错
+**正确做法**：查看已有代码中的请求示例或数据契约定义，确认必填字段
+
+### 规则 14：用唯一编码
+**严重度**：🟡WARN
+**场景**：多个测试用例使用相同编码
+**后果**：编码冲突错误，后续用例失败
+**正确做法**：每个用例使用唯一编码（加时间戳后缀），测试完成后清理
+
+### 规则 15：permit-all 放行 ≠ 有用户上下文
+**严重度**：❌FAIL
+**场景**：在应用配置文件中配置了放行（如 `permit-all-urls`），接口返回 200 但业务逻辑报 500 "系统异常"
+**后果**：安全框架（如 Spring Security）放行了请求，但安全工具获取当前用户返回 null。业务层调用权限校验方法时，内部远程调用失败，错误信息不直观
+**正确做法**：理解两层检查机制——安全层（Filter）和业务层（Service）是独立的。放行只跳过第一层，第二层仍需要有效的用户上下文。要么获取真实凭证带上，要么跳过需要用户上下文的接口
+
+### 规则 16：远程认证服务获取凭证
+**严重度**：❌FAIL
+**场景**：本地启动应用服务，自身不提供登录接口，无法获取访问凭证
+**后果**：所有需要认证的接口返回 401，无法测试
+**正确做法**：通过远程认证服务（如 SSO/Gateway）的登录接口获取凭证。查看项目配置文件（`harness-test-config.md`）中的登录端点和测试账号。如果项目配置不存在，询问用户如何获取有效的凭证
+
+### 规则 17：Windows 禁用 Python3 解析 JSON
+**严重度**：❌FAIL
+**场景**：用 Python3 解析 curl 返回的 JSON（如提取凭证）
+**后果**：Windows 环境 Python3 可能段错误（segfault），导致脚本静默失败，后续所有依赖该输出的命令全部异常（如凭证为空导致所有请求未认证）
+**正确做法**：用 PowerShell `Invoke-RestMethod` + `ConvertFrom-Json` 替代（推荐）：
+```powershell
+# 推荐：PowerShell Invoke-RestMethod + ConvertFrom-Json（经 Bash(powershell.exe:*) 通道或直接 PowerShell）
+$resp = Invoke-RestMethod -Uri '...' -Method Post -Headers @{...} -Body '...'
+$cred = $resp.data.accessToken
+```
+
+> **反例（禁止）**：以下 Bash + curl + grep + cut 方式违反 PowerShell-first 规则，不得使用：
+> ```bash
+> # ❌ 禁止：裸 Bash + curl + grep + cut（Windows 中文路径 + GBK 编码双重风险）
+> CRED=$(curl -s ... | grep -o '"accessToken":"[^"]*"' | cut -d'"' -f4)
+> ```
+
+### 规则 18：Bash 不可执行执行器（如 node）
+**严重度**：❌FAIL
+**场景**：日志显示 PowerShell 中确认了执行器可用，但接着错误地用 Bash `node api-test-runner.mjs` 执行，失败后直接降级到 Playwright MCP 逐条执行接口
+**后果**：浪费 1–2 分钟在错误降级路径上；接口测试以"Playwright"名义被逐条执行，丧失批量执行器的所有优势
+**正确做法**：硬规则——禁止裸 `node`、禁止用 Bash 执行执行器；必须 `powershell.exe -NoProfile -ExecutionPolicy Bypass -Command "& '<executorPath>' '...mjs'"`，`<executorPath>` 从 0.1 preflight 写入的 `preflight.json` 读取
+
+### 规则 19：Auto mode / 安全分类器降级时静默等待
+**严重度**：❌FAIL
+**场景**：Claude Code 在 Auto mode / 安全分类器临时不可用时，PowerShell 命令被拦截，Claude 静默重试、静默 fallback，最终接口测试卡住很久
+**后果**：用户体验极差，错误降级到逐条 MCP，最终报告里"Playwright"✅ 使用但实际是 fallback
+**正确做法**：Phase 0.1 preflight 检测出以下任一情况立即**硬停**：
+- 出现"安全分类器暂时不可用"
+- Auto mode 导致 PowerShell 命令不可执行
+- PowerShell 被拒
+- PowerShell 可用但执行器/构建工具不可执行
+
+输出原文："❌ 命令执行模式不可用：PowerShell/接口测试执行器无法稳定执行。请切换 Claude Code 权限模式..."；用户确认后重试 ≤ 1 次
+
+> 结果状态分级与硬停判定遵循 `../protocols/evidence-based-reporting-protocol.md`。
+
+### 规则 20：Playwright API 执行器与 Playwright MCP 混写
+**严重度**：🟡WARN
+**场景**：报告写"Playwright ✅ 使用"，实际是 Playwright MCP `browser_evaluate` 逐条执行
+**后果**：审计混乱，看不出真实降级路径
+**正确做法**：报告中**强制区分**四种执行器，且不得用一个"Playwright"代指两者：
+- `接口测试执行器` (`.mjs`)
+- `PowerShell batch runner` (`.ps1`)
+- `Playwright MCP browser_evaluate`
+- `curl`
+
+### 规则 21：直接 Edit tracked 应用配置文件
+**严重度**：🟡WARN
+**场景**：测试期间为了切换外部服务配置直接 Edit tracked 配置文件（如 `application-local-dev.yml`），测试后再还原，留下 diff 噪声
+**后果**：git diff --stat 出现意外文件、提交风险、误以为有业务变更
+**正确做法**：生成运行时配置叠加 `.harness/changes/<change>/runtime/application-harness-execute.yml`（不提交），启动用 `-Dspring.config.additional-location=file:...` 叠加（按技术栈）；如必须改 tracked 配置，先 blocking user confirmation，最终报告至少 🟡 WARN
+
+### 规则 22：唯一约束字段与本地预存数据冲突
+**严重度**：❌FAIL
+**场景**：执行器创建资源时唯一约束字段用硬编码值（如 `priority=1`），与本地已存在数据冲突，导致 9 个依赖该资源的场景全部 BLOCKED
+**后果**：API 测试出现大面积 BLOCKED，且容易误判为代码 Bug
+**正确做法**：所有创建类接口对唯一约束字段三选一：
+1. 随机：`900000 + Math.floor(Math.random() * 9999)`
+2. 先查再避让
+3. 用唯一隔离值隔离
+
+### 规则 23：setup 失败后用 null ID 继续请求
+**严重度**：❌FAIL
+**场景**：执行器没有阶段化，`createResource` 失败后 `resourceId=null`，但仍用 null 继续请求 9 个后续接口
+**后果**：后续接口大面积 400/500，掩盖真正的根因（setup 失败）
+**正确做法**：执行器强制 setup/test/cleanup 三阶段；依赖 setup 数据的场景在 test 阶段开头判定依赖，缺失则标 🟡 BLOCKED，**不发起请求**
+
+### 规则 24：归档数据把 PARTIAL 写成 NOT_RUN
+**严重度**：🟡WARN
+**场景**：15 个 API 场景中 5 PASS + 9 BLOCKED + 1 FAIL，`summary-data.json` 却写成 `apiTest=NOT_RUN`，导致平台错误显示为「未执行」。
+**后果**：报告与现实不符，下游 review / submit / package 误判
+**正确做法**：API 维度状态使用 5 个值：`OK / PARTIAL / BLOCKED / NOT_RUN / FAIL`。"部分执行+部分阻塞" 是 `PARTIAL`，附说明：`apiTest=PARTIAL — 15 个场景中 5 个 PASS, 9 个 BLOCKED, 1 个 FAIL`
+
+> 结果状态枚举与证据要求遵循 `../protocols/evidence-based-reporting-protocol.md`。
+
+### 规则 25：AI 启动的服务测试结束不关闭
+**严重度**：❌FAIL
+**场景**：选择 AI 启动服务，测试结束后忘记 Stop-Process，端口被长期占用；下次启动端口占用异常（如 `BindException`）
+**后果**：端口被占、内存浪费、下次启动失败
+**正确做法**：维护 `service.pid` + `serviceState`：
+- `AI_STARTED` → 默认 Stop-Process 并删除 pid 文件
+- `USER_STARTED` → 不动，只提示
+- `REUSED_EXISTING` → 不动，除非用户确认
+
+即使测试失败，也必须进入 finally 清理 AI_STARTED 服务
+
+### 规则 26：凭证在同一流程内重复获取
+**严重度**：🟡WARN
+**场景**：执行器因为浏览器当前 origin 在远程认证服务，就重新走一次认证登录获取凭证，覆盖了刚拿到的有效凭证
+**后果**：浪费一次认证调用（10+ 秒），且暴露低效流程的根本误解（凭证是独立凭证，不依赖浏览器 origin）
+**正确做法**：执行器用 `request.newContext({ baseURL: 本地 })` 或原生 HTTP 客户端直连本地 baseURL；凭证从 `credential-cache.json` 读，本地轻量接口验证；同一次流程内 `credentialRefreshCount > 1` → 🟡 WARN，原因要写入报告
+
+### 规则 27：服务启动盲等 + 无反馈
+**严重度**：🟡WARN
+**场景**：选择 AI 启动后默认每 30 秒检查一次健康，等 90 秒才发现启动失败（如配置缺失导致 `Could not resolve placeholder`）
+**后果**：启动反馈滞后，节奏极慢
+**正确做法**：启动状态机——0–30s 每 2s/30–120s 每 5s 探测；> 10s 必须输出一次状态行；遇到启动失败特征（按技术栈识别，如 Java Spring Boot 的 `BindException` / `Could not resolve placeholder` / `Connection refused during bean init` / `BeanCreationException` / `Failed to start bean` / `BUILD FAILURE`）立即停止等待
+
+### 规则 28：已有服务未先决策就跑业务接口
+**严重度**：❌FAIL
+**场景**：检测到已有应用服务进程（端口被占），未先展示服务决策门，直接调用业务接口
+**后果**：旧服务不含新代码，接口 500 后才发现版本不匹配，浪费时间分析业务数据，掩盖根因（服务版本/配置不匹配）
+**正确做法**：检测到已有服务后，先展示服务决策门（pid/profile/startTime/commandLine/fingerprint/源码是否晚于服务启动时间），询问复用/重启/跳过/停止。询问前只允许 health/meta 检查。只有 service-fingerprint 与当前真实 diffHash/profile/sdkUrl/startCommandHash 完全匹配时才允许自动复用。
+
+### 规则 29：启动命令反复试相对配置叠加 / 中文路径
+**严重度**：🟡WARN
+**场景**：运行时配置叠加用相对路径 `.harness/changes/<change>/runtime/application-harness-execute.yml` 或中文路径作为 JVM `additional-location`，应用（如 Spring Boot）读不到配置叠加，启动失败后反复试不同路径
+**后果**：启动反复失败，浪费时间；中文路径进入 JVM 参数也可能失败
+**正确做法**：默认只用 ASCII 绝对路径 `C:/temp/harness-execute-overlay/<change-name>/application-harness-execute.yml`，并固化已知良好测试配置。禁止把相对路径作为默认 JVM `additional-location`。
+
+### 规则 30：伪 diffHash 导致错误复用
+**严重度**：❌FAIL
+**场景**：ledger 的 diffHash 用描述性文本如 `3files-84plus-5minus`，无法证明代码未变，却据此复用 run 的 unitTest/apiTest 结果
+**后果**：代码已变却复用旧测试结果，掩盖回归问题
+**正确做法**：用 `git diff --binary` 生成 patch 并计算 SHA-256，ledger 只认 `sha256:<hash>` 格式。diffHash 不一致时必须重跑相关测试。
+
+### 规则 31：尝试破解验证码 / 人机验证
+**严重度**：❌FAIL（硬性禁止）
+**场景**：本地服务已起来，但业务接口需要真实登录上下文；认证服务登录接口返回 `验证码不能为空` / 返回滑块拼图（如 AJ-Captcha `blockPuzzle`）/ 图形验证码 / 短信验证码
+**后果**：真实日志里 AI 连续写了 4 版求解算法（边缘求和 → NCC 模板匹配 → 二维边缘匹配 → 一维归一化互相关）、反编译服务端 jar 找容差、共 28 次尝试全部失败，烧掉整段会话，最终仍然 BLOCKED
+**正确做法**：**验证码是安全控制，不是待调试的技术问题。** 一旦识别到验证码/人机验证：
+
+1. **立即停止**，不得编写、下载或运行任何验证码求解代码（图像匹配、OCR、打码平台、反编译校验逻辑找容差都在禁止之列）
+2. 该维度记 `apiTest=BLOCKED`，受影响场景标 🟡 BLOCKED，**不得**伪造 receipt 或把未执行写成通过
+3. 向用户输出原文，并给出三条可选出路：
+   - 用户手工登录后把凭证写入 `.harness/changes/<change-name>/runtime/credential-cache.json`（推荐，执行器本来就先读 cache）
+   - 用户在测试环境临时关闭验证码开关，AI 重跑
+   - 本轮跳过接口验证，按 BLOCKED 归档，留待环境就绪
+4. 顺手提示更新 `.harness/config/harness-test-config.md`——认证方式已变更，配置已过期
+
+> 判据：只要登录响应里出现 `验证码` / `captcha` / `blockPuzzle` / `slider` / `geetest` / `secretKey + originalImageBase64` 任一特征，即触发本规则。
+
+### 规则 32：预存环境缺陷被当成本次变更的阻塞
+**严重度**：🟡WARN
+**场景**：模块全量验证（如 `unitTestFull`）失败，但失败点在本次 diff 之外——例如别人提交的类新增了无默认值的配置占位符，导致某个全上下文测试无法加载
+**后果**：要么误判成自己的回归浪费时间排查，要么擅自改 tracked 配置 / 排除测试把问题掩盖掉，污染 diff
+**正确做法**：
+
+1. **先证明无关**：`git log -S '<符号>' --oneline` 定位引入提交 + `git diff` 证明本次触点不涉及该文件/目录，两条证据都要有
+2. **再上报**：按「预存缺陷」向用户说明——受影响模块、失败文件、引入提交、不阻断依据
+3. **由用户决策**：修根因（会扩大 diff，需明确点头）/ 记 🟡WARN 继续 / 停止本轮
+4. **禁止自作主张**：不得改 tracked 配置文件、不得 `-Dtest=` 排除失败测试、不得偏离 build-profile 的规范命令——这些都会让证据与 ledger 命令不一致
+
+> 用户批准修复后，该修复文件即进入本次 diff：必须在提交前复核它仍在工作区（真实日志里用户中途手工还原了该修复，AI 直到 staging 才发现）。
+
+> diffHash/ledger 复用规则遵循 `../protocols/ledger-protocol.md`；结果证据要求遵循 `../protocols/evidence-based-reporting-protocol.md`。
+
+## BOM-safe JSON / identifier sanitizer / 凭据扫描 (runtime-helpers.mjs)
+
+> 变更簇 5 (spec §3.4)：Node runtime helper 集中处理 PS5.1 BOM、非法测试标识符、凭据边界三类返工。源码 `scripts/runtime-helpers.mjs`，测试 `scripts/tests/runtime-helpers.test.mjs`（`node --test`）。
+
+| 函数 | 用途 | 规避的坑 |
+|------|------|----------|
+| `readJsonUtf8BomSafe(path)` | 读 credential-cache.json / api-test-results.json，容忍 U+FEFF BOM | PS5.1 `Out-File -Encoding utf8` 写入 BOM 导致 `JSON.parse` 失败 |
+| `writeJsonUtf8NoBom(path, value)` | 原子写 (temp+rename)，UTF-8 no BOM，LF，2-space 缩进 | 结果文件被 BOM/换行符污染破坏字节稳定；半写入文件被并发读到 |
+| `sanitizeTestIdentifier({name, pattern, maxLength, prefix})` | change-name → 稳定标识（清洗非法字符 + 超长截断 + 原文名短 hash 防碰撞） | 中文/连字符/超长 change-name 生成非法 identifier 触发服务端 400 |
+| `validateRunnerPayload(payload, {identifierPattern})` | Runner 生成前本地校验 payload schema/必填/identifier/重复 id，返回结构化错误码 | 测试脚本错误（缺字段/非法 id）直到请求服务后才暴露，返工成本高 |
+| `findCredentialValues(text)` | 扫描 profile/Markdown/docs 中的凭据明文值（password/token/secret/Authorization/jdbc password），占位符 `<*_REDACTED>` 与 env 引用 `${ENV}`/`$ENV` 不报 | profile/规则文档误含明文凭据被发布 |
+
+**Runner 生成前强制**（spec §3.4 point 3）：生成 `api-test-runner.mjs` 前用 `validateRunnerPayload` 校验全部场景；`ok=false` → 修复脚本错误，**不得带错请求服务**。场景 id 用 `sanitizeTestIdentifier` 生成（Build Profile v3 `identifier.pattern/maxLength/prefix` 已声明）。
+
+**凭据边界**（spec §3.4 point 4）：credential 配置只含 env key（如 `${TEST_TOKEN}`）、cache path、角色，不含值。发布前用 `findCredentialValues` 扫 profile/规则/Markdown，命中即 ❌FAIL。详见 `../protocols/sensitive-info-protocol.md` §6。

package/harness/bundles/java/codebuddy/{harness-test/reference.md → harness-execute/testing-reference.md}

@@ -1,14 +1,14 @@
 ---
-description: harness-test 的 API 测试执行细节、批量 runner、token 缓存、测试数据治理、报告模板和关门检查。仅在执行接口测试需要参考详细操作时读取。
+description: harness-execute 的 API 测试执行细节、批量 runner、token 缓存、测试数据治理、报告模板和关门检查。仅在执行接口测试需要参考详细操作时读取。
 ---
 
-# harness-test 参考 — API 测试详情
+# harness-execute 参考 — API 测试详情
 
 ## 命令执行模式 preflight（0.0y）
 
 执行 Maven 前必须读取 `.mvn/maven.config`。项目已声明的 `-s`、`-o`、镜像和仓库设置不得被测试命令重复追加或覆盖。离线依赖缺失时，只有在项目规则允许联网的情况下，才可临时执行至多一次非离线 `-nsu` 恢复；失败后停止并报告缺失依赖，不得在多套 Maven 参数间反复试跑。
 
-`/harness-test` 高度依赖 PowerShell 与 Node。在编译/启动服务/生成 runner **之前**
+`/harness-execute` 高度依赖 PowerShell 与 Node。在编译/启动服务/生成 runner **之前**
 必须执行 4 项执行模式检查：
 
 | 检查项 | 命令 | 预期 |
@@ -112,8 +112,8 @@ known-good-test-profile:
 
   overlay:
     pathStrategy: ascii-temp
-    directory: C:/temp/harness-test-overlay
-    fileName: application-harness-test.yml
+    directory: C:/temp/harness-execute-overlay
+    fileName: application-harness-execute.yml
 
   service:
     askBeforeReusingExisting: true
@@ -129,7 +129,7 @@ known-good-test-profile:
 不要直接 Edit `application-local-dev.yml`。默认生成 ASCII 绝对路径 overlay：
 
 ```text
-C:/temp/harness-test-overlay/<change-name>/application-harness-test.yml
+C:/temp/harness-execute-overlay/<change-name>/application-harness-execute.yml
 ```
 
 内容按 `known-good-test-profile` 渲染：
@@ -148,10 +148,10 @@ spring:
 唯一默认启动命令：
 
 ```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-test-overlay/<change-name>/application-harness-test.yml'"
+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'"
 ```
 
-不得默认使用 `.harness/changes/<change>/runtime/application-harness-test.yml` 相对路径作为 JVM `additional-location`。如必须修改 tracked yml，先 blocking user confirmation，最终报告至少 🟡 WARN。
+不得默认使用 `.harness/changes/<change>/runtime/application-harness-execute.yml` 相对路径作为 JVM `additional-location`。如必须修改 tracked yml，先 blocking user confirmation，最终报告至少 🟡 WARN。
 
 ## Service Decision Gate 与服务生命周期管理
 
@@ -179,7 +179,7 @@ serviceState：`AI_STARTED` / `AI_RESTARTED_FROM_USER_SERVICE` / `USER_STARTED`
 
 ### 重入沿用
 
-同一变更的 harness-test 重入时，若环境未变（PG/端口/执行器与上次一致）、上次已确认执行器/服务方案、且源码未改服务启动逻辑（未改 main 启动路径、未改端口/profile 配置、未改 spring-boot:run 启动相关代码），可沿用上次服务决策不重复询问，执行日志记 `重入沿用+环境未变`。不适用情形（service-fingerprint 不匹配、环境已变、USER_STARTED、源码改启动逻辑）仍须询问/重启。详见 checklist.md「0.5x 重入沿用」。
+同一变更的 harness-execute 重入时，若环境未变（PG/端口/执行器与上次一致）、上次已确认执行器/服务方案、且源码未改服务启动逻辑（未改 main 启动路径、未改端口/profile 配置、未改 spring-boot:run 启动相关代码），可沿用上次服务决策不重复询问，执行日志记 `重入沿用+环境未变`。不适用情形（service-fingerprint 不匹配、环境已变、USER_STARTED、源码改启动逻辑）仍须询问/重启。详见 testing-checklist.md「0.5x 重入沿用」。
 
 若用户选择重启已有服务，必须提示：测试结束后关闭新测试服务，不会恢复原服务。
 
@@ -613,7 +613,7 @@ JAVATEST_<change-name>_<timestamp>_<short-random>
 - tokenRefreshCount: 0 / 1（>1 → 🟡 WARN）
 
 ### 单元测试
-> ✅ 复用 harness-run 单元测试结果：Tests run: N, Failures: 0, Errors: 0
+> ✅ 复用 harness-execute 单元测试结果：Tests run: N, Failures: 0, Errors: 0
 > （diffHash=<...>, module=<...>, profile=<...>, scope=<...>）
 > 或：🔄 已重跑（原因：diffHash 变化 / 行为性 post-test 修改 / run 未跑全量）
 
@@ -686,7 +686,7 @@ JAVATEST_<change-name>_<timestamp>_<short-random>
 ### 下一步
 - 如果 ✅OK：进入 /harness-review
 - 如果 🟡WARN：根据 WARN 原因决定是否补充测试或进入 review
-- 如果 ❌FAIL：修复失败项后重新运行 /harness-test
+- 如果 ❌FAIL：修复失败项后重新运行 /harness-execute
 ```
 
 ## 结果分级规则
@@ -768,7 +768,7 @@ JAVATEST_<change-name>_<timestamp>_<short-random>
 
 ## 真实 diffHash 生成
 
-后续复用 ledger 前必须生成真实 SHA-256 diffHash，且**必须是 commit-invariant 三部分合并**（与 harness-run 步骤 2c、ledger-protocol 五逐字一致），保证 run→test 跨 checkpoint commit 复用链不断：
+后续复用 ledger 前必须生成真实 SHA-256 diffHash，且**必须是 commit-invariant 三部分合并**（与 harness-execute 步骤 2c、ledger-protocol 五逐字一致），保证 run→test 跨 checkpoint commit 复用链不断：
 
 ```powershell
 powershell.exe -NoProfile -Command "$base = '<baseCommit>'; $patch = '.harness/changes/<change>/runtime/current-diff.patch'; & { git diff $base HEAD --binary; git diff --binary; git ls-files --others --exclude-standard | ForEach-Object { Get-Content -Raw -LiteralPath $_ } } | Out-File -Encoding utf8 $patch; (Get-FileHash $patch -Algorithm SHA256).Hash"
@@ -789,4 +789,4 @@ powershell.exe -NoProfile -Command "$base = '<baseCommit>'; $patch = '.harness/c
 
 ## 执行日志记录
 
-`/harness-test` 只向 `events.ndjson` 追加事件（schema_version 3，兼容读取 v1/v2）；`logs/execution-log.md` 由 `harness_events.py append` 自动渲染。Phase 0 之前 append `phase.start`；写入 `command` / `verification` / `decision` / `issue` / `artifact`，摘要放 `note`。详见 [[../../protocols/report-pipeline-protocol.md|report-pipeline-protocol]] 与 core `harness-test/SKILL.md`。
+`/harness-execute` 只向 `events.ndjson` 追加事件（schema_version 3，兼容读取 v1/v2）；`logs/execution-log.md` 由 `harness_events.py append` 自动渲染。Phase 0 之前 append `phase.start`；写入 `command` / `verification` / `decision` / `issue` / `artifact`，摘要放 `note`。详见 [[../../protocols/report-pipeline-protocol.md|report-pipeline-protocol]] 与 core `harness-execute/SKILL.md`。

package/harness/bundles/java/codebuddy/harness-knowledge-ingest/SKILL.md

@@ -2,7 +2,7 @@
 name: harness-knowledge-ingest
 description: 确认归档 ZIP 已上传并由 Hunter Platform 在服务端解包、校验和入库。客户端不再构建或维护本地知识索引。
 ---
-<!-- generated by harness_deploy.py; core=29eda366c8fc661a; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=8334c3150a633202; overlay=java; agent=codebuddy; do not edit -->
 # harness-knowledge-ingest
 
 知识 ingest 完全由 Hunter Platform 负责。归档完成时，客户端生成一个确定性 ZIP；

package/harness/bundles/java/codebuddy/harness-knowledge-query/SKILL.md

@@ -2,7 +2,7 @@
 name: harness-knowledge-query
 description: 在规划、实现或排查前，通过 hunter-harness CLI 查询远端项目知识库。远端不可用时直接报告不可用，不建立本地索引或离线回退。
 ---
-<!-- generated by harness_deploy.py; core=29eda366c8fc661a; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=8334c3150a633202; overlay=java; agent=codebuddy; do not edit -->
 # harness-knowledge-query
 
 项目知识以 Hunter Platform 的服务端索引为唯一真源。客户端只提交查询并消费结果：

package/harness/bundles/java/codebuddy/harness-package/SKILL.md

@@ -2,7 +2,7 @@
 name: harness-package
 description: 增量模块打包：拉取最新→编译验证→mvn package→汇总 jar/war。仅当用户显式调用 /harness-package 时使用，不得自动触发。
 ---
-<!-- generated by harness_deploy.py; core=29eda366c8fc661a; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=8334c3150a633202; overlay=java; agent=codebuddy; do not edit -->
 # harness-package — 增量模块打包（Java overlay）
 
 ## Purpose

package/harness/bundles/java/codebuddy/harness-package/checklist.md

@@ -10,9 +10,9 @@ description: harness-package 的8步工作流详细步骤、模块识别方法
 
 如果 `$ARGUMENTS` 非空且与检测到的变更名不一致，以 `$ARGUMENTS` 为准。
 
-**读取 worktree 状态并切换**：读 `.harness/changes/<change-name>/meta/worktree.json`（旧路径 `worktree.json` 兼容）。`requested=true` 且 `.worktrees/<change-name>/` 已创建 → cd 到该 worktree 目录；`requested=true` 但 worktree 不存在 → 停止，提示先修复 `harness-run`，不得静默回主目录；`requested=false` → 在主目录执行。切换后检查构建配置文件（`.mvn/maven.config`、`settings-*.xml` 等）是否完整，缺失时从主目录复制。
+**读取 worktree 状态并切换**：读 `.harness/changes/<change-name>/meta/worktree.json`（旧路径 `worktree.json` 兼容）。`requested=true` 且 `.worktrees/<change-name>/` 已创建 → cd 到该 worktree 目录；`requested=true` 但 worktree 不存在 → 停止，提示先修复 `harness-execute`，不得静默回主目录；`requested=false` → 在主目录执行。切换后检查构建配置文件（`.mvn/maven.config`、`settings-*.xml` 等）是否完整，缺失时从主目录复制。
 
-**强制前置检查 — harness-test（硬门禁）和 harness-review（参考性）**：
+**强制前置检查 — harness-execute（硬门禁）和 harness-review（参考性）**：
 
 通过 Glob 检查：
 - `.harness/changes/<change-name>/reports/test/test-report-*.md` 是否存在（旧路径 `tests/` 兼容）
@@ -21,19 +21,19 @@ description: harness-package 的8步工作流详细步骤、模块识别方法
 如果缺失 test 报告，使用 `blocking user confirmation` 询问用户：
 
 ```
-检测到 harness-test 尚未运行（缺少测试报告）：
+检测到 harness-execute 尚未运行（缺少测试报告）：
 - 测试报告: <存在/缺失>
 - 审查报告: <存在/缺失>（参考性，不阻塞）
 
 打包前建议先运行测试。请选择：
-1. 先运行 harness-test — 退出 package 流程，运行 harness-test 后再 package（推荐）
+1. 先运行 harness-execute — 退出 package 流程，运行 harness-execute 后再 package（推荐）
 2. 跳过测试继续打包 — 风险自担，报告中明确标记
 3. 取消 package
 ```
 
 **默认不跳过 test**。用户确认跳过时，必须在执行日志和 package-report 中明确写明：
-- 执行日志：`- **跳过**: 用户确认跳过 harness-test`
-- package-report：`> ⚠️ 用户确认跳过 harness-test，打包结果未经测试验证`
+- 执行日志：`- **跳过**: 用户确认跳过 harness-execute`
+- package-report：`> ⚠️ 用户确认跳过 harness-execute，打包结果未经测试验证`
 
 **review 报告**：如果存在，记录路径和摘要供参考；如果不存在，不阻塞 package。review 结果不作为硬门禁。
 
@@ -46,7 +46,7 @@ description: harness-package 的8步工作流详细步骤、模块识别方法
    - `diffHash` 与当前提交一致
    - submit 后无新提交（`git log <baseCommit>..HEAD` 为空）
    - 无行为性 post-test 修改（`postTestClassification` ∈ {无, NON_BEHAVIORAL_CLEANUP, COMMENT_ONLY, TEST_ONLY}）
-4. ledger 有效 → 默认 `mvn package -DskipTests` 复用测试；ledger 无效 → 带测试打包或要求先跑 `/harness-test`
+4. ledger 有效 → 默认 `mvn package -DskipTests` 复用测试；ledger 无效 → 带测试打包或要求先跑 `/harness-execute`
 
 **append `phase.start`**（含 worktree/baseCommit/ledger 摘要于 `note`）：
 

package/harness/bundles/java/codebuddy/harness-plan/SKILL.md

@@ -3,7 +3,7 @@ name: harness-plan
 description: 将需求转化为设计文档+实施计划+完整测试场景表，必须在编码前完成。仅当用户显式调用 /harness-plan 或明确要求进入
   Harness 规划阶段时使用；不得因用户描述需求就自动触发。
 ---
-<!-- generated by harness_deploy.py; core=29eda366c8fc661a; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=8334c3150a633202; overlay=java; agent=codebuddy; do not edit -->
 # harness-plan — 需求规划
 
 ## Purpose
@@ -105,7 +105,7 @@ change-name 范围变更 → 提示重命名或记 🟡WARN（→ `reference.md`
 | 空目录 | 不得为“预留目录”生成 `.gitkeep`；只有产品明确需要跟踪空目录时才能创建，并在计划中说明业务原因 |
 | 设计审批包 | 一次 blocking user confirmation 含 worktree（读 `harness.json` `defaultWorktree`）。必须同时展示 **in_scope 与 out_of_scope 两个列表**——只展示"做什么"会让范围误判活到发布之后，代价是整份计划 republish |
 | 引用即追问 | 需求引用了外部设计文档章节（贴段落、指 `### Bn`、说"之前设计的时候如…"）时，阶段 2 必须确认该章节是否纳入本次范围，落到 in_scope 或 out_of_scope；引用 ≠ 纳入，也 ≠ 排除 |
-| 阶段 8 | 唯一入口：`hunter-harness plan finalize`（证据包 → 八 target + journal committed + plan-events.ndjson）。失败不得手工补终态；历史 legacy 收据只读（`harness_plan_finalize.py verify`） |
+| 阶段 8 | 唯一入口：`hunter-harness plan finalize`（证据包 → 八 target + journal committed + plan-events.ndjson）。assurance/高风险计划先跑 `plan review-record` 把对抗评审收据写回证据包（`PLAN_REVIEW_REQUIRED` 报错里的 `expected_review.input_hash` 是公开契约），不得手拼哈希。失败不得手工补终态；历史 legacy 收据只读（`harness_plan_finalize.py verify`） |
 | 发布路径 | **只有 v2**（`plan evidence-pack` → `plan finalize`）；legacy staging/finalize/republish 已于 0.3.0 移除，历史 legacy 收据保持可读（`harness_plan_finalize.py verify`）。v2 的场景契约已补齐 `priority`/`owner_phase` 与可执行测试三元，派生的 `meta/scenario-manifest.json` 能被 execute 门禁与 `harness_ledger.py record` 解包消费，证据闭环走得通。P0/P1 场景必须给全可执行三元（要么整组给全、要么整组省略；省略则 manifest 降为 schemaVersion 1，关门绑不上结构化执行收据） |
 | 发布后改产物 | 改 `meta/plan-evidence-input.json` 后重跑 `plan evidence-pack`（`context.attempt` 递增、`expected_baseline` 置 present 并带上次 manifest 哈希/generation），再 `plan finalize`——新 attempt + 重新派生 manifest 一次完成。**绝不手改 `meta/scenario-manifest.json`**（派生物，手改必致 `ARTIFACT_HASH_DRIFT`）→ `reference.md`「发布后修订计划」 |
 | v2 输入骨架 | 不要猜 `plan-evidence-input.json` 结构：`npx hunter-harness plan evidence-pack --print-template` 给出**一个字不改就能通过 evidence-pack** 的骨架（结构合法；`change_key`/`run_id` 仍须换成真实身份才能 finalize），逐项替换即可。结构不符时命令返回 `PLAN_EVIDENCE_INPUT_INVALID`，带 `field_path` 与 `problems[]`（缺失/多余键、枚举取值）——按 problems 改完重跑；**不得**为找契约去反编译 `dist/bin.js` 或翻 npx 缓存。带不了 `<>` 的占位字段与硬约束清单 → `reference.md` 阶段 8 v2 路径 |

package/harness/bundles/java/codebuddy/harness-plan/checklist.md

@@ -227,7 +227,7 @@ description: harness-plan 的阶段检查清单和覆盖检查列表。仅在执
 - 如果需求不明确，优先提问而不是猜测后继续设计
 - 任务拆分粒度按复杂度调整——plan 简表保持可追踪，implementation-detail 按风险和复杂度自适应展开
 
-> Plan 的结束行为（禁止询问执行模式、只提示 `/harness-run`）由 `SKILL.md` 的关键规则表定义，
+> Plan 的结束行为（禁止询问执行模式、只提示 `/harness-execute`）由 `SKILL.md` 的关键规则表定义，
 > 详细规则见 `reference.md`「Plan 结束行为规则」。此处不再复述。
 
 ## 事件记录（前置规则）

package/harness/bundles/java/codebuddy/harness-plan/reference.md

@@ -360,10 +360,34 @@ status: approved
 # 1) 规划自然产出 → 证据包（结构化身份/哈希全由冻结模块推导）
 npx hunter-harness plan evidence-pack --input .harness/changes/<cn>/meta/plan-evidence-input.json \
   --output .harness/changes/<cn>/meta/plan-evidence.json
-# 2) 证据包 → 质量门 + 原子发布 + 事件 outbox
+# 2) assurance / 高风险计划：记录对抗评审收据（0.4.8+；非 assurance 可跳过）
+npx hunter-harness plan review-record --input .harness/changes/<cn>/meta/plan-evidence.json \
+  --receipt .harness/changes/<cn>/meta/plan-review-draft.json
+# 3) 证据包 → 质量门 + 原子发布 + 事件 outbox
 npx hunter-harness plan finalize --input .harness/changes/<cn>/meta/plan-evidence.json
 ```
 
+**对抗评审收据（assurance 必做，0.4.8 起有正式链路）**：profile.mode 被推到 `assurance`
+（auth/concurrency/migration 等风险信号自动推断）或任一场景 `risk_level: "high"` 时，
+finalize 硬性要求证据包顶层 `adversarial_review` 收据，缺失即 `PLAN_REVIEW_REQUIRED` fail closed。
+收据的 `input_hash` 绑定产物 + 语义投影 + capabilities + 高风险发现 + 透镜（全在 CLI 内部管线，
+外部不可预计算），所以**不要手拼收据**：
+
+1. 先完成阶段 7.5 对抗评审，把结论写成草稿 `meta/plan-review-draft.json`：
+   `{ "reviewer_identity": "inline:<标识>", "findings": [] }`
+   （`review_mode` 缺省 `inline`；`completed_at` 缺省取当前时间；`findings` 为空数组表示无发现）
+2. 跑 `plan review-record`：CLI 内部重跑 layer1/layer2/layer3 算出权威 `input_hash`，
+   代算 `findings_hash`，把完整收据写回证据包顶层 `adversarial_review`（缺省覆盖 `--input`，
+   可用 `--output` 写到别处）。stdout 的 `review_required: false` 表示该包未触发评审、收据不会被消费。
+3. 再跑 `plan finalize`。
+
+两条公开契约（不再需要从 dist 里翻）：
+
+- `PLAN_REVIEW_REQUIRED` 报错的 `expected_review.input_hash` 就是绑定期望值——校验器自曝期望，
+  手工构造收据时用它；`findings_hash` 是你端 `findings` 数组 canonical JSON 的 sha256。
+- 收据绑定**证据包内容**：`review-record` 写回后任何对 pack 的修改（包括重跑 evidence-pack）
+  都使收据失效，必须重跑 `review-record`。墙钟时间不进 `input_hash`，不必担心时间戳漂移。
+
 **自然输入文件**（`meta/plan-evidence-input.json`，权威定义 `packages/cli/src/commands/plan-evidence-pack.ts` 的 `EvidencePackInputFile`）由规划阶段逐步沉淀，各字段定稿时点不得倒置。
 
 > 📋 **先取骨架，别猜结构**：CLI 自带模板输出，不需要去找 TS 接口或翻 npx 缓存——
@@ -388,10 +412,13 @@ npx hunter-harness plan finalize --input .harness/changes/<cn>/meta/plan-evidenc
 - `structured_input.scenarios` **至少 3 条**——八维度缺项由命令补 `not_applicable`，但场景总数不能少于 3
 - `intent.acceptance_examples` 2~5 条，`approval.content.acceptance_examples` 3~7 条 → 取 3 条同时满足
 - `key_alternatives` / `invariants` / `failure_behaviors` / `compatibility_boundaries` 各至少 1 条
-- `intent.in_scope`/`out_of_scope` 与 `approval.content` 同名字段必须**集合相等**
+- `intent.in_scope`/`out_of_scope` 与 `approval.content` 同名字段必须**集合相等**；0.4.8 起 approval 侧可以**整项省略**（从 intent 继承，成功输出的 `warnings` 会标 `approval_scope_inherited`），写了就必须相等
+- `intent.uncertainties` 非空时，每一项都会生成未决决策 `intent_uncertainty:<sha256(文本)>`，必须在 `decision_nodes` 提供**同 id** 的节点（通常是一条 `product_decision`，`status: "resolved"` + `resolution`/`resolved_by: "user"`/`resolved_at` 三元）；不想走决策图就留空数组。缺节点时边界报错会直接列出期望的决策 id
+- `tasks[].affected_paths` 必须是**文件形态**的相对路径：正斜杠分隔、不能以 `/` 结尾、不含 `.`/`..` 段、不接受盘符/绝对路径。目录路径会被拒——改为列出其中的具体文件
 - tasks 只写 `task_id/objective/affected_paths/owner_phase`，六个 refs 数组由命令接线；多写 `cluster`/`title` 这类键会因精确键集被拒
 - scenarios 只写 `scenario_id/title/acceptance/coverage_dimension/execution_level/evidence_requirements/risk_level`（+可选 `verification_command`）；`priority`/`test_file` 这类计划表列不属于本输入
 - `machine.worktree_policy` ∈ `project_default | required | forbidden`（没有 `none`）
+- `decision_nodes[]` 的 `type` ∈ `fact | engineering_default | product_decision | risk_decision`，`status` ∈ `pending | resolved | blocked | superseded`；`status: "resolved"` 必须带 `resolution`/`resolved_by`/`resolved_at` 三元，且 `resolved_by` 与类型推导的解决者一致（fact→evidence、engineering_default→engineering_default、产品/风险决策→user）
 
 > **结构错了怎么读报错**：命令在边界返回 `code:"PLAN_EVIDENCE_INPUT_INVALID"`（`stage:"boundary"`），
 > `field_path` 指向第一处问题，`problems[]` 逐条给 `missing_keys`/`unexpected_keys`/`message`。
@@ -428,7 +455,7 @@ npx hunter-harness plan finalize --input .harness/changes/<cn>/meta/plan-evidenc
 > 可执行三元是**可选**的，但要么整组给全、要么整组省略。ledger 场景全部带齐 → manifest 声明
 > `schemaVersion 2`，关门可绑结构化执行收据；否则降为 1。
 
-- **证据包**（`plan-evidence.json`）是命令推导的产物（trusted/publication/context/baseline），不得手改；任何字段变化必须改自然输入后重跑 evidence-pack。
+- **证据包**（`plan-evidence.json`）是命令推导的产物（trusted/publication/context/baseline），不得手改；任何字段变化必须改自然输入后重跑 evidence-pack。唯一的例外是 `adversarial_review` 顶层字段——它由 `plan review-record`（或手工构造的合规收据）写入，evidence-pack 构建时也会透传自然输入里已有的该字段。
 - **成功语义**：finalize exit 0 且 `code:"PLAN_FINALIZED"`。落盘事实 = 八 target（plans/*.md ×4 + meta/*.json ×4）+ `meta/publication-journals/<op>.json`（状态 committed）+ `meta/plan-events.ndjson`（artifact_published/phase_ended）。确定性门失败 exit 1 且 `code:"PLAN_FINALIZE_DETERMINISTIC_FAILED"` 附 findings——此时必须回到对应阶段修正规划内容，**不得**手改证据包或 staged 内容绕过。
 - **验证**：journal `state==="committed"` + 八 target 存在 + plan-events.ndjson 含两类终态事件；不得手工补写任何一项。
 - **legacy 收据**：v2 路径不写 `plan-finalization.json`；消费方若读历史 legacy receipt，`harness_plan_finalize.py verify` 保持可读。0.3.0 起 v2 无 legacy 回退——自然输入不完整先补齐（例如补真实审批记录），不得走已删除的 Python finalizer。

package/harness/bundles/java/codebuddy/harness-pull/SKILL.md

@@ -3,7 +3,7 @@ name: harness-pull
 description: 从 Hunter Platform 下拉配置/规则/架构/指令（及显式来源分支的分支文件恢复）。仅当用户显式调用
   /harness-pull 或明确说'从平台拉取/恢复'时使用；不得自动触发。
 ---
-<!-- generated by harness_deploy.py; core=29eda366c8fc661a; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=8334c3150a633202; overlay=java; agent=codebuddy; do not edit -->
 # harness-pull — 从 Hunter Platform 下拉与恢复
 
 ## Purpose

package/harness/bundles/java/codebuddy/harness-push/SKILL.md

@@ -3,7 +3,7 @@ name: harness-push
 description: 上传本地配置/规则/架构/指令（及显式归档）到 Hunter Platform。仅当用户显式调用 /harness-push
   或明确说'上传到平台'时使用；不得因存在本地修改就自动触发。
 ---
-<!-- generated by harness_deploy.py; core=29eda366c8fc661a; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=8334c3150a633202; overlay=java; agent=codebuddy; do not edit -->
 # harness-push — 上传到 Hunter Platform
 
 ## Purpose