@hunter-harness/workflow-harness 0.2.2 → 0.2.4

package/harness/bundles/java/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/java/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/java/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/java/codex/harness-review/SKILL.md

@@ -3,7 +3,7 @@ name: harness-review
 description: 6维度代码审查（架构/安全/规范/兼容/测试/性能），对照项目规则（见
   .harness/context-index.json）和测试场景表，在隔离上下文运行。使用场景：代码审查、提交前检查、合并评审
 ---
-<!-- generated by harness_deploy.py; core=d543c354ebf9093a; overlay=java; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=c0ce0eeba998d982; overlay=java; 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/java/codex/harness-run/SKILL.md

@@ -2,7 +2,7 @@
 name: harness-run
 description: 按变更簇执行 TDD 编码循环（RED→GREEN→REFACTOR→编译验证），逐变更簇实现计划中的任务。使用场景：开始编码、实现功能、写代码、TDD 编码
 ---
-<!-- generated by harness_deploy.py; core=d543c354ebf9093a; overlay=java; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=c0ce0eeba998d982; overlay=java; agent=codex; do not edit -->
 # harness-run — 需求编码
 
 ## Purpose
@@ -118,7 +118,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/java/codex/harness-run/checklist.md

@@ -30,6 +30,8 @@
 - [ ] **读取任务状态**：`.harness/changes/<change>/run-task-status.md`（如存在）— 恢复上次运行状态
 - [ ] 确认 `项目规则（见 .harness/context-index.json）/` 规则已加载
 - [ ] 检查构建配置完整性（worktree 中确认 `.mvn/maven.config`、`settings.xml` 等存在）
+- [ ] 读取 `.mvn/maven.config`，确认命令没有重复或覆盖项目已有的 `-s` / `-o` / 仓库设置
+- [ ] 离线依赖缺失时仅在项目规则允许联网的前提下执行至多一次非离线 `-nsu` 恢复；禁止离线/联网循环重试
 - [ ] 依赖模块预安装（worktree 中检查上游模块是否已 `mvn install`）
 - [ ] 代码探索优先用 `codegraph_explore`，仅在返回不完整时补充 Read
 - [ ] append `phase.start`（`note` 含测试基础设施 CHECKING 直至探测完成）

package/harness/bundles/java/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/java/codex/harness-run/reference.md

@@ -97,6 +97,12 @@ powershell.exe -NoProfile -Command "Test-Path '.claude/worktrees/<change-name>/.
 13. **依赖模块预安装**：如果在 worktree 中执行，检查上游依赖模块是否已 `mvn install` 到本地仓库。缺失时先执行 `powershell.exe -Command "mvn install -pl <upstream-modules> -am -DskipTests -nsu"`
 14. **代码探索优先用 codegraph_explore**：一次调用可获取多个相关符号的源码，替代逐个 Read 文件。违反 `项目 codegraph 规则` 规则逐个 Read 会浪费 3-5 分钟。仅在 codegraph 返回结果不完整时补充 Read
 
+### Maven 项目配置与重试预算
+
+- 运行 Maven 前先读取项目已有的 `.mvn/maven.config`；其中的 `-s`、`-o`、镜像和仓库设置视为项目契约，不在命令行重复追加或覆盖。
+- 若项目配置已启用离线模式，依赖缺失只允许一次有明确原因的恢复尝试：仅在项目规则允许联网时临时执行非离线的 `-nsu` 命令；随后继续遵循项目配置，不得在离线/联网命令之间循环试错。
+- 同一失败命令不得无分析地重复执行。先按“配置/依赖缺失、编译、测试、业务断言”分类，再决定修复或停止；每个变更簇仍遵守一次 RED、一次 GREEN 的 Maven 预算。
+
 ### 步骤 0.1：执行模式（默认 Inline）
 
 默认 **Inline Execution**；仅 `--subagent` 强制 Subagent-Driven。**不询问**任务数/模块数（P1-5）。

package/harness/bundles/java/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=d543c354ebf9093a; overlay=java; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=c0ce0eeba998d982; overlay=java; agent=codex; do not edit -->
 # harness-submit — 最终提交（含 worktree 合并）
 
 ## Purpose
@@ -138,7 +138,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/java/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/java/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=d543c354ebf9093a; overlay=java; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=c0ce0eeba998d982; overlay=java; 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/java/codex/harness-test/SKILL.md

@@ -2,7 +2,7 @@
 name: harness-test
 description: 测试执行：读取场景表，执行单元测试+API接口测试+数据兼容验证，输出测试报告。当用户说'跑测试/验证/跑用例/接口测试/单元测试'时使用
 ---
-<!-- generated by harness_deploy.py; core=d543c354ebf9093a; overlay=java; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=c0ce0eeba998d982; overlay=java; agent=codex; do not edit -->
 # harness-test — 测试执行
 
 ## Purpose
@@ -161,7 +161,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/java/codex/harness-test/checklist.md

@@ -37,6 +37,8 @@ description: harness-test 的 Phase 0 环境准备 + Playwright 探测 + 关门
 - [ ] 检查 PowerShell 基础命令：`powershell.exe -NoProfile -Command "$PSVersionTable.PSVersion"` 返回 exitCode=0
 - [ ] 检查 Node 绝对路径：`powershell.exe -NoProfile -Command "& 'C:\nvm4w\nodejs\node.exe' --version"` 返回 exitCode=0
 - [ ] 检查 Maven 可用性：`powershell.exe -NoProfile -Command "mvn -version"` 返回 exitCode=0
+- [ ] 读取 `.mvn/maven.config`，Maven 命令不重复或覆盖已有 `-s` / `-o` / 仓库设置
+- [ ] 离线依赖缺失时仅在项目规则允许联网时执行至多一次非离线 `-nsu` 恢复；失败后停止，禁止切换参数反复重试
 - [ ] 检查安全分类器：上述任一命令是否返回"安全分类器暂时不可用" / Auto mode 拦截 → **不应出现**
 - [ ] 将通过的 `nodeAbsolutePath` / `powershellVersion` / `mvnVersion` 写入 `.harness/changes/<change-name>/runtime/preflight.json`
 - [ ] **任一情况触发硬停**：原文输出"❌ 命令执行模式不可用：PowerShell/Node runner 无法稳定执行..."，**不得继续编译/启动服务/生成 runner，不得长时间等待，不得盲目降级到 Playwright MCP**
@@ -314,4 +316,4 @@ powershell.exe -Command "Copy-Item '<main-dir>/<module>/src/main/resources/appli
 - 请求执行器必须在报告中明确记录（四种执行器，含降级原因）
 - 请求耗时统计必须包含在报告中
 - 服务由 AI 启动的情况，测试结束默认 Stop-Process；**即使测试失败也要进入 finally 清理**
-- final-summary 的 apiTest 状态必须用 OK/PARTIAL/BLOCKED/NOT_RUN/FAIL（不得把 PARTIAL 写成 NOT_RUN）
+- final-summary 的 apiTest 状态必须用 OK/PARTIAL/BLOCKED/NOT_RUN/FAIL（不得把 PARTIAL 写成 NOT_RUN）

package/harness/bundles/java/codex/harness-test/reference.md

@@ -6,6 +6,8 @@ description: harness-test 的 API 测试执行细节、批量 runner、token 缓
 
 ## 命令执行模式 preflight（0.0y）
 
+执行 Maven 前必须读取 `.mvn/maven.config`。项目已声明的 `-s`、`-o`、镜像和仓库设置不得被测试命令重复追加或覆盖。离线依赖缺失时，只有在项目规则允许联网的情况下，才可临时执行至多一次非离线 `-nsu` 恢复；失败后停止并报告缺失依赖，不得在多套 Maven 参数间反复试跑。
+
 `/harness-test` 高度依赖 PowerShell 与 Node。在编译/启动服务/生成 runner **之前**
 必须执行 4 项执行模式检查：
 

package/harness/bundles/java/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/java/cursor/.harness-build.json

@@ -2,5 +2,5 @@
   "schemaVersion": 1,
   "overlay": "java",
   "agent": "cursor",
-  "coreHash": "d437039c3207693b"
+  "coreHash": "d89ba652e358a96b"
 }

package/harness/bundles/java/cursor/README.md

@@ -135,12 +135,12 @@
 
 ## 执行日志与结构化事件机制
 
-每个关联具体变更的 skill 都必须同时维护两类事实源：
+每个关联具体变更的 skill 只维护一个实时事实源：
 
-- `.harness/changes/<change-name>/logs/execution-log.md`：人类审计日志，保留上下文、降级原因、解释性文字。
-- `.harness/changes/<change-name>/events.ndjson`：程序化事件层，供 `harness_archive.py finalize` 生成 `summary-data.json`。
+- `.harness/changes/<change-name>/events.ndjson`：程序化事件层；人类可读上下文、降级原因和解释性文字写入事件 `note`。
+- `.harness/changes/<change-name>/logs/execution-log.md`：由 `harness_events.py` 在 `phase.end` 自动重建的人类审计投影，禁止 Write/Edit。
 
-`execution-log.md` 中记录开始和结束，格式统一：
+渲染后的 `execution-log.md` 阶段格式统一：
 
 ```markdown
 ### [<序号>] harness-<skill> — YYYY-MM-DD HH:MM
@@ -152,16 +152,17 @@
 - **摘要**: <一两句话描述主要产出或问题>
 ```
 
-- harness-plan 创建变更目录时初始化日志文件和 `events.ndjson`
-- 后续每个 skill 开始时追加开始条目和 `phase.start` 事件，结束时追加结束/耗时/结果和 `phase.end` 事件
-- **任何代码修改前必须先追加开始条目**（不得等执行完才补记录）
+- harness-plan 确定 change-name 后先追加 `phase.start`，脚本自动建立事件文件
+- 后续每个 skill 开始时追加 `phase.start` 事件，结束时追加包含耗时/结果的 `phase.end` 事件
+- **任何代码修改前必须先追加 `phase.start`**（不得等执行完才补记录）
 - **降级时必须记录明确原因**（如"Agent 不可用，降级为主会话只读探索"），不可仅写"完成"
-- **禁止末尾一次性补写**——每个阶段开始和结束都用 Edit 追加
+- **禁止末尾一次性补写**——各阶段实时 append 结构化事件，渲染日志不得直接编辑
 - **Bash 拒绝、PowerShell 重试、降级、跳过、用户确认都必须记录**
 - 日志状态统一使用 `✅OK / 🟡WARN(原因) / ❌FAIL(原因)`
 - harness-archive 归档时从日志汇总：时间线、总用时、Skill 调用统计
 - `harness_archive.py finalize/replay` 优先从 `events.ndjson` 汇总命令、验证、artifact、问题和决策；旧 archive 缺少 events 时才回放 execution-log/ledger/manifest
 - sync 默认不关联具体变更目录，仅在已有变更目录时追加日志和 events
+- archive 是例外：finalize 内部负责且仅负责一次 `phase.start` / `phase.end`，调用者不得重复追加阶段边界
 
 ## Skill 目录结构
 
@@ -259,10 +260,10 @@ harness-skills/
 | 阶段 | 强制检查 |
 |------|---------|
 | **plan 阶段 0** | 检查工作区是否有未提交业务代码变更，已有则询问用户处理方式（继续/暂存/回滚/取消），不得假装"编码前规划" |
-| **plan 阶段 3** | 委派前 `harness_preflight.py check-agents --agent harness-explorer`；`usable=false` 或无效返回 → 主会话只读探索，不 retry |
+| **plan 阶段 3** | 委派前 `python <skills-root>/scripts/harness_preflight.py check-agents --skills-root <skills-root> --agent harness-explorer --json`；`usable=false` 或无效返回 → 主会话只读探索，不 retry |
 | **plan 阶段 4/6** | 原生规划协议必须记录风险/复用/替代方案/推荐方案/关键决策，以及任务拆分摘要 |
 | **plan 阶段 5** | 设计文档自审结果必须展示给用户；测试场景表未覆盖维度必须标记为 ⚠️ 缺口，不得全部 ✅ |
-| **run 步骤 0** | 任何代码修改前必须先追加执行日志开始记录和 `events.ndjson` 的 `phase.start` |
+| **run 步骤 0** | 任何代码修改前必须先向 `events.ndjson` 追加 `phase.start`；执行日志由阶段结束事件自动渲染 |
 | **run 轻量验证** | `/harness-run` 默认只做开发反馈：TDD RED/GREEN + REFACTOR + 构建命令增量编译（Java 的 `mvn compile -pl <module>` 等）+ 关门检查 + 写 verification-ledger；除非改了公共模块/数据访问层/sql/权限认证/接口层/数据契约 或用户要求 full-run-validation 或不打算继续 `/harness-test`，否则不默认跑全量测试命令（Java 的 `mvn test` 等）。若跑了全量测试必须写入 ledger 供 test/submit 复用 |
 | **run TDD 降级** | 输出必须写"🟡 静态逻辑验证通过，未执行真实单元测试"，**禁止写"测试全部通过"**；降级标注写在执行日志和覆盖报告中，**不污染业务代码注释**；记录三项：降级原因、静态验证场景列表、待部署后验证场景列表 |
 | **test ledger 复用** | Phase 1 单元测试前先读 `verification-ledger.json`：若 run 阶段已对同一 diffHash/module/profile 跑过单元测试命令（Java 的 `mvn test` 等）且测试通过（Java 的 `Tests run: N, Failures: 0, Errors: 0` / 前端 N passing），可跳过重跑并标记"✅ 复用 harness-run 单元测试结果"；diffHash 不一致 / profile 不一致 / 命令范围更窄 / run 后有行为性修改则不得复用 |
@@ -276,7 +277,7 @@ harness-skills/
 | **submit 步骤 4** | 提交前必须展示四项：实际 staged 文件列表、diff stat、commit message、是否 push |
 | **submit push 前** | `git fetch` 后检查远程是否有新提交；有则**不得直接 pull 后 push**，必须 pull/rebase + 重新 compile/test |
 | **submit hash 记录** | pre-pull local hash + final pushed hash 双标注（主目录）；worktree 模式 submit 段只本地 commit，合并段产生 `mergeFinalHash`，archive 以 `mergeFinalHash` 为准（无则回退 final pushed hash） |
-| **archive 阶段 1** | 必须先 append `phase.start` 事件，**不得等归档完成后才补**；归档前确认：commit 已 push、hash 与 submit/merge 记录一致、test/review 报告状态 |
+| **archive 阶段 1** | 归档前确认 commit 已 push、hash 与 submit/merge 记录一致、test/review 报告状态；阶段边界由 finalize 单进程维护，调用者不额外 append |
 | **archive 文件移动** | 只用 PowerShell 或 Read+Write+验证，**禁止 Bash mv/cp/rm**；移动失败时不删除原目录 |
 | **archive final-summary.html** | 默认运行 `harness_archive.py finalize`：由 events/ledger/log/manifest 生成 `summary-data.json`，再由 `templates/render-summary.mjs` 渲染 `final-summary.html`，内嵌 validate。无测试或无 review 时必须在 JSON 中标记 `NOT_RUN` / `ADVISORY_NOT_RUN`，禁止伪造 100% 通过率。必须真实展示状态演进（✅OK / 🟡WARN / 🔁REUSED / 🔁RETESTED / 📝ADVISORY / 🧹NON_BEHAVIORAL_CLEANUP） |
 

package/harness/bundles/java/cursor/harness-apidoc/SKILL.md

@@ -2,7 +2,7 @@
 name: harness-apidoc
 description: 从 Java 后端代码生成结构化前端 API 文档（Controller/VO/ErrorCode）。使用场景：接口文档、前端接口文档、API 文档生成
 ---
-<!-- generated by harness_deploy.py; core=d437039c3207693b; overlay=java; agent=cursor; do not edit -->
+<!-- generated by harness_deploy.py; core=d89ba652e358a96b; overlay=java; agent=cursor; do not edit -->
 # harness-apidoc — 前端接口文档（Java overlay）
 
 ## Purpose
@@ -57,7 +57,7 @@ description: 从 Java 后端代码生成结构化前端 API 文档（Controller/
 
 ## 执行日志
 
-`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 "<触发指令>"