@hunter-harness/workflow-harness 0.4.9 → 0.4.11

package/harness/bundles/java/pi/harness-execute/SKILL.md

@@ -4,7 +4,7 @@ description: 执行阶段：按变更簇执行 TDD
   编码循环（RED→GREEN→REFACTOR→编译验证），随后完成单元/接口/数据兼容验证并输出测试报告。仅当用户显式调用
   /harness-execute 时使用；不得因用户提到编码/实现/测试就自动触发，也不得被其他阶段 skill 自动接续。
 ---
-<!-- generated by harness_deploy.py; core=410f64c18f167e3f; overlay=java; agent=pi; do not edit -->
+<!-- generated by harness_deploy.py; core=85f25ea4b4eae5cd; overlay=java; agent=pi; do not edit -->
 # harness-execute — 执行（编码 + 验证）
 
 > 2026-08 阶段合并：原 `run`（编码）与 `test`（验证）合并为单一 `execute` 阶段；
@@ -61,13 +61,15 @@ description: 执行阶段：按变更簇执行 TDD
 
 ## Workflow 概要
 
-0. 加载上下文：先 `harness_context.py prepare --project . --change <id> --phase execute --executor <tool> --json`（`--project` 必填），再 `harness_context.py begin --project . --change <id> --phase execute --executor <tool> --json` 校验交接，最后运行 **`harness_gate.py begin --phase execute --change <id>`**。旧名 `--phase run` / `--phase test` 仍被接受并归一为 execute。<br>**交接凭证不必手工补**：v2 计划的 `plan finalize` 不写 context 事务，`prepare` 会在检测到 committed 的 `meta/publication-journals/*.json` 时自动补录 `plan → execute` 凭证（凭证带 `bootstrapSource=plan_publication_journal` 留痕）。仍报 `HANDOFF_REQUIRED`/`LEGACY_BOOTSTRAP_REQUIRED` 说明**没有**这份发布证据——回到 plan 阶段确认发布是否真的完成，**不得**自己拼 `classify + configure-plan + close` 造凭证。<br>**Fixback** 不得拼装底层步骤，必须只调用一次 `harness_fixback.py launch-review --project . --change <id> --change-dir <change-dir> --executor <tool> --skills-root <skills-root> --product-identity <当前产品身份> --json`；返回 `FIXBACK_NOTHING_TO_APPLY` 时直接报告并停止。禁止手写 `events.ndjson` / `phase.end`。
+0. 加载上下文：先 `harness_context.py prepare --project . --change <id> --phase execute --executor <tool> --json`（`--project` 必填），再 `harness_context.py begin --project . --change <id> --phase execute --executor <tool> --json` 校验交接，最后运行 **`harness_gate.py begin --phase execute --change <id>`**。旧名 `--phase run` / `--phase test` 仍被接受并归一为 execute。<br>Git Bash 注意：`--note` 等字符串参数**不要以 `/` 开头**（MSYS 会把它当路径改写成 `C:/Program Files/Git/...`）；以 `/` 开头时先 `MSYS_NO_PATHCONV=1`。<br>**交接凭证不必手工补**：v2 计划的 `plan finalize` 不写 context 事务，`prepare` 会在检测到 committed 的 `meta/publication-journals/*.json` 时自动补录 `plan → execute` 凭证（凭证带 `bootstrapSource=plan_publication_journal` 留痕）。仍报 `HANDOFF_REQUIRED`/`LEGACY_BOOTSTRAP_REQUIRED` 说明**没有**这份发布证据——回到 plan 阶段确认发布是否真的完成，**不得**自己拼 `classify + configure-plan + close` 造凭证。<br>**Fixback** 不得拼装底层步骤，必须只调用一次 `harness_fixback.py launch-review --project . --change <id> --change-dir <change-dir> --executor <tool> --skills-root <skills-root> --product-identity <当前产品身份> --json`；返回 `FIXBACK_NOTHING_TO_APPLY` 时直接报告并停止。禁止手写 `events.ndjson` / `phase.end`。
+
+**Fixback 步骤序列**（0.4.11 起文档化；每步失败都有 recoveryAction）：launch-review 启动批次 → 托管 RED 会话（`harness_runtime.py run-start --verification fixback-red --product-identity <批次 baseProductIdentity，缺省自动注入> -- ...`）→ `harness_fixback.py evidence-template` 生成证据 + `register-evidence` 注册 → 修复 → GREEN 会话同法 → 逐 issue `resolve-issue` → `harness_review.py write-dispositions` 处置 → affected 验证会话 + review 收据 → `harness_fixback.py close --change-dir <change-dir> --batch-id <批次> --final-product-identity <身份>`（批次关闭会同步把 fixback-session 置 CLOSED）→ `harness_gate.py close --phase execute`（fixback 回环自动派生回 submit）。Windows 上命令名写 `mvn` 会 WinError 2——0.4.11 起 launcher 自动解析 .cmd/.exe，更早版本请写全路径。
 0.5. **测试基础设施探测**与**命令执行模式 preflight** → `testing-reference.md`「命令执行模式 preflight」；测试基线已由 gate begin 内部建立，不得再次执行 guard begin
 1. **变更簇 TDD** — `protocols.md` `run-tdd-protocol`；批量 RED/GREEN；按需 `change-cluster-review-protocol`
 2. 构建验证 + **仅**通过 `harness_ledger.py record` 写 ledger（禁止 Write/Edit `verification-ledger.json`）；profile 缺失或陈旧时先 `harness_preflight.py detect --project . --json`；`record --project . --profile-input <key>` 从同一 target 推导 scope、coverage、规范命令与输入闭包
 3. **验证执行**：单元测试可复用则跳过（`harness_ledger.py can-reuse`）；接口测试**强制批量执行器**一次跑完全部场景；数据兼容验证按场景表执行 → `testing-reference.md`
 4. **场景覆盖检查**（场景表映射，禁止用用例数冒充场景数）
-5. **关门检查**（10 项）→ 只执行一次 `harness_gate.py close`；`--to-phase` 可省略——计划后继唯一（排除 fixback 自环）时自动派生并交接（输出含 `derivedToPhase`）。仅 fixback 回环时显式传 `--to-phase execute`。该命令内部关闭 test guard、写 `phase.end`、释放租约、写 handoff 并补传事件；不得再单独调用 test-guard/context close。失败时按结构化 `recoveryAction` 原样重试，已完成步骤幂等复用。
+5. **关门检查**（10 项）→ 只执行一次 `harness_gate.py close`；`--to-phase` 可省略——计划后继唯一（排除 fixback 自环）时自动派生并交接（输出含 `derivedToPhase`）。仅 fixback 回环时显式传 `--to-phase execute`；fixback 批次的 execute 关门自动派生 review 的后继（submit），不会错误地再回一轮 review（0.4.11 起）。该命令内部关闭 test guard、写 `phase.end`、释放租约、写 handoff 并补传事件；不得再单独调用 test-guard/context close。失败时按结构化 `recoveryAction` 原样重试，已完成步骤幂等复用。
 
 **阶段归属规则**：只用 `ownerPhase=execute` 的任务和场景判定本阶段结果。`ownerPhase=review`/`submit` 的场景按计划留给后续阶段属于正常移交，出现在关门返回值的 `deferred` 里，不阻断 execute。合并前 `ownerPhase=run`/`test` 的旧清单经别名表归一为 execute，在 execute 关门时一并到期。
 

package/harness/bundles/java/pi/harness-execute/testing-pitfalls-java.md

@@ -14,3 +14,4 @@
 | 8 | 唯一字段加前缀 | 409/冲突 BLOCKED | 测试数据撞库 | `TEST_<change>_<ts>_<rand>` |
 | 9 | runtime overlay | tracked 配置被改 | 直接 Edit yml | additional-location 叠加 |
 | 10 | Service Gate 先决策 | 旧服务 500 | 端口已有进程 | ensure → needs-user-decision 才问 |
+| 11 | surefire 写死 excludedGroups | `-Dgroups=` 0 命中 + exit 0 假绿 | 插件级配置压过命令行空值覆盖 | pom 改 `${excludedGroups}` 占位；ledger record 会报 ZERO_TESTS_WITH_SELECTOR |

package/harness/bundles/java/pi/harness-knowledge-ingest/SKILL.md

@@ -2,7 +2,7 @@
 name: harness-knowledge-ingest
 description: 确认归档 ZIP 已上传并由 Hunter Platform 在服务端解包、校验和入库。客户端不再构建或维护本地知识索引。
 ---
-<!-- generated by harness_deploy.py; core=410f64c18f167e3f; overlay=java; agent=pi; do not edit -->
+<!-- generated by harness_deploy.py; core=85f25ea4b4eae5cd; overlay=java; agent=pi; do not edit -->
 # harness-knowledge-ingest
 
 知识 ingest 完全由 Hunter Platform 负责。归档完成时，客户端生成一个确定性 ZIP；
@@ -40,6 +40,12 @@ powershell.exe -Command "npx hunter-harness archive upload --file '<archive.zip>
 ```
 
 4. 检查响应中的包哈希、服务端保存状态和 `knowledge_status`。
+4.5. **查询面回读验证（强制）**：`knowledgeStatus=ready` 只是入库回执，不代表可查。
+    执行 `npx hunter-harness knowledge status --json` 确认 `pipeline.results_count`
+    符合预期（有候选的归档应 > 0）；再用归档中的已知关键词跑一次
+    `npx hunter-harness knowledge query "<已知关键词>" --json`，`count=0` 视为
+    ingest 未真正完成——报告 `pipeline.jobs` 状态（queued/extracting/failed）
+    并停止宣称 ready，不得仅凭上传回执收尾。
 5. 只有服务端确认原 ZIP 已持久保存且知识状态为 ready，才删除本地待上传 ZIP。
 6. 上传或 ingest 失败时保留 ZIP 与失败收据；修复连接后重试同一个 ZIP，不重新拼散文件。
 

package/harness/bundles/java/pi/harness-knowledge-query/SKILL.md

@@ -2,7 +2,7 @@
 name: harness-knowledge-query
 description: 在规划、实现或排查前，通过 hunter-harness CLI 查询远端项目知识库。远端不可用时直接报告不可用，不建立本地索引或离线回退。
 ---
-<!-- generated by harness_deploy.py; core=410f64c18f167e3f; overlay=java; agent=pi; do not edit -->
+<!-- generated by harness_deploy.py; core=85f25ea4b4eae5cd; overlay=java; agent=pi; do not edit -->
 # harness-knowledge-query
 
 项目知识以 Hunter Platform 的服务端索引为唯一真源。客户端只提交查询并消费结果：

package/harness/bundles/java/pi/harness-package/SKILL.md

@@ -2,7 +2,7 @@
 name: harness-package
 description: 增量模块打包：拉取最新→编译验证→mvn package→汇总 jar/war。仅当用户显式调用 /harness-package 时使用，不得自动触发。
 ---
-<!-- generated by harness_deploy.py; core=410f64c18f167e3f; overlay=java; agent=pi; do not edit -->
+<!-- generated by harness_deploy.py; core=85f25ea4b4eae5cd; overlay=java; agent=pi; do not edit -->
 # harness-package — 增量模块打包（Java overlay）
 
 ## Purpose

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

@@ -3,7 +3,7 @@ name: harness-plan
 description: 将需求转化为设计文档+实施计划+完整测试场景表，必须在编码前完成。仅当用户显式调用 /harness-plan 或明确要求进入
   Harness 规划阶段时使用；不得因用户描述需求就自动触发。
 ---
-<!-- generated by harness_deploy.py; core=410f64c18f167e3f; overlay=java; agent=pi; do not edit -->
+<!-- generated by harness_deploy.py; core=85f25ea4b4eae5cd; overlay=java; agent=pi; do not edit -->
 # harness-plan — 需求规划
 
 ## Purpose
@@ -67,10 +67,10 @@ description: 将需求转化为设计文档+实施计划+完整测试场景表
 | 阶段 | 动作 |
 |------|------|
 | 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.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`。返回里的 `legacyBootstrap: true` 只是「本次引导前还没有任何交接凭证」的标记（首个阶段的正常状态），不是项目结构需要迁移 |
 | 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` 并继续，不建立本地索引或离线回退 |
+| 1 | 直接执行一次 `npx hunter-harness knowledge query "<用户需求原文>" --limit 10 --json`。这是唯一执行入口，不扫描技能目录、不查找其他脚本；失败记 `issue` 并继续，不建立本地索引或离线回退。**查询结果（含 0 条）必须落事件**：`harness_events.py append --phase plan --type command --name "knowledge query" --message "count=<n>" --json`（query 回执的 `receipt.index_generation` 反映索引代数；0 条时可先跑 `npx hunter-harness knowledge status --json`（0.4.11+）区分「job 未跑 / 失败 / 结果为空」） |
 | 2 | 歧义优先检查 + 复杂度分级；先确认会改变实现方向的语义歧义 |
 | 3 | 按复杂度执行有预算的代码探索；简单修复不得扩散到无关模块 |
 | 4 | **设计审批包** blocking user confirmation；确认事件早于 approved 设计文档和 `meta/worktree.json` |

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

@@ -214,6 +214,7 @@ description: harness-plan 的阶段检查清单和覆盖检查列表。仅在执
 
 - [ ] **v2**：只手写 `meta/plan-evidence-input.json`。`plans/*.md` 由 finalize 派生，手写的会被渲染覆盖，只是白写
 - [ ] 任何缺失**都不得手工补写**（包括 `phase.end`）；回到对应阶段改自然输入/staging 后重跑
+- [ ] **phase.start/end 事件对完整**：plan 不经 gate close，0.4.11 起 `context close`/`handoff` 会自动补齐缺失的 `phase.end`（返回体 `phaseEndPair.code=PHASE_END_AUTO_PAIRED`）；发现平台 Run 监控计时不停时先查这对事件，而不是手工写事件
 - [ ] v2 过渡期**不写** `meta/plan-finalization.json` 与 `logs/execution-log.md`；缺这两项不算失败，不得为凑表手工补
 
 

package/harness/bundles/java/pi/harness-plan/reference.md

@@ -376,6 +376,14 @@ finalize 硬性要求证据包顶层 `adversarial_review` 收据，缺失即 `PL
 1. 先完成阶段 7.5 对抗评审，把结论写成草稿 `meta/plan-review-draft.json`：
    `{ "reviewer_identity": "inline:<标识>", "findings": [] }`
    （`review_mode` 缺省 `inline`；`completed_at` 缺省取当前时间；`findings` 为空数组表示无发现）
+
+   **草稿完整契约**（0.4.11 起可 `plan review-record --print-template` 取合法骨架）：
+   顶层键集精确为 `reviewer_identity / review_mode? / findings? / completed_at?`；
+   `reviewer_identity` 匹配 `^[a-z][a-z0-9_.:-]{0,159}$`。`findings` 元素键集精确为
+   `finding_id / category / severity / source_refs / message_zh / suggested_location`，
+   其中 `severity ∈ {advisory, blocking}`、`source_refs` 至少一条非空字符串、
+   `finding_id` 同上面的 identity 规则。缺键/多键/枚举越界都会在
+   `PLAN_REVIEW_RECORD_INPUT_INVALID` 的 `problems[]` 里逐条给出 `field_path`。
 2. 跑 `plan review-record`：CLI 内部重跑 layer1/layer2/layer3 算出权威 `input_hash`，
    代算 `findings_hash`，把完整收据写回证据包顶层 `adversarial_review`（缺省覆盖 `--input`，
    可用 `--output` 写到别处）。stdout 的 `review_required: false` 表示该包未触发评审、收据不会被消费。

package/harness/bundles/java/pi/harness-pull/SKILL.md

@@ -3,7 +3,7 @@ name: harness-pull
 description: 从 Hunter Platform 下拉配置/规则/架构/指令（及显式来源分支的分支文件恢复）。仅当用户显式调用
   /harness-pull 或明确说'从平台拉取/恢复'时使用；不得自动触发。
 ---
-<!-- generated by harness_deploy.py; core=410f64c18f167e3f; overlay=java; agent=pi; do not edit -->
+<!-- generated by harness_deploy.py; core=85f25ea4b4eae5cd; overlay=java; agent=pi; do not edit -->
 # harness-pull — 从 Hunter Platform 下拉与恢复
 
 ## Purpose

package/harness/bundles/java/pi/harness-push/SKILL.md

@@ -3,7 +3,7 @@ name: harness-push
 description: 上传本地配置/规则/架构/指令（及显式归档）到 Hunter Platform。仅当用户显式调用 /harness-push
   或明确说'上传到平台'时使用；不得因存在本地修改就自动触发。
 ---
-<!-- generated by harness_deploy.py; core=410f64c18f167e3f; overlay=java; agent=pi; do not edit -->
+<!-- generated by harness_deploy.py; core=85f25ea4b4eae5cd; overlay=java; agent=pi; do not edit -->
 # harness-push — 上传到 Hunter Platform
 
 ## Purpose

package/harness/bundles/java/pi/harness-review/SKILL.md

@@ -4,7 +4,7 @@ description: 6维度代码审查（架构/安全/规范/兼容/测试/性能）
   .harness/context-index.json）和测试场景表，在隔离上下文运行。仅当用户显式调用 /harness-review 时使用；不得在
   test 结束后自动接续执行。
 ---
-<!-- generated by harness_deploy.py; core=410f64c18f167e3f; overlay=java; agent=pi; do not edit -->
+<!-- generated by harness_deploy.py; core=85f25ea4b4eae5cd; overlay=java; agent=pi; do not edit -->
 # harness-review — 代码审查
 
 ## Purpose

package/harness/bundles/java/pi/harness-submit/SKILL.md

@@ -3,7 +3,7 @@ name: harness-submit
 description: 最终提交封装：验证→中文 commit→提交/推送；worktree 模式含 --no-ff 合并回主分支。仅当用户显式调用
   /harness-submit（或 /harness-merge 重入合并段）时使用；用户口头说'提交/commit/push'时必须先确认，不得自动触发。
 ---
-<!-- generated by harness_deploy.py; core=410f64c18f167e3f; overlay=java; agent=pi; do not edit -->
+<!-- generated by harness_deploy.py; core=85f25ea4b4eae5cd; overlay=java; agent=pi; do not edit -->
 # harness-submit — 最终提交（含 worktree 合并）
 
 ## Purpose

package/harness/bundles/java/pi/harness-sync/SKILL.md

@@ -4,7 +4,7 @@ description: Use when the user asks to synchronize, refresh, or validate Harness
   metadata, adapters, remote knowledge ownership, instruction entrypoints,
   config origins, or CodeGraph status.
 ---
-<!-- generated by harness_deploy.py; core=410f64c18f167e3f; overlay=java; agent=pi; do not edit -->
+<!-- generated by harness_deploy.py; core=85f25ea4b4eae5cd; overlay=java; agent=pi; do not edit -->
 # harness-sync
 
 ## Purpose

package/harness/bundles/java/pi/scripts/harness_context.py

@@ -478,6 +478,55 @@ def _phase_has_ended(event_paths: list[Path], phase: str) -> bool:
     )
 
 
+def _ensure_phase_end_event(
+    contract_root: Path,
+    *,
+    phase: str,
+    status: str,
+    executor: str,
+) -> dict[str, Any] | None:
+    """补齐 phase.start/end 事件对（P0-2）。
+
+    平台 Run 计时由 events-sync 上报的 phase.start/end 事件对驱动。不经
+    gate close 收尾的阶段（典型：plan 走 finalize + context close）只写
+    transitions 收据，phase.end 永远缺席，平台计时永不停——连续两个 change
+    复现，属结构性缺口（2026-08-30 sales-insight-agent demo-datasource 实测）。
+    close_transition 是所有跨阶段推进的共同通道，在此按事件配对补齐：
+    有 start 无 end → 复用 start 的 run_id/attempt 代写 end；已有 end（gate
+    close 先行写入）或连 start 都没有 → 不动，返回 None。
+    """
+    import harness_events as he
+
+    events_file = contract_root / "events.ndjson"
+    events = _read_ndjson(events_file)
+    starts = [
+        item
+        for item in events
+        if hpaths.resolve_phase_name(item.get("phase")) == phase
+        and item.get("type") == "phase.start"
+    ]
+    if not starts or any(
+        hpaths.resolve_phase_name(item.get("phase")) == phase
+        and item.get("type") == "phase.end"
+        for item in events
+    ):
+        return None
+    start = starts[-1]
+    result = he.append_event(
+        contract_root,
+        phase=phase,
+        type_="phase.end",
+        run_id=str(start.get("run_id") or f"{phase}_unknown"),
+        attempt=int(start.get("attempt") or 1),
+        status=status,
+        executor_tool=executor,
+        note="context close 自动补齐 phase.end（平台计时事件对配对）",
+    )
+    if not result.get("ok"):
+        return {"code": "PHASE_END_PAIR_FAILED", "detail": result}
+    return {"code": "PHASE_END_AUTO_PAIRED", "event": result.get("event")}
+
+
 def _reselect_review_fixback(
     project: Path,
     change: str,
@@ -1334,6 +1383,12 @@ def close_transition(
             and latest.get("artifacts") == artifact_entries
             and (executor is None or latest.get("executor") == executor)
         ):
+            paired = _ensure_phase_end_event(
+                contract_root,
+                phase=from_phase,
+                status=status,
+                executor=executor or str(latest.get("executor") or "unknown"),
+            )
             return {
                 "ok": True,
                 "code": "TRANSITION_ALREADY_CLOSED",
@@ -1341,6 +1396,7 @@ def close_transition(
                 "receipt": latest,
                 "path": str(paths["transitions"]),
                 "invalidation": None,
+                "phaseEndPair": paired,
             }
         return {"ok": False, "code": "CONTEXT_LEASE_REQUIRED"}
     try:
@@ -1397,6 +1453,12 @@ def close_transition(
     receipt["receiptHash"] = _payload_hash(receipt)
     _append_ndjson(paths["transitions"], receipt)
     paths["lease"].unlink(missing_ok=True)
+    paired = _ensure_phase_end_event(
+        contract_root,
+        phase=from_phase,
+        status=status,
+        executor=effective_executor,
+    )
     invalidation = None
     if to_phase == "execute" and from_phase in {"execute", "review"}:
         invalidation = _invalidate_for_fixback(
@@ -1411,6 +1473,7 @@ def close_transition(
         "receipt": receipt,
         "path": str(paths["transitions"]),
         "invalidation": invalidation,
+        "phaseEndPair": paired,
     }
 
 
@@ -1898,7 +1961,7 @@ def build_parser() -> argparse.ArgumentParser:
     prepare = sub.add_parser("prepare")
     prepare.add_argument("--json", action="store_true")
     prepare.add_argument("--project", required=True, type=Path)
-    prepare.add_argument("--change")
+    prepare.add_argument("--change", "--change-dir", dest="change")
     prepare.add_argument("--phase", required=True)
     prepare.add_argument("--executor", required=True)
     prepare.add_argument("--title")
@@ -1907,7 +1970,7 @@ def build_parser() -> argparse.ArgumentParser:
     bootstrap = sub.add_parser("bootstrap-plan")
     bootstrap.add_argument("--json", action="store_true")
     bootstrap.add_argument("--project", required=True, type=Path)
-    bootstrap.add_argument("--change", required=True)
+    bootstrap.add_argument("--change", "--change-dir", dest="change", required=True)
     bootstrap.add_argument("--executor", required=True)
     bootstrap.add_argument("--title")
     bootstrap.add_argument("--stage", default="plan", choices=["plan", "post-run"])
@@ -1915,7 +1978,7 @@ def build_parser() -> argparse.ArgumentParser:
     close = sub.add_parser("close")
     close.add_argument("--json", action="store_true")
     close.add_argument("--project", required=True, type=Path)
-    close.add_argument("--change", required=True)
+    close.add_argument("--change", "--change-dir", dest="change", required=True)
     close.add_argument("--from-phase", required=True)
     close.add_argument("--to-phase", required=True)
     close.add_argument("--executor", required=True)
@@ -1924,7 +1987,7 @@ def build_parser() -> argparse.ArgumentParser:
     begin = sub.add_parser("begin")
     begin.add_argument("--json", action="store_true")
     begin.add_argument("--project", required=True, type=Path)
-    begin.add_argument("--change", required=True)
+    begin.add_argument("--change", "--change-dir", dest="change", required=True)
     begin.add_argument("--phase", required=True)
     begin.add_argument("--executor", required=True)
     handoff = sub.add_parser(
@@ -1933,7 +1996,7 @@ def build_parser() -> argparse.ArgumentParser:
     )
     handoff.add_argument("--json", action="store_true")
     handoff.add_argument("--project", required=True, type=Path)
-    handoff.add_argument("--change", required=True)
+    handoff.add_argument("--change", "--change-dir", dest="change", required=True)
     handoff.add_argument("--to-phase", required=True)
     handoff.add_argument(
         "--from-phase",
@@ -1946,20 +2009,20 @@ def build_parser() -> argparse.ArgumentParser:
     )
     renew.add_argument("--json", action="store_true")
     renew.add_argument("--project", required=True, type=Path)
-    renew.add_argument("--change", required=True)
+    renew.add_argument("--change", "--change-dir", dest="change", required=True)
     renew.add_argument("--executor", required=True)
     renew.add_argument("--ttl-seconds", type=int, default=3600)
     configure = sub.add_parser("configure-plan")
     configure.add_argument("--json", action="store_true")
     configure.add_argument("--project", required=True, type=Path)
-    configure.add_argument("--change", required=True)
+    configure.add_argument("--change", "--change-dir", dest="change", required=True)
     configure.add_argument("--phases", required=True)
     configure.add_argument("--operator", required=True)
     configure.add_argument("--reason", required=True)
     view = sub.add_parser("view")
     view.add_argument("--json", action="store_true")
     view.add_argument("--project", required=True, type=Path)
-    view.add_argument("--change", required=True)
+    view.add_argument("--change", "--change-dir", dest="change", required=True)
     return parser
 
 

package/harness/bundles/java/pi/scripts/harness_events.py

@@ -884,22 +884,32 @@ def build_event(args: argparse.Namespace, existing: list[dict[str, Any]]) -> dic
 def validate_append_event(args: argparse.Namespace) -> tuple[str, str] | None:
     """Validate type-specific append fields before any file is mutated."""
     event_type = str(args.type)
-    for field in _EVENT_REQUIRED_FIELDS.get(event_type, ()):
-        value = getattr(args, field, None)
-        if value is None or (isinstance(value, str) and not value.strip()):
-            return (
-                "EVENT_REQUIRED_FIELD",
-                f"EVENT_REQUIRED_FIELD: {event_type} requires --{field.replace('_', '-')}",
-            )
+    missing = [
+        f"--{field.replace('_', '-')}"
+        for field in _EVENT_REQUIRED_FIELDS.get(event_type, ())
+        if getattr(args, field, None) is None
+        or (isinstance(getattr(args, field, None), str)
+            and not getattr(args, field).strip())
+    ]
+    if missing:
+        # 一次性列出全部缺失字段——逐个报错会让调用方每个字段往返一轮（E-3）
+        return (
+            "EVENT_REQUIRED_FIELD",
+            f"EVENT_REQUIRED_FIELD: {event_type} requires " + ", ".join(missing),
+        )
     allowed = _EVENT_ALLOWED_FIELDS[event_type]
-    for field in OPTIONAL_FIELDS:
-        value = getattr(args, field, None)
-        if value is not None and field not in allowed:
-            return (
-                "EVENT_FIELD_NOT_ALLOWED",
-                "EVENT_FIELD_NOT_ALLOWED: "
-                f"{event_type} does not accept --{field.replace('_', '-')}",
-            )
+    disallowed = [
+        f"--{field.replace('_', '-')}"
+        for field in OPTIONAL_FIELDS
+        if getattr(args, field, None) is not None and field not in allowed
+    ]
+    if disallowed:
+        # 一次列出全部不被接受的字段——逐个报错会让调用方每字段往返一轮（R-4）
+        return (
+            "EVENT_FIELD_NOT_ALLOWED",
+            f"EVENT_FIELD_NOT_ALLOWED: {event_type} does not accept "
+            + ", ".join(disallowed),
+        )
     for field, length in (("trace_id", 32), ("span_id", 16), ("parent_span_id", 16)):
         value = getattr(args, field, None)
         if value is not None and not re.fullmatch(rf"[0-9a-f]{{{length}}}", str(value)):
@@ -2146,7 +2156,7 @@ def build_parser() -> argparse.ArgumentParser:
         parents=[common],
         help="append one event and auto-render execution-log",
     )
-    p_append.add_argument("--change-dir", required=True)
+    p_append.add_argument("--change-dir", "--change", dest="change_dir", required=True)
     p_append.add_argument("--phase", required=True)
     p_append.add_argument("--type", required=True)
     p_append.add_argument("--command", default=None)
@@ -2200,7 +2210,7 @@ def build_parser() -> argparse.ArgumentParser:
         parents=[common],
         help="validate and append many events under one lock (H-15)",
     )
-    p_batch.add_argument("--change-dir", required=True)
+    p_batch.add_argument("--change-dir", "--change", dest="change_dir", required=True)
     p_batch.add_argument(
         "--file",
         required=True,
@@ -2213,7 +2223,7 @@ def build_parser() -> argparse.ArgumentParser:
         parents=[common],
         help="re-render execution-log.md from events.ndjson",
     )
-    p_render.add_argument("--change-dir", required=True)
+    p_render.add_argument("--change-dir", "--change", dest="change_dir", required=True)
     p_render.set_defaults(func=cmd_render)
 
     p_summary = sub.add_parser(
@@ -2221,7 +2231,7 @@ def build_parser() -> argparse.ArgumentParser:
         parents=[common],
         help="summarize phases/issues from events.ndjson",
     )
-    p_summary.add_argument("--change-dir", required=True)
+    p_summary.add_argument("--change-dir", "--change", dest="change_dir", required=True)
     p_summary.set_defaults(func=cmd_summary)
 
     return parser

package/harness/bundles/java/pi/scripts/harness_fixback.py

@@ -75,6 +75,14 @@ def _write_json(path: Path, value: dict[str, Any]) -> None:
         temporary.unlink(missing_ok=True)
 
 
+def _read_json(path: Path) -> Any:
+    try:
+        value = json.loads(path.read_text(encoding="utf-8-sig"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    return value
+
+
 def _load(change_dir: Path, batch_id: str) -> dict[str, Any]:
     path = _batch_path(change_dir, batch_id)
     try:
@@ -1186,7 +1194,21 @@ def evidence_template(
         "provenance": provenance,
     }
     target = Path(out) if out else Path("runtime") / f"fixback-{resolved_id}.json"
-    path = target if target.is_absolute() else (change_dir / target)
+    if target.is_absolute():
+        path = target
+    else:
+        # F-3：与 ledger --out 同一类坑——相对路径已含 change-dir 前缀时直接拼
+        # change_dir 会产生嵌套幽灵目录（2026-08-31 实测）。前缀命中按 cwd 解析。
+        cwd = Path.cwd().resolve()
+        change_resolved = change_dir.resolve()
+        if _is_within(change_resolved, [cwd]):
+            change_rel = change_resolved.relative_to(cwd)
+            if target.parts[: len(change_rel.parts)] == change_rel.parts:
+                path = cwd / target
+            else:
+                path = change_dir / target
+        else:
+            path = change_dir / target
     path = path.resolve()
     if not _is_within(path, [change_dir.resolve(), state_root, _project_root(change_dir)]):
         return {
@@ -1708,6 +1730,20 @@ def close_batch(
         }
     )
     _write_json(_batch_path(change_dir, batch_id), batch)
+    # F-5：批次关闭会同步把托管会话置为 CLOSED——否则 session 永远 ACTIVE，
+    # 后续 launch-review 被 CONTEXT_PREPARATION_ACTIVE 幂等保护误拦（2026-08-31
+    # demo-datasource 实测）。
+    session_file = _session_path(change_dir)
+    session = _read_json(session_file)
+    if (
+        isinstance(session, dict)
+        and session.get("batchId") == batch_id
+        and session.get("status") == "ACTIVE"
+    ):
+        session["status"] = "CLOSED"
+        session["nextStep"] = "done"
+        session["updatedAt"] = closed_at
+        _write_json(session_file, session)
     return batch