@hunter-harness/workflow-harness 0.2.9 → 0.2.11

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

@@ -6,7 +6,7 @@ description: harness-archive 的数据化归档和 final-summary 渲染协议。
 
 ## 原则
 
-archive 不应让模型临场生成 500+ 行 HTML。事实收集与校验由 `harness_archive.py finalize` 单命令完成（cleanup → collect → render → validate → archive-meta 内嵌）；模型仅通过 events 写入维护结论。`meta/archive-meta.md` 由 finalize 生成，禁止手写。历史 archive 回放用 `harness_archive.py replay`（只读，不写 archive-meta / 不跑 cleanup）。
+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，截断超大日志。
 
@@ -27,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": "...",
@@ -75,7 +75,8 @@ events.ndjson（新流程推荐；历史 archive 可缺失）
     "commands": [],
     "verificationChecks": [],
     "artifacts": [],
-    "validationIssues": []
+    "validationIssues": [],
+    "sourceConsistency": {"ok": true, "issues": []}
   }
 }
 ```
@@ -143,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/cursor/protocols/ledger-protocol.md

@@ -315,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/cursor/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