@hunter-harness/workflow-harness 0.4.8 → 0.4.9

package/harness/bundles/java/pi/harness-execute/SKILL.md

@@ -4,11 +4,11 @@ description: 执行阶段：按变更簇执行 TDD
   编码循环（RED→GREEN→REFACTOR→编译验证），随后完成单元/接口/数据兼容验证并输出测试报告。仅当用户显式调用
   /harness-execute 时使用；不得因用户提到编码/实现/测试就自动触发，也不得被其他阶段 skill 自动接续。
 ---
-<!-- generated by harness_deploy.py; core=a23ce7a4733cf3d7; overlay=java; agent=pi; do not edit -->
+<!-- generated by harness_deploy.py; core=410f64c18f167e3f; overlay=java; agent=pi; do not edit -->
 # harness-execute — 执行（编码 + 验证）
 
-> 2026-08 阶段合并：原 `run`（编码）与 `test`（验证）合并为单一 `execute` 阶段。
-> `/harness-run` 与 `/harness-test` 保留为别名入口，语义与本 skill 相同。
+> 2026-08 阶段合并：原 `run`（编码）与 `test`（验证）合并为单一 `execute` 阶段；
+> 0.4.9（workflow-harness）起 `/harness-run`、`/harness-test` 入口移除，统一由本 skill 承担。
 
 ## Purpose
 
@@ -16,7 +16,7 @@ description: 执行阶段：按变更簇执行 TDD
 
 ## When to Use
 
-仅当用户显式调用 `/harness-execute`（或别名 `/harness-run`、`/harness-test`）时执行；plan 完成后**不自动**进入本阶段。参数：`--subagent` 强制 Subagent-Driven；`--inline` 等同默认；`--fixback` 读最新 review fixback。**默认 Inline，不询问执行模式**。
+仅当用户显式调用 `/harness-execute` 时执行；plan 完成后**不自动**进入本阶段。参数：`--subagent` 强制 Subagent-Driven；`--inline` 等同默认；`--fixback` 读最新 review fixback。**默认 Inline，不询问执行模式**。
 
 **单阶段原则**：execute 关门后必须停止并交还用户，仅提示 `plannedPhases` 中的真实下一阶段；禁止自动开始其他阶段。
 
@@ -41,7 +41,7 @@ description: 执行阶段：按变更簇执行 TDD
 **状态与代码分离**：代码/编译/测试在 `worktreeRoot`；`stateDir`（logs/events/ledger/reports）写回 `.harness/changes/<change-name>/`。
 
 创建命令与 JSON 模板 → 各 skill `reference.md`（plan 写决策，run 创建/更新）。
-> 片段：worktree-gate · 创建命令 → `harness-run/reference.md`
+> 片段：worktree-gate · 创建命令 → `coding-reference.md`
 
 ## 统一读取协议
 
@@ -62,10 +62,10 @@ description: 执行阶段：按变更簇执行 TDD
 ## Workflow 概要
 
 0. 加载上下文：先 `harness_context.py prepare --project . --change <id> --phase execute --executor <tool> --json`（`--project` 必填），再 `harness_context.py begin --project . --change <id> --phase execute --executor <tool> --json` 校验交接，最后运行 **`harness_gate.py begin --phase execute --change <id>`**。旧名 `--phase run` / `--phase test` 仍被接受并归一为 execute。<br>**交接凭证不必手工补**：v2 计划的 `plan finalize` 不写 context 事务，`prepare` 会在检测到 committed 的 `meta/publication-journals/*.json` 时自动补录 `plan → execute` 凭证（凭证带 `bootstrapSource=plan_publication_journal` 留痕）。仍报 `HANDOFF_REQUIRED`/`LEGACY_BOOTSTRAP_REQUIRED` 说明**没有**这份发布证据——回到 plan 阶段确认发布是否真的完成，**不得**自己拼 `classify + configure-plan + close` 造凭证。<br>**Fixback** 不得拼装底层步骤，必须只调用一次 `harness_fixback.py launch-review --project . --change <id> --change-dir <change-dir> --executor <tool> --skills-root <skills-root> --product-identity <当前产品身份> --json`；返回 `FIXBACK_NOTHING_TO_APPLY` 时直接报告并停止。禁止手写 `events.ndjson` / `phase.end`。
-0.5. **测试基础设施探测**与**命令执行模式 preflight** → `harness-test/reference.md`「命令执行模式 preflight」；测试基线已由 gate begin 内部建立，不得再次执行 guard begin
-1. **变更簇 TDD** — `harness-run/protocols.md` `run-tdd-protocol`；批量 RED/GREEN；按需 `change-cluster-review-protocol`
+0.5. **测试基础设施探测**与**命令执行模式 preflight** → `testing-reference.md`「命令执行模式 preflight」；测试基线已由 gate begin 内部建立，不得再次执行 guard begin
+1. **变更簇 TDD** — `protocols.md` `run-tdd-protocol`；批量 RED/GREEN；按需 `change-cluster-review-protocol`
 2. 构建验证 + **仅**通过 `harness_ledger.py record` 写 ledger（禁止 Write/Edit `verification-ledger.json`）；profile 缺失或陈旧时先 `harness_preflight.py detect --project . --json`；`record --project . --profile-input <key>` 从同一 target 推导 scope、coverage、规范命令与输入闭包
-3. **验证执行**：单元测试可复用则跳过（`harness_ledger.py can-reuse`）；接口测试**强制批量执行器**一次跑完全部场景；数据兼容验证按场景表执行 → `harness-test/reference.md`
+3. **验证执行**：单元测试可复用则跳过（`harness_ledger.py can-reuse`）；接口测试**强制批量执行器**一次跑完全部场景；数据兼容验证按场景表执行 → `testing-reference.md`
 4. **场景覆盖检查**（场景表映射，禁止用用例数冒充场景数）
 5. **关门检查**（10 项）→ 只执行一次 `harness_gate.py close`；`--to-phase` 可省略——计划后继唯一（排除 fixback 自环）时自动派生并交接（输出含 `derivedToPhase`）。仅 fixback 回环时显式传 `--to-phase execute`。该命令内部关闭 test guard、写 `phase.end`、释放租约、写 handoff 并补传事件；不得再单独调用 test-guard/context close。失败时按结构化 `recoveryAction` 原样重试，已完成步骤幂等复用。
 
@@ -79,13 +79,13 @@ description: 执行阶段：按变更簇执行 TDD
 python <skills-root>/scripts/harness_test_runner.py exec --project . --timeout-seconds <预估上限> -- <构建命令及参数>
 ```
 
-资源档位是硬合同（`safe` 默认；`system`/`full` 需用户明确授权或 `--confirm-resource-intensive`）；Python `unittest` 必须逐模块隔离模式（`harness_test_runner.py unittest --profile safe --tests-dir <目录>`）。返回 `TEST_RUN_ALREADY_ACTIVE` 说明已有构建在跑：等待或查明持有者，不得绕开锁另起并行构建。完整约束 → `harness-test/checklist.md`「0.0-A 资源安全档位」。
+资源档位是硬合同（`safe` 默认；`system`/`full` 需用户明确授权或 `--confirm-resource-intensive`）；Python `unittest` 必须逐模块隔离模式（`harness_test_runner.py unittest --profile safe --tests-dir <目录>`），并发上限由 runner 注入的 `HARNESS_TEST_MAX_WORKERS` 决定，不得自行提升。返回 `TEST_RUN_ALREADY_ACTIVE` 说明已有构建在跑：等待或查明持有者，不得绕开锁另起并行构建。完整约束 → `testing-checklist.md`「0.0-A 资源安全档位」。
 
 **长阶段租约**：`gate begin` 的租约默认 TTL 3600 秒，execute 阶段常常跑得更久。租约过期不会中断执行，**也不再阻断收尾**：`gate close` 发现租约过期而 run-id 仍是本阶段的，会自动用原 run-id 重取并照常关门，只在返回体的 `leaseLapsed` 里记录。不需要定期续租；报 `LEASE_ABSENT`/`LEASE_INVALID` 时先确认 begin 真的跑过，**不要**重跑 `gate begin`。
 
 **关门重试是幂等续跑**（0.4.5 workflow 起）：租约释放是 close 的最后一个可失败步骤，handoff/monitor/清草稿任一失败时租约仍持有，原样重跑同一命令即可（已完成步骤由 closeTransaction journal 幂等跳过）。万一处于「phase.end 已写 + 租约已放 + 交接未完成」的历史中间态，重跑 close 会自动识别并补跑剩余步骤（`PHASE_CLOSE_RESUMED`）：未带 `--to-phase` 时从 plannedPhases 派生唯一后继，后继不唯一才报 `PHASE_HANDOFF_PENDING` 并列出候选。**都不需要手工 `harness_change.py claim`**——LEASE_ABSENT 只在 begin 从未跑过时才该出现。
 
-**接口测试执行器优先级**：接口测试执行器（默认首选）> PowerShell batch `.ps1` > Playwright MCP `browser_evaluate`（仅前两者不可用或用户明确选择）> curl + UTF-8 JSON body file（兜底）。执行器在 PowerShell 可用时**禁止**用 Playwright MCP 逐条执行。→ `harness-test/reference.md`「接口测试工具优先级」
+**接口测试执行器优先级**：接口测试执行器（默认首选）> PowerShell batch `.ps1` > Playwright MCP `browser_evaluate`（仅前两者不可用或用户明确选择）> curl + UTF-8 JSON body file（兜底）。执行器在 PowerShell 可用时**禁止**用 Playwright MCP 逐条执行。→ `testing-reference.md`「接口测试工具优先级」
 
 **陈旧测试安全修复**：只有当前生产代码、已批准计划或可验证历史能唯一确定新契约时，才允许仅修改测试并立即重跑，然后记录：
 
@@ -97,6 +97,28 @@ python <skills-root>/scripts/harness_test_guard.py record --project . --change-d
 
 **Foundation Gate**：若 `meta/implementation-checkpoints.json` 中 `foundation-gate` 为 pending，不得开始 plan 中任务 6+；由 `harness_gate.py` 硬阻断。
 
+### Java 构建验证（Maven）
+
+- 所有 `mvn`/`git` 经 `powershell.exe -NoProfile -Command`；命令读 `.harness/config/build-profile.json` 的 `commands`（v2，按 profile key resolve；**禁止 hardcode 模块名/端口**）
+- 增量编译：`commands.compile`（典型 `mvn compile -pl <module> -o -q`）
+- 变更簇 TDD：多测试类合并一次按 `commands.unitTest` resolve（典型 `mvn test -pl <module> -Dtest=A,B,C -o`）；每簇最多一次 RED + 一次 GREEN Maven
+- **轻量 run**：默认只 compile；全量 `mvn test` 仅当改了 mapper/sql/权限/controller/公共模块或用户要求 full-run-validation
+- **install -am**：仅 worktree 首建或上游模块文件变化时（见 ledger-protocol）；非每次 run 强制
+- worktree 中确认 `.mvn/maven.config` 等构建配置存在；缺失时从主目录复制
+### Java 测试环境补充
+
+- **preflight 0.1**：写入 `runtime/preflight.json` 的 `executorPath`/`mvnVersion` 等；Maven 可用性 `mvn -version` exit 0
+- **编译门禁**：测试前按 `build-profile.json` 的 `commands.compile`（v2，profile key resolve）；输出须含 `BUILD SUCCESS` 或 exit 0 证据
+- **条件 install**：worktree 首建或上游模块变更时按 profile 执行 `commands.install`（非每次强制 `-am`）
+- **单元测试**：可复用 ledger unitTest 则跳过；否则 `commands.unitTest`（典型 `mvn test -pl <module>`）；执行模块全量 `commands.unitTestFull` 成功 → 记 `unitTestFull`（scope=module，供 submit 复用）
+- **陈旧测试安全修复**：测试编译明确命中已移除/改名 API 且当前代码与批准计划唯一确定新契约时，只修测试并定向重跑，记录 `stale-test-repair`；有歧义则 `BLOCKED_PREEXISTING`，禁止 `.bak`/删除/禁用/exclude
+- **服务启动**：`build-profile.json` 的 `serviceStartTemplate`（典型 `spring-boot:run` + profile）；**禁止 hardcode 端口/模块路径**
+- **Maven 生命周期去重**：单元测试已独立通过后，服务启动命令可配置 `-Dmaven.test.skip=true` 避免重复测试编译；它仅优化启动，不是测试通过证据
+- **服务指纹输入**（Task 3 §5.1）：`serviceStart.inputFiles` 必须列出 module 源 glob（如 `["<module>/pom.xml", "<module>/src/main/**/*.java", "<module>/src/main/resources/**"]`）；`harness_service.py ensure` 取 CLI `--files` ∪ `inputFiles` 计算 `moduleInputsHash`。**空输入被拒绝**，不得生成可复用空指纹。源码/command/profile/overlayPath 任一变化即 restart
+- **runtime overlay**：`-Dspring.config.additional-location=file:<ascii-abs-path>/application-harness-execute.yml`；禁止默认 Edit tracked `application*.yml`
+- **known-good-test-profile**：profile 名、baseURL、healthUrl 写在 build-profile，非 skill 硬编码
+- **多租户请求头**：header 名/值来自 build-profile 的 `httpHeaders` 配置
+- **Service Gate**：`harness_service.py ensure` 返回 `needs-user-decision`（用户进程占端口）时**才** blocking user confirmation
 ## P0 执行可信度规则
 
 - 命令结果不得靠猜测；普通 Bash 被拒 → 立即改用等价 PowerShell 重试一次
@@ -111,7 +133,7 @@ python <skills-root>/scripts/harness_test_guard.py record --project . --change-d
 
 ## 关键规则（硬门禁速查）
 
-> 编码侧细则 → `harness-run/reference.md`、`harness-run/protocols.md`；验证侧细则 → `harness-test/reference.md`、`harness-test/checklist.md`、`harness-test/pitfalls.md`
+> 编码侧细则 → `coding-reference.md`、`protocols.md`；验证侧细则 → `testing-reference.md`、`testing-checklist.md`、`testing-pitfalls.md`
 
 | 域 | 要点 |
 |----|------|
@@ -126,17 +148,27 @@ python <skills-root>/scripts/harness_test_guard.py record --project . --change-d
 | **租约** | 阶段超 TTL 由 close 自动用原 run-id 重取，无需续租；`LEASE_ABSENT`/`LEASE_INVALID` 才需人工 `harness_change.py claim`，一律不重跑 begin |
 | **报告** | 区分"产品测试"与"工具维护"；API 维度 `OK`/`PARTIAL`/`BLOCKED`/`NOT_RUN`/`FAIL` 五态 |
 
+### Java TDD / 数据访问补充
+
+| 项 | 规则 |
+|----|------|
+| **低价值豁免** | ErrorCode 常量、VO/DTO 字段、注释、import 清理、格式化、SQL 脚本、配置模板、文档 — 不单独建测试类；禁止为单个错误码单独跑 Maven |
+| **Mapper / LambdaQueryWrapper / SQL** | 纯 Mock 返回值**不得**宣称 DB 验证通过 → 🟡 静态验证，交 harness-execute 真实 DB |
+| **行为性新分支** | 正则/条件/分支逻辑变更新增分支须 RED→GREEN；不属于低价值豁免 |
+| **ledger** | compile 必写；执行了 test 写 unitTest，否则 `NOT_RUN_BY_RUN`；diffHash 用 `harness_ledger.py diff-hash --change-dir`（见 reference） |
+| **陈旧 Java 测试** | `cannot find symbol`/mapper 方法改名/DTO 字段迁移只有在当前接口和批准计划唯一确定替代契约时才允许只改测试；修复后定向 `mvn test -Dtest=<class>`，再跑目标测试并记录 `stale-test-repair` |
+| **禁止规避** | 禁止把 `*Test.java` 改成 `.bak`、删除、`@Disabled`/`@Ignore`、Surefire exclude 或以 `-DskipTests` 充当 GREEN |
 ## Output Format
 
 变更文件表 + 构建/测试证据 + 场景覆盖摘要 + 最终状态（✅OK / 🟡WARN / ❌FAIL）。测试报告保存到 `.harness/changes/<change-name>/reports/test/test-report-YYYYMMDD-HHmm.md`。
 
 ## 渐进披露
 
-- **Read `harness-run/protocols.md`** — run-tdd + change-cluster-review
-- **Read `harness-run/reference.md`** — Step 0–5 细节、TDD/RED/ledger/迁移/安全矩阵
-- **Read `harness-test/checklist.md`** — 验证前各项强制检查、preflight、服务生命周期清单
-- **Read `harness-test/reference.md`** — API 测试执行方法、执行器模板、运行时配置叠加
-- **Read `harness-test/pitfalls.md`** — 测试踩坑规则
+- **Read `protocols.md`** — run-tdd + change-cluster-review
+- **Read `coding-reference.md`** — Step 0–5 细节、TDD/RED/ledger/迁移/安全矩阵
+- **Read `testing-checklist.md`** — 验证前各项强制检查、preflight、服务生命周期清单
+- **Read `testing-reference.md`** — API 测试执行方法、执行器模板、运行时配置叠加
+- **Read `testing-pitfalls.md`** — 测试踩坑规则
 
 ## 交互白名单
 

package/harness/bundles/java/pi/harness-execute/coding-checklist.md

@@ -0,0 +1,252 @@
+# harness-execute 执行检查清单
+
+> 编码执行时逐项勾选，确保不遗漏关键步骤。
+
+## 步骤 0：加载上下文
+
+### 步骤 0.0：Worktree 决策执行 ⚠️
+
+- [ ] 读取 `.harness/changes/<change-name>/worktree.json`
+- [ ] 如果文件缺失：🟡WARN，按 legacy 逻辑询问用户是否主目录执行或创建 worktree
+- [ ] `requested=false` → 主目录执行，记录原因
+- [ ] `requested=true` 且 worktree 存在 → 切换到 worktree 执行
+- [ ] `requested=true` 且 worktree 不存在 → 必须创建 worktree
+- [ ] worktree 创建命令必须使用 PowerShell：`git worktree add ...`
+- [ ] 创建后验证 `.worktrees/<change-name>/.git` 存在
+- [ ] 创建成功后更新 `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`
+- [ ] 读取并执行 `worktree.json`：如果 `requested=true` 必须创建/切换 worktree，创建失败则停止或询问用户改为主目录；禁止静默降级
+- [ ] **读取计划文件（主任务源）**：`.harness/changes/<change>/plans/<change>-plan.md` — 获取任务列表和依赖关系
+- [ ] **读取详细计划（补充参考）**：`.harness/changes/<change>/plans/<change>-implementation-detail.md`（如存在）
+- [ ] **读取设计文档**：`.harness/changes/<change>/plans/<change>-design.md`（v2）；不存在时回退 `spec/<change>-design.md`（legacy）— 获取核心设计决策和不变项
+- [ ] **读取测试场景表**：`.harness/changes/<change>/plans/<change>-test-scenarios.md` — 获取与当前任务相关的测试场景
+- [ ] **读取验证账本**：通过共享状态目录解析器定位 change，再读取 `evidence/verification-ledger.json`（兼容旧路径）— 复用已有 compile/unitTest 结果
+- [ ] **读取任务状态**：`.harness/changes/<change>/run-task-status.md`（如存在）— 恢复上次运行状态
+- [ ] 确认 `项目规则（见 .harness/context-index.json）/` 规则已加载
+- [ ] 检查构建配置完整性（worktree 中确认 `.mvn/maven.config`、`settings.xml` 等存在）
+- [ ] 读取 `.mvn/maven.config`，确认命令没有重复或覆盖项目已有的 `-s` / `-o` / 仓库设置
+- [ ] 离线依赖缺失时仅在项目规则允许联网的前提下执行至多一次非离线 `-nsu` 恢复；禁止离线/联网循环重试
+- [ ] 依赖模块预安装（worktree 中检查上游模块是否已 `mvn install`）
+- [ ] 代码探索优先用 `codegraph_explore`，仅在返回不完整时补充 Read
+- [ ] append `phase.start`（`note` 含测试基础设施 CHECKING 直至探测完成）
+
+### 步骤 0.1：执行模式
+
+- [ ] 默认 Inline；`--subagent` → Subagent-Driven；**不 blocking user confirmation 选模式**
+
+## 步骤 0.5：测试基础设施探测（⚠️ 必须先于任何 TDD 降级结论）
+
+> 探测完成前，执行日志中只能写 `**测试基础设施**: CHECKING`，不得写任何降级结论。
+
+- [ ] 探测 1：`src/test/java` 目录是否存在
+- [ ] 探测 2：`pom.xml` 是否包含 `spring-boot-starter-test` / `junit` / `mockito` 依赖
+- [ ] 探测 3：是否存在已有测试文件（`*Test.java` 或 `*Tests.java`）
+- [ ] 探测 4：目标模块测试基础设施是否可用（`mvn test-compile -pl <module> -o -q` 验证测试可编译，或测试枚举/秒级 smoke；**禁止完整模块测试**，spec §3.3）
+- [ ] 四项证据收集完毕 → 写结论：✅ 测试基础设施可用 / 🟡 测试基础设施部分可用 / ❌ 测试基础设施不可用
+- [ ] 如果 ❌ 不可用 → 记录 TDD 降级原因（必须引用具体证据，如"模块 X 无 src/test/java 目录"）
+
+## 步骤 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 豁免项（ErrorCode 常量、VO/DTO 字段、注释、import 清理、格式化、SQL 脚本、配置模板、文档）→ 标记为豁免，不单独建测试类
+- [ ] 确定每个变更簇的测试范围（哪些测试类合并执行）
+- [ ] 确认变更簇内 Mapper 查询条件是否需要用真实 DB 验证（非纯 Mock）
+
+### 进入变更簇 RED 前：执行 run-tdd-protocol
+
+- [ ] 在写第一行测试代码或生产代码之前执行 `run-tdd-protocol`（详见 `../protocols.md#协议一run-tdd-protocol`）
+- [ ] 测试基础设施可用 → 写真实 RED，记录：✅ 真实 RED 已建立
+- [ ] 测试基础设施不可用 → 记录降级原因，降级为静态 RED
+- [ ] RED 无效（测试搭建错误、private 访问限制、mock/stubbing 错误等）→ 必须先修测试，禁止进入 GREEN
+
+### RED（写测试 — 按变更簇批量执行）
+
+- [ ] 从场景表选取对应当前变更簇的测试用例
+- [ ] 写单元测试（JUnit 5 + Mockito + AssertJ），**优先通过 public API 验证**（非 private 方法）
+- [ ] **多个测试类合并到一次 Maven 命令执行**：`mvn test -pl <module> -Dtest=TestA,TestB,TestC -o`
+- [ ] **RED 有效性判定**（必须逐项确认）：
+  - [ ] 测试编译通过？（编译失败 → ❌无效 RED，先修测试）
+  - [ ] 未直接调用 private 方法？（private 访问限制 → ❌无效 RED）
+  - [ ] 失败断言指向目标业务行为？（mock/stubbing 错误 → ❌无效 RED）
+  - [ ] 失败原因与本次 bug/需求直接相关？（无关 → ❌无效 RED）
+  - [ ] 无 NoSuchBeanDefinitionException / NPE 来自测试搭建错误 / 不必要 stubbing？
+- [ ] 判定结果写入执行日志：`RED: ✅有效 / 🟡部分有效 / ❌无效`
+- [ ] 如果 ❌无效 RED → 必须先修测试，重新运行 RED，**禁止进入 GREEN**
+- [ ] 如果无测试基础设施 → 降级为静态逻辑验证（在执行日志和覆盖报告中标注覆盖关系，**不得在业务代码注释中标注**）
+
+### 低价值 TDD 豁免检查
+
+- [ ] ErrorCode 常量 → 不单独建测试类，compile 验证 + 被高层测试间接覆盖
+- [ ] VO/DTO 字段 → 不单独建测试类，被 service/API 测试间接覆盖
+- [ ] 注释 / import 清理 / 格式化 → compile 验证即可
+- [ ] SQL 迁移脚本 → 不做 TDD，生成审查清单，标记 NEEDS_DB_VALIDATION
+- [ ] 配置模板 / 文档 → 静态审查
+
+### Mapper 查询条件验证检查
+
+- [ ] 如果变更涉及 Mapper 查询条件 / LambdaQueryWrapper / SQL/XML → 不得用纯 Mock 宣称"自动化测试通过"
+- [ ] 纯 Mock Mapper 测试 → 标记为 🟡静态验证，交给 harness-execute 真实 DB 验证
+- [ ] 如果必须自动化 → 使用真实 mapper 或可检查 wrapper 条件的测试方式
+
+### GREEN（最简实现 — 按变更簇批量实现）
+
+- [ ] 写最少代码让变更簇测试全部通过
+- [ ] 遵循约束：Controller 只做参数校验和路由；Service 是唯一业务逻辑层；统一返回 `Result<T>`；集合返回空集合不返回 null；日志用 Slf4j；新增字段允许为空
+
+### REFACTOR（重构）
+
+- [ ] 在测试保护下重构代码结构
+- [ ] 清理过程性注释（如 `// 修复分页查询缺项目类型 Bug`），改写为稳定业务规则描述或删除
+- [ ] 重构后重新运行变更簇测试确认全部通过
+
+### Maven 批量验证（变更簇间）
+
+- [ ] 每个变更簇最多执行一次 RED Maven、一次 GREEN Maven — **不得每新增一个测试类就单独跑一次 Maven**
+- [ ] 多个测试类合并执行：`mvn test -pl <module> -Dtest=TestA,TestB,TestC -o`
+- [ ] 最终 compile 只执行一次（如前面已有 compile 成功证据，可复用 verification-ledger）
+- [ ] 使用 `-q` 模式时：报告中写 `exitCode=0`，不得写 `BUILD SUCCESS`（除非输出中真实出现）
+- [ ] 按需触发 `change-cluster-review-protocol`（详见 `../protocols.md#协议二change-cluster-review-protocol`）
+
+## 步骤 2：编译验证（默认轻量，Maven 批量执行）
+
+- [ ] `mvn compile -pl <module> -o`（始终执行，优先不用 `-q` 以获取 BUILD SUCCESS 证据）
+- [ ] 如果使用 `-q` quiet 模式 → 报告中写 `exitCode=0`，**不得写 BUILD SUCCESS**
+- [ ] 最终 compile 只执行一次，如果前面已有 compile 成功证据，可复用 verification-ledger
+- [ ] 判断是否需要全量 `mvn test`：改了公共模块/mapper/sql/权限认证/controller/VO，或用户要求 full-run-validation → 执行 `mvn test -pl <module> -o`；否则跳过全量 test
+- [ ] 编译失败 → 先分析错误类型（见 coding-reference.md 编译失败策略表）
+- [ ] **写入 verification-ledger.json**：`compile` 项必写（status/command/scope/evidence/时间戳/durationMs）；若执行了 mvn test 则 `unitTest` 项必写（testsRun/failures/errors/skipped/evidence）；未执行时标记 `NOT_RUN_BY_RUN`
+- [ ] 顶层写入 `diffHash` / `currentHead` / `baseCommit` / `module` / `profile`；`diffHash` **必须用三部分合并命令**（inline 见 reference 步骤 2c，与 ledger-protocol 五一致），**禁止仅用 `git diff` 未提交**；`currentHead`=`git rev-parse HEAD`
+- [ ] test/submit/package 阶段如果 diffHash 一致，可复用 run 的 compile/unitTest 结果
+
+## 步骤 3：场景覆盖检查
+
+- [ ] 单元测试场景逐条确认覆盖
+- [ ] 接口测试场景逐条确认代码逻辑覆盖
+- [ ] 数据兼容场景逐条确认（新字段 nullable、旧格式兼容）
+- [ ] 将覆盖结果展示给用户（✅/🟡/❌ 标注）
+- [ ] **覆盖状态必须正确分类**：✅ 自动化测试通过 / 🟡 静态检查未真实测试 / ❌ 未验证
+- [ ] 🟡 静态检查 **不得计入"已测试通过"**
+- [ ] 如果任一 P0 场景仅静态验证 → 最终结果必须是 🟡WARN
+- [ ] 最终摘要禁止写 `5✅ + 17🟡 = 22/22`，必须写 `自动化测试通过: 5 / 静态检查未真实验证: 17 / 未验证: 0`
+
+### 权限/组织过滤类变更：安全矩阵
+
+> 凡是修改了管理员/非管理员、orgCode、数据权限、越权异常等逻辑，必须强制生成。
+
+- [ ] 生成安全矩阵（模板见 coding-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
+
+### SQL 迁移任务审查清单
+
+> 如果变更涉及 SQL 脚本，必须生成此清单。
+
+- [ ] DROP INDEX 是否存在 IF EXISTS 或等效检查
+- [ ] 新索引名称
+- [ ] 新索引字段
+- [ ] 是否包含 deleted_time
+- [ ] 是否兼容已有数据
+- [ ] 是否包含历史数据修正
+- [ ] 是否需要备份
+- [ ] 是否需要回滚 SQL
+- [ ] SQL 脚本头部已标注"人工审查后手动执行，禁止自动运行"
+- [ ] SQL 任务状态标记为 🟡 NEEDS_DB_VALIDATION（不得标记为自动化测试通过）
+
+## 步骤 5：Worktree checkpoint commit（⚠️ 强制阻断）
+
+> 仅在 worktree 中执行时触发此步骤。在主目录执行时跳过（标记 ⏭️主目录跳过）。
+
+- [ ] 确认当前 cwd 在 `.worktrees/<change-name>/` 下
+- [ ] 生成变更摘要：`git diff --stat` + `git diff --stat --cached`
+- [ ] 构建 commit message：`wip(<scope>): <change-name> 编码完成 — N任务/M文件变更`
+- [ ] **⚠️ 强制阻断**：用 blocking user confirmation 展示变更列表 + commit message，等待用户确认
+- [ ] 用户确认 → 执行 `git add -A` + `git commit`（不用 --no-verify、--no-gpg-sign）
+- [ ] 用户拒绝 → 记录 `❌用户拒绝`，继续后续流程
+- [ ] 记录 checkpoint commit hash 到执行日志
+
+## 步骤 6：计划状态持久化
+
+- [ ] 每个任务状态更新到 plan 文件或新增 `run-task-status.md`
+- [ ] 状态区分：✅ DONE_AUTOMATED_TESTED / 🟡 DONE_STATIC_ONLY / 🟡 DONE_NEEDS_INTERFACE_TEST / 🟡 NEEDS_DB_VALIDATION / ❌ FAILED
+- [ ] 确保后续 harness-execute / harness-review 可读取待验证场景
+
+## 执行日志完成记录
+
+- [ ] 追加结束时间、耗时、结果、摘要、checkpoint commit 状态
+- [ ] **执行日志去重检查**：同一阶段不重复追加小节，如需补充应 Edit 原小节
+- [ ] 如果存在 🟡静态验证 P0 场景 → 下一步必须写 `必须先运行 /harness-execute`，不得并列"提交代码"
+- [ ] 如果存在 SQL 迁移/DB 验证未完成 → 最终不得输出纯 ✅OK
+
+### 最终状态分级
+
+- [ ] **✅OK**：所有计划内代码变更完成 + 关键 P0 场景已自动化测试通过 + compile 成功 + 无预存变更或已隔离 + 无非计划文件混入 + 无 P0 静态-only 场景
+- [ ] **🟡WARN**：存在 P0/P1 场景仅静态验证 / 存在预存变更 / SQL 需人工执行 / Mapper 只做静态验证 / 低价值 Mock 替代真实验证
+- [ ] **❌FAIL**：compile 失败 / 有效测试失败 / RED 无法建立 / 非计划文件被修改且无法解释 / git diff --check 失败
+- [ ] 如果存在 SQL 迁移/接口验证/DB 验证未完成 → 最终输出 🟡WARN，不得纯 ✅OK
+
+## events 记录（禁止手工 Edit execution-log）
+
+- [ ] 步骤 0 前 append `phase.start`
+- [ ] TDD/compile/test 写 `command` + `verification`；预存/worktree/降级写 `decision`/`issue`
+- [ ] `execution-log.md` 仅由 `harness_events.py` 渲染
+
+## PowerShell-only 命令检查
+
+- [ ] 所有 git 命令使用 `powershell.exe -NoProfile -Command "git ..."`
+- [ ] 所有 Maven 命令使用 `powershell.exe -NoProfile -Command "mvn ..."`
+- [ ] 所有文件系统命令使用 PowerShell
+- [ ] 如果出现 Bash hook error，记录违规命令并将当前阶段至少标为 🟡WARN
+
+## Ledger 必填字段检查
+
+- [ ] verification-ledger.json 包含 changeName/projectRoot/worktreeRoot/stateDir
+- [ ] 包含 currentHead/baseCommit/diffHash/module/profile
+- [ ] 包含 validations.compile 与 validations.unitTest
+- [ ] diffHash 必须用三部分合并命令（inline 见 reference 步骤 2c；commit 前 `baseCommit..HEAD` 部分为空也**必须保留**），`currentHead`=`git rev-parse HEAD`；禁止仅用 `git diff` 未提交——省略第一部分会导致 commit 后 diffHash 变化、run→test 复用链断裂
+- [ ] 缺字段时标记 `ledgerReusable=false`，后续阶段不得复用
+
+## 新筛选参数非法值行为检查
+
+- [ ] 如果新增筛选参数，设计中已明确非法值行为
+- [ ] 如果采用“忽略并不过滤”，必须有用户确认记录
+- [ ] 测试场景覆盖非法值