npm - hunter-harness - Versions diffs - 0.2.0 → 0.2.1 - Mend

hunter-harness 0.2.0 → 0.2.1

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 (564) hide show

package/resources/harness/bundles/general/codex/protocols/archive-report-protocol.md DELETED Viewed

@@ -1,175 +0,0 @@
----
-description: harness-archive 的数据化归档和 final-summary 渲染协议。用于减少模型长篇 HTML 生成、提升数据准确性和页面一致性。
----
-# Archive Report Protocol
-## 原则
-archive 不应让模型临场生成 500+ 行 HTML。事实收集与校验由 `harness_archive.py finalize` 单命令完成（collect → render → validate 内嵌）；模型仅补写 `maintenanceNotes` / `knownRisks` / `manualActions`。历史 archive 回放用 `harness_archive.py replay`。
-详见 `report-pipeline-protocol.md`。本协议保留 archive final report 的维度要求，report pipeline 负责把这些维度程序化生成和校验。
-## 必备产物
-归档目录必须包含：
-```text
-archive-meta.md
-archive-manifest-before.json
-archive-manifest-after.json
-summary-data.json
-final-summary.html
-events.ndjson（新流程推荐；历史 archive 可缺失）
-```
-## summary-data.json
-结构来源为 `harness-archive/templates/summary-data-template.json`（schemaVersion 2.2）。默认由 `harness_archive.py finalize` 生成；历史回放用 `harness_archive.py replay`。
-```json
-{
-  "schemaVersion": "2.2",
-  "changeName": "...",
-  "businessGoal": "本次变更为了做什么",
-  "finalCommit": "...",
-  "finalCommitBranch": "origin/...",
-  "baseCommit": "...",
-  "diffStat": {"filesChanged": 0, "insertions": 0, "deletions": 0, "range": "<base>..<head>"},
-  "stageStatus": {
-    "plan": "OK/FAIL",
-    "run": "WARN/OK/FAIL",
-    "test": "OK/PARTIAL/BLOCKED/FAIL",
-    "review": "ADVISORY",
-    "submit": "OK/WARN/FAIL",
-    "archive": "OK/FAIL"
-  },
-  "durations": {
-    "totalLabel": "约 N 分",
-    "totalMinutes": 0,
-    "stages": [{"stage":"plan","skill":"harness-plan","startedAt":"...","endedAt":"...","minutes":0,"result":"OK"}]
-  },
-  "skillCalls": [{"skill":"harness-plan","count":1,"result":"OK"}],
-  "verification": {
-    "unitTests": {"run": 0, "failures": 0, "errors": 0, "skipped": 0, "passRate": "183/185"},
-    "apiTests": {"total": 0, "passed": 0, "failed": 0, "blocked": 0, "passRate": "34/35"},
-    "coverageDisplay": "29/29"
-  },
-  "timeline": [],
-  "changedFiles": [{"path":"...","summary":"...","insertions":0,"deletions":0}],
-  "artifacts": [],
-  "reviewSummary": {"status":"ADVISORY","red":0,"yellow":0,"redFixed":0,"redConfirmed":0,"yellowFixed":0,"yellowDeferred":0,"summary":""},
-  "archiveManifest": {},
-  "uncommittedTestEvidence": [],
-  "maintenanceNotes": [],
-  "knownRisks": [],
-  "manualActions": [],
-  "reportPipeline": {
-    "schema_version": 1,
-    "generated_at": "...",
-    "event_count": 0,
-    "sources": [],
-    "phases": {},
-    "commands": [],
-    "verificationChecks": [],
-    "artifacts": [],
-    "validationIssues": []
-  }
-}
-```
-`final-summary.html` 的数字必须全部来自 events、`summary-data.json`、ledger 或 manifest，不得手写另一套统计。
-### 数据采集来源（禁止手写统计）
-- `diffStat` / `changedFiles[].insertions`/`deletions`：来自 `git diff --numstat <base>..<head>` 与 `git diff --stat <base>..<head>`，不得手写。
-- `durations`：从 `logs/execution-log.md` 各 `[N] harness-<skill>` 小节的 `开始`/`结束`/`耗时` 解析；`totalMinutes` 为各 stage `minutes` 之和。含用户确认等待的阶段须在该 stage 的 `result` 或 `maintenanceNotes` 注明，不得把等待时间伪装成纯执行时间。
-- `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/` 目录文件，不包含项目构建产物，两者不可混用。
-- `reportPipeline.commands[]` / `verificationChecks[]` / `validationIssues[]`：来自 `events.ndjson`、ledger、validate 结果。旧 archive 无 events 时可从 ledger/log/manifest 回放，不得编造。
-## manifest/checksum
-archive 前后生成文件清单，包含 path、size、sha256。before/after 统计不一致时，不得删除原目录。
-manifest 必须使用固定脚本生成，禁止内联包含 `$`、`$_`、`@{}`、script block、管道 JSON 输出的 PowerShell：
-```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"
-```
-最终报告必须区分：
-- movedFiles：实际移动的文件数；
-- generatedFiles：archive 过程中生成的文件数；
-- totalArchiveFiles：归档目录最终文件总数。
-## 页面内容
-final-summary 必须突出：
-1. 本次变更业务目标；
-2. 代码变更统计（diffStat：文件数 / insertions / deletions）；
-3. 各阶段耗时与 Skill 调用统计（durations / skillCalls）；
-4. 验证结果与复用/重测来源（含通过率）；
-5. review advisory 摘要（含修复进度：已修复 / 已确认 / 留后续）；
-6. 给后续维护者的结论；
-7. 已知风险或人工确认项。
-禁止出现顶部 `N/A`、正文 `100%` 这类互相矛盾的数据。
-## final-summary 信息密度要求
-`summary-data.json` 至少包含 `verification`、`artifacts`、`reviewSummary`、`archiveManifest`、`maintenanceNotes`、`knownRisks`、`manualActions`。renderer 只根据 JSON 渲染，不在 HTML 中重新推理数据。
-`artifacts` 与 `uncommittedTestEvidence` 为空数组时，renderer 不渲染对应卡片（"📦 产物清单"/"🧪 未提交测试证据"），避免空态噪音；非空才渲染。字段在 JSON 中始终保留，仅控制是否展示。
-## 渲染器
-默认渲染器为 Node.js：
-```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 的变更**。
-渲染后必须运行 report validate；validate error 存在时，archive 不得删除原 changes 目录。**缺 final-summary.html 恒为 validate error**（不再有"没有 HTML 但只 warning"的分支）。
-## 归档与知识维护解耦（§8）
-archive close 的破坏性事务只执行确定性 close：
-```text
-status -> manifest -> move -> collect -> render -> validate -> compare
--> 写 maintenance outbox(pending) -> stop AI service -> return
-```
-close **不再同步顺序启动四次** `harness_knowledge.py`（ingest/dedupe/auto-supersede/reverify-stale）。它写一个 `pending` outbox 项即返回，`knowledgeMaintenance=QUEUED`；写 outbox 失败时 `NOT_QUEUED`（warning，不回滚 archive，`finalStatus` 仍由验证事实决定，本次总状态 CONDITIONAL）。
-outbox 布局见 `state-layout-protocol.md`「knowledge maintenance-outbox」。`harness_knowledge.py maintain --project . --archive-id <id>` 单进程推进：claim pending/failed -> running -> 增量 ingest（含 in-memory near-dedupe，不再二次磁盘 dedupe）-> auto-supersede -> reverify-stale -> 导出残余 judge checklist -> completed（或 `completed_rules_pending_judge` 若 `pendingJudgements>0`）。失败 -> failed（attempts+1，可重试）；completed 项幂等。`harness-sync` 启动时扫描 pending/failed outbox 并执行 maintain。
-**机械 maintain 不得假装完成语义裁决**：存在待裁决项（conflict / promote-candidate）时状态为 `completed_rules_pending_judge`、`pendingJudgements>0`、写 `pending-judgements-<archive-id>.json`，由模型层后续 `judge --apply` 处理；`manualReview=true` 时保留人工确认。
-## 最终状态
-当 `apiTests.status=USER_SKIPPED` 或 `dbCompatibility=BLOCKED_BY_DBA` 时，最终状态不得写纯 `OK`，必须写：
-```text
-CONDITIONAL_OK
-```
-并在 `knownRisks` / `manualActions` 中说明风险接受和后续人工动作。
-## 未提交测试证据
-如果 run/test 使用了被 `.gitignore` 忽略或未提交的测试文件作为验证证据，必须：
-1. 归档到 `backups/uncommitted-tests/`；
-2. 在 `summary-data.json.uncommittedTestEvidence[]` 中记录文件名、验证了什么、是否随 commit 提交；
-3. final-summary 明确展示（`uncommittedTestEvidence` 非空时渲染"🧪 未提交测试证据"卡片），避免维护者误以为仓库包含该回归测试；无此类证据时不渲染该卡。

package/resources/harness/bundles/general/codex/protocols/evidence-based-reporting-protocol.md DELETED Viewed

@@ -1,134 +0,0 @@
----
-description: harness 全流程的证据化报告协议。所有 skill 输出必须区分 ✅真实成功 / 🟡静态验证或跳过 / ❌失败或被拒绝。由原 harness-plan/evidence-based-reporting.md 迁移。
----
-# Evidence-Based Reporting Protocol
-> 本协议适用于所有 harness-skills 的最终输出。禁止把"静态验证"写成"测试通过"，禁止把"命令被拒绝"写成"成功"。
-## 状态分类
-所有 skill 的最终输出必须使用以下三类状态标记：
-| 标记 | 含义 | 使用场景 |
-|:----:|------|----------|
-| ✅ | **已真实执行并成功** | 有构建成功证据（Java=`BUILD SUCCESS`；前端/Python 按各自工具成功标志） / git 成功信息 / 文件实际存在 / exit code 0 等明确证据 |
-| 🟡 | **静态验证 / 用户确认跳过 / 证据不足** | 1. TDD 降级：仅做静态逻辑验证，未执行真实单元测试<br>2. 用户明确跳过 test/review<br>3. 命令执行但证据不充分<br>4. 需部署后验证的场景 |
-| ❌ | **执行失败 / 被 hook 拒绝 / 未验证** | 1. 命令被 hook 拒绝（Denied / PreToolUse:Bash hook error）<br>2. exit code 非 0<br>3. 输出无有效 stdout<br>4. 场景未覆盖且未验证 |
-## 禁止的表述
-| 禁止表述 | 正确表述 | 原因 |
-|----------|----------|------|
-| "测试全部通过" | 🟡 静态逻辑验证通过，未执行真实单元测试 | TDD 降级时没有真实测试 |
-| "编译成功" | ❌ 编译命令被 hook 拒绝 | 命令没有成功执行 |
-| "打包成功" | ❌ 打包命令输出不包含构建成功证据 | 没有明确证据 |
-| "拉取成功" | ❌ git pull 命令被 Denied | 命令被 hook 拦截 |
-| "推送成功" | ❌ git push 返回非 0 exit code | 推送实际失败 |
-| "覆盖率 100%" | 🟡 静态验证覆盖率 100%，未运行真实测试 | 覆盖率来源不实 |
-## 编译验证状态映射
-| 构建工具输出 | 状态标记 |
-|-----------|:--------:|
-| 包含构建成功证据（Java=`BUILD SUCCESS`；前端/Python 按各自工具成功标志） | ✅ 编译成功 |
-| 包含构建失败标志（Java=`BUILD FAILURE`；前端/Python 按各自工具失败标志） | ❌ 编译失败 |
-| 命令被 hook 拒绝 | ❌ 编译命令被拒绝 |
-| 无输出 / 超时 | ❌ 编译状态未知 |
-| 仅部分模块编译（跳过无关模块） | ✅ 目标模块编译成功 |
-## 测试验证状态映射
-| 情况 | 状态标记 | 报告表述 |
-|------|:--------:|----------|
-| 测试命令输出包含测试通过证据（Java=`Tests run: N, Failures: 0`；前端/Python 按各自工具） | ✅ | ✅ 已测试通过：N 个用例，0 失败 |
-| TDD 降级（无测试基础设施） | 🟡 | 🟡 静态验证通过，未执行真实单元测试，待测试基础设施补齐后运行 harness-test |
-| 测试命令被 hook 拒绝 | ❌ | ❌ 测试命令被拒绝，无法确认测试结果 |
-| 测试失败（有 Failures > 0） | ❌ | ❌ 测试失败：N 个用例，M 个失败 |
-| 用户确认跳过测试 | 🟡 | 🟡 用户确认跳过测试 |
-## 场景覆盖状态映射
-| 情况 | 状态标记 |
-|------|:--------:|
-| 有对应测试方法且测试通过 | ✅ 已测试通过 |
-| 代码逻辑已覆盖但未执行测试 | 🟡 静态验证通过，未真实测试 |
-| 代码逻辑未覆盖 | ❌ 未覆盖 |
-| 需要端到端部署验证 | 🟡 待部署后验证 |
-| 用户确认跳过 | 🟡 用户确认跳过 |
-## Git 操作状态映射
-| git 输出 | 状态标记 |
-|----------|:--------:|
-| `Already up to date.` 或实际更新记录 | ✅ 拉取成功 |
-| `Denied: non-ASCII path in Bash` | ❌ 命令被 hook 拒绝 |
-| `To <remote>` + 推送范围 | ✅ 推送成功 |
-| 无输出 | ❌ 状态未知 |
-## final-summary.html / summary-data.json 状态映射
-final-summary.html 默认由 `summary-data.json + render-summary.mjs` 渲染；旧占位符模板仅作 legacy reference。
-归档前必须执行 `harness_archive.py finalize` 内嵌 validate，或 `harness_archive.py replay` 等价校验。只有 validate 无 error 时，才能宣称 final-summary 与 summary-data 一致；validate error 不得被写成 WARN 或"已完成"。
-| 数据来源 | 无报告时 |
-|----------|----------|
-| `summary-data.validations.unit/api` | 标记 `NOT_RUN` / `STATIC_ONLY`，不得显示 100% |
-| `summary-data.review` | 标记 `ADVISORY_NOT_RUN`，不得显示 100% |
-| `summary-data.package` | 缺失时标记 `WARN`，不得伪造 package 成功 |
-| `summary-data.stageStatus` | 必须真实展示 ✅OK / 🟡WARN / 🔁REUSED / 📝ADVISORY 等状态 |
-## 执行日志状态标注
-所有 skill 的 execution-log.md 中，结果字段必须使用以下格式：
-```markdown
-- **结果**: ✅OK成功 / 🟡WARN(降级原因) / ❌FAIL(失败原因)
-```
-禁止使用模糊表述如"OK"、"成功"、"完成"，必须包含状态标记和具体原因。
-## 两维度术语表
-本协议的状态标记与 review 的发现严重级是**两个独立维度**，不得混用。下表统一登记各态的边界与关系，避免散落未对齐。
-### 维度一：skill 执行状态三态
-任何 skill 的最终执行结果必须落到以下三态之一：
-| 标记 | 含义 | 适用场景 |
-|:----:|------|----------|
-| ✅OK | 已真实执行并成功 | 有构建成功证据 / git 成功信息 / 文件实际存在 / exit code 0 等明确证据 |
-| 🟡WARN(原因) | 静态验证 / 用户确认跳过 / 证据不足 / 降级 | TDD 降级仅静态验证、用户跳过 test/review、命令执行但证据不充分、需部署后验证、远端有新提交需 pull/rebase、用户选择仅本地 commit |
-| ❌FAIL(原因) | 执行失败 / 被 hook 拒绝 / 未验证 | 命令被 hook 拒绝、exit code 非 0、输出无有效 stdout、push 失败/被拒绝、commit 失败、hook 拒绝、场景未覆盖且未验证 |
-### 维度二：review 发现严重级（审查发现维度，不等于 skill 执行状态）
-harness-review 对代码/变更的审查发现按风险分级，反映的是**被审查对象的问题严重度**，而非 review 这个 skill 本身是否执行成功：
-| 标记 | 含义 | 适用场景 |
-|:----:|------|----------|
-| RED | 高风险建议 | 存在安全/数据/契约级高风险问题，建议阻塞合并 |
-| YELLOW | 中低风险 | 存在中低风险改进项，建议处理但不阻塞 |
-| OK | 无问题 | 审查通过，未发现需处理项 |
-> 注意：review skill 执行成功（✅OK）不等于发现严重级为 OK；review 发现 RED 时，review skill 本身仍可能是 ✅OK（执行成功并产出了 RED 发现）。
-### 条件态 / 跳过态（特殊最终状态）
-以下状态用于特定条件下的最终状态表达，不属于上述两个主维度的常规三态：
-| 标记 | 含义 | 适用场景 |
-|:----:|------|----------|
-| CONDITIONAL_OK | 条件性通过 | API 测试 `USER_SKIPPED` 或 DB 兼容性 `BLOCKED_BY_DBA` 时的归档最终状态，不得写纯 OK，必须在 knownRisks/manualActions 说明风险接受与后续人工动作 |
-| 🔁REUSED | 复用前阶段结果 | 复用了前一阶段验证结果，final-summary 必须显式标记，不得伪装成重新执行 |
-| 📝ADVISORY | 参考性未运行 | review 参考性意见，未作为门禁执行 |
-| ⏭️ | 用户选择跳过 | 用户主动选择跳过某步骤（如仅本地 commit 不 push、跳过 test/review） |
-### 两维度关系
-- skill 执行状态回答"这个步骤跑没跑、成没成"；
-- review 发现严重级回答"被审查的东西有没有问题、问题多大"；
-- 条件态/跳过态回答"这个步骤的最终结论是什么特殊情况"。
-- 三者独立：例如 test skill 可 ✅OK 执行成功，但 review 发现其覆盖的代码存在 RED 问题；又如 archive 可因 `USER_SKIPPED` 给出 CONDITIONAL_OK，同时 review 发现为 YELLOW。final-summary 必须分别展示，不得用一个维度覆盖另一个。

package/resources/harness/bundles/general/codex/protocols/ledger-protocol.md DELETED Viewed

@@ -1,270 +0,0 @@
----
-description: verification-ledger、diffHash、service-fingerprint 的统一协议。用于 run/test/submit/package/archive 之间复用验证结果。由原 harness-plan/verification-ledger.md 合并而来。
----
-# Ledger Protocol
-> 本协议被 harness-plan / harness-run / harness-test / harness-submit / harness-archive 共同引用。
-> 目标：消除跨阶段重复编译/测试，让每个"✅ 已验证"结论可追溯、可复用，避免 post-test 小改动导致前序报告有效性表达不清。
-## 一、为什么需要 verification-ledger
-实践教训：
-- 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 再决定是否重跑。
-## 二、账本文件位置
-```text
-.harness/changes/<change-name>/evidence/verification-ledger.json
-```
-> 旧路径 `.harness/changes/<change-name>/verification-ledger.json`（根目录）兼容读取，详见 `state-layout-protocol.md`。新版本优先写 `evidence/`。
-- 不提交到 git（已在 `.harness/` 屏蔽范围内）
-- 每次验证执行后**立即写回**（不得等所有阶段结束才补）
-- 后续阶段执行验证前**必须先读取** ledger
-## 三、账本结构
-`.harness/changes/<change>/verification-ledger.json` 必须至少包含：
-```json
-{
-  "changeName": "indicator-permission-fix",
-  "projectRoot": "C:/CQ_PROJECT/贡献积分管理系统/udp",
-  "worktreeRoot": "... 或 null",
-  "stateDir": ".harness/changes/<change>",
-  "currentHead": "<git rev-parse HEAD>",
-  "baseCommit": "<merge-base 或计划起点>",
-  "diffHash": "sha256:<diff 内容指纹>",
-  "module": "<module-from-build-profile>",
-  "profile": "local-dev",
-  "postTestClassification": "NON_BEHAVIORAL_CLEANUP",
-  "ledgerReusable": true,
-  "scope": "module",
-  "validations": {
-    "compile": {
-      "status": "OK",
-      "command": "<构建命令（按技术栈：Java=mvn compile -pl <module> -o -q；前端=npm --prefix <module> run build；Python=pytest <module>）>",
-      "scope": "module",
-      "evidence": "<构建成功证据（Java=BUILD SUCCESS；前端/Python 按各自工具成功标志）>",
-      "startedAt": "2026-06-22T10:00:00+08:00",
-      "finishedAt": "2026-06-22T10:01:30+08:00",
-      "durationMs": 90000
-    },
-    "unitTest": {
-      "status": "OK",
-      "command": "<测试命令（按技术栈：Java=mvn test -pl <module> -o；前端=npm test --prefix <module>；Python=pytest <module>）>",
-      "scope": "module",
-      "testsRun": 14,
-      "failures": 0,
-      "errors": 0,
-      "skipped": 0,
-      "evidence": "<测试通过证据（Java=Tests run: 14, Failures: 0, Errors: 0, Skipped: 0；前端/Python 按各自工具成功标志）>",
-      "startedAt": "2026-06-22T10:02:00+08:00",
-      "finishedAt": "2026-06-22T10:05:00+08:00",
-      "durationMs": 180000
-    },
-    "apiTest": {
-      "status": "OK",
-      "runner": "playwright-api-runner",
-      "scenariosTotal": 21,
-      "passed": 21,
-      "failed": 0,
-      "skipped": 0,
-      "evidence": "api-test-results.json summary",
-      "resultsFile": ".harness/changes/<change-name>/runtime/api-test-results.json",
-      "startedAt": "2026-06-22T10:06:00+08:00",
-      "finishedAt": "2026-06-22T10:08:00+08:00",
-      "durationMs": 120000
-    },
-    "package": {
-      "status": "OK",
-      "command": "<打包命令（按技术栈：Java=mvn package -pl <module> -am -DskipTests；前端=npm run build；Python=python -m build）>",
-      "baseCommit": "<final pushed hash>",
-      "deployArtifact": "<构建产物路径（Java=<module>/target/<artifact>.jar；前端=<module>/dist/；Python=<module>/dist/）>",
-      "sha256": "<artifact sha256>",
-      "testsExecuted": false,
-      "testsReusedFrom": "unitTest+apiTest",
-      "evidence": "<构建成功证据> + Glob 扫描确认构建产物存在",
-      "startedAt": "2026-06-22T10:30:00+08:00",
-      "finishedAt": "2026-06-22T10:35:00+08:00",
-      "durationMs": 300000
-    }
-  }
-}
-```
-缺少 `diffHash/currentHead/baseCommit/module/profile` 时，后续 skill 不得复用该 ledger，只能作为参考报告。
-字段说明：
-| 字段 | 含义 |
-|------|------|
-| `diffHash` | 本变更集相对 `baseCommit` 的全部内容变更 sha256 = `git diff baseCommit..HEAD`（已提交）+ `git diff`（未提交 tracked）+ 未跟踪新文件内容的合并指纹；**commit-invariant**（未提交 diff 转为已提交 diff，指纹不变），保证 run→test 跨 checkpoint commit 可复用 |
-| `currentHead` | 验证执行时的 HEAD commit hash |
-| `baseCommit` | merge-base 或计划起点（package 项另有 `baseCommit` 指 final pushed hash） |
-| `projectRoot` / `worktreeRoot` | 项目根与 worktree 根（无 worktree 时 `worktreeRoot=null`） |
-| `stateDir` | `.harness/changes/<change>`，避免手拼路径 |
-| `scope` | 验证范围：`module` / `module-am` / `full`，越严格越容易复用 |
-| `evidence` | 必须是命令实际输出的关键证据串，不得为空 |
-| `postTestClassification` | test 之后若发生代码变更，标注变更类型（见第六章） |
-| `ledgerReusable` | 布尔型，当前 ledger 是否可被后续阶段复用；由 postTestClassification（非行为性）+ diffHash 比对一致 + module/profile/scope 一致共同决定；缺关键字段时为 false，后续阶段不得复用 |
-| `scope`（顶层） | 顶层 scope 取 validations 中最宽 scope，作为复用判定的整体范围；条目级 scope 见各 validation |
-| `package.testsExecuted` | package 本次是否真实跑了测试；为 false 时 `testsReusedFrom` 必须指明复用来源 |
-## 四、复用判定规则
-后续阶段执行验证前先读 ledger。**同时满足以下全部条件**才可复用已有验证结果，否则必须重新执行：
-1. `diffHash` 与当前 diff 一致
-2. `currentHead` 或 merge-base 未发生影响当前 diff 的变化（HEAD 可前移，但本次变更文件未被他人提交触碰）
-3. `module` 一致
-4. `profile` 一致
-5. ledger 中该项 `command` 的 `scope` 一致或更严格（当前阶段范围 ⊆ ledger 范围）
-6. 前一次验证结果 `status=OK` 且 `evidence` 非空
-7. 前一次验证后**没有行为性代码变更**（见第六章分类；只有 NON_BEHAVIORAL_CLEANUP / COMMENT_ONLY / TEST_ONLY 才算"无行为性变更"）
-**禁止复用的高风险场景**（即使 diffHash 相同也必须重跑）：
-- post-test 修改属于 BEHAVIORAL_SERVICE_CHANGE / API_CONTRACT_CHANGE / SQL_OR_MAPPER_CHANGE / SECURITY_OR_PERMISSION_CHANGE
-- 远端 pull/rebase 引入了新提交
-- 用户显式要求 `submit-full-verify` / `package-with-tests`
-- ledger 缺失、损坏或 `evidence` 为空
-### 4.1 service-fingerprint（API 测试服务复用）
-接口测试复用已有服务前，读取：
-```text
-.harness/changes/<change>/runtime/service-session.json
-```
-字段（由 `harness_service.py ensure` 写入）：
-```json
-{
-  "pid": 0,
-  "startedBy": "AI / User",
-  "moduleInputsHash": "sha256:<依赖闭包内容指纹>",
-  "moduleInputsFiles": ["<project>/Svc.java", "..."],
-  "profile": "local-dev-remote-sdk",
-  "overlayPath": "C:/temp/harness-test-overlay/<change>/application-harness-test.yml",
-  "startCommandHash": "sha256:<command 指纹>",
-  "command": "<serviceStart.command>",
-  "startedAt": "..."
-}
-```
-`moduleInputsHash` 由 CLI `--files` ∪ `build-profile.json` 的 `serviceStart.inputFiles`（glob 列表，相对 project 展开）计算。**空输入被拒绝**（exit 非 0），不得生成可复用的空指纹（§5.1/§5.2）。
-复用必须**同时**满足（§5.3）：`moduleInputsHash` 一致、`startCommandHash` 一致、`profile` 一致、`overlayPath` 一致、进程身份（pid 存活 + create time 匹配 `startedAt`）可确认。任一变化 -> AI 自动 restart；身份无法确认 -> `needs-user-decision`；非 AI 用户进程永不自动 kill。否则必须进入 Service Decision Gate（见 harness-test）。
-### 4.2 unitTestFull 最终全量门禁
-`unitTestFull` 是 submit 前的**模块级全量单元测试**门禁，与增量 `unitTest` 严格区分，二者键独立、不可互冒充：
-| verification | 合法 scope | 复用规则 |
-|---|---|---|
-| `unitTest` | 测试类列表或 `module`/`module-am`/`full` | 可覆盖请求的受影响测试类 |
-| `unitTestFull` | 只能是 `module` / `module-am` / `full`（broad scope） | 只允许复用已有 `unitTestFull`；增量 `unitTest` 结果不能复用 |
-`unitTestFull` 复用必须**同时**满足：ledger 存在 `validations.unitTestFull`、`status=OK`、`scope ∈ broad scopes`、`evidence` 非空、`command` 非空（调用方传 `--command` 时须完全一致）、`inputsHash` 与当前文件集一致、`inputsFiles` 为非空 list。任一不满足（含 scope 为测试类名等增量范围）→ `insufficient-evidence`，执行全量测试但不允许缓存复用。
-**依赖闭包必须由 profile 展开**，最终门禁禁止用仅含 staged 文件的 `--files` 快捷方式冒充全量闭包：
-```text
-harness_ledger.py can-reuse --verification unitTestFull --scope module \
-  --project . --profile-input unitTestFull \
-  --command "<build-profile.json buildCommands.unitTestFull>" --json
-```
-`build-profile.json` 新增 `verificationInputs.unitTestFull`（glob 列表，相对 project 展开，只保留 project 内文件、去重排序）：
-```json
-{
-  "verificationInputs": {
-    "unitTestFull": ["pom.xml", "module/pom.xml", "module/src/main/**", "module/src/test/**"]
-  }
-}
-```
-profile key 缺失 / glob 无匹配 / 结果为空 → `insufficient-evidence`（exit 0），仍须执行全量测试但不允许缓存复用，直到 profile 被正确配置。`harness_preflight.py detect` 对单模块 Java 项目写入根级默认闭包 `["pom.xml", "src/main/**", "src/test/**"]`；多模块项目需手工改为 module 专属 glob，detect 不会覆盖用户已配置的 `verificationInputs`。
-## 五、真实 diffHash
-必须基于真实 diff 计算 SHA-256，且**必须是 commit-invariant 的**——覆盖本变更集相对 `baseCommit` 的全部内容变更（已提交 + 未提交 + 未跟踪），使 checkpoint commit 前后指纹一致，保证 run→test 复用链不断。
-`<baseCommit>` 从 ledger 读取（harness-plan 阶段写入）；缺失时用 `git merge-base HEAD <默认分支>` 兜底。推荐命令：
-```powershell
-powershell.exe -NoProfile -Command "$base = '<baseCommit>'; $patch = '.harness/changes/<change>/runtime/current-diff.patch'; & { git diff $base HEAD --binary; git diff --binary; git ls-files --others --exclude-standard | ForEach-Object { Get-Content -Raw -LiteralPath $_ } } | Out-File -Encoding utf8 $patch; (Get-FileHash $patch -Algorithm SHA256).Hash"
-```
-- 命令为模板：`<baseCommit>`/`<change>` 需替换；经 `powershell.exe -Command "..."` 从 PowerShell/Bash 调用时外层会展开 `$` 变量，建议直接用 PowerShell 工具执行去外壳脚本，或外层用单引号/`--%` 防展开
-- 三部分合并：`git diff $base HEAD`（已提交变更）+ `git diff`（未提交 tracked）+ 未跟踪新文件内容（`git ls-files --others --exclude-standard`）；`& { }` 必须带 `&` 才执行 scriptblock（bare `{ } | Out-File` 只写脚本块字符串，不执行）
-- commit 前：`$base..HEAD` 为空 + 未提交 24 文件 + 未跟踪 9 文件 = 全量；commit 后：`$base..HEAD` 24 文件 + 未提交空 + 未跟踪空 = 同内容 → 指纹一致 ✅
-- diffHash 只用于"内容是否变化"判断，不等于 commit hash
-- 账本中 `currentHead`（验证时 HEAD）与 `diffHash` 分开记录；reuse 规则 #2 允许 HEAD 前移（如 harness-run Step 5 checkpoint commit），因 diffHash 已 commit-invariant，HEAD 前移不改变指纹
-- **禁止**使用类似 `3files-84plus-5minus` 的描述性字符串作为复用依据
-- **禁止**仅用 `git diff`（未提交）计算 diffHash——checkpoint commit 后工作树干净会致指纹变空，断裂 run→test 复用链
-- **禁止**任何单部分简化：含 `git diff <base> HEAD`（仅已提交部分）、`git diff`（仅未提交）、`node -e`/`crypto.createHash` 自算 SHA-256。无论 commit 前后、无论工作树是否 clean，必须用上述三部分合并命令。commit 后 clean 致单部分偶然等价不得作为省略依据——时序或工作树状态变化即复现复用链断裂
-- **commit 前时序说明**：harness-run 步骤 2c 在 Step 5 checkpoint commit **之前**写 ledger，此时 `git diff baseCommit..HEAD` 部分为空（HEAD==baseCommit），只有"未提交 + 未跟踪"是全量。**即使第一部分为空也必须保留三部分合并命令**——commit 后第一部分被填充、未提交/未跟踪变空，两者内容相同 → diffHash 一致。省略第一部分只用未提交 diff，commit 后未提交变空 → diffHash 变化 → 复用链断裂（真实教训：run 产出非规范 `8a94c874`，test 重算 `b4c580fc` 不一致被迫重跑全量单元测试）。harness-run 步骤 2c 已 inline 完整三部分命令，执行者直接跑 verbatim，不得自行省略
-## 六、Post-test 变更分类
-当 `/harness-test` 完成后又发生代码变更（常见于 review 后清理、submit 前发现的小问题），后续 submit/package/archive **必须先对变更做分类**，写入 ledger 的 `postTestClassification`：
-| 类型 | 示例 | 是否需要重跑 API | 是否需要重跑 unit | 是否需要重 compile |
-|------|------|:---:|:---:|:---:|
-| `NON_BEHAVIORAL_CLEANUP` | 删除未使用 import、删除未使用字段、格式化 | 否 | 否 | 是（轻量） |
-| `COMMENT_ONLY` | 注释调整、Javadoc 补充 | 否 | 否 | 否 |
-| `TEST_ONLY` | 只改测试文件 | 否，但需重跑对应测试 | 是（对应测试） | 否 |
-| `BEHAVIORAL_SERVICE_CHANGE` | service 逻辑变化 | 是 | 是 | 是 |
-| `API_CONTRACT_CHANGE` | controller / VO / DTO 变化 | 是 | 是 | 是 |
-| `SQL_OR_MAPPER_CHANGE` | 数据访问层 / sql / 映射文件变化 | 是 | 是 | 是 |
-| `SECURITY_OR_PERMISSION_CHANGE` | 权限 / 组织过滤 / 认证变化 | 是 | 是 | 是 |
-分类方法：对 post-test diff 逐文件判断，按"最严格类型"汇总——只要有一个文件属于行为性变更，整体即视为行为性变更。
-**NON_BEHAVIORAL_CLEANUP 复用记录格式**（写入对应阶段报告）：
-```md
-post-test 变更: NON_BEHAVIORAL_CLEANUP
-影响: 不影响运行时行为
-追加验证: compile + unit test passed（如确实重跑了 compile/unit）
-API 测试: 🔁 复用上一轮结果（diffHash 未变 / 仅清理性变更）
-```
-**行为性变更**：必须重新运行 `/harness-test` 的相关场景（至少覆盖变更影响的接口/权限/SQL），ledger 对应项作废并重写。
-## 七、各阶段与 ledger 的交互
-| 阶段 | 读 ledger | 写 ledger |
-|------|:---:|:---:|
-| harness-plan | 计划起点读（了解前序变更状态/已有 ledger，作为复用链起点） | 计划落定后写初始 ledger（changeName/module/profile/baseCommit/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） |
-## 八、状态与 final-summary 的对应
-ledger 的 `status` 与 final-summary 展示状态对应：
-| ledger status | 含义 | final-summary 标记 |
-|:---:|------|------|
-| `OK`（本阶段真实执行并通过） | 真实验证 | ✅OK |
-| `OK` 但本阶段复用了前一阶段 | 复用 | 🔁REUSED |
-| `OK` 但 post-test 后重测通过 | 重测 | 🔁RETESTED |
-| `WARN` | 静态验证 / 跳过 / 降级 | 🟡WARN |
-| `ADVISORY` | review 参考性 | 📝ADVISORY |
-| postTestClassification=NON_BEHAVIORAL_CLEANUP | 小清理 | 🧹NON_BEHAVIORAL_CLEANUP |
-**强制规则**：任何阶段若复用了前一阶段结果，final-summary 必须显示 `🔁REUSED`，**不得伪装成重新执行**。