hunter-harness 0.1.2 → 0.2.0

package/resources/harness/bundles/java/claude-code/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/bundles/java/claude-code/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 → bundles/java/claude-code}/harness-run/SKILL.md

@@ -21,7 +21,7 @@ disallowed-tools:
   - Bash(curl *)
   - Bash(codegraph *)
 ---
-<!-- generated by harness_deploy.py; core=47a5159f5c4b49b8; overlay=java; do not edit -->
+<!-- generated by harness_deploy.py; core=c7f197c6a6f1ff5a; overlay=java; agent=claude-code; do not edit -->
 # harness-run — 需求编码
 
 ## Purpose

package/resources/harness/{java → bundles/java/claude-code}/harness-run/checklist.md

@@ -28,7 +28,7 @@
 - [ ] **读取测试场景表**：`.harness/changes/<change>/plans/<change>-test-scenarios.md` — 获取与当前任务相关的测试场景
 - [ ] **读取验证账本**：`.harness/changes/<change>/verification-ledger.json`（如存在）— 复用已有 compile/unitTest 结果
 - [ ] **读取任务状态**：`.harness/changes/<change>/run-task-status.md`（如存在）— 恢复上次运行状态
-- [ ] 确认 `.claude/rules/` 规则已加载
+- [ ] 确认 `项目规则（见 .harness/context-index.json）/` 规则已加载
 - [ ] 检查构建配置完整性（worktree 中确认 `.mvn/maven.config`、`settings.xml` 等存在）
 - [ ] 依赖模块预安装（worktree 中检查上游模块是否已 `mvn install`）
 - [ ] 代码探索优先用 `codegraph_explore`，仅在返回不完整时补充 Read

package/resources/harness/bundles/java/claude-code/harness-run/protocols.md

@@ -0,0 +1,78 @@
+---
+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`：任务状态、对应场景、未验证项。
+- `logs/execution-log.md`：RED 类型、GREEN 结果、REFACTOR 结果、验证证据。
+- `events.ndjson`：关键 command / verification / issue / artifact 事件。
+
+禁止把静态验证写成“测试通过”。静态 RED/GREEN 的最终状态至少是 🟡WARN，除非后续真实验证已完成。
+
+## 协议二：change-cluster-review-protocol
+
+用于高风险变更簇后的轻量审查。它内化 subagent-driven-development 的“新上下文审查”价值，但不把每个变更簇的 subagent 审查设为默认流程。
+
+### 触发条件
+
+满足**全部**条件时启用：
+
+- 变更簇命中高风险（数据迁移、权限、安全、并发、幂等、核心契约变更、缺真实测试证据等，见原触发列表任一）
+- `python <skills-root>/scripts/harness_preflight.py check-agents --skills-root <skills-root> --agent harness-reviewer --json` 返回 `usable=true`
+
+未满足时记录“跳过变更簇审查：低风险 / reviewer 不可用 / 后续 harness-review 覆盖”，不得视为降级。
+
+### 审查方式
+
+`usable=true` 时委派只读 `harness-reviewer` 审查当前变更簇 diff。**不 retry**；无效返回 → 主会话 checklist 自审，记 `decision` 事件。
+
+审查范围只限当前变更簇：
+
+- 是否偏离 plan / implementation-detail。
+- 是否遗漏 test-scenarios 中的 P0/P1 场景。
+- 是否破坏 API、数据、权限、安全或兼容契约。
+- 是否引入非计划文件、临时 debug、敏感信息或过程性注释。
+
+### 输出
+
+审查结论写入当前 run 日志：
+
+```markdown
+### 变更簇审查 — <cluster>
+- 触发原因: <risk trigger>
+- 方式: reviewer / 主会话自审 / 跳过
+- 结论: OK / YELLOW / RED
+- 问题: <文件:行 + 建议>
+```
+
+RED 问题必须在当前 run 中处理或明确记录为未处理风险；YELLOW 问题可交给后续 `/harness-review`。

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

@@ -90,12 +90,12 @@ powershell.exe -NoProfile -Command "Test-Path '.claude/worktrees/<change-name>/.
 6. **读取测试场景表**：`.harness/changes/<change-name>/plans/<change-name>-test-scenarios.md` → 获取测试真相源
 7. **读取验证账本**：`.harness/changes/<change-name>/verification-ledger.json`（如存在）→ 复用已有 compile/unitTest 结果
 8. **读取任务状态**：`.harness/changes/<change-name>/run-task-status.md`（如存在）→ 恢复上次运行状态
-9. 确认 `.claude/rules/` 规则已加载
+9. 确认 `项目规则（见 .harness/context-index.json）/` 规则已加载
 10. **执行测试基础设施探测**（见下方"步骤 0.5"）
 11. 确认编译环境正常（`powershell.exe -Command "mvn compile -pl <module> -o -q"`）
 12. **检查构建配置完整性**：如果在 worktree 中执行，确认构建配置文件（如 `.mvn/maven.config`、`settings.xml`、`gradle.properties` 等）存在。worktree 可能不包含主目录的构建配置，缺失时从主目录复制
 13. **依赖模块预安装**：如果在 worktree 中执行，检查上游依赖模块是否已 `mvn install` 到本地仓库。缺失时先执行 `powershell.exe -Command "mvn install -pl <upstream-modules> -am -DskipTests -nsu"`
-14. **代码探索优先用 codegraph_explore**：一次调用可获取多个相关符号的源码，替代逐个 Read 文件。违反 `.claude/rules/codegraph.md` 规则逐个 Read 会浪费 3-5 分钟。仅在 codegraph 返回结果不完整时补充 Read
+14. **代码探索优先用 codegraph_explore**：一次调用可获取多个相关符号的源码，替代逐个 Read 文件。违反 `项目 codegraph 规则` 规则逐个 Read 会浪费 3-5 分钟。仅在 codegraph 返回结果不完整时补充 Read
 
 ### 步骤 0.1：执行模式（默认 Inline）
 

package/resources/harness/{java → bundles/java/claude-code}/harness-submit/SKILL.md

@@ -20,7 +20,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=47a5159f5c4b49b8; overlay=java; do not edit -->
+<!-- generated by harness_deploy.py; core=c7f197c6a6f1ff5a; overlay=java; agent=claude-code; do not edit -->
 # harness-submit — 最终提交（含 worktree 合并）
 
 ## Purpose