@hunter-harness/workflow-harness 0.3.1 → 0.4.1

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

@@ -0,0 +1,188 @@
+---
+name: harness-run
+description: 按变更簇执行 TDD 编码循环（RED→GREEN→REFACTOR→编译验证），逐变更簇实现计划中的任务。仅当用户显式调用
+  /harness-run 时使用；不得因用户提到编码/实现就自动触发，也不得被其他阶段 skill 自动接续。
+---
+<!-- generated by harness_deploy.py; core=ec59ac2389d9dce9; overlay=none; agent=pi; do not edit -->
+# harness-run — 需求编码
+
+> **2026-08 阶段合并**：原 `run`（编码）与 `test`（验证）合并为单一 `execute` 阶段，
+> 统一入口为 **`/harness-execute`**（`harness/harness-execute/SKILL.md`）。本 skill 作为
+> 别名保留，frontmatter `name` 不变、内容照旧可用；门禁入参 `--phase run` 经
+> `LEGACY_PHASE_ALIASES` 归一为 execute。别名至少保留一个 minor 版本，退役时间见
+> `docs/harness-improvement-roadmap/`。下文出现的阶段名 `run`/`test` 均按别名解析。
+
+## Purpose
+
+基于 plan + test-scenarios，按**变更簇**执行 TDD（RED→GREEN→REFACTOR→构建验证），写入 verification-ledger。负责 worktree 创建/切换（见 worktree-gate）。
+
+## When to Use
+
+仅当用户显式调用 `/harness-run` 时执行；plan 完成后**不自动**进入本阶段。参数：`--subagent` 强制 Subagent-Driven；`--inline` 等同默认；`--fixback` 读最新 review fixback。**默认 Inline，不询问执行模式**。
+
+**单阶段原则**：run 关门后必须停止并交还用户，仅提示 `plannedPhases` 中的真实下一阶段；禁止自动开始其他阶段。
+
+## 前置条件
+
+- 设计文档（`plans/*-design.md` 优先，回退 `spec/*-design.md`）与 `plans/*-plan.md`（含 frontmatter）存在且已审批
+- 读 `meta/worktree.json`：`requested=true` 时 worktree 须存在或 run 负责创建
+
+## Worktree 门禁
+
+读取 `meta/worktree.json`（兼容旧路径 `worktree.json`）：
+
+| 条件 | 行为 |
+|------|------|
+| `requested=false` | 主目录执行 |
+| `requested=true` + path 存在 | 切换 worktree 执行 |
+| `requested=true` + path 不存在 | **必须创建**（run）或 **停止**（test/review/submit） |
+
+**严禁** `requested=true` 时静默回主目录。创建失败 → 停止或 blocking user confirmation 降级（须 🟡WARN + 用户确认）。
+
+**状态与代码分离**：代码/编译/测试在 `worktreeRoot`；`stateDir`（logs/events/ledger/reports）写回 `.harness/changes/<change-name>/`。
+
+创建命令与 JSON 模板 → 各 skill `reference.md`（plan 写决策，run 创建/更新）。
+> 片段：worktree-gate · 创建命令 → `reference.md`
+
+## 统一读取协议
+
+0. **脚本在 `<skills-root>/scripts/` 共享，不在每个 skill 子目录下** — 实际形态是 `.codebuddy/skills/scripts/harness_*.py`（`.claude`/`.cursor`/`.codex` 同理），**没有** `.../skills/harness-<phase>/scripts/`。plan、run/test、archive 三份执行日志里都先猜成后者、报 `No such file` 再靠 Search 找回来；照第一种写法直接用
+1. **`.harness/changes/<change-name>/` 是唯一真相源** — 所有输入从该目录读取，产物写入对应子目录
+2. **change-name 优先从 frontmatter 读取** — `plans/*-design.md`、`spec/*-design.md`、`plans/*-plan.md` 的 YAML `change-name`
+3. **frontmatter 缺失时兼容旧格式** — 从路径推断，标记 `🟡 legacy-plan`，不失败
+4. **design** — 设计真相源按序取第一个存在的：`plans/<change>-design.md`（v2 发布产物，哈希绑定）→ `spec/<change>-design.md`（legacy 手写）。两份**同时存在**时以 `plans/` 为准，并记 `🟡 WARN 设计文档双份`——v2 发布的那份才受完整性门禁保护，读手写的那份等于绕过校验
+5. **plan** — 任务真相源：`plans/<change>-plan.md`
+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>" --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
+
+## 执行模式
+
+默认 **Inline Execution**；仅 `--subagent` 切换 Subagent-Driven。
+
+## Workflow 概要
+
+0. 加载上下文：普通 Run 先 `harness_context.py prepare --project . --change <id> --phase run --executor <tool> --json`（`--project` 必填，漏了直接 argparse 报错），再 **`harness_context.py begin --project . --change <id> --phase run --executor <tool> --json`** 校验交接，最后运行 **`harness_gate.py begin --phase run --change <id>`**。<br>**交接凭证不必手工补**：v2 计划的 `plan finalize` 不写 context 事务，`prepare` 会在检测到 committed 的 `meta/publication-journals/*.json` 时自动补录 `plan → run` 凭证（凭证带 `bootstrapSource=plan_publication_journal` 留痕）。仍报 `HANDOFF_REQUIRED`/`LEGACY_BOOTSTRAP_REQUIRED` 说明**没有**这份发布证据——回到 plan 阶段确认发布是否真的完成，**不得**自己拼 `classify + configure-plan + close` 造凭证。`harness_gate.py` 会从当前已安装适配器自动识别 skills root；只有执行复制到别处的脚本时才显式传 `--skills-root`。`--fixback` 不得拼装这些底层步骤，必须只调用一次 `harness_fixback.py launch-review --project . --change <id> --change-dir <change-dir> --executor <tool> --skills-root <skills-root> --product-identity <当前产品身份> --json`：该命令会先筛选结构化评审项，再原子选择 Fixback 分支、确认上下文、取得 Run 门禁并创建已填充批次。返回 `FIXBACK_NOTHING_TO_APPLY` 时直接报告“本轮评审没有需要执行的代码修复”并停止；返回阻塞码时按 `recoveryAction` 停止，不搜索实现、不试探其他参数、不创建空批次。禁止手写 `events.ndjson` / `phase.end`。已连接平台时 begin 会 best-effort 补传事件，失败只告警。
+0.5. **测试基础设施探测**（先写 `CHECKING`，四项证据齐备后再结论）→ `reference.md` Step 0.5；测试基线已由上一步 gate begin 内部建立，不得再次执行 guard begin
+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`）；若本阶段创建/删除了清单、锁文件、源码根或改变技术栈，最后一次产品编辑后、写账本与关门前必须执行 `harness_preflight.py detect --project . --json` 刷新 build profile。`record --project . --profile-input <key>` 会对缺失/陈旧 profile 自动检测并从同一 target 推导 scope、coverage、规范命令和输入闭包；不得再手填另一套身份。detect 在嵌套/多组件仓库返回 `DETECTION_AMBIGUOUS` 时，响应里的 `profileTemplate` 就是可填骨架（已含 defaultsFingerprint、excludedRoots 默认集与 commands 条目形状），按 `hint` 填好写入 `.harness/config/build-profile.json` 即可，**不要去反读 `harness_profile.py` 源码凑结构**。`diff-hash --change-dir` 纳入 ignored tests → `reference.md` Step 2c
+3. **场景覆盖检查**（场景表映射，禁止用用例数冒充场景数）
+4. **关门检查**（10 项）→ 只执行一次 `harness_gate.py close`；`--to-phase` 必须取返回的 `nextPhases` 或 `plannedPhases` 中 run 的真实后继，禁止写死 test。该命令内部关闭 test guard、写 `phase.end`、释放租约、写 handoff 并补传事件；不得再单独调用 test-guard/context close。失败时按结构化 `recoveryAction` 原样重试，已完成步骤幂等复用。
+
+**阶段归属规则**：只用 `ownerPhase=run` 的任务和场景判定编码阶段结果。`ownerPhase=test` 的任务或场景按计划留给测试阶段属于正常移交，必须记录为“待测试阶段执行”，不得将编码阶段降级为 WARN；只有 run 自身负责的工作未完成、验证降级或证据异常时才使用 WARN。
+
+> 关门脚本与本规则一致：`harness_gate.py close --phase run` 的 C9 场景覆盖只要求 `ownerPhase` 为 `plan`/`run` 的必需场景有通过 receipt，`ownerPhase=test` 的场景出现在返回值的 `deferred` 里，不阻断 run。若 run 关门报 `REQUIRED_SCENARIO_NOT_EXECUTED` 且缺的是接口/端到端场景，那是 `meta/scenario-manifest.json` 里 `ownerPhase` 标错了（或老清单没声明），应当修清单——**不要**为了过门在 run 阶段起服务补跑本属 test 的验证。
+
+**Fixback**：入口只用 `launch-review`，后续问题处理通过 `resolve-issue/close` 驱动，不得把修复说明当成新的普通 Run。只读取返回的受影响问题和文件；验证仅失效与 `changedFiles` 相交的目标，其他 Test/Review 证据继续复用。RED 优先；`manual`、`workflow` 或未选用的建议不进入代码批次，使用中文记录处理结论。
+
+**构建/测试执行入口**：所有构建与测试命令（mvn / gradle / npm test / pytest 等）必须经 `harness_test_runner.py exec` 发起，**禁止**用 `powershell.exe -Command` 直接裸跑：
+
+```text
+python <skills-root>/scripts/harness_test_runner.py exec --project . --timeout-seconds <预估上限> -- <构建命令及参数>
+```
+
+该入口持有项目级互斥锁并托管进程树。裸跑构建在宿主工具超时后会被推入后台，多个后台构建同时写同一个 `target/`、`build/` 或 `node_modules/.cache`，表现为编译产物被清空、日志文件被占用、"增量编译抖动"——这些都不是代码缺陷，是并发自相残杀，排查成本极高。`--timeout-seconds` 按最慢的一次全量构建估（默认 300 秒偏短），宁可给足也不要让命令被中途掐断。
+
+返回 `TEST_RUN_ALREADY_ACTIVE`（退出码 3）说明**已有构建在跑**：等它结束或用 `lock-status` 查明持有者，**不得**改用裸跑绕开锁，也不得另起一个并行构建。确认持有进程已消失时才用 `lock-reap` 回收。
+
+**长阶段租约**：`gate begin` 的租约默认 TTL 3600 秒，而 run 阶段常常跑得更久。租约过期不会中断执行，**也不再阻断收尾**：`gate close` 发现租约过期而 run-id 仍是本阶段的，会自动用原 run-id 重取并照常关门，只在返回体的 `leaseLapsed` 里记下这个阶段跑过了 TTL。过期本身不说明所有权变了——抢占会重写租约文件把 run-id 换掉，那时报的是 `LEASE_OWNER_MISMATCH`。
+
+因此**不需要**为了长阶段定期续租。确实想让租约始终有效时，用本阶段原 run-id 刷新即可（同 run-id 重复 claim 即刷新，不会新开 attempt）：
+
+```text
+python <skills-root>/scripts/harness_change.py claim --change <id> --phase run --run-id <本阶段 run-id> --ttl-seconds 3600 --json
+```
+
+仍然报 `LEASE_ABSENT` 说明这个阶段**根本没有租约记录**（从未 begin，或已被释放），不是超时；先确认 `gate begin` 真的跑过。报 `LEASE_INVALID` 说明租约文件损坏，无法证明没被抢占，需人工确认无并发后再用上面的命令重取。两种情况都**不要**重跑 `gate begin`——那会新开 attempt 并丢失本轮 capsule。
+
+**执行器边界**：优先使用项目 build profile 和已有测试入口。禁止为了绕过 ESM、路径或参数问题临时生成 `.js`、`require` 脚本；需要文件式 runner 时使用项目已有入口，确需新增时遵循项目模块类型（例如 ESM 使用 `.mjs`）。runner 包装说明写入 `runnerCommand` 元数据，不得拼进账本的规范 `command`。
+
+**Foundation Gate**：若 `meta/implementation-checkpoints.json` 中 `foundation-gate` 为 pending，不得开始 plan 中任务 6+；由 `harness_gate.py` 硬阻断。
+
+## 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]]
+
+## 生成内容语言约定
+
+- sync/ingest 等生成的文档、规则、知识条目、架构说明一律**优先使用中文**撰写（标识符、命令、代码、API 字段名保持原文）
+- 面向平台展示的标题/摘要/正文默认中文；仅当用户明确要求或目标系统强制时才用英文
+> 片段：p0-trust
+
+## 关键规则（硬门禁速查）
+
+> 全文判定、示例、模板 → `reference.md`；ledger → `../protocols/ledger-protocol.md`
+
+| 域 | 要点 |
+|----|------|
+| **文档输入** | 只读 `.harness/changes/<cn>/`；禁止 `docs/superpowers/` |
+| **变更簇 TDD** | 一簇一次 RED/GREEN；低价值项豁免；新分支必须 RED |
+| **RED/GREEN** | RED 须有效；静态验证 ≠ 测试通过；greenfield 大重写豁免见 reference |
+| **Mapper/DB** | 纯 Mock 不得宣称 DB 验证通过；迁移脚本**永不自动执行** |
+| **探测/ledger** | 基础设施先探测；每次构建/测试经 `harness_ledger.py record`；禁止手写 ledger JSON；用 canonical `diff-hash --change-dir` |
+| **Gate/Guard** | 跨 Agent/阶段先用 `harness_context.py prepare/begin`；阶段门禁与上下文交接统一用 `harness_gate.py begin/close`；gate 内部负责 guard begin/close，模型只在需要记录测试来源或修复时调用 guard 的 `record/stage/mark` |
+| **预存变更** | 保留 → baseline 隔离；存在则最终 ≥ 🟡WARN |
+| **关门/状态** | 10 项关门检查；持久化 run-task-status；仅 run-owned P0 静态-only 导致 WARN；test-owned 待办正常移交 |
+| **Worktree** | `requested=true` 时代码只写 worktree |
+| **构建/测试** | 一律经 `harness_test_runner.py exec`；禁止裸跑 mvn/gradle/npm test；`TEST_RUN_ALREADY_ACTIVE` 表示已有构建在跑，等待而非另起 |
+| **租约** | 阶段超 TTL 由 close 自动用原 run-id 重取，无需续租；`LEASE_ABSENT`（无记录）/`LEASE_INVALID`（文件损坏）才需人工 `harness_change.py claim`，一律不重跑 begin |
+| **PowerShell** | 所有 git 经 `powershell.exe -NoProfile -Command` |
+
+### 陈旧测试安全修复与精确跟踪
+
+测试编译或 RED/GREEN 失败时，先区分当前实现缺陷、测试基础设施故障与陈旧测试。只有同时满足以下条件才允许自动修复陈旧测试：当前生产代码、已批准计划或可验证的历史变更能唯一确定新契约；修改范围仅限测试文件；修复后会立即重跑该测试及本变更目标测试。符合时以 `stale-test-repair` 记录：
+
+```text
+python <skills-root>/scripts/harness_test_guard.py record --project . --change-dir ".harness/changes/<change-name>" --files "<精确测试文件路径，逗号分隔>" --reason stale-test-repair --json
+```
+
+新建或正常更新测试分别使用 `tdd-created` / `test-updated`。若预期行为存在业务歧义，停止测试修复并记录 `BLOCKED_PREEXISTING`，不得猜测新断言。
+
+**禁止临时排除测试**：不得将测试改名为 `.bak`、移出测试目录、删除、添加 `@Disabled`/`@Ignore`、修改 Surefire/Gradle exclude 或跳过测试来制造绿色结果；也不得仅为满足陈旧测试而修改生产代码。`.gitignore` 中的测试只能通过 manifest 的精确路径闭环处理，禁止全局放宽 ignore。
+
+## Output Format
+
+变更文件表 + 构建/测试证据 + 场景覆盖摘要 + 最终状态（✅OK / 🟡WARN / ❌FAIL）。→ `reference.md`
+
+## 渐进披露
+
+- **Read `protocols.md`** — run-tdd + change-cluster-review
+- **Read `reference.md`** — Step 0–5 细节、TDD/RED/ledger/迁移/安全矩阵
+- **Read `checklist.md`** — 逐步勾选
+
+## 交互白名单
+
+1. **预存变更**：保留 / 暂存 / 终止
+2. **数据库迁移**：展示审查清单并确认（**永不自动执行**）
+3. **worktree 创建失败**：是否改主目录
+
+## 执行日志
+
+`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]]
+
+**`phase.start` 由 `harness_gate.py begin` 写，不要再手工追加一次。** 两条同 `run-id` 的
+`phase.start` 会让 `plan finalize` 以 `PHASE_START_DUPLICATE` 卡死，而且手工那次会先触发
+auto-seal、把正在开始的 attempt 封成 `RECOVERED`。要补触发指令说明就带 `--note` 跑 `gate begin`。
+（重复追加现已按 `(phase, run-id)` 判为幂等 no-op，但依赖它不如不写。）
+
+```powershell
+# 阶段开始：gate begin 负责，note 在这里给
+python <skills-root>/scripts/harness_gate.py begin --change-dir ".harness/changes/<change-name>" --phase <phase> --note "<触发指令>"
+# 阶段中的其他事件才用 append
+python <skills-root>/scripts/harness_events.py append --change-dir ".harness/changes/<change-name>" --phase <phase> --type <command|issue|verification> --run-id <phase-run-id> --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 边界保持最新。
+
+每个阶段的 `phase.start` 与对应 `phase.end` 必须复用同一 `--run-id` / `--attempt`；阶段结束必须写 `--status OK|WARN|FAIL|BLOCKED`。重试同一阶段时生成新的 run-id 并增加 `--attempt <n>`，不得覆盖或伪装成一次执行。**`attempt` 按 phase 全局递增，不是按 run-id**：一个 run-id 只绑定一个 attempt，重试必须「新 run-id ＋ 下一个 attempt」两者同时换，只换其一会撞 `EVENT_ATTEMPT_CONFLICT` 或 `PHASE_ALREADY_CLOSED`。已发布 plan 的修订通过重跑 `plan evidence-pack` + `plan finalize` 分配新 attempt（`harness_plan_finalize.py republish` 已于 0.3.0 移除）。
+
+阶段跑得久（plan/run 常见）时用 `harness_context.py renew --project . --change <cn> --executor <tool>` 续租；租约到期本身不再阻断 `close`（同一 owner 的过期租约不构成冲突，收据里记 `leaseLapsed`），但续租能让 `view` 的状态如实反映在跑。跨工具继续执行时写 `--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/pi/harness-run/checklist.md

@@ -0,0 +1,279 @@
+---
+description: harness-run 的执行检查清单。仅在编码执行时读取。
+---
+
+# harness-run 执行检查清单
+
+> 编码执行时逐项勾选，确保不遗漏关键步骤。
+
+## 步骤 0：加载上下文
+
+### 步骤 0.0：Worktree 决策执行 ⚠️
+
+- [ ] 运行 `harness_runtime.py doctor` 并读取 `meta/runtime.json`；后续使用绝对 executable 与 argv 数组
+- [ ] 读取 `.harness/changes/<change-name>/meta/worktree.json`（旧路径 `worktree.json` 兼容）
+- [ ] 如果文件缺失：🟡WARN，按 legacy 逻辑询问用户是否主目录执行或创建 worktree
+- [ ] `requested=false` → 主目录执行，记录原因
+- [ ] `requested=true` 且 worktree 存在 → 切换到 worktree 执行
+- [ ] `requested=true` 且 worktree 不存在 → 必须创建 worktree
+- [ ] worktree 创建命令必须使用 PowerShell：`git worktree add ...`
+- [ ] 创建后验证 `.worktrees/<change-name>/.git` 存在
+- [ ] 创建成功后更新 `meta/worktree.json` 的 `created=true/createdAt/createdBy`
+- [ ] 创建失败 → 停止，或 blocking user confirmation 询问是否改为主目录执行
+- [ ] 禁止 `requested=true && worktree 不存在` 时直接主目录执行
+- [ ] 记录 `projectRoot / worktreeRoot / stateDir`
+
+
+
+- [ ] 确定变更名：Glob 搜索 `.harness/changes/*/plans/*-plan.md`（排除 `.harness/archive/*/`），提取 `change-name`
+- [ ] 读取并执行 `meta/worktree.json`：如果 `requested=true` 必须创建/切换 worktree，创建失败则停止或询问用户改为主目录；禁止静默降级
+- [ ] **读取计划文件（主任务源）**：`.harness/changes/<change>/plans/<change>-plan.md` — 获取任务列表和依赖关系
+- [ ] **读取详细计划（补充参考）**：`.harness/changes/<change>/plans/<change>-implementation-detail.md`（新版必需；legacy 缺失时 🟡WARN）
+- [ ] **读取设计文档**：`.harness/changes/<change>/plans/<change>-design.md`（v2）；不存在时回退 `spec/<change>-design.md`（legacy）— 获取核心设计决策和不变项
+- [ ] **读取测试场景表**：`.harness/changes/<change>/plans/<change>-test-scenarios.md` — 获取与当前任务相关的测试场景
+- [ ] **读取验证账本**：通过 context 返回的 `executionRoot` 读取 `evidence/verification-ledger.json`（如存在）— 复用已有 compile/unitTest 结果
+- [ ] **读取任务状态**：`.harness/changes/<change>/evidence/run-task-status.md`（如存在）— 恢复上次运行状态
+- [ ] **读取 review fixback**：用户传入 `--fixback` 或要求修复 review 问题时，读取最新 `.harness/changes/<change>/reports/review/fixback-*.md`
+- [ ] 确认未将 `docs/superpowers/` 作为执行输入（旧草稿最多作为人工线索）
+- [ ] 确认 `项目规则（见 .harness/context-index.json）/` 规则已加载
+- [ ] 检查构建配置完整性（worktree 中确认构建配置文件存在，如 Java 的 `.mvn/maven.config`、`settings.xml`，前端的 `package.json`/lockfile 等）
+- [ ] 依赖模块预安装（worktree 中检查上游依赖是否已安装，如 Java 的 `mvn install`、前端的 `npm install`/lockfile 等）
+- [ ] 代码探索优先用 `codegraph_explore`，仅在返回不完整时补充 Read
+- [ ] `harness_context.py prepare/begin` 均带 `--project .` 与 `--change <id>`（缺 `--project` 会被 argparse 直接拒）
+- [ ] 交接凭证缺失时**不自行拼造**：v2 计划由 `prepare` 依据 committed 发布 journal 自动补录；仍报 `HANDOFF_REQUIRED`/`LEGACY_BOOTSTRAP_REQUIRED` 即代表发布证据不存在，回 plan 阶段查，不得用 `classify + configure-plan + close` 现编凭证
+- [ ] `harness_gate.py begin --phase run` 已返回 Plan handoff 校验通过并自动 append `phase.start`；不得手工写事件绕过
+- [ ] 门禁报 `SCENARIO_MANIFEST_V2_UNSUPPORTED` 时按 `missingFields` 回规划阶段补齐场景字段后重新发布；**不得**手改 `meta/scenario-manifest.json`（派生产物，手改必致哈希漂移）
+
+### 步骤 0.1：执行模式（无询问）
+
+- [ ] 统计任务数量和涉及模块数
+- [ ] 如果处于 `--fixback` 模式，将 RED/YELLOW fixback 条目映射为本轮变更簇，并记录 `fixback: applied`
+- [ ] 默认 Inline Execution；`--subagent` / `--inline` 参数覆盖
+- [ ] **禁止**因任务数/模块数 blocking user confirmation 选择执行模式
+
+## 步骤 0.5：测试基础设施探测（⚠️ 必须先于任何 TDD 降级结论）
+
+> 探测完成前，执行日志中只能写 `**测试基础设施**: CHECKING`，不得写任何降级结论。
+
+- [ ] 探测 1：测试目录是否存在（如 Java 的 `src/test/java`）
+- [ ] 探测 2：构建配置/依赖清单是否包含测试依赖（如 Java 的 `pom.xml` 含 `spring-boot-starter-test`/`junit`/`mockito`）
+- [ ] 探测 3：是否存在已有测试文件（按技术栈测试命名约定，如 Java 的 `*Test.java`/`*Tests.java`）
+- [ ] 探测 4：目标模块测试基础设施是否可用（按技术栈，如 Java 的 `mvn test-compile -pl <module> -o -q` 验证测试可编译，或测试枚举/秒级 smoke；**禁止完整模块测试**，spec §3.3）
+- [ ] 四项证据收集完毕 → 写结论：✅ 测试基础设施可用 / 🟡 测试基础设施部分可用 / ❌ 测试基础设施不可用
+- [ ] 如果 ❌ 不可用 → 记录 TDD 降级原因（必须引用具体证据，如"模块 X 无测试目录（如 Java 的 src/test/java）"）
+- [ ] 若探测失败来自具体陈旧测试，先执行「陈旧测试安全修复」判定：当前代码/批准计划/可验证历史唯一确定契约 + 仅改测试 + 立即重跑；满足才修复，否则记录 `BLOCKED_PREEXISTING`
+- [ ] 修复/新增/更新的精确测试路径已用 `harness_test_guard.py record` 记录为 `stale-test-repair` / `tdd-created` / `test-updated`
+- [ ] **禁止临时排除测试**：未使用 `.bak`/改名/移目录/删除/禁用注解/build exclude/skip-tests 绕过失败
+
+## 步骤 0.2：预存变更检测与隔离
+
+> 如果 run 开始前检测到已有未提交变更，必须执行此步骤。
+
+- [ ] 检查 git status 是否有 run 前的预存变更
+- [ ] 如果有预存变更 → 使用 blocking user confirmation 询问用户处理方式（保留/暂存/终止）
+- [ ] 用户选择保留 → 创建 `.harness/changes/<change>/pre-existing-files.json`（文件列表 + diff hash + 用户选择）
+- [ ] 用户选择保留 → 创建 `.harness/changes/<change>/pre-existing-diff.patch`（完整 diff 备份）
+- [ ] 在执行日志中记录预存变更检测结果和用户选择
+
+## 变更簇 TDD 循环
+
+> 默认按变更簇执行 TDD，不按每个小任务单独 RED/GREEN。
+
+### 步骤 1a：划分变更簇
+
+- [ ] 读取 plan.md 任务列表，按业务行为分组为变更簇
+- [ ] 检查是否有低价值 TDD 豁免项（错误码常量、数据契约字段 VO/DTO、注释、代码整理如 import 清理、格式化、数据库迁移脚本、配置模板、文档）→ 标记为豁免，不单独建测试类
+- [ ] 确定每个变更簇的测试范围（哪些测试类合并执行）
+- [ ] 确认变更簇内数据访问层查询条件是否需要用真实 DB 验证（非纯 Mock）
+
+### 进入变更簇 RED 前：执行 run-tdd-protocol
+
+- [ ] 已读取 `harness-run/protocols.md`
+- [ ] 为当前变更簇选择 RED 类型：真实 RED / 静态 RED / 复用 RED
+- [ ] 真实 RED → 测试编译通过且失败断言指向目标行为
+- [ ] 静态 RED → 记录降级原因、静态验证场景、待 harness-test 验证场景
+- [ ] 复用 RED → 引用 test-scenarios 编号与前序证据，并在执行日志登记
+- [ ] 任何 RED 类型都已写入 events.ndjson（`decision` / `verification` / `issue`）
+
+### RED（写测试 — 按变更簇批量执行）
+
+- [ ] 从场景表选取对应当前变更簇的测试用例
+- [ ] 写单元测试（按技术栈测试框架，如 Java 的 JUnit 5 + Mockito + AssertJ），**优先通过 public API 验证**（非 private 方法）
+- [ ] **多个测试类合并到一次构建/测试命令执行**（按技术栈模块/用例定位参数，如 Java 的 `mvn test -pl <module> -Dtest=TestA,TestB,TestC -o`）
+- [ ] **RED 有效性判定**（必须逐项确认）：
+  - [ ] 测试编译通过？（编译失败 → ❌无效 RED，先修测试）
+  - [ ] 未直接调用 private 方法？（private 访问限制 → ❌无效 RED）
+  - [ ] 失败断言指向目标业务行为？（mock/stubbing 错误 → ❌无效 RED）
+  - [ ] 失败原因与本次 bug/需求直接相关？（无关 → ❌无效 RED）
+  - [ ] 无依赖注入上下文加载失败（如 Java 的 NoSuchBeanDefinitionException）/ NPE 来自测试搭建错误 / 不必要 stubbing？
+- [ ] 判定结果写入执行日志：`RED: ✅有效 / 🟡部分有效 / ❌无效`
+- [ ] 如果 ❌无效 RED → 必须先修测试，重新运行 RED，**禁止进入 GREEN**
+- [ ] 如果无测试基础设施 → 降级为静态逻辑验证（在执行日志和覆盖报告中标注覆盖关系，**不得在业务代码注释中标注**）
+
+### 低价值 TDD 豁免检查
+
+- [ ] 错误码常量 → 不单独建测试类，构建验证 + 被高层测试间接覆盖
+- [ ] 数据契约字段（VO/DTO）→ 不单独建测试类，被业务层/API 测试间接覆盖
+- [ ] 注释 / 代码整理（import 清理）/ 格式化 → 构建验证即可
+- [ ] 数据库迁移脚本 → 不做 TDD，生成审查清单，标记 NEEDS_DB_VALIDATION
+- [ ] 配置模板 / 文档 → 静态审查
+
+### 数据访问层查询条件验证检查
+
+- [ ] 如果变更涉及数据访问层查询逻辑（Java 的 Mapper/LambdaQueryWrapper/SQL/XML）→ 不得用纯 Mock 宣称"自动化测试通过"
+- [ ] 纯 Mock 数据访问层测试 → 标记为 🟡静态验证，交给 harness-test 真实 DB 验证
+- [ ] 如果必须自动化 → 使用真实数据访问层（非 mock）或可检查查询条件的测试方式
+
+### 编码前检查（远程客户端 / stub 同源错误）
+
+- [ ] 变更涉及 HTTP/RPC 客户端（Feign/RestTemplate/SDK 封装）时：取客户端注解路径（类级 + 方法级拼接），与服务提供方 controller 的 `@RequestMapping` + 方法级注解**完整拼接路径**逐一比对，在计划/执行记录中列出比对结果。只看方法级注解不算完成。
+- [ ] 修 stub/null 返回时，顺带核对同文件相邻声明（注解、常量、同类方法路径）是否同源错误，一并列出核对结果
+
+### GREEN（最简实现 — 按变更簇批量实现）
+
+- [ ] 写最少代码让变更簇测试全部通过
+- [ ] 遵循约束：接口层只做参数校验和路由；业务层是唯一业务逻辑层；统一返回结构（如 Java 的 `Result<T>`）；集合返回空集合不返回 null；日志用日志框架（如 Java 的 Slf4j）；新增字段允许为空
+
+### REFACTOR（重构）
+
+- [ ] 在测试保护下重构代码结构
+- [ ] 清理过程性注释（如 `// 修复分页查询缺项目类型 Bug`），改写为稳定业务规则描述或删除
+- [ ] 重构后重新运行变更簇测试确认全部通过
+
+### 批量构建验证（变更簇间）
+
+- [ ] 每个变更簇最多执行一次 RED 构建/测试、一次 GREEN 构建/测试 — **不得每新增一个测试类就单独跑一次构建/测试**
+- [ ] 多个测试类合并执行（按技术栈模块/用例定位参数，如 Java 的 `mvn test -pl <module> -Dtest=TestA,TestB,TestC -o`）
+- [ ] 最终构建只执行一次（如前面已有构建成功证据，可复用 verification-ledger）
+- [ ] 使用静默模式（如 Maven `-q`）时：报告中写 `exitCode=0`，不得写"构建成功"字样（如 Java 的 BUILD SUCCESS，除非输出中真实出现）
+- [ ] 按 `change-cluster-review-protocol` 判断是否触发变更簇审查
+- [ ] 高风险触发条件（数据迁移/权限/安全/并发/核心契约/缺真实测试/用户要求）已检查
+- [ ] 触发审查时，已记录方式：只读 reviewer / 主会话自审
+- [ ] 未触发审查时，已记录跳过理由（低风险/已有真实测试证据/后续 harness-review 覆盖）
+
+## 步骤 2：构建验证（默认轻量，批量执行）
+
+- [ ] 构建命令（按技术栈，如 Java 的 `mvn compile -pl <module> -o`）（始终执行，优先不用静默模式以获取构建成功证据）
+- [ ] 如果使用静默模式（如 Maven `-q`）→ 报告中写 `exitCode=0`，**不得写"构建成功"字样（如 Java 的 BUILD SUCCESS）**
+- [ ] 最终构建只执行一次，如果前面已有构建成功证据，可复用 verification-ledger
+- [ ] 判断是否需要全量测试：改了公共模块/数据访问层/数据库迁移/权限认证/接口层/数据契约，或用户要求 full-run-validation → 执行测试命令（按技术栈，如 Java 的 `mvn test -pl <module> -o`）；否则跳过全量测试
+- [ ] 构建失败 → 先分析错误类型（见 reference.md 构建失败策略表）
+- [ ] **经 `harness_ledger.py record` 写入 ledger**（禁止 Write/Edit `verification-ledger.json`）：`compile` 项必写；若执行了测试则 `unitTest` 项必写；未执行时标记 `NOT_RUN_BY_RUN`
+- [ ] 顶层写入 `diffHash` / `currentHead` / `module` / `profile`；`diffHash` 必须执行 `harness_ledger.py diff-hash --repo . --base <baseCommit> --change-dir ".harness/changes/<change-name>" --json`，纳入 test-tracking manifest 中的 ignored tests；`currentHead`=`git rev-parse HEAD`
+- [ ] test/submit/package 阶段如果 diffHash 一致，可复用 run 的 compile/unitTest 结果
+
+## 步骤 3：场景覆盖检查
+
+- [ ] 单元测试场景逐条确认覆盖
+- [ ] 接口测试场景逐条确认代码逻辑覆盖
+- [ ] 数据兼容场景逐条确认（新字段 nullable、旧格式兼容）
+- [ ] 将覆盖结果展示给用户（✅/🟡/❌/⏳ 标注）
+- [ ] **覆盖状态必须正确分类**：✅ 自动化测试通过 / 🟡 静态检查未真实测试 / ❌ 未验证 / ⏳ `ownerPhase=test` 按计划移交
+- [ ] 🟡 静态检查 **不得计入"已测试通过"**
+- [ ] 如果任一 `ownerPhase=run` 的 P0 场景仅静态验证 → 最终结果必须是 🟡WARN
+- [ ] `ownerPhase=test` 的任务或场景只记录为“待测试阶段执行”，不得将编码阶段降级为 WARN
+- [ ] 最终摘要禁止写 `5✅ + 17🟡 = 22/22`，必须写 `自动化测试通过: 5 / 静态检查未真实验证: 17 / 未验证: 0`
+- [ ] **禁止用测试用例数（如 178 tests）冒充场景数**——计数对象是 test-scenarios.md 的场景编号
+- [ ] 四类计数自洽：run-owned 🟡/❌ 计入未验证；test-owned ⏳ 单列移交数量
+- [ ] 输出为场景表映射（UT/API/COM/INT 逐条或范围 ✅/🟡/❌），不得只给聚合测试数
+
+### 权限/组织过滤类变更：安全矩阵
+
+> 凡是修改了管理员/非管理员、orgCode、数据权限、越权异常等逻辑，必须强制生成。
+
+- [ ] 生成安全矩阵（模板见 reference.md）
+- [ ] 覆盖：超级管理员 token 空/非空 × 请求 orgCode 空/指定 × projectType 有/无
+- [ ] 覆盖：非管理员 token 本组织/空 × 请求 orgCode 本组织/其他组织/空 × projectType 有/无
+- [ ] 如果任一权限边界预期不明确 → 不允许标记 ✅OK
+
+## 步骤 4：关门检查（⚠️ 结束前强制执行）
+
+- [ ] `git status --porcelain`
+- [ ] `git diff --stat`
+- [ ] `git diff --check`（如果失败 → 最终结果必须是 ❌FAIL）
+- [ ] 变更文件是否全部在计划范围内
+- [ ] 是否新增/修改了测试文件
+- [ ] 是否误改 .harness/ 以外的非计划文件（如有 → 至少 🟡WARN，要求用户确认）
+- [ ] 是否有 conflict marker：`<<<<<<<` / `=======` / `>>>>>>>`
+- [ ] 是否有临时 debug：`System.out.println` / `console.log` / `debugger` / 临时 TODO/FIXME
+- [ ] 是否有敏感信息：`password` / `token` / `secret` / `accessKey` / 私有 IP/URL
+- [ ] 代码注释污染检查：生产代码中是否有 `// 修复 xxx Bug` / `// 本次变更` 等过程性注释（如有 → 必须在 REFACTOR 阶段清理）
+
+### 变更来源区分（预存变更隔离）
+
+- [ ] 区分本次 run 修改的文件 vs run 前预存变更的文件
+- [ ] 输出变更来源表（文件 / 来源 / 是否计划内 / 是否允许提交）
+- [ ] 如果存在预存变更 → 最终结果至少为 🟡WARN
+
+### 数据库迁移任务审查清单
+
+> 如果变更涉及数据库迁移脚本，必须生成此清单。
+
+- [ ] DROP INDEX 是否存在 IF EXISTS 或等效检查
+- [ ] 新索引名称
+- [ ] 新索引字段
+- [ ] 是否包含 deleted_time
+- [ ] 是否兼容已有数据
+- [ ] 是否包含历史数据修正
+- [ ] 是否需要备份
+- [ ] 是否需要回滚 SQL
+- [ ] 数据库迁移脚本头部已标注"人工审查后手动执行，禁止自动运行"
+- [ ] 数据库迁移任务状态标记为 🟡 NEEDS_DB_VALIDATION（不得标记为自动化测试通过）
+
+## 步骤 5：Worktree checkpoint commit（⚠️ 强制阻断）
+
+> 仅在 worktree 中执行时触发此步骤。在主目录执行时跳过（标记 ⏭️主目录跳过）。
+
+- [ ] 确认当前 cwd 在 `<adapter-worktree-root>/<change-name>/` 下，且 branch 使用 adapter 的 prefix
+- [ ] 生成变更摘要：`git diff --stat` + `git diff --stat --cached`
+- [ ] 构建 commit message：`wip(<scope>): <change-name> 编码完成 — N任务/M文件变更`
+- [ ] **⚠️ 强制阻断**：用 blocking user confirmation 展示变更列表 + commit message，等待用户确认
+- [ ] 用户确认 → 精确暂存业务文件；若存在 test-tracking manifest，先执行 `harness_test_guard.py stage --project . --change-dir ".harness/changes/<change-name>" --json`；禁止 `git add -A` 与目录级 force-add
+- [ ] `git diff --cached --name-only` 包含 manifest 的全部精确测试路径后再 `git commit`（不用 --no-verify、--no-gpg-sign）
+- [ ] 用户拒绝 → 记录 `❌用户拒绝`，继续后续流程
+- [ ] 记录 checkpoint commit hash 到执行日志
+
+## 步骤 6：计划状态持久化
+
+- [ ] 每个任务状态只更新到 `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 可读取待验证场景
+
+## 事件收尾记录
+
+- [ ] append `phase.end` **仅**通过 `harness_gate.py close`（禁止手工 Edit `events.ndjson` / 直接 append phase.end 绕过 close 校验）
+- [ ] 如果存在 run-owned 🟡静态验证 P0 场景 → 下一步必须写 `必须先运行 /harness-test`，不得并列"提交代码"
+- [ ] 如果 run 阶段负责的数据库迁移/DB 验证未完成 → 最终不得输出纯 ✅OK
+
+### 最终状态分级
+
+- [ ] **✅OK**：所有计划内代码变更完成 + run-owned 关键 P0 场景已自动化测试通过 + 构建成功 + 无预存变更或已隔离 + 无非计划文件混入 + 无 run-owned P0 静态-only 场景
+- [ ] **🟡WARN**：存在 run-owned P0/P1 场景仅静态验证 / 存在预存变更 / run-owned 数据库验证未完成 / 低价值 Mock 替代真实验证
+- [ ] **❌FAIL**：构建失败 / 有效测试失败 / RED 无法建立 / 非计划文件被修改且无法解释 / git diff --check 失败
+- [ ] `ownerPhase=test` 的待办属于正常阶段移交；不得因为后续阶段尚未执行而把已完成的 run 标成 WARN
+## PowerShell-only 命令检查
+
+- [ ] 所有 git 命令使用 `powershell.exe -NoProfile -Command "git ..."`
+- [ ] 所有构建/测试命令使用 `powershell.exe -NoProfile -Command "<构建/测试命令> ..."`
+- [ ] 所有文件系统命令使用 PowerShell
+- [ ] 如果出现 Bash hook error，记录违规命令并将当前阶段至少标为 🟡WARN
+
+## Ledger 必填字段检查
+
+- [ ] verification-ledger.json 包含 changeName/projectRoot/worktreeRoot/stateDir
+- [ ] 包含 currentHead/baseCommit/diffHash/module/profile
+- [ ] 包含 validations.compile 与 validations.unitTest
+- [ ] 缺字段时标记 `ledgerReusable=false`，后续阶段不得复用
+- [ ] diffHash 必须由 `harness_ledger.py diff-hash --change-dir` 生成；manifest hash 漂移或路径越界时硬停止，禁止绕过后复用 ledger
+
+## 新筛选参数非法值行为检查
+
+- [ ] 如果新增筛选参数，设计中已明确非法值行为
+- [ ] 如果采用“忽略并不过滤”，必须有用户确认记录
+- [ ] 测试场景覆盖非法值
+
+
+## Wave-2 — Migration head（H-7）
+
+- [ ] 若变更触及 alembic/versions 或项目约定 migration 路径：列出 config / CI / env / manifest 联动文件
+- [ ] 消费项目存在 .harness/config/migration-head.json 时，跑 harness_migration_head.py check --project . --json

package/harness/bundles/general/pi/harness-run/protocols.md

@@ -0,0 +1,141 @@
+---
+description: harness-run 的原生执行协议。内化 TDD 与变更簇审查能力，但不运行时依赖 Superpowers。
+---
+
+# harness-run 原生执行协议
+
+本文件定义 `/harness-run` 的内置执行协议。它吸收 test-driven-development 与 subagent-driven-development 的有效做法，但正式流程不调用 Superpowers，也不把外部 skill 是否存在作为执行条件。
+
+## 协议一：run-tdd-protocol
+
+用于每个变更簇。目标是保留 RED→GREEN→REFACTOR 的行为约束，同时允许 harness 按证据分级处理缺失测试基础设施的现实情况。
+
+### RED 三态
+
+| RED 类型 | 何时使用 | 证据要求 |
+|----------|----------|----------|
+| 真实 RED | 测试基础设施可用，能写测试并运行失败 | 测试编译通过，失败断言指向目标行为 |
+| 静态 RED | 测试基础设施不可用或目标层无法真实验证 | 记录降级原因、静态验证场景、待 harness-test 验证场景 |
+| 复用 RED | 计划和测试场景已明确失败场景，且本轮只执行同一场景的实现 | 引用 test-scenarios 编号与前序证据，仍需在 run 日志登记 |
+
+RED 失败原因必须与目标 bug 或需求直接相关。无效 RED（测试搭建错误、private 访问限制、mock/stubbing 错误、依赖注入失败、NPE 来自测试夹具）不得进入 GREEN。
+
+### GREEN
+
+GREEN 只做让当前变更簇通过的最小实现。不得顺手处理无关重构、顺手扩范围、或把未确认业务决策写入代码。
+
+### REFACTOR
+
+REFACTOR 只允许不改变行为的整理。若重构改变行为，必须回到 RED/GREEN。重构后重新运行当前变更簇对应验证；若无法运行真实测试，必须更新静态验证说明。
+
+### 证据写入
+
+每个变更簇结束必须写入或更新：
+
+- `evidence/verification-ledger.json`：构建/测试命令、证据、diffHash、复用状态。
+- `evidence/run-task-status.md`：任务状态、对应场景、未验证项。
+- `events.ndjson`：关键 command / verification / issue / artifact 事件；RED 类型、GREEN 结果、REFACTOR 结果和验证证据放入事件 `note`。
+
+执行日志是上述事件在阶段边界生成的只读投影，不作为变更簇的直接输出目标。
+
+禁止把静态验证写成“测试通过”。静态 RED/GREEN 的最终状态至少是 🟡WARN，除非后续真实验证已完成。
+
+上述分级只评估 `ownerPhase=run` 的任务和场景。`ownerPhase=test` 的验证按计划留给测试阶段时，记录为“待测试阶段执行”，不得将编码阶段降级为 WARN；后续阶段未开始不是当前阶段的风险。
+
+## 协议二：change-cluster-review-protocol
+
+用于高风险变更簇后的轻量审查。它内化 subagent-driven-development 的“新上下文审查”价值，但不把每个变更簇的 subagent 审查设为默认流程。
+
+### 触发条件
+
+满足**全部**条件时启用：
+
+- 变更簇命中高风险（数据迁移、权限、安全、并发、幂等、核心契约变更、缺真实测试证据等，见原触发列表任一）
+- 当前宿主已显式提供隔离 reviewer 能力；需要固定 reviewer 时，单次 `check-agents` 返回 `executionMode=delegated`
+
+未满足时记录“跳过变更簇隔离审查：低风险 / 正常 inline / 后续 harness-review 覆盖”，不得视为降级或显示不可用告警。
+
+### 审查方式
+
+`executionMode=delegated` 时委派只读 `harness-reviewer` 审查当前变更簇 diff。**不 retry**；spawn 失败或无效返回 → 主会话 checklist 自审，记一次 `issue` 事件。
+
+审查范围只限当前变更簇：
+
+- 是否偏离 plan / implementation-detail。
+- 是否遗漏 test-scenarios 中的 P0/P1 场景。
+- 是否破坏 API、数据、权限、安全或兼容契约。
+- 是否引入非计划文件、临时 debug、敏感信息或过程性注释。
+
+### 输出
+
+审查结论写入当前 run 日志：
+
+```markdown
+### 变更簇审查 — <cluster>
+- 触发原因: <risk trigger>
+- 方式: reviewer / 主会话自审 / 跳过
+- 结论: OK / YELLOW / RED
+- 问题: <文件:行 + 建议>
+```
+
+RED 问题必须在当前 run 中处理或明确记录为未处理风险；YELLOW 问题可交给后续 `/harness-review`。
+
+## fixback 证据契约
+
+> `launch-review` 的返回体里带 `evidenceContract` 字段，内容与本节一致。这里写一份是因为
+> 光靠运行时返回，调用方往往已经动手改代码了才看到。
+
+### 命令链
+
+```text
+run-start（修复前，采 RED）→ 改代码 → run-start（修复后，采 GREEN）
+  → evidence-template ×2 → register-evidence ×2 → resolve-issue
+  → run-start（受影响链）→ evidence-template --kind verification
+  → evidence-template --kind review → close
+```
+
+### 别手写证据 JSON
+
+证据文件的 `provenance` 需要 `sessionId` / `commandHash` / `resultDigest` / `runReceiptPath`
+四个字段，全部能从 `session.json` 直接读出来。用模板生成，不要手抄：
+
+```text
+python <skills-root>/scripts/harness_fixback.py evidence-template \
+  --change-dir <change-dir> --kind red|green|verification|review \
+  --session <sessionId> --out <证据 JSON 路径> --json
+```
+
+输出即可直接喂给 `register-evidence`。撞 `FIXBACK_RUN_PROVENANCE_INVALID` 时，错误体会点名
+**哪个字段、期望什么、实际什么**——按它改，不要去读实现反推。
+
+### `--product-identity`
+
+产品身份指纹，把 RED/GREEN 绑定到同一产品状态。规范取值是**当前 git HEAD**。省略即自动推导，
+`launch-review` 会在返回体的 `resolvedProductIdentity` 里回显；`close --final-product-identity`
+**原样引用那个值**，不要另行推导——推导方式不同就会撞 `FIXBACK_GREEN_IDENTITY_MISMATCH`。
+
+### RED 必须在修复之前
+
+RED 证明问题真实存在，GREEN 证明修复真的生效。先改完再把改动回退来凑 RED，证明的只是回退后的
+状态，不是原始缺陷，中途还会留下脏工作树。
+
+### close 的两张收据与 review-findings.json
+
+`close` 要 `--affected-receipt`（`kind=verification`，受影响链的托管会话）和 `--review-receipt`
+（`kind=review`，指向 `reports/review/review-findings.json`）。
+
+review 收据的放行规则按 **disposition**，不按 severity：
+
+| disposition | 是否阻塞 | 说明 |
+|---|---|---|
+| `OPEN` / 未登记 | ❌ 阻塞 | 还没人处置，必须先给结论 |
+| `FIXED` / `NOT_APPLICABLE` | ✅ 放行 | 已闭环 |
+| `ACCEPTED_RISK` / `DEFERRED` | ✅ 放行 | 记入收据 `residualRisks` 留痕 |
+
+> ⚠️ **不要为了让 close 通过而清空或删改 `review-findings.json`。** 它是发现的真相源，写空等于
+> 抹掉整轮审查的审计轨迹。处置结论属于另一个 sidecar：
+>
+> ```text
+> python <skills-root>/scripts/harness_review.py write-dispositions \
+>   --change-dir <change-dir> --input <dispositions.json>
+> ```