@hunter-harness/workflow-harness 0.2.8 → 0.2.10

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

@@ -36,25 +36,24 @@ description: harness-submit 的8 步工作流详细步骤和执行日志记录
 
 > **分支名自动读取**：不硬编码 `master` 或 `main`，使用 `git rev-parse --abbrev-ref @{u}` 自动读取 upstream 分支。
 
+**正常路径禁止 `git stash` / `stash pop`**。远端同步不在业务工作区执行；主目录与 worktree 模式统一由合并段的 `harness_integration.py` transaction 在隔离 integration worktree 内 fetch + merge：
+
 ```powershell
-# 0. 自动读取 upstream
+# 0. 自动读取 upstream 与目标分支（只读操作）
 powershell.exe -Command "git -C '<项目路径>' rev-parse --abbrev-ref @{u}"
 
-# 1. 暂存当前变更
-powershell.exe -Command "git -C '<项目路径>' stash"
-
-# 2. 拉取并合并远程
-powershell.exe -Command "git -C '<项目路径>' pull --rebase"
+# 1. preflight：获取 integration lock + 写 journal/保护 ref
+python harness/scripts/harness_integration.py preflight --change <change-name> --run-id <run-id> --feature-branch <feature> --target-branch <target> --temp-root <task-temp>
 
-# 3. 恢复暂存的变更
-powershell.exe -Command "git -C '<项目路径>' stash pop"
+# 2. prepare：fetch + 从已提交 target 创建临时 integration worktree
+python harness/scripts/harness_integration.py prepare --change <change-name> --run-id <run-id> --feature-branch <feature> --target-branch <target> --temp-root <task-temp>
 ```
 
 **Shell 安全规则（强制）**：
 - 任何 git 命令被 hook 拒绝（`Denied` / `PreToolUse:Bash hook error`）→ 停止流程，不得宣称"拉取成功"
-- 拉取成功的判断证据：git 输出包含 `Already up to date.` 或 `Fast-forward`、`Updating <hash>..<hash>`，且 exit code 为 0
+- transaction 各步骤状态以 journal 为唯一事实源；FAILED 步骤用 `recover` 续跑，不重复已完成副作用
 
-如果 stash pop 冲突或 merge 冲突，参考 `reference.md` 的常见问题处理。
+merge 冲突或 `TARGET_MOVED` 时，参考 `reference.md` 的恢复清单；**禁止 `checkout --ours/--theirs`**。
 
 ## 步骤 2：最终验证（ledger 复用优先）
 
@@ -311,122 +310,87 @@ powershell.exe -Command "git -C '<项目路径>' rev-parse HEAD"
 
 ---
 
-## worktree 合并流程（步骤 M0–M8）
+## worktree 合并流程（integration transaction，M0–M7）
 
-> worktree 模式 commit 成功后自动执行；用户仅说「合并分支」/`/harness-merge` 且已有本地 commit 时从 M0 重入。合并方式固定 `--no-ff`；冲突 → 停下 → 用户手动解 → 确认后继续；**禁止 `checkout --theirs/--ours`**。
+> worktree 模式 commit 成功后自动执行；用户仅说「合并分支」/`/harness-merge` 且已有本地 commit 时从 M0 重入。合并由 `harness_integration.py` transaction 执行：隔离 integration worktree + journal + 保护 ref + 精确清理。**禁止 `checkout --theirs/--ours`；正常路径禁止仓库级 stash。**
 
 ### P0 合并稳定性门禁
 
 - 主分支名不硬编码，用 `git symbolic-ref --short refs/remotes/origin/HEAD` 读取
 - push 只在主分支；worktree 分支不 push
-- 所有 git 命令通过 `powershell.exe -Command "..."` 执行
+- 所有 git 命令通过 `powershell.exe -Command "..."` 执行（transaction 脚本内部 git 调用除外）
+- transaction 步骤状态以 `.harness/state/integration/<transaction-id>/journal.json` 为唯一事实源
 
 ### 步骤 M0：启动合并段
 
 append `phase.start`（`--phase merge`；`note` 含 worktree 分支、主分支、ledger diffHash、验证策略；重入时 note 标注「重入 merge」）。
 
-### 步骤 M1：切回主目录主分支
-
-```powershell
-powershell.exe -Command "git -C '<项目路径>' symbolic-ref --short refs/remotes/origin/HEAD"
-powershell.exe -Command "git -C '<项目路径>' stash"   # 主目录有未提交变更时
-powershell.exe -Command "git -C '<项目路径>' rev-parse --abbrev-ref HEAD"
-```
-
-不在主分支则 `git checkout <主分支>`。
-
-### 步骤 M2：fetch + 同步主分支
+### 步骤 M1：preflight
 
 ```powershell
-powershell.exe -Command "git -C '<项目路径>' fetch origin"
-powershell.exe -Command "git -C '<项目路径>' pull --rebase"
+python harness/scripts/harness_integration.py preflight --change <change-name> --run-id <run-id> --feature-branch worktree/<change-name> --target-branch <主分支> --temp-root <task-temp>
 ```
 
-pull 输出非 `Already up to date.` → 引入他人提交 → M4 必须重跑验证。
+获取 integration lock、解析 base/feature head、写 journal 与保护 refs（`refs/harness/integration/<txn>/base|head`）。锁被其他 run 持有 → **停止**，不改动工作区与状态文件。
 
-**CRLF 预检**（pull 后强制）：旧 working copy 的 `.gitattributes eol=lf` 文件可能是 CRLF（.gitattributes 后加未重新检出），曾导致 `core_content_hash` 跨工作树不一致 → sync 产生 dirty → M5 失败重跑。检测并修复：
+### 步骤 M2：prepare
 
 ```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"
+python harness/scripts/harness_integration.py prepare --change <change-name> --run-id <run-id> --feature-branch worktree/<change-name> --target-branch <主分支> --temp-root <task-temp>
 ```
 
-> cluster 1 的 `core_content_hash` 改用 git blob sha 后，CRLF 不再影响 core hash，但 working copy CRLF 仍可能影响 workflow-data 包内容 hash，预检仍有价值。
+fetch 后从**已提交** target 创建临时 integration worktree；primary 的 staged/unstaged/untracked/ignored 与 mtime 均不被触碰。
 
-### 步骤 M3：合并 worktree 分支
+### 步骤 M3：merge
 
 ```powershell
-powershell.exe -Command "git -C '<项目路径>' merge --no-ff worktree/<change-name>"
+python harness/scripts/harness_integration.py merge --change <change-name> --run-id <run-id> --feature-branch worktree/<change-name> --target-branch <主分支> --temp-root <task-temp>
 ```
 
-合并消息默认 `Merge branch 'worktree/<change-name>'`，用户可改文案，**方式固定 --no-ff**。
+- 方式固定 `--no-ff`；merge diff 出现其他 Change 的 contract/runtime 路径 → 结构化 `FOREIGN_CHANGE_PATHS` 拒绝
+- 冲突 → step FAILED：**停下**，`git -C <integration-worktree> diff --name-only --diff-filter=U` 列冲突文件，提示用户手动解决；保护 refs 与 journal 保留
+- 人工解决后以 `recover` 续跑；已完成步骤返回 REUSED，不重复 merge
 
-### 步骤 M4：冲突处理
+### 步骤 M4：verify（组合态验证）
 
-若输出 `CONFLICT`：
+在 integration worktree 内执行验证命令；远端引入他人提交或 ledger 不可复用时必跑：
 
 ```powershell
-powershell.exe -Command "git -C '<项目路径>' diff --name-only --diff-filter=U"
+python harness/scripts/harness_integration.py verify --change <change-name> --run-id <run-id> --feature-branch worktree/<change-name> --target-branch <主分支> --temp-root <task-temp> --command "<resolved command>"
 ```
 
-- 列出冲突文件，**停下**，提示用户手动解决（编辑 → `git add` → `git commit`）
-- 状态 `🟡WARN(merge 冲突，待手动解决：<文件列表>)`
-- 用户确认解决后重跑 submit（从 M0 重入）
-- **禁止自动 `git checkout --theirs/--ours`**
-
-### 步骤 M5：合并后验证（ledger 复用优先）
-
-- 步骤 M2 引入他人提交 → **必须重跑** 构建+测试
-- 否则 diffHash 一致且 post-test 非行为性 → 🔁REUSED
-
-重跑后写回 ledger 的 `compile`/`unitTest`，更新 `diffHash`/`currentHead`。
+任一命令非零退出 → step FAILED，不进入 push。
 
-**写 check-ok marker**（npm run check exit 0 后强制）：让 pre-push hook 跳过重复 check。三重校验（marker ts<10min + command + commit tree），任一不满足照跑。marker 写入时记录 `git write-tree`，因此验证后创建 commit 不会仅因 HEAD 前移而使缓存失效。
+**写 check-ok marker**（npm run check exit 0 后强制）：
 
 ```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 主分支
+### 步骤 M5：push
 
 ```powershell
-powershell.exe -Command "git -C '<项目路径>' fetch"
-powershell.exe -Command "git -C '<项目路径>' log HEAD..@{u} --oneline"
+python harness/scripts/harness_integration.py push --change <change-name> --run-id <run-id> --feature-branch worktree/<change-name> --target-branch <主分支> --temp-root <task-temp>
 ```
 
-远端有新提交 → 回 M2；无则：
-
-```powershell
-powershell.exe -Command "git -C '<项目路径>' push"
-```
-
-记录 `mergeFinalHash`：`git rev-parse HEAD`。
-
-### 步骤 M7：清理 worktree
+远端基线漂移 → `TARGET_MOVED` 结构化失败，不继续。成功后 journal `pushedHead` 即 `mergeFinalHash`。
 
-若存在 test-tracking manifest，删除 worktree 前必须逐一确认 manifest 路径已包含在 worktree commit 中，且合并后的主分支可用 `git ls-files --error-unmatch -- <exact-path>` 找到；任一路径缺失即停止清理并报告，防止 ignored test 随 worktree 被永久删除。
+### 步骤 M6：cleanup
 
 ```powershell
-powershell.exe -Command "git -C '<项目路径>' worktree remove '<worktree-path>' --force"
-powershell.exe -Command "git -C '<项目路径>' branch -D worktree/<change-name>"
+python harness/scripts/harness_integration.py cleanup --change <change-name> --run-id <run-id> --feature-branch worktree/<change-name> --target-branch <主分支> --temp-root <task-temp>
 ```
 
-> Windows 兜底见 `reference.md`「Worktree 清理兜底（Windows）」。
+- `git worktree remove --force` 精确路径 → 验证注销 → 临时分支 `branch -D` → （push 成功后）删除保护 refs → 释放 integration lock
+- 清理只接受 journal 登记的精确 integrationRoot；仓库根、父目录、空路径、逃逸路径与其他 transaction 路径一律拒绝
+- 失败保留 journal 与诊断证据，状态 🟡WARN，不得宣称清理完成
+- 若存在 test-tracking manifest，确认其路径已由合并后的目标分支跟踪（`git ls-files --error-unmatch -- <exact-path>`），缺失即停止
 
 更新 `meta/worktree.json`：`created=false` + `removedAt`/`removedBy`/`removalNote`。
 
-### 步骤 M8：更新 ledger + 收尾
+### 步骤 M7：更新 ledger + 收尾
 
-ledger 顶层写入 `"mergeFinalHash": "<hash>"`；append `phase.end`（merge 段）。
+ledger 顶层写入 `"mergeFinalHash": "<journal pushedHead>"`；经 `harness_gate.py close --phase merge` 关闭（禁止手工 phase.end）。
 
 ```markdown
 ## 合并完成 — <change-name>

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=0d4dcc4204125f4d; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=43088896a4556b69; overlay=none; agent=claude-code; do not edit -->
 # harness-sync — 元数据同步
 
 ## Purpose
@@ -32,6 +32,21 @@ disallowed-tools:
 
 ## Workflow（薄编排）
 
+运行开始先执行受管 runtime 生命周期：
+
+```powershell
+python <skills-root>/scripts/harness_sync.py reap --project . --json
+python <skills-root>/scripts/harness_sync.py begin --project . --run-id <run-id> --agent <agent> --purpose harness-sync --json
+```
+
+所有 deploy 临时产物只能写入 `begin` 返回的 `workspace`。无论正常完成、命令失败还是异常退出，都必须在 `finally` 中执行：
+
+```powershell
+python <skills-root>/scripts/harness_sync.py finalize --project . --run-id <run-id> --json
+```
+
+禁止重新使用固定 `sync-deploy-*` 目录；`--keep-temp` 仅供显式诊断。
+
 | Phase | 检查 → 动作 |
 |-------|-------------|
 | 0 | 读 SKILL + `reference.md` + protocols |
@@ -42,7 +57,7 @@ disallowed-tools:
 | 3.6 | 单次运行 `harness_knowledge.py maintain --project . --drain --json`，有界推进全部 `.harness/knowledge/maintenance-outbox/{pending,failed}`；不得为每个条目重复启动 Python/重建索引（§8.2：archive close 只 enqueue，sync 异步推进 outbox 到 completed/pending-judge） |
 | 4 | CLAUDE.md 完整性/行数 → 超限 AskUserQuestion 瘦身 |
 | 5 | AGENTS.md 与 CLAUDE.md 一致 |
-| 6 | `.harness/` 结构（init 规程 → `reference.md` 第 6 步）；可选 `harness_deploy.py diff` 检查已装 skill 是否过期 |
+| 6 | `.harness/` 结构（init 规程 → `reference.md` 第 6 步）；已装 skill 新鲜度只经 `hunter-harness refresh --dry-run --json` 的 post-adaptation freshness 判断，禁止 raw build 字节比较 |
 | 7–9 | `项目规则（见 .harness/context-index.json）/`、构建配置、测试目录 — **只提示不自动修复** |
 
 状态判断表格、修复动作、输出示例 → `reference.md`

package/harness/bundles/general/claude-code/harness-sync/reference.md

@@ -75,8 +75,8 @@ powershell.exe -Command "git -C '<项目路径>' diff --stat HEAD~5 2>$null"
 | state 目录 | `.harness/state/baseline/` 存在（internal_state） | ✅OK | 无需操作 |
 | codebase map | `.harness/codebase/map/` 状态 | — | 见第 3 步 |
 | 整体缺失 | `project.yaml` 与 `context-index.json` 均不存在 | ❌FAIL(未初始化) | 执行 `hunter-harness init`（见下方风险规程） |
-| .gitignore 选择性跟踪 | 未整条忽略 `.harness/`：user_editable（project.yaml/knowledge/）、generated_reviewable（codebase/map）多需跟踪；internal_state（state/）、generated_cache（cache/、generated/、reports/）不跟踪 | ✅OK | 无需操作 |
-| .gitignore 整体忽略 | `.gitignore` 含整条 `.harness/` | 🟡WARN(过度忽略) | 提示按 file-policy 拆分跟踪策略，而非整体忽略 |
+
+> sync 不读取、不修改也不建议修改项目 `.gitignore` 策略（RET-34/35）：三种跟踪策略（整体忽略 / 选择性跟踪 / 完全跟踪）下完整性结论相同，新鲜度由 post-adaptation projection 判定，与 Git 策略无关。
 
 > ⚠️ **`hunter-harness init` 风险规程**（`.harness/` 未初始化时触发）：
 > 1. **预览**：`node packages/cli/dist/bin.js --non-interactive --dry-run --adapter claude-code --profile general --json`，确认将写入的路径清单与 `project_id`（`null` = 未绑服务器，本地自治理）。

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=0d4dcc4204125f4d; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=43088896a4556b69; overlay=none; agent=claude-code; do not edit -->
 # harness-test — 测试执行
 
 ## Purpose

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

@@ -293,6 +293,15 @@ powershell.exe -NoProfile -Command "try { (Invoke-WebRequest -Uri 'http://127.0.
 - [ ] durationMs > 10000 → 🟡SLOW，说明原因
 - [ ] durationMs > 30000 → ❌TIMEOUT_RISK，说明原因
 
+### 覆盖标注诚实性（✅ 实测 vs 🟡 推断）
+
+场景状态标注规则：
+
+- [ ] ✅ 仅当断言实际执行**且**场景声明的前置条件/数据真实构造
+- [ ] 🟡（推断）：未构造场景条件、以相邻场景或同接口行为推断时使用，必须注明推断依据
+- [ ] 用同一请求重复调用来"覆盖"不同异常场景 → 一律 🟡
+- [ ] 报告汇总行的通过数只统计 ✅（不含 🟡 推断）
+
 ## 关门检查（⚠️ 结束前强制执行）
 
 - [ ] `powershell.exe -NoProfile -Command "git status --porcelain"`

package/harness/bundles/general/claude-code/harness-test/pitfalls-java.md

@@ -0,0 +1,14 @@
+---
+description: Java/Feign 相关测试踩坑（harness-test）。API 实测前通读；发现客户端路径缺陷时回写 plan 外修复记录。
+---
+
+# Java 测试踩坑补充（Feign / 远程客户端）
+
+> 与 `pitfalls.md`（通用）及 `overlays/java/pitfalls-java.md`（overlay 速查表）互补；本文件收录路径拼接类缺陷的症状与流程要求。
+
+## Feign/客户端路径前缀缺失
+
+**症状**：服务正常、接口 200，但客户端拿到 404 / 空数据 / fallback 生效。
+**根因模式**：`@FeignClient` 方法上只写了 `@GetMapping("/type")`，漏掉服务端类级前缀（如 `/system/dict-data`）。
+**定位**：对照服务端 controller 完整映射（类级 `@RequestMapping` + 方法级注解），或看服务端访问日志中的实际 404 路径。
+**流程要求**：此类缺陷若在 test 阶段被 API 实测发现，属于"计划外修复"——必须记 decision 事件（含根因与修复文件），并检查同客户端文件的其余方法是否同源错误。

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

@@ -582,6 +582,15 @@ TEST_<change-name>_<timestamp>_<short-random>
 
 如果场景表有「数据兼容场景」：查询已有数据，验证新字段返回 null 或默认值，不报错。
 
+## 覆盖标注诚实性规则
+
+场景状态标注规则：
+
+- ✅ 仅当断言实际执行**且**场景声明的前置条件/数据真实构造。
+- 🟡（推断）：未构造场景条件、以相邻场景或同接口行为推断时使用，必须注明推断依据。
+- 用同一请求重复调用来"覆盖"不同异常场景 → 一律 🟡。
+- 报告汇总行的通过数只统计 ✅。
+
 ## 输出格式（测试报告模板）
 
 测试完成后，将报告保存到 `.harness/changes/<change-name>/reports/test/test-report-YYYYMMDD-HHmm.md`（时间戳格式：日期+时分），同时在控制台输出摘要。
@@ -684,6 +693,35 @@ TEST_<change-name>_<timestamp>_<short-random>
 - 如果 ❌FAIL：修复失败项后重新运行 /harness-test
 ```
 
+## CLI 速查（gate / ledger）
+
+> test 阶段常用子集。`--task` **仅在该 change 启用 checkpoint 时必需**。ledger status 枚举: ok|fail|not_run（没有 PASS）。`record` 还需 `--duration-ms`、`--evidence`，以及 `--files` 或 `--profile-input`+`--project`。
+> `--skills-root` 仅用于 `begin`（及 `lint-skills`）：必须是 adapter 根（如 `.cursor/skills`），不是 `scripts/` 子目录。**`close` 不需要 `--skills-root`**（该子命令不接受此参数）。
+
+```powershell
+# gate begin/close（phase=test；--task 仅 checkpoint 启用时必需；close 不需要 --skills-root）
+python <skills-root>/scripts/harness_gate.py begin --change <cn> --phase test --skills-root <skills-root> [--task N]
+python <skills-root>/scripts/harness_gate.py close --change <cn> --phase test --status OK [--task N]
+
+# ledger 记录 / 复用（--profile-input = verification key，不是文件路径）
+python <skills-root>/scripts/harness_ledger.py record --change-dir <dir> --verification unitTestFull --status ok --command "<完整命令>" --exit-code 0 --duration-ms 120000 --evidence "Tests run: N, Failures: 0" --coverage full --files "packages/core/src/index.ts"
+python <skills-root>/scripts/harness_ledger.py can-reuse --change-dir <dir> --verification unitTestFull --profile-input unitTestFull --project <project>
+```
+
+> **Ledger v3（v2 契约 / split-v1 布局起）**：`record` 强制顶层身份（缺失非零退出、不写账本）；`--metrics-json` 必须过 typed schema（unit/apiContract/browserE2E/dbCompatibility 各有不同必填键）；dbCompatibility 等不适用验证用 `--applicability NOT_APPLICABLE --applicability-reason "<scope 原因>"`（不计通过也不计失败）。legacy 契约行为不变。详见 `../protocols/ledger-protocol.md` 第十节。
+
+### 常见报错对照
+
+| 报错 | 原因 | 处理 |
+|------|------|------|
+| `unsupported status: PASS` | ledger status 无 PASS | 改用 `ok` / `fail` / `not_run` |
+| `TASK_NUMBER_REQUIRED` | 该 change 启用了 checkpoint（如 foundation-gate pending） | 补 `--task N` |
+| skills-root / BUNDLE_IDENTITY_* | `begin` 未传或传了 `.../scripts` 子目录（`close` 不接受该参数） | 仅对 `begin` 显式传 adapter 根：`.cursor/skills` / `.claude/skills`（含 `.harness-build.json`） |
+| `--profile-input` 指向文件路径 | 参数语义是 verification key | 传 `compile` / `unitTestFull` 等 key，不是 JSON 路径 |
+| `record requires --files or a non-empty --profile-input file set` | 缺少输入文件集 | 补 `--files` 或 `--profile-input <key> --project <project>` |
+| `--profile-input requires --project` | can-reuse/record 展开 profile 需要项目根 | 补 `--project <project>` |
+| `record` 缺 `--duration-ms` / `--evidence` | 参数为必填 | 按模板补齐 |
+
 ## 结果分级规则
 
 > 结果状态分级与证据要求遵循 `../protocols/evidence-based-reporting-protocol.md`。

package/harness/bundles/general/claude-code/protocols/archive-report-protocol.md

@@ -6,7 +6,9 @@ description: harness-archive 的数据化归档和 final-summary 渲染协议。
 
 ## 原则
 
-archive 不应让模型临场生成 500+ 行 HTML。事实收集与校验由 `harness_archive.py finalize` 单命令完成（collect → render → validate 内嵌）；模型仅补写 `maintenanceNotes` / `knownRisks` / `manualActions`。历史 archive 回放用 `harness_archive.py replay`。
+archive 不应让模型临场生成 500+ 行 HTML。事实收集与校验由 `harness_archive.py finalize` 单命令完成（cleanup → **freeze（事件 cutoff）** → collect → source consistency → render → renderer consistency → validate → archive-meta 内嵌）；模型仅通过 events 写入维护结论。`meta/archive-meta.md` 由 finalize 生成，禁止手写。历史 archive 回放用 `harness_archive.py replay`（只读，不写 archive-meta / 不跑 cleanup）。
+
+`knownRisks` 仅收录 severity∈{warning,error,critical} 的 issue 事件；无 severity 的 issue 进入 `maintenanceNotes`。`finalStatusReasons` 解释 CONDITIONAL_OK/WARN/FAIL 原因。finalize 在 before-manifest 前 cleanup：删除 lock/pid/launcher/credential，截断超大日志。
 
 详见 `report-pipeline-protocol.md`。本协议保留 archive final report 的维度要求，report pipeline 负责把这些维度程序化生成和校验。
 
@@ -25,11 +27,11 @@ events.ndjson（新流程推荐；历史 archive 可缺失）
 
 ## summary-data.json
 
-结构来源为 `harness-archive/templates/summary-data-template.json`（schemaVersion 2.2）。默认由 `harness_archive.py finalize` 生成；历史回放用 `harness_archive.py replay`。
+结构来源为 `harness-archive/templates/summary-data-template.json`（schemaVersion 2.3）。默认由 `harness_archive.py finalize` 生成；历史回放用 `harness_archive.py replay`。
 
 ```json
 {
-  "schemaVersion": "2.2",
+  "schemaVersion": "2.3",
   "changeName": "...",
   "businessGoal": "本次变更为了做什么",
   "finalCommit": "...",
@@ -73,7 +75,8 @@ events.ndjson（新流程推荐；历史 archive 可缺失）
     "commands": [],
     "verificationChecks": [],
     "artifacts": [],
-    "validationIssues": []
+    "validationIssues": [],
+    "sourceConsistency": {"ok": true, "issues": []}
   }
 }
 ```
@@ -141,6 +144,25 @@ PowerShell HTML renderer 仅作 legacy fallback。该脚本以 UTF-8 with BOM
 
 `validate` 是 `harness_archive.py finalize` 的内嵌同进程步骤（不存在独立 `report validate` CLI）；validate error 存在时，finalize 恢复原 changes 目录并 exit 非 0，绝不删除原 changes 目录。**缺 final-summary.html 恒为 validate error**（不再有"没有 HTML 但只 warning"的分支）。
 
+## 冻结优先 finalize 与两层一致性（schemaVersion 2.3 起）
+
+finalize 在 collect 之前**冻结事件事实**：所有 archive-fact 事件落盘并 fsync 后，写入唯一的 `phase.end` 与 `evidence/evidence-cutoff.json`（`eventCount` + `sha256` + `frozenAt`）。cutoff 之后**禁止再向归档 events.ndjson 追加任何事件**；后续报告生成事实（render/validate 结果、manifest 比对）只写入 finalize JSON payload 与 maintenance outbox，不回写事件流。collect 是纯函数：stage/timeline/durations 全部由冻结事件推导，**不存在选择性 patch 步骤**。
+
+两层 validator 顺序执行，任何一层失败都恢复原 change 目录并非零退出：
+
+1. **source consistency**（`validate_source_consistency`，render 前）：summary 事实对照冻结来源——`event_count` 对 cutoff、verification 对 ledger typed metrics projection、review 计数对 sidecars。结果写入 `reportPipeline.sourceConsistency = {ok, issues}`；`ok=false` 时 issue code 含 `event-count-mismatch` / `verification-mismatch`。
+2. **renderer consistency**（`validate_summary`，render 后）：HTML 对照 summary-data，数字不得漂移。
+
+## versioned repair（不改写原归档）
+
+`replay` 保持只读。归档后发现不一致时，用显式修复：
+
+```powershell
+python harness/scripts/harness_archive.py repair --archive-dir ".harness/archive/<archive-id>" --json
+```
+
+repair 先在 archive 外生成候选 derived version，两层 validator 均通过后，才以不可变新版本写入 `derived/v<N>/{summary-data.json, final-summary.html, repair-record.json}`，并把 `derived/authoritative.json` pointer 指向该版本；**原 summary-data.json、final-summary.html 与 manifest 永不覆盖**。知识层只从 authoritative pointer 指向且 hash 校验通过的版本提取条目。
+
 ## 归档与知识维护解耦（§8）
 
 archive close 的破坏性事务只执行确定性 close：

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

@@ -67,6 +67,7 @@ verification-ledger 把每次验证（compile / unit test / api test / package
       "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
@@ -284,6 +285,7 @@ ledger 的 `status` 与 final-summary 展示状态对应：
 | `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
 
@@ -313,3 +315,39 @@ ledger 的 `status` 与 final-summary 展示状态对应：
 ### 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 值 → `git rev-parse --verify 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`；`apiContract` 要求 `scenariosTotal/passed/failed`；`browserE2E` 要求 `total/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 / 其他命令）统一走原子写。

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

@@ -179,3 +179,19 @@ powershell.exe -NoProfile -ExecutionPolicy Bypass -File ".harness/changes/<chang
 ```
 
 原因：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"`。

package/harness/bundles/general/claude-code/protocols/report-pipeline-protocol.md

@@ -78,6 +78,23 @@ python <skills-root>/scripts/harness_events.py append --change-dir ".harness/cha
 | `issue` | code, severity, message | 问题和校验发现 |
 | `decision` | decision, reason | 人工确认、跳过、复用等决策 |
 
+## 事件语义与必填字段
+
+写入 `events.ndjson` 时按用途选 type；渲染侧会对缺失字段做 note 兜底，但写入侧仍应填齐语义字段。
+
+| type | 用途 | 必填 | 常见误用 |
+|------|------|------|----------|
+| `issue` | 需要跟进/影响结论的异常 | severity, message | 把信息性结论记成 issue（应使用 decision） |
+| `decision` | 决策/结论/知识引用 | note 或 decision+reason | - |
+| `verification` | 验证执行结果 | name, status | 漏 name 导致 "(unnamed)" |
+| `artifact` | 产物落盘 | path | 只传 note |
+| `command` | 命令执行 | command, exit_code | - |
+
+兼容提示（不失败、exit 0）：
+
+- `--type issue` 未传 `--severity` → 默认 `info` 并在 stderr 提示
+- `--type verification` 未传 `--name` 或 `--status` → stderr 提示，照常写入
+
 ## summary-data.json
 
 summary-data 必须保留原 archive final report 维度，并增加事件层摘要：

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

@@ -8,6 +8,21 @@ description: harness .harness 状态目录分层协议。用于减少根目录
 
 `.harness/changes/<change-name>/` 是变更状态真相源，但根目录不得继续堆放所有文件。新产物按子目录分层；旧路径保留读取兼容。
 
+## 双根布局（split-v1，2026-07 起）
+
+新 Change 将**静态合同**与**动态运行状态**分离到两个唯一所有者：
+
+```text
+.harness/changes/<change-name>/        # contractRoot：静态合同（spec/plans/meta）
+.harness/state/changes/<change-name>/  # stateRoot：动态状态（events/logs/ledger/tracking/reports/runtime）
+```
+
+- 合同由 `meta/change-context.json` 的 `stateOwnership.contractRoot` / `stateOwnership.runtimeRoot` 声明（schemaVersion 2）。
+- 动态产物（`events.ndjson`、`logs/execution-log.md`、`evidence/verification-ledger.json`、`evidence/test-tracking.json`、reports、runtime）只写 stateRoot。
+- 统一解析入口：`harness_paths.py` —— `resolve_change_layout()` 返回完整双根；`resolve_state_dir_for_contract()` 供 events/ledger/test_guard/gate 内部路由。
+- **legacy-colocated**：未声明 `stateOwnership` 的旧 Change 继续读写共址布局；resolve 只读，**绝不静默搬迁**；显式迁移须 copy → hash verify → atomic pointer switch。
+- 功能分支不得携带共享动态状态副本；checkpoint/archive 的 evidence snapshot 从 stateRoot 生成。
+
 ## 推荐结构
 
 ```text