hunter-harness 0.1.3 → 0.2.0

package/resources/harness/bundles/general/codex/harness-archive/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: harness-archive
+description: 归档所有变更产出（计划/测试报告/审查/SQL/API文档）到
+  .harness/archive/，含归档元数据和可视化最终总结。使用场景：归档、完成归档、收尾、打包产出物
+---
+<!-- generated by harness_deploy.py; core=560f9757ad576d78; overlay=none; agent=codex; do not edit -->
+# harness-archive — 变更归档
+
+## Purpose
+
+将 `.harness/changes/<change-name>/` 的所有产出移入 `.harness/archive/YYYY-MM-DD-<change-name>/`，生成归档元数据和可视化最终报告，释放工作区。
+
+## When to Use
+
+使用场景：
+
+- 用户说"归档 / 完成归档 / 收尾 / 打包产出物"。
+- submit 已推送、test/review 报告已就绪（或已明确标记跳过/未运行），需要封存变更产出。
+- 变更闭环最后一站，归档后从工作区移除 `.harness/changes/<change-name>/`。
+
+跳过场景：
+
+- 变更尚未 submit 推送（归档前 commit 必须已 push）。
+- 仍存在未结清的 test/review 验证（除非已明确标记 CONDITIONAL_OK）。
+
+自动调用边界：
+
+- 归档涉及移动/删除原变更目录，支持被其他 skill 调用，但调用前必须确保前置条件已满足；也支持用户显式 `/harness-archive` 调用。
+- 归档前确认是强制阻断检查点，用户拒绝 → 终止流程，不执行任何操作。
+
+## 前置条件
+
+- commit 已 push（`git log @{u}..HEAD` 输出为空）
+- **最终 hash 来源**：worktree 模式（`meta/worktree.json` requested=true）下读 ledger 的 `mergeFinalHash`（由 `/harness-submit` 合并段写入）；主目录模式读 submit 的 `final pushed hash`。当前 `git rev-parse HEAD` 须一致
+- test 报告存在或标记"跳过"；review 报告存在或标记"未运行 review"（review 不阻塞归档）
+
+## Inputs
+
+- `$ARGUMENTS`：变更名（可选，留空时 Glob `.harness/changes/*/plans/*-plan.md` 自动检测，排除 `.harness/archive/`）
+- 相关文件：`.harness/changes/<change-name>/logs/execution-log.md`、`.harness/changes/<change-name>/events.ndjson`、`evidence/verification-ledger.json`、各阶段 reports/
+
+## 统一读取协议
+
+1. **`.harness/changes/<change-name>/` 是唯一真相源** — 所有输入从该目录读取，产物写入对应子目录
+2. **change-name 优先从 frontmatter 读取** — `spec/*-design.md`、`plans/*-plan.md` 的 YAML `change-name`
+3. **frontmatter 缺失时兼容旧格式** — 从路径推断，标记 `🟡 legacy-plan`，不失败
+4. **spec** — 设计真相源：`spec/<change>-design.md`
+5. **plan** — 任务真相源：`plans/<change>-plan.md`
+6. **implementation-detail** — 自适应执行参考；legacy 缺失 🟡WARN，不阻断
+7. **test-scenarios** — 测试真相源：`plans/<change>-test-scenarios.md`
+8. **禁止读取 `docs/superpowers/` 作为正式输入** — 旧草稿仅人工线索
+
+状态目录分层：新路径优先，旧路径兼容 → [[../protocols/state-layout-protocol.md|state-layout-protocol]]
+
+## Workflow
+
+### Phase 0：读取规则和上下文
+
+1. 读取本文件。
+2. 按需读取 `reference.md`（归档流程、manifest、summary-data、final-summary 渲染、目录结构与最终状态规则）。
+3. 读取共用约束：
+   - `../protocols/archive-report-protocol.md`
+   - `../protocols/state-layout-protocol.md`
+   - `../protocols/powershell-protocol.md`
+   - `../protocols/sensitive-info-protocol.md`
+   - `../protocols/evidence-based-reporting-protocol.md`
+   - `../protocols/report-pipeline-protocol.md`
+4. 解析 `$ARGUMENTS`：留空时 Glob 自动检测未归档变更，排除 `.harness/archive/`。
+
+### Phase 1：确认归档对象（扫描未归档变更）
+
+用 Glob 搜索 `.harness/changes/*/plans/*-plan.md`（排除 `.harness/archive/`），展示变更概要。
+
+- **Read `checklist.md`** — 归档前检查项
+- 发现多个未归档变更 → 让用户选择或终止
+
+### Phase 2：确认归档 ⚠️ 强制阻断
+
+AskUserQuestion 让用户确认归档操作。**用户拒绝 → 终止流程，不执行任何操作。**
+
+- **Read `reference.md`** — 确认对话框的内容格式
+
+### Phase 3：执行归档
+
+1. append `phase.start` 事件。
+2. 运行 `python <skills-root>/scripts/harness_archive.py status --change-dir ".harness/changes/<change-name>" --json` 前置检查。
+3. 运行 `python <skills-root>/scripts/harness_archive.py finalize --change-dir ".harness/changes/<change-name>" --archive-root ".harness/archive" --json`；读 JSON（移动、collect、render、validate、manifest 比对）。**finalize 不再同步执行知识维护**（§8.2）：它写一个 `pending` maintenance-outbox 项即返回，`knowledgeMaintenance=QUEUED`；写 outbox 失败时 `NOT_QUEUED`（warning，不回滚 archive，总状态 CONDITIONAL）。后续由 `harness-sync` / `harness_knowledge.py maintain` 异步推进 outbox。
+4. 模型补写 `meta/archive-meta.md` 的维护者结论 / knownRisks / manualActions（脚本占位字段）。
+5. append `phase.end` 事件。**finalize 失败或 validate 报错时不删除原目录**。
+
+- **Read `reference.md`** — finalize 输出字段、archive-meta 格式、CONDITIONAL_OK 规则
+- **Read `templates/summary-data-template.json`** — summary-data 数据结构
+- **Read `templates/render-summary.mjs`** — final-summary 渲染脚本（finalize 内嵌调用）
+
+### Phase 4：验证与提示
+
+验证归档目录完整 → 提示用户归档完成。
+
+- **Read `checklist.md`** — 归档后验证项
+
+## P0 执行可信度规则
+
+- 命令结果不得靠猜测；普通 Bash 被拒 → 立即改用等价 PowerShell 重试一次
+- 仅 PowerShell 成功且有明确证据（构建/git/测试输出、文件存在、exit 0）时可标 ✅OK；否则 ❌FAIL 或 🟡WARN
+- 禁止把 hook 拒绝、静态验证、无输出、用户跳过说成成功 → 详见 [[../protocols/powershell-protocol.md|powershell-protocol]]、[[../protocols/evidence-based-reporting-protocol.md|evidence-based-reporting-protocol]]
+
+## 关键规则（硬门禁速查）
+
+> 每条规则的详细判定、模板见 `reference.md` 对应章节；归档报告协议见 `../protocols/archive-report-protocol.md`，Shell 执行安全见 `../protocols/powershell-protocol.md`，敏感信息见 `../protocols/sensitive-info-protocol.md`，证据化报告见 `../protocols/evidence-based-reporting-protocol.md`，状态目录见 `../protocols/state-layout-protocol.md`。
+
+### 一、同一时间最多 1 个未归档变更
+
+扫描排除 `.harness/archive/`；多个未归档变更 → 让用户选择或终止，不批量归档。
+
+### 二、归档前确认是强制阻断检查点
+
+AskUserQuestion 确认；用户拒绝 → 终止，不执行任何操作。
+
+### 三、文件移动只用内置工具或 PowerShell
+
+移动用 Read+Write+验证 或 PowerShell；**禁止 Bash mv/cp/rm**。移动失败时不删除原目录，报错退出让用户手动处理。
+
+### 四、数据化归档门禁（先数据后渲染）
+
+必须通过 `harness_archive.py finalize` 生成 `reports/final/summary-data.json` 与 `final-summary.html` 并完成 validate；**禁止模型临场写 500+ 行 HTML**。统计数字只能来自 summary-data、events、ledger 或 manifest。详见 `../protocols/report-pipeline-protocol.md`、`../protocols/archive-report-protocol.md`、`reference.md`。
+
+### 五、manifest/checksum 必须存在
+
+归档前后生成 `evidence/archive-manifest-before.json` / `archive-manifest-after.json`（path/size/sha256），before/after 不一致时**不得删除原目录**。复杂 PowerShell 写入 `scripts/*.ps1` 后 `-File` 执行，禁止内联 `$` / `$_` / `@{}`。详见 `reference.md`。
+
+### 六、归档前确认四项（缺一不可）
+
+- commit 已 push（`git log @{u}..HEAD` 输出为空）
+- **final hash 来源**：worktree 模式（requested=true）下读 ledger `mergeFinalHash`（submit 合并段）；否则读 submit 日志 `final pushed hash`。当前 HEAD 须一致
+- test 报告存在，或标记"跳过"/"未运行测试"
+- review 报告：存在则作 📝ADVISORY 归档材料；不存在标记"📝ADVISORY：未运行 review"（review 不阻塞归档）
+
+### 七、verification-ledger 汇总状态
+
+归档前读 `evidence/verification-ledger.json`，提取各阶段 status、postTestClassification、复用关系，供 final-summary 真实展示状态演进。若 ledger 有 `postTestClassification`，final-summary 必须展示该分类及对应的复用/重测决策。
+
+### 八、final-summary 不得伪造且必须展示状态演进
+
+无测试报告 → 显示"未运行测试 / 静态验证"，不得 100% 通过率；无 review → "📝ADVISORY：未运行 review"。状态用 ✅OK / 🟡WARN / 🔁REUSED / 🔁RETESTED / 📝ADVISORY / 🧹NON_BEHAVIORAL_CLEANUP，复用前一阶段结果显示 🔁REUSED，**不得伪装成重新执行，不得无脑全绿**。
+
+**final-summary 必须产出**：Node 渲染器不可用/超时/exit 非 0/未产出文件时，`harness_archive.py` 自动用内置 Python fallback 渲染（含 changeName/finalStatus/commands/verification/changedFiles/archiveManifest/knownRisks/manualActions/maintenanceNotes，USER_SKIPPED/BLOCKED_BY_DBA/失败状态可见，全部 HTML 转义）。Node 与 Python fallback **都失败**时，finalize 立即恢复原 change 目录并 exit 非 0，**绝不归档一个没有 final-summary.html 的变更**。
+
+### 九、CONDITIONAL_OK 最终状态
+
+API 测试 `USER_SKIPPED` 或 DB 兼容 `BLOCKED_BY_DBA` 时，最终状态必须是 `CONDITIONAL_OK`，不能显示纯 `OK`。
+
+### 十、未提交测试文件归档
+
+未提交但用于验证的测试文件必须归档到 `backups/uncommitted-tests/` 并在 final-summary 中展示。
+
+### 十一、phase.start 事件前置
+
+阶段 0 之前必须先 append `phase.start` 事件（`harness_events.py append`）；不得等归档完成才补。归档后 events.ndjson 与自动渲染的 execution-log.md 一起移入 archive。
+
+### 十二、Shell 安全 / 敏感信息 / 证据化报告
+
+git 命令通过 `powershell.exe -Command "..."` 执行；archive-meta.md 和 final-summary.html 不得含明文 token/密码/密钥；归档报告必须区分 ✅真实成功 / 🟡跳过·静态验证 / ❌失败。
+
+## Output Format
+
+> 归档元数据格式见 `reference.md` 的 archive-meta 模板；最终报告由 `templates/summary-data-template.json` 数据结构 + `templates/render-summary.mjs` 固定脚本渲染。
+
+产出文件：
+
+- `.harness/archive/YYYY-MM-DD-<change-name>/meta/archive-meta.md` — 归档元数据
+- `.harness/archive/YYYY-MM-DD-<change-name>/events.ndjson` — 结构化事件层（新流程推荐；旧 archive 可缺失）
+- `.harness/archive/YYYY-MM-DD-<change-name>/reports/final/summary-data.json` — 最终报告数据源
+- `.harness/archive/YYYY-MM-DD-<change-name>/reports/final/final-summary.html` — 由 `render-summary.mjs` 渲染（Node 不可用或失败时由 `harness_archive.py` 内置 Python fallback 渲染）；**始终必须存在**，否则 finalize 恢复原 change 目录并 exit 非 0
+- `.harness/archive/YYYY-MM-DD-<change-name>/evidence/archive-manifest-before.json` / `archive-manifest-after.json` — 归档前后 manifest/checksum
+
+## 渐进披露
+
+- **Read `checklist.md`** 仅在 Phase 1 归档前检查和 Phase 4 验证时 — 含归档前检查项和归档后验证项
+- **Read `reference.md`** 仅在 Phase 0/2/3 时 — 含归档流程、archive-meta 格式、summary-data 字段说明、final-summary 渲染规则、目录结构与最终状态规则
+- **Read `reference.md`** 仅在 Phase 3 finalize 时 — summary-data、final-summary 校验与 archive-meta 补写
+- **Read `templates/summary-data-template.json`** 仅在 Phase 3 生成 `summary-data.json` 时 — 含最终报告数据结构
+- **Read `templates/render-summary.mjs`** 仅在 Phase 3 渲染 `final-summary.html` 时 — 固定 HTML 渲染脚本
+
+## 交互白名单
+
+**仅允许**归档确认（Phase 2 AskUserQuestion）；拒绝 → 终止，不执行任何移动。
+
+## 执行日志
+
+`events.ndjson` 为唯一事实源（schema_version 2，`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止手工 Edit**。结构 → [[../protocols/report-pipeline-protocol.md|report-pipeline-protocol]]
+
+```powershell
+python <skills-root>/scripts/harness_events.py append --change-dir ".harness/changes/<change-name>" --phase <phase> --type phase.start --note "<触发指令>"
+```
+
+> **脚本接线**：`harness_events.py append`；`harness_archive.py finalize`；`harness_preflight.py check`；`harness_ledger.py can-reuse`；`harness_service.py ensure/stop`（须 `--files`/`serviceStart.inputFiles`）。JSON 输出按 D13 护栏解读。
+
+> **Task 4 §6.1 写入契约**：普通 `append` = 加锁 -> 追加一行 -> fsync -> 解锁，**不 load 历史、不渲染**（O(1)，跨进程锁 `events.ndjson.lock`，UUID 用完整 `uuid4().hex` 无需去重扫描）。仅 `--type phase.end` append 在追加成功后渲染一次 `execution-log.md`；显式 `harness_events.py render` 随时从完整 events 重建；`harness_archive.py finalize` 在 collect 前强制 render 一次。高频 command append 期间 log 可能滞后，phase 边界保持最新。

package/resources/harness/bundles/general/codex/harness-archive/checklist.md

@@ -0,0 +1,52 @@
+---
+description: harness-archive 的归档前检查项和归档后验证项。仅在 Phase 1 检查和 Phase 4 验证时读取。
+---
+
+# harness-archive 检查清单
+
+## P0 数据化归档门禁
+
+归档遵循 `../protocols/archive-report-protocol.md`，门禁要点见 SKILL.md `## 关键规则` 四/五/九：
+
+- 先写 `reports/final/summary-data.json`，再渲染 `reports/final/final-summary.html`。
+- 归档前生成 `evidence/archive-manifest-before.json`，移动后生成 `archive-manifest-after.json`。
+- final-summary 的统计只能来自 summary-data 或 manifest。
+- before/after checksum 不一致时，不得删除原目录。
+- 默认渲染器 `templates/render-summary.mjs`（finalize 内嵌调用）。
+
+## 归档前检查（Phase 1）
+
+> ⚠️ **phase.start 前置**：在归档前检查的第一项前，必须先 append `phase.start` 事件（见 SKILL.md `## 执行日志`）。不得等归档完成才补。
+
+- [ ] 已 append `phase.start` 事件（`harness_events.py append --change-dir ".harness/changes/<change-name>"`）
+- [ ] 只有一个未归档变更目录（多个时终止或让用户选择）
+- [ ] 变更目录下有 plans/ 子目录（至少有计划文件）
+- [ ] `logs/execution-log.md` 存在（需要追加归档记录；新路径缺失时兼容根目录 `execution-log.md`）
+- [ ] 准备生成 `archive-manifest-before.json`（path/size/sha256）
+- [ ] 准备生成 `summary-data.json`（业务目标、阶段状态、验证、产物、维护者结论）
+- [ ] git status 无未提交的重要变更（归档应对应已提交的代码）
+- [ ] **commit 已 push**：`powershell.exe -Command "git -C '<项目路径>' log @{u}..HEAD --oneline"` 输出为空（无未推送提交）
+- [ ] **最终 hash 一致**：worktree 模式（requested=true）下读 `evidence/verification-ledger.json` 的 `mergeFinalHash`（submit 合并段写入），否则从 events/ledger 读取 `final pushed hash`，与当前 `git rev-parse HEAD` 比对
+- [ ] **test/review 报告状态确认**：
+  - ✅ `.harness/changes/<change-name>/tests/test-report-*.md` 存在 → 归档正常
+  - 🟡 不存在 → 必须在 archive-meta.md 和 final-summary.html 中标记"跳过测试"或"未运行测试"，不得伪造通过率
+  - ✅ `.harness/changes/<change-name>/reports/review/review-report-*.md` 存在（旧路径 `reviews/review-report-*.md` 兼容回退）→ 作为 📝ADVISORY 归档材料
+  - 📝 `.harness/changes/<change-name>/reports/review/fixback-*.md` 存在 → 随 review 报告一并归档；默认 advisory，除非 `strict-review-gate=true`
+  - 🟡 不存在但 `logs/execution-log.md` 有 harness-review 小节 → **review 已运行但未落盘**（harness-review `context:fork` 交接缝常见，见 `agent/case-candidates/2026-06-30-harness-review-forked-not-persisting-report.md`）：从 execution-log/会话补落盘到 `reports/review/review-report-YYYYMMDD-HHmm.md` 再归档，**不得误标"未运行 review"**（实际跑过）
+  - 🟡 不存在且 execution-log 无 review 小节 → 在 archive-meta.md 和 final-summary.html 中标记"📝ADVISORY：未运行 review"
+
+## 归档后验证（Phase 4）
+
+- [ ] `.harness/archive/YYYY-MM-DD-<change-name>/` 目录存在（通过 Glob 实际扫描确认）
+- [ ] 所有子目录（plans/, tests/, reviews/, sqls/）已完整移入（通过 Glob 实际扫描确认，不仅看预期路径）
+- [ ] before/after manifest 校验通过（排除 `logs/execution-log.md`——归档追加结束记录预期 sha256 变化；其他 moved 文件 sha256 必须一致，missing/mismatch=0）
+- [ ] archive-meta.md 已创建，frontmatter 字段完整
+- [ ] summary-data.json 已生成，且为合法 JSON
+- [ ] final-summary.html 已由 `templates/render-summary.mjs` 渲染生成
+- [ ] **final-summary.html 真实性检查**：
+  - 无测试报告时，`summary-data.json.verification.unitTests.status` / `summary-data.json.verification.apiTests.status` 必须标记为 `NOT_RUN`、`USER_SKIPPED`、`BLOCKED` 或 `STATIC_ONLY`，不得显示 100%
+  - 无 review 报告时，`summary-data.json.reviewSummary.status` 必须标记为 `ADVISORY_NOT_RUN`，不得显示 100%
+  - 跳过、复用、人工确认的部分必须明确标记，不伪装成 ✅
+  - final-summary.html 中不得残留 `{{...}}` 占位符
+- [ ] 原目录 `.harness/changes/<change-name>/` 已删除（仅在前面所有验证通过后）
+- [ ] .harness/ 下无残留未归档变更目录

package/resources/harness/bundles/general/codex/harness-archive/reference.md

@@ -0,0 +1,103 @@
+---
+description: harness-archive 的归档流程、manifest、summary-data、final-summary 渲染、目录结构与最终状态规则。
+---
+
+# harness-archive 参考
+
+## 归档流程（对齐 SKILL.md Workflow）
+
+- **Phase 0 读取上下文**：读 SKILL.md / 本文件 / 共用协议（`../protocols/archive-report-protocol.md`、`../protocols/report-pipeline-protocol.md`、`../protocols/state-layout-protocol.md`、`../protocols/powershell-protocol.md`、`../protocols/sensitive-info-protocol.md`、`../protocols/evidence-based-reporting-protocol.md`）/ 解析 `$ARGUMENTS`。
+- **Phase 1 确认归档对象**：Glob `.harness/changes/*/plans/*-plan.md`（排除 archive），展示概要；多变更让用户选择或终止。
+- **Phase 2 确认归档（强制阻断）**：AskUserQuestion 确认，拒绝即终止。
+- **Phase 3 执行归档**：
+  1. append `phase.start` 事件（`harness_events.py append`）。
+  2. 运行 `python <skills-root>/scripts/harness_archive.py status --change-dir ... --json` 做前置检查。
+  3. 运行 `python <skills-root>/scripts/harness_archive.py finalize --change-dir ... --archive-root ".harness/archive" --json`；读 JSON 结果。
+  4. 模型补写 `meta/archive-meta.md` 的 `maintenanceNotes` / `knownRisks` / `manualActions`（脚本留空占位）。
+  5. append `phase.end` 事件。**finalize 报错或 validate 失败时不删除原 changes 目录**。
+- **Phase 4 验证与提示**：见 `checklist.md` 归档后验证项。
+
+## manifest 生成
+
+manifest 每项包含：
+
+```json
+{"path":"...","size":123,"sha256":"...","lastModified":"..."}
+```
+
+建议使用固定脚本，禁止内联复杂 PowerShell（包含 `$`、`$_`、`@{}`、script block、管道 JSON 输出）：
+
+```powershell
+powershell.exe -NoProfile -ExecutionPolicy Bypass -File "harness-skills/harness-archive/scripts/gen-manifest.ps1" -RootPath ".harness/changes/<change>" -OutputPath ".harness/changes/<change>/evidence/archive-manifest-before.json"
+```
+
+移动到 archive 目录后，再生成 after manifest：
+
+```powershell
+powershell.exe -NoProfile -ExecutionPolicy Bypass -File "harness-skills/harness-archive/scripts/gen-manifest.ps1" -RootPath ".harness/archive/<date-change>" -OutputPath ".harness/archive/<date-change>/evidence/archive-manifest-after.json"
+```
+
+**校验 before/after 时排除 execution-log**（通用）：`logs/execution-log.md` 在归档过程会追加结束记录（Phase 4），before（移动前含开始记录）与 after（含开始+结束记录）sha256 必然不同——这是预期追加，非文件损坏。校验脚本需跳过 `logs/execution-log.md`，其他 moved 文件 sha256 必须一致；若其他文件 missing/mismatch，才表示移动损坏，不得删除原目录。
+
+## summary-data.json 与 harness_archive.py
+
+默认由 `harness_archive.py finalize`（或 `replay`）生成/校验 `reports/final/summary-data.json`；CLI 不可用时按 `../protocols/report-pipeline-protocol.md` 与 `templates/summary-data-template.json`（schemaVersion 2.2）生成等价数据。必须保留原 final report 维度。必须包含：
+
+- `businessGoal`：本次变更为了做什么；
+- `stageStatus`：plan/run/test/review/submit/archive；
+- `diffStat`：filesChanged/insertions/deletions/range —— 来自 `git diff --numstat` + `git diff --stat <base>..<head>`，不得手写；
+- `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`；
+- `changedFiles`：path/summary/insertions/deletions —— 来自 `git diff --numstat <base>..<head>`；
+- `reviewSummary`：red/yellow + redFixed/redConfirmed/yellowFixed/yellowDeferred 修复进度；
+- `maintenanceNotes`：给后续维护者看的结论；
+- `knownRisks`：剩余风险或人工确认项。
+
+报告必须突出业务目标和维护者结论。所有统计数字只能来自 events、summary-data、ledger 或 manifest，不得手写另一套。历史 archive 没有 `events.ndjson` 时，允许从 ledger/log/manifest 回放，并在 `reportPipeline.sources` 中记录来源。
+
+## final-summary 渲染
+
+默认使用 Node.js 渲染器：
+
+```powershell
+powershell.exe -NoProfile -Command "& '<node-path>' 'harness-skills/harness-archive/templates/render-summary.mjs' --summary '.harness/archive/<date-change>/reports/final/summary-data.json' --out '.harness/archive/<date-change>/reports/final/final-summary.html'"
+```
+
+如模板脚本位于 skill 目录，则先复制到 archive 目录或直接引用 skill 路径。
+
+禁止模型临场手写大段 HTML。确需临时修 HTML，只能修模板，不得让统计数字脱离 `summary-data.json`。
+
+渲染后必须执行：
+
+```powershell
+powershell.exe -NoProfile -Command "npx hunter-harness report validate --change-id '<date-change>' --json"
+```
+
+存在 validate error 时，不得删除原 `.harness/changes/<change>` 目录。
+
+## archive-meta.md 模板
+
+```markdown
+# Archive Meta — <change-name>
+
+- archivedAt: YYYY-MM-DD HH:mm
+- finalCommit: <hash>
+- sourceDir: .harness/changes/<change-name>
+- archiveDir: .harness/archive/YYYY-MM-DD-<change-name>
+- movedFiles: <from manifest>
+- generatedFiles: archive-meta.md, summary-data.json, final-summary.html, manifests
+- totalArchiveFiles: <from after manifest>
+```
+
+## 目录结构与最终状态规则
+
+- 默认渲染器：`templates/render-summary.mjs`，输入 `reports/final/summary-data.json`，输出 `reports/final/final-summary.html`。
+- `render-summary.mjs` 是默认 UTF-8 渲染器；finalize 内嵌调用，不得由模型临场写 HTML。
+- 新路径优先：`meta/`、`logs/`、`evidence/`、`reports/final/`、`scripts/`、`backups/uncommitted-tests/`。旧路径只做读取兼容，不再写大量根目录文件。
+- 当 `summary-data.json.verification.apiTests.status=USER_SKIPPED` 或 `verification.dbCompatibility.status=BLOCKED_BY_DBA`，最终状态必须是 `CONDITIONAL_OK`。
+- 复杂 PowerShell 命令写入 `scripts/*.ps1` 后 `-File` 执行，禁止内联 `$` / `$_`。
+
+## 执行日志记录
+
+归档只向 `events.ndjson` 追加事件（schema_version 2）；`logs/execution-log.md` 由 `harness_events.py append` 自动渲染，禁止手工 Edit。事件类型与脚本用法见 SKILL.md `## 执行日志` 与 `../protocols/report-pipeline-protocol.md`。

package/resources/harness/bundles/general/codex/harness-archive/scripts/gen-manifest.ps1

@@ -0,0 +1,31 @@
+param(
+  [Parameter(Mandatory=$true)][string]$RootPath,
+  [Parameter(Mandatory=$true)][string]$OutputPath
+)
+
+$ErrorActionPreference = 'Stop'
+$root = (Resolve-Path $RootPath).Path
+# 排除 OutputPath 自身：重新生成 manifest 时旧 manifest 文件会被扫到，导致递归（新 manifest 含旧 manifest 的 sha256，fileCount 虚高 +1）。
+# OutputPath 不存在时（首次生成）$excludePath=$null，Where-Object 不过滤。
+$excludePath = $null
+if (Test-Path $OutputPath) {
+  $excludePath = (Resolve-Path $OutputPath).Path
+}
+$items = Get-ChildItem -Path $root -File -Recurse | Where-Object { $excludePath -eq $null -or $_.FullName -ne $excludePath } | Sort-Object FullName | ForEach-Object {
+  $relative = $_.FullName.Substring($root.Length).TrimStart('\','/') -replace '\\','/'
+  $hash = Get-FileHash -Path $_.FullName -Algorithm SHA256
+  [PSCustomObject]@{
+    path = $relative
+    sizeBytes = $_.Length
+    sha256 = $hash.Hash.ToLowerInvariant()
+  }
+}
+$result = [PSCustomObject]@{
+  root = $root
+  generatedAt = (Get-Date).ToString('s')
+  fileCount = @($items).Count
+  totalBytes = (@($items) | Measure-Object -Property sizeBytes -Sum).Sum
+  files = @($items)
+}
+$utf8NoBom = New-Object System.Text.UTF8Encoding($false)
+[System.IO.File]::WriteAllText((Resolve-Path (Split-Path $OutputPath -Parent)).Path + [System.IO.Path]::DirectorySeparatorChar + (Split-Path $OutputPath -Leaf), ($result | ConvertTo-Json -Depth 8), $utf8NoBom)

package/resources/harness/bundles/general/codex/harness-archive/templates/render-summary.mjs

@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+// render-summary.mjs
+// Deterministic UTF-8 renderer for harness archive final-summary.html.
+// Input: summary-data.json (schemaVersion 2.2). Output: final-summary.html.
+// Keeps UTF-8, avoids PowerShell string interpolation issues.
+// All numbers come from summary-data.json or manifest — never re-inferred here.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const args = process.argv.slice(2);
+function getArg(name, fallback) {
+  const i = args.indexOf(name);
+  return i >= 0 && args[i + 1] ? args[i + 1] : fallback;
+}
+
+const summaryPath = getArg('--summary', args[0]);
+const outPath = getArg('--out', args[1] || 'final-summary.html');
+if (!summaryPath) {
+  console.error('Usage: node render-summary.mjs --summary summary-data.json --out final-summary.html');
+  process.exit(2);
+}
+
+const data = JSON.parse(fs.readFileSync(summaryPath, 'utf8'));
+const esc = (v) => String(v ?? '').replace(/[&<>"']/g, (c) => ({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&#39;'}[c]));
+const arr = (v) => Array.isArray(v) ? v : [];
+const obj = (v) => v && typeof v === 'object' ? v : {};
+const num = (v) => Number(v) || 0;
+const badgeClass = (s) => {
+  const v = String(s ?? '').toUpperCase();
+  if (v.includes('FAIL') || v.includes('ERROR')) return 'bad';
+  if (v.includes('WARN') || v.includes('BLOCK') || v.includes('SKIP') || v.includes('CONDITIONAL') || v.includes('PARTIAL') || v.includes('NOT_RUN')) return 'warn';
+  if (v.includes('ADVISORY') || v.includes('REUSED')) return 'info';
+  return 'ok';
+};
+const badge = (s) => `<span class="badge ${badgeClass(s)}">${esc(s || 'N/A')}</span>`;
+
+// pass-rate progress bar: parses "183/185" style strings
+const parseRate = (rate) => {
+  if (!rate) return null;
+  const m = String(rate).match(/(\d+)\s*\/\s*(\d+)/);
+  return m ? { passed: +m[1], total: +m[2] } : null;
+};
+const rateBar = (rateStr, status) => {
+  const r = parseRate(rateStr);
+  if (!r || r.total <= 0) return `<span class="muted">N/A</span>`;
+  const pct = Math.round(r.passed / r.total * 100);
+  const cls = badgeClass(status || (r.passed >= r.total ? 'OK' : 'WARN'));
+  return `<div class="rate"><div class="bar-track"><div class="bar-fill ${cls}" style="width:${pct}%"></div></div><span class="muted small">${esc(rateStr)} · ${pct}%</span></div>`;
+};
+
+const stageRows = Object.entries(obj(data.stageStatus)).map(([k,v]) => `<tr><td>${esc(k)}</td><td>${badge(v)}</td></tr>`).join('\n') || `<tr><td colspan="2" class="muted">未记录阶段状态</td></tr>`;
+
+const verification = obj(data.verification);
+const unit = obj(verification.unitTests);
+const api = obj(verification.apiTests);
+const unitStatus = (num(unit.failures) + num(unit.errors)) > 0 ? 'WARN' : 'OK';
+const verificationRows = [
+  ['Unit Tests', `${rateBar(unit.passRate, unitStatus)}<div class="muted small">${esc(unit.run ?? 0)} run · ${esc(unit.failures ?? 0)} fail · ${esc(unit.errors ?? 0)} err · ${esc(unit.skipped ?? 0)} skip · ${esc(unit.source || 'not recorded')}</div>`],
+  ['API Tests', `${rateBar(api.passRate, api.status)}<div class="muted small">${esc(api.passed ?? 0)}/${esc(api.total ?? 0)} · ${esc(api.status || data.stageStatus?.test || 'N/A')}</div>`],
+  ['DB Compat', badge(verification.dbCompatibility || 'N/A')],
+  ['Coverage', esc(verification.coverageDisplay || 'N/A')],
+  ['Overall', badge(data.finalStatus || data.overallStatus || 'N/A')]
+].map(([a,b]) => `<tr><td>${a}</td><td>${b}</td></tr>`).join('\n');
+
+const diffStat = obj(data.diffStat);
+const changedRows = arr(data.changedFiles).map(f => `<tr><td><code>${esc(f.path || f.file || '')}</code></td><td>${esc(f.summary || f.change || '')}</td><td class="ins">+${esc(f.insertions ?? 0)}</td><td class="del">-${esc(f.deletions ?? 0)}</td></tr>`).join('\n') || `<tr><td colspan="4" class="muted">未记录变更文件</td></tr>`;
+const artifactList = arr(data.artifacts);
+const artifactRows = artifactList.map(a => `<tr><td>${esc(a.name || '')}</td><td><code>${esc(a.path || '')}</code></td><td>${esc(a.size || '')}</td><td><code>${esc(a.sha256 || '')}</code></td></tr>`).join('\n');
+const artifactCard = artifactList.length > 0 ? `<div class="card"><h2>📦 产物清单</h2><table><tr><th>名称</th><th>路径</th><th>大小</th><th>SHA-256</th></tr>${artifactRows}</table></div>` : '';
+const notes = arr(data.maintenanceNotes).map(n => `<li>${esc(n)}</li>`).join('\n') || `<li class="muted">无额外维护说明</li>`;
+const risks = arr(data.knownRisks).map(n => `<li>${esc(n)}</li>`).join('\n') || `<li class="muted">无已知遗留风险</li>`;
+const manual = arr(data.manualActions).map(n => `<li>${esc(n)}</li>`).join('\n') || `<li class="muted">无人工后续动作</li>`;
+const uncommittedList = arr(data.uncommittedTestEvidence);
+const uncommittedTests = uncommittedList.map(n => `<li>${esc(n)}</li>`).join('\n');
+const uncommittedCard = uncommittedList.length > 0 ? `<div class="card"><h2>🧪 未提交测试证据</h2><ul>${uncommittedTests}</ul></div>` : '';
+const review = obj(data.reviewSummary);
+const manifest = obj(data.archiveManifest);
+const timeline = arr(data.timeline).map(t => `<tr><td>${esc(t.stage || '')}</td><td>${badge(t.result || '')}</td><td>${esc(t.evidence || '')}</td></tr>`).join('\n');
+
+// durations + skillCalls (schema 2.1); fall back to timeline when absent
+const durations = obj(data.durations);
+const durStages = arr(durations.stages);
+const maxMin = durStages.reduce((m, s) => Math.max(m, num(s.minutes)), 0);
+const durRows = durStages.map(s => {
+  const min = num(s.minutes);
+  const pct = maxMin > 0 ? Math.round(min / maxMin * 100) : 0;
+  return `<div class="dur-row"><div class="dur-label">${esc(s.skill || s.stage || '')} <span class="muted small">${esc(s.result || '')}</span></div><div class="dur-track"><div class="dur-bar" style="width:${pct}%"></div></div><div class="dur-min">${esc(min)}m</div></div>`;
+}).join('\n');
+const skillCallsHtml = arr(data.skillCalls).map(s => `${esc(s.skill)}×${esc(s.count)} ${badge(s.result)}`).join(' ') || '<span class="muted">未记录</span>';
+
+const durCard = durStages.length > 0
+  ? `<div class="card"><h2>⏱️ 阶段耗时与 Skill 调用</h2>${durRows}<div class="muted small" style="margin-top:10px">Skill 调用：${skillCallsHtml}</div></div>`
+  : (timeline ? `<div class="card"><h2>阶段时间线</h2><table><tr><th>阶段</th><th>结果</th><th>证据</th></tr>${timeline}</table></div>` : '');
+
+const totalLabel = durations.totalLabel || (durations.totalMinutes ? durations.totalMinutes + 'm' : 'N/A');
+
+const html = `<!doctype html>
+<html lang="zh-CN">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>变更最终报告 - ${esc(data.changeName || '')}</title>
+<style>
+:root { color-scheme: dark; }
+* { box-sizing: border-box; }
+body { font-family: -apple-system,BlinkMacSystemFont,'Segoe UI','Microsoft YaHei',sans-serif; margin: 0; background: #0b1020; color: #e5e7eb; }
+main { max-width: 1120px; margin: 0 auto; padding: 32px; }
+.card { background: rgba(255,255,255,.06); border: 1px solid rgba(255,255,255,.12); border-radius: 16px; padding: 20px; margin: 16px 0; box-shadow: 0 12px 40px rgba(0,0,0,.18); }
+h1 { margin: 0 0 8px; font-size: 30px; }
+h2 { margin: 0 0 12px; font-size: 20px; }
+h3 { margin: 18px 0 8px; }
+.muted { color: #94a3b8; }
+.small { font-size: 12px; }
+table { width: 100%; border-collapse: collapse; table-layout: fixed; }
+th, td { border-bottom: 1px solid rgba(255,255,255,.12); padding: 10px; text-align: left; vertical-align: top; overflow-wrap: anywhere; }
+th { color: #cbd5e1; font-weight: 600; }
+tbody tr:nth-child(even) { background: rgba(255,255,255,.03); }
+tbody tr:hover { background: rgba(96,165,250,.08); }
+code { color: #bfdbfe; word-break: break-all; }
+.ins { color: #86efac; font-weight: 600; }
+.del { color: #fca5a5; font-weight: 600; }
+.badge { display: inline-block; padding: 4px 8px; border-radius: 999px; font-weight: 700; font-size: 12px; }
+.badge.ok { background: rgba(34,197,94,.16); color: #86efac; }
+.badge.warn { background: rgba(245,158,11,.18); color: #fcd34d; }
+.badge.bad { background: rgba(239,68,68,.18); color: #fca5a5; }
+.badge.info { background: rgba(59,130,246,.18); color: #93c5fd; }
+.grid { display: grid; grid-template-columns: repeat(auto-fit,minmax(200px,1fr)); gap: 16px; }
+.kpi { font-size: 18px; font-weight: 700; margin-top: 4px; word-break: break-all; }
+.hero { border-color: rgba(96,165,250,.35); background: linear-gradient(135deg, rgba(59,130,246,.12), rgba(255,255,255,.04)); }
+ul { margin-top: 8px; }
+.bar-track { background: rgba(255,255,255,.08); border-radius: 999px; height: 8px; overflow: hidden; margin: 4px 0; }
+.bar-fill { height: 100%; border-radius: 999px; }
+.bar-fill.ok { background: #22c55e; }
+.bar-fill.warn { background: #f59e0b; }
+.bar-fill.bad { background: #ef4444; }
+.bar-fill.info { background: #3b82f6; }
+.rate { display: flex; flex-direction: column; gap: 2px; min-width: 160px; }
+.dur-row { display: grid; grid-template-columns: 150px 1fr 50px; align-items: center; gap: 10px; padding: 6px 0; }
+.dur-label { color: #93c5fd; font-size: 13px; }
+.dur-track { background: rgba(255,255,255,.06); border-radius: 4px; height: 18px; overflow: hidden; }
+.dur-bar { height: 100%; background: linear-gradient(90deg, #3b82f6, #60a5fa); border-radius: 4px; }
+.dur-min { color: #94a3b8; font-size: 13px; text-align: right; }
+@media (max-width: 640px) { main { padding: 16px; } .grid { grid-template-columns: 1fr; } .dur-row { grid-template-columns: 100px 1fr 40px; } }
+</style>
+</head>
+<body><main>
+<div class="card hero">
+  <h1>变更最终报告：${esc(data.changeName || '')}</h1>
+  <p class="muted">${esc(data.businessGoal || '未记录业务目标')}</p>
+</div>
+<div class="grid">
+  <div class="card"><div class="muted">🎯 最终状态</div><div class="kpi">${badge(data.finalStatus || data.overallStatus || 'N/A')}</div></div>
+  <div class="card"><div class="muted">🔒 Final Commit</div><div class="kpi"><code>${esc(data.finalCommit || 'N/A')}</code></div><div class="muted small">${esc(data.finalCommitBranch || '')}</div></div>
+  <div class="card"><div class="muted">📊 代码变更</div><div class="kpi">${esc(diffStat.filesChanged ?? 'N/A')} 文件</div><div class="muted small"><span class="ins">+${esc(diffStat.insertions ?? 0)}</span> <span class="del">-${esc(diffStat.deletions ?? 0)}</span></div></div>
+  <div class="card"><div class="muted">⏱️ 总耗时</div><div class="kpi">${esc(totalLabel)}</div><div class="muted small">${esc(durStages.length)} 个阶段</div></div>
+  <div class="card"><div class="muted">📝 Review</div><div class="kpi">${esc(review.status || 'N/A')}</div><div class="muted small">RED ${esc(review.red ?? 0)}(修${esc(review.redFixed ?? 0)}/确${esc(review.redConfirmed ?? 0)}) · YEL ${esc(review.yellow ?? 0)}(修${esc(review.yellowFixed ?? 0)}/留${esc(review.yellowDeferred ?? 0)})</div></div>
+  <div class="card"><div class="muted">📦 Archive</div><div class="kpi">${esc(manifest.totalArchiveFiles ?? 'N/A')} 文件</div><div class="muted small">${esc(manifest.checksumStatus || 'N/A')}</div></div>
+</div>
+<div class="card"><h2>📋 阶段状态</h2><table><tr><th>阶段</th><th>状态</th></tr>${stageRows}</table></div>
+${durCard}
+<div class="card"><h2>🛡️ 验证明细</h2><table><tr><th>类型</th><th>结果</th></tr>${verificationRows}</table></div>
+<div class="card"><h2>📁 变更文件</h2><table><tr><th>文件</th><th>说明</th><th>+</th><th>-</th></tr>${changedRows}</table></div>
+${artifactCard}
+${uncommittedCard}
+<div class="card"><h2>👨‍🔧 给后续维护者</h2><ul>${notes}</ul></div>
+<div class="card"><h2>⚠️ 已知风险 / 人工确认项</h2><ul>${risks}</ul><h3>人工后续动作</h3><ul>${manual}</ul></div>
+</main></body></html>`;
+
+fs.mkdirSync(path.dirname(outPath), { recursive: true });
+fs.writeFileSync(outPath, html, 'utf8');