npm - @hunter-harness/workflow-harness - Versions diffs - 0.2.42 → 0.2.43 - Mend

@hunter-harness/workflow-harness 0.2.42 → 0.2.43

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (238) hide show

package/harness/bundles/general/claude-code/.harness-build.json CHANGED Viewed

@@ -2,5 +2,5 @@
   "schemaVersion": 1,
   "overlay": "none",
   "agent": "claude-code",
-  "coreHash": "433205be6e827dd9"
+  "coreHash": "49a193cd2335f90e"
 }

package/harness/bundles/general/claude-code/contracts/build-profile-v3.schema.json CHANGED Viewed

@@ -108,6 +108,10 @@
               "requiredCapabilities"
             ],
             "properties": {
+              "id": {
+                "type": "string",
+                "pattern": "^[A-Za-z][A-Za-z0-9_-]*$"
+              },
               "commandKey": {
                 "type": "string",
                 "pattern": "^[A-Za-z][A-Za-z0-9_-]*$"
@@ -124,7 +128,36 @@
                 "enum": [
                   "incremental",
                   "module-am",
-                  "module"
+                  "module",
+                  "full"
+                ]
+              },
+              "argvTemplate": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "minItems": 1
+              },
+              "inputs": {
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "minLength": 1
+                }
+              },
+              "coverage": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "coverageLevel": {
+                "enum": [
+                  "incremental",
+                  "module",
+                  "module-am",
+                  "full"
                 ]
               },
               "candidate": {
@@ -137,6 +170,28 @@
                   "minLength": 1
                 },
                 "uniqueItems": true
+              },
+              "resourceLocks": {
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "uniqueItems": true
+              },
+              "estimatedDurationSeconds": {
+                "type": "number",
+                "minimum": 0
+              },
+              "requiresFrozenIdentity": {
+                "type": "boolean"
+              },
+              "reusePolicy": {
+                "enum": [
+                  "never",
+                  "identity-exact",
+                  "ledger-exact"
+                ]
               }
             }
           }

package/harness/bundles/general/claude-code/harness-archive/SKILL.md CHANGED Viewed

@@ -20,7 +20,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=433205be6e827dd9; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=49a193cd2335f90e; overlay=none; agent=claude-code; do not edit -->
 # harness-archive — 变更归档
 ## Purpose

package/harness/bundles/general/claude-code/harness-archive/reference.md CHANGED Viewed

@@ -47,6 +47,7 @@ powershell.exe -NoProfile -ExecutionPolicy Bypass -File "harness-skills/harness-
 - `durations`：totalMinutes + stages[{stage,skill,startedAt,endedAt,minutes,result}] —— 从 `logs/execution-log.md` 各 `[N] harness-<skill>` 小节的 `开始`/`结束`/`耗时` 解析；
 - `skillCalls`：每个 skill 的调用次数（含重入）+ 结果 —— 从 execution-log 统计；
 - `verification`：单元/API/覆盖展示，含 passRate —— 来自 `evidence/verification-ledger.json`；
+- `efficiency`：墙钟/活动/资源等待、验证尝试、失败分类、环境 prepare/reuse/reset/cleanup、重复命令与 wrapper 数 —— 由 `harness_efficiency.py` 从运行回执自动汇总；
 - `changedFiles`：path/summary/insertions/deletions —— 来自 `git diff --numstat <base>..<head>`；
 - `reviewSummary`：red/yellow + redFixed/redConfirmed/yellowFixed/yellowDeferred 修复进度；
 - `maintenanceNotes`：给后续维护者看的结论；

package/harness/bundles/general/claude-code/harness-archive/templates/render-summary.mjs CHANGED Viewed

@@ -201,6 +201,10 @@ const releaseHtml = recordOnly ? "" : `
 const remoteCost = record(measurements.remoteCost);
 const remoteCostTotals = record(remoteCost.totals);
 const storage = record(measurements.artifactStorage);
+const efficiency = record(data.efficiency);
+const efficiencyTiming = record(efficiency.timing);
+const environmentActions = record(efficiency.environment);
+const failureClasses = record(efficiency.failureClasses);
 const projection = record(data.projection);
 const durability = record(data.archiveDurability);
 const durabilityStatus = durability.status || "ARCHIVED_LOCAL_ONLY";
@@ -264,6 +268,10 @@ ${scenarioCoverageHtml}
   <div class="fact"><span>未归因 <code title="agentOrToolUnattributedMs">agentOrToolUnattributed</code></span><strong>${esc(duration(timing.agentOrToolUnattributedMs))}</strong></div>
   <div class="fact"><span>远端 runner 成本</span><strong>${measurement(remoteCostTotals.runnerMinutes ?? remoteCost.runnerMinutes, " 分钟")}</strong></div>
   <div class="fact"><span>新增制品字节</span><strong>${measurement(storage.bytesAdded, " bytes")}</strong></div>
+  <div class="fact"><span>验证尝试 / 资源等待</span><strong>${esc(efficiency.verificationAttempts ?? 0)} / ${esc(duration(efficiencyTiming.resourceWaitMs))}</strong></div>
+  <div class="fact"><span>环境准备 / 复用 / 重置 / 清理</span><strong>${esc(environmentActions.prepare ?? 0)} / ${esc(environmentActions.reuse ?? 0)} / ${esc(environmentActions.reset ?? 0)} / ${esc(environmentActions.cleanup ?? 0)}</strong></div>
+  <div class="fact"><span>启动器 / 环境 / 测试 / 外部失败</span><strong>${esc(failureClasses.launcher ?? 0)} / ${esc(failureClasses.environment ?? 0)} / ${esc(failureClasses.test ?? 0)} / ${esc(failureClasses.external ?? 0)}</strong></div>
+  <div class="fact"><span>无新证据的重复命令</span><strong>${esc(efficiency.repeatedCommandsWithoutNewEvidence ?? 0)}</strong></div>
   <div class="fact"><span>守恒差值 <code>conservationDeltaMs</code></span><strong>${esc(timing.conservationDeltaMs ?? "N/A")}</strong></div>
 </div></details>
 <details><summary>阶段状态</summary><div class="table-wrap"><table><thead><tr><th>阶段</th><th>结果</th></tr></thead><tbody>${stageHtml}</tbody></table></div></details>

package/harness/bundles/general/claude-code/harness-archive/templates/summary-data-template.json CHANGED Viewed

@@ -125,6 +125,34 @@
       "duplicateRunCount": 0
     }
   },
+  "efficiency": {
+    "schemaVersion": 1,
+    "timing": {
+      "wallClockMs": 0,
+      "activeTimeMs": 0,
+      "resourceWaitMs": 0
+    },
+    "verificationAttempts": 0,
+    "statusCounts": {},
+    "failureClasses": {
+      "launcher": 0,
+      "environment": 0,
+      "test": 0,
+      "external": 0,
+      "unknown": 0
+    },
+    "invalidationReasons": {},
+    "environment": {
+      "prepare": 0,
+      "reuse": 0,
+      "reset": 0,
+      "cleanup": 0
+    },
+    "productIdentityCount": 0,
+    "repeatedCommandsWithoutNewEvidence": 0,
+    "manualWrapperCount": 0,
+    "notes": []
+  },
   "reviewSummary": {
     "status": "ADVISORY",
     "red": 0,

package/harness/bundles/general/claude-code/harness-codebase-map/SKILL.md CHANGED Viewed

@@ -20,7 +20,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=433205be6e827dd9; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=49a193cd2335f90e; overlay=none; agent=claude-code; do not edit -->
 # harness-codebase-map — 代码库地图
 ## Purpose

package/harness/bundles/general/claude-code/harness-knowledge-ingest/SKILL.md CHANGED Viewed

@@ -20,7 +20,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=433205be6e827dd9; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=49a193cd2335f90e; overlay=none; agent=claude-code; do not edit -->
 # harness-knowledge-ingest
 从 `.harness/archive/**/reports/final/summary-data.json` 抽取项目知识，生成并维护本地 `.harness/knowledge/` 索引。

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

@@ -20,7 +20,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=433205be6e827dd9; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=49a193cd2335f90e; overlay=none; agent=claude-code; do not edit -->
 # harness-knowledge-query
 并行 change 中查询必须传 `--change <change-id>`；成功后以该 change 的 `meta/knowledge-context.json` 为稳定指针。全局 `context-packs/latest.json` 仅向后兼容，不得用于判断多个 active change 的上下文归属。

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

@@ -20,7 +20,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=433205be6e827dd9; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=49a193cd2335f90e; overlay=none; agent=claude-code; do not edit -->
 # harness-plan — 需求规划
 ## Purpose

package/harness/bundles/general/claude-code/harness-review/SKILL.md CHANGED Viewed

@@ -21,7 +21,7 @@ disallowed-tools:
   - Bash(curl *)
   - Bash(codegraph *)
 ---
-<!-- generated by harness_deploy.py; core=433205be6e827dd9; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=49a193cd2335f90e; overlay=none; agent=claude-code; do not edit -->
 # harness-review — 代码审查
 ## Purpose

package/harness/bundles/general/claude-code/harness-run/SKILL.md CHANGED Viewed

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

package/harness/bundles/general/claude-code/harness-run/reference.md CHANGED Viewed

@@ -94,7 +94,7 @@ requested=true + path missing
 6. **读取测试场景表**：`.harness/changes/<change-name>/plans/<change-name>-test-scenarios.md` → 获取测试真相源
 7. **读取验证账本**：`.harness/changes/<change-name>/evidence/verification-ledger.json`（如存在）→ 复用已有 compile/unitTest 结果
 8. **读取任务状态**：`.harness/changes/<change-name>/evidence/run-task-status.md`（如存在）→ 恢复上次运行状态
-9. **读取 review fixback**：用户传入 `--fixback` 或要求修复 review 问题时，读取最新 `.harness/changes/<change-name>/reports/review/fixback-*.md`，并将 RED/YELLOW 条目映射为本轮变更簇
+9. **读取 review fixback**：用户传入 `--fixback` 或要求修复 review 问题时，读取最新 `.harness/changes/<change-name>/reports/review/fixback-*.md`，并用 `harness_fixback.py` 将相关 RED/YELLOW 条目合并为一个批次；每条问题保留 RED/GREEN 证据，批次关闭后只触发一次 affected verification 与一次 review
 10. 确认 `项目规则（见 .harness/context-index.json）/` 规则已加载
 11. **执行测试基础设施探测**（见下方"步骤 0.5"）
 12. 确认构建环境正常（构建命令按技术栈，见项目 CLAUDE.md 或 `.harness/config/harness-build-config.md`；如 Java 的 `powershell.exe -Command "mvn compile -pl <module> -o -q"`）
@@ -102,6 +102,11 @@ requested=true + path missing
 14. **依赖模块预安装**：如果在 worktree 中执行，检查上游依赖是否已安装（如 Java 的 `mvn install` 到本地仓库、前端的依赖已 install）。缺失时先执行对应安装命令（Java 示例：`powershell.exe -Command "mvn install -pl <upstream-modules> -am -DskipTests -nsu"`）
 15. **代码探索优先用 codegraph_explore**：一次调用可获取多个相关符号的源码，替代逐个 Read 文件。违反 `项目 codegraph 规则` 规则逐个 Read 会浪费 3-5 分钟。仅在 codegraph 返回结果不完整时补充 Read
+长时编译或验证不得依赖当前对话持续在线；使用 `harness_runtime.py run-start` 创建
+受管会话，并以状态/日志游标重连。并行执行前先调用
+`harness_verification.py` 的 `plan` 模式取得资源锁 wave；没有资源声明的重任务保持串行。详见
+`../protocols/execution-session-protocol.md`。
 ### 步骤 0.0：正式产物来源确认
 在读取计划文件后，确认本次执行只使用 `.harness/changes/<change-name>/` 下的正式产物：

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

@@ -20,7 +20,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=433205be6e827dd9; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=49a193cd2335f90e; overlay=none; agent=claude-code; do not edit -->
 # harness-submit — 最终提交（含 worktree 合并）
 ## Purpose

package/harness/bundles/general/claude-code/harness-sync/SKILL.md CHANGED Viewed

@@ -19,7 +19,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=433205be6e827dd9; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=49a193cd2335f90e; overlay=none; agent=claude-code; do not edit -->
 # harness-sync
 ## Purpose

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

@@ -22,7 +22,7 @@ disallowed-tools:
   - Bash(node *)
   - Bash(codegraph *)
 ---
-<!-- generated by harness_deploy.py; core=433205be6e827dd9; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=49a193cd2335f90e; overlay=none; agent=claude-code; do not edit -->
 # harness-test — 测试执行
 ## Purpose
@@ -92,11 +92,17 @@ Runner 强制同项目单实例、低调度优先级、逐命令超时、正常
 动态数据库/Redis/令牌字段必须先由 `harness_environment.py prepare` 生成 secret-free receipt，再用 `exec --environment-receipt <file> --required-environment-field <NAME>` 闭包注入；缺失或指纹变化在启动测试前返回 `VERIFICATION_ENVIRONMENT_INCOMPLETE`。复杂 JSON、Docker template 或含引号参数不得跨多层 `-Command` 传递，改用 `exec --argv-file <utf8-json> --runtime-receipt <file>`；参数文件记录 PowerShell edition/version，运行回执只存 argv hash。`harness_service.py ensure` 属于正式持久服务模式，禁止从 bounded runner 内启动；命中时返回 `PERSISTENT_SERVICE_MODE_REQUIRED`。
+预计超过交互窗口的正式验证使用 `harness_runtime.py run-start`，随后通过
+`run-status` / `run-log --cursor` 重连；不得把调用方存活当作验证存活条件。环境 acquire
+必须显式选择 `change-session`（同 change + 内容指纹复用）或 `ephemeral`（每次重置）。
+验证 DAG 的并行度由 `resourceLocks` 决定，未分类重任务默认串行。完整合同见
+`../protocols/execution-session-protocol.md`。
 ### Phase 0：环境准备（主会话执行，需要交互确认）
 先 `harness_context.py prepare --phase test --executor <tool> [--change <id>] --json`，再 `harness_context.py begin --phase test --change <id> --executor <tool> --json` 校验最新 run→test receipt 的 artifact/hash/HEAD；然后 **`harness_gate.py begin --phase test --change <id>`**（禁止手工 phase.start / 手写 ledger）。执行各项强制环境检查 + **命令执行模式 preflight (0.1)**；只有首选执行器不可用时，才执行 fallback 执行器探测。
-验证写入**仅**允许 `harness_ledger.py record` / `can-reuse`；禁止 Write/Edit `verification-ledger.json`。测试跟踪：`harness_test_guard.py begin` → 执行 → `close`（可选 `mark` stale-test-repair）。阶段结束必须 `harness_gate.py close --phase test --status ...`，随后 `harness_context.py close --from-phase test --to-phase review --executor <tool> --json`；fixback 时改为 `--to-phase run` 并由 context 失效受影响 target。
+验证写入**仅**允许 `harness_ledger.py record` / `can-reuse`；禁止 Write/Edit `verification-ledger.json`。测试跟踪：`harness_test_guard.py begin` → 执行 → `close`（可选 `mark` stale-test-repair）。阶段结束必须 `harness_gate.py close --phase test --status ...`，随后 `harness_context.py close --from-phase test --to-phase review --executor <tool> --json`；fixback 时由 `harness_fixback.py` 合批记录 RED/GREEN 和 affected verification，再 `--to-phase run` 并由 context 失效受影响 target。
 - **Read `checklist.md`** — 各项检查详情 + 0.1 preflight + Playwright 探测 + 避坑规则指引
 - **失败处理**：任一项检查失败 → 终止流程并报告原因，用户确认修复后才能继续

package/harness/bundles/general/claude-code/protocols/execution-session-protocol.md ADDED Viewed

@@ -0,0 +1,52 @@
+---
+description: 长时命令、验证调度、环境复用与 fixback 的可恢复执行协议。
+---
+# Execution Session Protocol
+## 受管运行会话
+可能超过交互窗口的命令必须通过 `harness_runtime.py run-start` 创建受管会话，而不是依赖调用方进程持续在线。会话状态位于：
+```text
+runtime/run-sessions/<session-id>/
+├── session.json
+├── stdout.log
+├── stderr.log
+└── worker.log
+```
+`session.json` 只持久化脱敏身份：命令哈希、环境哈希、产品身份、验证目标、阶段、资源锁、进程身份、心跳、进度、超时和原因码。原始环境变量和敏感 argv 不得写入回执。
+- `run-status` 可由新进程重连；心跳丢失超过 grace period 才标记 `INCOMPLETE`。
+- `run-log --cursor` 按字节游标增量读取 UTF-8 日志，返回下一游标。
+- `run-cancel` 只终止身份完全匹配的进程树；身份不确定时 fail closed。
+- launcher 尚未启动子进程时失败，状态为 `INCOMPLETE/LAUNCHER_FAILED`；子进程非零退出为 `FAIL/CHILD_EXIT_NONZERO`；超时为 `CANCELLED/TIMEOUT`。
+- `resourceLocks` 通过 `runtime/resource-locks/<lock-hash>.json` 原子独占；冲突会在启动测试进程前返回 `INCOMPLETE/RESOURCE_LOCK_BUSY`，终态写入前必须释放持有的锁。
+- Windows 使用 shell-free argv 和 kill-on-close Job Object；Job Object 绑定失败时必须终止已验证的子进程并返回 `PROCESS_TREE_ISOLATION_UNAVAILABLE`，不得降级为无隔离运行。
+## 验证调度
+`harness_verification.py plan` 对验证 DAG 做拓扑调度。每个目标声明 `dependsOn`、`resourceLocks`、identity 与复用策略。
+- 只有资源锁不相交的 ready 目标可进入同一 wave。
+- 未声明资源锁且预计大于等于 60 秒的目标自动使用 `harness:unclassified-heavy`，因此默认串行。
+- 冻结后的产品 identity 发生变化时返回 `FROZEN_IDENTITY_DRIFT`，禁止继续执行或复用。
+- 复用和跳过必须记录 `decision`、`reasonCode` 与人类可读 `explanation`；无证据不得返回 `REUSE`。
+## 环境会话
+环境租约支持两种模式：
+- `change-session`：同一 change、stack、内容指纹和通过的 canary 可复用。
+- `ephemeral`：每次 acquire 都创建新 session；替换既有 session 前必须提供匹配 stack/environment identity 的 provider reset 回执。
+租约获取通过注册锁原子串行化，跨 change 的 writable volume 永不共享。`change-session` 只有在内容指纹非空、environment hash、owner identity、expiry、mode、volume 和 canary 全部匹配时才可复用。内容指纹漂移标记 `STALE_CONTENT`；过期租约不可写。prepare/reuse 写入事实回执；reset/cleanup 只有在 provider operation evidence 为 `OK` 时才可如此命名。单纯释放租约只能记录 `release`，不得声称已清理外部环境。回执写入 change 的 `runtime/environment-receipts/`，文件名使用 stack hash，且不包含凭据明文。
+## Fixback 批次
+Review/Test 回灌通过 `harness_fixback.py` 形成批次。一个批次可包含多条相关问题，但每条问题必须保留可读取的 JSON RED/GREEN 证据。证据必须位于项目或 change state 内，包含 evidence id、状态和产品 identity，并在批次中固定 SHA-256；RED 必须为 `FAIL`，GREEN 必须为 `PASS/OK`。affected verification 与 review 回执必须绑定最终产品 identity，其 `passedGates` 合集覆盖风险扩展后的全部门禁。`freeze-readiness` 会重新校验证据摘要；开放问题、证据漂移或缺门禁均阻止 code freeze。
+## 效率摘要
+`harness_efficiency.py summary` 从运行会话、环境回执和失效回执生成事实型指标：墙钟区间并集、累计活动/资源等待、execution/launcher/verification 尝试、失败分类、环境 prepare/reuse/reset/cleanup、重复且没有新 result digest 的命令和人工 wrapper 数。reset/cleanup 只统计带有效 provider evidence 的回执。归档摘要自动包含该结构；指标不得归责个人，也不得在历史样本不足时虚构 ETA。

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

@@ -60,7 +60,14 @@ description: harness .harness 状态目录分层协议。用于减少根目录
 ├── sqls/
 ├── scripts/
 ├── runtime/
-│   └── service-session.json
+│   ├── service-session.json
+│   ├── run-sessions/<session-id>/
+│   │   ├── session.json
+│   │   ├── stdout.log
+│   │   └── stderr.log
+│   ├── environment-receipts/
+│   ├── invalidations/
+│   └── fixback/batches/
 └── backups/
     └── uncommitted-tests/
 ```
@@ -73,6 +80,10 @@ description: harness .harness 状态目录分层协议。用于减少根目录
 `build-profile.json` 的 `serviceStart.inputFiles`（glob 列表，相对 project 展开）是 `moduleInputsHash` 的来源。`harness_service.py ensure` 取 CLI `--files` ∪ `serviceStart.inputFiles` 计算依赖闭包；**空输入被拒绝**（exit 非 0），**不得生成可复用的空指纹**。通用项目 detect 无法猜 module 源，`inputFiles` 默认空数组，须人工配置。
+过期的 service session 只有在进程身份明确不匹配时才允许由 `retire-stale` 移入
+`runtime/retired-service-sessions/`；该动作保留原始回执且不终止进程。受管命令、
+环境会话和 fixback 的完整合同见 `execution-session-protocol.md`。
 ## knowledge maintenance-outbox（§8）
 归档 close 不再同步执行知识维护；它写一个 pending outbox 项即返回：
@@ -179,3 +190,15 @@ Harness skill 读取的项目级配置（不提交 git）。缺失时使用下
 | `knowledge.manualReview` | boolean | `false` | `true` 时 knowledge-ingest promote 等高价值操作需人工确认；`false` 时按 skill 默认策略 |
 读取顺序：`.harness/config/harness.json` → 缺失则默认值。plan 阶段 5 设计审批包须读取 `defaultWorktree` 作为 worktree 选项的推荐值。
+## 可恢复文件事务
+schema v3 事务在本地 `transactions/<transaction-id>/` 保存 journal、before snapshot、staged payload、after manifest 和小型 status 投影。journal 固定 project identity、执行器版本、目标 Bundle identity、ownership manifest hash、plan hash 与 snapshot digest。
+未完成事务同时镜像到用户级恢复根：
+```text
+${HUNTER_HARNESS_RECOVERY_ROOT:-~/.hunter-harness/recovery}/<project-path-hash>/transactions/<transaction-id>/
+```
+因此项目内 `.harness` 局部丢失后，`status` 仍可只读发现恢复项。`resume` 仅在 plan/snapshot/staged digest 与已完成操作的当前文件状态全部匹配时继续 pending operations；任一不匹配均 fail closed。`rollback` 在写回 before snapshot 前重新校验 snapshot digest。事务提交或回滚成功后删除用户级镜像；本地 committed 事务仍按保留策略提供显式回滚。

package/harness/bundles/general/claude-code/protocols/verification-graph-protocol.md CHANGED Viewed

@@ -11,6 +11,9 @@ Build Profile v3 用 `verificationGraph` 取代账本内的固定验证目标清
 - `requiredCoverage`：`incremental/module-am/module`；
 - `candidate`：是否为发布候选门禁；
 - `requiredCapabilities`：执行环境必须具备的能力。
+- `resourceLocks`：目标独占或共享的数据库、端口、浏览器、容器等资源身份；
+- `estimatedDurationSeconds`：供默认串行策略和进度显示使用，不作为虚构 ETA 的依据；
+- `reusePolicy`：允许复用时必须匹配的产品、环境、命令与覆盖身份。
 `candidateTarget` 必须引用已声明目标。未知目标、未知依赖、循环依赖、命令缺失都 fail closed。
@@ -22,5 +25,8 @@ Build Profile v3 用 `verificationGraph` 取代账本内的固定验证目标清
 4. 未进入闭包的目标是 `omitted`，与“执行失败”或“因能力阻断”分开报告。
 5. 账本记录目标定义的规范化 identity；依赖、覆盖度或能力声明变化后，旧证据必须失效。
 6. 候选目标即使自身命令可运行，也必须等待所有依赖和能力满足。
+7. ready 目标按 `resourceLocks` 分 wave；锁相交的目标不得并行。预计 ≥60 秒且未声明锁的目标默认归入 `harness:unclassified-heavy` 串行队列。
+8. code freeze 后产品 identity 漂移必须返回 `FROZEN_IDENTITY_DRIFT`；禁止在旧候选上补跑后声称覆盖新候选。
+9. 每个 `RUN / REUSE / SKIP / BLOCKED` 决策都必须带稳定 `reasonCode` 和解释；`REUSE` 还必须绑定现有证据 identity。
 JSON 合同见 `contracts/build-profile-v3.schema.json`；通用选择器为 `@hunter-harness/core` 的 `selectVerificationTargets`。

package/harness/bundles/general/claude-code/scripts/harness_archive.py CHANGED Viewed

@@ -70,6 +70,7 @@ if str(SCRIPTS_DIR) not in sys.path:
     sys.path.insert(0, str(SCRIPTS_DIR))
 import harness_events as he  # noqa: E402
+import harness_efficiency as heff  # noqa: E402
 import harness_gate as hgate  # noqa: E402
 import harness_ledger as hl  # noqa: E402
 import harness_paths as hp  # noqa: E402
@@ -3890,12 +3891,15 @@ def collect_summary_data(
             "retention",
             "archiveDurability",
             "remoteCost",
+            "efficiency",
             "projection",
         ):
             if key in existing:
                 data[key] = _deepcopy_json(existing[key])
     if not for_replay or not isinstance(data.get("remoteCost"), dict):
         data["remoteCost"] = remote_cost
+    if not for_replay or not isinstance(data.get("efficiency"), dict):
+        data["efficiency"] = heff.collect_efficiency_summary(change_dir)
     event_summary = he.build_summary(change_dir, events) if events else {
         "ok": True,