@hunter-harness/workflow-harness 0.2.8 → 0.2.10

package/harness/bundles/java/codex/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/java/codex/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/java/codex/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/java/codex/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