@hunter-harness/workflow-harness 0.2.59 → 0.2.61

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

@@ -1,12 +1,12 @@
 ---
-description: harness-archive 的数据化归档和 final-summary 渲染协议。用于减少模型长篇 HTML 生成、提升数据准确性和页面一致性。
+description: harness-archive 的结构化归档与 summary-data 校验协议。用于减少重复产物、提升数据准确性和平台展示一致性。
 ---
 
 # Archive Report Protocol
 
 ## 原则
 
-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）。
+归档不应维护与平台重复的展示文件。常规入口是 `harness_archive.py execute`：它一次性完成状态采集与自动门禁，再复用预检结果调用 finalize。finalize 执行 cleanup → **freeze（事件 cutoff）** → collect → source consistency → summary 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，截断超大日志。
 
@@ -21,7 +21,6 @@ archive-meta.md
 archive-manifest-before.json
 archive-manifest-after.json
 summary-data.json
-final-summary.html
 events.ndjson（新流程推荐；历史 archive 可缺失）
 ```
 
@@ -81,7 +80,7 @@ events.ndjson（新流程推荐；历史 archive 可缺失）
 }
 ```
 
-`final-summary.html` 的数字必须全部来自 events、`summary-data.json`、ledger 或 manifest，不得手写另一套统计。
+`summary-data.json` 的数字必须全部来自 events、ledger 或 manifest，不得手写另一套统计。
 
 ### 数据采集来源（禁止手写统计）
 
@@ -90,7 +89,7 @@ events.ndjson（新流程推荐；历史 archive 可缺失）
 - `skillCalls`：从 execution-log 统计每个 `harness-<skill>` 小节出现次数（含重入）及结果。
 - `verification` 各项及 `passRate`：来自 `evidence/verification-ledger.json`，不得手写通过率。
 - `reviewSummary.redFixed`/`redConfirmed`/`yellowFixed`/`yellowDeferred`：从 review 报告清单 + 后续修复提交 diff 比对得出，不得手写。
-- `artifacts[]`：本次变更构建出的可分发 package 产物（如 `.jar`/`.war`/`.zip`/`.tar`/`.gz`/`.dll`/`.exe`/`.whl`/`.nupkg` 等）。来自项目构建输出目录扫描（按构建工具识别产物路径，如 Maven `target/*.jar`、Gradle `build/libs/*`、npm `dist/*`、.NET `bin/Release/*`），每项记录 `name`（basename）、`path`（相对仓库根）、`size`、`sha256`（`Get-FileHash -Algorithm SHA256` 计算），不得手写。无构建产物时留空数组（renderer 不渲染该卡）。注意：归档 manifest（`archive-manifest-after.json`）记录的是 `.harness/archive/` 目录文件，不包含项目构建产物，两者不可混用。
+- `artifacts[]`：本次变更构建出的可分发 package 产物（如 `.jar`/`.war`/`.zip`/`.tar`/`.gz`/`.dll`/`.exe`/`.whl`/`.nupkg` 等）。来自项目构建输出目录扫描（按构建工具识别产物路径，如 Maven `target/*.jar`、Gradle `build/libs/*`、npm `dist/*`、.NET `bin/Release/*`），每项记录 `name`（basename）、`path`（相对仓库根）、`size`、`sha256`（`Get-FileHash -Algorithm SHA256` 计算），不得手写。无构建产物时留空数组，平台不展示空卡片。注意：归档 manifest（`archive-manifest-after.json`）记录的是 `.harness/archive/` 目录文件，不包含项目构建产物，两者不可混用。
 - `reportPipeline.commands[]` / `verificationChecks[]` / `validationIssues[]`：来自 `events.ndjson`、ledger、validate 结果。旧 archive 无 events 时可从 ledger/log/manifest 回放，不得编造。
 
 ## manifest/checksum
@@ -121,7 +120,7 @@ powershell.exe -NoProfile -ExecutionPolicy Bypass -File "harness-skills/harness-
 
 ## 页面内容
 
-final-summary 必须突出：
+平台归档摘要必须突出：
 
 1. 本次变更业务目标；
 2. 代码变更统计（diffStat：文件数 / insertions / deletions）；
@@ -134,34 +133,28 @@ final-summary 必须突出：
 禁止出现顶部 `N/A`、正文 `100%` 这类互相矛盾的数据。
 
 
-## final-summary 信息密度要求
+## summary-data 信息密度要求
 
-`summary-data.json` 至少包含 `verification`、`artifacts`、`reviewSummary`、`archiveManifest`、`maintenanceNotes`、`knownRisks`、`manualActions`。renderer 只根据 JSON 渲染，不在 HTML 中重新推理数据。
+`summary-data.json` 至少包含 `verification`、`artifacts`、`reviewSummary`、`archiveManifest`、`maintenanceNotes`、`knownRisks`、`manualActions`。平台只读取该 JSON，不重新推理或维护第二套统计。
 
-`artifacts` 与 `uncommittedTestEvidence` 为空数组时，renderer 不渲染对应卡片（"📦 产物清单"/"🧪 未提交测试证据"），避免空态噪音；非空才渲染。字段在 JSON 中始终保留，仅控制是否展示。
+`artifacts` 与 `uncommittedTestEvidence` 为空数组时，平台不展示对应卡片，避免空态噪音；非空时才展示。字段在 JSON 中始终保留，仅控制界面展示。
 
-## 渲染器
+## 数据校验
 
-默认渲染器为 Node.js：
+`validate` 是 finalize 的内嵌同进程步骤（不存在独立 `report validate` CLI）。validate error 存在时，finalize 恢复原 changes 目录并 exit 非 0，绝不删除原 changes 目录。warning 保留在报告中，但不会被误判为 validate error。Hunter Platform 直接读取已校验的 `summary-data.json`。
 
-```powershell
-powershell.exe -NoProfile -Command "& '<node-path>' 'harness-skills/harness-archive/templates/render-summary.mjs' --summary '.harness/changes/<change>/reports/final/summary-data.json' --out '.harness/changes/<change>/reports/final/final-summary.html'"
-```
-
-PowerShell HTML renderer 仅作 legacy fallback。该脚本以 UTF-8 with BOM 保存，确保 Windows PowerShell 5.1 正确识别编码（无 BOM 会被 5.1 按 ANSI/GBK 误读导致中文 label 乱码）；默认渲染器仍为 Node.js `render-summary.mjs`。
-
-**Python fallback（`harness_archive.py` 内置）**：Node 不可用/超时/exit 非 0/未产出文件时，`harness_archive.py render_final_summary` 自动降级为内置 Python fallback（`render_fallback_html`），渲染含 changeName、finalStatus、`reportPipeline.commands`（command/exitCode）、`verification`（unitTests/apiTests/dbCompatibility）、changedFiles、archiveManifest、knownRisks、manualActions、maintenanceNotes 的确定性 HTML；USER_SKIPPED/BLOCKED_BY_DBA/失败状态可见，所有动态值 HTML 转义。返回结构统一为 `{ok, renderer: node|python-fallback|none, fallbackReason, out_path}`。Node 与 Python fallback **都失败**（`renderer=none, ok=false`）时，finalize 立即恢复原 change 目录并 exit 非 0，**绝不归档无 final-summary.html 的变更**。
+正常完成时，`baseCommit` 与产品 tip 相同属于 `ARCHIVE_BASE_EQUALS_FEATURE_TIP`，必须在暂存前阻断。不得手工改 ledger 或 state snapshot。已有提交确属本变更时，使用 `adopt-existing-range` 生成绑定仓库、ownership 和 diffHash 的不可变收据；主动废弃或被替代时允许零产品增量，但必须记录中文原因，且固定 `releaseEligible=false`。
 
-`validate` 是 `harness_archive.py finalize` 的内嵌同进程步骤（不存在独立 `report validate` CLI）；validate error 存在时，finalize 恢复原 changes 目录并 exit 非 0，绝不删除原 changes 目录。**缺 final-summary.html 恒为 validate error**（不再有"没有 HTML 但只 warning"的分支）。
+候选收据缺失时，`execute` 可以复用身份一致、范围完整的 `unitTestFull` ledger 自动生成本地候选认证。提交只改变 commit 身份而产品树和验证输入未变化时，允许安全重绑定到当前 HEAD；该过程不得执行测试。门禁策略未声明数据库能力且未要求 `dbCompatibility` 时，数据库投影为带原因的 `NOT_APPLICABLE`，不得把缺少无关数据库证据升级为归档错误。
 
 ## 冻结优先 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 步骤**。
+finalize 在 collect 之前**冻结事件事实**：所有 archive-fact 事件落盘并 fsync 后，写入唯一的 `phase.end` 与 `evidence/evidence-cutoff.json`（`eventCount` + `sha256` + `frozenAt`）。cutoff 之后**禁止再向归档 events.ndjson 追加任何事件**；后续校验结果与 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，数字不得漂移。
+1. **source consistency**（`validate_source_consistency`）：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. **summary consistency**（`validate_summary_data`）：检查最终状态与验证结果是否矛盾，以及结构化字段是否满足归档要求。
 
 ## versioned repair（不改写原归档）
 
@@ -171,14 +164,14 @@ finalize 在 collect 之前**冻结事件事实**：所有 archive-fact 事件
 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 校验通过的版本提取条目。
+repair 先在 archive 外生成候选 derived version。来源校验与数据校验均通过后，才以不可变新版本写入 `derived/v<N>/{summary-data.json, repair-record.json}`，并把 `derived/authoritative.json` pointer 指向该版本；**原 summary-data.json 与 manifest 永不覆盖**。知识层只从 authoritative pointer 指向且 hash 校验通过的版本提取条目。
 
 ## 归档包与服务端知识 ingest（§8）
 
 archive close 的破坏性事务只执行确定性 close：
 
 ```text
-status -> manifest -> move -> collect -> render -> validate -> compare
+execute(one-shot status + gate) -> manifest -> move -> collect -> validate -> compare
 -> 生成确定性核心 ZIP -> 上传并等待服务端持久化/ingest 收据 -> stop AI service -> return
 ```
 
@@ -200,4 +193,4 @@ CONDITIONAL_OK
 
 run/test 本轮新增、更新或安全修复且被 `.gitignore` 忽略的测试，必须先由 `test-tracking.json` + `harness_test_guard.py stage` 精确提交；这类测试不得继续作为“未提交证据”收尾，也不得计入可复用 P0 验证后随 worktree 删除。
 
-`uncommittedTestEvidence` 只兼容历史归档或明确只读的外部证据：归档到 `backups/uncommitted-tests/`，记录文件名、验证范围与未提交原因，并在 final-summary 展示风险。若它是本轮可修改的回归测试，则 archive 必须阻断并要求先走精确跟踪流程。
+`uncommittedTestEvidence` 只兼容历史归档或明确只读的外部证据：归档到 `backups/uncommitted-tests/`，记录文件名、验证范围与未提交原因，并在 `summary-data.json` 中记录风险。若它是本轮可修改的回归测试，则 archive 必须阻断并要求先走精确跟踪流程。

package/harness/bundles/general/cursor/protocols/evidence-based-reporting-protocol.md

@@ -66,11 +66,11 @@ description: harness 全流程的证据化报告协议。所有 skill 输出必
 | `To <remote>` + 推送范围 | ✅ 推送成功 |
 | 无输出 | ❌ 状态未知 |
 
-## final-summary.html / summary-data.json 状态映射
+## summary-data.json 状态映射
 
-final-summary.html 默认由 `summary-data.json + render-summary.mjs` 渲染；旧占位符模板仅作 legacy reference。
+平台监控直接读取 `summary-data.json`。本地归档不再生成重复的 HTML 报告。
 
-归档前必须执行 `harness_archive.py finalize` 内嵌 validate，或 `harness_archive.py replay` 等价校验。只有 validate 无 error 时，才能宣称 final-summary 与 summary-data 一致；validate error 不得被写成 WARN 或"已完成"。
+归档前必须执行 `harness_archive.py finalize` 内嵌 validate，或使用 `harness_archive.py replay` 做等价校验。只有 validate 无 error 时，才能宣称报告数据有效；validate error 不得被写成 WARN 或「已完成」。
 
 | 数据来源 | 无报告时 |
 |----------|----------|
@@ -122,7 +122,7 @@ harness-review 对代码/变更的审查发现按风险分级，反映的是**
 | 标记 | 含义 | 适用场景 |
 |:----:|------|----------|
 | CONDITIONAL_OK | 条件性通过 | API 测试 `USER_SKIPPED` 或 DB 兼容性 `BLOCKED_BY_DBA` 时的归档最终状态，不得写纯 OK，必须在 knownRisks/manualActions 说明风险接受与后续人工动作 |
-| 🔁REUSED | 复用前阶段结果 | 复用了前一阶段验证结果，final-summary 必须显式标记，不得伪装成重新执行 |
+| 🔁REUSED | 复用前阶段结果 | 复用了前一阶段验证结果，summary-data 必须显式标记，不得伪装成重新执行 |
 | 📝ADVISORY | 参考性未运行 | review 参考性意见，未作为门禁执行 |
 | ⏭️ | 用户选择跳过 | 用户主动选择跳过某步骤（如仅本地 commit 不 push、跳过 test/review） |
 
@@ -131,4 +131,4 @@ harness-review 对代码/变更的审查发现按风险分级，反映的是**
 - skill 执行状态回答"这个步骤跑没跑、成没成"；
 - review 发现严重级回答"被审查的东西有没有问题、问题多大"；
 - 条件态/跳过态回答"这个步骤的最终结论是什么特殊情况"。
-- 三者独立：例如 test skill 可 ✅OK 执行成功，但 review 发现其覆盖的代码存在 RED 问题；又如 archive 可因 `USER_SKIPPED` 给出 CONDITIONAL_OK，同时 review 发现为 YELLOW。final-summary 必须分别展示，不得用一个维度覆盖另一个。
+- 三者独立：例如 test skill 可 ✅OK 执行成功，但 review 发现其覆盖的代码存在 RED 问题；又如 archive 可因 `USER_SKIPPED` 给出 CONDITIONAL_OK，同时 review 发现为 YELLOW。summary-data 必须分别记录，不得用一个维度覆盖另一个。

package/harness/bundles/general/cursor/protocols/ledger-protocol.md

@@ -14,7 +14,7 @@ description: verification-ledger、diffHash、service-fingerprint 的统一协
 - run 跑过测试命令（如 `mvn test`/`pytest`），test 阶段又原样跑一遍——浪费 3~8 分钟
 - submit/package 各自再 compile+test 一次——同一 diff 被验证三四轮
 - test 通过后用户改了一行注释/删了一个未用 import，package 不知道该不该重测，干脆全量重跑
-- final-summary 只展示全绿，看不出哪些是"重新执行"、哪些是"复用"、哪些是"小改动后复用"
+- 阶段汇总只展示全绿时，看不出哪些是「重新执行」、哪些是「复用」、哪些是「小改动后复用」
 
 verification-ledger 把每次验证（compile / unit test / api test / package）的**结果 + 证据 + 作用范围 + diffHash** 记下来，后续阶段先读 ledger 再决定是否重跑。
 
@@ -255,13 +255,13 @@ API 测试: 🔁 复用上一轮结果（diffHash 未变 / 仅清理性变更）
 | harness-run | 步骤 2 前读（确认是否已有 compile/unitTest 可复用） | 步骤 2 后写 compile + unitTest（若跑了全量测试） |
 | harness-test | Phase 1 前读（复用 run 的 unitTest） | Phase 1/2 后写 unitTest + apiTest |
 | harness-submit | 验证前读（复用 test 的 compile/unitTest） | 若重跑则写回 |
-| harness-archive | 归档前读（汇总各阶段状态用于 final-summary） | 不写（归档时一并移入 archive） |
+| harness-archive | 归档前读（汇总各阶段状态，写入 `summary-data.json` 并上传平台） | 不写（归档时一并移入 archive） |
 
-## 八、状态与 final-summary 的对应
+## 八、状态与归档投影的对应
 
-ledger 的 `status` 与 final-summary 展示状态对应：
+ledger 的 `status` 与 `summary-data.json`、平台监控中的展示状态对应：
 
-| ledger status | 含义 | final-summary 标记 |
+| ledger status | 含义 | 归档与平台标记 |
 |:---:|------|------|
 | `OK`（本阶段真实执行并通过） | 真实验证 | ✅OK |
 | `OK` 但本阶段复用了前一阶段 | 复用 | 🔁REUSED |
@@ -270,7 +270,7 @@ ledger 的 `status` 与 final-summary 展示状态对应：
 | `ADVISORY` | review 参考性 | 📝ADVISORY |
 | postTestClassification=NON_BEHAVIORAL_CLEANUP | 小清理 | 🧹NON_BEHAVIORAL_CLEANUP |
 
-**强制规则**：任何阶段若复用了前一阶段结果，final-summary 必须显示 `🔁REUSED`，**不得伪装成重新执行**。
+**强制规则**：任何阶段若复用了前一阶段结果，`summary-data.json` 与平台监控必须显示 `🔁REUSED`，**不得伪装成重新执行**。
 
 ## 九、Ledger v2（cluster 2）
 
@@ -329,7 +329,7 @@ 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` |
+| `baseCommit` | `--base-commit` → 既有 ledger 值 → `state-snapshot.json.changeBase`。只有全新 change 的首次 ledger 写入可以用当时 HEAD 建立基线；旧 ledger 迁移缺少以上三种证据时必须报错，禁止用迁移时的当前 HEAD 猜测基线 |
 | `currentHead` | `git rev-parse --verify HEAD`（验证执行时） |
 | `diffHash` | `--diff-hash` → 既有 ledger 值 → 按 ownership 范围重算（§10.3） |
 | `ownershipHash` | 契约 `ownership` 段规范化 JSON 的 sha256 |

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

@@ -1,5 +1,5 @@
 ---
-description: 结构化事件、summary-data 生成、final-summary 校验和外部可观测性边界协议（finalize/replay）。
+description: 结构化事件、summary-data 生成与校验，以及外部可观测性边界协议（finalize/replay）。
 ---
 
 # Report Pipeline Protocol
@@ -10,7 +10,7 @@ description: 结构化事件、summary-data 生成、final-summary 校验和外
 
 1. **Event Layer**：`events.ndjson` 记录结构化执行事实。
 2. **Report Data Layer**：`summary-data.json` 由程序或确定性规则生成。
-3. **Renderer / Final Report Layer**：`final-summary.html` 只渲染和解释 summary-data，不重新推理统计。
+3. **Platform View Layer**：Hunter Platform 读取 `summary-data.json` 并展示结果，不在本地保存重复报告。
 
 模型可以写维护者结论、风险解释和人工判断，但不得凭印象手写统计数字、通过率、耗时、命令结果或 artifact hash。
 
@@ -19,12 +19,12 @@ description: 结构化事件、summary-data 生成、final-summary 校验和外
 Skill-bundled 脚本（推荐）：
 
 ```powershell
-python <skills-root>/scripts/harness_archive.py finalize --change-dir ".harness/changes/<change-name>" --archive-root ".harness/archive" --json
+python <skills-root>/scripts/harness_archive.py execute --change-dir ".harness/changes/<change-name>" --archive-root ".harness/archive" --intent record-only --closure completed --json
 python <skills-root>/scripts/harness_archive.py replay --archive-dir ".harness/archive/YYYY-MM-DD-<change-name>" --json
 python <skills-root>/scripts/harness_events.py append --change-dir ".harness/changes/<change-name>" --phase "<phase>" --type <type> [--note "..."]
 ```
 
-归档报告流水线只有两个入口，均由 `harness_archive.py` 提供：`collect`/`render`/`validate` 是 `finalize` 的内嵌同进程步骤，**不再作为独立 CLI 暴露**（不存在 `report collect`/`report validate` 子命令）。`summary-data.json` 只能由 `finalize`（归档时）或 `replay`（回放时）生成；**禁止 agent 临场手写或拼装等价的 `summary-data.json`**。`harness_archive.py` 不可用时归档失败退出，不得退回手写汇总。
+归档报告流水线的常规入口是 `execute`。它只采集一次状态并复用给内部 finalize；`collect` 与 `validate` 是 finalize 的内嵌同进程步骤，**不作为独立 CLI 暴露**（不存在 `report collect` / `report validate` 子命令）。`summary-data.json` 只能由 finalize（归档时）或 `replay`（回放时）生成；**禁止 agent 临场手写或拼装等价的 `summary-data.json`**。`harness_archive.py` 不可用时归档失败退出，不得退回手写汇总。
 
 ## events.ndjson
 
@@ -141,15 +141,16 @@ summary-data 必须保留原 archive final report 维度，并增加事件层摘
 
 新增 `reportPipeline` 不替代这些字段；它负责为这些字段提供可追溯的数据来源和一致性校验结果。
 
-## finalize 责任边界（`harness_archive.py finalize`）
+## execute 与 finalize 责任边界
+
+`execute` 负责一次性状态采集、自动门禁、准备耗时事件和对 finalize 的单次调用。常规调用者不得串行执行 `auto-gate`、`status`、`finalize`。finalize 负责正式归档尝试，并复用 execute 传入的预检结果。
 
 | 阶段 | 责任 | 写入 |
 |---|---|---|
 | `collect` | 从 events/ledger/log/manifest/report/git evidence 收集事实 | `summary-data.json` |
-| `render` | 由 `render-summary.mjs` 渲染 final-summary | `final-summary.html` |
-| `validate` | 检查 final-summary 是否覆盖 summary-data 关键事实 | issues；不得静默忽略 error |
+| `validate` | 检查 summary-data 的身份、验证状态与事实是否一致 | issues；不得静默忽略 error |
 
-> **已废弃**：独立 `enrich` 步骤与 `harness-report` skill；全部并入 `finalize` 单命令。回放见 `harness_archive.py replay`。
+> **已废弃**：独立 `enrich` 步骤与 `harness-report` skill；报告生成并入 finalize，常规归档由 `execute` 调用。回放见 `harness_archive.py replay`。
 
 `validate` error 存在时，`harness-archive` 不得删除原 changes 目录。
 
@@ -168,4 +169,4 @@ summary-data 必须保留原 archive final report 维度，并增加事件层摘
 
 - 可保留 `reportPipeline.externalTraceRefs[]` 等扩展字段。
 - 不得要求外部服务可用才允许 archive 成功。
-- 未来接入也必须以 `events.ndjson` 和 `summary-data.json` 为稳定合同，不改变 final-summary 质量维度。
+- 未来接入也必须以 `events.ndjson` 和 `summary-data.json` 为稳定合同，不改变结构化报告的质量维度。

package/harness/bundles/general/cursor/protocols/sensitive-info-protocol.md

@@ -1,10 +1,10 @@
 ---
-description: harness 全流程的敏感信息脱敏协议。所有 skill 的输出（控制台、execution-log、报告、commit message、final-summary）按本协议脱敏，禁止明文 token/密码/密钥。由原 harness-plan/sensitive-info.md 迁移。
+description: harness 全流程的敏感信息脱敏协议。所有 skill 的输出（控制台、execution-log、报告、commit message、summary-data）按本协议脱敏，禁止明文 token/密码/密钥。由原 harness-plan/sensitive-info.md 迁移。
 ---
 
 # Sensitive Info Protocol
 
-> 本协议适用于所有 harness-skills 的输出（控制台、execution-log.md、package-report、review-report、final-summary.html、commit message）。
+> 本协议适用于所有 harness-skills 的输出（控制台、execution-log.md、package-report、review-report、summary-data.json、commit message）。
 
 ## 1. 禁止明文输出的信息类型
 
@@ -49,7 +49,7 @@ description: harness 全流程的敏感信息脱敏协议。所有 skill 的输
 | 执行日志 | `.harness/changes/<change-name>/logs/execution-log.md` |
 | 审查报告 | `.harness/changes/<change-name>/reports/review/review-report-*.md` |
 | 测试报告 | `.harness/changes/<change-name>/reports/test/test-report-*.md` |
-| 最终总结 | `.harness/archive/YYYY-MM-DD-<change-name>/reports/final/final-summary.html` |
+| 最终总结数据 | `.harness/archive/YYYY-MM-DD-<change-name>/reports/final/summary-data.json` |
 | 归档元数据 | `.harness/archive/YYYY-MM-DD-<change-name>/meta/archive-meta.md` |
 | Commit message | git log 中的提交信息 |
 

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

@@ -55,8 +55,7 @@ description: harness .harness 状态目录分层协议。用于减少根目录
 │   ├── review/
 │   ├── package/
 │   └── final/
-│       ├── summary-data.json
-│       └── final-summary.html
+│       └── summary-data.json
 ├── sqls/
 ├── scripts/
 ├── runtime/
@@ -117,7 +116,6 @@ package SHA-256，且服务端同时确认 `archive_status=durable` 与
 | worktree | `meta/worktree.json` | `worktree.json` |
 | run status | `evidence/run-task-status.md` | `run-task-status.md` |
 | final summary data | `reports/final/summary-data.json` | `summary-data.json` |
-| final report | `reports/final/final-summary.html` | `final-summary.html` |
 
 ## 写入规则
 
@@ -143,7 +141,7 @@ package SHA-256，且服务端同时确认 `archive_status=durable` 与
 
 ## state-snapshot.json（cluster 3 §3.6）
 
-`meta/state-snapshot.json`（由 `harness_state.py` 写入）集中记录 project/worktree root、HEAD/base、profile/rules/map/knowledge/diff 各段指纹与相关文件。plan/run/test/review/submit 读取该快照；失效时由脚本刷新，**不得仅凭缓存跳过代码或验证门禁**。
+`meta/state-snapshot.json`（由 `harness_state.py` 写入）集中记录 project/worktree root、不可变 `changeBase`、当前 HEAD，以及 profile/rules/map/knowledge/diff 各段指纹与相关文件。Plan 首次捕获把当时 HEAD 写入 `changeBase`；run/test/review/submit/archive 刷新时只能更新当前 HEAD 和各段指纹。失效时由脚本刷新，**不得仅凭缓存跳过代码或验证门禁，也不得把后续 HEAD 覆盖为变更基线**。
 
 schema：
 
@@ -152,6 +150,7 @@ schema：
   "schemaVersion": 1,
   "generatedAt": "<iso>",
   "changeName": "<change-name>",
+  "changeBase": "<首次 Plan 捕获的 sha>",
   "project": {"root": "<abs>"},
   "worktree": {"root": "<abs>"},
   "git": {"base": "<sha>", "head": "<sha>"},
@@ -161,13 +160,13 @@ schema：
 }
 ```
 
-各段独立失效：`is_segment_stale(snapshot, segment, current_fingerprint)` 比较单段指纹；段不存在 → stale（需采集）。`refresh_segments(..., segments=["profile"])` 只重采受影响段，其他段保留原 capturedAt/fingerprint（缓存失效只重采受影响段）。
+各段独立失效：`is_segment_stale(snapshot, segment, current_fingerprint)` 比较单段指纹；段不存在 → stale（需采集）。`refresh_segments(..., segments=["profile"])` 只重采受影响段，其他段保留原 capturedAt/fingerprint（缓存失效只重采受影响段）。`git.base` 是 `changeBase` 的兼容镜像，不是每次 capture 的 HEAD。
 
 segment 的文件集由调用方（各 skill）决定：`capture_snapshot(..., segment_files={"profile": [...], "rules": [...]})`。snapshot 只负责采集 + 比对 + 失效，不负责发现文件。git 段记录 base/head；diff 段指纹由调用方按需用 `harness_ledger.compute_diff_hash` 采集后填入 segment_files。
 
 ## archive 结构
 
-archive 后保持同样分层结构，不把 `.bak`、脚本、manifest、HTML 全部放在 archive 根目录。
+archive 后保持同样分层结构，不把 `.bak`、脚本、manifest 或其他生成文件堆在 archive 根目录。
 
 未提交但用于验证的测试文件放入：