@hunter-harness/workflow-harness 0.4.0 → 0.4.1

package/harness/bundles/general/pi/protocols/ledger-protocol.md

@@ -0,0 +1,365 @@
+---
+description: verification-ledger、diffHash、service-fingerprint 的统一协议。用于 run/test/submit/package/archive 之间复用验证结果。由原 harness-plan/verification-ledger.md 合并而来。
+---
+
+# Ledger Protocol
+
+> 本协议被 harness-plan / harness-run / harness-test / harness-submit / harness-archive 共同引用。
+> 目标：消除跨阶段重复编译/测试，让每个"✅ 已验证"结论可追溯、可复用，避免 post-test 小改动导致前序报告有效性表达不清。
+
+## 一、为什么需要 verification-ledger
+
+实践教训：
+
+- run 跑过测试命令（如 `mvn test`/`pytest`），test 阶段又原样跑一遍——浪费 3~8 分钟
+- submit/package 各自再 compile+test 一次——同一 diff 被验证三四轮
+- test 通过后用户改了一行注释/删了一个未用 import，package 不知道该不该重测，干脆全量重跑
+- 阶段汇总只展示全绿时，看不出哪些是「重新执行」、哪些是「复用」、哪些是「小改动后复用」
+
+verification-ledger 把每次验证（compile / unit test / api test / package）的**结果 + 证据 + 作用范围 + diffHash** 记下来，后续阶段先读 ledger 再决定是否重跑。
+
+## 二、账本文件位置
+
+```text
+<resolved-change-state>/evidence/verification-ledger.json
+```
+
+> `<resolved-change-state>` 必须由共享状态目录解析器取得：split-v1 通常位于 `.harness/state/changes/<change-name>`，旧布局仍位于 `.harness/changes/<change-name>`。根目录旧文件 `verification-ledger.json` 只兼容读取，详见 `state-layout-protocol.md`；新版本统一写入 `evidence/`。
+
+- 不提交到 git（已在 `.harness/` 屏蔽范围内）
+- 每次验证执行后**立即写回**（不得等所有阶段结束才补）
+- 后续阶段执行验证前**必须先读取** ledger
+
+## 三、账本结构
+
+解析后的变更状态目录中，`evidence/verification-ledger.json` 必须至少包含：
+
+```json
+{
+  "changeName": "indicator-permission-fix",
+  "projectRoot": "C:/CQ_PROJECT/贡献积分管理系统/udp",
+  "worktreeRoot": "... 或 null",
+  "stateDir": ".harness/changes/<change>",
+  "currentHead": "<git rev-parse HEAD>",
+  "baseCommit": "<merge-base 或计划起点>",
+  "diffHash": "sha256:<diff 内容指纹>",
+  "module": "<module-from-build-profile>",
+  "profile": "local-dev",
+  "postTestClassification": "NON_BEHAVIORAL_CLEANUP",
+  "ledgerReusable": true,
+  "scope": "module",
+  "validations": {
+    "compile": {
+      "status": "OK",
+      "command": "<构建命令（按技术栈：Java=mvn compile -pl <module> -o -q；前端=npm --prefix <module> run build；Python=pytest <module>）>",
+      "scope": "module",
+      "evidence": "<构建成功证据（Java=BUILD SUCCESS；前端/Python 按各自工具成功标志）>",
+      "startedAt": "2026-06-22T10:00:00+08:00",
+      "finishedAt": "2026-06-22T10:01:30+08:00",
+      "durationMs": 90000
+    },
+    "unitTest": {
+      "status": "OK",
+      "command": "<测试命令（按技术栈：Java=mvn test -pl <module> -o；前端=npm test --prefix <module>；Python=pytest <module>）>",
+      "scope": "module",
+      "testsRun": 14,
+      "failures": 0,
+      "errors": 0,
+      "skipped": 0,
+      "evidence": "<测试通过证据（Java=Tests run: 14, Failures: 0, Errors: 0, Skipped: 0；前端/Python 按各自工具成功标志）>",
+      "metrics": {"run": 14, "failures": 0, "errors": 0, "skipped": 0},
+      "startedAt": "2026-06-22T10:02:00+08:00",
+      "finishedAt": "2026-06-22T10:05:00+08:00",
+      "durationMs": 180000
+    },
+    "apiTest": {
+      "status": "OK",
+      "runner": "playwright-api-runner",
+      "scenariosTotal": 21,
+      "passed": 21,
+      "failed": 0,
+      "skipped": 0,
+      "evidence": "api-test-results.json summary",
+      "resultsFile": ".harness/changes/<change-name>/runtime/api-test-results.json",
+      "startedAt": "2026-06-22T10:06:00+08:00",
+      "finishedAt": "2026-06-22T10:08:00+08:00",
+      "durationMs": 120000
+    },
+    "package": {
+      "status": "OK",
+      "command": "<打包命令（按技术栈：Java=mvn clean package -pl <module> -am -DskipTests；前端=npm run build；Python=python -m build）>",
+      "baseCommit": "<final pushed hash>",
+      "deployArtifact": "<构建产物路径（Java=<module>/target/<artifact>.jar；前端=<module>/dist/；Python=<module>/dist/）>",
+      "sha256": "<artifact sha256>",
+      "testsExecuted": false,
+      "testsReusedFrom": "unitTest+apiTest",
+      "evidence": "<构建成功证据> + Glob 扫描确认构建产物存在",
+      "startedAt": "2026-06-22T10:30:00+08:00",
+      "finishedAt": "2026-06-22T10:35:00+08:00",
+      "durationMs": 300000
+    }
+  }
+}
+```
+
+缺少 `diffHash/currentHead/baseCommit/module/profile` 时，后续 skill 不得复用该 ledger，只能作为参考报告。
+
+字段说明：
+
+| 字段 | 含义 |
+|------|------|
+| `diffHash` | 本变更集相对 `baseCommit` 的全部内容变更 sha256 = `git diff baseCommit..HEAD`（已提交）+ `git diff`（未提交 tracked）+ 未跟踪新文件内容的合并指纹；**commit-invariant**（未提交 diff 转为已提交 diff，指纹不变），保证 run→test 跨 checkpoint commit 可复用 |
+| `currentHead` | 验证执行时的 HEAD commit hash |
+| `baseCommit` | merge-base 或计划起点（package 项另有 `baseCommit` 指 final pushed hash） |
+| `projectRoot` / `worktreeRoot` | 项目根与 worktree 根（无 worktree 时 `worktreeRoot=null`） |
+| `stateDir` | `.harness/changes/<change>`，避免手拼路径 |
+| `scope` | 验证范围：`module` / `module-am` / `full`，越严格越容易复用 |
+| `evidence` | 必须是命令实际输出的关键证据串，不得为空 |
+| `postTestClassification` | test 之后若发生代码变更，标注变更类型（见第六章） |
+| `ledgerReusable` | 布尔型，当前 ledger 是否可被后续阶段复用；由 postTestClassification（非行为性）+ diffHash 比对一致 + module/profile/scope 一致共同决定；缺关键字段时为 false，后续阶段不得复用 |
+| `scope`（顶层） | 顶层 scope 取 validations 中最宽 scope，作为复用判定的整体范围；条目级 scope 见各 validation |
+| `package.testsExecuted` | package 本次是否真实跑了测试；为 false 时 `testsReusedFrom` 必须指明复用来源 |
+
+## 四、复用判定规则
+
+后续阶段执行验证前先读 ledger。**同时满足以下全部条件**才可复用已有验证结果，否则必须重新执行：
+
+1. `diffHash` 与当前 diff 一致
+2. `currentHead` 或 merge-base 未发生影响当前 diff 的变化（HEAD 可前移，但本次变更文件未被他人提交触碰）
+3. `module` 一致
+4. `profile` 一致
+5. ledger 中该项 `command` 的 `scope` 一致或更严格（当前阶段范围 ⊆ ledger 范围）
+6. 前一次验证结果 `status=OK` 且 `evidence` 非空
+7. 前一次验证后**没有行为性代码变更**（见第六章分类；只有 NON_BEHAVIORAL_CLEANUP / COMMENT_ONLY / TEST_ONLY 才算"无行为性变更"）
+
+**禁止复用的高风险场景**（即使 diffHash 相同也必须重跑）：
+
+- post-test 修改属于 BEHAVIORAL_SERVICE_CHANGE / API_CONTRACT_CHANGE / SQL_OR_MAPPER_CHANGE / SECURITY_OR_PERMISSION_CHANGE
+- 远端 pull/rebase 引入了新提交
+- 用户显式要求 `submit-full-verify` / `package-with-tests`
+- ledger 缺失、损坏或 `evidence` 为空
+
+### 4.1 service-fingerprint（API 测试服务复用）
+
+接口测试复用已有服务前，读取：
+
+```text
+.harness/changes/<change>/runtime/service-session.json
+```
+
+字段（由 `harness_service.py ensure` 写入）：
+
+```json
+{
+  "pid": 0,
+  "startedBy": "AI / User",
+  "moduleInputsHash": "sha256:<依赖闭包内容指纹>",
+  "moduleInputsFiles": ["<project>/Svc.java", "..."],
+  "profile": "local-dev-remote-sdk",
+  "overlayPath": "C:/temp/harness-test-overlay/<change>/application-harness-test.yml",
+  "startCommandHash": "sha256:<command 指纹>",
+  "command": "<serviceStart.command>",
+  "startedAt": "..."
+}
+```
+
+`moduleInputsHash` 由 CLI `--files` ∪ `build-profile.json` 的 `serviceStart.inputFiles`（glob 列表，相对 project 展开）计算。**空输入被拒绝**（exit 非 0），不得生成可复用的空指纹（§5.1/§5.2）。
+
+复用必须**同时**满足（§5.3）：`moduleInputsHash` 一致、`startCommandHash` 一致、`profile` 一致、`overlayPath` 一致、进程身份（pid 存活 + create time 匹配 `startedAt`）可确认。任一变化 -> AI 自动 restart；身份无法确认 -> `needs-user-decision`；非 AI 用户进程永不自动 kill。否则必须进入 Service Decision Gate（见 harness-test）。
+
+### 4.2 unitTestFull 最终全量门禁
+
+`unitTestFull` 是 submit 前的**模块级全量单元测试**门禁，与增量 `unitTest` 严格区分，二者键独立、不可互冒充：
+
+| verification | 合法 scope | 复用规则 |
+|---|---|---|
+| `unitTest` | 测试类列表或 `module`/`module-am`/`full` | 可覆盖请求的受影响测试类 |
+| `unitTestFull` | 只能是 `module` / `module-am` / `full`（broad scope） | 只允许复用已有 `unitTestFull`；增量 `unitTest` 结果不能复用 |
+
+`unitTestFull` 复用必须**同时**满足：ledger 存在 `validations.unitTestFull`、`status=OK`、`scope ∈ broad scopes`、`evidence` 非空、`command` 非空（调用方传 `--command` 时须完全一致）、`inputsHash` 与当前文件集一致、`inputsFiles` 为非空 list。任一不满足（含 scope 为测试类名等增量范围）→ `insufficient-evidence`，执行全量测试但不允许缓存复用。
+
+**依赖闭包必须由 profile 展开**，最终门禁禁止用仅含 staged 文件的 `--files` 快捷方式冒充全量闭包：
+
+```text
+harness_ledger.py can-reuse --verification unitTestFull --scope module \
+  --project . --profile-input unitTestFull \
+  --command "<resolved build-profile.json commands.unitTestFull.command>" --json
+```
+
+`build-profile.json` 新增 `verificationInputs.unitTestFull`（glob 列表，相对 project 展开，只保留 project 内文件、去重排序）：
+
+```json
+{
+  "verificationInputs": {
+    "unitTestFull": ["pom.xml", "module/pom.xml", "module/src/main/**", "module/src/test/**"]
+  }
+}
+```
+
+profile key 缺失 / glob 无匹配 / 结果为空 → `insufficient-evidence`（exit 0），仍须执行全量测试但不允许缓存复用，直到 profile 被正确配置。`harness_preflight.py detect` 对单模块 Java 项目写入根级默认闭包 `["pom.xml", "src/main/**", "src/test/**"]`；多模块项目需手工改为 module 专属 glob，detect 不会覆盖用户已配置的 `verificationInputs`。
+
+## 五、真实 diffHash
+
+必须基于真实内容变更集计算 SHA-256，且**必须是 commit-invariant 的**——覆盖本变更集相对 `baseCommit` 的 tracked 变化、标准 untracked 文件，以及 `test-tracking.json` 明确记录的 ignored tests，使 checkpoint commit 前后指纹一致，保证 run→test→submit 复用链不断。
+
+`<baseCommit>` 从 ledger 读取（harness-plan 阶段写入）；缺失时用 `git merge-base HEAD <默认分支>` 兜底。
+
+**canonical 命令（cluster 2 起脚本化，推荐）**：
+
+```text
+harness_ledger.py diff-hash --repo <projectRoot> --base <baseCommit> --change-dir ".harness/changes/<change-name>" --json
+```
+
+`diff-hash` 用 subprocess 直接捕获 Git bytes，按 repo-relative path 排序并进行长度 framing（`path-len | path | exists | content-len | content`），独立于 shell/控制台编码/BOM/系统换行。算法版本 `content-changeset-2`，输出 `diffHash`/`algorithmVersion`/`fileCount`/`base`/`head`/`trackedTestFileCount`/`testTrackingManifest`。
+
+- `--change-dir` 可选以兼容普通调用；run/test/submit 对正式 change 必须传入。manifest 不存在时贡献 0 个额外路径。
+- manifest 存在时必须严格验证 schema/mode/projectRoot、精确相对路径、文件存在性与 SHA-256；结构非法、路径越界或 hash 漂移均非零退出，旧 ledger 不得复用。
+- ignored test 在 checkpoint 前由 manifest 加入内容集；经 guard force-stage/commit 后由 Git diff 加入同一路径，集合去重，因此 hash 保持不变。
+- diffHash 只用于"内容是否变化"判断，不等于 commit hash
+- 账本中 `currentHead`（验证时 HEAD）与 `diffHash` 分开记录；reuse 规则 #2 允许 HEAD 前移（如 harness-run Step 5 checkpoint commit），因 diffHash 已 commit-invariant，HEAD 前移不改变指纹
+- **禁止**使用类似 `3files-84plus-5minus` 的描述性字符串作为复用依据
+- **禁止**删除/忽略 test-tracking manifest 后继续复用，也禁止用手写 Git/Node/PowerShell hash 替代 canonical 命令。
+
+## 六、Post-test 变更分类
+
+当 `/harness-test` 完成后又发生代码变更（常见于 review 后清理、submit 前发现的小问题），后续 submit/package/archive **必须先对变更做分类**，写入 ledger 的 `postTestClassification`：
+
+| 类型 | 示例 | 是否需要重跑 API | 是否需要重跑 unit | 是否需要重 compile |
+|------|------|:---:|:---:|:---:|
+| `NON_BEHAVIORAL_CLEANUP` | 删除未使用 import、删除未使用字段、格式化 | 否 | 否 | 是（轻量） |
+| `COMMENT_ONLY` | 注释调整、Javadoc 补充 | 否 | 否 | 否 |
+| `TEST_ONLY` | 只改测试文件 | 否，但需重跑对应测试 | 是（对应测试） | 否 |
+| `BEHAVIORAL_SERVICE_CHANGE` | service 逻辑变化 | 是 | 是 | 是 |
+| `API_CONTRACT_CHANGE` | controller / VO / DTO 变化 | 是 | 是 | 是 |
+| `SQL_OR_MAPPER_CHANGE` | 数据访问层 / sql / 映射文件变化 | 是 | 是 | 是 |
+| `SECURITY_OR_PERMISSION_CHANGE` | 权限 / 组织过滤 / 认证变化 | 是 | 是 | 是 |
+
+分类方法：对 post-test diff 逐文件判断，按"最严格类型"汇总——只要有一个文件属于行为性变更，整体即视为行为性变更。
+
+**NON_BEHAVIORAL_CLEANUP 复用记录格式**（写入对应阶段报告）：
+
+```md
+post-test 变更: NON_BEHAVIORAL_CLEANUP
+影响: 不影响运行时行为
+追加验证: compile + unit test passed（如确实重跑了 compile/unit）
+API 测试: 🔁 复用上一轮结果（diffHash 未变 / 仅清理性变更）
+```
+
+**行为性变更**：必须重新运行 `/harness-test` 的相关场景（至少覆盖变更影响的接口/权限/SQL），ledger 对应项作废并重写。
+
+## 七、各阶段与 ledger 的交互
+
+| 阶段 | 读 ledger | 写 ledger |
+|------|:---:|:---:|
+| harness-plan | 计划起点读（了解前序变更状态/已有 ledger，作为复用链起点） | 计划落定后写初始 ledger（changeName/module/profile/baseCommit/diffHash 占位） |
+| harness-run | 步骤 2 前读（确认是否已有 compile/unitTest 可复用） | 步骤 2 后写 compile + unitTest（若跑了全量测试） |
+| harness-test | Phase 1 前读（复用 run 的 unitTest） | Phase 1/2 后写 unitTest + apiTest |
+| harness-submit | 验证前读（复用 test 的 compile/unitTest） | 若重跑则写回 |
+| harness-archive | 归档前读（汇总各阶段状态，写入 `summary-data.json` 并上传平台） | 不写（归档时一并移入 archive） |
+
+## 八、状态与归档投影的对应
+
+ledger 的 `status` 与 `summary-data.json`、平台监控中的展示状态对应：
+
+| ledger status | 含义 | 归档与平台标记 |
+|:---:|------|------|
+| `OK`（本阶段真实执行并通过） | 真实验证 | ✅OK |
+| `OK` 但本阶段复用了前一阶段 | 复用 | 🔁REUSED |
+| `OK` 但 post-test 后重测通过 | 重测 | 🔁RETESTED |
+| `WARN` | 静态验证 / 跳过 / 降级 | 🟡WARN |
+| `ADVISORY` | review 参考性 | 📝ADVISORY |
+| postTestClassification=NON_BEHAVIORAL_CLEANUP | 小清理 | 🧹NON_BEHAVIORAL_CLEANUP |
+
+**强制规则**：任何阶段若复用了前一阶段结果，`summary-data.json` 与平台监控必须显示 `🔁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） |
+| `metrics` | 可选；`record --metrics-json '{"run":155,"failures":0,...}'` 写入结构化计数（不参与 inputsHash）。archive 读取顺序：`metrics` → evidence dict → evidence 文本正则 → `runtime/api-test-results.json` |
+
+### 9.2 coverage lattice
+
+`COVERAGE_RANK = {incremental:0, module:1, module-am:2, full:3}`。各 verification 最低要求：`unitTest`=0、`unitTestFull`/`compile`/`apiTest`/`browserTest`=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 一次性失效，不危险复用。
+
+## 十、Ledger v3（contract-gated，2026-07 起）
+
+v3 仅在 change contract 为 schemaVersion ≥ 2（或声明 `stateOwnership.runtimeRoot`，即 split-v1 布局）时启用；legacy v1 契约与无契约目录**行为完全不变**（零回归，旧 362 测试套件证明）。
+
+### 10.1 强制顶层身份
+
+v2 契约下 `record` 写入前强制解析并校验顶层身份字段，缺失且不可解析时**非零退出、不写账本**：
+
+| 字段 | 解析顺序 |
+|------|------|
+| `schemaVersion` | 固定 `3` |
+| `repositoryId` | `harness_paths.repository_identity(repo_root)`（远端规范化 + root commit；无远端回退 git common-dir，跨 worktree 稳定，RET-09） |
+| `changeName` | change 目录名 |
+| `baseCommit` | `--base-commit` → 既有 ledger 值 → `state-snapshot.json.changeBase`。只有全新 change 的首次 ledger 写入可以用当时 HEAD 建立基线；旧 ledger 迁移缺少以上三种证据时必须报错，禁止用迁移时的当前 HEAD 猜测基线 |
+| `currentHead` | `git rev-parse --verify HEAD`（验证执行时） |
+| `diffHash` | `--diff-hash` → 既有 ledger 值 → 按 ownership 范围重算（§10.3） |
+| `ownershipHash` | 契约 `ownership` 段规范化 JSON 的 sha256 |
+
+### 10.2 类型化 metrics 与 applicability
+
+- v2 契约下 `--metrics-json` 必须通过 `validate_metrics` 类型校验：`unitTest`/`unitTestFull` 要求 `total/passed/failed`；`apiTest` 要求 `total/passed/failed`；`browserTest`（报告投影名 `browserE2E`）要求 `total/passed/failed`；`apiContract` 要求 `scenariosTotal/passed/failed`；`dbCompatibility` 要求 `applicability ∈ APPLICABLE|NOT_APPLICABLE`，`NOT_APPLICABLE` 必须带 `reason`（UT-005/RET-15、UT-006/RET-16）。未知 verification 类型放行。
+- `--applicability APPLICABLE|NOT_APPLICABLE` + `--applicability-reason` 写入 entry 级 applicability；`NOT_APPLICABLE` 无 reason 直接报错。applicability **既不计入通过也不计入失败**（UT-012/RET-24）。
+- legacy 契约不校验 metrics 形状（旧的 `{"run","failures"}` 松散格式继续可用）。
+
+### 10.3 ownership 范围 diffHash（RET-18）
+
+`compute_ownership_diff(repo_root, base, change_dir)` 只对本变更 ownership 范围内的路径计算 diffHash：
+
+- 排除 `.harness/state/**` 动态运行时证据（计入 `excludedRuntimeCount`）
+- 他变更路径（`.harness/changes/<other>/`、`.harness/state/changes/<other>/`）单列 `foreignPaths`，不混入哈希
+- 输出 `diffHash/files/foreignPaths/excludedRuntimeCount/ownedFileCount/ownershipHash`
+
+### 10.4 原子写入
+
+`write_ledger` 采用 tmp → fsync → `os.replace`；replace 失败时旧账本字节不变、不留 `.tmp` 残骸。所有写路径（record / 其他命令）统一走原子写。
+
+### 10.5 写前透明迁移
+
+Reader 继续读取当前 v3 与前一支持窗口 v2（并保守识别无 schema 的 v1）。已有 schemaVersion 2 ledger，或显式携带 identity 参数的 legacy ledger，再次 `record` 时必须先完成身份迁移再修改任何 evidence；无 schema 且未显式请求 identity 的旧调用继续保持兼容行为：
+
+- 解析 repository/change/base/current/diff/ownership identity，目标固定为 schemaVersion 3；
+- 对 `validations`、`verificationTargets`、`integration`、`artifacts` 生成迁移前 evidence identity；
+- 迁移只增加 schema/identity 元数据，迁移后 evidence identity 必须完全相同；
+- 把 receipt 原子嵌入 `migrationHistory[]`，记录 original/target schema、before/after identity 与 `receiptId`；
+- 版本超出支持窗口、仓库/ownership/diff 无法确认、或 evidence identity 漂移时不写文件，返回 `LEDGER_MIGRATION_REQUIRED` 与参数数组形式的 `rerecordCommand`。
+
+submit/review/test/archive 只能通过 `harness_ledger.py` 读取/写入，禁止各自实现 schema 猜测或手工改 ledger。

package/harness/bundles/general/pi/protocols/memory-closeout-protocol.md

@@ -0,0 +1,21 @@
+# 项目与全局记忆收尾协议
+
+Workflow 的 canonical state 永远是项目 Git 中的配置/文档和 `.harness` 的本地收据；聊天记录与跨项目记忆只能辅助发现，不能代替 gate、identity 或完成状态。
+
+## 分层写入
+
+- 项目事实、命令、发布清单和长期约束写入项目真源；
+- 当前运行状态、尝试和证据写入 `.harness`；
+- 只有可跨项目复用、已经验证且不含 secret 的经验才写入全局记忆。
+
+## Closeout 字段
+
+每条全局记忆至少记录来源项目、来源提交/收据、`agent_id`、写入时间、置信度、TTL 或复核条件。新结论替代旧结论时显式记录 `supersede` 关系，不直接覆盖而失去历史。
+
+## 禁止项
+
+- 不写入凭据、token、生产数据或个人隐私；
+- 不写入未经验证的临时诊断；
+- 不把“上次成功”当成当前环境事实；
+- 不因 closeout 失败改写已经产生的产品或发布结论；
+- 只检查不落库时使用 dry-run，成功写入后提交本轮实际修改的记忆文件。

package/harness/bundles/general/pi/protocols/model-routing-protocol.md

@@ -0,0 +1,22 @@
+# model-routing-protocol — 能力级模型路由（Wave-2 H-16）
+
+> 本协议定义 **economy / balanced / frontier** 三档能力级。通用 Harness 规则与 skill **禁止**硬编码供应商模型名（如 `claude-*`、`gpt-*`、`gemini-*`）。宿主把能力级映射到具体模型；映射表属于项目/宿主配置，不属于本协议正文。
+
+## 能力级
+
+| 级别 | 适用任务 | 示例 |
+|------|----------|------|
+| `economy` | 机械提取、日志压缩、等待监控、格式化摘要 | 解析测试输出行、压缩长日志、轮询服务就绪 |
+| `balanced` | 常规实现、常规修复、常规文档修订 | 按 plan 实现 CRUD、修 YELLOW、补 checklist |
+| `frontier` | 架构取舍、安全/并发/迁移、最终审查、高风险判断 | 设计审批、RED 安全项、schema 迁移方案、merge 前终审 |
+
+## 路由规则
+
+1. Skill/任务描述用能力级（`--capability economy|balanced|frontier` 或文案「本任务=frontier」），不写供应商模型 id。  
+2. 宿主或 `HUNTER_HARNESS_MODEL` 仅作**遥测**（`executor_model`），不得反过来驱动通用规则分支。  
+3. **降级**（frontier→balanced→economy）必须由确定性命令结果或更高能力审查验收；不得用更低能力级的模型输出替代测试/门禁证据。  
+4. 无法映射某能力级时：fail closed，列出可用级别，禁止静默落到未知模型。
+
+## 与验证的关系
+
+能力级不改变 ledger / can-reuse / verification graph 合同。模型便宜不能成为跳过 `unitTestFull` 或忽略 `requiredOnMerge` 的理由。

package/harness/bundles/general/pi/protocols/powershell-protocol.md

@@ -0,0 +1,238 @@
+---
+description: harness 全流程的 Windows/中文路径命令执行协议。所有 skill 在需要 git/构建命令/node/文件系统命令时按本协议执行。由原 harness-plan/shell-safety.md 合并而来。
+---
+
+# PowerShell Protocol
+
+> 本协议适用于所有 harness-skills（sync/codebase-map/plan/run/test/review/submit/archive）。Windows 中文路径项目中，Bash 工具会被 hook 拒绝（返回 `Denied: non-ASCII path in Bash`），且 Bash 在中文路径下经常超时。统一通过 `powershell.exe -NoProfile -Command "..."` 执行，规避路径编码问题。
+
+## 1. PowerShell-first 自动重试策略
+
+Claude **必须默认使用 PowerShell** 执行 git/构建命令/系统命令，不应先尝试普通 Bash。
+
+正确策略：
+
+1. **优先直接使用 PowerShell**：`powershell.exe -NoProfile -Command "<命令>"`
+2. 如果 Claude 意外使用了普通 Bash，并出现以下任一输出：
+   - `PreToolUse:Bash hook error`
+   - `Denied: non-ASCII path in Bash`
+   - `Use Write/Edit/PowerShell instead`
+3. **必须立即自动改用等价 PowerShell 命令重试一次**——不得中断流程，也不得推断成功
+4. 只有 PowerShell 重试也失败、被拒绝、超时、无有效输出、或 exit code 非 0，才停止当前阶段
+5. 停止时不得宣称成功，必须标记为 ❌FAIL 或 🟡WARN(状态未知)
+
+```
+❌ 错误：先尝试普通 Bash，被拒绝后中断流程并宣称"工作区干净"
+git status --porcelain  → 被拒 → 输出"工作区干净" ← 禁止
+
+✅ 正确：直接使用 PowerShell，或被拒后自动重试
+powershell.exe -NoProfile -Command "git -C '<项目路径>' status --porcelain"
+```
+
+只有 PowerShell 命令也失败时，才停止当前阶段并请求用户介入。
+
+## 2. 统一模板
+
+```powershell
+powershell.exe -NoProfile -Command "<command>"
+```
+
+复杂命令优先写成临时 `.ps1`，再执行：
+
+```powershell
+powershell.exe -NoProfile -ExecutionPolicy Bypass -File ".harness/changes/<change>/runtime/<script>.ps1"
+```
+
+## 3. 禁止普通 Bash
+
+如果当前路径包含中文、空格、非 ASCII 字符，或项目位于 Windows 路径（如 `C:\...`），**禁止使用普通 Bash 执行以下命令**：
+
+- `git`（任何子命令：log、diff、status、stash、pull、push、commit、add、worktree 等）
+- 构建命令（按技术栈：`mvn` compile/test/package、`npm` run build/test、`pytest` 等子命令）
+- `node`、`curl`
+- `mkdir`、`cp`、`mv`、`rm`、`touch`、`cat`、`sed`、`awk`（文件操作）
+- `find`、`ls`、`grep`（文件搜索）
+
+禁止 Bash here-doc、Bash command substitution、Bash 管道作为默认执行方式。
+禁止因 Bash 中没有 node/构建命令/git 就降级执行器；应改用 PowerShell 绝对路径。
+
+## 4. 优先使用内置工具
+
+文件读写、移动前验证、扫描**优先使用 Claude Code 内置工具**：
+
+| 操作 | 内置工具 | 替代 Bash 命令 |
+|------|----------|----------------|
+| 读取文件 | `Read` | `cat` |
+| 编辑文件 | `Edit` | `sed` |
+| 写入文件 | `Write` | `echo >` / `touch` |
+| 搜索文件 | `Glob` | `find` / `ls` |
+| 搜索内容 | `Grep` | `grep` |
+| 创建目录 | `Write`（写入目标文件时自动创建） | `mkdir -p` |
+| 移动文件 | `Read` + `Write` + 验证 | `mv` / `cp` |
+
+## 5. Git/构建命令 通过 PowerShell 执行
+
+所有 git/构建命令必须通过 `Bash(powershell.exe:*)` 调用 PowerShell 执行：
+
+```powershell
+# Git 命令示例
+powershell.exe -NoProfile -Command "git -C 'C:\CQ_PROJECT\贡献积分管理系统\udp' status"
+powershell.exe -NoProfile -Command "git -C 'C:\CQ_PROJECT\贡献积分管理系统\udp' diff --name-only"
+powershell.exe -NoProfile -Command "git -C 'C:\CQ_PROJECT\贡献积分管理系统\udp' log --oneline -10"
+
+# 构建命令示例（按技术栈；Java=mvn，前端=npm，Python=pytest）
+powershell.exe -NoProfile -Command "mvn compile -pl <module> -o -q"
+powershell.exe -NoProfile -Command "npm --prefix <module> run build"
+powershell.exe -NoProfile -Command "pytest <module>"
+```
+
+> **路径引用**：PowerShell 中路径必须用单引号或双引号包裹，避免中文路径解析错误。使用 `git -C "<路径>"` 指定项目目录。
+
+## 6. PowerShell 调用被拒绝时的处理
+
+如果 `powershell.exe` 或 `pwsh` 调用被 hook 拒绝，或返回无有效输出：
+
+- **必须停止当前阶段**，标记为 ❌FAIL 或 🟡WARN，不得宣称成功
+- **不得回退到普通 Bash**——这是硬性约束，不是建议
+- **不得在 PowerShell 重试失败后继续流程**——必须请求用户介入
+- 提示格式：`"Shell 命令执行失败：powershell.exe 调用被拒绝或无有效输出。请在终端手动执行：<命令>，完成后告诉我继续。"`
+
+## 7. 失败判定
+
+出现以下任一情况，当前阶段至少 `🟡WARN`，影响关键门禁时必须 `❌FAIL`：
+
+- `PreToolUse:Bash hook error` — **必须立即改用 PowerShell 等价命令重试**
+- `Denied: non-ASCII path in Bash` — **必须立即改用 PowerShell 等价命令重试**
+- `Denied: non-ASCII path in Bash. Use Write/Edit/PowerShell instead.` — **必须立即改用 PowerShell 等价命令重试**
+- `安全分类器暂时不可用` 且命令不可执行
+- PowerShell 重试后仍出现上述标志 → ❌FAIL，停止当前阶段
+- 非 0 exit code → ❌FAIL
+- 无有效 stdout → ❌FAIL（空输出 ≠ 无提交，先怀疑工具问题）
+- `internal error` / `timeout` / `Tool result missing` → ❌FAIL
+
+普通 Bash 被拒绝 = 必须 PowerShell 重试，不是成功，也不是最终失败。
+PowerShell 重试失败 = 当前阶段失败或未知，必须停止。
+
+## 8. 证据化成功结论
+
+所有"成功"结论必须绑定**明确证据**：
+
+| 结论 | 必须的证据 |
+|------|-----------|
+| 编译成功 | 构建工具输出包含构建成功证据（Java=`BUILD SUCCESS`；前端/Python 按各自工具成功标志） |
+| 拉取成功 | git 输出包含 `Already up to date.` 或实际 pull/push/commit 成功信息 |
+| 打包成功 | 构建产物通过 Glob 扫描产物目录实际确认存在（Java=`target/*.jar`；前端=`dist/`；Python=`dist/`） |
+| 推送成功 | git push 输出包含 `To <remote>` 和实际推送范围 |
+| 测试通过 | 测试命令输出包含测试通过证据（Java=`Tests run: N, Failures: 0`；前端/Python 按各自工具成功标志） |
+| exit code 0 | 命令返回 exit code 0 |
+
+> 构建工具的 quiet 模式（如 `mvn -q`）只能写 `exitCode=0，无错误输出`，不得把"无输出"改写成 `BUILD SUCCESS`。
+
+**没有证据 = 不成功。** 如果命令被拒绝、超时、或输出不含成功标志，必须标注"未知"或"失败"，不得推断成功。
+
+## 9. allowed-tools 配置规则
+
+Claude Code 不支持 `PowerShell(...)` 过滤语法，且 `allowed-tools` 不是严格白名单而是免确认通道。所有 skill 的 `allowed-tools` 使用以下策略实现 PowerShell-first：
+
+- **需要执行 git/构建命令的 skill**：`allowed-tools` 含 `Bash(powershell.exe:*)`（免确认通道），`disallowed-tools` 禁 `Bash(git *)`、`Bash(mvn *)`/`Bash(npm *)`/`Bash(pytest *)` 等裸命令（激活期间硬限制）
+- **不需要执行 git/构建命令的 skill**：不包含任何 Bash 工具
+- **codegraph 命令**：改为 MCP 工具调用（`mcp__codegraph__codegraph_*`），不再通过 Bash 调用
+- 不禁止 `Bash(powershell.exe:*)`——这是 PowerShell 调用的免确认通道
+- 所有 skill 正文中明确：Windows 或中文路径下，所有 git/构建命令/文件移动命令必须通过 `powershell.exe -NoProfile -Command "..."` 执行
+
+> 真正的强安全边界应结合 `permissions.deny`、`hooks`、`sandbox`；`allowed-tools`/`disallowed-tools` 只做激活期间预批准/限制。
+
+## 10. 各 skill 命令示例统一格式
+
+所有 skill 中的命令示例统一用 PowerShell 格式：
+
+```powershell
+# ❌ 旧格式（会被 hook 拒绝）
+git stash
+git pull origin master
+<构建命令> <模块定位参数>  # 例：mvn compile -pl <module> -o -q / npm --prefix <module> run build
+
+# ✅ 新格式（通过 PowerShell 执行）
+powershell.exe -NoProfile -Command "git -C '<项目路径>' stash"
+powershell.exe -NoProfile -Command "git -C '<项目路径>' pull origin <upstream-branch>"
+powershell.exe -NoProfile -Command "<构建命令> <模块定位参数>"  # 例：mvn compile -pl <module> -o -q
+```
+
+> 注意：构建命令（如 mvn）在 PowerShell 中通常不需要特殊处理（不含中文路径参数时可以直接执行），但为保持一致性，仍建议通过 powershell.exe 执行。
+
+## 11. 复杂 PowerShell 命令必须脚本化
+
+简单命令可以使用 `powershell.exe -NoProfile -Command "..."`。
+
+但如果命令包含以下内容，不得内联到 `-Command`：
+
+- `$variable`、`$_`、`$PSVersionTable` 等变量；
+- `@{}` hashtable；
+- `ForEach-Object` / `Where-Object` / script block `{ ... }`；
+- here-string；
+- 多管道和 JSON/HTML 大文本拼接。
+
+必须写入 `.harness/changes/<change>/scripts/*.ps1` 后使用：
+
+```powershell
+powershell.exe -NoProfile -ExecutionPolicy Bypass -File ".harness/changes/<change>/scripts/<name>.ps1"
+```
+
+原因：Claude Code 的 Bash 工具外壳会先处理双引号内容，`$log`、`$_` 这类变量可能被外层 shell 吃掉，导致命令变形。简单命令可以 inline；复杂命令必须 `-File`。
+
+
+## 12. PowerShell 5.1 兼容清单
+
+Windows 默认常为 Windows PowerShell **5.1**。下列特性在 5.1 不可用，禁止写进可复制命令模板：
+
+| 特性 | 最低版本 | PowerShell 5.1 替代 |
+|------|---------|--------------------|
+| `Invoke-WebRequest -SkipHttpErrorCheck` | 7.0 | `try/catch` 包裹或 `$ErrorActionPreference` 处理非 2xx |
+| `Join-String` | 6.2 | `-join` 运算符 |
+| `ForEach-Object -Parallel` | 7.0 | 顺序执行 |
+
+### 非 ASCII 路径与 Bash 拒绝后的切换
+
+- 非 ASCII 路径（含中文）仓库：git/构建/文件操作一律 PowerShell；Bash 被 hook 拒绝（如 `Denied: non-ASCII path`）后**立即**改用 PowerShell 重发等价命令，禁止原样重试 Bash。
+- Maven `-D` 参数在 PowerShell 中加引号：`"-Dmaven.test.skip=true"`。
+
+### 捕获子进程中文输出：`$env:PYTHONUTF8=1` 不够
+
+`PYTHONUTF8=1` 只让 **Python 按 UTF-8 输出**，不改变 **PowerShell 按什么编码读**。
+控制台代码页是 GBK(936) 时，PowerShell 会用 GBK 解码 UTF-8 字节，得到形如
+`绫?javadoc 鏈�闅� 6 绾х簿绠€` 的乱码——内容已在捕获阶段损坏，落进报告、回执与
+JSON 字段后无法还原。
+
+调用任何会输出中文的子进程前，**必须同时设置输出编码**：
+
+```powershell
+[Console]::OutputEncoding = [Text.Encoding]::UTF8
+$env:PYTHONUTF8 = 1
+python harness/scripts/harness_fixback.py <子命令> --json
+```
+
+- 两行缺一不可：只设 `PYTHONUTF8` 会乱码，只设 `OutputEncoding` 则 Python 可能仍按本地编码输出。
+- 写脚本时把这两行放在脚本开头，不要依赖调用方记得加。
+- 少用 `2>&1` 合并流：PowerShell 5.1 会把 stderr 包装成 `NativeCommandError`，
+  与编码问题叠加后更难判断真实失败原因；需要 stderr 时分开捕获。
+
+## 13. PS5/PS7 原生参数合同
+
+复杂 JSON、Docker Go template、here-string 内容及多层引号不得作为 native process 的内联参数跨 `Bash → powershell -Command → native executable` 传递。统一写 UTF-8 JSON 参数文件：
+
+```json
+{
+  "schemaVersion": 1,
+  "transport": "utf8-json-argument-file",
+  "argv": ["python", "tool.py", "--template", "{{json .State}}"],
+  "powershell": {"edition": "Desktop", "version": "5.1"}
+}
+```
+
+执行入口：
+
+```powershell
+python harness/scripts/harness_test_runner.py exec --argv-file <file> --runtime-receipt <receipt>
+```
+
+Runner 直接把 `argv[]` 传给 native process（`shell=False`），不重新拼接或解析命令文本。PowerShell Desktop 5.1 与 Core 7 使用同一参数文件必须产生相同 argv。运行回执记录 edition/version、参数数量和 argv SHA-256，不写原始参数，避免凭证或模板内容泄漏。