@hunter-harness/workflow-harness 0.2.69 → 0.2.71

package/harness/bundles/general/claude-code/.harness-build.json

@@ -2,5 +2,5 @@
   "schemaVersion": 1,
   "overlay": "none",
   "agent": "claude-code",
-  "coreHash": "bfe37ba08ec6ec72"
+  "coreHash": "2295b79da2fe3e66"
 }

package/harness/bundles/general/claude-code/README.md

@@ -376,7 +376,7 @@ $out = "<build-output-dir>"
 # 通用项目
 python "$skillsRoot/scripts/harness_deploy.py" build --skills-root $skillsRoot --out $out --json
 
-# Java 后端（core + java overlay → 12 skill 自包含树）
+# Java 后端（core + java overlay → 14 skill 自包含树：12 base + 2 java-only）
 python "$skillsRoot/scripts/harness_deploy.py" build --skills-root $skillsRoot --overlay java --out $out --json
 
 python "$skillsRoot/scripts/harness_deploy.py" install --from $out --project "<目标项目>" --json

package/harness/bundles/general/claude-code/harness-archive/SKILL.md

@@ -21,7 +21,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=bfe37ba08ec6ec72; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=2295b79da2fe3e66; overlay=none; agent=claude-code; do not edit -->
 # harness-archive — 变更归档
 
 ## Purpose

package/harness/bundles/general/claude-code/harness-codebase-map/SKILL.md

@@ -20,7 +20,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=bfe37ba08ec6ec72; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=2295b79da2fe3e66; overlay=none; agent=claude-code; do not edit -->
 # harness-codebase-map — 代码库地图
 
 ## Purpose

package/harness/bundles/general/claude-code/harness-knowledge-ingest/SKILL.md

@@ -8,7 +8,7 @@ disallowed-tools:
   - Bash(git *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=bfe37ba08ec6ec72; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=2295b79da2fe3e66; overlay=none; agent=claude-code; do not edit -->
 # harness-knowledge-ingest
 
 知识 ingest 完全由 Hunter Platform 负责。归档完成时，客户端生成一个确定性 ZIP；

package/harness/bundles/general/claude-code/harness-knowledge-query/SKILL.md

@@ -8,7 +8,7 @@ disallowed-tools:
   - Bash(git *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=bfe37ba08ec6ec72; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=2295b79da2fe3e66; overlay=none; agent=claude-code; do not edit -->
 # harness-knowledge-query
 
 项目知识以 Hunter Platform 的服务端索引为唯一真源。客户端只提交查询并消费结果：

package/harness/bundles/general/claude-code/harness-plan/SKILL.md

@@ -21,7 +21,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=bfe37ba08ec6ec72; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=2295b79da2fe3e66; overlay=none; agent=claude-code; do not edit -->
 # harness-plan — 需求规划
 
 ## Purpose
@@ -120,6 +120,8 @@ change-name 范围变更 → 提示重命名或记 🟡WARN（→ `reference.md`
 | 空目录 | 不得为“预留目录”生成 `.gitkeep`；只有产品明确需要跟踪空目录时才能创建，并在计划中说明业务原因 |
 | 设计审批包 | 一次 blocking user confirmation 含 worktree（读 `harness.json` `defaultWorktree`） |
 | 阶段 8 | 二选一且不得混用：**v2** = `hunter-harness plan finalize`（证据包 → 八 target + journal committed + plan-events.ndjson）；**legacy** = 六项标准产物先进入 staging，仅 finalizer 校验成功后发布并写唯一 `phase.end`/log，随后 `verify` 确认 start/end、收据完整覆盖六项标准产物、哈希、全部任务表和非空场景清单一致。失败均不得手工补终态 |
+| 发布后改产物 | 用 `harness_plan_finalize.py republish --run-id <全新> --reason "<why>"` 一次完成（新 attempt + 换收据 + 重新派生 manifest）。重跑 `finalize` 会报 `PLAN_FINALIZATION_HASH_CONFLICT`；**绝不手改 `meta/scenario-manifest.json`**（派生物，手改必致 `ARTIFACT_HASH_DRIFT`）→ `reference.md`「发布后修订计划」 |
+| v2 输入骨架 | 不要猜 `plan-evidence-input.json` 结构，也不要去翻 TS 接口/npx 缓存：`npx hunter-harness plan evidence-pack --print-template` 直接给带占位符的完整骨架 |
 | Plan 结束 | **禁止**询问执行模式；只提示 `/harness-run` |
 | 知识查询 | 阶段 1 失败不得假装已读历史，也不得改用本地索引或其他执行入口 |
 | 歧义优先检查 | 否定、对比、动作对象或范围存在多种合理解释时，最小取证后先给推荐理解并一次一问；确认前不深挖错误方向 |

package/harness/bundles/general/claude-code/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/general/claude-code/harness-pull/SKILL.md

@@ -21,7 +21,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=bfe37ba08ec6ec72; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=2295b79da2fe3e66; overlay=none; agent=claude-code; do not edit -->
 # harness-pull — 从 Hunter Platform 下拉与恢复
 
 ## Purpose

package/harness/bundles/general/claude-code/harness-push/SKILL.md

@@ -21,7 +21,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=bfe37ba08ec6ec72; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=2295b79da2fe3e66; overlay=none; agent=claude-code; do not edit -->
 # harness-push — 上传到 Hunter Platform
 
 ## Purpose

package/harness/bundles/general/claude-code/harness-review/SKILL.md

@@ -22,7 +22,7 @@ disallowed-tools:
   - Bash(curl *)
   - Bash(codegraph *)
 ---
-<!-- generated by harness_deploy.py; core=bfe37ba08ec6ec72; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=2295b79da2fe3e66; overlay=none; agent=claude-code; do not edit -->
 # harness-review — 代码审查
 
 ## Purpose

package/harness/bundles/general/claude-code/harness-run/SKILL.md

@@ -22,7 +22,7 @@ disallowed-tools:
   - Bash(curl *)
   - Bash(codegraph *)
 ---
-<!-- generated by harness_deploy.py; core=bfe37ba08ec6ec72; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=2295b79da2fe3e66; overlay=none; agent=claude-code; do not edit -->
 # harness-run — 需求编码
 
 ## Purpose
@@ -87,6 +87,8 @@ disallowed-tools:
 
 **阶段归属规则**：只用 `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/general/claude-code/harness-run/reference.md

@@ -799,6 +799,8 @@ powershell.exe -Command "git -C '<project-path>' diff --check"
 > 可直接复制；替换 `<skills-root>` / `<cn>` / `<dir>` / `<project>`。`--task` **仅在该 change 启用 checkpoint 时必需**（checkpoints 文件缺失或不含 pending foundation-gate 时不要传）。
 > `ledger record` 必需：`--duration-ms`、`--evidence`，以及 `--files`（逗号分隔源文件）或 `--profile-input <verificationKey> --project <project>`（从 build-profile 展开）。`status` 枚举: `ok|fail|not_run`（没有 PASS）。
 > `--skills-root` 仅用于 `begin`（及 `lint-skills`）：必须是 adapter 根（如 `.cursor/skills`），不是 `scripts/` 子目录。**`close` 不需要 `--skills-root`**（该子命令不接受此参数）。
+>
+> ⚠️ **`--project` 一律传路径，不传项目名。** 在项目根执行时就写 `--project .`。传项目名（`--project udp`）会被解析成 `<cwd>/udp`，然后以各不相同的下游错误暴露出来（`PROJECT_ROOT_INVALID` / `EXECUTION_ROOT_INVALID`）。
 
 ```powershell
 # gate begin/close（--task 仅在该 change 启用 checkpoint 时必需；close 不需要 --skills-root）
@@ -810,8 +812,21 @@ python <skills-root>/scripts/harness_ledger.py record --change-dir <dir> --verif
 
 # 复用检查（--profile-input 取 verification key，不是文件路径；配合 --project）
 python <skills-root>/scripts/harness_ledger.py can-reuse --change-dir <dir> --verification unitTestFull --profile-input unitTestFull --project <project>
+
+# scenario-manifest schemaVersion 2：record 绑定场景必须带 receipt，先生成骨架再记录
+python <skills-root>/scripts/harness_ledger.py scenario-receipt-template --change-dir <dir> --scenario-ids "UT-001,UT-002" --runner <runner 名> --out runtime/scenario-receipt-unit.json --json
+python <skills-root>/scripts/harness_ledger.py record --change-dir <dir> --verification unitTest --status ok ... --scenario-ids "UT-001,UT-002" --scenario-receipt-file runtime/scenario-receipt-unit.json
 ```
 
+### run 阶段关门顺序
+
+```powershell
+python <skills-root>/scripts/harness_test_guard.py close --project . --change-dir ".harness/changes/<cn>" --json
+python <skills-root>/scripts/harness_gate.py close --change <cn> --phase run --status OK --to-phase <后继> --executor <tool>
+```
+
+C9 场景覆盖按 `ownerPhase` **分阶段判定**：run 关门只要求 `ownerPhase` 为 `plan`/`run` 的必需场景有通过 receipt；`ownerPhase=test` 的场景计入返回值的 `deferred`，属正常移交，不阻断 run。反过来，test 关门时这些场景仍然必须有 receipt。未声明 `ownerPhase` 的老清单沿用旧语义（全部即时要求）。
+
 ### 常见报错对照
 
 | 报错 | 原因 | 处理 |
@@ -823,6 +838,11 @@ python <skills-root>/scripts/harness_ledger.py can-reuse --change-dir <dir> --ve
 | `record requires --files or a non-empty --profile-input file set` | 缺少输入文件集 | 补 `--files` 或 `--profile-input <key> --project <project>` |
 | `--profile-input requires --project` | can-reuse/record 展开 profile 需要项目根 | 补 `--project <project>` |
 | `record` 缺 `--duration-ms` / `--evidence` | 参数为必填 | 按模板补齐 |
+| `PROJECT_ROOT_INVALID` | `--project` 传了项目名而不是路径 | 在项目根执行并传 `--project .`；报错的 `resolvedProject` 字段显示了实际解析到哪 |
+| `EXECUTION_ROOT_INVALID` | gate 的 `--project` 是**执行根路径**（worktree），同样不接受项目名 | 传 `.` 或 worktree 绝对路径 |
+| `SCENARIO_RECEIPT_REQUIRED` | manifest 是 schemaVersion 2，`--scenario-ids` 必须配 receipt | 用上面的 `scenario-receipt-template` 生成骨架，再传 `--scenario-receipt-file` |
+| `SCENARIO_RECEIPT_NOT_FOUND` | receipt 路径找不到 | 报错的 `triedPaths` 列出了尝试过的绝对路径；相对路径同时按 CWD 和 `--change-dir` 解析，二选一放对即可 |
+| `REQUIRED_SCENARIO_NOT_EXECUTED`（run 关门，缺的是接口场景） | 这些场景 `ownerPhase` 应为 `test` 却写成了 run，或清单未声明 `ownerPhase` | 修 `meta/scenario-manifest.json` 的 `ownerPhase`；**不要**为了过门去跑本该属于 test 阶段的验证 |
 
 ## 关键原则
 

package/harness/bundles/general/claude-code/harness-submit/SKILL.md

@@ -21,7 +21,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=bfe37ba08ec6ec72; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=2295b79da2fe3e66; overlay=none; agent=claude-code; do not edit -->
 # harness-submit — 最终提交（含 worktree 合并）
 
 ## Purpose

package/harness/bundles/general/claude-code/harness-sync/SKILL.md

@@ -19,7 +19,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=bfe37ba08ec6ec72; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=2295b79da2fe3e66; overlay=none; agent=claude-code; do not edit -->
 # harness-sync
 
 ## Purpose

package/harness/bundles/general/claude-code/harness-test/SKILL.md

@@ -23,7 +23,7 @@ disallowed-tools:
   - Bash(node *)
   - Bash(codegraph *)
 ---
-<!-- generated by harness_deploy.py; core=bfe37ba08ec6ec72; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=2295b79da2fe3e66; overlay=none; agent=claude-code; do not edit -->
 # harness-test — 测试执行
 
 ## Purpose
@@ -201,6 +201,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/general/claude-code/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/general/claude-code/harness-test/reference.md

@@ -736,6 +736,8 @@ TEST_<change-name>_<timestamp>_<short-random>
 
 > test 阶段常用子集。`--task` **仅在该 change 启用 checkpoint 时必需**。ledger status 枚举: ok|fail|not_run（没有 PASS）。`record` 还需 `--duration-ms`、`--evidence`，以及 `--files` 或 `--profile-input`+`--project`。
 > `--skills-root` 仅用于 `begin`（及 `lint-skills`）：必须是 adapter 根（如 `.cursor/skills`），不是 `scripts/` 子目录。**`close` 不需要 `--skills-root`**（该子命令不接受此参数）。
+>
+> ⚠️ **`--project` 一律传路径，不传项目名**（在项目根就写 `--project .`）。传项目名会解析成 `<cwd>/<名字>` 并报 `PROJECT_ROOT_INVALID` / `EXECUTION_ROOT_INVALID`。
 
 ```powershell
 # gate begin/close（phase=test；--task 仅 checkpoint 启用时必需；close 不需要 --skills-root）
@@ -746,6 +748,9 @@ python <skills-root>/scripts/harness_gate.py close --change <cn> --phase test --
 python <skills-root>/scripts/harness_ledger.py record --change-dir <dir> --verification unitTestFull --status ok --command "<完整命令>" --exit-code 0 --duration-ms 120000 --evidence "Tests run: N, Failures: 0" --coverage full --files "packages/core/src/index.ts"
 python <skills-root>/scripts/harness_ledger.py record --change-dir <dir> --verification browserTest --status ok --command "<真实栈 Playwright 命令>" --exit-code 0 --duration-ms 120000 --evidence "Browser E2E: N passed, 0 failed" --coverage module --files "<Playwright 配置与受测 spec>"
 python <skills-root>/scripts/harness_ledger.py can-reuse --change-dir <dir> --verification unitTestFull --profile-input unitTestFull --project <project>
+
+# scenario-manifest schemaVersion 2：绑定场景必须带 receipt，先生成骨架再 record
+python <skills-root>/scripts/harness_ledger.py scenario-receipt-template --change-dir <dir> --scenario-ids "API-001,API-002" --runner <runner 名> --out runtime/scenario-receipt-api.json --json
 ```
 
 > **Ledger v3（v2 契约 / split-v1 布局起）**：`record` 强制顶层身份（缺失非零退出、不写账本）；`--metrics-json` 必须过 typed schema（unit/apiTest/browserTest/apiContract/dbCompatibility 各有不同必填键）；`browserTest` 在报告中投影为 `browserE2E`；dbCompatibility 等不适用验证用 `--applicability NOT_APPLICABLE --applicability-reason "<scope 原因>"`（不计通过也不计失败）。legacy 契约行为不变。详见 `../protocols/ledger-protocol.md` 第十节。
@@ -761,6 +766,10 @@ python <skills-root>/scripts/harness_ledger.py can-reuse --change-dir <dir> --ve
 | `record requires --files or a non-empty --profile-input file set` | 缺少输入文件集 | 补 `--files` 或 `--profile-input <key> --project <project>` |
 | `--profile-input requires --project` | can-reuse/record 展开 profile 需要项目根 | 补 `--project <project>` |
 | `record` 缺 `--duration-ms` / `--evidence` | 参数为必填 | 按模板补齐 |
+| `PROJECT_ROOT_INVALID` | `--project` 传了项目名而不是路径 | 传 `.` 或绝对路径；报错的 `resolvedProject` 显示实际解析结果 |
+| `SCENARIO_RECEIPT_REQUIRED` | manifest 是 schemaVersion 2，`--scenario-ids` 必须配 receipt | 用 `scenario-receipt-template` 生成骨架 |
+| `SCENARIO_RECEIPT_NOT_FOUND` | receipt 路径找不到 | 看报错的 `triedPaths`；相对路径同时按 CWD 与 `--change-dir` 解析 |
+| `REQUIRED_SCENARIO_NOT_EXECUTED`（test 关门） | `ownerPhase=test` 的场景到 test 阶段仍无通过 receipt——这是真阻塞 | 补跑该场景；接口被验证码挡住时按 `pitfalls.md` 规则 31 记 BLOCKED，不得伪造 receipt |
 
 `can-reuse` 的主文案按 `executionNeed` 呈现，错误码仅放技术详情：`first-run` 表示首次执行，`rerun` 表示已有证据因输入或环境变化失效，`evidence-incomplete` 表示旧记录缺少当前契约字段，`reuse` 表示可直接复用。不得把 `VALIDATION_MISSING` 翻译成“强制重跑”。
 

package/harness/bundles/general/claude-code/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/general/claude-code/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",
         )