@hunter-harness/workflow-harness 0.2.1 → 0.2.3

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

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

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

@@ -2,7 +2,7 @@
 name: harness-package
 description: 增量模块打包：拉取最新→编译验证→mvn package→汇总 jar/war。使用场景：打包、package、发版准备
 ---
-<!-- generated by harness_deploy.py; core=65b0b8e31d85f905; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=959b22fdc1e7af33; overlay=java; agent=codebuddy; 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/codebuddy/harness-plan/SKILL.md

@@ -2,7 +2,7 @@
 name: harness-plan
 description: 将需求转化为设计文档+实施计划+完整测试场景表，必须在编码前完成。使用场景：需求分析、feature plan、技术方案设计、实现方案规划
 ---
-<!-- generated by harness_deploy.py; core=65b0b8e31d85f905; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=959b22fdc1e7af33; overlay=java; agent=codebuddy; 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/codebuddy/harness-review/SKILL.md

@@ -3,7 +3,7 @@ name: harness-review
 description: 6维度代码审查（架构/安全/规范/兼容/测试/性能），对照项目规则（见
   .harness/context-index.json）和测试场景表，在隔离上下文运行。使用场景：代码审查、提交前检查、合并评审
 ---
-<!-- generated by harness_deploy.py; core=65b0b8e31d85f905; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=959b22fdc1e7af33; overlay=java; agent=codebuddy; do not edit -->
 # harness-review — 代码审查
 
 ## Purpose
@@ -125,6 +125,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/codebuddy/harness-run/SKILL.md

@@ -2,7 +2,7 @@
 name: harness-run
 description: 按变更簇执行 TDD 编码循环（RED→GREEN→REFACTOR→编译验证），逐变更簇实现计划中的任务。使用场景：开始编码、实现功能、写代码、TDD 编码
 ---
-<!-- generated by harness_deploy.py; core=65b0b8e31d85f905; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=959b22fdc1e7af33; overlay=java; agent=codebuddy; 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/codebuddy/harness-run/checklist.md

@@ -30,6 +30,8 @@
 - [ ] **读取任务状态**：`.harness/changes/<change>/run-task-status.md`（如存在）— 恢复上次运行状态
 - [ ] 确认 `项目规则（见 .harness/context-index.json）/` 规则已加载
 - [ ] 检查构建配置完整性（worktree 中确认 `.mvn/maven.config`、`settings.xml` 等存在）
+- [ ] 读取 `.mvn/maven.config`，确认命令没有重复或覆盖项目已有的 `-s` / `-o` / 仓库设置
+- [ ] 离线依赖缺失时仅在项目规则允许联网的前提下执行至多一次非离线 `-nsu` 恢复；禁止离线/联网循环重试
 - [ ] 依赖模块预安装（worktree 中检查上游模块是否已 `mvn install`）
 - [ ] 代码探索优先用 `codegraph_explore`，仅在返回不完整时补充 Read
 - [ ] append `phase.start`（`note` 含测试基础设施 CHECKING 直至探测完成）
@@ -45,7 +47,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/codebuddy/harness-run/reference.md

@@ -97,6 +97,12 @@ powershell.exe -NoProfile -Command "Test-Path '.claude/worktrees/<change-name>/.
 13. **依赖模块预安装**：如果在 worktree 中执行，检查上游依赖模块是否已 `mvn install` 到本地仓库。缺失时先执行 `powershell.exe -Command "mvn install -pl <upstream-modules> -am -DskipTests -nsu"`
 14. **代码探索优先用 codegraph_explore**：一次调用可获取多个相关符号的源码，替代逐个 Read 文件。违反 `项目 codegraph 规则` 规则逐个 Read 会浪费 3-5 分钟。仅在 codegraph 返回结果不完整时补充 Read
 
+### Maven 项目配置与重试预算
+
+- 运行 Maven 前先读取项目已有的 `.mvn/maven.config`；其中的 `-s`、`-o`、镜像和仓库设置视为项目契约，不在命令行重复追加或覆盖。
+- 若项目配置已启用离线模式，依赖缺失只允许一次有明确原因的恢复尝试：仅在项目规则允许联网时临时执行非离线的 `-nsu` 命令；随后继续遵循项目配置，不得在离线/联网命令之间循环试错。
+- 同一失败命令不得无分析地重复执行。先按“配置/依赖缺失、编译、测试、业务断言”分类，再决定修复或停止；每个变更簇仍遵守一次 RED、一次 GREEN 的 Maven 预算。
+
 ### 步骤 0.1：执行模式（默认 Inline）
 
 默认 **Inline Execution**；仅 `--subagent` 强制 Subagent-Driven。**不询问**任务数/模块数（P1-5）。

package/harness/bundles/java/codebuddy/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=65b0b8e31d85f905; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=959b22fdc1e7af33; overlay=java; agent=codebuddy; 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/codebuddy/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。三重校验（marker ts<10min + command + commit tree），任一不满足照跑。marker 写入时记录 `git write-tree`，因此验证后创建 commit 不会仅因 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 比较 `HEAD^{tree}` 与 marker 的 `treeHash`，再校验 ts<10min + command；commit tree 未变化即可跳过，任何内容变化都照跑（安全默认）。
+
 ### 步骤 M6：push 主分支
 
 ```powershell

package/harness/bundles/java/codebuddy/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=65b0b8e31d85f905; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=959b22fdc1e7af33; overlay=java; agent=codebuddy; do not edit -->
 # harness-sync — 元数据同步
 
 ## Purpose

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

@@ -2,7 +2,7 @@
 name: harness-test
 description: 测试执行：读取场景表，执行单元测试+API接口测试+数据兼容验证，输出测试报告。当用户说'跑测试/验证/跑用例/接口测试/单元测试'时使用
 ---
-<!-- generated by harness_deploy.py; core=65b0b8e31d85f905; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=959b22fdc1e7af33; overlay=java; agent=codebuddy; 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/codebuddy/harness-test/checklist.md

@@ -37,6 +37,8 @@ description: harness-test 的 Phase 0 环境准备 + Playwright 探测 + 关门
 - [ ] 检查 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**
@@ -314,4 +316,4 @@ powershell.exe -Command "Copy-Item '<main-dir>/<module>/src/main/resources/appli
 - 请求执行器必须在报告中明确记录（四种执行器，含降级原因）
 - 请求耗时统计必须包含在报告中
 - 服务由 AI 启动的情况，测试结束默认 Stop-Process；**即使测试失败也要进入 finally 清理**
-- final-summary 的 apiTest 状态必须用 OK/PARTIAL/BLOCKED/NOT_RUN/FAIL（不得把 PARTIAL 写成 NOT_RUN）
+- final-summary 的 apiTest 状态必须用 OK/PARTIAL/BLOCKED/NOT_RUN/FAIL（不得把 PARTIAL 写成 NOT_RUN）

package/harness/bundles/java/codebuddy/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/codebuddy/harness-test/reference.md

@@ -6,6 +6,8 @@ description: harness-test 的 API 测试执行细节、批量 runner、token 缓
 
 ## 命令执行模式 preflight（0.0y）
 
+执行 Maven 前必须读取 `.mvn/maven.config`。项目已声明的 `-s`、`-o`、镜像和仓库设置不得被测试命令重复追加或覆盖。离线依赖缺失时，只有在项目规则允许联网的情况下，才可临时执行至多一次非离线 `-nsu` 恢复；失败后停止并报告缺失依赖，不得在多套 Maven 参数间反复试跑。
+
 `/harness-test` 高度依赖 PowerShell 与 Node。在编译/启动服务/生成 runner **之前**
 必须执行 4 项执行模式检查：
 

package/harness/bundles/java/codebuddy/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/codebuddy/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/codebuddy/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 一次性失效，不危险复用。