@hunter-harness/workflow-harness 0.2.1 → 0.2.3

package/harness/bundles/general/claude-code/harness-knowledge-query/SKILL.md

@@ -20,7 +20,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=781daf01a900c012; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=31546eadb30f5fdf; overlay=none; agent=claude-code; do not edit -->
 # harness-knowledge-query
 
 根据用户的新需求或排查问题，从项目本地 `.harness/knowledge` 中检索历史需求、决策、实现、风险和测试证据，并生成 AI 可读的 context pack。

package/harness/bundles/general/claude-code/harness-plan/SKILL.md

@@ -20,7 +20,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=781daf01a900c012; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=31546eadb30f5fdf; overlay=none; agent=claude-code; do not edit -->
 # harness-plan — 需求规划
 
 ## Purpose
@@ -99,6 +99,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/general/claude-code/harness-review/SKILL.md

@@ -21,7 +21,7 @@ disallowed-tools:
   - Bash(curl *)
   - Bash(codegraph *)
 ---
-<!-- generated by harness_deploy.py; core=781daf01a900c012; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=31546eadb30f5fdf; overlay=none; agent=claude-code; do not edit -->
 # harness-review — 代码审查
 
 ## Purpose
@@ -143,6 +143,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/general/claude-code/harness-run/SKILL.md

@@ -21,7 +21,7 @@ disallowed-tools:
   - Bash(curl *)
   - Bash(codegraph *)
 ---
-<!-- generated by harness_deploy.py; core=781daf01a900c012; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=31546eadb30f5fdf; overlay=none; agent=claude-code; do not edit -->
 # harness-run — 需求编码
 
 ## Purpose

package/harness/bundles/general/claude-code/harness-run/checklist.md

@@ -54,7 +54,7 @@ description: harness-run 的执行检查清单。仅在编码执行时读取。
 - [ ] 探测 1：测试目录是否存在（如 Java 的 `src/test/java`）
 - [ ] 探测 2：构建配置/依赖清单是否包含测试依赖（如 Java 的 `pom.xml` 含 `spring-boot-starter-test`/`junit`/`mockito`）
 - [ ] 探测 3：是否存在已有测试文件（按技术栈测试命名约定，如 Java 的 `*Test.java`/`*Tests.java`）
-- [ ] 探测 4：目标模块测试命令是否可运行（按技术栈，如 Java 的 `mvn test -pl <module> -o -q` 试运行）
+- [ ] 探测 4：目标模块测试基础设施是否可用（按技术栈，如 Java 的 `mvn test-compile -pl <module> -o -q` 验证测试可编译，或测试枚举/秒级 smoke；**禁止完整模块测试**，spec §3.3）
 - [ ] 四项证据收集完毕 → 写结论：✅ 测试基础设施可用 / 🟡 测试基础设施部分可用 / ❌ 测试基础设施不可用
 - [ ] 如果 ❌ 不可用 → 记录 TDD 降级原因（必须引用具体证据，如"模块 X 无测试目录（如 Java 的 src/test/java）"）
 

package/harness/bundles/general/claude-code/harness-submit/SKILL.md

@@ -20,7 +20,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=781daf01a900c012; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=31546eadb30f5fdf; overlay=none; agent=claude-code; do not edit -->
 # harness-submit — 最终提交（含 worktree 合并）
 
 ## Purpose
@@ -72,7 +72,7 @@ disallowed-tools:
 
 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；用户确认

package/harness/bundles/general/claude-code/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/general/claude-code/harness-sync/SKILL.md

@@ -19,7 +19,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=781daf01a900c012; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=31546eadb30f5fdf; overlay=none; agent=claude-code; do not edit -->
 # harness-sync — 元数据同步
 
 ## Purpose

package/harness/bundles/general/claude-code/harness-test/SKILL.md

@@ -22,7 +22,7 @@ disallowed-tools:
   - Bash(node *)
   - Bash(codegraph *)
 ---
-<!-- generated by harness_deploy.py; core=781daf01a900c012; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=31546eadb30f5fdf; overlay=none; agent=claude-code; do not edit -->
 # harness-test — 测试执行
 
 ## Purpose
@@ -119,7 +119,7 @@ disallowed-tools:
 
 ### 四、单元测试复用 + 写入 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/general/claude-code/harness-test/checklist.md

@@ -251,7 +251,7 @@ powershell.exe -NoProfile -Command "try { (Invoke-WebRequest -Uri 'http://127.0.
 - [ ] Phase 1 前读取 `.harness/changes/<change-name>/evidence/verification-ledger.json`
 - [ ] 判断是否复用 run 的 unitTest：diffHash 一致 + module/profile 一致 + scope 一致或更严格 + run 后无行为性修改 + run 实际跑了全量测试
 - [ ] 复用 → 跳过重跑，标记"✅ 复用 harness-run 单元测试结果"
-- [ ] 不复用 → 重跑测试命令（按技术栈，如 `mvn test -pl <module>`），结果写回 ledger 的 `unitTest` 项
+- [ ] 不复用 → 按 profile key resolve 重跑测试命令（`harness_profile.py resolve --key unitTest`，不复制示例 `-pl` 命令），结果写回 ledger 的 `unitTest` 项
 
 ### 批量执行器（强制单次 PowerShell + 执行器绝对路径执行）
 

package/harness/bundles/general/claude-code/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/general/claude-code/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/general/claude-code/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/general/claude-code/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/general/claude-code/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/general/claude-code/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 或占位符 */ }
+```

package/harness/bundles/general/claude-code/protocols/state-layout-protocol.md

@@ -98,6 +98,30 @@ description: harness .harness 状态目录分层协议。用于减少根目录
 
 后续阶段应优先从该文件读取路径，避免手拼 change-name 导致路径拼写错误。
 
+## state-snapshot.json（cluster 3 §3.6）
+
+`meta/state-snapshot.json`（由 `harness_state.py` 写入）集中记录 project/worktree root、HEAD/base、profile/rules/map/knowledge/diff 各段指纹与相关文件。plan/run/test/review/submit 读取该快照；失效时由脚本刷新，**不得仅凭缓存跳过代码或验证门禁**。
+
+schema：
+
+```json
+{
+  "schemaVersion": 1,
+  "generatedAt": "<iso>",
+  "changeName": "<change-name>",
+  "project": {"root": "<abs>"},
+  "worktree": {"root": "<abs>"},
+  "git": {"base": "<sha>", "head": "<sha>"},
+  "segments": {
+    "<segment>": {"fingerprint": "sha256:...", "files": ["..."], "capturedAt": "<iso>"}
+  }
+}
+```
+
+各段独立失效：`is_segment_stale(snapshot, segment, current_fingerprint)` 比较单段指纹；段不存在 → stale（需采集）。`refresh_segments(..., segments=["profile"])` 只重采受影响段，其他段保留原 capturedAt/fingerprint（缓存失效只重采受影响段）。
+
+segment 的文件集由调用方（各 skill）决定：`capture_snapshot(..., segment_files={"profile": [...], "rules": [...]})`。snapshot 只负责采集 + 比对 + 失效，不负责发现文件。git 段记录 base/head；diff 段指纹由调用方按需用 `harness_ledger.compute_diff_hash` 采集后填入 segment_files。
+
 ## archive 结构
 
 archive 后保持同样分层结构，不把 `.bak`、脚本、manifest、HTML 全部放在 archive 根目录。