hunter-harness 0.1.2 → 0.2.0

package/resources/harness/bundles/general/cursor/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` 事件）

package/resources/harness/bundles/general/cursor/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。