@hunter-harness/workflow-harness 0.2.29 → 0.2.31

package/harness/bundles/general/codebuddy/harness-plan/SKILL.md

@@ -2,7 +2,7 @@
 name: harness-plan
 description: 将需求转化为设计文档+实施计划+完整测试场景表，必须在编码前完成。使用场景：需求分析、feature plan、技术方案设计、实现方案规划
 ---
-<!-- generated by harness_deploy.py; core=9a2ab44ad7a34065; overlay=none; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=33c3c012031041b2; overlay=none; agent=codebuddy; do not edit -->
 # harness-plan — 需求规划
 
 ## Purpose
@@ -64,14 +64,14 @@ description: 将需求转化为设计文档+实施计划+完整测试场景表
 | 阶段 | 动作 |
 |------|------|
 | 0 | 用当前解释器运行 `harness_runtime.py doctor`，后续消费绝对 argv；git status；脏工作区 → baseline 隔离 + `decision`，不询问 |
-| 0.5 | 先初始化 change-name + `phase.start`，从第一条知识查询起保留事件证据 |
+| 0.5 | 先初始化 change-name、plan-run-id 与 attempt（首次为 1），用同一身份追加 `phase.start`；从第一条知识查询起保留事件证据，并在 finalizer 中复用该身份 |
 | 1 | `harness-knowledge-query` 单次 query（内部 ensure-current；失败记 `issue`） |
 | 2 | 歧义优先检查 + 复杂度分级；先确认会改变实现方向的语义歧义 |
 | 3 | 按复杂度执行有预算的代码探索；简单修复不得扩散到无关模块 |
 | 4 | **设计审批包** blocking user confirmation；确认事件早于 approved 设计文档和 `meta/worktree.json` |
 | 5–6 | plan + implementation-detail + test-scenarios → `plans/` |
 | 7.5 | 仅 `--adversarial` 对抗评审 |
-| 8 | 在临时产物集上运行 `harness_plan_finalize.py finalize`；原子发布、唯一 `phase.end`、render → `checklist.md` |
+| 8 | 在临时产物集上运行 `harness_plan_finalize.py finalize`，随后立即运行 `verify`；原子发布、派生清单计数对账、完整生命周期、render → `checklist.md` |
 
 change-name 范围变更 → 提示重命名或记 🟡WARN（→ `reference.md`）
 
@@ -88,7 +88,7 @@ change-name 范围变更 → 提示重命名或记 🟡WARN（→ `reference.md`
 |------|------|
 | 产物路径 | 只写 `.harness/changes/<cn>/`；禁止 superpowers 输入 |
 | 设计审批包 | 一次 blocking user confirmation 含 worktree（读 `harness.json` `defaultWorktree`） |
-| 阶段 8 | spec/plan/detail/scenarios/worktree.json 先进入 staging；仅 finalizer 校验成功后发布并写唯一 `phase.end`/log，失败不得手工补终态 |
+| 阶段 8 | spec/plan/detail/scenarios/worktree.json 先进入 staging；仅 finalizer 校验成功后发布并写唯一 `phase.end`/log；随后 `verify` 必须确认 start/end、收据哈希、全部任务表和非空场景清单一致，失败不得手工补终态 |
 | Plan 结束 | **禁止**询问执行模式；只提示 `/harness-run` |
 | 知识查询 | 0.5 失败不得假装已读历史 |
 | 歧义优先检查 | 否定、对比、动作对象或范围存在多种合理解释时，最小取证后先给推荐理解并一次一问；确认前不深挖错误方向 |
@@ -116,12 +116,12 @@ change-name 范围变更 → 提示重命名或记 🟡WARN（→ `reference.md`
 `events.ndjson` 为唯一事实源（schema_version 3，兼容读取 v1/v2；`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止用 Write/Edit 直接维护**。直接修改的内容会在 `phase.end` 或 finalize 时被完整重建覆盖，属于数据丢失；需要保留的详情必须进入事件 `note`。结构 → [[../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 "<触发指令>"
+python <skills-root>/scripts/harness_events.py append --change-dir ".harness/changes/<change-name>" --phase <phase> --type phase.start --run-id <phase-run-id> --attempt <n> --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 边界保持最新。
 
-每次阶段结束必须写 `--status OK|WARN|FAIL|BLOCKED`；重试同一阶段时增加 `--attempt <n>`，不得覆盖或伪装成一次执行。跨工具继续执行时写 `--executor-tool <codex|claude-code|codebuddy|cursor>`，并在接棒事件写 `--handoff-from-tool` / `--handoff-reason`；也可由 `HUNTER_HARNESS_TOOL/AGENT/MODEL/RUN_ID` 环境变量统一注入。
+每个阶段的 `phase.start` 与对应 `phase.end` 必须复用同一 `--run-id` / `--attempt`；阶段结束必须写 `--status OK|WARN|FAIL|BLOCKED`。重试同一阶段时生成新的 run-id 并增加 `--attempt <n>`，不得覆盖或伪装成一次执行。跨工具继续执行时写 `--executor-tool <codex|claude-code|codebuddy|cursor>`，并在接棒事件写 `--handoff-from-tool` / `--handoff-reason`；也可由 `HUNTER_HARNESS_TOOL/AGENT/MODEL/RUN_ID` 环境变量统一注入。
 > 片段：logging · phase=`plan`

package/harness/bundles/general/codebuddy/harness-plan/checklist.md

@@ -14,7 +14,7 @@ description: harness-plan 的阶段检查清单和覆盖检查列表。仅在执
 
 ## 阶段 0.5：事件初始化与知识查询
 
-- [ ] 先确定 change-name，并立即用 `harness_events.py append` 追加 `phase.start`
+- [ ] 先确定 change-name、稳定的 plan-run-id 与 attempt（首次为 1），立即用 `harness_events.py append ... --phase plan --type phase.start --run-id <plan-run-id> --attempt <attempt>` 追加开始事件
 - [ ] 再执行一次 knowledge `query`；由 query 内部 ensure-current，不另跑前置 sync
 - [ ] 查询失败追加 `issue`，不得重跑“sync + query”循环或假装已读取历史
 
@@ -210,8 +210,11 @@ source: harness-plan
 > **缺任一文件 → ❌FAIL，不得宣称 plan 完成。**
 
 - [ ] 所有待发布产物先写入 staging，不直接覆盖正式 change 目录
-- [ ] 执行 `harness_plan_finalize.py finalize --change-dir ... --staging-dir ... --change ... --run-id ... --attempt ... --json`
+- [ ] 执行 `harness_plan_finalize.py finalize --change-dir ... --staging-dir ... --change ... --run-id <plan-run-id> --attempt <attempt> --json`；身份必须与本次 `phase.start` 完全相同
 - [ ] finalizer 返回 `ok=true` 与 `artifactsHash`；重复执行返回 `idempotent=true`
+- [ ] 紧接着执行 `harness_plan_finalize.py verify --change-dir ... --json`
+- [ ] verify 返回 `phaseStartCount=1`、`phaseEndCount=1`、`phaseEndStatus=OK`、`receiptConsistent=true`
+- [ ] verify 的 `taskCount` 等于全部任务表行数，`scenarioCount` 等于 Markdown 中全部唯一场景 ID 数；任一为 0 或不一致即 ❌FAIL
 - [ ] finalizer 失败时正式目录无半发布产物、无成功 `phase.end`、无伪造 execution log
 - [ ] 禁止在 finalizer 之前手工追加成功 `phase.end`
 
@@ -222,6 +225,9 @@ source: harness-plan
 | `.harness/changes/<change>/plans/<change>-implementation-detail.md` | ✅ | □ |
 | `.harness/changes/<change>/plans/<change>-test-scenarios.md` | ✅ | □ |
 | `.harness/changes/<change>/meta/worktree.json` | ✅ | □ |
+| `.harness/changes/<change>/meta/implementation-checkpoints.json` | ✅ | □ |
+| `.harness/changes/<change>/meta/scenario-manifest.json`（非空且计数一致） | ✅ | □ |
+| `.harness/changes/<change>/meta/plan-finalization.json`（finalized） | ✅ | □ |
 | `.harness/changes/<change>/logs/execution-log.md` | ✅ | □ |
 | `.harness/changes/<change>/events.ndjson` | ✅ | □ |
 
@@ -244,7 +250,7 @@ source: harness-plan
 
 ## 关键原则
 
-- **产物路径唯一性**：`.harness/changes/<change-name>/` 是唯一真相源，plan 产物必须直接写入此目录
+- **产物路径唯一性**：正式 `.harness/changes/<change-name>/` 是唯一真相源；plan 只写 staging，由 finalizer 原子发布，禁止先写正式目录再补 staging
 - **原生规划协议**：阶段 4/6 使用 clarification、decision-grilling、implementation-planning 三段内置协议，不运行时依赖 Superpowers/grill-me/writing-plans
 - **阶段 4 是强制阻断检查点**——展示设计审批包后必须停下来问用户，收到回复后才能写 approved 设计文档。不要跳过
 - 代码探索只读不写——这个阶段的目标是理解，不是修改
@@ -255,7 +261,7 @@ source: harness-plan
 
 ## 事件记录（前置规则）
 
-- [ ] 确定 change-name 后立即 append `phase.start` 事件；各阶段用 `harness_events.py append` 写入 `decision` / `issue` / `artifact`
+- [ ] 确定 change-name 后立即用稳定且可复用的 `--run-id` / `--attempt` append `phase.start` 事件；各阶段用 `harness_events.py append` 写入 `decision` / `issue` / `artifact`
 - [ ] 阶段 0 在 change-name 确定前可不写事件；阶段 0.5 确定 change-name 后必须开始记录
 
 ## 需求范围缩减后的 change-name 检查 ⚠️

package/harness/bundles/general/codebuddy/harness-plan/reference.md

@@ -228,35 +228,35 @@ status: approved
 
 #### 1.1 <类名.方法名>
 
-| # | 分类 | 场景描述 | 输入 | 预期 | 执行层级 | 预计时长 | 资源预算 | 超时 | 可复用证据 |
-|:--:|:----:|----------|------|------|----------|----------|----------|------|------------|
-| UT-001 | 正常 | ... | ... | ... | affected | ≤10s | 1 worker / ≤512MB | 30s | inputsHash + command |
-| UT-002 | 异常 | ... | ... | 抛 xxxException | affected | ≤10s | 1 worker / ≤512MB | 30s | inputsHash + command |
-| UT-003 | 边界 | ... | ... | ... | module | ≤60s | ≤50% CPU / ≤1GB | 120s | ledger identity |
+| ID | 优先级 | 分类 | 场景描述 | 输入 | 预期 | 执行层级 | 预计时长 | 资源预算 | 超时 | 可复用证据 |
+|:--:|:------:|:----:|----------|------|------|----------|----------|----------|------|------------|
+| UT-001 | P0 | 正常 | ... | ... | ... | affected | ≤10s | 1 worker / ≤512MB | 30s | inputsHash + command |
+| UT-002 | P0 | 异常 | ... | ... | 抛 xxxException | affected | ≤10s | 1 worker / ≤512MB | 30s | inputsHash + command |
+| UT-003 | P1 | 边界 | ... | ... | ... | module | ≤60s | ≤50% CPU / ≤1GB | 120s | ledger identity |
 
 ### 二、接口测试场景
 
 #### 2.1 POST /xxx
 
-| # | 分类 | 场景描述 | 关键字段 | HTTP | code | message | 执行层级 | 预计时长 | 资源预算 | 超时 | 可复用证据 |
-|:--:|:----:|----------|----------|:----:|:----:|--------|----------|----------|----------|------|------------|
-| API-001 | 正常 | ... | ... | 200 | 0 | 成功 | module | ≤60s | 1 service / ≤1GB | 120s | environmentHash + ledger |
-| API-002 | 校验 | ... | ... | 200 | xxx | ... | affected | ≤20s | 1 service / ≤1GB | 60s | environmentHash + ledger |
+| ID | 优先级 | 分类 | 场景描述 | 关键字段 | HTTP | code | message | 执行层级 | 预计时长 | 资源预算 | 超时 | 可复用证据 |
+|:--:|:------:|:----:|----------|----------|:----:|:----:|--------|----------|----------|----------|------|------------|
+| API-001 | P0 | 正常 | ... | ... | 200 | 0 | 成功 | module | ≤60s | 1 service / ≤1GB | 120s | environmentHash + ledger |
+| API-002 | P1 | 校验 | ... | ... | 200 | xxx | ... | affected | ≤20s | 1 service / ≤1GB | 60s | environmentHash + ledger |
 
 ### 三、数据兼容场景
 
-| # | 分类 | 场景描述 | 操作 | 数据特征 | 预期 | 执行层级 | 预计时长 | 资源预算 | 超时 | 可复用证据 |
-|:--:|:----:|----------|:----:|----------|------|----------|----------|----------|------|------------|
-| COM-001 | 旧数据 | ... | ... | ... | ... | module | ≤60s | isolated DB / ≤1GB | 120s | dbSchemaHash + ledger |
+| ID | 优先级 | 分类 | 场景描述 | 操作 | 数据特征 | 预期 | 执行层级 | 预计时长 | 资源预算 | 超时 | 可复用证据 |
+|:--:|:------:|:----:|----------|:----:|----------|------|----------|----------|----------|------|------------|
+| COM-001 | P1 | 旧数据 | ... | ... | ... | ... | module | ≤60s | isolated DB / ≤1GB | 120s | dbSchemaHash + ledger |
 
 ### 四、集成场景
 
-| # | 分类 | 场景描述 | 前置条件 | 步骤 | 预期 | 执行层级 | 预计时长 | 资源预算 | 超时 | 可复用证据 |
-|:--:|:----:|----------|----------|------|------|----------|----------|----------|------|------------|
-| INT-001 | 端到端 | ... | ... | N 步操作 | ... | candidate | ≤10m | ≤50% CPU / ≤2GB | 15m | verification identity |
+| ID | 优先级 | 分类 | 场景描述 | 前置条件 | 步骤 | 预期 | 执行层级 | 预计时长 | 资源预算 | 超时 | 可复用证据 |
+|:--:|:------:|:----:|----------|----------|------|------|----------|----------|----------|------|------------|
+| INT-001 | P0 | 端到端 | ... | ... | N 步操作 | ... | candidate | ≤10m | ≤50% CPU / ≤2GB | 15m | verification identity |
 ```
 
-执行层级固定为 `affected`（快速反馈）、`module`（变更模块门禁）、`candidate`（产品候选）。禁止所有场景默认跑全仓库；无法给出预算或超时时必须说明原因，并拆分或隔离高成本场景。只有 command、inputs/toolchain/environment 身份一致的成功 ledger 证据可以复用。
+新计划必须显式使用 `ID` 和 `优先级` 列；`P0/P1` 都要求 ledger 证据，`P2` 才是 advisory。解析器兼容旧的 `#`、`分类`、`场景描述` 表头，旧表缺优先级时保守按 `P1` 处理。执行层级固定为 `affected`（快速反馈）、`module`（变更模块门禁）、`candidate`（产品候选）。禁止所有场景默认跑全仓库；无法给出预算或超时时必须说明原因，并拆分或隔离高成本场景。只有 command、inputs/toolchain/environment 身份一致的成功 ledger 证据可以复用。
 
 ## 产物保存规则（跨阶段：阶段0.5/4/6/8）
 
@@ -299,7 +299,7 @@ status: approved
 
    > 如果 frontmatter 缺失，后续 run/test/review/submit/archive 不得依赖模型猜测 change-name。
 
-4. **初始化结构化事件**：确定 change-name 后，立即运行 `harness_events.py append --type phase.start`。脚本负责建立父目录和 `events.ndjson`；执行日志在 `phase.end` 时由完整事件流渲染，任何阶段都不得直接用 Write/Edit 维护该投影。
+4. **初始化结构化事件**：确定 change-name 后，立即生成稳定的 `<plan-run-id>`（同一次 plan 尝试内不得改变；首次 `<attempt>` 为 `1`），运行 `harness_events.py append --change-dir ... --phase plan --type phase.start --run-id <plan-run-id> --attempt <attempt>`。finalizer 必须复用完全相同的 `--run-id` / `--attempt`，否则 verify 会按生命周期身份 fail-closed。脚本负责建立父目录和 `events.ndjson`；执行日志在 `phase.end` 时由完整事件流渲染，任何阶段都不得直接用 Write/Edit 维护该投影。
 
 5. **保存计划文件**：计划文件包含 YAML frontmatter（含 change-name），保存到：
    - `.harness/changes/<change-name>/plans/<change-name>-plan.md`（简洁任务表）

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

@@ -3,7 +3,7 @@ name: harness-review
 description: 6维度代码审查（架构/安全/规范/兼容/测试/性能），对照项目规则（见
   .harness/context-index.json）和测试场景表，在隔离上下文运行。使用场景：代码审查、提交前检查、合并评审
 ---
-<!-- generated by harness_deploy.py; core=9a2ab44ad7a34065; overlay=none; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=33c3c012031041b2; overlay=none; agent=codebuddy; do not edit -->
 # harness-review — 代码审查
 
 ## Purpose
@@ -143,12 +143,12 @@ review 读取 `state-snapshot.json`（`harness_state.py` / state-layout-protocol
 `events.ndjson` 为唯一事实源（schema_version 3，兼容读取 v1/v2；`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止用 Write/Edit 直接维护**。直接修改的内容会在 `phase.end` 或 finalize 时被完整重建覆盖，属于数据丢失；需要保留的详情必须进入事件 `note`。结构 → [[../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 "<触发指令>"
+python <skills-root>/scripts/harness_events.py append --change-dir ".harness/changes/<change-name>" --phase <phase> --type phase.start --run-id <phase-run-id> --attempt <n> --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 边界保持最新。
 
-每次阶段结束必须写 `--status OK|WARN|FAIL|BLOCKED`；重试同一阶段时增加 `--attempt <n>`，不得覆盖或伪装成一次执行。跨工具继续执行时写 `--executor-tool <codex|claude-code|codebuddy|cursor>`，并在接棒事件写 `--handoff-from-tool` / `--handoff-reason`；也可由 `HUNTER_HARNESS_TOOL/AGENT/MODEL/RUN_ID` 环境变量统一注入。
+每个阶段的 `phase.start` 与对应 `phase.end` 必须复用同一 `--run-id` / `--attempt`；阶段结束必须写 `--status OK|WARN|FAIL|BLOCKED`。重试同一阶段时生成新的 run-id 并增加 `--attempt <n>`，不得覆盖或伪装成一次执行。跨工具继续执行时写 `--executor-tool <codex|claude-code|codebuddy|cursor>`，并在接棒事件写 `--handoff-from-tool` / `--handoff-reason`；也可由 `HUNTER_HARNESS_TOOL/AGENT/MODEL/RUN_ID` 环境变量统一注入。
 > 片段：logging · phase=`review` · 事件：phase/decision/verification/issue/artifact

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

@@ -2,7 +2,7 @@
 name: harness-run
 description: 按变更簇执行 TDD 编码循环（RED→GREEN→REFACTOR→编译验证），逐变更簇实现计划中的任务。使用场景：开始编码、实现功能、写代码、TDD 编码
 ---
-<!-- generated by harness_deploy.py; core=9a2ab44ad7a34065; overlay=none; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=33c3c012031041b2; overlay=none; agent=codebuddy; do not edit -->
 # harness-run — 需求编码
 
 ## Purpose
@@ -56,7 +56,7 @@ description: 按变更簇执行 TDD 编码循环（RED→GREEN→REFACTOR→编
 
 ## Workflow 概要
 
-0. 加载上下文：先 `harness_change.py resolve [--change] --json`（多 active 缺参 → `CHANGE_SELECTION_REQUIRED`，禁止按 mtime 猜测）；读 spec/plan/detail/scenarios/ledger/run-task-status/worktree；`--fixback` 读 fixback → **`harness_gate.py begin --phase run --change <id>`**（内部 claim + phase.start + identity；禁止手工 Write `events.ndjson` / 手工 `phase.end`）
+0. 加载上下文：先 `harness_change.py resolve [--change] --json`（多 active 缺参 → `CHANGE_SELECTION_REQUIRED`，禁止按 mtime 猜测）；读 spec/plan/detail/scenarios/ledger/run-task-status/worktree；`--fixback` 读 fixback → **`harness_gate.py begin --phase run --change <id>`**（先 fail-closed 校验 Plan 收据/哈希/完整生命周期/全部任务/非空场景清单，再 claim + phase.start + identity；禁止手工 Write `events.ndjson` / 手工 `phase.end`）
 0.5. **测试基础设施探测**（先写 `CHECKING`，四项证据齐备后再结论）→ `reference.md` Step 0.5；进入 TDD 前执行 `harness_test_guard.py begin --project . --change-dir ".harness/changes/<cn>" --json`
 1. **变更簇 TDD** — `protocols.md` `run-tdd-protocol`；批量 RED/GREEN；按需 `change-cluster-review-protocol`（高风险 + reviewer 预检可用）
 2. 构建验证 + **仅**通过 `harness_ledger.py record` 写 ledger（禁止 Write/Edit `verification-ledger.json`）；`diff-hash --change-dir` 纳入 ignored tests → `reference.md` Step 2c
@@ -124,12 +124,12 @@ python <skills-root>/scripts/harness_test_guard.py record --project . --change-d
 `events.ndjson` 为唯一事实源（schema_version 3，兼容读取 v1/v2；`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止用 Write/Edit 直接维护**。直接修改的内容会在 `phase.end` 或 finalize 时被完整重建覆盖，属于数据丢失；需要保留的详情必须进入事件 `note`。结构 → [[../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 "<触发指令>"
+python <skills-root>/scripts/harness_events.py append --change-dir ".harness/changes/<change-name>" --phase <phase> --type phase.start --run-id <phase-run-id> --attempt <n> --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 边界保持最新。
 
-每次阶段结束必须写 `--status OK|WARN|FAIL|BLOCKED`；重试同一阶段时增加 `--attempt <n>`，不得覆盖或伪装成一次执行。跨工具继续执行时写 `--executor-tool <codex|claude-code|codebuddy|cursor>`，并在接棒事件写 `--handoff-from-tool` / `--handoff-reason`；也可由 `HUNTER_HARNESS_TOOL/AGENT/MODEL/RUN_ID` 环境变量统一注入。
+每个阶段的 `phase.start` 与对应 `phase.end` 必须复用同一 `--run-id` / `--attempt`；阶段结束必须写 `--status OK|WARN|FAIL|BLOCKED`。重试同一阶段时生成新的 run-id 并增加 `--attempt <n>`，不得覆盖或伪装成一次执行。跨工具继续执行时写 `--executor-tool <codex|claude-code|codebuddy|cursor>`，并在接棒事件写 `--handoff-from-tool` / `--handoff-reason`；也可由 `HUNTER_HARNESS_TOOL/AGENT/MODEL/RUN_ID` 环境变量统一注入。
 > 片段：logging · phase=`run`

package/harness/bundles/general/codebuddy/harness-run/checklist.md

@@ -39,7 +39,7 @@ description: harness-run 的执行检查清单。仅在编码执行时读取。
 - [ ] 检查构建配置完整性（worktree 中确认构建配置文件存在，如 Java 的 `.mvn/maven.config`、`settings.xml`，前端的 `package.json`/lockfile 等）
 - [ ] 依赖模块预安装（worktree 中检查上游依赖是否已安装，如 Java 的 `mvn install`、前端的 `npm install`/lockfile 等）
 - [ ] 代码探索优先用 `codegraph_explore`，仅在返回不完整时补充 Read
-- [ ] append `phase.start` 事件（`harness_events.py append`；`note` 含 `测试基础设施: CHECKING`，不得先写降级结论）
+- [ ] `harness_gate.py begin --phase run` 已返回 Plan handoff 校验通过并自动 append `phase.start`；不得手工写事件绕过
 
 ### 步骤 0.1：执行模式（无询问）
 
@@ -231,7 +231,7 @@ description: harness-run 的执行检查清单。仅在编码执行时读取。
 
 ## 步骤 6：计划状态持久化
 
-- [ ] 每个任务状态更新到 plan 文件或新增 `evidence/run-task-status.md`
+- [ ] 每个任务状态只更新到 `evidence/run-task-status.md`；不得修改 finalized plan 文件
 - [ ] 状态区分：✅ DONE_AUTOMATED_TESTED / 🟡 DONE_STATIC_ONLY / 🟡 DONE_NEEDS_INTERFACE_TEST / 🟡 NEEDS_DB_VALIDATION / ❌ FAILED
 - [ ] 确保后续 harness-test / harness-review 可读取待验证场景
 

package/harness/bundles/general/codebuddy/harness-run/reference.md

@@ -83,7 +83,7 @@ requested=true + path missing
 
 
 
-> ⚠️ **phase.start 前置**：步骤 0 第一件事是 `harness_events.py append --type phase.start`（见 SKILL.md `## 执行日志`）。**任何代码修改前必须先记录**，不能等代码改完才补。
+> ⚠️ **Plan handoff / phase.start 前置**：步骤 0 第一件事是执行 `harness_gate.py begin --phase run`。它先校验 Plan 收据、哈希、生命周期、全部任务和非空场景清单，再自动追加 `phase.start`。**任何代码修改前必须成功**，不得手工补事件绕过。
 > ⚠️ **测试基础设施探测前置**：步骤 0 中必须首先执行"步骤 0.5 测试基础设施探测"，探测完成前不得写任何 TDD 降级结论。
 
 1. **确定变更名**：用 Glob 搜索 `.harness/changes/*/plans/*-plan.md`（**排除 `.harness/archive/*/`**），读取找到的 plan.md 的 YAML frontmatter，提取 `change-name`。默认最多一个未归档变更；如有多个，优先取最近修改的，或询问用户选择。
@@ -711,17 +711,7 @@ powershell.exe -Command "git -C '<project-path>' diff --check"
 
 ### 持久化方式
 
-**方式一（推荐）**：更新 plan.md 中的任务状态
-
-在 plan.md 的任务列表中，为每个任务追加状态标记：
-
-```markdown
-### Task 1: 修复分页查询缺项目类型 Bug
-- **状态**: ✅ DONE_AUTOMATED_TESTED
-- **测试**: UT-001~005 已通过
-```
-
-**方式二**：新增 `evidence/run-task-status.md`
+只能新增或更新 `evidence/run-task-status.md`。finalized 的 spec/plan/detail/scenarios/gate-policy 属于 Plan 收据哈希覆盖的不可变输入，Run 不得追加状态、改勾选框或重排表格。
 
 在 `.harness/changes/<change-name>/evidence/run-task-status.md` 中记录：
 
@@ -750,6 +740,7 @@ powershell.exe -Command "git -C '<project-path>' diff --check"
 ### 规则
 
 - 不允许只在对话里说"任务完成"但不写入任何持久化文件
+- 不允许修改 finalized plan Markdown 来记录状态；恢复信息只写 `evidence/run-task-status.md`
 - 后续 harness-test 和 harness-review 必须能从持久化状态识别哪些场景仍待验证
 
 ## 输出示例

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

@@ -3,7 +3,7 @@ name: harness-submit
 description: 最终提交封装：验证→中文 commit→提交/推送；worktree 模式含 --no-ff
   合并回主分支。使用场景：提交代码、commit、push、合并分支、merge to main、完成开发
 ---
-<!-- generated by harness_deploy.py; core=9a2ab44ad7a34065; overlay=none; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=33c3c012031041b2; overlay=none; agent=codebuddy; do not edit -->
 # harness-submit — 最终提交（含 worktree 合并）
 
 ## Purpose
@@ -157,12 +157,12 @@ git 经 PowerShell；commit/报告不得含明文密钥。遵循 `../protocols/s
 `events.ndjson` 为唯一事实源（schema_version 3，兼容读取 v1/v2；`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止用 Write/Edit 直接维护**。直接修改的内容会在 `phase.end` 或 finalize 时被完整重建覆盖，属于数据丢失；需要保留的详情必须进入事件 `note`。结构 → [[../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 "<触发指令>"
+python <skills-root>/scripts/harness_events.py append --change-dir ".harness/changes/<change-name>" --phase <phase> --type phase.start --run-id <phase-run-id> --attempt <n> --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 边界保持最新。
 
-每次阶段结束必须写 `--status OK|WARN|FAIL|BLOCKED`；重试同一阶段时增加 `--attempt <n>`，不得覆盖或伪装成一次执行。跨工具继续执行时写 `--executor-tool <codex|claude-code|codebuddy|cursor>`，并在接棒事件写 `--handoff-from-tool` / `--handoff-reason`；也可由 `HUNTER_HARNESS_TOOL/AGENT/MODEL/RUN_ID` 环境变量统一注入。
+每个阶段的 `phase.start` 与对应 `phase.end` 必须复用同一 `--run-id` / `--attempt`；阶段结束必须写 `--status OK|WARN|FAIL|BLOCKED`。重试同一阶段时生成新的 run-id 并增加 `--attempt <n>`，不得覆盖或伪装成一次执行。跨工具继续执行时写 `--executor-tool <codex|claude-code|codebuddy|cursor>`，并在接棒事件写 `--handoff-from-tool` / `--handoff-reason`；也可由 `HUNTER_HARNESS_TOOL/AGENT/MODEL/RUN_ID` 环境变量统一注入。
 > 片段：logging · phase=`submit`/`merge`

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

@@ -1,89 +1,68 @@
 ---
 name: harness-sync
-description: 检查并更新项目AI元数据（CodeGraph索引、harness-codebase-map分析、CLAUDE.md、AGENTS.md、.harness/完整性），确保Claude对代码库的理解与最新代码一致。当用户说'同步/更新索引/刷新元数据/检查一致性'时使用
+description: Use when the user asks to synchronize, refresh, or validate Harness
+  metadata, adapters, knowledge, rules, instruction entrypoints, config origins,
+  or CodeGraph status.
 ---
-<!-- generated by harness_deploy.py; core=9a2ab44ad7a34065; overlay=none; agent=codebuddy; do not edit -->
-# harness-sync — 元数据同步
+<!-- generated by harness_deploy.py; core=33c3c012031041b2; overlay=none; agent=codebuddy; do not edit -->
+# harness-sync
 
 ## Purpose
 
-检查并更新 AI 元数据（CodeGraph、codebase map、knowledge 索引、公共规则、CLAUDE.md、AGENTS.md、`.harness/`），使理解与代码一致。
+通过一个有界入口同步 Harness 投影、知识、公共规则和元数据，并输出可验证的组件收据。
 
-## When to Use
+## Before running
 
-「同步/更新索引/刷新元数据」、提交前校准、archive/knowledge 变化后。跳过：刚 sync 且无新提交。
-
-## Workflow（薄编排）
-
-运行开始先执行受管 runtime 生命周期：
+读取 `reference.md`。先执行只读能力握手；若最低 CLI 版本或任一必需能力不满足，立即停止，不得先运行 knowledge、refresh 或其他重操作：
 
 ```powershell
-python <skills-root>/scripts/harness_sync.py reap --project . --json
-python <skills-root>/scripts/harness_sync.py begin --project . --run-id <run-id> --agent <agent> --purpose harness-sync --json
+npx hunter-harness capabilities --json
 ```
 
-所有 deploy 临时产物只能写入 `begin` 返回的 `workspace`。无论正常完成、命令失败还是异常退出，都必须在 `finally` 中执行：
+工作流要求 `sync@1`、`rules-sync@1`、`rules-review@1`、`knowledge-sync@2`。`BLOCKED_CAPABILITY_MISMATCH` 属环境阻塞，不得降级为手工拼接旧流程。
+
+## Run
 
 ```powershell
-python <skills-root>/scripts/harness_sync.py finalize --project . --run-id <run-id> --json
+npx hunter-harness sync --project <项目路径> --profile interactive --progress jsonl --json
 ```
 
-禁止重新使用固定 `sync-deploy-*` 目录；`--keep-temp` 仅供显式诊断。
-
-| Phase | 检查 → 动作 |
-|-------|-------------|
-| 0 | 读 SKILL + `reference.md` + protocols |
-| 1 | git log/diff 感知变更量 |
-| 2 | CodeGraph 索引是否需重建 |
-| 3 | `.harness/codebase/map/` 是否过期 → 报告建议 `/harness-codebase-map` |
-| 3.5 | `harness_knowledge.py sync`；可 `sync --update`；失败不得假装可用。**知识闭环主入口**是 `/harness-knowledge-ingest auto`（含 Agent judge），sync 不重复列人工知识待办 |
-| 3.6 | 单次运行 `harness_knowledge.py maintain --project . --drain --json`，有界推进全部 `.harness/knowledge/maintenance-outbox/{pending,failed}`；不得为每个条目重复启动 Python/重建索引（§8.2：archive close 只 enqueue，sync 异步推进 outbox 到 completed/pending-judge） |
-| 4 | CLAUDE.md 完整性/行数 → 超限 blocking user confirmation 瘦身 |
-| 5 | AGENTS.md 与各 Agent 指令入口一致；Claude Code 启用时验证 CLAUDE.md 引用 AGENTS.md，禁止反向循环引用 |
-| 5.5 | 运行 `npx hunter-harness rules-sync --json`：扫描各 Agent 用户规则并收敛到 `.harness/rules/`，刷新受管投影；读取结构化 review/test/archive 证据生成 `.harness/knowledge/rule-candidates.json`。表现差异按 Agent 适配器语义归一，真实分歧只报告不覆盖 |
-| 5.6 | 读取 `rule_review_pending`。用户主动交互式 sync 且存在新增候选时，运行 `npx hunter-harness rules-review --json`，由 Agent 将候选推荐为公共规则/项目知识/回归测试/CI 任务/Harness issue/暂缓/拒绝，展示证据与规则 diff 并询问用户；批准或修改后用带 candidate revision + target hash 的 decision JSON 执行 `rules-review --apply`。非交互 sync 只报告待评审数，不阻塞、不激活 |
-| 6 | `.harness/` 结构（init 规程 → `reference.md` 第 6 步）；已装 skill 新鲜度只经 `hunter-harness refresh --dry-run --json` 的 post-adaptation freshness 判断，禁止 raw build 字节比较 |
-| 7–9 | `项目规则（见 .harness/context-index.json）/`、构建配置、测试目录 — **只提示不自动修复** |
-
-状态判断表格、修复动作、输出示例 → `reference.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]]
-> 片段：p0-trust
-
-## 关键规则
+CLI 负责 Python runtime 解析、投影事务、knowledge、rules、map、指令图、配置来源、change 状态及 CodeGraph 证据汇总。禁止直接调用内部 Python 脚本，禁止使用固定 `HEAD~5`，禁止自动全量重建 CodeGraph。
 
-变更量先行 · CodeGraph 依赖编译产物 · map 与 Repomix 互斥 · CLAUDE 瘦身须用户确认 · 公共规则自动收敛但真实分歧不覆盖 · 历史证据先生成候选再由 Agent 推荐、用户批准 · Phase 7–9 只提示 · knowledge sync 失败记 WARN/FAIL
+长阶段的 heartbeat 写 stderr；stdout 只保留紧凑摘要。完整报告写入摘要中的 `reportPath`，并带 `reportSha256`。不得把完整 JSON 报告直接回显到对话。
 
-## Output Format
+## Interpret
 
-各组件状态表格 + 操作摘要 → `reference.md`
+- `OK`：所有可验证组件通过。
+- `WARN`：存在过期、冲突、待评审或 `UNKNOWN` 证据；按 `reportPath` 中的 `nextAction` 处理。
+- `FAIL`：组件执行失败；不得宣称同步完成。
+- `BLOCKED`：runtime、项目状态或能力契约阻塞；先修复阻塞条件。
+- `UNKNOWN`：证据不足，不等于成功，也不触发无界重建。
 
-## 渐进披露
+非交互或 CI 使用 `--profile general --progress jsonl --json`，不得等待规则候选确认。交互式运行若报告规则待评审，再按 `reference.md` 的显式入口处理。
 
-- **Read `reference.md`** — 10 步详细判定与修复
+## Safety
 
-## 交互白名单
+同步不得修改 `.harness/state` 或 `.harness/cache` 的内部文件；只通过 CLI 事务写入。配置真源与生成投影存在漂移时只报告，不静默覆盖真源。change 清理先 dry-run，仅对已验证归档收据执行安全清理。
 
-- CLAUDE.md/AGENTS.md 瘦身拆分确认
-- 新增、修改、弱化、删除公共规则前的候选处置与最终 diff 确认
+## P0 执行可信度规则
 
-非交互、定时或 CI sync 禁止等待输入；只输出 `rule_review_pending` 和后续 `rules-review` 命令。
+- 命令结果不得靠猜测；普通 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]]
+> 片段：p0-trust
 
 ## 执行日志
 
 `events.ndjson` 为唯一事实源（schema_version 3，兼容读取 v1/v2；`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止用 Write/Edit 直接维护**。直接修改的内容会在 `phase.end` 或 finalize 时被完整重建覆盖，属于数据丢失；需要保留的详情必须进入事件 `note`。结构 → [[../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 "<触发指令>"
+python <skills-root>/scripts/harness_events.py append --change-dir ".harness/changes/<change-name>" --phase <phase> --type phase.start --run-id <phase-run-id> --attempt <n> --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 边界保持最新。
 
-每次阶段结束必须写 `--status OK|WARN|FAIL|BLOCKED`；重试同一阶段时增加 `--attempt <n>`，不得覆盖或伪装成一次执行。跨工具继续执行时写 `--executor-tool <codex|claude-code|codebuddy|cursor>`，并在接棒事件写 `--handoff-from-tool` / `--handoff-reason`；也可由 `HUNTER_HARNESS_TOOL/AGENT/MODEL/RUN_ID` 环境变量统一注入。
-> 片段：logging · phase=`sync`；有未归档变更时写入其 change-dir events
+每个阶段的 `phase.start` 与对应 `phase.end` 必须复用同一 `--run-id` / `--attempt`；阶段结束必须写 `--status OK|WARN|FAIL|BLOCKED`。重试同一阶段时生成新的 run-id 并增加 `--attempt <n>`，不得覆盖或伪装成一次执行。跨工具继续执行时写 `--executor-tool <codex|claude-code|codebuddy|cursor>`，并在接棒事件写 `--handoff-from-tool` / `--handoff-reason`；也可由 `HUNTER_HARNESS_TOOL/AGENT/MODEL/RUN_ID` 环境变量统一注入。
+> 片段：logging · phase=`sync`