hunter-harness 0.1.0 → 0.1.2

package/resources/harness/java/harness-run/SKILL.md

@@ -1,148 +1,148 @@
----
-name: harness-run
-description: "按变更簇执行 TDD 编码循环（RED→GREEN→REFACTOR→编译验证），逐变更簇实现计划中的任务。使用场景：开始编码、实现功能、写代码、TDD 编码"
-argument-hint: "变更名 | --subagent | --inline | --fixback | 留空自动检测"
-effort: medium
-allowed-tools: [Read, Edit, Write, Glob, Grep, Bash(powershell.exe:*)]
-disallowed-tools:
-  - Bash(git *)
-  - Bash(mvn *)
-  - Bash(ls *)
-  - Bash(find *)
-  - Bash(grep *)
-  - Bash(cat *)
-  - Bash(cp *)
-  - Bash(mv *)
-  - Bash(rm *)
-  - Bash(mkdir *)
-  - Bash(touch *)
-  - Bash(sed *)
-  - Bash(awk *)
-  - Bash(curl *)
-  - Bash(codegraph *)
----
-<!-- generated by harness_deploy.py; core=8917528f7dfdc5ca; overlay=java; do not edit -->
-# harness-run — 需求编码
-
-## Purpose
-
-基于 plan + test-scenarios，按**变更簇**执行 TDD（RED→GREEN→REFACTOR→构建验证），写入 verification-ledger。负责 worktree 创建/切换（见 [[shared/worktree-gate.md|worktree-gate]]）。
-
-## When to Use
-
-触发语："开始编码""实现功能""写代码""TDD编码"。参数：`--subagent` 强制 Subagent-Driven；`--inline` 等同默认；`--fixback` 读最新 review fixback。**默认 Inline，不询问执行模式**。
-
-## 前置条件
-
-- `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` 时静默回主目录。创建失败 → 停止或 AskUserQuestion 降级（须 🟡WARN + 用户确认）。
-
-**状态与代码分离**：代码/编译/测试在 `worktreeRoot`；`stateDir`（logs/events/ledger/reports）写回 `.harness/changes/<change-name>/`。
-
-创建命令与 JSON 模板 → 各 skill `reference.md`（plan 写决策，run 创建/更新）。
-
-## 统一读取协议
-
-1. **`.harness/changes/<change-name>/` 是唯一真相源** — 所有输入从该目录读取，产物写入对应子目录
-2. **change-name 优先从 frontmatter 读取** — `spec/*-design.md`、`plans/*-plan.md` 的 YAML `change-name`
-3. **frontmatter 缺失时兼容旧格式** — 从路径推断，标记 `🟡 legacy-plan`，不失败
-4. **spec** — 设计真相源：`spec/<change>-design.md`
-5. **plan** — 任务真相源：`plans/<change>-plan.md`
-6. **implementation-detail** — 自适应执行参考；legacy 缺失 🟡WARN，不阻断
-7. **test-scenarios** — 测试真相源：`plans/<change>-test-scenarios.md`
-8. **禁止读取 `docs/superpowers/` 作为正式输入** — 旧草稿仅人工线索
-
-状态目录分层：新路径优先，旧路径兼容 → [[../protocols/state-layout-protocol.md|state-layout-protocol]]
-
-## 执行模式
-
-默认 **Inline Execution**；仅 `--subagent` 切换 Subagent-Driven。
-
-## Workflow 概要
-
-0. 加载上下文（change-name、spec/plan/detail/scenarios/ledger/run-task-status/worktree；`--fixback` 读 fixback）→ append `phase.start`
-0.5. **测试基础设施探测**（先写 `CHECKING`，四项证据齐备后再结论）→ `reference.md` Step 0.5
-1. **变更簇 TDD** — `protocols.md` `run-tdd-protocol`；批量 RED/GREEN；按需 `change-cluster-review-protocol`（高风险 + reviewer 预检可用）
-2. 构建验证 + 写 ledger（diffHash 三部分合并，`reference.md` Step 2c）
-3. **场景覆盖检查**（场景表映射，禁止用用例数冒充场景数）
-4. **关门检查**（10 项）+ 计划状态持久化
-
-**Fixback**：`--fixback` 或用户要求时读 `reports/review/fixback-*.md`；RED 优先；未选用则记 `fixback: advisory-not-applied`。
-
-### Java 构建验证（Maven）
-
-- 所有 `mvn`/`git` 经 `powershell.exe -NoProfile -Command`；命令读 `.harness/config/build-profile.json` 的 `buildCommands`（**禁止 hardcode 模块名/端口**）
-- 增量编译：`buildCommands.compile`（典型 `mvn compile -pl <module> -o -q`）
-- 变更簇 TDD：多测试类合并一次 `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` 等构建配置存在；缺失时从主目录复制
-## 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]]
-
-## 关键规则（硬门禁速查）
-
-> 全文判定、示例、模板 → `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** | 基础设施先探测；每次构建/测试写 ledger；三部分 diffHash |
-| **预存变更** | 保留 → baseline 隔离；存在则最终 ≥ 🟡WARN |
-| **关门/状态** | 10 项关门检查；持久化 run-task-status；P0 静态-only 不得建议 submit |
-| **Worktree** | `requested=true` 时代码只写 worktree |
-| **PowerShell** | 所有 git/构建经 `powershell.exe -NoProfile -Command` |
-
-### Java TDD / 数据访问补充
-
-| 项 | 规则 |
-|----|------|
-| **低价值豁免** | ErrorCode 常量、VO/DTO 字段、注释、import 清理、格式化、SQL 脚本、配置模板、文档 — 不单独建测试类；禁止为单个错误码单独跑 Maven |
-| **Mapper / LambdaQueryWrapper / SQL** | 纯 Mock 返回值**不得**宣称 DB 验证通过 → 🟡 静态验证，交 harness-test 真实 DB |
-| **行为性新分支** | 正则/条件/分支逻辑变更新增分支须 RED→GREEN；不属于低价值豁免 |
-| **ledger** | compile 必写；执行了 test 写 unitTest，否则 `NOT_RUN_BY_RUN`；diffHash 三部分合并（见 reference） |
-## 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 2，`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止手工 Edit**。结构 → [[../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 "<触发指令>"
-```
-
-> **脚本接线**：`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 边界保持最新。
+---
+name: harness-run
+description: "按变更簇执行 TDD 编码循环（RED→GREEN→REFACTOR→编译验证），逐变更簇实现计划中的任务。使用场景：开始编码、实现功能、写代码、TDD 编码"
+argument-hint: "变更名 | --subagent | --inline | --fixback | 留空自动检测"
+effort: medium
+allowed-tools: [Read, Edit, Write, Glob, Grep, Bash(powershell.exe:*)]
+disallowed-tools:
+  - Bash(git *)
+  - Bash(mvn *)
+  - Bash(ls *)
+  - Bash(find *)
+  - Bash(grep *)
+  - Bash(cat *)
+  - Bash(cp *)
+  - Bash(mv *)
+  - Bash(rm *)
+  - Bash(mkdir *)
+  - Bash(touch *)
+  - Bash(sed *)
+  - Bash(awk *)
+  - Bash(curl *)
+  - Bash(codegraph *)
+---
+<!-- generated by harness_deploy.py; core=47a5159f5c4b49b8; overlay=java; do not edit -->
+# harness-run — 需求编码
+
+## Purpose
+
+基于 plan + test-scenarios，按**变更簇**执行 TDD（RED→GREEN→REFACTOR→构建验证），写入 verification-ledger。负责 worktree 创建/切换（见 [[shared/worktree-gate.md|worktree-gate]]）。
+
+## When to Use
+
+触发语："开始编码""实现功能""写代码""TDD编码"。参数：`--subagent` 强制 Subagent-Driven；`--inline` 等同默认；`--fixback` 读最新 review fixback。**默认 Inline，不询问执行模式**。
+
+## 前置条件
+
+- `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` 时静默回主目录。创建失败 → 停止或 AskUserQuestion 降级（须 🟡WARN + 用户确认）。
+
+**状态与代码分离**：代码/编译/测试在 `worktreeRoot`；`stateDir`（logs/events/ledger/reports）写回 `.harness/changes/<change-name>/`。
+
+创建命令与 JSON 模板 → 各 skill `reference.md`（plan 写决策，run 创建/更新）。
+
+## 统一读取协议
+
+1. **`.harness/changes/<change-name>/` 是唯一真相源** — 所有输入从该目录读取，产物写入对应子目录
+2. **change-name 优先从 frontmatter 读取** — `spec/*-design.md`、`plans/*-plan.md` 的 YAML `change-name`
+3. **frontmatter 缺失时兼容旧格式** — 从路径推断，标记 `🟡 legacy-plan`，不失败
+4. **spec** — 设计真相源：`spec/<change>-design.md`
+5. **plan** — 任务真相源：`plans/<change>-plan.md`
+6. **implementation-detail** — 自适应执行参考；legacy 缺失 🟡WARN，不阻断
+7. **test-scenarios** — 测试真相源：`plans/<change>-test-scenarios.md`
+8. **禁止读取 `docs/superpowers/` 作为正式输入** — 旧草稿仅人工线索
+
+状态目录分层：新路径优先，旧路径兼容 → [[../protocols/state-layout-protocol.md|state-layout-protocol]]
+
+## 执行模式
+
+默认 **Inline Execution**；仅 `--subagent` 切换 Subagent-Driven。
+
+## Workflow 概要
+
+0. 加载上下文（change-name、spec/plan/detail/scenarios/ledger/run-task-status/worktree；`--fixback` 读 fixback）→ append `phase.start`
+0.5. **测试基础设施探测**（先写 `CHECKING`，四项证据齐备后再结论）→ `reference.md` Step 0.5
+1. **变更簇 TDD** — `protocols.md` `run-tdd-protocol`；批量 RED/GREEN；按需 `change-cluster-review-protocol`（高风险 + reviewer 预检可用）
+2. 构建验证 + 写 ledger（diffHash 三部分合并，`reference.md` Step 2c）
+3. **场景覆盖检查**（场景表映射，禁止用用例数冒充场景数）
+4. **关门检查**（10 项）+ 计划状态持久化
+
+**Fixback**：`--fixback` 或用户要求时读 `reports/review/fixback-*.md`；RED 优先；未选用则记 `fixback: advisory-not-applied`。
+
+### Java 构建验证（Maven）
+
+- 所有 `mvn`/`git` 经 `powershell.exe -NoProfile -Command`；命令读 `.harness/config/build-profile.json` 的 `buildCommands`（**禁止 hardcode 模块名/端口**）
+- 增量编译：`buildCommands.compile`（典型 `mvn compile -pl <module> -o -q`）
+- 变更簇 TDD：多测试类合并一次 `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` 等构建配置存在；缺失时从主目录复制
+## 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]]
+
+## 关键规则（硬门禁速查）
+
+> 全文判定、示例、模板 → `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** | 基础设施先探测；每次构建/测试写 ledger；三部分 diffHash |
+| **预存变更** | 保留 → baseline 隔离；存在则最终 ≥ 🟡WARN |
+| **关门/状态** | 10 项关门检查；持久化 run-task-status；P0 静态-only 不得建议 submit |
+| **Worktree** | `requested=true` 时代码只写 worktree |
+| **PowerShell** | 所有 git/构建经 `powershell.exe -NoProfile -Command` |
+
+### Java TDD / 数据访问补充
+
+| 项 | 规则 |
+|----|------|
+| **低价值豁免** | ErrorCode 常量、VO/DTO 字段、注释、import 清理、格式化、SQL 脚本、配置模板、文档 — 不单独建测试类；禁止为单个错误码单独跑 Maven |
+| **Mapper / LambdaQueryWrapper / SQL** | 纯 Mock 返回值**不得**宣称 DB 验证通过 → 🟡 静态验证，交 harness-test 真实 DB |
+| **行为性新分支** | 正则/条件/分支逻辑变更新增分支须 RED→GREEN；不属于低价值豁免 |
+| **ledger** | compile 必写；执行了 test 写 unitTest，否则 `NOT_RUN_BY_RUN`；diffHash 三部分合并（见 reference） |
+## 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 2，`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止手工 Edit**。结构 → [[../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 "<触发指令>"
+```
+
+> **脚本接线**：`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 边界保持最新。