hunter-harness 0.1.2 → 0.2.0

package/resources/harness/bundles/java/codebuddy/harness-plan/reference.md

@@ -0,0 +1,376 @@
+---
+description: harness-plan 的需求提取模板、任务拆分规则、测试场景4维度详细格式。仅在执行规划需要参考详细格式时读取。
+---
+
+# harness-plan
+
+## Worktree 决策文件模板
+
+阶段 2 必须生成 `.harness/changes/<change-name>/meta/worktree.json`。这是后续 `/harness-run` 是否创建/切换 worktree 的唯一机器可读依据。
+
+### 使用 Worktree
+
+```json
+{
+  "requested": true,
+  "created": false,
+  "path": ".claude/worktrees/<change-name>",
+  "branch": "worktree/<change-name>",
+  "decisionBy": "user",
+  "decisionAt": "YYYY-MM-DD HH:mm",
+  "ownerSkill": "harness-run"
+}
+```
+
+### 不使用 Worktree
+
+```json
+{
+  "requested": false,
+  "created": false,
+  "path": null,
+  "branch": null,
+  "decisionBy": "user",
+  "decisionAt": "YYYY-MM-DD HH:mm",
+  "ownerSkill": null
+}
+```
+
+### execution-log 记录示例
+
+```md
+## 阶段 2：Worktree 决策
+- 用户选择：使用 Worktree
+- 决策文件：.harness/changes/<change-name>/meta/worktree.json
+- requested=true, created=false
+- 创建责任：harness-run
+```
+
+## 参考 — 详细格式
+
+## 阶段 1：需求接收
+
+接收用户输入（文字描述或文档路径），提取关键信息：
+- 功能范围（要做什么、不做什么）
+- 业务规则（校验逻辑、权限约束）
+- 数据模型变更（新表、新字段）
+- 接口变更（新增/修改的端点）
+
+如果需求不明确（如"做一个指标管理功能"），列出具体疑问向用户澄清——不要猜测后直接设计。
+
+### 影响面检查
+
+方案汇总后（阶段 4 末尾），主动列出可能受影响但用户未提及的点，让用户一次性确认：
+
+```markdown
+### 影响面检查
+
+基于代码探索，以下点可能受本次变更影响但尚未讨论：
+
+| # | 影响点 | 说明 | 需要处理？ |
+|:--:|--------|------|:----------:|
+| 1 | 请求参数变更 | 数据契约删除字段后，前端请求格式变化 | 是/否 |
+| 2 | 数据库迁移 | 字段删除前需迁移历史数据 | 是/否 |
+| 3 | 其他模块引用 | 其他业务模块引用了该字段 | 是/否 |
+| 4 | 前端兼容性 | 旧前端传已删除字段会报错 | 是/否 |
+```
+
+> 这一检查的目的是减少设计文档生成后的迭代轮次——提前发现用户可能提出的修改。
+
+## 阶段 3：代码探索（只读）输出格式
+
+```markdown
+## 设计概要 — <功能名>
+
+### 涉及模块
+- 接口层: xxx-server/.../xxx/
+- 业务层: 同上
+- 新增表: xxx
+- 修改表: xxx (新增 N 字段)
+
+### 接口变更
+| 方法 | 路径 | 类型 |
+|------|------|:----:|
+| GET | /xxx | 新增 |
+| POST | /xxx | 修改 |
+
+### 关键决策
+- 决策1: 说明
+- 决策2: 说明
+```
+
+## 阶段 5：生成设计文档 ⚠️ 用户审核
+
+基于代码探索和需求澄清的结果，撰写设计文档并展示给用户审核。
+
+> **本阶段是强制检查点。** 设计文档生成后必须展示给用户，收到确认后才能进入阶段 6（任务拆分）。设计文档确保方向正确后再细化任务——避免基于错误理解拆分出无效任务。
+
+**用户确认后必须立即写入** `.harness/changes/<change-name>/spec/<change-name>-design.md`。如果此文件不存在，harness-plan 不得进入阶段 6。
+
+**设计文档路径规则**：设计文档必须保存到 `.harness/changes/<change-name>/spec/<change-name>-design.md`。禁止保存到 `docs/superpowers/specs/` 作为正式产物；`/harness-plan` 不运行时调用 Superpowers。
+
+### 设计文档模板
+
+```markdown
+---
+change-name: <change-name>
+created: YYYY-MM-DD HH:mm
+status: approved
+source: harness-plan
+---
+
+# <功能名> 设计文档
+
+> 日期：YYYY-MM-DD
+> 状态：待审核
+> 范围：<简述改动范围>
+
+---
+
+## 1. 背景与动机
+
+<为什么做这个改动？现有代码有什么问题或缺失？这个改动解决什么痛点？>
+
+<如果涉及差距分析，用表格对比现状与目标：>
+
+| 维度 | 现状 | 目标 | 差距级别 |
+|------|------|------|---------|
+| ... | ... | ... | 🔴/🟡/🟠 |
+
+---
+
+## 2. 方案概述
+
+<选定方案的核心思路，2-3句话概括>
+
+---
+
+## 3. 详细设计
+
+<按改动涉及的维度分节展示，每节包含：>
+- 具体做法
+- 配置变更
+- 关键设计决策及原因
+
+---
+
+## 4. 变更清单
+
+| 类别 | 文件路径 | 说明 |
+|------|---------|------|
+| 新增 | `exact/path/to/file` | ... |
+| 修改 | `exact/path/to/file` | ... |
+
+---
+
+## 5. 验证方式
+
+<如何测试这些改动？列出关键验证步骤>
+```
+
+### 设计文档自审
+
+写完设计文档后，用以下清单自检：
+- □ 无"TBD"/"TODO"/未完成章节
+- □ 各节之间无矛盾
+- □ 范围聚焦，无不相关内容
+- □ 无歧义需求（可被两种方式解读的，已选一种并明确说明）
+
+## 阶段 6：任务拆分
+
+将设计拆分为可追踪的任务，标注涉及文件和依赖关系。任务拆分执行 `protocols.md` 的 `implementation-planning-protocol`：plan 简表保持精炼，implementation-detail 按复杂度自适应展开。
+
+### 产物结构
+
+推荐结构：
+
+```
+.harness/changes/<change-name>/plans/
+├── <change-name>-plan.md                    # harness 简洁任务表，run 默认读取
+├── <change-name>-implementation-detail.md   # 原生自适应详细执行参考，run 补充读取
+└── <change-name>-test-scenarios.md          # 测试场景表
+```
+
+### 计划文件 frontmatter（必须）
+
+```yaml
+---
+change-name: <change-name>
+plan-name: <change-name>
+created: YYYY-MM-DD HH:mm
+source-spec: ../spec/<change-name>-design.md
+implementation-detail: ./<change-name>-implementation-detail.md
+test-scenarios: ./<change-name>-test-scenarios.md
+status: approved
+---
+```
+
+### 简洁任务表格式（`<change-name>-plan.md`）
+
+```markdown
+| # | 任务 | 涉及文件 | 依赖 |
+|:--:|------|----------|:----:|
+| 1 | 新建枚举类 | 2 个枚举 | - |
+| 2 | 扩展错误码 | 错误码定义文件 | - |
+| 3 | 编写数据库迁移脚本 | 1 个迁移脚本 | - |
+| 4 | 新建数据模型 | 2 个数据模型 | 3 |
+| ... | ... | ... | ... |
+```
+
+## 阶段 7：测试场景表 4 维度格式
+
+场景表覆盖 **4 个维度**：
+
+```markdown
+## 测试场景 — <功能名>
+> 生成日期：YYYY-MM-DD | 对应需求：xxx.md | 对应计划：xxx-plan.md
+
+### 一、单元测试场景
+
+#### 1.1 <类名.方法名>
+
+| # | 分类 | 场景描述 | 输入 | 预期 |
+|:--:|:----:|----------|------|------|
+| UT-001 | 正常 | ... | ... | ... |
+| UT-002 | 异常 | ... | ... | 抛 xxxException |
+| UT-003 | 边界 | ... | ... | ... |
+
+### 二、接口测试场景
+
+#### 2.1 POST /xxx
+
+| # | 分类 | 场景描述 | 关键字段 | HTTP | code | message |
+|:--:|:----:|----------|----------|:----:|:----:|--------|
+| API-001 | 正常 | ... | ... | 200 | 0 | 成功 |
+| API-002 | 校验 | ... | ... | 200 | xxx | ... |
+
+### 三、数据兼容场景
+
+| # | 分类 | 场景描述 | 操作 | 数据特征 | 预期 |
+|:--:|:----:|----------|:----:|----------|------|
+| COM-001 | 旧数据 | ... | ... | ... | ... |
+
+### 四、集成场景
+
+| # | 分类 | 场景描述 | 前置条件 | 步骤 | 预期 |
+|:--:|:----:|----------|----------|------|------|
+| INT-001 | 端到端 | ... | ... | N 步操作 | ... |
+```
+
+## 产物保存规则（跨阶段：阶段1/5/6/8）
+
+1. **自动确定变更名**：基于需求描述自动生成变更名（kebab-case），无需用户确认
+
+   变更名命名规则：
+   - **kebab-case**（小写字母，单词间连字符）
+   - 从需求/功能描述中提取核心关键词
+   - 示例：`contribution-module`、`fix-duplicate-submit`
+   - 变更名一旦确定即为最终值，后续所有 skill 自动引用
+
+   > **与 Worktree 的关系**：如果阶段 2 用户选择了 worktree，变更名在创建 worktree 时随分支名确定（worktree 名即变更名）。如果未使用 worktree，变更名在阶段 1 自动生成。
+
+2. **创建产出目录**：用 Write 工具创建以下目录结构（Write 会自动创建中间目录）：
+   ```
+   .harness/changes/<change-name>/meta/
+   .harness/changes/<change-name>/logs/
+   .harness/changes/<change-name>/spec/
+   .harness/changes/<change-name>/plans/
+   .harness/changes/<change-name>/evidence/
+   .harness/changes/<change-name>/reports/
+   .harness/changes/<change-name>/sqls/
+   .harness/changes/<change-name>/scripts/
+   .harness/changes/<change-name>/runtime/
+   .harness/changes/<change-name>/backups/
+   ```
+
+3. **保存设计文档**：将阶段 5 生成的设计文档保存到：
+   - `.harness/changes/<change-name>/spec/<change-name>-design.md`
+
+   设计文档 frontmatter 格式：
+   ```yaml
+   ---
+   change-name: <change-name>
+   created: YYYY-MM-DD HH:mm
+   status: approved
+   source: harness-plan
+   ---
+   ```
+
+   > 如果 frontmatter 缺失，后续 run/test/review/submit/archive 不得依赖模型猜测 change-name。
+
+4. **初始化执行日志和结构化事件**：创建 `.harness/changes/<change-name>/logs/execution-log.md` 与 `.harness/changes/<change-name>/events.ndjson`，写入变更开始记录和 `phase.start` 事件：
+
+   ```markdown
+   # 执行日志 — <change-name>
+
+   > 变更创建时间：YYYY-MM-DD HH:MM | 变更名：<change-name>
+
+   ---
+   ```
+
+5. **保存计划文件**：计划文件包含 YAML frontmatter（含 change-name），保存到：
+   - `.harness/changes/<change-name>/plans/<change-name>-plan.md`（简洁任务表）
+   - `.harness/changes/<change-name>/plans/<change-name>-implementation-detail.md`（自适应详细执行参考）
+   - `.harness/changes/<change-name>/plans/<change-name>-test-scenarios.md`（测试场景表）
+
+   计划文件 frontmatter 格式：
+   ```yaml
+   ---
+   change-name: <change-name>
+   plan-name: <change-name>
+   created: YYYY-MM-DD HH:mm
+   source-spec: ../spec/<change-name>-design.md
+   implementation-detail: ./<change-name>-implementation-detail.md
+   test-scenarios: ./<change-name>-test-scenarios.md
+   status: approved
+   ---
+   ```
+
+   > 如果 frontmatter 缺失，后续 run 不得依赖模型猜测 change-name 或关联文件路径。
+
+6. **等待用户确认后**，提示下一步：运行 `/harness-run`
+
+   > 后续 skill（run/test/review）启动时，会扫描 `.harness/changes/*/plans/`（排除 `.harness/archive/*/`）自动定位变更名目录，无需手动指定路径。同一时间最多一个未归档变更。
+
+## 阶段 8：结束前产物完整性检查 ⚠️ 强制
+
+> **缺任一文件 → ❌FAIL，不得宣称 plan 完成。**
+
+| 文件 | 必须存在 |
+|------|:---:|
+| `.harness/changes/<change>/spec/<change>-design.md` | ✅ |
+| `.harness/changes/<change>/plans/<change>-plan.md` | ✅ |
+| `.harness/changes/<change>/plans/<change>-implementation-detail.md` | ✅ |
+| `.harness/changes/<change>/plans/<change>-test-scenarios.md` | ✅ |
+| `.harness/changes/<change>/meta/worktree.json` | ✅ |
+| `.harness/changes/<change>/logs/execution-log.md` | ✅ |
+| `.harness/changes/<change>/events.ndjson` | ✅ |
+
+### Plan 结束行为规则
+
+- **禁止询问执行模式**：Subagent-Driven / Inline Execution 属于 /harness-run 阶段
+- 最终输出只提示产出物路径和下一步 `/harness-run`
+- `docs/superpowers/` 不得作为最终产物路径出现在输出中
+
+## C2 升级口：Codex 跨 provider 评审（可选，未实现）
+
+阶段 7.5 的 harness-evaluator 是同 provider（Claude）评审，基于"上下文隔离 + 档位差异"。如需真正跨 provider 对抗（高风险构建：auth/支付/数据迁移/并发），可在 evaluator 返回 REVISE 后，可选调 Codex CLI 做二次确认。
+
+### 前置
+- Codex CLI ≥ 0.130：`npm install -g @openai/codex@latest`（现 0.142.3）
+- Codex 已登录：`codex login`（ChatGPT 账号即可）
+- Windows + bridge 环境未实测，TODO(review)
+
+### 执行（示例）
+```powershell
+powershell.exe -NoProfile -Command "codex exec -s read-only '$(Get-Content .harness/changes/<cn>/spec/<cn>-design.md -Raw)'"
+```
+
+### 安全线 ⚠️
+- 首次 `codex exec -s read-only` 强制只读沙箱
+- resume 必须加 `-c sandbox_mode="read-only"`（`resume` 不接受 `-s`，漏写会继承 config 默认，可能 `danger-full-access`）——这是最关键安全线
+- Codex 全程只读，从不写文件
+- 不 pin `-m` 模型（ChatGPT 账号鉴权会拒 `gpt-5.x-codex` 变体并 400 报错）
+
+### 状态
+本节为**升级口**，当前 harness-plan 阶段 7.5 默认走 harness-evaluator（C1），不自动触发 Codex。需手动启用，且建议先验证 Codex CLI 在当前环境可用。详见 grill-me 文档的 grill-me-codex Act 2（技术知识库/02-Skills与扩展/Skills合集/grill-me.md）。

package/resources/harness/bundles/java/codebuddy/harness-review/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: harness-review
+description: 6维度代码审查（架构/安全/规范/兼容/测试/性能），对照项目规则（见
+  .harness/context-index.json）和测试场景表，在隔离上下文运行。使用场景：代码审查、提交前检查、合并评审
+---
+<!-- generated by harness_deploy.py; core=c7f197c6a6f1ff5a; overlay=java; agent=codebuddy; do not edit -->
+# harness-review — 代码审查
+
+## Purpose
+
+对 git diff 进行6维度审查，对照项目规则和测试场景表，输出分级报告。**审查结果仅供参考，默认不阻塞后续 submit/archive 流程。**
+
+## When to Use
+
+使用此 Skill 当：
+- 代码变更完成后需要审查
+- 提交前需要质量检查
+- 合并评审时需要系统性检查
+- 用户说"审查代码"、"review"、"检查代码质量"
+
+## 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 状态供参考
+
+## 统一读取协议
+
+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]]
+
+## Workflow
+
+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. 委派 harness-reviewer
+
+先运行 `python <skills-root>/scripts/harness_preflight.py check-agents --skills-root <skills-root> --agent harness-reviewer --json`。`usable=false` → **直接主会话审查**，记 `decision` 事件，**不委派**。`usable=true` 时用 Agent spawn `harness-reviewer`（只读, 6 维度）。返回空 / 无报告正文 → **不 retry**，降级主会话审查。
+
+3. **持久化报告（强制，主会话）** — Agent 返回后主会话 Write 到 `reports/review/review-report-*.md`。未 Write → 🟡WARN，不得宣称 review 完成。
+4. **生成修复反馈（原生协议）** — 若报告存在 RED/YELLOW 问题，执行 `protocols.md` 的 `review-fixback-protocol`，将问题转化为结构化 fixback 清单并落盘到 `.harness/changes/<change-name>/reports/review/fixback-YYYYMMDD-HHmm.md`。若无 RED/YELLOW，记录 `review-fixback-protocol: skipped(no findings)`。不调用 Superpowers `receiving-code-review`，也不记录外部 skill 降级。
+5. **收尾** — append `phase.end` / `artifact` 事件；控制台输出摘要
+
+## 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 时记录跳过原因，不制造空修复任务。
+
+## 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]]
+
+## 关键规则（硬门禁速查）
+
+> 每条规则的详细判定、检查项见 `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`）；MCP 不可用时降级为 Grep/Glob + Read，并在执行日志记录降级原因。遵循 `../protocols/powershell-protocol.md` / `sensitive-info-protocol.md` / `evidence-based-reporting-protocol.md`。
+
+## 交互白名单
+
+**无** AskUserQuestion（审查全自动）。委派失败 → 主会话审查 + `decision` 事件。
+
+## 执行日志
+
+`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 边界保持最新。

package/resources/harness/bundles/java/codebuddy/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. 对照 项目规则（见 .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 统计摘要）