@hunter-harness/workflow-harness 0.2.20 → 0.2.22

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

@@ -2,5 +2,5 @@
   "schemaVersion": 1,
   "overlay": "none",
   "agent": "claude-code",
-  "coreHash": "5b9a3abb544f8fb2"
+  "coreHash": "f211142684412a01"
 }

package/harness/bundles/general/claude-code/CONTEXT.md

@@ -48,6 +48,26 @@ _Avoid_: 每次重新探测, skill 内硬编码项目参数
 一项验证（compile/install/unitTest/apiTest）所依赖源文件集合的内容哈希。指纹一致且证据完整才允许 🔁REUSED；无法证明即保守重跑。
 _Avoid_: 仅凭 diffHash 复用, 无证据跳过
 
+**验证图（verification graph）**:
+`evidence/verification-graph.json` 按 canonical identity 持久化验证节点；`can-reuse` 返回 `invalidationCode`（如 `INPUT_CHANGED`）；profile `mergeVerification.requiredOnMerge` 进入 integration verify。详见 ledger / integration 脚本。
+_Avoid_: 冻结后无因重跑全量
+
+**Migration head 单源**:
+消费项目用 `.harness/config/migration-head.json` 声明 canonical head 与联动 sources；`harness_migration_head.py check` 做静态一致性门禁。
+_Avoid_: config/CI/manifest 多处手写 head
+
+**事件批处理**:
+同阶段多事件用 `harness_events.py batch-append`（单锁多行）；`phase.end` 仍走单次 append。
+_Avoid_: 机械事件逐条起进程
+
+**能力级模型路由**:
+任务用 `economy` / `balanced` / `frontier` 表述；禁止在通用 harness 规则硬编码供应商模型名。详见 `protocols/model-routing-protocol.md`。
+_Avoid_: skill 内写死 claude-/gpt- 模型 id
+
+**Overlay 所有权**:
+Bundle 安装目标由安装器管理；项目自有配置放 `.harness/project-overlay/`（或 project.yaml 侧）。`--force-managed` 必须配合 `--yes`/`--confirmed`，冲突 fail closed。
+_Avoid_: 静默 force-managed
+
 **服务会话**:
 `runtime/service-session.json` 记录的 AI 启动服务生命周期。指纹匹配静默复用、不匹配自动重启、归档收尾统一停止；只有用户自启服务占端口才询问。
 _Avoid_: 每轮测试后必杀服务

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

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

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

@@ -14,6 +14,20 @@ description: harness-archive 的归档前检查项和归档后验证项。仅在
 - before/after checksum 不一致时，不得删除原目录。
 - 默认渲染器 `templates/render-summary.mjs`（finalize 内嵌调用）。
 
+### Wave-A 状态机与身份（IA-1 / IA-4）
+
+硬顺序：feature frozen → local gates → product candidate CI → **CI green** → merge → authoritative CI → archive product candidate → archive-only governance → release。
+
+- [ ] `evidence/product-candidate-ci.json`（或等价 ledger 字段）`conclusion=success`，含 `runUrl` + `commit`；否则 `PRODUCT_CI_NOT_GREEN` 阻断
+- [ ] summary/identity 含 `productCommit` / `productTreeHash` / `archiveCommit`；`productTreeHash` 排除 `.harness/**`
+- [ ] 产品输入在 archive 后变化 → `ARCHIVE_EVIDENCE_REOPEN_REQUIRED`，旧 archive 不可作发布证据
+- [ ] Manifest：coverage 字节在最终 snapshot 后不得静默漂移；后写报告必须 `exclusionReasons`，禁止假绿 `checksumStatus=OK`
+
+### Environment 合同（IA-3）
+
+- [ ] 使用可写环境栈前：`harness_environment.py fingerprint` → `acquire` lease → run → `release`
+- [ ] 租约落在主仓 `.harness/runtime/env-leases/`；跨 change 默认不得共享可写 volume
+
 ## 归档前检查（Phase 1）
 
 > ⚠️ **单一所有权**：finalize 内部负责且仅负责一次 `phase.start` / `phase.end`。归档前检查不得自行追加 archive 阶段边界。

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

@@ -42,6 +42,16 @@ const duration = (minutes) => {
   if (value < 60) return `${Math.round(value * 10) / 10} 分钟`;
   return `${Math.floor(value / 60)} 小时 ${Math.round(value % 60)} 分钟`;
 };
+const durationMs = (ms) => {
+  const value = number(ms);
+  if (value <= 0) return "0 秒";
+  if (value < 1000) return `${value}ms`;
+  const seconds = value / 1000;
+  if (seconds < 60) return `${Math.round(seconds * 10) / 10} 秒`;
+  const minutes = seconds / 60;
+  if (minutes < 60) return `${Math.round(minutes * 10) / 10} 分钟`;
+  return `${Math.floor(minutes / 60)} 小时 ${Math.round(minutes % 60)} 分钟`;
+};
 
 const stages = Object.entries(record(data.stageStatus));
 const verification = record(data.verification);
@@ -49,6 +59,17 @@ const unit = record(verification.unitTests);
 const api = record(verification.apiTests);
 const durations = record(data.durations);
 const durationStages = list(durations.stages);
+const timing = record(data.timing);
+const wallLabel = timing.workflowWallClockMs != null
+  ? durationMs(timing.workflowWallClockMs)
+  : (durations.totalLabel || duration(durations.totalMinutes));
+const timingColumnsHtml = `
+<article class="card" id="timingColumns"><h2>时长（三列）</h2>
+<div class="row"><div><strong>活动执行</strong><small>stageActiveExecution</small></div><span>${esc(durationMs(timing.stageActiveExecutionMs))}</span></div>
+<div class="row"><div><strong>阶段墙钟</strong><small>stageWallClockSpan</small></div><span>${esc(durationMs(timing.stageWallClockSpanMs))}</span></div>
+<div class="row"><div><strong>全流程墙钟</strong><small>workflowWallClock</small></div><span>${esc(durationMs(timing.workflowWallClockMs))}</span></div>
+<p><small>reportCutoffAt=<code id="reportCutoffAt">${esc(timing.reportCutoffAt || "N/A")}</code> · durations.totalMinutes 仅为活动执行，不冒充墙钟</small></p>
+</article>`;
 const maxMinutes = Math.max(1, ...durationStages.map((item) => number(item.minutes)));
 const diff = record(data.diffStat);
 const risks = list(data.knownRisks);
@@ -86,12 +107,12 @@ const html = `<!doctype html><html lang="zh-CN"><head><meta charset="utf-8"><met
 @media(max-width:800px){.metrics{grid-template-columns:1fr 1fr}.grid,.risk{grid-template-columns:1fr}}@media(max-width:480px){main{width:calc(100% - 18px);margin-top:9px}.metrics{grid-template-columns:1fr}.hero{padding:19px}h1{font-size:23px}dl{grid-template-columns:1fr}}
 </style></head><body><main>
 <section class="hero"><div class="eyebrow">HARNESS EXECUTION REPORT</div><h1>${esc(data.changeName || "未命名变更")}</h1><p class="goal">${esc(data.businessGoal || "未记录业务目标")}</p><div class="status">${pill(data.finalStatus)}<span>基于事件、验证账本与 Git 证据生成${data.riskTier ? ` · riskTier=${esc(data.riskTier)}` : ""}</span></div>${reasonHtml ? `<div class="status">${reasonHtml}</div>` : ""}</section>
-<section class="metrics"><article class="metric"><small>任务提交</small><strong><code title="${esc(data.finalCommit)}">${esc(shortHash(data.finalCommit))}</code></strong><small>${esc(data.finalCommitBranch || "未记录分支")}</small></article><article class="metric"><small>代码范围</small><strong>${number(diff.filesChanged)} 个文件</strong><small><span class="plus">+${number(diff.insertions)}</span> · <span class="minus">-${number(diff.deletions)}</span></small></article><article class="metric"><small>总耗时</small><strong>${esc(durations.totalLabel || duration(durations.totalMinutes))}</strong><small>${durationStages.length} 个阶段</small></article><article class="metric"><small>归档完整性</small><strong>${esc(record(data.archiveManifest).checksumStatus || "UNKNOWN")}</strong><small>${number(record(data.archiveManifest).totalArchiveFiles)} 个归档文件</small></article></section>
-<section class="grid"><div><article class="card"><h2>验证结论</h2>${verificationHtml}</article><article class="card"><h2>阶段耗时</h2>${durationHtml}</article></div><div><article class="card"><h2>阶段状态</h2>${stageHtml}</article><article class="card"><h2>风险与后续</h2><div class="risk"><div><h3>已知风险</h3><ul>${riskHtml}</ul></div><div><h3>人工动作</h3><ul>${actionHtml}</ul></div></div></article></div></section>
+<section class="metrics"><article class="metric"><small>产品提交</small><strong><code title="${esc(data.productCommit || data.finalCommit)}">${esc(shortHash(data.productCommit || data.finalCommit))}</code></strong><small>archive=${esc(shortHash(data.archiveCommit || data.finalCommit))}</small></article><article class="metric"><small>代码范围</small><strong>${number(diff.filesChanged)} 个文件</strong><small><span class="plus">+${number(diff.insertions)}</span> · <span class="minus">-${number(diff.deletions)}</span></small></article><article class="metric"><small>全流程墙钟</small><strong>${esc(wallLabel)}</strong><small>活动=${esc(durationMs(timing.stageActiveExecutionMs))} · ${durationStages.length} 阶段</small></article><article class="metric"><small>归档完整性</small><strong>${esc(record(data.archiveManifest).checksumStatus || "UNKNOWN")}</strong><small>${number(record(data.archiveManifest).totalArchiveFiles)} 个归档文件</small></article></section>
+<section class="grid"><div><article class="card"><h2>验证结论</h2>${verificationHtml}</article><article class="card"><h2>阶段耗时（活动）</h2>${durationHtml}</article>${timingColumnsHtml}</div><div><article class="card"><h2>阶段状态</h2>${stageHtml}</article><article class="card"><h2>风险与后续</h2><div class="risk"><div><h3>已知风险</h3><ul>${riskHtml}</ul></div><div><h3>人工动作</h3><ul>${actionHtml}</ul></div></div></article></div></section>
 <details><summary>变更文件（${files.length}）</summary><div><table><thead><tr><th>文件</th><th>新增</th><th>删除</th></tr></thead><tbody>${fileRows}</tbody></table></div></details>
 <details><summary>执行时间线与工具交接（${timeline.length}）</summary><div><table><thead><tr><th>阶段</th><th>尝试</th><th>状态</th><th>来源 / 摘要</th></tr></thead><tbody>${timelineRows}</tbody></table></div></details>
 <details><summary>命令证据（${commands.length}）</summary><div><table><thead><tr><th>阶段</th><th>命令</th><th>结果</th></tr></thead><tbody>${commandRows}</tbody></table></div></details>
-<details><summary>技术元数据</summary><div><dl><dt>完整提交</dt><dd><code>${esc(data.finalCommit || "N/A")}</code></dd><dt>基线提交</dt><dd><code>${esc(data.baseCommit || "N/A")}</code></dd><dt>Git 范围</dt><dd><code>${esc(diff.range || "N/A")}</code></dd><dt>报告数据版本</dt><dd>${esc(data.schemaVersion || "N/A")}</dd><dt>事实来源</dt><dd>${esc(list(record(data.reportPipeline).sources).join(" · ") || "N/A")}</dd></dl></div></details>
+<details><summary>技术元数据</summary><div><dl><dt>产品提交</dt><dd><code>${esc(data.productCommit || data.finalCommit || "N/A")}</code></dd><dt>产品树哈希</dt><dd><code>${esc(data.productTreeHash || "N/A")}</code></dd><dt>归档提交</dt><dd><code>${esc(data.archiveCommit || data.finalCommit || "N/A")}</code></dd><dt>基线提交</dt><dd><code>${esc(data.baseCommit || "N/A")}</code></dd><dt>Git 范围</dt><dd><code>${esc(diff.range || "N/A")}</code></dd><dt>报告数据版本</dt><dd>${esc(data.schemaVersion || "N/A")}</dd><dt>事实来源</dt><dd>${esc(list(record(data.reportPipeline).sources).join(" · ") || "N/A")}</dd></dl></div></details>
 </main></body></html>`;
 
 fs.mkdirSync(path.dirname(outPath), { recursive: true });

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

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

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

@@ -20,7 +20,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=5b9a3abb544f8fb2; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=f211142684412a01; 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

@@ -20,7 +20,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=5b9a3abb544f8fb2; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=f211142684412a01; 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

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

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

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

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

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

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

@@ -267,3 +267,9 @@ description: harness-run 的执行检查清单。仅在编码执行时读取。
 - [ ] 如果新增筛选参数，设计中已明确非法值行为
 - [ ] 如果采用“忽略并不过滤”，必须有用户确认记录
 - [ ] 测试场景覆盖非法值
+
+
+## Wave-2 — Migration head（H-7）
+
+- [ ] 若变更触及 alembic/versions 或项目约定 migration 路径：列出 config / CI / env / manifest 联动文件
+- [ ] 消费项目存在 .harness/config/migration-head.json 时，跑 harness_migration_head.py check --project . --json

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

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

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

@@ -15,6 +15,12 @@ description: harness-submit 的8 步工作流详细步骤和执行日志记录
 - blocking user confirmation 参数错误时不得自行绕过，必须改用固定模板重问。
 - staged diff 是唯一提交依据。
 
+### Wave-A 发布身份与环境边界
+
+- [ ] 产品候选身份与归档治理身份分离：`productCommit`/`productTreeHash` 绑产品验证；`archiveCommit` 可晚于产品
+- [ ] 进入 candidate CI / archive 前确认 product candidate CI 证据可被 `harness_archive status` 读取为 green
+- [ ] 需要可写 DB/栈时走 `harness_environment` lease；禁止跨 change 默认可写共享
+
 
 ## 步骤 0：启动准备
 
@@ -420,3 +426,9 @@ ledger 顶层写入 `"mergeFinalHash": "<journal pushedHead>"`；经 `harness_ga
 - worktree: 已清理（迁根后）
 - 下一步: `/harness-archive`
 ```
+
+
+## Wave-2 — 验证复用与 merge 面（H-9）
+
+- [ ] 代码冻结后，同 identity 的 unitTestFull 须 can-reuse；禁止无 invalidationCode 整套重跑
+- [ ] integration verify 会合并 profile mergeVerification.requiredOnMerge（若配置）

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=5b9a3abb544f8fb2; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=f211142684412a01; overlay=none; agent=claude-code; do not edit -->
 # harness-sync — 元数据同步
 
 ## Purpose

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

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

@@ -6,6 +6,12 @@ description: harness-test 的 Phase 0 环境准备 + Playwright 探测 + 关门
 
 以下检查项确认完了再开始测试。每一项背后都有踩坑经历。
 
+### Wave-A 环境合同（IA-3）
+
+- [ ] 需要可写 DB/栈时：先 `harness_environment.py fingerprint` → `acquire` lease → 再跑测试 → `release`
+- [ ] 无 lease 不得占用可写栈（`ENVIRONMENT_LEASE_REQUIRED`）；跨 change 默认可写共享拒绝（`ENVIRONMENT_LEASE_CROSS_CHANGE`）
+- [ ] 租约目录：主仓 `.harness/runtime/env-leases/`（与 change 状态目录分离）
+
 #### 0.0 加载项目配置（如存在）与确定变更名
 
 先检查当前项目的测试配置文件（按优先级查找）：

package/harness/bundles/general/claude-code/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` 的理由。