@hunter-harness/workflow-harness 0.2.69 → 0.2.70

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

@@ -357,7 +357,14 @@ npx hunter-harness plan evidence-pack --input .harness/changes/<cn>/meta/plan-ev
 npx hunter-harness plan finalize --input .harness/changes/<cn>/meta/plan-evidence.json
 ```
 
-**自然输入文件**（`meta/plan-evidence-input.json`，权威定义 `packages/cli/src/commands/plan-evidence-pack.ts` 的 `EvidencePackInputFile`）由规划阶段逐步沉淀，各字段定稿时点不得倒置：
+**自然输入文件**（`meta/plan-evidence-input.json`，权威定义 `packages/cli/src/commands/plan-evidence-pack.ts` 的 `EvidencePackInputFile`）由规划阶段逐步沉淀，各字段定稿时点不得倒置。
+
+> 📋 **先取骨架，别猜结构**：CLI 自带模板输出，不需要去找 TS 接口或翻 npx 缓存——
+> ```bash
+> npx hunter-harness plan evidence-pack --print-template > .harness/changes/<cn>/meta/plan-evidence-input.json
+> ```
+> 输出是带 `<...>` 占位符的完整骨架，逐项替换即可；替换完 grep 一次 `<` 自检有无遗漏。
+> `--print-template` 不读写任何文件，只打到 stdout。
 
 | 字段 | 内容 | 定稿阶段 |
 |------|------|:---:|
@@ -379,6 +386,29 @@ npx hunter-harness plan finalize --input .harness/changes/<cn>/meta/plan-evidenc
 - **legacy 收据**：过渡期（阶段 14 前）v2 路径不写 `plan-finalization.json`；消费方若仍读 legacy receipt，由兼容投影单独提供，不得反向要求 v2 双写。
 - **回退**：v2 自然输入不完整（如缺真实审批记录）时才允许走 Python finalizer（legacy 路径）；同一次发布不得两条路径混用。
 
+### 发布后修订计划（republish）
+
+计划发布后又要改产物，是**正常且高频**的情况——用户看完计划补一个回归场景、修正一条任务、调整验收标准。这时不要与哈希守卫搏斗：
+
+```bash
+python <skills-root>/scripts/harness_plan_finalize.py republish \
+  --change-dir ".harness/changes/<cn>" --staging-dir ".harness/changes/<cn>/runtime/plan-staging" \
+  --change <cn> --run-id "plan_$(uuidgen)" --reason "<为什么要改>" --json
+```
+
+它一次性完成整套动作：校验 staging → 分配新 attempt（自动取已用最大值 +1）→ 追加 `phase.start` → 替换收据 → 重新派生 `scenario-manifest.json` 与 `implementation-checkpoints.json` → 写 `phase.end`。收据里保留 `supersedes`（被取代的 hash/runId/attempt）与 `amendReason`，修订全程可审计。
+
+| 约束 | 说明 |
+|------|------|
+| `--reason` 必填 | 修订已发布计划必须留下理由，否则 `PLAN_AMEND_REASON_REQUIRED` |
+| `--run-id` 必须全新 | 复用旧 run-id 报 `PLAN_AMEND_RUN_ID_IN_USE`（attempt 与 run-id 一一绑定） |
+| 首次发布不能用它 | 无收据时报 `PLAN_NOT_FINALIZED`，首次发布走 `finalize` |
+| 内容没变则空操作 | 返回 `idempotent:true`，不写事件、不消耗 attempt |
+
+⚠️ **绝对不要手改 `meta/scenario-manifest.json`**。它是 finalizer 从 `test-scenarios.md` 派生的产物，手改会造成真实漂移：`verify` 报 `ARTIFACT_HASH_DRIFT`，run 阶段 `validate_plan_handoff` 也会记 WARN。`republish` 会重新派生它，这才是唯一正确入口。
+
+> 直接重跑 `finalize` 会报 `PLAN_FINALIZATION_HASH_CONFLICT`——这是守卫在防止发布后产物被悄悄改动，不是 bug。报错信息里已经给出 `republish` 命令行。
+
 ### Plan 结束行为规则
 
 - **禁止询问执行模式**：Subagent-Driven / Inline Execution 属于 /harness-run 阶段

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

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

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

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

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

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

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

@@ -3,7 +3,7 @@ name: harness-run
 description: 按变更簇执行 TDD 编码循环（RED→GREEN→REFACTOR→编译验证），逐变更簇实现计划中的任务。仅当用户显式调用
   /harness-run 时使用；不得因用户提到编码/实现就自动触发，也不得被其他阶段 skill 自动接续。
 ---
-<!-- generated by harness_deploy.py; core=99e00f374c938811; overlay=java; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=9a77548e8651f505; overlay=java; agent=codex; do not edit -->
 # harness-run — 需求编码
 
 ## Purpose
@@ -68,6 +68,8 @@ description: 按变更簇执行 TDD 编码循环（RED→GREEN→REFACTOR→编
 
 **阶段归属规则**：只用 `ownerPhase=run` 的任务和场景判定编码阶段结果。`ownerPhase=test` 的任务或场景按计划留给测试阶段属于正常移交，必须记录为“待测试阶段执行”，不得将编码阶段降级为 WARN；只有 run 自身负责的工作未完成、验证降级或证据异常时才使用 WARN。
 
+> 关门脚本与本规则一致：`harness_gate.py close --phase run` 的 C9 场景覆盖只要求 `ownerPhase` 为 `plan`/`run` 的必需场景有通过 receipt，`ownerPhase=test` 的场景出现在返回值的 `deferred` 里，不阻断 run。若 run 关门报 `REQUIRED_SCENARIO_NOT_EXECUTED` 且缺的是接口/端到端场景，那是 `meta/scenario-manifest.json` 里 `ownerPhase` 标错了（或老清单没声明），应当修清单——**不要**为了过门在 run 阶段起服务补跑本属 test 的验证。
+
 **Fixback**：入口只用 `launch-review`，后续问题处理通过 `resolve-issue/close` 驱动，不得把修复说明当成新的普通 Run。只读取返回的受影响问题和文件；验证仅失效与 `changedFiles` 相交的目标，其他 Test/Review 证据继续复用。RED 优先；`manual`、`workflow` 或未选用的建议不进入代码批次，使用中文记录处理结论。
 
 **执行器边界**：优先使用项目 build profile 和已有测试入口。禁止为了绕过 ESM、路径或参数问题临时生成 `.js`、`require` 脚本；需要文件式 runner 时使用项目已有入口，确需新增时遵循项目模块类型（例如 ESM 使用 `.mjs`）。runner 包装说明写入 `runnerCommand` 元数据，不得拼进账本的规范 `command`。

package/harness/bundles/java/codex/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=99e00f374c938811; overlay=java; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=9a77548e8651f505; overlay=java; agent=codex; do not edit -->
 # harness-submit — 最终提交（含 worktree 合并）
 
 ## Purpose

package/harness/bundles/java/codex/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=99e00f374c938811; overlay=java; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=9a77548e8651f505; overlay=java; agent=codex; do not edit -->
 # harness-sync
 
 ## Purpose

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

@@ -3,7 +3,7 @@ name: harness-test
 description: 测试执行：读取场景表，执行单元测试+API接口测试+数据兼容验证，输出测试报告。仅当用户显式调用 /harness-test
   时使用；不得在 run 结束后自动接续执行。
 ---
-<!-- generated by harness_deploy.py; core=99e00f374c938811; overlay=java; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=9a77548e8651f505; overlay=java; agent=codex; do not edit -->
 # harness-test — 测试执行
 
 ## Purpose
@@ -195,6 +195,8 @@ python <skills-root>/scripts/harness_test_guard.py record --project . --change-d
 
 先读 `.harness/changes/<change-name>/runtime/credential-cache.json`（认证凭证缓存，按项目认证机制；token/SSO 为常见实现），本地轻量接口验证通过则复用，失败才走远程认证。接口测试执行器用 request context / 原生 HTTP 客户端直连本地 baseURL，**不得依赖浏览器当前页面 origin**。同一次流程内凭证刷新计数 > 1 → 🟡 WARN。**不得在报告/日志/对话总结中输出明文凭证**。详见 `reference.md`「认证凭证缓存与复用」。
 
+> ⛔ **验证码 = 硬停，不是待解的技术问题。** 登录响应出现 `验证码` / `captcha` / `blockPuzzle` / `slider` / `geetest` 等特征时，**禁止**编写或运行任何求解代码（图像匹配、OCR、打码平台、反编译服务端找容差均在禁止之列）。立即记 `apiTest=BLOCKED`，请用户手工把凭证写入 `runtime/credential-cache.json` 或临时关闭测试环境验证码，并提示 `.harness/config/harness-test-config.md` 的认证方式已过期。详见 `pitfalls.md` 规则 31。
+
 ### 九、测试报告状态规则
 
 整体 ✅OK / 🟡WARN / ❌FAIL 三态；API 维度使用 `OK` / `PARTIAL` / `BLOCKED` / `NOT_RUN` / `FAIL` 五态。**不得把「5 PASS + 9 BLOCKED + 1 FAIL」写成 `apiTest=NOT_RUN`**，正确为 `apiTest=PARTIAL`。P0 场景 BLOCKED 不得仍 OK。详见 `reference.md`「结果分级规则」。

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

@@ -2,16 +2,16 @@
 description: harness-test 的踩坑规则（来自真实对话日志）。执行测试前必须通读，遇到测试失败时重新参考。
 ---
 
-# 避坑规则（30 条）
+# 避坑规则（32 条）
 
-> 以下规则来自真实对话日志（2026-06-12 ~ 06-24），每个都有明确的现象和根因。
+> 以下规则来自真实对话日志（2026-06-12 ~ 08-17），每个都有明确的现象和根因。
 > 执行 `harness-test` 时必须通读，避免重蹈覆辙。
 
 | # | 规则 | 现象 | 根因 | 解法 |
 |:--:|------|------|------|------|
 | 1 | 凭证可展示但注意安全 | 对话日志记录了凭证 | Bearer 凭证被粘贴到聊天中 | 凭证可以在对话中展示用于调试，但不要写入持久化文件（测试报告、执行日志等） |
 | 2 | 不用 curl 发中文 | `Invalid UTF-8 start byte 0xb2` | Windows curl 默认 GBK 编码 | 用 PowerShell Invoke-WebRequest 或 Playwright fetch |
-| 3 | 必须带租户标识 | 所有接口 500 | 租户上下文为空 | 请求头加租户标识（见 build-profile.httpHeaders） |
+| 3 | 必须带租户标识 | 所有接口 500，或 200 但 `data:null` | 租户上下文为空，或请求头租户值与测试数据行的租户不一致 | 请求头加租户标识（见 build-profile.httpHeaders）；**取值必须等于测试数据实际所属租户**，先查数据行的租户列再填，不要默认写 0 |
 | 4 | 认证降级 | 接口 401 "账号未登录" | 本地无认证服务 | 应用配置放行（如 permit-all-urls）或权限降级 |
 | 5 | 错误码双格式兼容 | 测试断言失败 | 预期 `1_003_002_009`，实际 `1003002009` | 自动兼容下划线和数字两种格式 |
 | 6 | 编译产物确认 | 修改代码后测试结果不变 | IDE 热重载未触发 | 测试前编译（如 `mvn compile -o`） |
@@ -39,6 +39,8 @@ description: harness-test 的踩坑规则（来自真实对话日志）。执行
 | 28 | **已有服务未先决策就跑业务接口** | 旧服务不含新代码，接口 500 后才发现版本不匹配 | 检测到已有应用服务（端口被占）后，未先展示服务决策门就跑业务接口 | 先展示服务决策门，询问复用/重启/跳过/停止；询问前只允许 health/meta 检查 |
 | 29 | **启动命令反复试相对配置叠加 / 中文路径** | 相对路径或中文路径导致应用读不到运行时配置叠加，启动失败 | 默认只用 `C:/temp/harness-test-overlay/<change>/application-harness-test.yml` ASCII 绝对路径，并固化已知良好测试配置 |
 | 30 | **伪 diffHash 导致错误复用** | `3files-84plus-5minus` 不能证明代码未变 | 用 `git diff --binary` 生成 patch 并计算 SHA-256，ledger 只认 `sha256:<hash>` |
+| 31 | **尝试破解验证码 / 人机验证** | 认证服务返回"验证码不能为空"，AI 写图像识别脚本反复试坐标（实测 28 次 / 4 种算法全失败） | 测试配置里的账号密码登录流程被加了滑块/图形验证码，配置未同步 | **硬停**。禁止编写或运行任何验证码求解代码；立即标 `apiTest=BLOCKED`，请用户手工提供凭证写入 `runtime/credential-cache.json`，或临时关闭测试环境验证码 |
+| 32 | **预存环境缺陷被当成本次变更的阻塞** | `unitTestFull` 144 个测试挂 1 个，根因是别人提交引入的缺省配置缺失 | 全量验证把预存缺陷和本次 diff 混在一起判定 | 先用 `git log -S` + diff 触点证明与本次变更无关，再按「预存缺陷」上报并请用户决策（修根因 / 记 🟡WARN / 停止），**不得**擅自改 tracked 配置或排除测试 |
 
 
 ## 详细说明
@@ -257,6 +259,35 @@ $cred = $resp.data.accessToken
 **后果**：代码已变却复用旧测试结果，掩盖回归问题
 **正确做法**：用 `git diff --binary` 生成 patch 并计算 SHA-256，ledger 只认 `sha256:<hash>` 格式。diffHash 不一致时必须重跑相关测试。
 
+### 规则 31：尝试破解验证码 / 人机验证
+**严重度**：❌FAIL（硬性禁止）
+**场景**：本地服务已起来，但业务接口需要真实登录上下文；认证服务登录接口返回 `验证码不能为空` / 返回滑块拼图（如 AJ-Captcha `blockPuzzle`）/ 图形验证码 / 短信验证码
+**后果**：真实日志里 AI 连续写了 4 版求解算法（边缘求和 → NCC 模板匹配 → 二维边缘匹配 → 一维归一化互相关）、反编译服务端 jar 找容差、共 28 次尝试全部失败，烧掉整段会话，最终仍然 BLOCKED
+**正确做法**：**验证码是安全控制，不是待调试的技术问题。** 一旦识别到验证码/人机验证：
+
+1. **立即停止**，不得编写、下载或运行任何验证码求解代码（图像匹配、OCR、打码平台、反编译校验逻辑找容差都在禁止之列）
+2. 该维度记 `apiTest=BLOCKED`，受影响场景标 🟡 BLOCKED，**不得**伪造 receipt 或把未执行写成通过
+3. 向用户输出原文，并给出三条可选出路：
+   - 用户手工登录后把凭证写入 `.harness/changes/<change-name>/runtime/credential-cache.json`（推荐，执行器本来就先读 cache）
+   - 用户在测试环境临时关闭验证码开关，AI 重跑
+   - 本轮跳过接口验证，按 BLOCKED 归档，留待环境就绪
+4. 顺手提示更新 `.harness/config/harness-test-config.md`——认证方式已变更，配置已过期
+
+> 判据：只要登录响应里出现 `验证码` / `captcha` / `blockPuzzle` / `slider` / `geetest` / `secretKey + originalImageBase64` 任一特征，即触发本规则。
+
+### 规则 32：预存环境缺陷被当成本次变更的阻塞
+**严重度**：🟡WARN
+**场景**：模块全量验证（如 `unitTestFull`）失败，但失败点在本次 diff 之外——例如别人提交的类新增了无默认值的配置占位符，导致某个全上下文测试无法加载
+**后果**：要么误判成自己的回归浪费时间排查，要么擅自改 tracked 配置 / 排除测试把问题掩盖掉，污染 diff
+**正确做法**：
+
+1. **先证明无关**：`git log -S '<符号>' --oneline` 定位引入提交 + `git diff` 证明本次触点不涉及该文件/目录，两条证据都要有
+2. **再上报**：按「预存缺陷」向用户说明——受影响模块、失败文件、引入提交、不阻断依据
+3. **由用户决策**：修根因（会扩大 diff，需明确点头）/ 记 🟡WARN 继续 / 停止本轮
+4. **禁止自作主张**：不得改 tracked 配置文件、不得 `-Dtest=` 排除失败测试、不得偏离 build-profile 的规范命令——这些都会让证据与 ledger 命令不一致
+
+> 用户批准修复后，该修复文件即进入本次 diff：必须在提交前复核它仍在工作区（真实日志里用户中途手工还原了该修复，AI 直到 staging 才发现）。
+
 > diffHash/ledger 复用规则遵循 `../protocols/ledger-protocol.md`；结果证据要求遵循 `../protocols/evidence-based-reporting-protocol.md`。
 
 ## BOM-safe JSON / identifier sanitizer / 凭据扫描 (runtime-helpers.mjs)

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

@@ -219,10 +219,30 @@ def _same_repository(project: Path, candidate: Path) -> bool:
     return candidate.is_relative_to(project)
 
 
+def _contract_error_code(exc: BaseException) -> str:
+    """Keep PROJECT_ROOT_INVALID distinct from a genuinely missing change."""
+    if str(exc).startswith("PROJECT_ROOT_INVALID"):
+        return "PROJECT_ROOT_INVALID"
+    return "CHANGE_NOT_FOUND"
+
+
 def _contract(project: Path, change: str) -> tuple[Path, dict[str, Any], Path]:
     root = project.resolve()
-    contract_root = (root / ".harness" / "changes" / change).resolve()
+    # A bare project *name* (--project udp) resolves to <cwd>/udp and then
+    # reports CHANGE_NOT_FOUND, which sends the caller hunting for the change
+    # instead of fixing the argument. Separate the two failures.
+    if not root.is_dir():
+        raise ValueError(
+            f"PROJECT_ROOT_INVALID: {root} is not a directory — --project takes "
+            "a path to the project root (use '.'), not the project name"
+        )
     changes_root = (root / ".harness" / "changes").resolve()
+    if not changes_root.is_dir():
+        raise ValueError(
+            f"PROJECT_ROOT_INVALID: {changes_root} does not exist — "
+            f"{root} is not a harness project root"
+        )
+    contract_root = (root / ".harness" / "changes" / change).resolve()
     if not contract_root.is_relative_to(changes_root) or not contract_root.is_dir():
         raise ValueError(f"CHANGE_NOT_FOUND: {change}")
     context_path = contract_root / "meta" / "change-context.json"
@@ -296,7 +316,7 @@ def configure_phase_plan(
     try:
         contract_root, _contract_data, _state_root = _contract(project, change)
     except (OSError, ValueError, json.JSONDecodeError) as exc:
-        return {"ok": False, "code": "CHANGE_NOT_FOUND", "error": str(exc)}
+        return {"ok": False, "code": _contract_error_code(exc), "error": str(exc)}
     normalized = [str(item).strip() for item in phases if str(item).strip()]
     if (
         not normalized
@@ -802,7 +822,7 @@ def close_transition(
     try:
         contract_root, _contract_data, state_root = _contract(project, change)
     except (OSError, ValueError, json.JSONDecodeError) as exc:
-        return {"ok": False, "code": "CHANGE_NOT_FOUND", "error": str(exc)}
+        return {"ok": False, "code": _contract_error_code(exc), "error": str(exc)}
     allowed_next = _allowed_next_phases(contract_root, from_phase)
     if to_phase not in allowed_next:
         planned_phases, source = _phase_plan(contract_root)
@@ -962,7 +982,7 @@ def _begin_transition_unlocked(
     try:
         contract_root, _contract_data, state_root = _contract(project, change)
     except (OSError, ValueError, json.JSONDecodeError) as exc:
-        return {"ok": False, "code": "CHANGE_NOT_FOUND", "error": str(exc)}
+        return {"ok": False, "code": _contract_error_code(exc), "error": str(exc)}
     paths = _paths(state_root)
     try:
         execution_root = _execution_root(project, contract_root, state_root)
@@ -1074,7 +1094,7 @@ def begin_transition(
     try:
         _contract_root, _contract_data, state_root = _contract(project, change)
     except (OSError, ValueError, json.JSONDecodeError) as exc:
-        return {"ok": False, "code": "CHANGE_NOT_FOUND", "error": str(exc)}
+        return {"ok": False, "code": _contract_error_code(exc), "error": str(exc)}
     paths = _paths(state_root)
     with _exclusive_state_lock(paths["runtime"] / "branch-selection.lock"):
         return _begin_transition_unlocked(
@@ -1100,7 +1120,7 @@ def cancel_prepared_context(
     try:
         _contract_root, _contract_data, state_root = _contract(project, change)
     except (OSError, ValueError, json.JSONDecodeError) as exc:
-        return {"ok": False, "code": "CHANGE_NOT_FOUND", "error": str(exc)}
+        return {"ok": False, "code": _contract_error_code(exc), "error": str(exc)}
     paths = _paths(state_root)
     removed: list[str] = []
     receipt_hash: str | None = None
@@ -1186,7 +1206,7 @@ def context_view(project: Path, change: str) -> dict[str, Any]:
     try:
         contract_root, contract, state_root = _contract(project, change)
     except (OSError, ValueError, json.JSONDecodeError) as exc:
-        return {"ok": False, "code": "CHANGE_NOT_FOUND", "error": str(exc)}
+        return {"ok": False, "code": _contract_error_code(exc), "error": str(exc)}
     paths = _paths(state_root)
     transitions = _read_ndjson(paths["transitions"])
     begins = _read_ndjson(paths["begins"])

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

@@ -704,7 +704,11 @@ def append_event(
         return {
             "ok": False,
             "code": "PHASE_ALREADY_CLOSED",
-            "message": "PHASE_ALREADY_CLOSED: refusing a second phase.end for the same attempt",
+            "message": (
+                "PHASE_ALREADY_CLOSED: refusing a second phase.end for the "
+                "same attempt. A retry needs a fresh run id AND the next "
+                "attempt number (attempts are global per phase, not per run id)."
+            ),
             "event": event,
             "autoSealed": result.get("autoSealed") or [],
         }
@@ -1931,7 +1935,9 @@ def cmd_append(args: argparse.Namespace) -> int:
                     ):
                         attempt_error = (
                             "EVENT_ATTEMPT_CONFLICT: run_id is already bound to "
-                            f"attempt {expected_attempt}, received {explicit_attempt}"
+                            f"attempt {expected_attempt}, received "
+                            f"{explicit_attempt}. One run id maps to exactly one "
+                            "attempt — allocate a fresh run id for the next attempt."
                         )
                     else:
                         event["attempt"] = expected_attempt
@@ -1972,7 +1978,10 @@ def cmd_append(args: argparse.Namespace) -> int:
         return emit_error(f"append failed: {exc}", as_json=as_json)
     if phase_closed:
         return emit_error(
-            "PHASE_ALREADY_CLOSED: refusing a second phase.end for the same attempt",
+            "PHASE_ALREADY_CLOSED: refusing a second phase.end for the same "
+            "attempt. A retry needs a fresh run id AND the next attempt number "
+            "(attempts are global per phase, not per run id). For a published "
+            "plan use harness_plan_finalize.py republish, which allocates both.",
             as_json=as_json,
             error_code="PHASE_ALREADY_CLOSED",
         )

package/harness/bundles/java/codex/scripts/harness_gate.py

@@ -151,6 +151,11 @@ SOFT_GATE_SITES = frozenset({
 })
 GATE_WARNINGS_REL = Path("evidence") / "gate-warnings.ndjson"
 
+# Lifecycle order used to scope C9 scenario coverage by scenario ownerPhase.
+# A scenario owned by a later phase is deferred, not missing, at an earlier
+# phase close. Must stay a superset-ordering of hpf.VALID_OWNER_PHASES.
+SCENARIO_OWNER_PHASE_ORDER = ("plan", "run", "test", "review", "submit")
+
 
 def gate_severity_mode(project: Path, change_dir: Path | None = None) -> str:
     """Resolve gate severity mode: env > change gate-policy > project config.
@@ -367,7 +372,11 @@ def evaluate_projection_gate(
 def resolve_execution_root(main_project: Path, raw: str | None) -> Path:
     candidate = Path(raw).expanduser().resolve() if raw else main_project.resolve()
     if not candidate.is_dir():
-        raise ValueError(f"execution root not found: {candidate}")
+        raise ValueError(
+            f"execution root not found: {candidate} — --project takes a "
+            "filesystem path to the execution root (use '.' when running from "
+            "it), not the project name"
+        )
     top = _git_text(candidate, "rev-parse", "--show-toplevel")
     if not top:
         raise ValueError(f"execution root is not a git worktree: {candidate}")
@@ -1957,12 +1966,78 @@ def _sync_after_phase_close(project: Path, change_dir: Path) -> dict[str, Any]:
         }
 
 
-def _validate_scenario_coverage(change_dir: Path) -> dict[str, Any]:
+def _scenario_owner_phase_rank(owner_phase: str | None) -> int | None:
+    """Rank a scenario ownerPhase against the lifecycle order, None when unknown."""
+    if not owner_phase:
+        return None
+    normalized = str(owner_phase).strip().lower()
+    if normalized not in hpf.VALID_OWNER_PHASES:
+        return None
+    try:
+        return SCENARIO_OWNER_PHASE_ORDER.index(normalized)
+    except ValueError:
+        return None
+
+
+def _partition_scenarios_by_owner_phase(
+    scenarios: list[Any],
+    required_ids: set[str],
+    phase: str | None,
+) -> tuple[set[str], list[str]]:
+    """Split required scenarios into (due now, deferred to a later phase).
+
+    A scenario is deferred only when it declares an `ownerPhase` that ranks
+    strictly after the phase being closed. Scenarios without a usable
+    `ownerPhase` (legacy/v1 manifests) stay due, preserving old behaviour.
+    """
+    closing_rank = _scenario_owner_phase_rank(phase)
+    if closing_rank is None:
+        return set(required_ids), []
+    due: set[str] = set()
+    deferred: set[str] = set()
+    for scenario in scenarios:
+        if not isinstance(scenario, dict):
+            continue
+        scenario_id = str(scenario.get("id") or "").strip()
+        if scenario_id not in required_ids:
+            continue
+        owner_rank = _scenario_owner_phase_rank(scenario.get("ownerPhase"))
+        if owner_rank is not None and owner_rank > closing_rank:
+            deferred.add(scenario_id)
+        else:
+            due.add(scenario_id)
+    # IDs present in required_ids but absent from the scan stay due (defensive).
+    due |= required_ids - due - deferred
+    # A duplicated ID declaring two ownerPhases must fail closed: if any
+    # occurrence is due now, the scenario is due now.
+    deferred -= due
+    return due, sorted(deferred)
+
+
+def _deferred_hint(deferred_ids: list[str], phase: str | None) -> str:
+    """Append a note so callers never mistake a deferred scenario for a blocker."""
+    if not deferred_ids:
+        return ""
+    return (
+        f"（另有 {len(deferred_ids)} 个场景按 ownerPhase 移交后续阶段，"
+        f"未计入 {phase or '本'} 阶段要求: " + ", ".join(deferred_ids) + "）"
+    )
+
+
+def _validate_scenario_coverage(
+    change_dir: Path, phase: str | None = None
+) -> dict[str, Any]:
     """C9: validate all ledger-required scenarios are covered by ledger entries.
 
     Reads meta/scenario-manifest.json and evidence/verification-ledger.json.
     Returns ok=True when a legacy manifest is missing or all required scenarios
     are covered. A present but empty manifest is always invalid.
+
+    Phase scoping: when `phase` is given, only scenarios whose `ownerPhase`
+    is due by that phase are required to carry passing receipts. Scenarios
+    owned by a later phase (e.g. `ownerPhase=test` at `run` close) are
+    reported under `deferred` instead of blocking the close — this matches the
+    documented hand-off rule in harness-run/SKILL.md ("ownerPhase=test 按计划移交").
     """
     manifest_path = change_dir / "meta" / "scenario-manifest.json"
     if not manifest_path.is_file():
@@ -2010,6 +2085,9 @@ def _validate_scenario_coverage(change_dir: Path) -> dict[str, Any]:
     }
     if not required_ids:
         return {"ok": True, "code": "NO_LEDGER_REQUIRED_SCENARIOS"}
+    due_ids, deferred_ids = _partition_scenarios_by_owner_phase(
+        scenarios, required_ids, phase
+    )
     raw_schema_version = (
         manifest.get("schemaVersion") if isinstance(manifest, dict) else None
     )
@@ -2043,6 +2121,18 @@ def _validate_scenario_coverage(change_dir: Path) -> dict[str, Any]:
                 "missingMappings": missing_mappings,
             }
 
+    if not due_ids:
+        # Every required scenario is owned by a later phase — nothing is due
+        # at this close. Report the hand-off instead of blocking.
+        return {
+            "ok": True,
+            "code": "SCENARIO_COVERAGE_DEFERRED",
+            "covered": [],
+            "deferred": deferred_ids,
+            "ownerPhaseScope": phase,
+            "schemaVersion": schema_version,
+        }
+
     try:
         ledger, ledger_path = hl.load_ledger(change_dir)
     except (OSError, ValueError, json.JSONDecodeError) as exc:
@@ -2050,14 +2140,16 @@ def _validate_scenario_coverage(change_dir: Path) -> dict[str, Any]:
             "ok": False,
             "code": "SCENARIO_COVERAGE_FAILED",
             "message": f"ledger unreadable: {exc}",
-            "missing": sorted(required_ids),
+            "missing": sorted(due_ids),
+            "deferred": deferred_ids,
         }
     if ledger is None or ledger_path is None:
         return {
             "ok": False,
             "code": "SCENARIO_COVERAGE_FAILED",
             "message": "ledger missing; cannot verify required scenario coverage",
-            "missing": sorted(required_ids),
+            "missing": sorted(due_ids),
+            "deferred": deferred_ids,
         }
     if schema_version >= 2:
         coverage_sets: dict[str, set[str]] = {
@@ -2137,8 +2229,8 @@ def _validate_scenario_coverage(change_dir: Path) -> dict[str, Any]:
                         )
 
         passed = coverage_sets["passed"]
-        missing = sorted(required_ids - bound)
-        unexecuted = sorted(required_ids - passed)
+        missing = sorted(due_ids - bound)
+        unexecuted = sorted(due_ids - passed)
         detail = {
             key: sorted(values & required_ids)
             for key, values in coverage_sets.items()
@@ -2147,6 +2239,8 @@ def _validate_scenario_coverage(change_dir: Path) -> dict[str, Any]:
             {
                 "missing": missing,
                 "unexecuted": unexecuted,
+                "deferred": deferred_ids,
+                "ownerPhaseScope": phase,
                 "attempts": {
                     scenario_id: sorted(values)
                     for scenario_id, values in sorted(attempts.items())
@@ -2162,6 +2256,7 @@ def _validate_scenario_coverage(change_dir: Path) -> dict[str, Any]:
                 "message": (
                     "required scenarios without exact passed execution receipts: "
                     + ", ".join(unexecuted)
+                    + _deferred_hint(deferred_ids, phase)
                 ),
                 **detail,
             }
@@ -2180,7 +2275,7 @@ def _validate_scenario_coverage(change_dir: Path) -> dict[str, Any]:
                 ids = entry.get("scenarioIds")
                 if isinstance(ids, list):
                     covered.update(str(i) for i in ids)
-    missing = sorted(required_ids - covered)
+    missing = sorted(due_ids - covered)
     if missing:
         return {
             "ok": False,
@@ -2188,13 +2283,18 @@ def _validate_scenario_coverage(change_dir: Path) -> dict[str, Any]:
             "message": (
                 "ledger-required scenarios without ledger entry: "
                 + ", ".join(missing)
+                + _deferred_hint(deferred_ids, phase)
             ),
             "missing": missing,
+            "deferred": deferred_ids,
+            "ownerPhaseScope": phase,
         }
     return {
         "ok": True,
         "code": "SCENARIO_COVERAGE_OK",
         "covered": sorted(covered & required_ids),
+        "deferred": deferred_ids,
+        "ownerPhaseScope": phase,
     }
 
 
@@ -2888,9 +2988,11 @@ def cmd_close(args: argparse.Namespace) -> int:
                 },
             )
 
-    # C9: scenario coverage check — all P0 scenarios must have a ledger entry.
+    # C9: scenario coverage check — every P0/ledger scenario *due by this phase*
+    # must have a ledger entry. Scenarios with a later ownerPhase are deferred,
+    # not missing (see _validate_scenario_coverage).
     if args.phase in {"run", "test"}:
-        coverage = _validate_scenario_coverage(change_dir)
+        coverage = _validate_scenario_coverage(change_dir, args.phase)
         if not coverage.get("ok"):
             if gate_soft_allowed(severity_mode, args.phase, "scenario-coverage"):
                 gate_warnings.append(record_gate_warning(
@@ -3284,7 +3386,14 @@ def build_parser() -> argparse.ArgumentParser:
     p_begin = sub.add_parser("begin", parents=[shared])
     p_begin.add_argument("--phase", required=True)
     p_begin.add_argument("--change", default=None)
-    p_begin.add_argument("--project", default=None)
+    p_begin.add_argument(
+        "--project",
+        default=None,
+        help=(
+            "execution root PATH (worktree) for this phase; defaults to the "
+            "change's main project. Takes a path, not a project name."
+        ),
+    )
     p_begin.add_argument("--skills-root", default=None)
     p_begin.add_argument("--run-id", default=None)
     p_begin.add_argument("--ttl-seconds", type=int, default=3600)
@@ -3298,7 +3407,14 @@ def build_parser() -> argparse.ArgumentParser:
     p_close = sub.add_parser("close", parents=[shared])
     p_close.add_argument("--phase", required=True)
     p_close.add_argument("--change", default=None)
-    p_close.add_argument("--project", default=None)
+    p_close.add_argument(
+        "--project",
+        default=None,
+        help=(
+            "execution root PATH (worktree) for this phase; defaults to the "
+            "change's main project. Takes a path, not a project name."
+        ),
+    )
     p_close.add_argument("--status", required=True)
     p_close.add_argument("--run-id", default=None)
     p_close.add_argument("--task", type=int, default=None)