@hunter-harness/workflow-harness 0.4.0 → 0.4.1

package/harness/bundles/general/pi/harness-plan/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: harness-plan
+description: 将需求转化为设计文档+实施计划+完整测试场景表，必须在编码前完成。仅当用户显式调用 /harness-plan 或明确要求进入
+  Harness 规划阶段时使用；不得因用户描述需求就自动触发。
+---
+<!-- generated by harness_deploy.py; core=ec59ac2389d9dce9; overlay=none; agent=pi; do not edit -->
+# harness-plan — 需求规划
+
+## Purpose
+
+确定 change 后必须运行 `python <skills-root>/scripts/harness_gate.py classify --change <id> --stage plan --json`，并把脚本返回的 risk tier、默认阶段、条件阶段和必需验证写入计划；不得凭模型印象另建风险分级。
+
+需求 → 设计文档 → 任务拆分 → 测试场景表（编码/测试唯一真相源）。项目已绑定远端平台时，阶段 1 只执行下表中的远端查询命令；远端不可用则记录 issue 并继续，不做本地回退。
+
+## When to Use
+
+仅当用户显式调用 `/harness-plan`（或明确说"用 harness 规划这个需求"）时执行。用户只是描述需求、提问或讨论方案时，**不得**自动进入本 skill。
+
+**单阶段原则**：本 skill 只负责 plan 阶段。plan finalize + verify 完成后必须停止并交还用户，仅提示 `plannedPhases` 中的真实下一阶段；禁止自动调用其他阶段 skill。
+
+## 统一读取协议
+
+0. **脚本在 `<skills-root>/scripts/` 共享，不在每个 skill 子目录下** — 实际形态是 `.codebuddy/skills/scripts/harness_*.py`（`.claude`/`.cursor`/`.codex` 同理），**没有** `.../skills/harness-<phase>/scripts/`。plan、run/test、archive 三份执行日志里都先猜成后者、报 `No such file` 再靠 Search 找回来；照第一种写法直接用
+1. **`.harness/changes/<change-name>/` 是唯一真相源** — 所有输入从该目录读取，产物写入对应子目录
+2. **change-name 优先从 frontmatter 读取** — `plans/*-design.md`、`spec/*-design.md`、`plans/*-plan.md` 的 YAML `change-name`
+3. **frontmatter 缺失时兼容旧格式** — 从路径推断，标记 `🟡 legacy-plan`，不失败
+4. **design** — 设计真相源按序取第一个存在的：`plans/<change>-design.md`（v2 发布产物，哈希绑定）→ `spec/<change>-design.md`（legacy 手写）。两份**同时存在**时以 `plans/` 为准，并记 `🟡 WARN 设计文档双份`——v2 发布的那份才受完整性门禁保护，读手写的那份等于绕过校验
+5. **plan** — 任务真相源：`plans/<change>-plan.md`
+6. **implementation-detail** — 自适应执行参考；legacy 缺失 🟡WARN，不阻断
+7. **test-scenarios** — 测试真相源：`plans/<change>-test-scenarios.md`
+8. **禁止读取 `docs/superpowers/` 作为正式输入** — 旧草稿仅人工线索
+9. **每个 skill 边界只刷新一次状态快照** — 先运行 `python <skills-root>/scripts/harness_state.py capture --project . --change-dir ".harness/changes/<change-name>" --json`。首次 Plan 捕获时，脚本把当时的 Git HEAD 写入不可变 `changeBase`；后续阶段只刷新 `git.head` 与各段指纹，不得用当前 HEAD 覆盖 `changeBase`。只有迁移旧 change 且已能证明真实计划起点时，才在首次补录时传 `--base <baseCommit>`。`changedSegments=[]` 时复用已有 profile/rules/map/change/code 指纹，不再重复跑全量 `harness-sync` 或代码库扫描。`knowledge` 段仅为兼容空段，知识始终按需远端查询；快照不能替代源码读取和验证门禁。
+
+状态目录分层：新路径优先，旧路径兼容 → [[../protocols/state-layout-protocol.md|state-layout-protocol]]
+> 片段：read-protocol · plan 额外写 `meta/worktree.json`、`meta/change-context.json`
+
+## Worktree 门禁
+
+读取 `meta/worktree.json`（兼容旧路径 `worktree.json`）：
+
+| 条件 | 行为 |
+|------|------|
+| `requested=false` | 主目录执行 |
+| `requested=true` + path 存在 | 切换 worktree 执行 |
+| `requested=true` + path 不存在 | **必须创建**（run）或 **停止**（test/review/submit） |
+
+**严禁** `requested=true` 时静默回主目录。创建失败 → 停止或 blocking user confirmation 降级（须 🟡WARN + 用户确认）。
+
+**状态与代码分离**：代码/编译/测试在 `worktreeRoot`；`stateDir`（logs/events/ledger/reports）写回 `.harness/changes/<change-name>/`。
+
+创建命令与 JSON 模板 → 各 skill `reference.md`（plan 写决策，run 创建/更新）。
+> 片段：worktree-gate · plan 在**设计审批包**写入 `worktree.json`（模板 → `reference.md`）
+
+## 原生规划协议
+
+内化为 `protocols.md`：`clarification-protocol`、`decision-grilling-protocol`、`implementation-planning-protocol`。不运行时调用 Superpowers/grill-me。
+
+<!-- @section-id plan.delegate -->
+## 执行路由（inline 优先）
+
+- **阶段 3 探索默认 inline**：主会话直接使用 CodeGraph/Read，简单修复和常规跨文件变更不得为“隔离上下文”额外启动 agent。
+- **仅高复杂度探索考虑委派**：涉及多个独立模块、陌生大型代码库或可并行的独立调查时，才执行一次 `python <skills-root>/scripts/harness_preflight.py check-agents --skills-root <skills-root> --agent harness-explorer --json`。只有 `executionMode=delegated` 才委派；`executionMode=inline` 是正常路径，静默继续；`unavailable` 只记录安装问题后 inline。
+- **阶段 7.5 evaluator**：仅 `--adversarial` 或 auth/支付/迁移/并发等高风险规划启用；需要固定 agent 时才预检。无论预检 inline、spawn 失败、空返回或只有元数据，都立即由主会话完成同一对抗检查，`fallbackPolicy=inline-no-retry`。
+- 日志记录 `executionMode=inline|delegated`；只有真实定义损坏或 spawn 失败才记 issue。正常 inline 不得显示“subagent 不可用”告警。
+
+## Workflow 概要
+
+| 阶段 | 动作 |
+|------|------|
+| 0 | git status；脏工作区 → baseline 隔离 + `decision`，不询问。环境体检并入 0.5 的引导命令，不再单独跑 doctor |
+| 0.5 | 先定英文 `change-name`（kebab-case，`^[a-z0-9]+(-[a-z0-9]+)*$`）与一次性中文展示标题（建议 6～24 个可见字符，保留必要产品名），然后**一条命令完成引导**：<br>`python <skills-root>/scripts/harness_context.py bootstrap-plan --project . --change <cn> --executor <tool> --title "<中文标题>" --json`<br>它按序做完 doctor → 建 change 骨架 → prepare → state capture（首次把当时 HEAD 固定为不可变 `changeBase`）→ classify（落 `meta/gate-policy.json`）→ 生成合规 `plan_<uuid>` run-id 并追加 `phase.start`，返回紧凑摘要：`runId`/`attempt`/`tier`/`defaultPhases`/`conditionalPhases`/`requiredValidations`/`changeBase`/`head`/`executionRoot`。**重跑复用同一 run-id、不重复写 `phase.start`**（换 run-id 会让 finalize 按生命周期身份 fail-closed）。finalizer 必须复用该 `runId`/`attempt` |
+| 0.5b | 仅在引导失败需要单步排查时用等价分解——**每条的参数都是必填，少一个就是白跑一轮**：<br>`harness_runtime.py doctor --project . --change-dir ".harness/changes/<cn>" --agent <claude-code\|codebuddy\|codex\|cursor> --json`<br>`harness_context.py prepare --project . --change <cn> --phase plan --executor <tool> --title "<中文标题>" --json`<br>`harness_state.py capture --project . --change-dir ".harness/changes/<cn>" --json`<br>`harness_gate.py classify --change <cn> --stage plan --json`<br>`harness_events.py append --change-dir ".harness/changes/<cn>" --phase plan --type phase.start --run-id plan_<uuid> --attempt 1`<br>⚠️ `--change-dir` 一律是 `.harness/changes/<cn>`（状态目录），**不是** prepare 返回的 `executionRoot`（代码执行根，无 worktree 时等于项目根）——填错会把 gate-policy/events 写到项目根 |
+| 0.6 | 用引导返回的 `tier`/`defaultPhases`/`requiredValidations` 生成 `plannedPhases`，向用户用中文说明可选阶段；确认后运行 `harness_context.py configure-plan --project . --change <cn> --phases "plan,execute,...,archive" --operator <tool> --reason "<中文原因>" --json`。无 Git 或不需要提交时不得加入 `submit`；快速迭代默认 `plan,execute,archive`。省略项由脚本写入 `skippedPhases`，不得伪造阶段事件。<br>⚠️ 无风险信号时 classify 默认 `standard`（`plan,execute,submit,archive` + compile/unitTest/unitTestFull），**不再默认 full**。需要 review 阶段与 apiTest 的高风险变更，在计划文档里写「风险等级: full」或用 `classify --tier-override full` 显式升档 |
+| 1 | 直接执行一次 `npx hunter-harness knowledge query "<用户需求原文>" --limit 10 --json`。这是唯一执行入口，不扫描技能目录、不查找其他脚本；失败记 `issue` 并继续，不建立本地索引或离线回退 |
+| 2 | 歧义优先检查 + 复杂度分级；先确认会改变实现方向的语义歧义 |
+| 3 | 按复杂度执行有预算的代码探索；简单修复不得扩散到无关模块 |
+| 4 | **设计审批包** blocking user confirmation；确认事件早于 approved 设计文档和 `meta/worktree.json` |
+| 5–6 | **v2（默认）**：任务与场景只沉淀进 `meta/plan-evidence-input.json`（自然输入，字段定稿时点见 `reference.md` 阶段 8 v2 表）；`plans/*.md` 四份由 finalize 派生，**不得手写**——手写的会被派生渲染覆盖，只是白写。|
+| 7.5 | 仅 `--adversarial` 对抗评审 |
+| 8 | **v2 路径（新 change 优先）**：`npx hunter-harness plan evidence-pack --input <meta/plan-evidence-input.json> --output <meta/plan-evidence.json>`，再 `npx hunter-harness plan finalize --input <meta/plan-evidence.json>`；exit 0 且 `code:"PLAN_FINALIZED"` 即发布完成（契约见 `reference.md` 阶段 8 v2 路径）。`risk_signals` 可留空：evidence-pack 按 affected_paths 与 git status 推断信号并与手填取并集；capabilities 由命令探测真实仓库状态，阶段 0.6 的 plannedPhases 会被读取。发布成功后把 `harness_context.py close` 的 `--to-phase` 取 `plannedPhases` 中 plan 的真实后继，不得写死。原子发布、派生清单计数对账、完整生命周期、render → `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]]
+
+## 生成内容语言约定
+
+- sync/ingest 等生成的文档、规则、知识条目、架构说明一律**优先使用中文**撰写（标识符、命令、代码、API 字段名保持原文）
+- 面向平台展示的标题/摘要/正文默认中文；仅当用户明确要求或目标系统强制时才用英文
+> 片段：p0-trust
+
+## 关键规则
+
+| 规则 | 要点 |
+|------|------|
+| 产物路径 | 只写 `.harness/changes/<cn>/`；禁止 superpowers 输入 |
+| 设计真相源 | **v2** = `plans/<cn>-design.md`（finalize 派生、哈希绑定、八 target 之一）；**legacy** = `spec/<cn>-design.md`。同一 change 只有一份设计权威，禁止两处并存导致漂移；下游读取顺序见 `shared/read-protocol.md` |
+| Change 标题 | 首次 Plan 同时确定英文 `change-name` 与中文展示标题；英文名保持目录和机器标识不变，中文标题由 `prepare --title` 持久化，后续阶段只复用、不重新生成 |
+| 阶段计划 | Plan 必须持久化 `plannedPhases`；固定从 plan 开始、以 archive 结束。Execute、Review、Submit、Package、API 文档可按项目策略省略；高风险必需项只能转为“提前结束且不可发布”，不得伪装通过 |
+| 产品边界 | `ownership.productPaths` 必须覆盖计划会修改的源文件、测试文件和构建入口；只写目录前缀或精确文件，禁止 `**` 通配。finalize 前对照任务表补齐，避免归档阶段才发现边界缺口 |
+| 空目录 | 不得为“预留目录”生成 `.gitkeep`；只有产品明确需要跟踪空目录时才能创建，并在计划中说明业务原因 |
+| 设计审批包 | 一次 blocking user confirmation 含 worktree（读 `harness.json` `defaultWorktree`）。必须同时展示 **in_scope 与 out_of_scope 两个列表**——只展示"做什么"会让范围误判活到发布之后，代价是整份计划 republish |
+| 引用即追问 | 需求引用了外部设计文档章节（贴段落、指 `### Bn`、说"之前设计的时候如…"）时，阶段 2 必须确认该章节是否纳入本次范围，落到 in_scope 或 out_of_scope；引用 ≠ 纳入，也 ≠ 排除 |
+| 阶段 8 | 唯一入口：`hunter-harness plan finalize`（证据包 → 八 target + journal committed + plan-events.ndjson）。失败不得手工补终态；历史 legacy 收据只读（`harness_plan_finalize.py verify`） |
+| 发布路径 | **只有 v2**（`plan evidence-pack` → `plan finalize`）；legacy staging/finalize/republish 已于 0.3.0 移除，历史 legacy 收据保持可读（`harness_plan_finalize.py verify`）。v2 的场景契约已补齐 `priority`/`owner_phase` 与可执行测试三元，派生的 `meta/scenario-manifest.json` 能被 execute 门禁与 `harness_ledger.py record` 解包消费，证据闭环走得通。P0/P1 场景必须给全可执行三元（要么整组给全、要么整组省略；省略则 manifest 降为 schemaVersion 1，关门绑不上结构化执行收据） |
+| 发布后改产物 | 改 `meta/plan-evidence-input.json` 后重跑 `plan evidence-pack`（`context.attempt` 递增、`expected_baseline` 置 present 并带上次 manifest 哈希/generation），再 `plan finalize`——新 attempt + 重新派生 manifest 一次完成。**绝不手改 `meta/scenario-manifest.json`**（派生物，手改必致 `ARTIFACT_HASH_DRIFT`）→ `reference.md`「发布后修订计划」 |
+| v2 输入骨架 | 不要猜 `plan-evidence-input.json` 结构：`npx hunter-harness plan evidence-pack --print-template` 给出**一个字不改就能通过 evidence-pack** 的骨架（结构合法；`change_key`/`run_id` 仍须换成真实身份才能 finalize），逐项替换即可。结构不符时命令返回 `PLAN_EVIDENCE_INPUT_INVALID`，带 `field_path` 与 `problems[]`（缺失/多余键、枚举取值）——按 problems 改完重跑；**不得**为找契约去反编译 `dist/bin.js` 或翻 npx 缓存。带不了 `<>` 的占位字段与硬约束清单 → `reference.md` 阶段 8 v2 路径 |
+| Plan 结束 | **禁止**询问执行模式；只提示 `/harness-execute` |
+| 知识查询 | 阶段 1 失败不得假装已读历史，也不得改用本地索引或其他执行入口 |
+| 读命令输出 | `--json` 输出是完整结构，**不得**接 `\| tail -N` / `\| head -N` 后据此判断——截断的 JSON 解析不了，只会逼出一次补读。输出太长时读命令写下的文件（classify → `meta/gate-policy.json`），或用 `bootstrap-plan` 的紧凑摘要 |
+| 歧义优先检查 | 否定、对比、动作对象或范围存在多种合理解释时，最小取证后先给推荐理解并一次一问；确认前不深挖错误方向 |
+| 简单修复探索预算 | 预计不超过 2 个代码文件、且不涉及认证/安全/迁移/并发/API 契约重设时，最多 1 次合并 CodeGraph 查询 + 1 次定向补查、1 个用户澄清问题；无关发现只记非阻断说明 |
+| 精简产物 | 简单修复只保留实现所需的设计、任务、边界和测试；禁止在 spec/plan/detail/scenarios 中重复同一背景和结论 |
+| 测试执行成本 | 场景表必须设计快速反馈层级、预计时长、资源预算、超时和可复用证据；默认先跑受影响测试，再跑模块门禁，候选验证只复用身份一致的全量证据 |
+| state snapshot | Plan 首次 capture 固定不可变 `changeBase`；后续刷新只更新 HEAD 和各段指纹，不得把当前 HEAD 写回为基线。读取 `state-snapshot.json` 了解 project/worktree root、HEAD/base、profile/rules/map/knowledge 指纹；失效由脚本刷新，**不得仅凭缓存跳过代码探索或验证门禁**（design §3.6） |
+| 协议 | 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**（阶段 2/3 澄清）：语义歧义或高风险业务裁决（一次一问）
+
+## 执行日志
+
+`events.ndjson` 为唯一事实源（schema_version 3，兼容读取 v1/v2；`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止用 Write/Edit 直接维护**。直接修改的内容会在 `phase.end` 或 finalize 时被完整重建覆盖，属于数据丢失；需要保留的详情必须进入事件 `note`。结构 → [[../protocols/report-pipeline-protocol.md|report-pipeline-protocol]]
+
+**`phase.start` 由 `harness_gate.py begin` 写，不要再手工追加一次。** 两条同 `run-id` 的
+`phase.start` 会让 `plan finalize` 以 `PHASE_START_DUPLICATE` 卡死，而且手工那次会先触发
+auto-seal、把正在开始的 attempt 封成 `RECOVERED`。要补触发指令说明就带 `--note` 跑 `gate begin`。
+（重复追加现已按 `(phase, run-id)` 判为幂等 no-op，但依赖它不如不写。）
+
+```powershell
+# 阶段开始：gate begin 负责，note 在这里给
+python <skills-root>/scripts/harness_gate.py begin --change-dir ".harness/changes/<change-name>" --phase <phase> --note "<触发指令>"
+# 阶段中的其他事件才用 append
+python <skills-root>/scripts/harness_events.py append --change-dir ".harness/changes/<change-name>" --phase <phase> --type <command|issue|verification> --run-id <phase-run-id> --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 边界保持最新。
+
+每个阶段的 `phase.start` 与对应 `phase.end` 必须复用同一 `--run-id` / `--attempt`；阶段结束必须写 `--status OK|WARN|FAIL|BLOCKED`。重试同一阶段时生成新的 run-id 并增加 `--attempt <n>`，不得覆盖或伪装成一次执行。**`attempt` 按 phase 全局递增，不是按 run-id**：一个 run-id 只绑定一个 attempt，重试必须「新 run-id ＋ 下一个 attempt」两者同时换，只换其一会撞 `EVENT_ATTEMPT_CONFLICT` 或 `PHASE_ALREADY_CLOSED`。已发布 plan 的修订通过重跑 `plan evidence-pack` + `plan finalize` 分配新 attempt（`harness_plan_finalize.py republish` 已于 0.3.0 移除）。
+
+阶段跑得久（plan/run 常见）时用 `harness_context.py renew --project . --change <cn> --executor <tool>` 续租；租约到期本身不再阻断 `close`（同一 owner 的过期租约不构成冲突，收据里记 `leaseLapsed`），但续租能让 `view` 的状态如实反映在跑。跨工具继续执行时写 `--executor-tool <codex|claude-code|codebuddy|cursor>`，并在接棒事件写 `--handoff-from-tool` / `--handoff-reason`；也可由 `HUNTER_HARNESS_TOOL/AGENT/MODEL/RUN_ID` 环境变量统一注入。
+> 片段：logging · phase=`plan`

package/harness/bundles/general/pi/harness-plan/checklist.md

@@ -0,0 +1,243 @@
+---
+description: harness-plan 的阶段检查清单和覆盖检查列表。仅在执行完整需求规划时读取。
+---
+
+# harness-plan 检查清单
+
+## 阶段 0：工作区变更检查 ⚠️ 强制检查
+
+> 有未提交业务变更（排除 `.harness/`）→ **默认 baseline 隔离**，append `decision` 事件，**不 blocking user confirmation**，继续规划。PowerShell 失败 → ❌ 停止。
+
+**固定命令**：`powershell.exe -Command "git -C '<项目路径>' status --porcelain"`
+
+**判定**：stdout 为空 → ✅ 继续；stdout 非空 → baseline 隔离 + `decision`（note 含变更文件列表）；Bash 被拒 → PowerShell 重试。
+
+## 阶段 0.5：一次性引导与知识查询
+
+- [ ] 定好 change-name（kebab-case）与中文展示标题后，运行一次 `harness_context.py bootstrap-plan --project . --change <cn> --executor <tool> --title "<中文标题>" --json`
+- [ ] 引导返回 `code:"PLAN_BOOTSTRAPPED"`，记下 `runId`/`attempt`/`tier`/`defaultPhases`/`changeBase`；后续 finalize 必须复用同一 `runId`/`attempt`
+- [ ] 不再手工生成 run-id、不再单独跑 doctor/prepare/capture/classify/append；需要单步排查时才用 SKILL.md 阶段 0.5b 的等价分解
+- [ ] 引导失败时按返回的 `code` 处理（`PROJECT_ROOT_INVALID` → 该项目未 init），**不得**跳过引导直接写产物
+- [ ] 项目已绑定平台时执行一次远端 knowledge `query`；不另跑前置 sync，不创建本地索引
+- [ ] 查询失败追加 `issue`，不得回退本地 archive/SQLite、重跑“sync + query”循环或假装已读取历史
+
+## 阶段 2：歧义优先检查与复杂度分级
+
+- [ ] 否定、对比、动作对象、范围或保留/删除关系不存在未确认的多义解释
+- [ ] 若存在歧义，仅完成最小取证后一次一问，并给出推荐理解
+- [ ] **需求里引用了外部设计文档/章节（贴了段落、给了 `xxx.md` 的 `### Bn` 小节、说"之前设计的时候如…"）时，必须确认该章节本次是否纳入**——引用不等于纳入，也不等于排除。把它列进 `in_scope` 或 `out_of_scope` 后再进入阶段 4；漏判会导致计划发布后整体作废重来（republish），是本流程最贵的返工
+- [ ] 简单修复探索预算：最多 1 次合并 CodeGraph 查询 + 1 次定向补查、1 个澄清问题
+- [ ] 无关发现只记非阻断 `issue`，未扩展当前方案或问题列表
+
+## 设计审批包字段：Worktree
+
+> worktree 不再单独询问。阶段 4 **设计审批包** 一次 blocking user confirmation 含 worktree 选项（推荐值读 `harness.json` `defaultWorktree`）。确认后写入 `meta/worktree.json`。
+
+- [ ] 审批包确认后写入 worktree.json（`requested` true/false）
+- [ ] 阶段 8 检查 worktree.json 存在
+
+## 阶段 3：代码探索确认（含 Agent/CodeGraph 降级记录）
+
+阶段 3 执行完成后，确认以下事项：
+
+```
+□ 已按复杂度选择 `executionMode=inline|delegated`；默认 inline
+□ inline 时主会话直接使用 CodeGraph/Read，并返回结构化设计概要
+□ 仅高复杂度且准备委派固定 agent 时，才运行一次 `check-agents --agent harness-explorer`
+□ 只有预检 `executionMode=delegated` 才委派；`inline` 静默继续，不显示不可用告警
+□ spawn 失败、空返回、0 tool uses、仅 "Done"/元数据 → 主会话探索，**不 retry 委派**
+□ 执行日志记录 executionMode、委派原因（如有）、只读约束和核心结论
+```
+
+> 正常 inline 只记 `decision`，不是降级或故障。如果已尝试委派但未返回有效输出（0 tool uses / 空返回 / 仅 "Done"），必须：
+> - 追加一次 `issue` 事件并在 note 写明：子代理未返回有效输出，改为主会话只读探索
+> - 主会话直接使用 codegraph MCP 工具（`mcp__codegraph__codegraph_explore`）和 Read 探索代码（只读，不执行写操作）
+> - 不得在主会话中执行任何写操作
+> - CodeGraph 如通过 MCP 调用，必须优先用 MCP 工具，不允许通过普通 Bash 调 codegraph 命令
+> - 禁止把子代理未经工具验证的文本结论当作"详尽报告"或代码证据采纳
+
+## 影响面检查（远程客户端路径）
+
+变更涉及 HTTP/RPC 客户端时，在设计/任务拆分前完成路径静态比对：
+
+- [ ] 变更涉及 HTTP/RPC 客户端（Feign/RestTemplate/SDK 封装）时：取客户端注解路径（类级 + 方法级拼接），与服务提供方 controller 的 `@RequestMapping` + 方法级注解**完整拼接路径**逐一比对，在计划/执行记录中列出比对结果。只看方法级注解不算完成。
+
+## 阶段 4：设计审批包 ⚠️ 强制阻断（一次 blocking user confirmation）
+
+> 合并原「设计审核 + worktree + 场景表预览 + change-name」。推荐 worktree 读 `harness.json` `defaultWorktree`。
+
+**展示内容**：
+
+1. 设计摘要 + 关键证据 + 风险 + 变更清单
+2. **本次做什么（in_scope）/ 本次不做什么（out_of_scope）** — 两个列表都必须显式列出，不得只展示"做什么"。用户看到"不做"清单才有机会当场纠正范围误判；`out_of_scope` 为空时写"无"，不得省略该行。这两个列表随后原样进入 `plan-evidence-input.json` 的 `intent` 与 `approval.content`（两处必须集合相等）
+3. 测试场景表摘要 + 8 维度覆盖检查
+4. worktree 选项（是/否，含推荐理由）
+5. change-name（自动生成，可修改）
+6. 确认进入任务拆分
+
+确认后立即追加 decision 事件，并写入 `meta/worktree.json`。设计文档按路径分流：
+
+- 审批内容写进 `meta/plan-evidence-input.json` 的 `approval.content`（含 `approver_id`），
+  `plans/<change>-design.md` 由 finalize 从审批内容派生——**不要**手写它，手写的会被覆盖
+
+- [ ] 确认事件早于 approved 设计文档；未获确认时不得先落盘 `status: approved`
+
+展示可审核包后，使用 `blocking user confirmation` 询问用户：
+- **确认**：设计方向正确，继续任务拆分
+- **修改**：某个部分需要调整，修改后再审核
+- **取消**：方向不对，回到需求澄清阶段
+
+### 设计文档自审清单
+
+写完设计文档后，用以下清单自检，**并将自审结果展示给用户**：
+
+```
+□ 无"TBD"/"TODO"/未完成章节
+□ 各节之间无矛盾
+□ 范围聚焦，无不相关内容
+□ 无歧义需求（可被两种方式解读的，已选一种并明确说明）
+□ 自审结果已展示给用户
+```
+
+> 展示格式示例：
+> ```
+> ### 设计文档自审
+> - ✅ 无 TBD/TODO/未完成章节
+> - ✅ 各节之间无矛盾
+> - ✅ 范围聚焦，无不相关内容
+> - ⚠️ 第3.2节"枚举删除"与第4节变更清单中"标记@Deprecated"有矛盾，已修正为"删除"
+> ```
+
+## 测试场景覆盖检查表（8 维度覆盖检查表，强制输出）
+
+> 注意：覆盖检查表是 8 维度，与 4 维度场景表（单元/接口/数据兼容/集成）是两个不同制品。
+
+生成场景表后，逐项确认是否覆盖，**必须输出覆盖检查表展示给用户确认**。未覆盖的维度必须标记为缺口（⚠️ 缺口），不得全部标记为 ✅：
+
+| 覆盖维度 | 状态 | 说明 |
+|---|---|---|
+| 正常路径 | ✅/🟡/❌ | 每个接口 ≥ 1 个正常场景 |
+| 参数校验 | ✅/🟡/❌ | 必填缺失、格式非法、类型错误 |
+| 业务规则 | ✅/🟡/❌ | 唯一性、范围约束、状态机 |
+| 权限/组织边界 | ✅/🟡/❌ | 无权限、跨组织、角色限制 |
+| 数据兼容 | ✅/🟡/❌ | 旧数据无新字段 |
+| 错误码 | ✅/🟡/❌ | 每个异常对应明确错误码 |
+| 集成影响 | ✅/🟡/❌ | 跨模块调用、端到端流程 |
+| 并发/幂等 | ✅/🟡/❌ | 重复提交、并发修改 |
+
+> 展示格式示例：
+> ```
+> ### 场景覆盖检查表
+> | 覆盖维度 | 状态 | 说明 |
+> |---|---|---|
+> | 正常路径 | ✅ | 5 个接口各 ≥ 1 个正常场景 |
+> | 参数校验 | ✅ | 必填缺失、格式非法已覆盖 |
+> | 业务规则 | ✅ | 唯一性、状态机已覆盖 |
+> | 权限/组织边界 | 🟡 | ⚠️ 缺口：未覆盖跨组织场景，需补充 |
+> | 数据兼容 | ✅ | 旧数据 scene_code 迁移场景已覆盖 |
+> | 错误码 | ✅ | 3 个错误码均有对应场景 |
+> | 集成影响 | 🟡 | ⚠️ 缺口：未覆盖端到端流程，需部署后验证 |
+> | 并发/幂等 | ❌ | ⚠️ 缺口：未覆盖重复提交场景，需补充 |
+> ```
+
+## 阶段 7.5：计划对抗评审（可选）确认
+
+> 仅在用户选择启用对抗评审时执行本节检查。默认不启用（高风险构建 auth/支付/迁移/并发 才启用）。
+
+阶段 7.5 执行完成后，确认以下事项：
+
+```
+□ 已用 **设计审批包** 一次 blocking user confirmation（设计 + 场景表摘要 + worktree + change-name）
+□ **未**单独询问 worktree 或对抗评审（对抗评审仅 `--adversarial`）
+□ 已按宿主能力选择隔离 evaluator 或主会话对抗自审；正常 inline 不记故障
+□ 若委派，已使用隔离上下文且校验 tool uses > 0
+□ 若委派返回 0/空/Done/元数据，已立即 inline 自审且未 retry
+□ 已产出 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 执行
+□ 输入包含需求摘要 + 阶段1 context pack（如有）+ 阶段3代码探索结果 + 项目架构约束
+□ 已用 decision / issue 事件 note 记录五类输出：风险识别 / 复用机会 / 替代方案 / 推荐方案 / 关键决策
+□ 已叠加项目架构约束（分层规范、数据模型、接口规范）
+□ 需求澄清结论已追加到 events.ndjson，阶段结束后执行日志由渲染器生成
+□ 提问方式与问题预算符合 protocols.md 的 decision-grilling-protocol（预算数值以那份为准，此处不复述）
+□ 能由 context pack / 阶段3代码探索 / CodeGraph 自答的问题已自答，未打扰用户
+□ 每个需要用户决策的问题，AI 先给出了推荐答案、理由和取舍，用户仅确认或修正
+□ 高风险/业务语义决策（范围、权限、安全、支付、迁移、删除、API契约、用户可见行为）已显式等待用户确认
+```
+
+> 不再检查 Superpowers brainstorming 是否安装或调用；阶段 4 是 harness 原生协议，不存在外部 skill 降级分支。
+
+### 阶段 6：implementation-planning
+
+阶段 6 执行完成后，确认以下事项：
+
+```
+□ 已读取 protocols.md，并按 implementation-planning-protocol 执行
+□ 输入为阶段4已审核设计文档
+□ 已用 artifact 事件 note 记录任务拆分摘要
+□ 已叠加项目层序依赖（数据/契约→业务层→接口层）
+□ 已生成 4 维度场景表（单元/接口/数据兼容/集成）
+□ 每个自动化场景均标注执行层级、预计时长、资源预算、超时、可复用证据；快速反馈不默认扫描全仓库
+□ 已确定变更名（kebab-case）
+□ implementation-detail.md 按复杂度自适应：简单任务不过度展开，复杂任务写清接口/数据/顺序/风险/测试策略
+□ plan / implementation-detail / test-scenarios 三件套互相引用一致，无 TBD/TODO/空泛占位
+```
+
+> 产物是否齐全、任务表与场景表是否非空、优先级与 ownerPhase 取值是否合法，由 finalizer
+> fail-closed 判定（`PLAN_ARTIFACT_MISSING` / `PLAN_TASKS_EMPTY` / `PLAN_SCENARIOS_EMPTY` /
+> `PLAN_SCENARIO_PRIORITY_INVALID`），此处不重复勾选。上面留下的都是机器判不了的：
+> 层序依赖是否合理、维度是否真被覆盖、详略是否配得上复杂度、三件套是否自洽。
+
+> 不再检查 Superpowers writing-plans 是否安装或调用；阶段 6 是 harness 原生协议，不存在 `docs/superpowers/` 同步分支。
+
+## 阶段 8：结束前产物完整性检查 ⚠️ 强制
+
+> **先认路径**：新 change 只走 v2；legacy 产物（历史 change）只读。必需文件清单 → `reference.md`「阶段 8」。
+
+文件是否齐全、哈希是否一致、身份是否匹配、计数是否对得上——这些 **finalizer 与 verify 已经 fail-closed 判定**，逐条复述不产生新结论，只会把一份事实变成两份。命令失败时按返回的 `code` 查 `reference.md`，不要对着清单猜。
+
+下面三条不在机器判定范围内，必须自己守：
+
+- [ ] **v2**：只手写 `meta/plan-evidence-input.json`。`plans/*.md` 由 finalize 派生，手写的会被渲染覆盖，只是白写
+- [ ] 任何缺失**都不得手工补写**（包括 `phase.end`）；回到对应阶段改自然输入/staging 后重跑
+- [ ] v2 过渡期**不写** `meta/plan-finalization.json` 与 `logs/execution-log.md`；缺这两项不算失败，不得为凑表手工补
+
+
+## 关键原则
+
+- **产物路径唯一性**：正式 `.harness/changes/<change-name>/` 是唯一真相源；plan 只写 staging，由 finalizer 原子发布，禁止先写正式目录再补 staging
+- **原生规划协议**：阶段 4/6 使用 clarification、decision-grilling、implementation-planning 三段内置协议，不运行时依赖 Superpowers/grill-me/writing-plans
+- **阶段 4 是强制阻断检查点**——展示设计审批包后必须停下来问用户，收到回复后才能写 approved 设计文档。不要跳过
+- 代码探索只读不写——这个阶段的目标是理解，不是修改
+- 场景表是后续所有步骤的真相源——宁可多花时间打磨，不要草草了事
+- 如果需求不明确，优先提问而不是猜测后继续设计
+- 任务拆分粒度按复杂度调整——plan 简表保持可追踪，implementation-detail 按风险和复杂度自适应展开
+
+> Plan 的结束行为（禁止询问执行模式、只提示 `/harness-run`）由 `SKILL.md` 的关键规则表定义，
+> 详细规则见 `reference.md`「Plan 结束行为规则」。此处不再复述。
+
+## 事件记录（前置规则）
+
+- [ ] 确定 change-name 后立即用稳定且可复用的 `--run-id` / `--attempt` append `phase.start` 事件；各阶段用 `harness_events.py append` 写入 `decision` / `issue` / `artifact`
+- [ ] 阶段 0 在 change-name 确定前可不写事件；阶段 0.5 确定 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/harness/bundles/general/pi/harness-plan/protocols.md

@@ -0,0 +1,133 @@
+---
+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，目标是把需求从“用户意图”收敛成可审核设计输入。
+
+必须输出以下五类结论。用 `harness_events.py append` 追加 `decision` / `issue` 事件，完整的人类可读结论放进事件 `note`；执行日志仅由事件渲染器派生：
+
+| 输出 | 要求 |
+|------|------|
+| 风险识别 | 列出会影响实现、测试、数据、兼容性或交付判断的风险 |
+| 复用机会 | 明确可复用的既有模块、接口、测试、迁移脚本或历史知识 |
+| 替代方案 | 给出 2-3 个可行方案；简单需求可给 1 个主方案 + 1 个不选方案 |
+| 推荐方案 | 明确推荐选项和理由，不让用户从空白处决策 |
+| 用户确认的关键决策 | 只记录真正影响范围、行为、兼容性或风险的决策 |
+
+执行纪律：
+
+1. 先消费阶段 1 的 context pack、阶段 3 的代码探索结果和项目规则。
+2. 能由代码、历史知识、配置、现有文档回答的问题，不问用户。
+3. 需要用户裁决时，交给 `decision-grilling-protocol`。
+4. 影响面检查必须覆盖用户未显式提到的参数、数据、接口、权限、兼容性、模块引用和测试影响。
+5. 低风险工程判断可由 AI 推荐并记录后继续；高风险或业务语义判断必须等待用户确认。
+6. **歧义优先检查**：否定、对比、动作对象、范围或保留/删除关系存在多种合理解释时，只做足以定位现状的最小取证，然后先给出推荐理解并确认；不得先沿某一种猜测深挖完整代码路径。
+7. 探索中发现的无关问题仅以非阻断 `issue` 记录，不加入当前决策树，不扩展设计范围。
+
+## 协议二：decision-grilling-protocol
+
+用于阶段 4 的用户澄清问题。它借鉴 grill-me 的逐问决策树，但采用有限问题预算，避免仪式化盘问。
+
+### 问题预算
+
+| 场景 | 用户问题上限 |
+|------|:---:|
+| 信息充分、无必须裁决的问题 | 0 |
+| 简单修复 | 0-1 |
+| 普通需求 | 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 指令。简单任务可以短，复杂任务必须细。
+
+简单修复的四份产物采用“单点事实、引用不复述”：设计写行为契约，plan 写任务与依赖，detail 写关键修改点与命令，scenarios 写可验证用例。不得复制同一段背景、风险或结论来增加篇幅。
+
+### 计划质量门槛
+
+任务拆分必须满足：
+
+- 每个任务有明确目标、涉及文件和依赖。
+- 不出现 `TBD`、`TODO`、`稍后实现`、`补充测试`、`适当处理错误` 等占位表达。
+- 不引用尚未定义的类型、函数、接口或迁移文件。
+- 层序依赖清晰：数据/契约先于业务实现，业务实现先于接口暴露，验证场景覆盖关键路径。
+- 测试方向明确：单元、接口、数据兼容、集成至少说明适用与不适用原因。
+- 如果设计范围发生收缩，先按 `change-name` 同步规则处理名称和路径。
+
+### implementation-detail 自适应规则
+
+| 复杂度 | 内容要求 |
+|--------|----------|
+| 简单修复 | 关键文件、修改点、验证命令、容易误判的边界 |
+| 中等功能 | 模块顺序、接口/数据约束、测试策略、回滚/兼容注意事项 |
+| 高风险构建 | 迁移顺序、失败恢复、权限/安全边界、并发/幂等、评审关注点 |
+
+禁止为了“看起来完整”生成机械微步骤；也禁止因为“只是参考”而写空泛描述。
+
+## 自检
+
+阶段 4 和阶段 6 完成后，必须自检：
+
+```markdown
+### 原生规划协议自检
+- clarification-protocol：风险 / 复用 / 替代方案 / 推荐方案 / 关键决策均已记录
+- decision-grilling-protocol：用户问题未超预算；每问包含推荐答案；能自查的问题未打扰用户
+- implementation-planning-protocol：plan 简表、implementation-detail、test-scenarios 三件套一致，无占位符
+```
+
+自检结论直接展示给用户即可，**不要**再追加一条 `verification` 事件——「协议自检通过」不改变
+任何结论，只增加监控噪声（roadmap 12 号「事件规则」）。真正影响行为的东西照常留痕：关键决策
+追加 `decision`，发现的冲突与阻塞追加 `issue`。渲染器在 `phase.end` 后生成执行日志。