@hunter-harness/workflow-harness 0.2.2 → 0.2.4

package/harness/bundles/general/codex/harness-knowledge-query/SKILL.md

@@ -3,7 +3,7 @@ name: harness-knowledge-query
 description: 根据新需求、设计任务、代码修改请求或问题排查，在规划和编码前查询 .harness/knowledge
   历史上下文。适用场景：query knowledge、查找历史需求、根据归档理解需求、继续之前类似开发、生成需求上下文包。
 ---
-<!-- generated by harness_deploy.py; core=5401f914277e0517; overlay=none; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=ab1182505b44093f; overlay=none; agent=codex; do not edit -->
 # harness-knowledge-query
 
 根据用户的新需求或排查问题，从项目本地 `.harness/knowledge` 中检索历史需求、决策、实现、风险和测试证据，并生成 AI 可读的 context pack。
@@ -25,13 +25,7 @@ description: 根据新需求、设计任务、代码修改请求或问题排查
 
 当用户提出新功能、改造、排查、设计方案、继续历史任务，且项目存在 `.harness/archive` 或 `.harness/knowledge` 时，AI 应主动运行本 skill，不需要等用户提醒。
 
-如果 `.harness/knowledge/index.json` 不存在或已过期，先运行：
-
-```powershell
-powershell.exe -Command "python '<ingest-skill-dir>\scripts\harness_knowledge.py' sync --project '<project-root>' --update"
-```
-
-然后再查询。
+不在 query 前单独执行 sync。`query` 命令内部执行一次 ensure-current：建立一次当前快照，索引新鲜时无操作，过期或缺失时只构建一次，然后在同一调用内完成查询。
 
 ## Commands
 
@@ -59,12 +53,10 @@ powershell.exe -Command "python '<ingest-skill-dir>\scripts\harness_knowledge.py
 ## Workflow
 
 1. 确认项目根目录。
-2. 运行 `sync --project <root>`。
-3. 如果 `upToDate=false`，运行 `sync --update`。
-4. 用用户原始需求作为 `--query` 查询。
-5. 如已知道相关文件，追加 `--file` 过滤。
-6. 读取 JSON 输出中的 `contextPack`。
-7. 在 `harness-plan`、设计、代码探索或实现前，把 context pack 当作必读输入。
+2. 用用户原始需求执行一次 `query`；query 命令内部执行一次 ensure-current。
+3. 如已知道相关文件，在同一次查询中追加 `--file` 过滤。
+4. 读取 JSON 输出中的 `contextPack`。
+5. 在 `harness-plan`、设计、代码探索或实现前，把 context pack 当作必读输入。
 
 ## Output Contract
 
@@ -96,6 +88,8 @@ powershell.exe -Command "python '<ingest-skill-dir>\scripts\harness_knowledge.py
 ## Forbidden Actions
 
 - rebuild_index_without_need
+- pre_sync_before_query
+- query_then_sync_then_query_again
 - treat_candidate_as_current_fact
 - treat_stale_as_current_fact
 - skip_context_pack_before_planning
@@ -124,7 +118,7 @@ powershell.exe -Command "python '<ingest-skill-dir>\scripts\harness_knowledge.py
 - `matchCount` 与按状态分组的命中数（active/candidate/stale/superseded/conflicted）。
 - `contextPack` 路径与 `latest.json` 指针。
 - 命中 stale/superseded/conflicted 时显式提示风险。
-- 下一步建议（context pack 已就绪 → 进入 `/harness-plan`；索引过期 → 先 `sync --update`）。
+- 下一步建议（context pack 已就绪 → 进入 `/harness-plan`；ensure-current 失败 → 报告具体 issue，不重复同步或查询）。
 
 ## 渐进披露
 
@@ -136,7 +130,7 @@ powershell.exe -Command "python '<ingest-skill-dir>\scripts\harness_knowledge.py
 
 ## 执行日志
 
-`events.ndjson` 为唯一事实源（schema_version 2，`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止手工 Edit**。结构 → [[../protocols/report-pipeline-protocol.md|report-pipeline-protocol]]
+`events.ndjson` 为唯一事实源（schema_version 2，`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止用 Write/Edit 直接维护**。直接修改的内容会在 `phase.end` 或 finalize 时被完整重建覆盖，属于数据丢失；需要保留的详情必须进入事件 `note`。结构 → [[../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 "<触发指令>"

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

@@ -2,7 +2,7 @@
 name: harness-plan
 description: 将需求转化为设计文档+实施计划+完整测试场景表，必须在编码前完成。使用场景：需求分析、feature plan、技术方案设计、实现方案规划
 ---
-<!-- generated by harness_deploy.py; core=5401f914277e0517; overlay=none; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=ab1182505b44093f; overlay=none; agent=codex; do not edit -->
 # harness-plan — 需求规划
 
 ## Purpose
@@ -48,18 +48,19 @@ description: 将需求转化为设计文档+实施计划+完整测试场景表
 
 ## Subagent 委派
 
-- **阶段 3 探索**：`check-agents --agent harness-explorer` → 可用则委派，否则主会话探索；无效返回不 retry
-- **阶段 7.5**：仅 `--adversarial`；`check-agents --agent harness-evaluator` → `reports/plan-review/`
+- **阶段 3 探索**：先运行 `python <skills-root>/scripts/harness_preflight.py check-agents --skills-root <skills-root> --agent harness-explorer --json`；可用则委派，否则主会话探索；无效返回不 retry
+- **阶段 7.5**：仅 `--adversarial`；先运行 `python <skills-root>/scripts/harness_preflight.py check-agents --skills-root <skills-root> --agent harness-evaluator --json`；可用才委派到 `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` |
+| 0.5 | 先初始化 change-name + `phase.start`，从第一条知识查询起保留事件证据 |
+| 1 | `harness-knowledge-query` 单次 query（内部 ensure-current；失败记 `issue`） |
+| 2 | 歧义优先检查 + 复杂度分级；先确认会改变实现方向的语义歧义 |
+| 3 | 按复杂度执行有预算的代码探索；简单修复不得扩散到无关模块 |
+| 4 | **设计审批包** AskUserQuestion；确认事件早于 approved 设计文档和 `meta/worktree.json` |
 | 5–6 | plan + implementation-detail + test-scenarios → `plans/` |
 | 7.5 | 仅 `--adversarial` 对抗评审 |
 | 8 | 产物完整性必检 → `checklist.md` |
@@ -81,6 +82,9 @@ change-name 范围变更 → 提示重命名或记 🟡WARN（→ `reference.md`
 | 阶段 8 | spec/plan/detail/scenarios/worktree.json/logs/events 缺一不可 → ❌FAIL |
 | Plan 结束 | **禁止**询问执行模式；只提示 `/harness-run` |
 | 知识查询 | 0.5 失败不得假装已读历史 |
+| 歧义优先检查 | 否定、对比、动作对象或范围存在多种合理解释时，最小取证后先给推荐理解并一次一问；确认前不深挖错误方向 |
+| 简单修复探索预算 | 预计不超过 2 个代码文件、且不涉及认证/安全/迁移/并发/API 契约重设时，最多 1 次合并 CodeGraph 查询 + 1 次定向补查、1 个用户澄清问题；无关发现只记非阻断说明 |
+| 精简产物 | 简单修复只保留实现所需的设计、任务、边界和测试；禁止在 spec/plan/detail/scenarios 中重复同一背景和结论 |
 | state snapshot | 读取 `state-snapshot.json`（`harness_state.py` / state-layout-protocol §state-snapshot.json）了解 project/worktree root、HEAD/base、profile/rules/map/knowledge 指纹；失效由脚本刷新，**不得仅凭缓存跳过代码探索或验证门禁**（design §3.6） |
 | 协议 | sensitive-info / evidence-based-reporting / state-layout |
 
@@ -95,11 +99,11 @@ change-name 范围变更 → 提示重命名或记 🟡WARN（→ `reference.md`
 ## 交互白名单
 
 1. **设计审批包**（阶段 4）：设计 + 场景表 + worktree + change-name
-2. **decision-grilling**（阶段 3 澄清）：高风险业务裁决（一次一问）
+2. **decision-grilling**（阶段 2/3 澄清）：语义歧义或高风险业务裁决（一次一问）
 
 ## 执行日志
 
-`events.ndjson` 为唯一事实源（schema_version 2，`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止手工 Edit**。结构 → [[../protocols/report-pipeline-protocol.md|report-pipeline-protocol]]
+`events.ndjson` 为唯一事实源（schema_version 2，`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止用 Write/Edit 直接维护**。直接修改的内容会在 `phase.end` 或 finalize 时被完整重建覆盖，属于数据丢失；需要保留的详情必须进入事件 `note`。结构 → [[../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 "<触发指令>"

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

@@ -12,9 +12,22 @@ description: harness-plan 的阶段检查清单和覆盖检查列表。仅在执
 
 **判定**：stdout 为空 → ✅ 继续；stdout 非空 → baseline 隔离 + `decision`（note 含变更文件列表）；Bash 被拒 → PowerShell 重试。
 
-## 阶段 2：Worktree 决策（并入设计审批包）
+## 阶段 0.5：事件初始化与知识查询
 
-> worktree 不再单独询问。阶段 5 **设计审批包** 一次 AskUserQuestion 含 worktree 选项（推荐值读 `harness.json` `defaultWorktree`）。确认后写入 `meta/worktree.json`。
+- [ ] 先确定 change-name，并立即用 `harness_events.py append` 追加 `phase.start`
+- [ ] 再执行一次 knowledge `query`；由 query 内部 ensure-current，不另跑前置 sync
+- [ ] 查询失败追加 `issue`，不得重跑“sync + query”循环或假装已读取历史
+
+## 阶段 2：歧义优先检查与复杂度分级
+
+- [ ] 否定、对比、动作对象、范围或保留/删除关系不存在未确认的多义解释
+- [ ] 若存在歧义，仅完成最小取证后一次一问，并给出推荐理解
+- [ ] 简单修复探索预算：最多 1 次合并 CodeGraph 查询 + 1 次定向补查、1 个澄清问题
+- [ ] 无关发现只记非阻断 `issue`，未扩展当前方案或问题列表
+
+## 设计审批包字段：Worktree
+
+> worktree 不再单独询问。阶段 4 **设计审批包** 一次 AskUserQuestion 含 worktree 选项（推荐值读 `harness.json` `defaultWorktree`）。确认后写入 `meta/worktree.json`。
 
 - [ ] 审批包确认后写入 worktree.json（`requested` true/false）
 - [ ] 阶段 8 检查 worktree.json 存在
@@ -26,7 +39,7 @@ description: harness-plan 的阶段检查清单和覆盖检查列表。仅在执
 ```
 □ 是通过 Agent 工具委派 subagent 执行的（不是主会话直接调用 codegraph）
 □ subagent 返回了结构化设计概要（涉及模块、接口变更、关键决策）
-□ 委派前已运行 `harness_preflight.py check-agents --agent harness-explorer`
+□ 委派前已运行 `python <skills-root>/scripts/harness_preflight.py check-agents --skills-root <skills-root> --agent harness-explorer --json`
 □ `usable=false` 或未返回有效输出 → 主会话探索，**不 retry 委派**
 □ 主会话未被代码探索的中间结果污染
 □ 在执行日志中记录了 Agent 调用状态：
@@ -38,13 +51,13 @@ description: harness-plan 的阶段检查清单和覆盖检查列表。仅在执
 ```
 
 > 如果 Agent 工具不可用，或子代理被委派但未返回有效输出（0 tool uses / 空返回 / 仅 "Done"），必须显式降级并记录：
-> - 在执行日志中写明降级原因：🟡 阶段3降级：Agent 不可用 / 子代理未返回有效输出，改为主会话只读探索
+> - 追加 `issue` 事件并在 note 写明降级原因：Agent 不可用 / 子代理未返回有效输出，改为主会话只读探索
 > - 主会话直接使用 codegraph MCP 工具（`mcp__codegraph__codegraph_explore`）和 Read 探索代码（只读，不执行写操作）
 > - 不得在主会话中执行任何写操作
 > - CodeGraph 如通过 MCP 调用，必须优先用 MCP 工具，不允许通过普通 Bash 调 codegraph 命令
 > - 禁止把子代理未经工具验证的文本结论当作"详尽报告"或代码证据采纳
 
-## 阶段 5：设计审批包 ⚠️ 强制阻断（一次 AskUserQuestion）
+## 阶段 4：设计审批包 ⚠️ 强制阻断（一次 AskUserQuestion）
 
 > 合并原「设计审核 + worktree + 场景表预览 + change-name」。推荐 worktree 读 `harness.json` `defaultWorktree`。
 
@@ -58,6 +71,8 @@ description: harness-plan 的阶段检查清单和覆盖检查列表。仅在执
 
 确认后写入 `spec/<change>-design.md`（含 frontmatter）和 `meta/worktree.json`。
 
+- [ ] 确认事件早于 approved 设计文档；未获确认时不得先落盘 `status: approved`
+
 设计文档必须包含 frontmatter：
 ```yaml
 ---
@@ -155,11 +170,11 @@ source: harness-plan
 
 ```
 □ 已读取 protocols.md，并按 clarification-protocol / decision-grilling-protocol 执行
-□ 输入包含需求摘要 + 阶段0.5 context pack（如有）+ 阶段3代码探索结果 + 项目架构约束
-□ 已在 execution-log 中记录五类输出：风险识别 / 复用机会 / 替代方案 / 推荐方案 / 关键决策
+□ 输入包含需求摘要 + 阶段1 context pack（如有）+ 阶段3代码探索结果 + 项目架构约束
+□ 已用 decision / issue 事件 note 记录五类输出：风险识别 / 复用机会 / 替代方案 / 推荐方案 / 关键决策
 □ 已叠加项目架构约束（分层规范、数据模型、接口规范）
-□ 需求澄清结论已写入 .harness/changes/<change-name>/logs/execution-log.md，并在 events.ndjson 记录 decision
-□ 用户问题未超预算：普通需求 1-3 问，高风险需求 5-7 问；无必须裁决事项时 0 问
+□ 需求澄清结论已追加到 events.ndjson，阶段结束后执行日志由渲染器生成
+□ 用户问题未超预算：简单修复 0-1 问，普通需求 1-3 问，高风险需求 5-7 问；无必须裁决事项时 0 问
 □ 提问遵循"一次一问、等答再继续"；能由 context pack / 阶段3代码探索 / CodeGraph 自答的问题已自答，未打扰用户
 □ 每个需要用户决策的问题，AI 先给出了推荐答案、理由和取舍，用户仅确认或修正
 □ 高风险/业务语义决策（范围、权限、安全、支付、迁移、删除、API契约、用户可见行为）已显式等待用户确认
@@ -173,8 +188,8 @@ source: harness-plan
 
 ```
 □ 已读取 protocols.md，并按 implementation-planning-protocol 执行
-□ 输入为阶段5已审核设计文档
-□ 已生成基础任务列表，并在 execution-log 记录任务拆分摘要
+□ 输入为阶段4已审核设计文档
+□ 已生成基础任务列表，并用 artifact 事件 note 记录任务拆分摘要
 □ 已叠加项目层序依赖（数据/契约→业务层→接口层）
 □ 已生成 4 维度场景表（单元/接口/数据兼容/集成）
 □ 已确定变更名（kebab-case）
@@ -223,7 +238,7 @@ source: harness-plan
 
 - **产物路径唯一性**：`.harness/changes/<change-name>/` 是唯一真相源，plan 产物必须直接写入此目录
 - **原生规划协议**：阶段 4/6 使用 clarification、decision-grilling、implementation-planning 三段内置协议，不运行时依赖 Superpowers/grill-me/writing-plans
-- **阶段 2 是强制阻断检查点**——必须停下来问用户，收到回复后才能继续。不要跳过
+- **阶段 4 是强制阻断检查点**——展示设计审批包后必须停下来问用户，收到回复后才能写 approved 设计文档。不要跳过
 - 代码探索只读不写——这个阶段的目标是理解，不是修改
 - 场景表是后续所有步骤的真相源——宁可多花时间打磨，不要草草了事
 - 如果需求不明确，优先提问而不是猜测后继续设计
@@ -233,7 +248,7 @@ source: harness-plan
 ## 事件记录（前置规则）
 
 - [ ] 确定 change-name 后立即 append `phase.start` 事件；各阶段用 `harness_events.py append` 写入 `decision` / `issue` / `artifact`
-- [ ] 阶段 0 在 change-name 确定前可不写事件；阶段 1 确定 change-name 后必须开始记录
+- [ ] 阶段 0 在 change-name 确定前可不写事件；阶段 0.5 确定 change-name 后必须开始记录
 
 ## 需求范围缩减后的 change-name 检查 ⚠️
 

package/harness/bundles/general/codex/harness-plan/protocols.md

@@ -12,7 +12,7 @@ description: harness-plan 的原生规划协议。吸收 brainstorming、grill-m
 
 用于阶段 4，目标是把需求从“用户意图”收敛成可审核设计输入。
 
-必须输出以下五类结论，并写入 `logs/execution-log.md`，关键决策同步追加到 `events.ndjson`：
+必须输出以下五类结论。用 `harness_events.py append` 追加 `decision` / `issue` 事件，完整的人类可读结论放进事件 `note`；执行日志仅由事件渲染器派生：
 
 | 输出 | 要求 |
 |------|------|
@@ -24,11 +24,13 @@ description: harness-plan 的原生规划协议。吸收 brainstorming、grill-m
 
 执行纪律：
 
-1. 先消费阶段 0.5 的 context pack、阶段 3 的代码探索结果和项目规则。
+1. 先消费阶段 1 的 context pack、阶段 3 的代码探索结果和项目规则。
 2. 能由代码、历史知识、配置、现有文档回答的问题，不问用户。
 3. 需要用户裁决时，交给 `decision-grilling-protocol`。
 4. 影响面检查必须覆盖用户未显式提到的参数、数据、接口、权限、兼容性、模块引用和测试影响。
 5. 低风险工程判断可由 AI 推荐并记录后继续；高风险或业务语义判断必须等待用户确认。
+6. **歧义优先检查**：否定、对比、动作对象、范围或保留/删除关系存在多种合理解释时，只做足以定位现状的最小取证，然后先给出推荐理解并确认；不得先沿某一种猜测深挖完整代码路径。
+7. 探索中发现的无关问题仅以非阻断 `issue` 记录，不加入当前决策树，不扩展设计范围。
 
 ## 协议二：decision-grilling-protocol
 
@@ -39,11 +41,14 @@ description: harness-plan 的原生规划协议。吸收 brainstorming、grill-m
 | 场景 | 用户问题上限 |
 |------|:---:|
 | 信息充分、无必须裁决的问题 | 0 |
+| 简单修复 | 0-1 |
 | 普通需求 | 1-3 |
 | 高风险需求（auth、支付、数据迁移、并发、安全、不可逆删除、用户可见行为变化） | 5-7 |
 
 超过预算仍无法收敛时，不要继续追问；必须输出“未决决策清单”，标记阻塞项，并请用户裁决是否缩小范围或暂停。
 
+用户纠正了最初理解时，立即丢弃错误探索假设；简单修复最多再进行一次定向确认，不因旧探索结果追加连锁问题。
+
 ### 提问格式
 
 每次只问一个问题，且必须包含推荐答案：
@@ -89,6 +94,8 @@ description: harness-plan 的原生规划协议。吸收 brainstorming、grill-m
 
 `implementation-detail.md` 必须存在，但不再强制写成 2-5 分钟粒度、逐行代码片段或逐 commit 指令。简单任务可以短，复杂任务必须细。
 
+简单修复的四份产物采用“单点事实、引用不复述”：设计写行为契约，plan 写任务与依赖，detail 写关键修改点与命令，scenarios 写可验证用例。不得复制同一段背景、风险或结论来增加篇幅。
+
 ### 计划质量门槛
 
 任务拆分必须满足：
@@ -121,4 +128,4 @@ description: harness-plan 的原生规划协议。吸收 brainstorming、grill-m
 - implementation-planning-protocol：plan 简表、implementation-detail、test-scenarios 三件套一致，无占位符
 ```
 
-该自检写入 execution-log；关键结论写入 events.ndjson。
+该自检作为 `verification` 事件的 `note` 追加；关键结论分别追加 `decision` / `issue` 事件。渲染器在 `phase.end` 后生成执行日志。

package/harness/bundles/general/codex/harness-plan/reference.md

@@ -6,7 +6,7 @@ description: harness-plan 的需求提取模板、任务拆分规则、测试场
 
 ## Worktree 决策文件模板
 
-阶段 2 必须生成 `.harness/changes/<change-name>/meta/worktree.json`。这是后续 `/harness-run` 是否创建/切换 worktree 的唯一机器可读依据。
+阶段 4 设计审批包确认后必须生成 `.harness/changes/<change-name>/meta/worktree.json`。这是后续 `/harness-run` 是否创建/切换 worktree 的唯一机器可读依据。
 
 ### 使用 Worktree
 
@@ -36,15 +36,9 @@ description: harness-plan 的需求提取模板、任务拆分规则、测试场
 }
 ```
 
-### execution-log 记录示例
+### 决策事件 note 示例
 
-```md
-## 阶段 2：Worktree 决策
-- 用户选择：使用 Worktree
-- 决策文件：.harness/changes/<change-name>/meta/worktree.json
-- requested=true, created=false
-- 创建责任：harness-run
-```
+`用户选择使用 Worktree；决策文件为 meta/worktree.json；requested=true, created=false；创建责任为 harness-run。`
 
 ## 参考 — 详细格式
 
@@ -99,11 +93,11 @@ description: harness-plan 的需求提取模板、任务拆分规则、测试场
 - 决策2: 说明
 ```
 
-## 阶段 5：生成设计文档 ⚠️ 用户审核
+## 阶段 4：设计审批与文档落盘 ⚠️ 用户审核
 
 基于代码探索和需求澄清的结果，撰写设计文档并展示给用户审核。
 
-> **本阶段是强制检查点。** 设计文档生成后必须展示给用户，收到确认后才能进入阶段 6（任务拆分）。设计文档确保方向正确后再细化任务——避免基于错误理解拆分出无效任务。
+> **本阶段是强制检查点。** 先展示设计审批包，收到确认并追加 decision 事件后，才能落盘 `status: approved` 的设计文档并进入阶段 6（任务拆分）。设计方向正确后再细化任务，避免基于错误理解拆分无效任务。
 
 **用户确认后必须立即写入** `.harness/changes/<change-name>/spec/<change-name>-design.md`。如果此文件不存在，harness-plan 不得进入阶段 6。
 
@@ -257,7 +251,7 @@ status: approved
 | INT-001 | 端到端 | ... | ... | N 步操作 | ... |
 ```
 
-## 产物保存规则（跨阶段：阶段1/5/6/8）
+## 产物保存规则（跨阶段：阶段0.5/4/6/8）
 
 1. **自动确定变更名**：基于需求描述自动生成变更名（kebab-case），无需用户确认
 
@@ -267,7 +261,7 @@ status: approved
    - 示例：`contribution-module`、`fix-duplicate-submit`
    - 变更名一旦确定即为最终值，后续所有 skill 自动引用
 
-   > **与 Worktree 的关系**：如果阶段 2 用户选择了 worktree，变更名在创建 worktree 时随分支名确定（worktree 名即变更名）。如果未使用 worktree，变更名在阶段 1 自动生成。
+   > **与 Worktree 的关系**：阶段 4 用户确认是否使用 worktree；变更名已在阶段 0.5 生成，后续 worktree 直接复用该名称。
 
 2. **创建产出目录**：用 Write 工具创建以下目录结构（Write 会自动创建中间目录）：
    ```
@@ -283,7 +277,7 @@ status: approved
    .harness/changes/<change-name>/backups/
    ```
 
-3. **保存设计文档**：将阶段 5 生成的设计文档保存到：
+3. **保存设计文档**：将阶段 4 已确认的设计文档保存到：
    - `.harness/changes/<change-name>/spec/<change-name>-design.md`
 
    设计文档 frontmatter 格式：
@@ -298,15 +292,7 @@ status: approved
 
    > 如果 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>
-
-   ---
-   ```
+4. **初始化结构化事件**：确定 change-name 后，立即运行 `harness_events.py append --type phase.start`。脚本负责建立父目录和 `events.ndjson`；执行日志在 `phase.end` 时由完整事件流渲染，任何阶段都不得直接用 Write/Edit 维护该投影。
 
 5. **保存计划文件**：计划文件包含 YAML frontmatter（含 change-name），保存到：
    - `.harness/changes/<change-name>/plans/<change-name>-plan.md`（简洁任务表）

package/harness/bundles/general/codex/harness-review/SKILL.md

@@ -3,7 +3,7 @@ name: harness-review
 description: 6维度代码审查（架构/安全/规范/兼容/测试/性能），对照项目规则（见
   .harness/context-index.json）和测试场景表，在隔离上下文运行。使用场景：代码审查、提交前检查、合并评审
 ---
-<!-- generated by harness_deploy.py; core=5401f914277e0517; overlay=none; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=ab1182505b44093f; overlay=none; agent=codex; do not edit -->
 # harness-review — 代码审查
 
 ## Purpose
@@ -130,7 +130,7 @@ review 读取 `state-snapshot.json`（`harness_state.py` / state-layout-protocol
 
 ## 执行日志
 
-`events.ndjson` 为唯一事实源（schema_version 2，`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止手工 Edit**。结构 → [[../protocols/report-pipeline-protocol.md|report-pipeline-protocol]]
+`events.ndjson` 为唯一事实源（schema_version 2，`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止用 Write/Edit 直接维护**。直接修改的内容会在 `phase.end` 或 finalize 时被完整重建覆盖，属于数据丢失；需要保留的详情必须进入事件 `note`。结构 → [[../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 "<触发指令>"

package/harness/bundles/general/codex/harness-run/SKILL.md

@@ -2,7 +2,7 @@
 name: harness-run
 description: 按变更簇执行 TDD 编码循环（RED→GREEN→REFACTOR→编译验证），逐变更簇实现计划中的任务。使用场景：开始编码、实现功能、写代码、TDD 编码
 ---
-<!-- generated by harness_deploy.py; core=5401f914277e0517; overlay=none; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=ab1182505b44093f; overlay=none; agent=codex; do not edit -->
 # harness-run — 需求编码
 
 ## Purpose
@@ -102,7 +102,7 @@ description: 按变更簇执行 TDD 编码循环（RED→GREEN→REFACTOR→编
 
 ## 执行日志
 
-`events.ndjson` 为唯一事实源（schema_version 2，`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止手工 Edit**。结构 → [[../protocols/report-pipeline-protocol.md|report-pipeline-protocol]]
+`events.ndjson` 为唯一事实源（schema_version 2，`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止用 Write/Edit 直接维护**。直接修改的内容会在 `phase.end` 或 finalize 时被完整重建覆盖，属于数据丢失；需要保留的详情必须进入事件 `note`。结构 → [[../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 "<触发指令>"

package/harness/bundles/general/codex/harness-run/protocols.md

@@ -34,8 +34,9 @@ REFACTOR 只允许不改变行为的整理。若重构改变行为，必须回
 
 - `evidence/verification-ledger.json`：构建/测试命令、证据、diffHash、复用状态。
 - `evidence/run-task-status.md`：任务状态、对应场景、未验证项。
-- `logs/execution-log.md`：RED 类型、GREEN 结果、REFACTOR 结果、验证证据。
-- `events.ndjson`：关键 command / verification / issue / artifact 事件。
+- `events.ndjson`：关键 command / verification / issue / artifact 事件；RED 类型、GREEN 结果、REFACTOR 结果和验证证据放入事件 `note`。
+
+执行日志是上述事件在阶段边界生成的只读投影，不作为变更簇的直接输出目标。
 
 禁止把静态验证写成“测试通过”。静态 RED/GREEN 的最终状态至少是 🟡WARN，除非后续真实验证已完成。
 

package/harness/bundles/general/codex/harness-submit/SKILL.md

@@ -3,7 +3,7 @@ name: harness-submit
 description: 最终提交封装：验证→中文 commit→提交/推送；worktree 模式含 --no-ff
   合并回主分支。使用场景：提交代码、commit、push、合并分支、merge to main、完成开发
 ---
-<!-- generated by harness_deploy.py; core=5401f914277e0517; overlay=none; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=ab1182505b44093f; overlay=none; agent=codex; do not edit -->
 # harness-submit — 最终提交（含 worktree 合并）
 
 ## Purpose
@@ -131,7 +131,7 @@ git 经 PowerShell；commit/报告不得含明文密钥。遵循 `../protocols/s
 
 ## 执行日志
 
-`events.ndjson` 为唯一事实源（schema_version 2，`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止手工 Edit**。结构 → [[../protocols/report-pipeline-protocol.md|report-pipeline-protocol]]
+`events.ndjson` 为唯一事实源（schema_version 2，`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止用 Write/Edit 直接维护**。直接修改的内容会在 `phase.end` 或 finalize 时被完整重建覆盖，属于数据丢失；需要保留的详情必须进入事件 `note`。结构 → [[../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 "<触发指令>"

package/harness/bundles/general/codex/harness-submit/checklist.md

@@ -380,14 +380,14 @@ powershell.exe -Command "git -C '<项目路径>' diff --name-only --diff-filter=
 
 重跑后写回 ledger 的 `compile`/`unitTest`，更新 `diffHash`/`currentHead`。
 
-**写 check-ok marker**（npm run check exit 0 后强制）：让 pre-push hook 跳过重复 check（省 ~350s）。三重校验（marker ts<10min + command + HEAD），任一不满足照跑。
+**写 check-ok marker**（npm run check exit 0 后强制）：让 pre-push hook 跳过重复 check。三重校验（marker ts<10min + command + commit tree），任一不满足照跑。marker 写入时记录 `git write-tree`，因此验证后创建 commit 不会仅因 HEAD 前移而使缓存失效。
 
 ```powershell
 # npm run check exit 0 后立即写 marker（M5 或 REUSED 后均可）
 powershell.exe -Command "python harness/scripts/harness_check_gate.py --write"
 ```
 
-> marker 写入 `.harness/check-ok.marker`（gitignored，本地）。push 时 pre-push hook 读 marker：HEAD 自写 marker 后未变 + ts<10min + command 匹配 → 跳过 npm run check；否则照跑（安全默认）。
+> marker 写入 `.harness/check-ok.marker`（gitignored，本地）。push 时 pre-push hook 比较 `HEAD^{tree}` 与 marker 的 `treeHash`，再校验 ts<10min + command；commit tree 未变化即可跳过，任何内容变化都照跑（安全默认）。
 
 ### 步骤 M6：push 主分支
 

package/harness/bundles/general/codex/harness-sync/SKILL.md

@@ -2,7 +2,7 @@
 name: harness-sync
 description: 检查并更新项目AI元数据（CodeGraph索引、harness-codebase-map分析、CLAUDE.md、AGENTS.md、.harness/完整性），确保Claude对代码库的理解与最新代码一致。当用户说'同步/更新索引/刷新元数据/检查一致性'时使用
 ---
-<!-- generated by harness_deploy.py; core=5401f914277e0517; overlay=none; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=ab1182505b44093f; overlay=none; agent=codex; do not edit -->
 # harness-sync — 元数据同步
 
 ## Purpose
@@ -54,7 +54,7 @@ description: 检查并更新项目AI元数据（CodeGraph索引、harness-codeba
 
 ## 执行日志
 
-`events.ndjson` 为唯一事实源（schema_version 2，`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止手工 Edit**。结构 → [[../protocols/report-pipeline-protocol.md|report-pipeline-protocol]]
+`events.ndjson` 为唯一事实源（schema_version 2，`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止用 Write/Edit 直接维护**。直接修改的内容会在 `phase.end` 或 finalize 时被完整重建覆盖，属于数据丢失；需要保留的详情必须进入事件 `note`。结构 → [[../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 "<触发指令>"

package/harness/bundles/general/codex/harness-test/SKILL.md

@@ -2,7 +2,7 @@
 name: harness-test
 description: 测试执行：读取场景表，执行单元测试+API接口测试+数据兼容验证，输出测试报告。当用户说'跑测试/验证/跑用例/接口测试/单元测试'时使用
 ---
-<!-- generated by harness_deploy.py; core=5401f914277e0517; overlay=none; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=ab1182505b44093f; overlay=none; agent=codex; do not edit -->
 # harness-test — 测试执行
 
 ## Purpose
@@ -149,7 +149,7 @@ Phase 1 前先读 `.harness/changes/<change-name>/evidence/verification-ledger.j
 
 ## 执行日志
 
-`events.ndjson` 为唯一事实源（schema_version 2，`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止手工 Edit**。结构 → [[../protocols/report-pipeline-protocol.md|report-pipeline-protocol]]
+`events.ndjson` 为唯一事实源（schema_version 2，`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止用 Write/Edit 直接维护**。直接修改的内容会在 `phase.end` 或 finalize 时被完整重建覆盖，属于数据丢失；需要保留的详情必须进入事件 `note`。结构 → [[../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 "<触发指令>"

package/harness/bundles/general/codex/scripts/harness_check_gate.py

@@ -1,14 +1,15 @@
 #!/usr/bin/env python3
 """Pre-push gate: skip `npm run check` when a recent check-ok marker matches
-the current HEAD.
+the tree of the commit being pushed.
 
 Triple check (all must pass to skip, else exit 1 → hook runs npm run check):
   1. marker exists and its `ts` is within MAX_AGE_S (10 min) of now
   2. marker `command` == EXPECTED_CMD ("npm run check")
-  3. current `git rev-parse HEAD` == marker `commitHash`
+  3. current `git rev-parse HEAD^{tree}` == marker `treeHash`
 
-The marker is written by harness-submit M5 right after a green `npm run check`.
-Any mismatch (no marker, stale, different command, HEAD moved since the check)
+The marker is written by harness-submit M5 after a green `npm run check` and
+records `git write-tree`. This remains valid after commit because the new HEAD
+has the same tree. Any mismatch (no marker, stale, command or tree changed)
 forces a full re-run — the safe default. This is a local convenience only;
 non-harness pushes have no marker and always run the check.
 
@@ -28,10 +29,10 @@ MAX_AGE_S = 600  # 10 minutes
 EXPECTED_CMD = "npm run check"
 
 
-def _current_head() -> str | None:
+def _git_output(args: list[str]) -> str | None:
     try:
         r = subprocess.run(
-            ["git", "rev-parse", "HEAD"],
+            ["git", *args],
             cwd=str(ROOT),
             capture_output=True,
             text=True,
@@ -42,20 +43,27 @@ def _current_head() -> str | None:
     return r.stdout.strip() if r.returncode == 0 else None
 
 
+def _current_index_tree() -> str | None:
+    return _git_output(["write-tree"])
+
+
+def _current_head_tree() -> str | None:
+    return _git_output(["rev-parse", "HEAD^{tree}"])
+
+
 def write_marker() -> int:
-    """Write a check-ok marker for the current HEAD (called by harness-submit M5
-    after a green npm run check). Pre-push gate reads it to skip a re-run."""
-    head = _current_head()
-    if head is None:
+    """Record the verified index tree so the marker survives the next commit."""
+    tree = _current_index_tree()
+    if tree is None:
         return 1
     MARKER.parent.mkdir(parents=True, exist_ok=True)
-    payload = {"ts": time.time(), "commitHash": head, "command": EXPECTED_CMD}
+    payload = {"ts": time.time(), "treeHash": tree, "command": EXPECTED_CMD}
     MARKER.write_text(
         json.dumps(payload, ensure_ascii=False) + "\n",
         encoding="utf-8",
         newline="\n",
     )
-    print(f"check-ok marker written for HEAD {head[:7]}")
+    print(f"check-ok marker written for tree {tree[:7]}")
     return 0
 
 
@@ -84,17 +92,17 @@ def main(argv: list[str] | None = None) -> int:
         return 1
     if data.get("command") != EXPECTED_CMD:
         return 1
-    marker_commit = data.get("commitHash")
-    if not isinstance(marker_commit, str):
+    marker_tree = data.get("treeHash")
+    if not isinstance(marker_tree, str):
         return 1
-    head = _current_head()
-    if head is None or head != marker_commit:
+    tree = _current_head_tree()
+    if tree is None or tree != marker_tree:
         return 1
     # All three checks passed: a green npm run check ran on this exact HEAD
     # within the last 10 minutes. Safe to skip.
     print(
         f"pre-push: skipping npm run check (verified {int(time.time() - ts)}s ago "
-        f"at HEAD {head[:7]})"
+        f"for tree {tree[:7]})"
     )
     return 0
 

package/harness/bundles/general/cursor/.harness-build.json

@@ -2,5 +2,5 @@
   "schemaVersion": 1,
   "overlay": "none",
   "agent": "cursor",
-  "coreHash": "507d66eba1aaf00e"
+  "coreHash": "bcff8a45420f1380"
 }