@hunter-harness/workflow-harness 0.4.8 → 0.4.9

package/harness/bundles/java/claude-code/harness-execute/SKILL.md

@@ -23,11 +23,11 @@ disallowed-tools:
   - Bash(node *)
   - Bash(codegraph *)
 ---
-<!-- generated by harness_deploy.py; core=c74ed00e15a0ea44; overlay=java; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=8334c3150a633202; overlay=java; agent=claude-code; 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
 
@@ -35,7 +35,7 @@ disallowed-tools:
 
 ## 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` 中的真实下一阶段；禁止自动开始其他阶段。
 
@@ -60,7 +60,7 @@ disallowed-tools:
 **状态与代码分离**：代码/编译/测试在 `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`
 
 ## 统一读取协议
 
@@ -81,10 +81,10 @@ disallowed-tools:
 ## 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` 原样重试，已完成步骤幂等复用。
 
@@ -98,13 +98,13 @@ disallowed-tools:
 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`「接口测试工具优先级」
 
 **陈旧测试安全修复**：只有当前生产代码、已批准计划或可验证历史能唯一确定新契约时，才允许仅修改测试并立即重跑，然后记录：
 
@@ -116,6 +116,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 重试一次
@@ -130,7 +152,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`
 
 | 域 | 要点 |
 |----|------|
@@ -145,17 +167,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/claude-code/{harness-run/checklist.md → harness-execute/coding-checklist.md}

@@ -1,4 +1,4 @@
-# harness-run 执行检查清单
+# harness-execute 执行检查清单
 
 > 编码执行时逐项勾选，确保不遗漏关键步骤。
 
@@ -105,7 +105,7 @@
 ### Mapper 查询条件验证检查
 
 - [ ] 如果变更涉及 Mapper 查询条件 / LambdaQueryWrapper / SQL/XML → 不得用纯 Mock 宣称"自动化测试通过"
-- [ ] 纯 Mock Mapper 测试 → 标记为 🟡静态验证，交给 harness-test 真实 DB 验证
+- [ ] 纯 Mock Mapper 测试 → 标记为 🟡静态验证，交给 harness-execute 真实 DB 验证
 - [ ] 如果必须自动化 → 使用真实 mapper 或可检查 wrapper 条件的测试方式
 
 ### GREEN（最简实现 — 按变更簇批量实现）
@@ -133,7 +133,7 @@
 - [ ] 如果使用 `-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
-- [ ] 编译失败 → 先分析错误类型（见 reference.md 编译失败策略表）
+- [ ] 编译失败 → 先分析错误类型（见 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 结果
@@ -153,7 +153,7 @@
 
 > 凡是修改了管理员/非管理员、orgCode、数据权限、越权异常等逻辑，必须强制生成。
 
-- [ ] 生成安全矩阵（模板见 reference.md）
+- [ ] 生成安全矩阵（模板见 coding-reference.md）
 - [ ] 覆盖：超级管理员 token 空/非空 × 请求 orgCode 空/指定 × projectType 有/无
 - [ ] 覆盖：非管理员 token 本组织/空 × 请求 orgCode 本组织/其他组织/空 × projectType 有/无
 - [ ] 如果任一权限边界预期不明确 → 不允许标记 ✅OK
@@ -208,13 +208,13 @@
 
 - [ ] 每个任务状态更新到 plan 文件或新增 `run-task-status.md`
 - [ ] 状态区分：✅ DONE_AUTOMATED_TESTED / 🟡 DONE_STATIC_ONLY / 🟡 DONE_NEEDS_INTERFACE_TEST / 🟡 NEEDS_DB_VALIDATION / ❌ FAILED
-- [ ] 确保后续 harness-test / harness-review 可读取待验证场景
+- [ ] 确保后续 harness-execute / harness-review 可读取待验证场景
 
 ## 执行日志完成记录
 
 - [ ] 追加结束时间、耗时、结果、摘要、checkpoint commit 状态
 - [ ] **执行日志去重检查**：同一阶段不重复追加小节，如需补充应 Edit 原小节
-- [ ] 如果存在 🟡静态验证 P0 场景 → 下一步必须写 `必须先运行 /harness-test`，不得并列"提交代码"
+- [ ] 如果存在 🟡静态验证 P0 场景 → 下一步必须写 `必须先运行 /harness-execute`，不得并列"提交代码"
 - [ ] 如果存在 SQL 迁移/DB 验证未完成 → 最终不得输出纯 ✅OK
 
 ### 最终状态分级

package/harness/bundles/java/claude-code/{harness-run/reference.md → harness-execute/coding-reference.md}

@@ -1,8 +1,8 @@
 ---
-description: harness-run 的编译失败策略表、TDD循环详细步骤和编码约束。仅在编码执行遇到编译问题或需要参考详细规则时读取。
+description: harness-execute 的编译失败策略表、TDD循环详细步骤和编码约束。仅在编码执行遇到编译问题或需要参考详细规则时读取。
 ---
 
-# harness-run 参考 — 详细规则
+# harness-execute 参考 — 详细规则
 
 ## 为什么走变更簇 TDD 而不是逐任务 TDD
 
@@ -30,7 +30,7 @@ description: harness-run 的编译失败策略表、TDD循环详细步骤和编
 
 ## Worktree 创建与切换详细规则
 
-`harness-run` 必须把 `worktree.json` 当作唯一决策源。
+`harness-execute` 必须把 `worktree.json` 当作唯一决策源。
 
 ### 状态机
 
@@ -163,7 +163,7 @@ powershell.exe -Command "mvn test -pl <module> -o -q"
 从场景表选取对应当前变更簇的测试用例：
 
 - **单元测试**（优先）：JUnit 5 + Mockito，命名 `{方法名}_{场景}_{预期结果}()`，用 AssertJ `assertThat`
-- **接口测试**（必要时代码逻辑已覆盖即可，实际 HTTP 调用留给 `harness-test`）
+- **接口测试**（必要时代码逻辑已覆盖即可，实际 HTTP 调用留给 `harness-execute`）
 - **多个测试类合并到一次 Maven 命令执行**：`mvn test -pl <module> -Dtest=TestA,TestB,TestC -o`
 
 ### RED 有效性判定（⚠️ 必须逐项确认）
@@ -226,7 +226,7 @@ RED 不是"测试失败"即可通过，必须确认失败原因与目标 bug/需
 | 注释 | compile 验证 | 不影响运行时行为 |
 | import 清理 | compile 验证 | 不影响运行时行为 |
 | 格式化 | compile 验证 | 不影响运行时行为 |
-| SQL 迁移脚本 | 静态审查 + harness-test DB 验证 | 不做 TDD，生成审查清单 |
+| SQL 迁移脚本 | 静态审查 + harness-execute DB 验证 | 不做 TDD，生成审查清单 |
 | 配置模板 | 静态审查 | 部署时生效 |
 | 文档文件 | 静态审查 | 不涉及代码 |
 
@@ -264,7 +264,7 @@ Mapper 查询条件、LambdaQueryWrapper、SQL/XML 查询逻辑，**不得通过
 | 是否可通过 mockStatic 构造？ | 是/否 |
 | 是否可写轻量集成测试？ | 是/否 |
 | 跳过自动化测试的具体阻塞点 | ... |
-| 后续必须由哪个阶段验证 | harness-test / 手工接口 / 部署验证 |
+| 后续必须由哪个阶段验证 | harness-execute / 手工接口 / 部署验证 |
 
 如果只是"配置麻烦"或"mock 复杂"，不得直接跳过。对 DTO 字段、分页返回、权限过滤、组织过滤等用户可见行为，必须优先写公共行为测试。
 
@@ -285,9 +285,9 @@ Mapper 查询条件、LambdaQueryWrapper、SQL/XML 查询逻辑，**不得通过
 5. 输出必须明确写成：
    - "🟡 静态逻辑验证通过"
    - "未执行真实单元测试"
-   - "待测试基础设施补齐后运行 harness-test"
+   - "待测试基础设施补齐后运行 harness-execute"
 6. **禁止写成**："测试全部通过"、"测试通过 N/N"、"覆盖率 100%"等含暗示真实测试已运行的表述
-7. 提示用户在测试基础设施就绪后补充运行 `harness-test`
+7. 提示用户在测试基础设施就绪后补充运行 `harness-execute`
 
 ## GREEN：最简实现
 
@@ -340,7 +340,7 @@ GREEN 阶段完成后，对照以下反模式清单自检：
 
 ## Maven 批量验证策略
 
-harness-run 必须减少 Maven 启动次数。
+harness-execute 必须减少 Maven 启动次数。
 
 **默认策略**：
 1. 每个变更簇最多执行一次 RED Maven、一次 GREEN Maven
@@ -373,7 +373,7 @@ TestA+TestB+TestC RED → 实现相关代码 → TestA+TestB+TestC GREEN → 最
 
 ## 预存变更隔离
 
-如果 harness-run 开始时检测到已有未提交变更，并且用户选择保留，必须创建 baseline。
+如果 harness-execute 开始时检测到已有未提交变更，并且用户选择保留，必须创建 baseline。
 
 ### baseline 文件
 
@@ -448,7 +448,7 @@ SQL 相关任务状态：🟡 NEEDS_DB_VALIDATION，**不得标记为完全自
 - 无 P0 静态-only 场景
 
 ### 🟡WARN
-- 存在 P0/P1 场景仅静态验证，需 harness-test
+- 存在 P0/P1 场景仅静态验证，需 harness-execute
 - 存在预存变更
 - SQL 脚本需要人工执行或 DB 验证
 - Mapper/SQL 查询只做静态验证
@@ -463,11 +463,11 @@ SQL 相关任务状态：🟡 NEEDS_DB_VALIDATION，**不得标记为完全自
 - git diff --check 失败
 
 如果存在 SQL 迁移、接口验证、DB 验证未完成，最终不得输出纯 ✅OK，应输出：
-🟡WARN：编码完成，需 harness-test 验证剩余 DB/API 场景。
+🟡WARN：编码完成，需 harness-execute 验证剩余 DB/API 场景。
 
 ## 步骤 2：编译验证（默认轻量，按需全量 test）
 
-> **轻量验证职责**：`/harness-run` 默认只做开发反馈，不默认跑全量 `mvn test`。是否跑全量 test 按下方条件判断。
+> **轻量验证职责**：`/harness-execute` 默认只做开发反馈，不默认跑全量 `mvn test`。是否跑全量 test 按下方条件判断。
 
 ### 2a. 编译验证（始终执行）
 
@@ -478,14 +478,14 @@ powershell.exe -Command "mvn compile -pl <module> -o"
 
 ### 2b. 全量 mvn test（仅当满足触发条件时执行）
 
-默认**跳过**全量 `mvn test`，把完整单元测试留给 `/harness-test`。仅当满足以下任一条件时才在本阶段执行 `mvn test -pl <module> -o`：
+默认**跳过**全量 `mvn test`，把完整单元测试留给 `/harness-execute`。仅当满足以下任一条件时才在本阶段执行 `mvn test -pl <module> -o`：
 
 - 修改了公共模块（被多模块依赖的 common/utils 等）
 - 修改了 mapper / sql / xml
 - 修改了权限 / 认证 / 组织过滤逻辑
 - 修改了 controller / VO / DTO
 - 用户要求 `full-run-validation`
-- 用户不打算继续运行 `/harness-test`（run 需自证 P0 场景）
+- 用户不打算继续运行 `/harness-execute`（run 需自证 P0 场景）
 
 ```powershell
 powershell.exe -Command "mvn test -pl <module> -o"
@@ -504,11 +504,11 @@ powershell.exe -Command "mvn test -pl <module> -o"
 步骤 2 完成后**必须**写入/更新 `通过共享状态目录解析器定位的 evidence/verification-ledger.json`：
 
 - `compile` 项：始终写入（status / command / scope / evidence / 时间戳 / durationMs）
-- `unitTest` 项：仅当 2b 执行了全量 mvn test 时写入（testsRun / failures / errors / skipped / evidence）；未执行时标记 `{"status": "NOT_RUN_BY_RUN", "note": "轻量验证，全量单元测试由 harness-test 执行"}`
+- `unitTest` 项：仅当 2b 执行了全量 mvn test 时写入（testsRun / failures / errors / skipped / evidence）；未执行时标记 `{"status": "NOT_RUN_BY_RUN", "note": "轻量验证，全量单元测试由 harness-execute 执行"}`
 - 顶层写入 `diffHash` / `currentHead` / `baseCommit` / `module` / `profile`
 - `baseCommit`：merge-base 或计划起点（worktree 分支从主分支分出点，由 harness-plan 写入、run 读取复用；缺失时用 `git merge-base HEAD <默认分支>` 兜底）
 - `currentHead`：`git rev-parse HEAD`（步骤 2c 在 Step 5 checkpoint commit 之前执行，此时 HEAD==baseCommit；commit 后 HEAD 前移到 checkpoint commit，由 ledger-protocol reuse 规则 #2「currentHead 可前移」容忍，**不需为它改时序**）
-- `diffHash`：**必须用 ledger-protocol「五、真实 diffHash」的 commit-invariant 三部分合并命令**（与 harness-test 重算命令逐字一致），**禁止仅用 `git diff`（未提交）**。命令如下（经 `Bash(powershell.exe:*)` 通道时外层用单引号防 `$base` 展开，见 ledger-protocol 五）：
+- `diffHash`：**必须用 ledger-protocol「五、真实 diffHash」的 commit-invariant 三部分合并命令**（与 harness-execute 重算命令逐字一致），**禁止仅用 `git diff`（未提交）**。命令如下（经 `Bash(powershell.exe:*)` 通道时外层用单引号防 `$base` 展开，见 ledger-protocol 五）：
 
 ```powershell
 powershell.exe -NoProfile -Command "$base = '<baseCommit>'; $patch = '.harness/changes/<change>/runtime/current-diff.patch'; & { git diff $base HEAD --binary; git diff --binary; git ls-files --others --exclude-standard | ForEach-Object { Get-Content -Raw -LiteralPath $_ } } | Out-File -Encoding utf8 $patch; (Get-FileHash $patch -Algorithm SHA256).Hash"
@@ -522,11 +522,11 @@ powershell.exe -NoProfile -Command "$base = '<baseCommit>'; $patch = '.harness/c
 >
 > 无论 commit 前后、无论工作树是否 clean，**必须**用三部分合并命令。"commit 后 clean 致单部分偶然等价"不得作为省略三部分的依据——时序或工作树状态一旦变化即复现复用链断裂。
 
-> 这样 harness-test 的 Phase 1 可读取 ledger 判断是否复用 run 的 unitTest（diffHash commit-invariant + reuse 规则 #2 允许 HEAD 前移 → run 的 checkpoint commit 不破坏复用），submit/package 也可复用 compile 结果。详见 `../protocols/ledger-protocol.md`。
+> 这样 harness-execute 的 Phase 1 可读取 ledger 判断是否复用 run 的 unitTest（diffHash commit-invariant + reuse 规则 #2 允许 HEAD 前移 → run 的 checkpoint commit 不破坏复用），submit/package 也可复用 compile 结果。详见 `../protocols/ledger-protocol.md`。
 
 ## 步骤 3.5：权限/组织过滤类变更 — 安全矩阵
 
-> 凡是修改了以下逻辑，必须强制生成安全矩阵。如果任一权限边界的预期不明确，不允许标记 harness-run 为 ✅OK。
+> 凡是修改了以下逻辑，必须强制生成安全矩阵。如果任一权限边界的预期不明确，不允许标记 harness-execute 为 ✅OK。
 
 ### 触发条件
 
@@ -558,7 +558,7 @@ powershell.exe -NoProfile -Command "$base = '<baseCommit>'; $patch = '.harness/c
 
 ### 判定规则
 
-- 如果任一权限边界的预期不明确（如"非管理员+token空+指定组织"场景未明确是拒绝还是允许），则必须标记为 ❌未验证，且不允许标记 harness-run 为 ✅OK
+- 如果任一权限边界的预期不明确（如"非管理员+token空+指定组织"场景未明确是拒绝还是允许），则必须标记为 ❌未验证，且不允许标记 harness-execute 为 ✅OK
 - 每个场景的覆盖状态必须真实标注：✅ 自动化测试通过 / 🟡 静态检查未真实测试 / ❌ 未验证
 - 安全矩阵必须写入执行日志
 
@@ -648,7 +648,7 @@ powershell.exe -Command "git -C '<project-path>' diff --check"
 
 ## 步骤 5：计划状态持久化
 
-如果 `.harness/changes/<change>/plans/*.md` 是任务来源，则 harness-run 完成任务后必须持久化任务状态。
+如果 `.harness/changes/<change>/plans/*.md` 是任务来源，则 harness-execute 完成任务后必须持久化任务状态。
 
 ### 持久化方式
 
@@ -673,12 +673,12 @@ powershell.exe -Command "git -C '<project-path>' diff --check"
 | 任务 | 状态 | 测试场景 | 待验证 |
 |------|------|----------|--------|
 | Task 1 | ✅ DONE_AUTOMATED_TESTED | UT-001~005 | - |
-| Task 2 | 🟡 DONE_STATIC_ONLY | UT-006~010 | harness-test |
-| Task 3 | 🟡 DONE_NEEDS_INTERFACE_TEST | API-001~003 | harness-test |
+| Task 2 | 🟡 DONE_STATIC_ONLY | UT-006~010 | harness-execute |
+| Task 3 | 🟡 DONE_NEEDS_INTERFACE_TEST | API-001~003 | harness-execute |
 
 ## 待验证场景汇总
-- UT-006~010: 静态验证通过，需 harness-test 接口验证
-- API-001~003: 接口逻辑已覆盖，需 harness-test 真实 HTTP 验证
+- UT-006~010: 静态验证通过，需 harness-execute 接口验证
+- API-001~003: 接口逻辑已覆盖，需 harness-execute 真实 HTTP 验证
 ```
 
 ### 状态定义
@@ -691,7 +691,7 @@ powershell.exe -Command "git -C '<project-path>' diff --check"
 ### 规则
 
 - 不允许只在对话里说"任务完成"但不写入任何持久化文件
-- 后续 harness-test 和 harness-review 必须能从持久化状态识别哪些场景仍待验证
+- 后续 harness-execute 和 harness-review 必须能从持久化状态识别哪些场景仍待验证
 
 ## 步骤 3：场景覆盖检查
 
@@ -704,7 +704,7 @@ powershell.exe -Command "git -C '<project-path>' diff --check"
 ### 静态验证不等于测试覆盖（⚠️ 关键规则）
 
 1. 🟡 静态检查 **不得计入"已测试通过"**
-2. 如果任一 P0 场景仅静态验证，则 harness-run 最终结果必须是：
+2. 如果任一 P0 场景仅静态验证，则 harness-execute 最终结果必须是：
    `🟡WARN：编码和编译完成，但存在 P0 场景未真实验证`
 3. 只有所有 P0 场景都有自动化测试或真实接口验证时，最终结果才能是：
    `✅OK成功`
@@ -714,16 +714,16 @@ powershell.exe -Command "git -C '<project-path>' diff --check"
    自动化测试通过: 5
    静态检查未真实验证: 17
    未验证: 0
-   harness-run 结果: 🟡WARN，必须进入 harness-test 后才能 submit
+   harness-execute 结果: 🟡WARN，必须进入 harness-execute 后才能 submit
    ```
 
 > 展示格式示例：
 > ```
 > ### 场景覆盖检查
 > - ✅ UT-001~005: getEnabledIndicators 正常/异常/边界场景已测试通过
-> - 🟡 UT-006~010: getIndicatorPage 分页场景静态验证通过，待测试基础设施补齐后运行 harness-test
+> - 🟡 UT-006~010: getIndicatorPage 分页场景静态验证通过，待测试基础设施补齐后运行 harness-execute
 > - ❌ UT-011~015: getIndicatorByCode 场景未覆盖，需补充测试用例
-> - ✅ API-001~005: enabled 接口场景代码逻辑已覆盖（接口测试待 harness-test 验证）
+> - ✅ API-001~005: enabled 接口场景代码逻辑已覆盖（接口测试待 harness-execute 验证）
 > - ✅ COM-001~005: SQL 迁移脚本覆盖
 > - 🟡 INT-001~004: 需端到端部署验证
 > ```
@@ -733,7 +733,7 @@ powershell.exe -Command "git -C '<project-path>' diff --check"
 > 自动化测试通过: 5
 > 静态检查未真实验证: 17
 > 未验证: 0
-> harness-run 结果: 🟡WARN，必须进入 harness-test 后才能 submit
+> harness-execute 结果: 🟡WARN，必须进入 harness-execute 后才能 submit
 > ```
 
 ## 输出示例
@@ -755,7 +755,7 @@ powershell.exe -Command "git -C '<project-path>' diff --check"
 - 自动化测试通过: K
 - 静态检查未真实验证: M
 - 未验证: P
-- harness-run 结果: ✅OK成功 / 🟡WARN，必须进入 harness-test 后才能 submit
+- harness-execute 结果: ✅OK成功 / 🟡WARN，必须进入 harness-execute 后才能 submit
 
 ### 关门检查结果
 - git status --porcelain: ✅/❌
@@ -773,10 +773,10 @@ powershell.exe -Command "git -C '<project-path>' diff --check"
 - 状态已写入: `.harness/changes/<change-name>/run-task-status.md`
 
 ### 下一步
-> ⚠️ 如果存在 P0 场景为 🟡静态验证，下一步必须且只能是 harness-test。
+> ⚠️ 如果存在 P0 场景为 🟡静态验证，下一步必须且只能是 harness-execute。
 
-运行 `/harness-test` 验证剩余 P0 场景。
-在 harness-test 通过前，不建议也不应进入 `/harness-submit`。
+运行 `/harness-execute` 验证剩余 P0 场景。
+在 harness-execute 通过前，不建议也不应进入 `/harness-submit`。
 ```
 
 ## 关键原则
@@ -792,7 +792,7 @@ powershell.exe -Command "git -C '<project-path>' diff --check"
 
 ## 执行日志记录
 
-`/harness-run` 只向 `events.ndjson` 追加事件（schema_version 3，兼容读取 v1/v2）；`logs/execution-log.md` 由 `harness_events.py append` 自动渲染。步骤 0 之前 append `phase.start`；各阶段写入 `command` / `verification` / `decision` / `issue`，人类可读摘要放 `note`。详见 [[../../protocols/report-pipeline-protocol.md|report-pipeline-protocol]] 与 core `harness-run/SKILL.md`。
+`/harness-execute` 只向 `events.ndjson` 追加事件（schema_version 3，兼容读取 v1/v2）；`logs/execution-log.md` 由 `harness_events.py append` 自动渲染。步骤 0 之前 append `phase.start`；各阶段写入 `command` / `verification` / `decision` / `issue`，人类可读摘要放 `note`。详见 [[../../protocols/report-pipeline-protocol.md|report-pipeline-protocol]] 与 core `harness-execute/SKILL.md`。
 
 ## verification-ledger 可复用判定
 
@@ -810,7 +810,7 @@ powershell.exe -Command "git -C '<project-path>' diff --check"
 
 ## Mapper @Select / JOIN / IPage 真实验证要求
 
-`@Select`、JOIN、DISTINCT、IPage 分页、SQL/XML 变更在 run 阶段只能标记 🟡DONE_STATIC_ONLY，必须交给 harness-test 真实 DB/API 验证：
+`@Select`、JOIN、DISTINCT、IPage 分页、SQL/XML 变更在 run 阶段只能标记 🟡DONE_STATIC_ONLY，必须交给 harness-execute 真实 DB/API 验证：
 
 - SQL 可执行；
 - total 正确；

package/harness/bundles/java/claude-code/harness-execute/protocols.md

@@ -0,0 +1,141 @@
+---
+description: harness-execute 的原生执行协议。内化 TDD 与变更簇审查能力，但不运行时依赖 Superpowers。
+---
+
+# harness-execute 原生执行协议
+
+本文件定义 `/harness-execute` 的内置执行协议。它吸收 test-driven-development 与 subagent-driven-development 的有效做法，但正式流程不调用 Superpowers，也不把外部 skill 是否存在作为执行条件。
+
+## 协议一：run-tdd-protocol
+
+用于每个变更簇。目标是保留 RED→GREEN→REFACTOR 的行为约束，同时允许 harness 按证据分级处理缺失测试基础设施的现实情况。
+
+### RED 三态
+
+| RED 类型 | 何时使用 | 证据要求 |
+|----------|----------|----------|
+| 真实 RED | 测试基础设施可用，能写测试并运行失败 | 测试编译通过，失败断言指向目标行为 |
+| 静态 RED | 测试基础设施不可用或目标层无法真实验证 | 记录降级原因、静态验证场景、待 harness-execute 验证场景 |
+| 复用 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>
+> ```