@hunter-harness/workflow-harness 0.2.60 → 0.2.61

package/harness/bundles/java/codebuddy/harness-review/SKILL.md

@@ -4,7 +4,7 @@ description: 6维度代码审查（架构/安全/规范/兼容/测试/性能）
   .harness/context-index.json）和测试场景表，在隔离上下文运行。仅当用户显式调用 /harness-review 时使用；不得在
   test 结束后自动接续执行。
 ---
-<!-- generated by harness_deploy.py; core=ed5c4708eeba6351; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=c4b98f515e0ec1ae; overlay=java; agent=codebuddy; do not edit -->
 # harness-review — 代码审查
 
 ## Purpose
@@ -38,7 +38,7 @@ description: 6维度代码审查（架构/安全/规范/兼容/测试/性能）
 6. **implementation-detail** — 自适应执行参考；legacy 缺失 🟡WARN，不阻断
 7. **test-scenarios** — 测试真相源：`plans/<change>-test-scenarios.md`
 8. **禁止读取 `docs/superpowers/` 作为正式输入** — 旧草稿仅人工线索
-9. **每个 skill 边界只刷新一次状态快照** — 先运行 `python <skills-root>/scripts/harness_state.py capture --project . --change-dir ".harness/changes/<change-name>" --base <baseCommit> --json`；`changedSegments=[]` 时复用已有 profile/rules/map/change/code 指纹，不再重复跑全量 `harness-sync` 或代码库扫描。`knowledge` 段仅为兼容空段，知识始终按需远端查询；快照不能替代源码读取和验证门禁。
+9. **每个 skill 边界只刷新一次状态快照** — 先运行 `python <skills-root>/scripts/harness_state.py capture --project . --change-dir ".harness/changes/<change-name>" --json`。首次 Plan 捕获时，脚本把当时的 Git HEAD 写入不可变 `changeBase`；后续阶段只刷新 `git.head` 与各段指纹，不得用当前 HEAD 覆盖 `changeBase`。只有迁移旧 change 且已能证明真实计划起点时，才在首次补录时传 `--base <baseCommit>`。`changedSegments=[]` 时复用已有 profile/rules/map/change/code 指纹，不再重复跑全量 `harness-sync` 或代码库扫描。`knowledge` 段仅为兼容空段，知识始终按需远端查询；快照不能替代源码读取和验证门禁。
 
 状态目录分层：新路径优先，旧路径兼容 → [[../protocols/state-layout-protocol.md|state-layout-protocol]]
 > 片段：read-protocol

package/harness/bundles/java/codebuddy/harness-run/SKILL.md

@@ -3,7 +3,7 @@ name: harness-run
 description: 按变更簇执行 TDD 编码循环（RED→GREEN→REFACTOR→编译验证），逐变更簇实现计划中的任务。仅当用户显式调用
   /harness-run 时使用；不得因用户提到编码/实现就自动触发，也不得被其他阶段 skill 自动接续。
 ---
-<!-- generated by harness_deploy.py; core=ed5c4708eeba6351; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=c4b98f515e0ec1ae; overlay=java; agent=codebuddy; do not edit -->
 # harness-run — 需求编码
 
 ## Purpose
@@ -48,7 +48,7 @@ description: 按变更簇执行 TDD 编码循环（RED→GREEN→REFACTOR→编
 6. **implementation-detail** — 自适应执行参考；legacy 缺失 🟡WARN，不阻断
 7. **test-scenarios** — 测试真相源：`plans/<change>-test-scenarios.md`
 8. **禁止读取 `docs/superpowers/` 作为正式输入** — 旧草稿仅人工线索
-9. **每个 skill 边界只刷新一次状态快照** — 先运行 `python <skills-root>/scripts/harness_state.py capture --project . --change-dir ".harness/changes/<change-name>" --base <baseCommit> --json`；`changedSegments=[]` 时复用已有 profile/rules/map/change/code 指纹，不再重复跑全量 `harness-sync` 或代码库扫描。`knowledge` 段仅为兼容空段，知识始终按需远端查询；快照不能替代源码读取和验证门禁。
+9. **每个 skill 边界只刷新一次状态快照** — 先运行 `python <skills-root>/scripts/harness_state.py capture --project . --change-dir ".harness/changes/<change-name>" --json`。首次 Plan 捕获时，脚本把当时的 Git HEAD 写入不可变 `changeBase`；后续阶段只刷新 `git.head` 与各段指纹，不得用当前 HEAD 覆盖 `changeBase`。只有迁移旧 change 且已能证明真实计划起点时，才在首次补录时传 `--base <baseCommit>`。`changedSegments=[]` 时复用已有 profile/rules/map/change/code 指纹，不再重复跑全量 `harness-sync` 或代码库扫描。`knowledge` 段仅为兼容空段，知识始终按需远端查询；快照不能替代源码读取和验证门禁。
 
 状态目录分层：新路径优先，旧路径兼容 → [[../protocols/state-layout-protocol.md|state-layout-protocol]]
 > 片段：read-protocol · run 必读文件优先级 → `reference.md` Step 0

package/harness/bundles/java/codebuddy/harness-submit/SKILL.md

@@ -3,7 +3,7 @@ name: harness-submit
 description: 最终提交封装：验证→中文 commit→提交/推送；worktree 模式含 --no-ff 合并回主分支。仅当用户显式调用
   /harness-submit（或 /harness-merge 重入合并段）时使用；用户口头说'提交/commit/push'时必须先确认，不得自动触发。
 ---
-<!-- generated by harness_deploy.py; core=ed5c4708eeba6351; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=c4b98f515e0ec1ae; overlay=java; agent=codebuddy; do not edit -->
 # harness-submit — 最终提交（含 worktree 合并）
 
 ## Purpose
@@ -37,7 +37,7 @@ description: 最终提交封装：验证→中文 commit→提交/推送；workt
 6. **implementation-detail** — 自适应执行参考；legacy 缺失 🟡WARN，不阻断
 7. **test-scenarios** — 测试真相源：`plans/<change>-test-scenarios.md`
 8. **禁止读取 `docs/superpowers/` 作为正式输入** — 旧草稿仅人工线索
-9. **每个 skill 边界只刷新一次状态快照** — 先运行 `python <skills-root>/scripts/harness_state.py capture --project . --change-dir ".harness/changes/<change-name>" --base <baseCommit> --json`；`changedSegments=[]` 时复用已有 profile/rules/map/change/code 指纹，不再重复跑全量 `harness-sync` 或代码库扫描。`knowledge` 段仅为兼容空段，知识始终按需远端查询；快照不能替代源码读取和验证门禁。
+9. **每个 skill 边界只刷新一次状态快照** — 先运行 `python <skills-root>/scripts/harness_state.py capture --project . --change-dir ".harness/changes/<change-name>" --json`。首次 Plan 捕获时，脚本把当时的 Git HEAD 写入不可变 `changeBase`；后续阶段只刷新 `git.head` 与各段指纹，不得用当前 HEAD 覆盖 `changeBase`。只有迁移旧 change 且已能证明真实计划起点时，才在首次补录时传 `--base <baseCommit>`。`changedSegments=[]` 时复用已有 profile/rules/map/change/code 指纹，不再重复跑全量 `harness-sync` 或代码库扫描。`knowledge` 段仅为兼容空段，知识始终按需远端查询；快照不能替代源码读取和验证门禁。
 
 状态目录分层：新路径优先，旧路径兼容 → [[../protocols/state-layout-protocol.md|state-layout-protocol]]
 > 片段：read-protocol

package/harness/bundles/java/codebuddy/harness-sync/SKILL.md

@@ -4,7 +4,7 @@ description: Use when the user asks to synchronize, refresh, or validate Harness
   metadata, adapters, remote knowledge ownership, instruction entrypoints,
   config origins, or CodeGraph status.
 ---
-<!-- generated by harness_deploy.py; core=ed5c4708eeba6351; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=c4b98f515e0ec1ae; overlay=java; agent=codebuddy; do not edit -->
 # harness-sync
 
 ## Purpose

package/harness/bundles/java/codebuddy/harness-test/SKILL.md

@@ -3,7 +3,7 @@ name: harness-test
 description: 测试执行：读取场景表，执行单元测试+API接口测试+数据兼容验证，输出测试报告。仅当用户显式调用 /harness-test
   时使用；不得在 run 结束后自动接续执行。
 ---
-<!-- generated by harness_deploy.py; core=ed5c4708eeba6351; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=c4b98f515e0ec1ae; overlay=java; agent=codebuddy; do not edit -->
 # harness-test — 测试执行
 
 ## Purpose
@@ -39,7 +39,7 @@ description: 测试执行：读取场景表，执行单元测试+API接口测试
 6. **implementation-detail** — 自适应执行参考；legacy 缺失 🟡WARN，不阻断
 7. **test-scenarios** — 测试真相源：`plans/<change>-test-scenarios.md`
 8. **禁止读取 `docs/superpowers/` 作为正式输入** — 旧草稿仅人工线索
-9. **每个 skill 边界只刷新一次状态快照** — 先运行 `python <skills-root>/scripts/harness_state.py capture --project . --change-dir ".harness/changes/<change-name>" --base <baseCommit> --json`；`changedSegments=[]` 时复用已有 profile/rules/map/change/code 指纹，不再重复跑全量 `harness-sync` 或代码库扫描。`knowledge` 段仅为兼容空段，知识始终按需远端查询；快照不能替代源码读取和验证门禁。
+9. **每个 skill 边界只刷新一次状态快照** — 先运行 `python <skills-root>/scripts/harness_state.py capture --project . --change-dir ".harness/changes/<change-name>" --json`。首次 Plan 捕获时，脚本把当时的 Git HEAD 写入不可变 `changeBase`；后续阶段只刷新 `git.head` 与各段指纹，不得用当前 HEAD 覆盖 `changeBase`。只有迁移旧 change 且已能证明真实计划起点时，才在首次补录时传 `--base <baseCommit>`。`changedSegments=[]` 时复用已有 profile/rules/map/change/code 指纹，不再重复跑全量 `harness-sync` 或代码库扫描。`knowledge` 段仅为兼容空段，知识始终按需远端查询；快照不能替代源码读取和验证门禁。
 
 状态目录分层：新路径优先，旧路径兼容 → [[../protocols/state-layout-protocol.md|state-layout-protocol]]
 > 片段：read-protocol

package/harness/bundles/java/codebuddy/protocols/archive-report-protocol.md

@@ -6,7 +6,7 @@ description: harness-archive 的结构化归档与 summary-data 校验协议。
 
 ## 原则
 
-归档不应维护与平台重复的展示文件。事实收集与校验由 `harness_archive.py 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）。
+归档不应维护与平台重复的展示文件。常规入口是 `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，截断超大日志。
 
@@ -141,7 +141,11 @@ powershell.exe -NoProfile -ExecutionPolicy Bypass -File "harness-skills/harness-
 
 ## 数据校验
 
-`validate` 是 `harness_archive.py finalize` 的内嵌同进程步骤（不存在独立 `report validate` CLI）。validate error 存在时，finalize 恢复原 changes 目录并 exit 非 0，绝不删除原 changes 目录。Hunter Platform 直接读取已校验的 `summary-data.json`。
+`validate` 是 finalize 的内嵌同进程步骤（不存在独立 `report validate` CLI）。validate error 存在时，finalize 恢复原 changes 目录并 exit 非 0，绝不删除原 changes 目录。warning 保留在报告中，但不会被误判为 validate error。Hunter Platform 直接读取已校验的 `summary-data.json`。
+
+正常完成时，`baseCommit` 与产品 tip 相同属于 `ARCHIVE_BASE_EQUALS_FEATURE_TIP`，必须在暂存前阻断。不得手工改 ledger 或 state snapshot。已有提交确属本变更时，使用 `adopt-existing-range` 生成绑定仓库、ownership 和 diffHash 的不可变收据；主动废弃或被替代时允许零产品增量，但必须记录中文原因，且固定 `releaseEligible=false`。
+
+候选收据缺失时，`execute` 可以复用身份一致、范围完整的 `unitTestFull` ledger 自动生成本地候选认证。提交只改变 commit 身份而产品树和验证输入未变化时，允许安全重绑定到当前 HEAD；该过程不得执行测试。门禁策略未声明数据库能力且未要求 `dbCompatibility` 时，数据库投影为带原因的 `NOT_APPLICABLE`，不得把缺少无关数据库证据升级为归档错误。
 
 ## 冻结优先 finalize 与两层一致性（schemaVersion 2.3 起）
 
@@ -167,7 +171,7 @@ repair 先在 archive 外生成候选 derived version。来源校验与数据校
 archive close 的破坏性事务只执行确定性 close：
 
 ```text
-status -> manifest -> move -> collect -> validate -> compare
+execute(one-shot status + gate) -> manifest -> move -> collect -> validate -> compare
 -> 生成确定性核心 ZIP -> 上传并等待服务端持久化/ingest 收据 -> stop AI service -> return
 ```
 

package/harness/bundles/java/codebuddy/protocols/ledger-protocol.md

@@ -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/java/codebuddy/protocols/report-pipeline-protocol.md

@@ -19,12 +19,12 @@ description: 结构化事件、summary-data 生成与校验，以及外部可观
 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` 与 `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,14 +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` |
 | `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 目录。
 

package/harness/bundles/java/codebuddy/protocols/state-layout-protocol.md

@@ -141,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：
 
@@ -150,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>"},
@@ -159,7 +160,7 @@ 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。