hunter-harness 0.1.0

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

@@ -0,0 +1,124 @@
+---
+description: harness-plan 的原生规划协议。吸收 brainstorming、grill-me、writing-plans 的方法论精华，但不运行时依赖外部 skill。
+---
+
+# harness-plan 原生规划协议
+
+本文件定义 `/harness-plan` 的内置 planning kernel。它吸收外部 skill 的有效做法，但正式流程不调用 Superpowers、grill-me 或 writing-plans，也不读取或同步 `docs/superpowers/` 作为计划产物。
+
+核心原则：**流程更轻，质量门槛更硬**。删掉外部 skill 检查、Adapter Mode、降级和草稿同步；保留需求澄清、逐问决策、方案对比、任务自检和测试优先。
+
+## 协议一：clarification-protocol
+
+用于阶段 4，目标是把需求从“用户意图”收敛成可审核设计输入。
+
+必须输出以下五类结论，并写入 `logs/execution-log.md`，关键决策同步追加到 `events.ndjson`：
+
+| 输出 | 要求 |
+|------|------|
+| 风险识别 | 列出会影响实现、测试、数据、兼容性或交付判断的风险 |
+| 复用机会 | 明确可复用的既有模块、接口、测试、迁移脚本或历史知识 |
+| 替代方案 | 给出 2-3 个可行方案；简单需求可给 1 个主方案 + 1 个不选方案 |
+| 推荐方案 | 明确推荐选项和理由，不让用户从空白处决策 |
+| 用户确认的关键决策 | 只记录真正影响范围、行为、兼容性或风险的决策 |
+
+执行纪律：
+
+1. 先消费阶段 0.5 的 context pack、阶段 3 的代码探索结果和项目规则。
+2. 能由代码、历史知识、配置、现有文档回答的问题，不问用户。
+3. 需要用户裁决时，交给 `decision-grilling-protocol`。
+4. 影响面检查必须覆盖用户未显式提到的参数、数据、接口、权限、兼容性、模块引用和测试影响。
+5. 低风险工程判断可由 AI 推荐并记录后继续；高风险或业务语义判断必须等待用户确认。
+
+## 协议二：decision-grilling-protocol
+
+用于阶段 4 的用户澄清问题。它借鉴 grill-me 的逐问决策树，但采用有限问题预算，避免仪式化盘问。
+
+### 问题预算
+
+| 场景 | 用户问题上限 |
+|------|:---:|
+| 信息充分、无必须裁决的问题 | 0 |
+| 普通需求 | 1-3 |
+| 高风险需求（auth、支付、数据迁移、并发、安全、不可逆删除、用户可见行为变化） | 5-7 |
+
+超过预算仍无法收敛时，不要继续追问；必须输出“未决决策清单”，标记阻塞项，并请用户裁决是否缩小范围或暂停。
+
+### 提问格式
+
+每次只问一个问题，且必须包含推荐答案：
+
+```markdown
+### 需要确认：<决策主题>
+
+我的推荐：<推荐答案>
+
+理由：<为什么这个选择更适合当前代码、历史上下文和风险约束>
+
+取舍：<代价、风险、未来扩展限制>
+
+请确认是否采用该推荐，或指出要调整的方向。
+```
+
+### 自动采用与必须确认
+
+可自动采用推荐并记录：
+- 文件组织、命名、任务顺序、测试拆分
+- 是否复用现有 helper、adapter、测试 fixture
+- 不改变用户可见行为的内部实现细节
+
+必须用户确认：
+- 需求范围增删、延期或拆分
+- 权限、安全、支付、审计、数据迁移、删除行为
+- API 契约、错误码、前端兼容、用户可见行为变化
+- 不可逆操作或可能影响历史数据的方案
+
+不确定归类时，按“必须确认”处理。
+
+## 协议三：implementation-planning-protocol
+
+用于阶段 6，目标是把已审核设计转成 harness 可执行计划，而不是生成外部超细步骤文档。
+
+### 产物分工
+
+| 产物 | 定位 | 详细度 |
+|------|------|--------|
+| `<change-name>-plan.md` | 任务真相源 | 简洁任务表：任务、涉及文件、依赖 |
+| `<change-name>-implementation-detail.md` | 执行参考 | 按复杂度自适应：关键接口、顺序、坑点、测试策略 |
+| `<change-name>-test-scenarios.md` | 测试真相源 | 4 维度测试场景 + 覆盖检查 |
+
+`implementation-detail.md` 必须存在，但不再强制写成 2-5 分钟粒度、逐行代码片段或逐 commit 指令。简单任务可以短，复杂任务必须细。
+
+### 计划质量门槛
+
+任务拆分必须满足：
+
+- 每个任务有明确目标、涉及文件和依赖。
+- 不出现 `TBD`、`TODO`、`稍后实现`、`补充测试`、`适当处理错误` 等占位表达。
+- 不引用尚未定义的类型、函数、接口或迁移文件。
+- 层序依赖清晰：数据/契约先于业务实现，业务实现先于接口暴露，验证场景覆盖关键路径。
+- 测试方向明确：单元、接口、数据兼容、集成至少说明适用与不适用原因。
+- 如果设计范围发生收缩，先按 `change-name` 同步规则处理名称和路径。
+
+### implementation-detail 自适应规则
+
+| 复杂度 | 内容要求 |
+|--------|----------|
+| 简单修复 | 关键文件、修改点、验证命令、容易误判的边界 |
+| 中等功能 | 模块顺序、接口/数据约束、测试策略、回滚/兼容注意事项 |
+| 高风险构建 | 迁移顺序、失败恢复、权限/安全边界、并发/幂等、评审关注点 |
+
+禁止为了“看起来完整”生成机械微步骤；也禁止因为“只是参考”而写空泛描述。
+
+## 自检
+
+阶段 4 和阶段 6 完成后，必须自检：
+
+```markdown
+### 原生规划协议自检
+- clarification-protocol：风险 / 复用 / 替代方案 / 推荐方案 / 关键决策均已记录
+- decision-grilling-protocol：用户问题未超预算；每问包含推荐答案；能自查的问题未打扰用户
+- implementation-planning-protocol：plan 简表、implementation-detail、test-scenarios 三件套一致，无占位符
+```
+
+该自检写入 execution-log；关键结论写入 events.ndjson。

package/resources/harness/java/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/java/harness-review/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: harness-review
+description: "6维度代码审查（架构/安全/规范/兼容/测试/性能），对照.claude/rules/和测试场景表，在隔离上下文运行。使用场景：代码审查、提交前检查、合并评审"
+argument-hint: "变更名或留空自动检测"
+effort: high
+allowed-tools: [Read, Write, Edit, Glob, Grep, Agent, 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-review — 代码审查
+
+## Purpose
+
+对 git diff 进行6维度审查，对照项目规则和测试场景表，输出分级报告。**审查结果仅供参考，默认不阻塞后续 submit/archive 流程。**
+
+## When to Use
+
+使用此 Skill 当：
+- 代码变更完成后需要审查
+- 提交前需要质量检查
+- 合并评审时需要系统性检查
+- 用户说"审查代码"、"review"、"检查代码质量"
+
+## Inputs
+
+- `$ARGUMENTS`：变更名（可选，留空时自动扫描 `.harness/changes/*/plans/` 确定）
+- 相关文件：`.harness/changes/*/plans/*-plan.md`、`.claude/rules/`、测试场景表
+
+## 前置条件
+
+- `.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` → 审查主目录变更
+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 边界保持最新。