@hunter-harness/workflow-harness 0.4.0 → 0.4.2

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

@@ -0,0 +1,166 @@
+---
+name: harness-review
+description: 6维度代码审查（架构/安全/规范/兼容/测试/性能），对照项目规则（见
+  .harness/context-index.json）和测试场景表，在隔离上下文运行。仅当用户显式调用 /harness-review 时使用；不得在
+  test 结束后自动接续执行。
+---
+<!-- generated by harness_deploy.py; core=c6237736626a939b; overlay=java; agent=pi; do not edit -->
+# harness-review — 代码审查
+
+## Purpose
+
+对 git diff 进行6维度审查，对照项目规则和测试场景表，输出分级报告。**审查结果仅供参考，默认不阻塞后续 submit/archive 流程。**
+
+## When to Use
+
+仅当用户显式调用 `/harness-review` 时执行。test 阶段结束后**不自动**进入本阶段；用户口头提到"审查/review"而未调用本 skill 时，先确认是否走 Harness 审查阶段。
+
+**单阶段原则**：review 关门（报告 + fixback 产出）后必须停止并交还用户，仅提示下一步可执行 `/harness-execute --fixback`（有待修项）或 `/harness-submit`；禁止自动接续执行。
+
+## Inputs
+
+- `$ARGUMENTS`：变更名（可选，留空时自动扫描 `.harness/changes/*/plans/` 确定）
+- 相关文件：`.harness/changes/*/plans/*-plan.md`、`项目规则（见 .harness/context-index.json）/`、测试场景表
+
+## 前置条件
+
+- `.harness/changes/<change-name>/plans/<change-name>-plan.md` 存在（任务真相源）
+- 必须读取 `.harness/changes/<change-name>/meta/worktree.json`：`requested=true` 且 worktree 已创建 → 在 worktree 目录中执行审查；`requested=true` 但 worktree 不存在 → 停止，提示先修复 `harness-run`，不得静默回主目录
+- **review 不阻塞后续流程**：test 报告缺失或未运行不阻止 review（review 是参考性阶段），但应在报告中标注 test 状态供参考
+
+## 统一读取协议
+
+0. **脚本在 `<skills-root>/scripts/` 共享，不在每个 skill 子目录下** — 实际形态是 `.codebuddy/skills/scripts/harness_*.py`（`.claude`/`.cursor`/`.codex` 同理），**没有** `.../skills/harness-<phase>/scripts/`。plan、run/test、archive 三份执行日志里都先猜成后者、报 `No such file` 再靠 Search 找回来；照第一种写法直接用
+1. **`.harness/changes/<change-name>/` 是唯一真相源** — 所有输入从该目录读取，产物写入对应子目录
+2. **change-name 优先从 frontmatter 读取** — `plans/*-design.md`、`spec/*-design.md`、`plans/*-plan.md` 的 YAML `change-name`
+3. **frontmatter 缺失时兼容旧格式** — 从路径推断，标记 `🟡 legacy-plan`，不失败
+4. **design** — 设计真相源按序取第一个存在的：`plans/<change>-design.md`（v2 发布产物，哈希绑定）→ `spec/<change>-design.md`（legacy 手写）。两份**同时存在**时以 `plans/` 为准，并记 `🟡 WARN 设计文档双份`——v2 发布的那份才受完整性门禁保护，读手写的那份等于绕过校验
+5. **plan** — 任务真相源：`plans/<change>-plan.md`
+6. **implementation-detail** — 自适应执行参考；legacy 缺失 🟡WARN，不阻断
+7. **test-scenarios** — 测试真相源：`plans/<change>-test-scenarios.md`
+8. **禁止读取 `docs/superpowers/` 作为正式输入** — 旧草稿仅人工线索
+9. **每个 skill 边界只刷新一次状态快照** — 先运行 `python <skills-root>/scripts/harness_state.py capture --project . --change-dir ".harness/changes/<change-name>" --json`。首次 Plan 捕获时，脚本把当时的 Git HEAD 写入不可变 `changeBase`；后续阶段只刷新 `git.head` 与各段指纹，不得用当前 HEAD 覆盖 `changeBase`。只有迁移旧 change 且已能证明真实计划起点时，才在首次补录时传 `--base <baseCommit>`。`changedSegments=[]` 时复用已有 profile/rules/map/change/code 指纹，不再重复跑全量 `harness-sync` 或代码库扫描。`knowledge` 段仅为兼容空段，知识始终按需远端查询；快照不能替代源码读取和验证门禁。
+
+状态目录分层：新路径优先，旧路径兼容 → [[../protocols/state-layout-protocol.md|state-layout-protocol]]
+> 片段：read-protocol
+
+## Workflow
+
+先用 `harness_context.py prepare --phase review --executor <tool> [--change <id>] --json` 与 `harness_context.py begin --phase review --change <id> --executor <tool> --json` 解析唯一 active change 并校验实际前序 receipt；多个 active change 未显式选择时返回 `ACTIVE_CHANGE_AMBIGUOUS`，禁止再按 Glob/mtime 猜测。阶段门禁使用 `harness_gate.py begin --phase review --change <id> --task <n> --skills-root <skills-root> --executor-tool <tool> --json`；结束时只执行一次 `harness_gate.py close`，正常路径的 `--to-phase` 取 `plannedPhases` 中 review 的后继，Fixback 才返回 run。由 gate 完成阶段事件、租约、上下文交接与远端补传。不得手工追加阶段边界或再次调用 context close；任一 close 失败不得宣称评审完成。
+
+0. **启动准备** — 确定变更名（Glob `.harness/changes/*/plans/*-plan.md`，排除 `.harness/archive/*/`，读 frontmatter 提取 change-name）；**append `phase.start` 事件**（不得等审查完成才补）
+1. **读取 worktree 状态（门禁检查）** — 读 `.harness/changes/<change-name>/meta/worktree.json`：`requested=true` 但 worktree 不存在 → 停止并提示先修复 `harness-run`，不得静默回主目录（否则 git diff 为空）；`requested=true` 且 worktree 已创建 → spawned agent 用该 worktree 路径执行 `git diff`（确保审查 worktree 变更而非主目录）；`requested=false` → 审查主目录变更
+<!-- @section-id review.delegate -->
+### 2. 审查执行（独立评审优先）
+
+环境已安装 pi-subagents 扩展（提供 `subagent` 工具）时，默认优先临时委派一次只读审查，**不要求安装固定 `harness-reviewer`，也不运行固定 `harness-reviewer` 预检**。子任务只读取 diff、规则和测试证据；主会话核验并写报告。无法委派、spawn 失败、空返回或无报告正文 → 不 retry，继续主会话审查。每次都记一条 `decision`，用 `REVIEW_DELEGATED` 或相应 `REVIEW_INLINE_*` 原因码说明是否委派及原因；正常 inline 不显示为故障。
+## Review 定位（重要）
+
+**harness-review 是参考性代码审查阶段，不是硬门禁。**
+
+| 等级 | 含义 | 后续影响 |
+|:----:|------|----------|
+| RED | 高风险建议，强烈建议处理 | 不阻塞后续流程 |
+| YELLOW | 中低风险建议 | 不阻塞后续流程 |
+| OK | 无问题 | 不阻塞后续流程 |
+
+- 审查结果默认只作为参考，不阻塞 `/harness-submit`、`/harness-archive`
+- 除非用户显式要求"review 结果阻塞提交"，否则 review 不参与硬门禁
+- Review 报告中**禁止写**：阻塞 submit / 必须修复后才能继续
+- Review 报告中**应写**：建议优先处理 / 建议在 submit 前人工确认 / 建议补充测试 / 仅供参考，不阻塞后续 harness 流程
+
+### 可选 strict-review-gate 配置
+
+如果团队希望 review 结果阻塞提交，可在 `.harness/config/harness-test-config.md` 中设置：
+
+```yaml
+review:
+  strict-review-gate: true   # 默认 false
+```
+
+当且仅当 `strict-review-gate: true` 时，review RED 才阻塞 submit。默认行为是 `strict-review-gate: false`。
+
+## Output Format
+
+审查报告保存到 `.harness/changes/<change-name>/reports/review/review-report-YYYYMMDD-HHmm.md`（时间戳区分多次运行），同时在控制台输出摘要。报告格式详见 `reference.md` 的「输出报告完整模板」。
+
+## 渐进披露
+
+- **Read `checklist.md`** 仅在执行完整6维度审查时 — 含6维度检查项详细列表 + 输出格式 + 执行日志记录模板
+- **Read `reference.md`** 仅在需要理解审查标准或生成详细报告时 — 含"为什么需要审查"概述 + 严重级别判定标准 + 输出报告完整模板
+- **Read `protocols.md`** 仅在 RED/YELLOW 问题需要转化为修复反馈时 — 含 `review-fixback-protocol` 的结构化 fixback 字段与落盘要求
+
+## 原生修复反馈协议
+
+`/harness-review` 不再运行时调用 Superpowers `receiving-code-review`。审查后的修复反馈能力内化为 `protocols.md` 的 `review-fixback-protocol`：
+
+1. RED/YELLOW 问题转成 fixback 条目：严重级别、位置、风险、建议、验证方式、对 submit 的影响。
+2. fixback 落盘到 `.harness/changes/<change-name>/reports/review/fixback-YYYYMMDD-HHmm.md`。
+3. 无 RED/YELLOW 时记录跳过原因，不制造空修复任务。
+
+没有 `.codegraph/` 只意味着“项目尚未建立 CodeGraph 索引，已直接读取源码”，不得将它写成独立评审不可用或委派失败原因。历史英文原因码不得进入摘要；稳定码只写结构化字段并留在技术详情。
+
+## 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]]
+
+## 生成内容语言约定
+
+- sync/ingest 等生成的文档、规则、知识条目、架构说明一律**优先使用中文**撰写（标识符、命令、代码、API 字段名保持原文）
+- 面向平台展示的标题/摘要/正文默认中文；仅当用户明确要求或目标系统强制时才用英文
+> 片段：p0-trust
+
+## 关键规则（硬门禁速查）
+
+> 每条规则的详细判定、检查项见 `checklist.md` 对应章节；Shell 执行安全见 `../protocols/powershell-protocol.md`，敏感信息见 `../protocols/sensitive-info-protocol.md`，证据化报告见 `../protocols/evidence-based-reporting-protocol.md`，状态目录见 `../protocols/state-layout-protocol.md`，结构化报告事件见 `../protocols/report-pipeline-protocol.md`。
+
+### 一、只审查 git diff 变更部分
+
+只审查本次 `git diff` 中的变更，不审查已有代码；diff 为空 → 直接返回"无变更可审查"。每个问题给出具体修复建议（文件:行号 + 建议做法）。
+
+### 二、严重级别三态
+
+RED=高风险建议（强烈建议处理），YELLOW=中低风险建议，OK=无问题。6维度逐文件审查（架构/安全/规范/兼容/测试/性能）—— 检查项见 `checklist.md`。判定标准见 `reference.md`「严重级别判定标准」。
+
+### 三、review 结果仅供参考（不阻塞后续流程）
+
+review 结果默认只作参考，不阻塞 submit/archive；报告措辞遵循 `## Review 定位（重要）` 的“禁止写/应写”清单，不得出现“阻塞 submit / 必须修复后才能继续”。
+
+### 四、Shell 安全 / 敏感信息 / 证据化报告 / CodeGraph 探索
+
+git diff/log 命令通过 `powershell.exe -Command "..."` 执行；review-report 中如发现明文 token/密码/密钥，必须列入 RED 问题并在报告中以 `<TOKEN_REDACTED>` 等占位符引用；RED/YELLOW/OK 结论必须基于实际 diff 内容，不得凭印象判断。代码探索必须优先使用 CodeGraph MCP 工具（`mcp__codegraph__codegraph_explore`），不允许通过普通 Bash 调 codegraph 命令（已列入 `disallowed-tools`）；采纳任何返回源码前，按 `reference.md` 的 C12 合同校验 executionRoot/rootPath、worktreeId、repositoryId、HEAD 与 index snapshot，`IDENTITY_MISMATCH` 必须读取实际 worktree，不得当作 stale 忽略；MCP 不可用时降级为 Grep/Glob + Read，并在执行日志记录降级原因。遵循 `../protocols/powershell-protocol.md` / `sensitive-info-protocol.md` / `evidence-based-reporting-protocol.md`。
+
+### 五、state snapshot 与源码重验
+
+review 读取 `state-snapshot.json`（`harness_state.py` / state-layout-protocol §state-snapshot.json）的 code/diff 段确定审查范围；snapshot 失效或代码段变化时**必须重新读取实际变更源码**，不得仅凭缓存快照跳过源码审查（design §3.6）。
+
+## 交互白名单
+
+**无** blocking user confirmation（审查全自动）。委派失败 → 主会话审查 + `decision` 事件。
+
+## 执行日志
+
+`events.ndjson` 为唯一事实源（schema_version 3，兼容读取 v1/v2；`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止用 Write/Edit 直接维护**。直接修改的内容会在 `phase.end` 或 finalize 时被完整重建覆盖，属于数据丢失；需要保留的详情必须进入事件 `note`。结构 → [[../protocols/report-pipeline-protocol.md|report-pipeline-protocol]]
+
+**`phase.start` 由 `harness_gate.py begin` 写，不要再手工追加一次。** 两条同 `run-id` 的
+`phase.start` 会让 `plan finalize` 以 `PHASE_START_DUPLICATE` 卡死，而且手工那次会先触发
+auto-seal、把正在开始的 attempt 封成 `RECOVERED`。要补触发指令说明就带 `--note` 跑 `gate begin`。
+（重复追加现已按 `(phase, run-id)` 判为幂等 no-op，但依赖它不如不写。）
+
+```powershell
+# 阶段开始：gate begin 负责，note 在这里给
+python <skills-root>/scripts/harness_gate.py begin --change-dir ".harness/changes/<change-name>" --phase <phase> --note "<触发指令>"
+# 阶段中的其他事件才用 append
+python <skills-root>/scripts/harness_events.py append --change-dir ".harness/changes/<change-name>" --phase <phase> --type <command|issue|verification> --run-id <phase-run-id> --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 边界保持最新。
+
+每个阶段的 `phase.start` 与对应 `phase.end` 必须复用同一 `--run-id` / `--attempt`；阶段结束必须写 `--status OK|WARN|FAIL|BLOCKED`。重试同一阶段时生成新的 run-id 并增加 `--attempt <n>`，不得覆盖或伪装成一次执行。**`attempt` 按 phase 全局递增，不是按 run-id**：一个 run-id 只绑定一个 attempt，重试必须「新 run-id ＋ 下一个 attempt」两者同时换，只换其一会撞 `EVENT_ATTEMPT_CONFLICT` 或 `PHASE_ALREADY_CLOSED`。已发布 plan 的修订通过重跑 `plan evidence-pack` + `plan finalize` 分配新 attempt（`harness_plan_finalize.py republish` 已于 0.3.0 移除）。
+
+阶段跑得久（plan/run 常见）时用 `harness_context.py renew --project . --change <cn> --executor <tool>` 续租；租约到期本身不再阻断 `close`（同一 owner 的过期租约不构成冲突，收据里记 `leaseLapsed`），但续租能让 `view` 的状态如实反映在跑。跨工具继续执行时写 `--executor-tool <codex|claude-code|codebuddy|cursor>`，并在接棒事件写 `--handoff-from-tool` / `--handoff-reason`；也可由 `HUNTER_HARNESS_TOOL/AGENT/MODEL/RUN_ID` 环境变量统一注入。
+> 片段：logging · phase=`review` · 事件：phase/decision/verification/issue/artifact

package/harness/bundles/java/pi/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 路径（`.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. 对照 项目规则（见 .harness/context-index.json）/ 检查
+
+逐个规则文件检查变更是否违规。违规项标注对应规则文件名和行号。
+
+### 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 文件（违反 项目 codegraph 规则 规则）
+```
+
+## 关键原则
+
+- 只审查 `git diff` 中的变更部分，不审查已有代码
+- 对照 `项目规则（见 .harness/context-index.json）/` 是审查的基准线
+- 区分严重级别：RED=高风险建议（强烈建议处理），YELLOW=中低风险建议
+- 每个问题给出具体修复建议（文件:行号 + 建议做法）
+- 如果 diff 为空，直接返回"无变更可审查"
+- **review 结果仅供参考，不阻塞后续 submit/archive**
+
+## 事件记录
+
+- [ ] append `phase.start` 事件（步骤 0 启动准备之前；`note` 含触发指令）
+- [ ] append `phase.end` 事件（`note` 含耗时、结果、落盘 path、RED/YELLOW 统计摘要）

package/harness/bundles/java/pi/harness-review/protocols.md

@@ -0,0 +1,69 @@
+---
+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 |
+| 影响位置 | 文件路径 + 行号或最小可定位区域 |
+| 风险说明 | 说明为什么值得处理 |
+| 推荐修复 | 可执行的修复方向，不写空泛建议 |
+| 验证方式 | 构建、测试、场景编号或人工确认方式 |
+| 修复动作 | `code` / `manual` / `workflow`；只有 `code` 会进入 `/harness-execute --fixback` |
+| submit 影响 | 默认 advisory；仅 strict-review-gate=true 时标记阻塞 |
+
+如果没有 RED/YELLOW，必须明确写：
+
+```markdown
+无需 fixback：本次 review 未发现 RED/YELLOW 问题。
+```
+
+### 定位边界
+
+- harness-review 默认仅供参考，不阻塞 submit/archive。
+- `review-fixback-protocol` 只生成修复反馈，不自动修改代码。人工验收与流程建议不得伪装成代码问题，也不得创建空 Fixback 批次。
+- 不得把 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/harness/bundles/java/pi/harness-review/reference.md

@@ -0,0 +1,114 @@
+---
+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 时记录跳过原因，不生成空文件。
+
+## CodeGraph Identity 合同（C12）
+
+发出 `codegraph_explore` 前，必须从实际 `executionRoot` 构造并随查询记录以下
+expected identity：`rootPath`、`worktreeId`（主 checkout 为 `null`）、`repositoryId`、`head`。
+采纳返回源码前，必须校验响应中的：
+
+- `rootPath` 必须是当前 `executionRoot`（规范化后比较）；不可只比较 repositoryId
+- `worktreeId` 必须与当前 worktree 相同；主 checkout 必须为 `null`
+- `repositoryId` 必须与 `harness_paths.repository_identity(project_root)` 一致
+- `head`（兼容 `indexedHead`）必须与当前 HEAD 一致
+- `indexSnapshotAt`（兼容 `indexedAt`）必须存在
+
+identity 不匹配时必须返回 `IDENTITY_MISMATCH`，包含 expected/actual 的完整
+identity，且**不得采纳任何 CodeGraph 源码**；降级为 Grep/Glob + Read 实际
+worktree。该状态不同于 index stale，不能以 stale warning 代替。
+identity 匹配时正常使用 codegraph 结果。
+
+校验函数：
+`harness_review.validate_codegraph_identity(response, expected_repository_id, expected_head, expected_root, expected_worktree_id)`。
+
+Review 通过脚本入口执行该校验，例如：
+
+```text
+python harness_review.py validate-codegraph-identity --input <codegraph-response.json> \
+  --execution-root <actual-worktree-root> --repository-id <repository-id> \
+  --head <HEAD> [--worktree-id <worktree-id>]
+```