hunter-harness 0.1.0

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

@@ -0,0 +1,210 @@
+---
+description: harness-package 的Maven打包参数速查、增量vs全量对比、常见问题处理和报告格式示例。仅在需要参考参数细节或处理问题时读取。
+---
+
+# harness-package 参考 — 参数、问题与格式
+
+## Maven 打包参数速查
+
+| 参数 | 说明 | 示例 |
+|------|------|------|
+| `-pl <modules>` | 指定构建模块列表（逗号分隔） | `-pl module-a,module-b/sub-b` |
+| `-am` | 同时构建指定模块的上游依赖（Also Make） | `-pl module-a -am` |
+| `-amd` | 同时构建依赖指定模块的下游模块（Also Make Dependents） | `-pl module-a -amd` |
+| `-DskipTests` | 跳过测试执行（**ledger 有效时默认使用**，复用 test 阶段验证） | `mvn package -DskipTests` |
+| `-Dmaven.test.skip=true` | 跳过测试编译和执行（更激进，连测试代码都不编译） | 不推荐使用 |
+| `-T 4` | 并行构建，4个线程 | `mvn package -T 4` |
+| `-o` | 离线模式（不从远程仓库下载） | `mvn package -o` |
+| `-DfinalName=<name>` | 指定最终产物名称 | `-DfinalName=my-app` |
+| `--batch-mode` | 非交互模式（CI 场景） | `mvn package --batch-mode` |
+
+## 可选配置（package 时序与测试策略）
+
+在 `.harness/config/harness-test-config.md` 中可配置 package 行为：
+
+```yaml
+package:
+  preferred-order: after-submit   # 默认：package 在 submit 之后运行
+  allow-before-submit: true       # 允许发版前打包（submit 之前）；false 时 package 启动检查 submit 是否已运行
+  reuse-ledger-tests: true        # 默认：ledger 有效时用 -DskipTests 复用 test 阶段验证
+  force-with-tests: false         # 强制带测试打包（等同 package-with-tests）
+```
+
+- `preferred-order: after-submit`：package 的 `baseCommit` 取 submit 日志的 final pushed hash
+- `allow-before-submit: true`：允许在 submit 之前运行 package，此时 `baseCommit` 为当前 HEAD；submit 后若 pull 引入新提交，须重新 package
+- `reuse-ledger-tests: true`：ledger 有效时默认 `-DskipTests`，报告标明复用来源；ledger 无效时自动改为带测试打包
+
+> 未配置时使用上述默认值。
+
+## 增量 vs 全量对比
+
+| 维度 | 增量打包 | 全量打包 |
+|------|----------|----------|
+| **命令** | `mvn package -pl <modules> -am` | `mvn package` |
+| **适用场景** | 日常发版、局部变更、迭代开发 | 首次发版、重大重构、不确定依赖关系 |
+| **构建范围** | 变更模块 + 上游依赖 | 所有模块 |
+| **构建速度** | 快（只构建相关模块） | 慢（全量构建） |
+| **风险** | 可能遗漏间接依赖 | 无遗漏风险 |
+| **产物数量** | 只产出相关模块的 jar/war | 产出所有模块的 jar/war |
+| **推荐优先级** | 首选（默认模式） | 增量失败时的降级方案 |
+
+**何时选择全量**：
+- 首次部署或项目初始化
+- pom.xml 结构发生重大变更
+- 依赖关系不确定或增量打包出现版本冲突
+- 用户明确要求全量构建
+
+## 常见问题处理
+
+| 问题 | 原因 | 处理方法 |
+|------|------|----------|
+| **合并冲突** | 他人代码与本次变更有重叠 | 停止打包流程，提示用户手动解决冲突后重新运行 |
+| **合并后编译失败** | 他人代码引入新依赖或修改公共接口 | 分析错误是否与本次变更相关，相关则修复，无关则记录并询问用户 |
+| **合并后测试失败** | 他人代码破坏了本次功能 | 记录冲突点，提示用户协调解决 |
+| **打包失败：找不到依赖** | 上游模块未安装到本地仓库 | 先执行 `mvn install -pl <upstream> -am`，再打包 |
+| **打包失败：版本冲突** | 同一依赖多个版本，SNAPSHOT 冲突 | 检查 pom.xml 版本号，统一版本；或用 `-DallowConflictingSnapshots=true` |
+| **打包失败：编译错误** | 变更文件有语法错误或类型不匹配 | 先执行 `mvn compile` 定位错误，修复后重新打包 |
+| **打包失败：测试失败** | 单元测试或集成测试报错 | 检查测试日志，修复测试或用户确认后加 `-DskipTests` |
+| **打包失败：离线依赖缺失** | `-o` 模式下本地仓库缺少依赖 | 去掉 `-o`，加 `-nsu` 联网下载（见 `.claude/rules/maven-offline.md`） |
+| **target/ 目录不存在** | 模块未被打包命令包含 | 检查 `-pl` 参数是否遗漏该模块，或改用全量打包 |
+| **增量打包遗漏产物** | `-am` 未包含足够的上游模块 | 检查依赖链，补充遗漏模块到 `-pl` 列表，或改用全量打包 |
+| **parent-pom 模块无 jar 产物** | 父 pom 模块只做依赖管理，不生成 jar | 正常行为，状态标记为 SKIPPED |
+| **war 包过大** | 包含了不必要的依赖或资源 | 检查 pom.xml 的依赖范围（scope），排除 provided/test 依赖 |
+| **并行构建报错** | 模块间存在循环依赖或线程竞争 | 去掉 `-T` 参数，改用串行构建 |
+
+**依赖缺失的典型解决流程**：
+
+```powershell
+# 1. 先安装所有上游依赖到本地仓库
+powershell.exe -Command "mvn install -pl module-common,module-parent -am"
+
+# 2. 再对变更模块执行增量打包
+powershell.exe -Command "mvn package -pl module-a -am"
+```
+
+## 报告格式示例
+
+```markdown
+---
+change-name: user-auth-feature
+package-mode: incremental
+generated-at: 2026-06-17 14:30:00
+base-commit: abc1234
+base-commit-source: submit final pushed hash
+maven-command: mvn package -pl module-auth,module-api -am -DskipTests
+tests-executed: false
+tests-reused-from: unitTest+apiTest
+ledger-diff-hash: sha256:...
+---
+
+# 打包报告 — user-auth-feature
+
+## 打包概要
+
+| 项目 | 值 |
+|------|-----|
+| 变更名 | user-auth-feature |
+| 打包模式 | 增量（-pl + -am） |
+| Maven 命令 | `mvn package -pl module-auth,module-api -am -DskipTests` |
+| 基准 commit | abc1234（来源：submit final pushed hash） |
+| 开始时间 | 2026-06-17 14:25:00 |
+| 结束时间 | 2026-06-17 14:30:00 |
+| 构建耗时 | 5分0秒 |
+| 构建结果 | SUCCESS |
+
+## 测试执行策略
+
+- package 本次是否执行 tests: **否**（`-DskipTests`）
+- 复用来源: verification-ledger 的 `unitTest` + `apiTest`（status=OK）
+- ledger diffHash: sha256:...
+- 复用成立条件: diffHash 一致 + submit 后无新提交 + 无行为性 post-test 修改
+- 若 ledger 无效: 改为"是（带测试打包）"并说明原因（test 未跑 / diffHash 不一致 / submit 后有新提交 / 行为性 post-test 修改）
+
+## 变更模块
+
+### 直接变更模块 (2 个)
+
+| 模块 | 变更文件数 | 变更类型 |
+|------|-----------|----------|
+| module-auth | 5 | 新增+修改 |
+| module-api | 2 | 修改 |
+
+### 依赖链模块
+
+| 类型 | 模块 |
+|------|------|
+| 上游依赖 (-am) | parent-pom, module-common |
+| 下游依赖 (-amd) | 未包含 |
+
+## 产物清单
+
+| 模块 | 产物文件名 | 相对路径 | 大小 | 状态 |
+|------|-----------|----------|------|------|
+| module-auth | auth-service-1.0.0.jar | module-auth/target/auth-service-1.0.0.jar | 12.5 MB | SUCCESS |
+| module-api | api-model-1.0.0.jar | module-api/target/api-model-1.0.0.jar | 3.2 MB | SUCCESS |
+| module-common | common-utils-1.0.0.jar | module-common/target/common-utils-1.0.0.jar | 8.1 MB | SUCCESS |
+| parent-pom | — | — | — | SKIPPED |
+
+**产物总计**: 3 个 jar, 总大小 23.8 MB
+
+## 构建日志摘要
+
+```
+[INFO] Reactor Build Order:
+  parent-pom  .................................. SKIPPED
+  module-common  ................................ SUCCESS [8.1s]
+  module-api  ................................... SUCCESS [3.2s]
+  module-auth  .................................. SUCCESS [12.5s]
+[INFO] BUILD SUCCESS
+```
+
+## 部署建议
+
+- 部署顺序：common-utils → api-model → auth-service（按依赖顺序）
+- 注意：auth-service 依赖 common-utils 和 api-model，确保目标环境已有这两个依赖
+```
+
+## 变更模块识别方法
+
+### 方法 1：git diff + pom.xml 映射（推荐）
+
+```powershell
+# 1. 获取基准 commit
+powershell.exe -Command "git -C '<项目路径>' merge-base HEAD origin/master"
+
+# 2. 获取变更文件列表
+powershell.exe -Command "git -C '<项目路径>' diff <base-commit> --name-only"
+
+# 3. 对每个变更文件，向上查找 pom.xml 所在目录
+#    变更文件: module-a/src/main/java/com/example/Service.java
+#    → pom.xml 在: module-a/pom.xml
+#    → 模块路径: module-a
+```
+
+### 方法 2：git diff + Maven Reactor 映射
+
+```powershell
+# 1. 获取变更文件列表
+powershell.exe -Command "git -C '<项目路径>' diff <base-commit> --name-only"
+
+# 2. 对变更目录执行 Maven 列出模块
+powershell.exe -Command "mvn -f <项目路径>/pom.xml help:active-profiles -pl :<module-artifactId>"
+```
+
+### 依赖链识别
+
+**上游依赖（-am）**：变更模块 pom.xml 中 `<dependencies>` 引用的同项目模块，由 Maven `-am` 参数自动处理。
+
+**下游依赖（-amd）**：需要扫描其他模块的 pom.xml，找出 `<dependency>` 中引用了变更模块 `<groupId>:<artifactId>` 的模块：
+
+```powershell
+# 扫描所有子模块 pom.xml 中对变更模块的引用（使用 Grep 工具更高效）
+Grep("<artifactId>module-a</artifactId>", "<项目路径>/", glob="**/pom.xml")
+```
+
+### 边界情况
+
+- **根 pom.xml 变更**：属于父项目，需全量打包
+- **多模块同一变更**：合并到 `-pl` 列表，用逗号分隔
+- **无变更文件**：提示用户确认是否需要全量打包
+- **新增模块**：pom.xml 本身是新增文件，需全量打包确保 Reactor 顺序正确

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

@@ -0,0 +1,127 @@
+---
+name: harness-plan
+description: "将需求转化为设计文档+实施计划+完整测试场景表，必须在编码前完成。使用场景：需求分析、feature plan、技术方案设计、实现方案规划"
+argument-hint: "需求描述 | --adversarial"
+effort: high
+allowed-tools: [Read, Glob, Grep, Edit, Write, 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 *)
+---
+<!-- generated by harness_deploy.py; core=8917528f7dfdc5ca; overlay=java; do not edit -->
+# harness-plan — 需求规划
+
+## Purpose
+
+需求 → 设计文档 → 任务拆分 → 测试场景表（编码/测试唯一真相源）。存在 `.harness/archive/` 或 `.harness/knowledge/` 时须先 `harness-knowledge-query`。
+
+## When to Use
+
+`/harness-plan`、新功能设计、技术方案、测试场景表规划。
+
+## 统一读取协议
+
+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]]
+
+## 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 创建/更新）。
+
+## 原生规划协议
+
+内化为 `protocols.md`：`clarification-protocol`、`decision-grilling-protocol`、`implementation-planning-protocol`。不运行时调用 Superpowers/grill-me。
+
+## Subagent 委派
+
+- **阶段 3 探索**：`check-agents --agent harness-explorer` → 可用则委派，否则主会话探索；无效返回不 retry
+- **阶段 7.5**：仅 `--adversarial`；`check-agents --agent harness-evaluator` → `reports/plan-review/`
+
+## Workflow 概要
+
+| 阶段 | 动作 |
+|------|------|
+| 0 | git status；脏工作区 → baseline 隔离 + `decision`，不询问 |
+| 0.5 | `harness-knowledge-query`（失败记 `issue`） |
+| 1 | 自动生成 change-name + 初始化 logs/events |
+| 2–3 | 代码探索 + 需求澄清（高风险 → 交互白名单 ②） |
+| 4 | **设计审批包** AskUserQuestion → 写 `spec/*-design.md` + `meta/worktree.json` |
+| 5–6 | plan + implementation-detail + test-scenarios → `plans/` |
+| 7.5 | 仅 `--adversarial` 对抗评审 |
+| 8 | 产物完整性必检 → `checklist.md` |
+
+change-name 范围变更 → 提示重命名或记 🟡WARN（→ `reference.md`）
+
+## 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]]
+
+## 关键规则
+
+| 规则 | 要点 |
+|------|------|
+| 产物路径 | 只写 `.harness/changes/<cn>/`；禁止 superpowers 输入 |
+| 设计审批包 | 一次 AskUserQuestion 含 worktree（读 `harness.json` `defaultWorktree`） |
+| 阶段 8 | spec/plan/detail/scenarios/worktree.json/logs/events 缺一不可 → ❌FAIL |
+| Plan 结束 | **禁止**询问执行模式；只提示 `/harness-run` |
+| 知识查询 | 0.5 失败不得假装已读历史 |
+| 协议 | sensitive-info / evidence-based-reporting / state-layout |
+
+产出物表、frontmatter、legacy 兼容、结束输出模板 → `reference.md`
+
+## 渐进披露
+
+- **Read `checklist.md`** — 阶段检查与覆盖表
+- **Read `protocols.md`** — 阶段 4/6 原生协议
+- **Read `reference.md`** — 模板与 worktree JSON
+
+## 交互白名单
+
+1. **设计审批包**（阶段 4）：设计 + 场景表 + worktree + change-name
+2. **decision-grilling**（阶段 3 澄清）：高风险业务裁决（一次一问）
+
+## 执行日志
+
+`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/java/harness-plan/checklist.md

@@ -0,0 +1,243 @@
+---
+description: harness-plan 的阶段检查清单和覆盖检查列表。仅在执行完整需求规划时读取。
+---
+
+# harness-plan 检查清单
+
+## 阶段 0：工作区变更检查 ⚠️ 强制检查
+
+> 有未提交业务变更（排除 `.harness/`）→ **默认 baseline 隔离**，append `decision` 事件，**不 AskUserQuestion**，继续规划。PowerShell 失败 → ❌ 停止。
+
+**固定命令**：`powershell.exe -Command "git -C '<项目路径>' status --porcelain"`
+
+**判定**：stdout 为空 → ✅ 继续；stdout 非空 → baseline 隔离 + `decision`（note 含变更文件列表）；Bash 被拒 → PowerShell 重试。
+
+## 阶段 2：Worktree 决策（并入设计审批包）
+
+> worktree 不再单独询问。阶段 5 **设计审批包** 一次 AskUserQuestion 含 worktree 选项（推荐值读 `harness.json` `defaultWorktree`）。确认后写入 `meta/worktree.json`。
+
+- [ ] 审批包确认后写入 worktree.json（`requested` true/false）
+- [ ] 阶段 8 检查 worktree.json 存在
+
+## 阶段 3：代码探索确认（含 Agent/CodeGraph 降级记录）
+
+阶段 3 执行完成后，确认以下事项：
+
+```
+□ 是通过 Agent 工具委派 subagent 执行的（不是主会话直接调用 codegraph）
+□ subagent 返回了结构化设计概要（涉及模块、接口变更、关键决策）
+□ 委派前已运行 `harness_preflight.py check-agents --agent harness-explorer`
+□ `usable=false` 或未返回有效输出 → 主会话探索，**不 retry 委派**
+□ 主会话未被代码探索的中间结果污染
+□ 在执行日志中记录了 Agent 调用状态：
+  - 是否成功调用
+  - 使用的 agent 名称
+  - 是否只读
+  - 子代理实际 tool uses 计数
+  - 返回的核心结论
+```
+
+> 如果 Agent 工具不可用，或子代理被委派但未返回有效输出（0 tool uses / 空返回 / 仅 "Done"），必须显式降级并记录：
+> - 在执行日志中写明降级原因：🟡 阶段3降级：Agent 不可用 / 子代理未返回有效输出，改为主会话只读探索
+> - 主会话直接使用 codegraph MCP 工具（`mcp__codegraph__codegraph_explore`）和 Read 探索代码（只读，不执行写操作）
+> - 不得在主会话中执行任何写操作
+> - CodeGraph 如通过 MCP 调用，必须优先用 MCP 工具，不允许通过普通 Bash 调 codegraph 命令
+> - 禁止把子代理未经工具验证的文本结论当作"详尽报告"或代码证据采纳
+
+## 阶段 5：设计审批包 ⚠️ 强制阻断（一次 AskUserQuestion）
+
+> 合并原「设计审核 + worktree + 场景表预览 + change-name」。推荐 worktree 读 `harness.json` `defaultWorktree`。
+
+**展示内容**：
+
+1. 设计摘要 + 关键证据 + 风险 + 变更清单
+2. 测试场景表摘要 + 8 维度覆盖检查
+3. worktree 选项（是/否，含推荐理由）
+4. change-name（自动生成，可修改）
+5. 确认进入任务拆分
+
+确认后写入 `spec/<change>-design.md`（含 frontmatter）和 `meta/worktree.json`。
+
+设计文档必须包含 frontmatter：
+```yaml
+---
+change-name: <change-name>
+created: YYYY-MM-DD HH:mm
+status: approved
+source: harness-plan
+---
+```
+
+展示可审核包后，使用 `AskUserQuestion` 询问用户：
+- **确认**：设计方向正确，继续任务拆分
+- **修改**：某个部分需要调整，修改后再审核
+- **取消**：方向不对，回到需求澄清阶段
+
+### 设计文档自审清单
+
+写完设计文档后，用以下清单自检，**并将自审结果展示给用户**：
+
+```
+□ 无"TBD"/"TODO"/未完成章节
+□ 各节之间无矛盾
+□ 范围聚焦，无不相关内容
+□ 无歧义需求（可被两种方式解读的，已选一种并明确说明）
+□ 自审结果已展示给用户
+```
+
+> 展示格式示例：
+> ```
+> ### 设计文档自审
+> - ✅ 无 TBD/TODO/未完成章节
+> - ✅ 各节之间无矛盾
+> - ✅ 范围聚焦，无不相关内容
+> - ⚠️ 第3.2节"枚举删除"与第4节变更清单中"标记@Deprecated"有矛盾，已修正为"删除"
+> ```
+
+## 测试场景覆盖检查表（8 维度覆盖检查表，强制输出）
+
+> 注意：覆盖检查表是 8 维度，与 4 维度场景表（单元/接口/数据兼容/集成）是两个不同制品。
+
+生成场景表后，逐项确认是否覆盖，**必须输出覆盖检查表展示给用户确认**。未覆盖的维度必须标记为缺口（⚠️ 缺口），不得全部标记为 ✅：
+
+| 覆盖维度 | 状态 | 说明 |
+|---|---|---|
+| 正常路径 | ✅/🟡/❌ | 每个接口 ≥ 1 个正常场景 |
+| 参数校验 | ✅/🟡/❌ | 必填缺失、格式非法、类型错误 |
+| 业务规则 | ✅/🟡/❌ | 唯一性、范围约束、状态机 |
+| 权限/组织边界 | ✅/🟡/❌ | 无权限、跨组织、角色限制 |
+| 数据兼容 | ✅/🟡/❌ | 旧数据无新字段 |
+| 错误码 | ✅/🟡/❌ | 每个异常对应明确错误码 |
+| 集成影响 | ✅/🟡/❌ | 跨模块调用、端到端流程 |
+| 并发/幂等 | ✅/🟡/❌ | 重复提交、并发修改 |
+
+> 展示格式示例：
+> ```
+> ### 场景覆盖检查表
+> | 覆盖维度 | 状态 | 说明 |
+> |---|---|---|
+> | 正常路径 | ✅ | 5 个接口各 ≥ 1 个正常场景 |
+> | 参数校验 | ✅ | 必填缺失、格式非法已覆盖 |
+> | 业务规则 | ✅ | 唯一性、状态机已覆盖 |
+> | 权限/组织边界 | 🟡 | ⚠️ 缺口：未覆盖跨组织场景，需补充 |
+> | 数据兼容 | ✅ | 旧数据 scene_code 迁移场景已覆盖 |
+> | 错误码 | ✅ | 3 个错误码均有对应场景 |
+> | 集成影响 | 🟡 | ⚠️ 缺口：未覆盖端到端流程，需部署后验证 |
+> | 并发/幂等 | ❌ | ⚠️ 缺口：未覆盖重复提交场景，需补充 |
+> ```
+
+## 阶段 7.5：计划对抗评审（可选）确认
+
+> 仅在用户选择启用对抗评审时执行本节检查。默认不启用（高风险构建 auth/支付/迁移/并发 才启用）。
+
+阶段 7.5 执行完成后，确认以下事项：
+
+```
+□ 已用 **设计审批包** 一次 AskUserQuestion（设计 + 场景表摘要 + worktree + change-name）
+□ **未**单独询问 worktree 或对抗评审（对抗评审仅 `--adversarial`）
+□ 用户同意后，已用 Agent 工具委派 harness-evaluator（haiku, context:fork, plan 模式只读, maxTurns:8）
+□ 已用 context:fork 隔离上下文（evaluator 未参与规划，破除确认偏误）
+□ 已校验子代理 tool uses > 0（0/空/Done 视为未返回有效输出，已降级为主会话自审并记录）
+□ evaluator 返回了 VERDICT(APPROVED/REVISE) + 结构化问题清单（RED/YELLOW）
+□ 评审报告已写入 .harness/changes/<change-name>/reports/plan-review/plan-review-YYYYMMDD-HHmm.md
+□ VERDICT 和问题清单已展示给用户（不得仅记"已评审"）
+□ REVISE 时已询问用户是否修订；修订后可选再审
+□ 评审为参考性，未阻塞阶段8
+□ 执行日志记录了 evaluator 调用状态（委派成功/降级原因）+ VERDICT 摘要
+□ 如为主会话自审降级，已标注"⚠️ 同会话自审，回音壁风险"
+```
+
+## 原生规划协议检查
+
+### 阶段 4：clarification + decision-grilling
+
+阶段 4 执行完成后，确认以下事项：
+
+```
+□ 已读取 protocols.md，并按 clarification-protocol / decision-grilling-protocol 执行
+□ 输入包含需求摘要 + 阶段0.5 context pack（如有）+ 阶段3代码探索结果 + 项目架构约束
+□ 已在 execution-log 中记录五类输出：风险识别 / 复用机会 / 替代方案 / 推荐方案 / 关键决策
+□ 已叠加项目架构约束（分层规范、数据模型、接口规范）
+□ 需求澄清结论已写入 .harness/changes/<change-name>/logs/execution-log.md，并在 events.ndjson 记录 decision
+□ 用户问题未超预算：普通需求 1-3 问，高风险需求 5-7 问；无必须裁决事项时 0 问
+□ 提问遵循"一次一问、等答再继续"；能由 context pack / 阶段3代码探索 / CodeGraph 自答的问题已自答，未打扰用户
+□ 每个需要用户决策的问题，AI 先给出了推荐答案、理由和取舍，用户仅确认或修正
+□ 高风险/业务语义决策（范围、权限、安全、支付、迁移、删除、API契约、用户可见行为）已显式等待用户确认
+```
+
+> 不再检查 Superpowers brainstorming 是否安装或调用；阶段 4 是 harness 原生协议，不存在外部 skill 降级分支。
+
+### 阶段 6：implementation-planning
+
+阶段 6 执行完成后，确认以下事项：
+
+```
+□ 已读取 protocols.md，并按 implementation-planning-protocol 执行
+□ 输入为阶段5已审核设计文档
+□ 已生成基础任务列表，并在 execution-log 记录任务拆分摘要
+□ 已叠加项目层序依赖（数据/契约→业务层→接口层）
+□ 已生成 4 维度场景表（单元/接口/数据兼容/集成）
+□ 已确定变更名（kebab-case）
+□ 产物已写入 .harness/changes/<change-name>/plans/：
+  - <change-name>-plan.md（简洁任务表）
+  - <change-name>-implementation-detail.md（自适应详细执行参考）
+  - <change-name>-test-scenarios.md（测试场景表）
+□ implementation-detail.md 按复杂度自适应：简单任务不过度展开，复杂任务写清接口/数据/顺序/风险/测试策略
+□ plan / implementation-detail / test-scenarios 三件套互相引用一致，无 TBD/TODO/空泛占位
+```
+
+> 不再检查 Superpowers writing-plans 是否安装或调用；阶段 6 是 harness 原生协议，不存在 `docs/superpowers/` 同步分支。
+
+## 阶段 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
+□ 未将 docs/superpowers/ 列为最终产物路径
+```
+
+### Legacy Frontmatter 兼容
+
+```
+□ 已确认 plan 文件 frontmatter 存在
+□ 如不存在 → 已从路径推断 change-name 和 plan-name
+□ 如不存在 → 执行日志中已标记 🟡 legacy-plan
+□ 旧 plan 不因 frontmatter 缺失而 FAIL
+```
+
+## 关键原则
+
+- **产物路径唯一性**：`.harness/changes/<change-name>/` 是唯一真相源，plan 产物必须直接写入此目录
+- **原生规划协议**：阶段 4/6 使用 clarification、decision-grilling、implementation-planning 三段内置协议，不运行时依赖 Superpowers/grill-me/writing-plans
+- **阶段 2 是强制阻断检查点**——必须停下来问用户，收到回复后才能继续。不要跳过
+- 代码探索只读不写——这个阶段的目标是理解，不是修改
+- 场景表是后续所有步骤的真相源——宁可多花时间打磨，不要草草了事
+- 如果需求不明确，优先提问而不是猜测后继续设计
+- 任务拆分粒度按复杂度调整——plan 简表保持可追踪，implementation-detail 按风险和复杂度自适应展开
+- **Plan 结束禁止询问执行模式**：Subagent-Driven / Inline Execution 属于 /harness-run 阶段
+
+## 事件记录（前置规则）
+
+- [ ] 确定 change-name 后立即 append `phase.start` 事件；各阶段用 `harness_events.py append` 写入 `decision` / `issue` / `artifact`
+- [ ] 阶段 0 在 change-name 确定前可不写事件；阶段 1 确定 change-name 后必须开始记录
+
+## 需求范围缩减后的 change-name 检查 ⚠️
+
+- [ ] 阶段 4 澄清后，检查最终需求范围是否和 change-name 一致
+- [ ] 如果用户取消某个需求，但 change-name 仍包含该需求关键词，必须建议重命名
+- [ ] 重命名后同步目录名、spec/plan/scenarios 文件名、frontmatter、logs/execution-log、events.ndjson、meta/worktree.json
+- [ ] 如果用户选择不重命名，记录 🟡WARN 到 events.ndjson（`issue` 或 `decision` 事件）