hunter-harness 0.1.3 → 0.2.1

package/resources/harness/general/harness-plan/checklist.md

@@ -1,243 +0,0 @@
----
-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/general/harness-plan/protocols.md

@@ -1,124 +0,0 @@
----
-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。