@hunter-harness/workflow-harness 0.2.1 → 0.2.2

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

@@ -3,7 +3,7 @@ name: harness-knowledge-query
 description: 根据新需求、设计任务、代码修改请求或问题排查，在规划和编码前查询 .harness/knowledge
   历史上下文。适用场景：query knowledge、查找历史需求、根据归档理解需求、继续之前类似开发、生成需求上下文包。
 ---
-<!-- generated by harness_deploy.py; core=7b81effe1faaef85; overlay=java; agent=cursor; do not edit -->
+<!-- generated by harness_deploy.py; core=d437039c3207693b; overlay=java; agent=cursor; do not edit -->
 # harness-knowledge-query
 
 根据用户的新需求或排查问题，从项目本地 `.harness/knowledge` 中检索历史需求、决策、实现、风险和测试证据，并生成 AI 可读的 context pack。

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

@@ -2,7 +2,7 @@
 name: harness-package
 description: 增量模块打包：拉取最新→编译验证→mvn package→汇总 jar/war。使用场景：打包、package、发版准备
 ---
-<!-- generated by harness_deploy.py; core=7b81effe1faaef85; overlay=java; agent=cursor; do not edit -->
+<!-- generated by harness_deploy.py; core=d437039c3207693b; overlay=java; agent=cursor; do not edit -->
 # harness-package — 增量模块打包（Java overlay）
 
 ## Purpose
@@ -36,9 +36,9 @@ description: 增量模块打包：拉取最新→编译验证→mvn package→
 
 ## Workflow
 
-1. 读 ledger + build-profile 的 `buildCommands.package`
+1. 读 ledger + build-profile 的 `commands.package`（v2，按 profile key resolve）
 2. 识别变更模块（git diff + pom 结构）
-3. `mvn package -DskipTests`（ledger 不可复用时先跑必要测试）
+3. **单次** Maven package lifecycle（spec §3.3 去重，不预先 compile/test）：full test 可复用（`can-reuse unitTestFull=true`）→ 按 `commands.package` resolve 执行一次 skip-tests package；不可复用 → 按 `commands.package` resolve 执行一次含测试 package
 4. 写打包报告 + append 事件
 
 ## P0 执行可信度规则

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

@@ -2,7 +2,7 @@
 name: harness-plan
 description: 将需求转化为设计文档+实施计划+完整测试场景表，必须在编码前完成。使用场景：需求分析、feature plan、技术方案设计、实现方案规划
 ---
-<!-- generated by harness_deploy.py; core=7b81effe1faaef85; overlay=java; agent=cursor; do not edit -->
+<!-- generated by harness_deploy.py; core=d437039c3207693b; overlay=java; agent=cursor; do not edit -->
 # harness-plan — 需求规划
 
 ## Purpose
@@ -81,6 +81,7 @@ change-name 范围变更 → 提示重命名或记 🟡WARN（→ `reference.md`
 | 阶段 8 | spec/plan/detail/scenarios/worktree.json/logs/events 缺一不可 → ❌FAIL |
 | Plan 结束 | **禁止**询问执行模式；只提示 `/harness-run` |
 | 知识查询 | 0.5 失败不得假装已读历史 |
+| state snapshot | 读取 `state-snapshot.json`（`harness_state.py` / state-layout-protocol §state-snapshot.json）了解 project/worktree root、HEAD/base、profile/rules/map/knowledge 指纹；失效由脚本刷新，**不得仅凭缓存跳过代码探索或验证门禁**（design §3.6） |
 | 协议 | sensitive-info / evidence-based-reporting / state-layout |
 
 产出物表、frontmatter、legacy 兼容、结束输出模板 → `reference.md`

package/harness/bundles/java/cursor/harness-review/SKILL.md

@@ -3,7 +3,7 @@ name: harness-review
 description: 6维度代码审查（架构/安全/规范/兼容/测试/性能），对照项目规则（见
   .harness/context-index.json）和测试场景表，在隔离上下文运行。使用场景：代码审查、提交前检查、合并评审
 ---
-<!-- generated by harness_deploy.py; core=7b81effe1faaef85; overlay=java; agent=cursor; do not edit -->
+<!-- generated by harness_deploy.py; core=d437039c3207693b; overlay=java; agent=cursor; do not edit -->
 # harness-review — 代码审查
 
 ## Purpose
@@ -120,6 +120,10 @@ review 结果默认只作参考，不阻塞 submit/archive；报告措辞遵循
 
 git diff/log 命令通过 `powershell.exe -Command "..."` 执行；review-report 中如发现明文 token/密码/密钥，必须列入 RED 问题并在报告中以 `<TOKEN_REDACTED>` 等占位符引用；RED/YELLOW/OK 结论必须基于实际 diff 内容，不得凭印象判断。代码探索必须优先使用 CodeGraph MCP 工具（`mcp__codegraph__codegraph_explore`），不允许通过普通 Bash 调 codegraph 命令（已列入 `disallowed-tools`）；MCP 不可用时降级为 Grep/Glob + Read，并在执行日志记录降级原因。遵循 `../protocols/powershell-protocol.md` / `sensitive-info-protocol.md` / `evidence-based-reporting-protocol.md`。
 
+### 五、state snapshot 与源码重验
+
+review 读取 `state-snapshot.json`（`harness_state.py` / state-layout-protocol §state-snapshot.json）的 code/diff 段确定审查范围；snapshot 失效或代码段变化时**必须重新读取实际变更源码**，不得仅凭缓存快照跳过源码审查（design §3.6）。
+
 ## 交互白名单
 
 **无** AskUserQuestion（审查全自动）。委派失败 → 主会话审查 + `decision` 事件。

package/harness/bundles/java/cursor/harness-run/SKILL.md

@@ -2,7 +2,7 @@
 name: harness-run
 description: 按变更簇执行 TDD 编码循环（RED→GREEN→REFACTOR→编译验证），逐变更簇实现计划中的任务。使用场景：开始编码、实现功能、写代码、TDD 编码
 ---
-<!-- generated by harness_deploy.py; core=7b81effe1faaef85; overlay=java; agent=cursor; do not edit -->
+<!-- generated by harness_deploy.py; core=d437039c3207693b; overlay=java; agent=cursor; do not edit -->
 # harness-run — 需求编码
 
 ## Purpose
@@ -64,9 +64,9 @@ description: 按变更簇执行 TDD 编码循环（RED→GREEN→REFACTOR→编
 
 ### Java 构建验证（Maven）
 
-- 所有 `mvn`/`git` 经 `powershell.exe -NoProfile -Command`；命令读 `.harness/config/build-profile.json` 的 `buildCommands`（**禁止 hardcode 模块名/端口**）
-- 增量编译：`buildCommands.compile`（典型 `mvn compile -pl <module> -o -q`）
-- 变更簇 TDD：多测试类合并一次 `mvn test -pl <module> -Dtest=A,B,C -o`；每簇最多一次 RED + 一次 GREEN Maven
+- 所有 `mvn`/`git` 经 `powershell.exe -NoProfile -Command`；命令读 `.harness/config/build-profile.json` 的 `commands`（v2，按 profile key resolve；**禁止 hardcode 模块名/端口**）
+- 增量编译：`commands.compile`（典型 `mvn compile -pl <module> -o -q`）
+- 变更簇 TDD：多测试类合并一次按 `commands.unitTest` resolve（典型 `mvn test -pl <module> -Dtest=A,B,C -o`）；每簇最多一次 RED + 一次 GREEN Maven
 - **轻量 run**：默认只 compile；全量 `mvn test` 仅当改了 mapper/sql/权限/controller/公共模块或用户要求 full-run-validation
 - **install -am**：仅 worktree 首建或上游模块文件变化时（见 ledger-protocol）；非每次 run 强制
 - worktree 中确认 `.mvn/maven.config` 等构建配置存在；缺失时从主目录复制

package/harness/bundles/java/cursor/harness-run/checklist.md

@@ -45,7 +45,7 @@
 - [ ] 探测 1：`src/test/java` 目录是否存在
 - [ ] 探测 2：`pom.xml` 是否包含 `spring-boot-starter-test` / `junit` / `mockito` 依赖
 - [ ] 探测 3：是否存在已有测试文件（`*Test.java` 或 `*Tests.java`）
-- [ ] 探测 4：目标模块测试命令是否可运行（`mvn test -pl <module> -o -q` 试运行）
+- [ ] 探测 4：目标模块测试基础设施是否可用（`mvn test-compile -pl <module> -o -q` 验证测试可编译，或测试枚举/秒级 smoke；**禁止完整模块测试**，spec §3.3）
 - [ ] 四项证据收集完毕 → 写结论：✅ 测试基础设施可用 / 🟡 测试基础设施部分可用 / ❌ 测试基础设施不可用
 - [ ] 如果 ❌ 不可用 → 记录 TDD 降级原因（必须引用具体证据，如"模块 X 无 src/test/java 目录"）
 

package/harness/bundles/java/cursor/harness-submit/SKILL.md

@@ -3,7 +3,7 @@ name: harness-submit
 description: 最终提交封装：验证→中文 commit→提交/推送；worktree 模式含 --no-ff
   合并回主分支。使用场景：提交代码、commit、push、合并分支、merge to main、完成开发
 ---
-<!-- generated by harness_deploy.py; core=7b81effe1faaef85; overlay=java; agent=cursor; do not edit -->
+<!-- generated by harness_deploy.py; core=d437039c3207693b; overlay=java; agent=cursor; do not edit -->
 # harness-submit — 最终提交（含 worktree 合并）
 
 ## Purpose
@@ -55,7 +55,7 @@ description: 最终提交封装：验证→中文 commit→提交/推送；workt
 
 0. **启动准备** — 确定变更名；读 ledger + 计算 diffHash + post-test 7 类分类；append `phase.start`
 1. **合并最新代码** — 主目录：`stash` → `pull --rebase` → `stash pop`；**worktree：N/A**（远端同步在合并段主分支完成）
-2. **最终验证** — ledger 复用优先；**提交前最终门禁**：`harness_ledger.py can-reuse --verification unitTestFull --scope module --project . --profile-input unitTestFull --command <build-profile.json buildCommands.unitTestFull>`（`--profile-input unitTestFull` 从 `build-profile.json` 的 `verificationInputs.unitTestFull` 展开依赖闭包文件集，**禁止用仅含 staged 文件的 `--files` 快捷方式**冒充全量闭包；`<command>` 直接读 `buildCommands.unitTestFull`，不复制示例模块名）。不可复用则执行 `buildCommands.unitTestFull` 模块级全量单元测试，成功后用同一文件集、command、`scope=module` 写回 ledger 的 `unitTestFull` 项。增量 `unitTest` 永远不能冒充 `unitTestFull` 门禁。
+2. **最终验证** — ledger 复用优先；**提交前最终门禁只调 `can-reuse`**（删除与 coverage 冲突的二次全量门禁）：`harness_ledger.py can-reuse --verification unitTestFull --scope module --project . --profile-input unitTestFull --command <resolved commands.unitTestFull.command>`。`--command` **按 profile key resolve**：读 `build-profile.json` 的 `commands.unitTestFull.command`（v2），或 `harness_profile.py resolve --project . --key unitTestFull --json` 取 resolved command，**不复制示例模块名**（文档示例只展示 key）。`--profile-input unitTestFull` 从 `verificationInputs.unitTestFull`（v2 由 `commands.unitTestFull.inputs` 派生）展开依赖闭包，**禁止用仅含 staged 文件的 `--files` 快捷方式**冒充全量闭包。`reuse=true` → 不再执行二次全量测试；仅 `reuse=false` 时执行**同一 resolved verification**（profile `unitTestFull` 命令），成功后用同一文件集、command、`scope=module` 写回 ledger `unitTestFull` 项。增量 `unitTest` 永远不能冒充 `unitTestFull` 门禁。
 3. **.gitignore + 暂存** ⚠️ — 检查 `.harness/` 在 `.gitignore`；**禁止 `git add -A`**
 4. **提交方式** — 主目录：AskUserQuestion 三选项（commit+push / 仅本地 / 取消）；**worktree：固定仅本地 commit**
 5. **commit-message.txt** ⚠️ — 展示 staged、diff stat、完整中文 message；用户确认
@@ -80,7 +80,7 @@ M8. **ledger + 收尾** — 写入 `mergeFinalHash`；append `phase.end`；提
 
 通用 `harness-submit` 的最终门禁已统一为 `unitTestFull`（见通用 SKILL.md 步骤 2 / checklist 步骤 2）。Java overlay **不重复定义门禁规则**，只补两点：
 
-- **Maven 命令来源**：`--command` 取 `build-profile.json` 的 `buildCommands.unitTestFull`，典型 `mvn test -pl <module> -o`。`mvn test` 不带 `-Dtest=` 即模块级全量 → 记 `scope=module` 可复用；带 `-Dtest=<类>` 是增量 `unitTest`，**不能**冒充 `unitTestFull`。
+- **Maven 命令来源**：`--command` 按 profile key resolve 取 `build-profile.json` 的 `commands.unitTestFull.command`（或 `harness_profile.py resolve --key unitTestFull`），典型 `mvn test -pl <module> -o`。`mvn test` 不带 `-Dtest=` 即模块级全量 → 记 `scope=module` 可复用；带 `-Dtest=<类>` 是增量 `unitTest`，**不能**冒充 `unitTestFull`。
 - **Java 依赖闭包**：`verificationInputs.unitTestFull` 必须覆盖完整编译+测试依赖闭包，建议 `["pom.xml", "<module>/pom.xml", "<module>/src/main/**", "<module>/src/test/**"]`，避免只哈希 staged 文件而漏掉 pom 依赖变化导致误复用。`harness_preflight.py detect` 对单模块项目写入根级默认 `["pom.xml", "src/main/**", "src/test/**"]`，多模块项目需手工改为 module 专属 glob。
 - **可选 package 前置**：若团队发版前需 jar 验证，在 submit 后接 `/harness-package`（默认时序 submit → package → archive）
 ## P0 执行可信度规则

package/harness/bundles/java/cursor/harness-submit/checklist.md

@@ -89,21 +89,21 @@ powershell.exe -NoProfile -Command "<项目测试命令>"
 
 **重跑后必须把结果写回 ledger** 的 `compile`/`unitTest` 项，并更新 `diffHash`/`currentHead`。
 
-**提交前最终门禁**（步骤 2 末尾，commit 前强制，`unitTestFull` 模块级全量）：
+**提交前最终门禁**（步骤 2 末尾，commit 前强制，`unitTestFull` 模块级全量）——**只调 `can-reuse`，删除二次全量门禁**：
 
 ```powershell
 python <skills-root>/scripts/harness_ledger.py can-reuse `
   --change-dir ".harness/changes/<change-name>" `
   --verification unitTestFull --scope module `
   --project . --profile-input unitTestFull `
-  --command "<build-profile.json buildCommands.unitTestFull>" --json
+  --command "<resolved commands.unitTestFull.command>" --json
 ```
 
-- `--profile-input unitTestFull` 从 `build-profile.json` 的 `verificationInputs.unitTestFull` 展开**依赖闭包**文件集，**禁止用仅含 staged 业务文件的 `--files` 快捷方式**冒充全量闭包。
-- `--command` 必须直接读取当前项目 `build-profile.json` 的 `buildCommands.unitTestFull`，禁止原样复制示例模块名。
+- `--command` **按 profile key resolve**：读 `build-profile.json` 的 `commands.unitTestFull.command`（v2），或 `python <skills-root>/scripts/harness_profile.py resolve --project . --key unitTestFull --json` 取 resolved command。**禁止原样复制示例模块名**（命令按 profile key resolve，文档示例只展示 key）。
+- `--profile-input unitTestFull` 从 `build-profile.json` 的 `verificationInputs.unitTestFull`（v2 由 `commands.unitTestFull.inputs` 派生）展开**依赖闭包**文件集，**禁止用仅含 staged 业务文件的 `--files` 快捷方式**冒充全量闭包。
 - 增量 `unitTest`（scope=测试类）永远不能冒充 `unitTestFull` 门禁；ledger 只有 `unitTest` 时返回 `insufficient-evidence`。
-- `reuse=false` → 执行 `buildCommands.unitTestFull`（模块级全量单元测试），成功后用**同一文件集、command、`scope=module`** 写回 ledger 的 `unitTestFull` 项，再继续步骤 3。
-- profile 缺 `verificationInputs.unitTestFull` / glob 无匹配 / 结果为空 → 返回 `insufficient-evidence`（exit 0），仍须执行全量测试但**不允许缓存复用**，直到 profile 正确配置。
+- `reuse=true` → **不再执行二次全量测试**（删除与 coverage 冲突的二次门禁，spec §3.3）；仅 `reuse=false`（can-reuse 明确失败）时执行**同一 resolved verification**（profile `unitTestFull` 命令，模块级全量单元测试），成功后用**同一文件集、command、`scope=module`** 写回 ledger 的 `unitTestFull` 项，再继续步骤 3。
+- profile 缺 `commands.unitTestFull` / `verificationInputs.unitTestFull` / glob 无匹配 / 结果为空 → 返回 `insufficient-evidence`（exit 0），仍须执行全量测试但**不允许缓存复用**，直到 profile 正确配置。
 
 **编译/测试成功必须有明确证据**：
 - 构建命令输出必须包含构建成功证据（如 `BUILD SUCCESS` / `Finished` / exit code 0）
@@ -337,6 +337,21 @@ powershell.exe -Command "git -C '<项目路径>' pull --rebase"
 
 pull 输出非 `Already up to date.` → 引入他人提交 → M4 必须重跑验证。
 
+**CRLF 预检**（pull 后强制）：旧 working copy 的 `.gitattributes eol=lf` 文件可能是 CRLF（.gitattributes 后加未重新检出），曾导致 `core_content_hash` 跨工作树不一致 → sync 产生 dirty → M5 失败重跑。检测并修复：
+
+```powershell
+# 1. renormalize 暴露 CRLF 漂移（仅规范化行尾，不改内容语义）
+powershell.exe -Command "git -C '<项目路径>' add --renormalize ."
+# 2. 若 git status --porcelain 非空 → working copy 存在 CRLF 漂移
+powershell.exe -Command "git -C '<项目路径>' status --porcelain"
+# 3. 有漂移 → 弃 staging + 强制 LF 重检（worktree 合并段 M2 在主仓库 main，应 clean，安全）
+powershell.exe -Command "git -C '<项目路径>' reset -q; git -C '<项目路径>' checkout -- ."
+# 4. 重新 renormalize 确认 clean（git status --porcelain 应空）
+powershell.exe -Command "git -C '<项目路径>' add --renormalize .; git status --porcelain"
+```
+
+> cluster 1 的 `core_content_hash` 改用 git blob sha 后，CRLF 不再影响 core hash，但 working copy CRLF 仍可能影响 workflow-data 包内容 hash，预检仍有价值。
+
 ### 步骤 M3：合并 worktree 分支
 
 ```powershell
@@ -365,6 +380,15 @@ powershell.exe -Command "git -C '<项目路径>' diff --name-only --diff-filter=
 
 重跑后写回 ledger 的 `compile`/`unitTest`，更新 `diffHash`/`currentHead`。
 
+**写 check-ok marker**（npm run check exit 0 后强制）：让 pre-push hook 跳过重复 check（省 ~350s）。三重校验（marker ts<10min + command + HEAD），任一不满足照跑。
+
+```powershell
+# npm run check exit 0 后立即写 marker（M5 或 REUSED 后均可）
+powershell.exe -Command "python harness/scripts/harness_check_gate.py --write"
+```
+
+> marker 写入 `.harness/check-ok.marker`（gitignored，本地）。push 时 pre-push hook 读 marker：HEAD 自写 marker 后未变 + ts<10min + command 匹配 → 跳过 npm run check；否则照跑（安全默认）。
+
 ### 步骤 M6：push 主分支
 
 ```powershell

package/harness/bundles/java/cursor/harness-sync/SKILL.md

@@ -2,7 +2,7 @@
 name: harness-sync
 description: 检查并更新项目AI元数据（CodeGraph索引、harness-codebase-map分析、CLAUDE.md、AGENTS.md、.harness/完整性），确保Claude对代码库的理解与最新代码一致。当用户说'同步/更新索引/刷新元数据/检查一致性'时使用
 ---
-<!-- generated by harness_deploy.py; core=7b81effe1faaef85; overlay=java; agent=cursor; do not edit -->
+<!-- generated by harness_deploy.py; core=d437039c3207693b; overlay=java; agent=cursor; do not edit -->
 # harness-sync — 元数据同步
 
 ## Purpose

package/harness/bundles/java/cursor/harness-test/SKILL.md

@@ -2,7 +2,7 @@
 name: harness-test
 description: 测试执行：读取场景表，执行单元测试+API接口测试+数据兼容验证，输出测试报告。当用户说'跑测试/验证/跑用例/接口测试/单元测试'时使用
 ---
-<!-- generated by harness_deploy.py; core=7b81effe1faaef85; overlay=java; agent=cursor; do not edit -->
+<!-- generated by harness_deploy.py; core=d437039c3207693b; overlay=java; agent=cursor; do not edit -->
 # harness-test — 测试执行
 
 ## Purpose
@@ -78,9 +78,9 @@ description: 测试执行：读取场景表，执行单元测试+API接口测试
 ### Java 测试环境补充
 
 - **preflight 0.1**：写入 `runtime/preflight.json` 的 `executorPath`/`mvnVersion` 等；Maven 可用性 `mvn -version` exit 0
-- **编译门禁**：测试前按 `build-profile.json` 的 `buildCommands.compile`；输出须含 `BUILD SUCCESS` 或 exit 0 证据
-- **条件 install**：worktree 首建或上游模块变更时按 profile 执行 `buildCommands.install`（非每次强制 `-am`）
-- **单元测试**：可复用 ledger unitTest 则跳过；否则 `buildCommands.unitTest`（典型 `mvn test -pl <module>`）
+- **编译门禁**：测试前按 `build-profile.json` 的 `commands.compile`（v2，profile key resolve）；输出须含 `BUILD SUCCESS` 或 exit 0 证据
+- **条件 install**：worktree 首建或上游模块变更时按 profile 执行 `commands.install`（非每次强制 `-am`）
+- **单元测试**：可复用 ledger unitTest 则跳过；否则 `commands.unitTest`（典型 `mvn test -pl <module>`）；执行模块全量 `commands.unitTestFull` 成功 → 记 `unitTestFull`（scope=module，供 submit 复用）
 - **服务启动**：`build-profile.json` 的 `serviceStartTemplate`（典型 `spring-boot:run` + profile）；**禁止 hardcode 端口/模块路径**
 - **服务指纹输入**（Task 3 §5.1）：`serviceStart.inputFiles` 必须列出 module 源 glob（如 `["<module>/pom.xml", "<module>/src/main/**/*.java", "<module>/src/main/resources/**"]`）；`harness_service.py ensure` 取 CLI `--files` ∪ `inputFiles` 计算 `moduleInputsHash`。**空输入被拒绝**，不得生成可复用空指纹。源码/command/profile/overlayPath 任一变化即 restart
 - **runtime overlay**：`-Dspring.config.additional-location=file:<ascii-abs-path>/application-harness-test.yml`；禁止默认 Edit tracked `application*.yml`
@@ -111,7 +111,7 @@ description: 测试执行：读取场景表，执行单元测试+API接口测试
 
 ### 四、单元测试复用 + 写入 ledger
 
-Phase 1 前先读 `.harness/changes/<change-name>/evidence/verification-ledger.json`：run 的 unitTest 满足（diffHash 一致 + module/profile 一致 + scope 一致或更严格 + run 后无行为性修改 + run 跑了全量测试）则复用，否则重跑测试命令（按技术栈，如 `mvn test -pl <module>`）。Phase 1/2 完成后必须写回 ledger 的 `unitTest`/`apiTest` 项。详见 `checklist.md`「单元测试复用」、`../protocols/ledger-protocol.md`。
+Phase 1 前先读 `.harness/changes/<change-name>/evidence/verification-ledger.json`：run 的 unitTest 满足（diffHash 一致 + module/profile 一致 + scope 一致或更严格 + run 后无行为性修改 + run 跑了全量测试）则复用，否则按 **profile key resolve** 执行测试命令（`python <skills-root>/scripts/harness_profile.py resolve --project . --key unitTest|unitTestFull --json`，**不复制示例 `-pl` 命令**）。Phase 1/2 完成后必须写回 ledger：执行增量测试类 → 记 `unitTest`（scope=incremental）；执行 profile 模块全量命令 → 记 `unitTestFull`（scope=module，可供 submit 复用）；接口测试 → 记 `apiTest`。详见 `checklist.md`「单元测试复用」、`../protocols/ledger-protocol.md`。
 
 ### 五、命令与请求超时治理
 

package/harness/bundles/java/cursor/harness-test/pitfalls.md

@@ -258,3 +258,19 @@ $cred = $resp.data.accessToken
 **正确做法**：用 `git diff --binary` 生成 patch 并计算 SHA-256，ledger 只认 `sha256:<hash>` 格式。diffHash 不一致时必须重跑相关测试。
 
 > 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` 生成（profile v2 `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/cursor/harness-test/scripts/runtime-helpers.mjs

@@ -0,0 +1,216 @@
+#!/usr/bin/env node
+// runtime-helpers.mjs — BOM-safe JSON I/O + test-identifier sanitizer + runner payload validation + credential scan.
+// 变更簇 5 (spec §3.4): BOM-safe Runner, identifier sanitizer, 凭据边界.
+//
+// 设计目标:
+//  - readJsonUtf8BomSafe: 容忍 UTF-8 BOM (U+FEFF), credential-cache.json 等文件可能被 PS5.1 写入 BOM
+//  - writeJsonUtf8NoBom: 原子写 (temp+rename), UTF-8 no BOM, LF — 结果/报告文件字节稳定
+//  - sanitizeTestIdentifier: 按 pattern/maxLength/prefix 生成稳定标识; 超长截断 + 原文名短 hash 防碰撞
+//  - validateRunnerPayload: Runner 生成前本地校验 payload schema/必填/identifier, 测试脚本错误不得请求服务后才发现
+//  - findCredentialValues: 扫描 profile/Markdown/docs 中的凭据明文值 (sensitive-info-protocol §1)
+//
+// Node ≥18 ESM, stdlib only. 输出 JSON 内容确定性 (不含 Math.random); 仅临时文件名用 randomBytes.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+export const BOM = 0xfeff;
+export const DEFAULT_IDENTIFIER_PATTERN = '^[A-Za-z][A-Za-z0-9_-]*$';
+export const DEFAULT_IDENTIFIER_MAX_LENGTH = 64;
+const HASH_LEN = 8;
+
+// ---------------------------------------------------------------------------
+// BOM-safe JSON I/O
+// ---------------------------------------------------------------------------
+
+/** Strip a single leading UTF-8 BOM (U+FEFF) from text. No-op if absent. */
+export function stripBom(text) {
+  return text.codePointAt(0) === BOM ? text.slice(1) : text;
+}
+
+/** Read a JSON file, tolerating a leading UTF-8 BOM. Throws on invalid JSON. */
+export function readJsonUtf8BomSafe(filePath) {
+  const raw = fs.readFileSync(filePath, 'utf8');
+  return JSON.parse(stripBom(raw));
+}
+
+/** Atomically write JSON as UTF-8 (no BOM), LF, 2-space indent, trailing newline.
+ *  Writes to a temp file then renames — readers never see a half-written file. */
+export function writeJsonUtf8NoBom(filePath, value) {
+  const json = JSON.stringify(value, null, 2) + '\n';
+  const dir = path.dirname(filePath);
+  fs.mkdirSync(dir, { recursive: true });
+  const tmp = `${filePath}.${process.pid}.${crypto.randomBytes(6).toString('hex')}.tmp`;
+  fs.writeFileSync(tmp, json, 'utf8');
+  try {
+    fs.renameSync(tmp, filePath);
+  } catch (err) {
+    try {
+      fs.unlinkSync(tmp);
+    } catch {
+      /* best-effort cleanup */
+    }
+    throw err;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// sanitizeTestIdentifier
+// ---------------------------------------------------------------------------
+
+/**
+ * Sanitize a change/test name into a stable identifier matching the default
+ * pattern `^[A-Za-z][A-Za-z0-9_-]*$`.
+ *
+ * - runs of chars outside [A-Za-z0-9_-] → '_'
+ * - prepend `prefix_` when prefix given; ensure leading letter (prepend 'T')
+ * - if over maxLength: truncate and append a short sha256 hash of the ORIGINAL
+ *   name, so two near-identical long names that collide after truncation stay
+ *   distinct (UT-023). Hash is deterministic — no Math.random.
+ *
+ * @returns {string} identifier matching the default pattern, length ≤ maxLength.
+ */
+export function sanitizeTestIdentifier({
+  name,
+  pattern = DEFAULT_IDENTIFIER_PATTERN,
+  maxLength = DEFAULT_IDENTIFIER_MAX_LENGTH,
+  prefix = '',
+}) {
+  const raw = String(name ?? '');
+  let base = prefix ? `${prefix}_` : '';
+  base += raw.replace(/[^A-Za-z0-9_-]+/g, '_');
+  // leading letter (pattern ^[A-Za-z]); prepend 'T' if first char is _ or digit
+  if (!/^[A-Za-z]/.test(base)) base = `T${base}`;
+  if (base.length <= maxLength) return base;
+  const hash = crypto.createHash('sha256').update(raw, 'utf8').digest('hex').slice(0, HASH_LEN);
+  const reserve = HASH_LEN + 1; // '_' + hash
+  const cap = Math.max(1, maxLength - reserve);
+  let truncated = base.slice(0, cap).replace(/_+$/, '');
+  // if truncation removed the leading letter guarantee, restore it
+  if (!/^[A-Za-z]/.test(truncated)) truncated = `T${truncated}`;
+  return `${truncated}_${hash}`;
+}
+
+/** Compile a pattern safely; returns null if invalid. */
+function safeRegex(pattern) {
+  try {
+    return new RegExp(`^(?:${pattern})$`);
+  } catch {
+    return null;
+  }
+}
+
+/** True if id matches pattern. Invalid pattern → false. */
+export function matchesPattern(id, pattern = DEFAULT_IDENTIFIER_PATTERN) {
+  const re = safeRegex(pattern);
+  return re ? re.test(String(id)) : false;
+}
+
+// ---------------------------------------------------------------------------
+// validateRunnerPayload — Runner 生成前本地校验
+// ---------------------------------------------------------------------------
+
+const HTTP_METHODS = /^(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)$/i;
+
+/**
+ * Validate a runner payload (array of API test scenarios) BEFORE generating or
+ * executing the runner. Catches script/schema errors locally so they don't
+ * surface only after a service request (spec §3.4 point 3).
+ *
+ * Scenario required fields: id, method, url. id must match identifierPattern
+ * and be unique. method must be a known HTTP method.
+ *
+ * @returns {{ ok: boolean, errors: Array<{code: string, field: string, message: string}> }}
+ */
+export function validateRunnerPayload(payload, opts = {}) {
+  const errors = [];
+  const pattern = opts.identifierPattern || DEFAULT_IDENTIFIER_PATTERN;
+  const re = safeRegex(pattern);
+
+  if (!Array.isArray(payload)) {
+    return {
+      ok: false,
+      errors: [{ code: 'PAYLOAD_NOT_ARRAY', field: 'payload', message: 'payload must be an array of scenarios' }],
+    };
+  }
+  if (payload.length === 0) {
+    errors.push({ code: 'PAYLOAD_EMPTY', field: 'payload', message: 'payload has no scenarios' });
+  }
+
+  const seenIds = new Set();
+  payload.forEach((scn, i) => {
+    const where = `scenarios[${i}]`;
+    if (!scn || typeof scn !== 'object' || Array.isArray(scn)) {
+      errors.push({ code: 'SCENARIO_NOT_OBJECT', field: where, message: 'scenario must be an object' });
+      return;
+    }
+    for (const f of ['id', 'method', 'url']) {
+      if (scn[f] === undefined || scn[f] === null || scn[f] === '') {
+        errors.push({ code: 'MISSING_FIELD', field: `${where}.${f}`, message: `required field '${f}' missing or empty` });
+      }
+    }
+    if (scn.id !== undefined && scn.id !== null && scn.id !== '') {
+      const idStr = String(scn.id);
+      if (re && !re.test(idStr)) {
+        errors.push({ code: 'INVALID_IDENTIFIER', field: `${where}.id`, message: `id '${idStr}' does not match pattern ${pattern}` });
+      }
+      if (seenIds.has(idStr)) {
+        errors.push({ code: 'DUPLICATE_ID', field: `${where}.id`, message: `duplicate id '${idStr}'` });
+      } else {
+        seenIds.add(idStr);
+      }
+    }
+    if (scn.method !== undefined && scn.method !== null && scn.method !== '') {
+      if (!HTTP_METHODS.test(String(scn.method))) {
+        errors.push({ code: 'INVALID_METHOD', field: `${where}.method`, message: `unknown HTTP method '${scn.method}'` });
+      }
+    }
+  });
+
+  return { ok: errors.length === 0, errors };
+}
+
+// ---------------------------------------------------------------------------
+// findCredentialValues — 凭据明文扫描 (sensitive-info-protocol §1)
+// ---------------------------------------------------------------------------
+
+// 值占位符或 env 引用 (不会被当作凭据明文): <*_REDACTED> / ${ENV} / $ENV
+// 前缀匹配 ${ENV (无需闭合 }) — value 正则在 } 处停止, 仍应识别为 env 引用。
+const SAFE_VALUE = /<\w+_REDACTED>|\$\{[A-Z0-9_]+|\$[A-Z][A-Z0-9_]*\b/;
+
+const CRED_PATTERNS = [
+  // password / passwd / pwd = 或 : 后跟值 (字段名可带 JSON/YAML 引号)
+  { code: 'PASSWORD_VALUE', re: /"?password"?\s*[:=]\s*(['"]?)([^'"\s,;)}\n]+)\1/i, group: 2 },
+  // token / access_token / api_key / apikey / secret / accessKey / secretAccessKey
+  { code: 'SECRET_VALUE', re: /(?:"?(?:access_token|apikey|api_key|secretAccessKey|accessKey|secret|token)"?)\s*[:=]\s*(['"]?)([^'"\s,;)}\n]+)\1/i, group: 2 },
+  // Authorization: Bearer <jwt-ish>
+  { code: 'AUTH_HEADER', re: /Authorization\s*:\s*Bearer\s+([A-Za-z0-9_.-]{10,})/i, group: 1 },
+  // jdbc url with password=
+  { code: 'DB_PASSWORD', re: /jdbc:[^\s?]*[?&]password=([^&\s]+)/i, group: 1 },
+];
+
+/**
+ * Scan text for credential VALUES per sensitive-info-protocol §1.
+ * Placeholders (`<TOKEN_REDACTED>`) and env refs (`${DB_PASSWORD}` / `$DB_PASSWORD`)
+ * are NOT flagged — credential config may carry env keys, not values (spec §3.4 point 4).
+ *
+ * @returns {Array<{ line: number, code: string, snippet: string }>}
+ */
+export function findCredentialValues(text) {
+  const findings = [];
+  const lines = String(text ?? '').split(/\r?\n/);
+  lines.forEach((line, idx) => {
+    for (const { code, re, group } of CRED_PATTERNS) {
+      const m = line.match(re);
+      if (!m) continue;
+      const value = m[group] || '';
+      if (SAFE_VALUE.test(value)) continue; // placeholder / env ref — safe
+      // Redact the captured credential value in the snippet so reports/logs
+      // never leak it; field name + line number remain for locating the finding.
+      const snippet = (value ? line.replace(value, '<REDACTED>') : line).trim().slice(0, 80);
+      findings.push({ line: idx + 1, code, snippet });
+    }
+  });
+  return findings;
+}

package/harness/bundles/java/cursor/protocols/archive-report-protocol.md

@@ -139,7 +139,7 @@ PowerShell HTML renderer 仅作 legacy fallback。该脚本以 UTF-8 with BOM
 
 **Python fallback（`harness_archive.py` 内置）**：Node 不可用/超时/exit 非 0/未产出文件时，`harness_archive.py render_final_summary` 自动降级为内置 Python fallback（`render_fallback_html`），渲染含 changeName、finalStatus、`reportPipeline.commands`（command/exitCode）、`verification`（unitTests/apiTests/dbCompatibility）、changedFiles、archiveManifest、knownRisks、manualActions、maintenanceNotes 的确定性 HTML；USER_SKIPPED/BLOCKED_BY_DBA/失败状态可见，所有动态值 HTML 转义。返回结构统一为 `{ok, renderer: node|python-fallback|none, fallbackReason, out_path}`。Node 与 Python fallback **都失败**（`renderer=none, ok=false`）时，finalize 立即恢复原 change 目录并 exit 非 0，**绝不归档无 final-summary.html 的变更**。
 
-渲染后必须运行 report validate；validate error 存在时，archive 不得删除原 changes 目录。**缺 final-summary.html 恒为 validate error**（不再有"没有 HTML 但只 warning"的分支）。
+`validate` 是 `harness_archive.py finalize` 的内嵌同进程步骤（不存在独立 `report validate` CLI）；validate error 存在时，finalize 恢复原 changes 目录并 exit 非 0，绝不删除原 changes 目录。**缺 final-summary.html 恒为 validate error**（不再有"没有 HTML 但只 warning"的分支）。
 
 ## 归档与知识维护解耦（§8）
 

package/harness/bundles/java/cursor/protocols/ledger-protocol.md

@@ -182,7 +182,7 @@ verification-ledger 把每次验证（compile / unit test / api test / package
 ```text
 harness_ledger.py can-reuse --verification unitTestFull --scope module \
   --project . --profile-input unitTestFull \
-  --command "<build-profile.json buildCommands.unitTestFull>" --json
+  --command "<resolved build-profile.json commands.unitTestFull.command>" --json
 ```
 
 `build-profile.json` 新增 `verificationInputs.unitTestFull`（glob 列表，相对 project 展开，只保留 project 内文件、去重排序）：
@@ -201,7 +201,17 @@ profile key 缺失 / glob 无匹配 / 结果为空 → `insufficient-evidence`
 
 必须基于真实 diff 计算 SHA-256，且**必须是 commit-invariant 的**——覆盖本变更集相对 `baseCommit` 的全部内容变更（已提交 + 未提交 + 未跟踪），使 checkpoint commit 前后指纹一致，保证 run→test 复用链不断。
 
-`<baseCommit>` 从 ledger 读取（harness-plan 阶段写入）；缺失时用 `git merge-base HEAD <默认分支>` 兜底。推荐命令：
+`<baseCommit>` 从 ledger 读取（harness-plan 阶段写入）；缺失时用 `git merge-base HEAD <默认分支>` 兜底。
+
+**canonical 命令（cluster 2 起脚本化，推荐）**：
+
+```text
+harness_ledger.py diff-hash --repo <projectRoot> --base <baseCommit> --json
+```
+
+`diff-hash` 用 subprocess 直接捕获 Git bytes，基于**内容变更集**计算 SHA-256：working tree 相对 base 的所有变化文件 + 未跟踪文件，按 repo-relative path 排序、长度 framing（`path-len | path | exists | content-len | content`），独立于 shell/控制台编码/BOM/系统换行，且 **commit-invariant**（checkpoint commit 不改 working tree → 指纹不变，UT-011）。算法版本 `content-changeset-1`，输出 `diffHash`/`algorithmVersion`/`fileCount`/`base`/`head`。
+
+> 旧 v1 PowerShell 拼接命令（下方）已废弃：依赖文本编码，且未跟踪文件提交后表示从 framed-content 切换为 diff-format 会破坏 commit-invariance。仅作历史参考。
 
 ```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"
@@ -268,3 +278,46 @@ ledger 的 `status` 与 final-summary 展示状态对应：
 | postTestClassification=NON_BEHAVIORAL_CLEANUP | 小清理 | 🧹NON_BEHAVIORAL_CLEANUP |
 
 **强制规则**：任何阶段若复用了前一阶段结果，final-summary 必须显示 `🔁REUSED`，**不得伪装成重新执行**。
+
+## 九、Ledger v2（cluster 2）
+
+`harness_ledger.py` v2 引入确定性 `diff-hash`（§五）、v2 entry 字段、coverage lattice、`package` verification 与结构化错误码。Skill 只调用 `record`/`can-reuse`/`diff-hash`，不再手工判断或解释自由文本。
+
+### 9.1 v2 entry 字段
+
+`record` 自动写入：
+
+| 字段 | 含义 |
+|------|------|
+| `algorithmVersion` | 固定 `harness-ledger-2`；缺失即 v1 entry |
+| `coverage` | 覆盖层级 `incremental`/`module`/`module-am`/`full`，由 verification+scope 派生或 `--coverage` 显式指定 |
+| `toolchainHash`/`profileHash`/`environmentHash` | 可选；`record --toolchain-hash` 等写入，`can-reuse --toolchain-hash` 等比对（UT-017） |
+
+### 9.2 coverage lattice
+
+`COVERAGE_RANK = {incremental:0, module:1, module-am:2, full:3}`。各 verification 最低要求：`unitTest`=0、`unitTestFull`/`compile`/`apiTest`=1、`install`/`package`=2。entry.coverage rank < 要求 → `insufficient-evidence`（code `COVERAGE_INSUFFICIENT`），**禁止增量证据提升为全量门禁**（UT-015/API-005）。
+
+### 9.3 package verification
+
+`package` 加入 `VERIFICATIONS`。`record --verification package` 额外记录 `deployArtifact`/`sha256`/`testsExecuted`/`testsReusedFrom`。API-006/007 的 package 生命周期复用编排由 cluster 4 负责，cluster 2 仅提供 record/can-reuse 能力（UT-018）。
+
+### 9.4 结构化错误码
+
+`can-reuse` 每个非 reuse 结果携带 `code` 字段，Skill 据 `code` 决策，不解析 `detail` 自由文本：
+
+| code | reason | 含义 |
+|------|--------|------|
+| `LEDGER_MISSING`/`VALIDATIONS_MISSING`/`VALIDATION_MISSING` | insufficient-evidence | ledger/条目缺失 |
+| `MISSING_V2_FIELDS` | insufficient-evidence | v1 entry 缺 algorithmVersion/coverage，**一次性保守失效**（COM-002），重记录 v2 后可复用 |
+| `MISSING_FIELDS` | insufficient-evidence | 缺 status/evidence/inputsHash/scope 等基础字段 |
+| `COVERAGE_INSUFFICIENT` | insufficient-evidence | coverage rank 不足 |
+| `SCOPE_INSUFFICIENT` | insufficient-evidence | unitTest scope 不覆盖请求 |
+| `INPUT_FILE_MISSING` | insufficient-evidence | 当前文件集读取失败 |
+| `COMMAND_CHANGED` | rerun | 命令变化 |
+| `TOOLCHAIN_CHANGED`/`PROFILE_CHANGED`/`ENVIRONMENT_CHANGED` | rerun | 对应 hash 变化（UT-017） |
+| `INPUTS_HASH_CHANGED` | rerun | inputsHash 变化 |
+| `REUSED` | reuse | 复用 |
+
+### 9.5 v1→v2 兼容
+
+v1 ledger 可读；entry 缺 v2 字段时 `can-reuse` 返回 `MISSING_V2_FIELDS`（insufficient-evidence），**不静默升级证据**。重新 `record`（自动补 v2 字段）后恢复复用。diffHash 算法升级后旧 ledger 一次性失效，不危险复用。

package/harness/bundles/java/cursor/protocols/report-pipeline-protocol.md

@@ -24,14 +24,7 @@ python <skills-root>/scripts/harness_archive.py replay --archive-dir ".harness/a
 python <skills-root>/scripts/harness_events.py append --change-dir ".harness/changes/<change-name>" --phase "<phase>" --type <type> [--note "..."]
 ```
 
-若项目安装 Hunter-Harness CLI，collect/validate 亦可使用（与 finalize 内嵌步骤等价）：
-
-```powershell
-powershell.exe -NoProfile -Command "npx hunter-harness report collect --change-id '<change-name>' --json"
-powershell.exe -NoProfile -Command "npx hunter-harness report validate --change-id '<change-name>' --json"
-```
-
-CLI 不可用时，agent 仍必须按本协议生成等价的 `summary-data.json` 并执行一致性校验，不得退回手写汇总。
+归档报告流水线只有两个入口，均由 `harness_archive.py` 提供：`collect`/`render`/`validate` 是 `finalize` 的内嵌同进程步骤，**不再作为独立 CLI 暴露**（不存在 `report collect`/`report validate` 子命令）。`summary-data.json` 只能由 `finalize`（归档时）或 `replay`（回放时）生成；**禁止 agent 临场手写或拼装等价的 `summary-data.json`**。`harness_archive.py` 不可用时归档失败退出，不得退回手写汇总。
 
 ## events.ndjson
 

package/harness/bundles/java/cursor/protocols/sensitive-info-protocol.md

@@ -90,3 +90,16 @@ spring:
 - API 测试报告的持久化记录中
 
 > 对于 API 测试中获取的 token，在测试执行过程中可临时使用（如 Playwright 请求），但测试报告中必须用 `<TOKEN_REDACTED>` 替换。
+
+## 6. profile / 规则 / Markdown 凭据扫描
+
+profile `build-profile.json`、规则文档、Skill Markdown **不得包含凭据明文值**（spec §3.4 凭据边界：配置只含 env key、cache path、角色，不含值）。发布前用 `harness-test/scripts/runtime-helpers.mjs` 的 `findCredentialValues(text)` 扫描：
+
+- 命中 `password/token/secret/accessKey/Authorization: Bearer/jdbc password=` 等明文值 → ❌FAIL，必须改为占位符 `<*_REDACTED>` 或 env 引用 `${ENV}` / `$ENV`。
+- 占位符 `<TOKEN_REDACTED>` 与 env 引用 `${TEST_TOKEN}` / `$DB_PASSWORD` 不报（credential 配置允许 env key）。
+
+```js
+import { findCredentialValues } from '<skills-root>/harness-test/scripts/runtime-helpers.mjs';
+const findings = findCredentialValues(fs.readFileSync('build-profile.json', 'utf8'));
+if (findings.length > 0) { /* ❌FAIL: 列出 line/code/snippet，改为 env key 或占位符 */ }
+```