hunter-harness 0.1.0

package/resources/harness/java/harness-review/checklist.md

@@ -0,0 +1,124 @@
+---
+description: harness-review 的6维度审查检查项详细列表。仅在执行完整代码审查时读取。
+---
+
+# harness-review 检查清单
+
+## 启动准备：确定变更名
+
+用 Glob 搜索 `.harness/changes/*/plans/*-plan.md`（**排除 `.harness/archive/*/`**），读取 frontmatter 提取 `change-name`。默认最多一个未归档变更；如有多个，优先取最近修改的，或询问用户。后续所有路径基于此变更名。
+
+**读取 worktree 状态**：读 `.harness/changes/<change-name>/meta/worktree.json`。`requested=true` 且 worktree 已创建 → 后续 `git diff` 的 `<项目路径>` 用 worktree 路径（`.claude/worktrees/<change-name>`）；`requested=true` 但 worktree 不存在 → 停止，提示先修复 `harness-run`，不得静默回主目录。
+
+## 审查流程
+
+### 1. 获取变更范围
+
+```powershell
+powershell.exe -Command "git -C '<项目路径>' diff --stat"
+powershell.exe -Command "git -C '<项目路径>' diff"
+```
+
+### 2. 六维度逐文件审查
+
+#### 维度 1：架构
+
+| 检查项 | 为什么重要 |
+|--------|------------|
+| 接口层中有业务逻辑 | 破坏分层，后续修改影响面不可控 |
+| 业务层间循环依赖 | 启动失败或运行时 StackOverflow |
+| 接口层跨模块调用业务层 | 破坏模块边界，耦合扩散 |
+| 业务层抛异常、接口层 try-catch | 异常处理应在全局异常处理器统一 |
+| 写操作无事务边界 | 数据不一致（部分写入成功、部分失败） |
+
+#### 维度 2：安全
+
+| 检查项 | 为什么重要 |
+|--------|------------|
+| 硬编码密码/Token/密钥 | 代码泄露 = 凭据泄露 |
+| 字符串拼接 SQL | SQL 注入风险 |
+| 用户输入直接返回前端 | XSS 风险 |
+| 对生产库执行写操作 | 数据丢失/破坏 |
+| 日志打印敏感信息 | 日志泄露 Token/身份证号 |
+| 新增接口无权限校验 | 未授权访问 |
+
+#### 维度 3：编码规范
+
+| 检查项 | 严重度 |
+|--------|:------:|
+| 数据类暴露不必要可变 setter（应改只读访问器） | YELLOW |
+| 控制台输出替代日志框架 | YELLOW |
+| 集合方法返回 null 而非空集合 | YELLOW |
+| 魔法值未定义常量 | YELLOW |
+| 公共 API 无文档注释 | YELLOW |
+
+#### 维度 4：兼容性
+
+| 检查项 | 为什么重要 |
+|--------|------------|
+| 删除/修改已发布接口的字段 | 旧前端/调用方立即报错 |
+| 删除/重命名数据库已有字段 | 数据丢失 |
+| 删除/修改已有枚举值 | 存量数据无法解析 |
+| 新增字段不为 nullable | 旧数据无法查询/写入 |
+
+#### 维度 5：测试
+
+对照场景表检查覆盖。重点看新增业务方法是否有对应单元测试，异常场景是否有覆盖。
+
+#### 维度 6：性能
+
+| 检查项 | 信号 |
+|--------|------|
+| N+1 查询 | 循环体内调用数据访问层查询 |
+| 缺少索引 | 新增 WHERE 条件无对应索引 |
+| 大事务 | 事务内含远程调用或文件 IO |
+| 逐条 insert | 循环内单条 insert 而非批量 |
+
+### 3. 对照 .claude/rules/ 检查
+
+逐个规则文件检查变更是否违规。违规项标注对应规则文件名和行号。
+
+### 4. 对照场景表检查
+
+如果场景表存在，逐条确认代码是否覆盖。未覆盖的标记为「测试缺口」。
+
+## 输出格式
+
+审查报告保存到 `.harness/changes/<change-name>/reports/review/review-report-YYYYMMDD-HHmm.md`（时间戳格式：日期+时分），同时在控制台输出摘要。完整报告模板见 `reference.md`「输出报告完整模板」，本文不再重复。
+
+## 原生修复反馈检查
+
+### fixback 生成确认（按需）
+
+如果用户需要修复任务清单，确认以下事项：
+
+```
+□ 已读取 harness-review/protocols.md
+□ 已执行 review-fixback-protocol（不调用外部 receiving-code-review）
+□ RED/YELLOW 问题已转化为结构化修复任务清单
+□ 修复任务清单含严重级别、位置、风险、修复建议、验证方式、submit 影响
+□ fixback 已落盘到 .harness/changes/<change-name>/reports/review/fixback-YYYYMMDD-HHmm.md
+```
+
+> 如果没有 RED/YELLOW 问题，记录 `review-fixback-protocol: skipped(no findings)`，不要生成空 fixback。`harness-review` 不检查 Superpowers 是否安装，也不记录外部 skill 降级。
+
+### 代码探索效率检查
+
+```
+□ 审查代码时优先使用 codegraph_explore（一次获取多个符号源码）
+□ 未逐个 Read 文件（违反 .claude/rules/codegraph.md 规则）
+```
+
+## 关键原则
+
+- 只审查 `git diff` 中的变更部分，不审查已有代码
+- 对照 `.claude/rules/` 是审查的基准线
+- 区分严重级别：RED=高风险建议（强烈建议处理），YELLOW=中低风险建议
+- 每个问题给出具体修复建议（文件:行号 + 建议做法）
+- 如果 diff 为空，直接返回"无变更可审查"
+- **review 结果仅供参考，不阻塞后续 submit/archive**
+
+## 事件记录
+
+- [ ] append `phase.start` 事件（步骤 0 启动准备之前；`note` 含触发指令）
+- [ ] append `phase.end` 事件（`note` 含耗时、结果、落盘 path、RED/YELLOW 统计摘要）

package/resources/harness/java/harness-review/protocols.md

@@ -0,0 +1,68 @@
+---
+description: harness-review 的原生修复反馈协议。内化 receiving-code-review 能力，但不运行时依赖外部 skill。
+---
+
+# harness-review 原生修复反馈协议
+
+本文件定义 `/harness-review` 的 `review-fixback-protocol`。它把 RED/YELLOW 审查建议转成结构化修复反馈，不调用 Superpowers `receiving-code-review`。
+
+## review-fixback-protocol
+
+用于 review 报告生成之后。目标是让 RED/YELLOW 问题可以被后续 run 或人工修复直接消费，同时保持 harness-review 的 advisory 定位。
+
+### 输入
+
+- `reports/review/review-report-YYYYMMDD-HHmm.md`
+- 当前 diff 的 RED/YELLOW 问题清单
+- `plans/<change-name>-test-scenarios.md`
+- `evidence/verification-ledger.json` 与 `evidence/run-task-status.md`（如存在）
+
+### 输出规则
+
+如果存在 RED/YELLOW 问题，必须单独生成结构化 fixback 并写入：
+
+```text
+.harness/changes/<change-name>/reports/review/fixback-YYYYMMDD-HHmm.md
+```
+
+每条 fixback 必须包含：
+
+| 字段 | 要求 |
+|------|------|
+| 等级 | RED / YELLOW |
+| 影响位置 | 文件路径 + 行号或最小可定位区域 |
+| 风险说明 | 说明为什么值得处理 |
+| 推荐修复 | 可执行的修复方向，不写空泛建议 |
+| 验证方式 | 构建、测试、场景编号或人工确认方式 |
+| submit 影响 | 默认 advisory；仅 strict-review-gate=true 时标记阻塞 |
+
+如果没有 RED/YELLOW，必须明确写：
+
+```markdown
+无需 fixback：本次 review 未发现 RED/YELLOW 问题。
+```
+
+### 定位边界
+
+- harness-review 默认仅供参考，不阻塞 submit/archive。
+- `review-fixback-protocol` 只生成修复反馈，不自动修改代码。
+- 不得把 YELLOW 写成必须阻塞 submit。
+- 只有配置 `strict-review-gate: true` 时，RED 才可标记为阻塞 submit。
+
+### 模板
+
+```markdown
+# Review Fixback — <change-name>
+
+## 摘要
+
+- RED: N
+- YELLOW: M
+- strict-review-gate: true/false
+
+## 修复反馈
+
+| # | 等级 | 影响位置 | 风险说明 | 推荐修复 | 验证方式 | submit 影响 |
+|:--:|:----:|----------|----------|----------|----------|-------------|
+| 1 | RED | `path/to/file:123` | ... | ... | `test-scenarios.md` API-001 + 构建命令 | advisory / blocking |
+```

package/resources/harness/java/harness-review/reference.md

@@ -0,0 +1,86 @@
+---
+description: harness-review 的审查标准说明和输出报告完整模板。仅在需要理解审查标准或生成详细报告时读取。
+---
+
+# harness-review 参考 — 审查标准
+
+## 为什么需要审查
+
+即使有 TDD 和场景覆盖，仍然可能遗漏一些只在"阅读代码"时才能发现的问题：
+- 违反架构约束（TDD 关注行为，不关注结构）
+- 安全漏洞（测试通常不会故意测试安全攻击）
+- 编码规范偏离（IDE 自动格式化可能产生不一致的风格）
+- 性能隐患（N+1 查询在单元测试中不起眼，但在生产环境是灾难）
+
+> 维度检查项的详细列表和重要性说明见 `checklist.md`，本文件保留"为什么需要审查"概述、严重级别判定标准和输出报告模板。
+
+## 严重级别判定标准
+
+RED/YELLOW/OK 三态的判定原则——结论必须基于实际 diff 内容，不得凭印象；每条建议给出文件:行号 + 修复做法。
+
+| 级别 | 判定原则 | 典型场景 |
+|:----:|------|------|
+| RED | 高风险，强烈建议处理——生产环境会直接造成损失或数据破坏 | 硬编码密码/Token/密钥；SQL 字符串拼接（注入）；新增接口无权限校验；删除/修改已发布接口字段或数据库字段；写操作无事务边界；业务层间循环依赖；接口层跨模块调用；对生产库执行写操作 |
+| YELLOW | 中低风险，建议处理——影响可维护性或存在隐患，但不会立即造成损失 | 数据类暴露不必要可变 setter（应改只读访问器）；控制台输出替代日志框架；集合返回 null 而非空集合；魔法值未定义常量；公共 API 无文档注释；N+1 查询；缺少索引；大事务；逐条 insert；新增非空字段；新增业务方法无对应单元测试 |
+| OK | 该维度在本次 diff 中无问题 | —— |
+
+**判定要点**：
+- 敏感信息（明文 token/密码/密钥）一律 RED，并在报告中以 `<TOKEN_REDACTED>` 等占位符引用
+- 占位符与脱敏做法遵循 `../protocols/sensitive-info-protocol.md`；结论须基于实际 diff 证据，见 `../protocols/evidence-based-reporting-protocol.md`
+- 安全维度的问题默认 RED（除非确属误报）
+- 兼容性维度：删除/修改已发布契约为 RED，新增字段提醒为 YELLOW
+- 测试维度：核心业务方法无任何测试覆盖为 YELLOW（建议补充），不判 RED（review 不阻塞）
+- 当界限模糊时，倾向 YELLOW 并在建议中说明判断依据，让用户决定
+
+## 输出报告完整模板
+
+```markdown
+## 代码审查报告 — <功能名>
+
+### 变更摘要
+- 变更文件: N 个 | +xxx / -xxx
+
+### 审查结果
+
+| 维度 | RED 高风险 | YELLOW 中低风险 | OK 通过 |
+|------|:------:|:------:|:------:|
+| 架构 | 0 | 1 | 4 |
+| 安全 | 0 | 0 | 5 |
+| 编码规范 | 0 | 2 | 4 |
+| 兼容性 | 0 | 0 | 4 |
+| 测试 | 0 | 1 | 3 |
+| 性能 | 0 | 0 | 3 |
+
+### RED 高风险建议（强烈建议处理）
+| # | 文件:行 | 维度 | 问题 | 建议 | 参考优先级 |
+|:--:|---------|------|------|------|:--------:|
+| （列出所有高风险问题） |
+
+### YELLOW 中低风险建议（建议处理）
+| # | 文件:行 | 维度 | 问题 | 建议 | 参考优先级 |
+|:--:|---------|------|------|------|:--------:|
+| 1 | xxx:396 | 架构 | ... | ... | 建议优先处理 |
+| 2 | xxx:25 | 规范 | 数据类暴露可变 setter | 改为只读访问器 | 建议在 submit 前人工确认 |
+
+### 规则对照
+| 规则文件 | 结果 |
+|----------|:----:|
+| architecture.md | OK / FAIL |
+| 项目编码规范（按技术栈，示例：Java 项目的 `java-coding-standards.md`，前端项目按项目实际规则文件） | OK / FAIL |
+| 项目框架规范（按技术栈，示例：Java 项目的 `spring-boot-patterns.md`，其他技术栈按项目实际） | OK / FAIL |
+| testing-conventions.md | OK / FAIL |
+| database-safety.md | OK / FAIL |
+
+### 总结
+RED 高风险建议: N | YELLOW 中低风险建议: M | 仅供参考，不阻塞后续 harness 流程
+```
+
+## Fixback 输出关系
+
+当审查报告包含 RED 或 YELLOW 问题时，执行 `protocols.md` 的 `review-fixback-protocol`，另行生成：
+
+```text
+.harness/changes/<change-name>/reports/review/fixback-YYYYMMDD-HHmm.md
+```
+
+fixback 是给后续修复循环使用的结构化清单，不替代 review-report；无 RED/YELLOW 时记录跳过原因，不生成空文件。

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

@@ -0,0 +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 边界保持最新。