@hunter-harness/workflow-harness 0.2.69 → 0.2.70

package/harness/bundles/java/claude-code/scripts/harness_service.py

@@ -1462,6 +1462,10 @@ def _job_id_path(change_dir: Path) -> Path:
     return _runtime_dir(change_dir) / "_harness_service.job.id"
 
 
+def _breakaway_note_path(change_dir: Path) -> Path:
+    return _runtime_dir(change_dir) / "_harness_service.breakaway.json"
+
+
 def _child_pid_path(change_dir: Path) -> Path:
     return _runtime_dir(change_dir) / "_harness_service.child.pid"
 
@@ -1574,20 +1578,56 @@ def _start_detached_service_windows(
         str(pid_path),
         job_id,
     ]
-    win_flags = (
-        _DETACHED_PROCESS
-        | _CREATE_NEW_PROCESS_GROUP
-        | _CREATE_NO_WINDOW
-        | _CREATE_BREAKAWAY_FROM_JOB
-    )
-    launcher_proc = subprocess.Popen(
-        launcher_args,
-        cwd=str(cwd),
-        stdin=subprocess.DEVNULL,
-        stdout=subprocess.DEVNULL,
-        stderr=subprocess.DEVNULL,
-        creationflags=win_flags,
-        close_fds=False,
+    base_flags = _DETACHED_PROCESS | _CREATE_NEW_PROCESS_GROUP | _CREATE_NO_WINDOW
+    # CREATE_BREAKAWAY_FROM_JOB fails with ERROR_ACCESS_DENIED (WinError 5)
+    # whenever the *caller* already runs inside a Job Object that was created
+    # without JOB_OBJECT_LIMIT_BREAKAWAY_OK — which is exactly how agent CLIs
+    # (Claude Code / CodeBuddy / Codex) contain their child processes. Breakaway
+    # is an optimisation (the service outlives the agent session), not a
+    # requirement, so fall back to spawning inside the caller's job rather than
+    # failing the whole start.
+    launcher_proc = None
+    breakaway = True
+    try:
+        launcher_proc = subprocess.Popen(
+            launcher_args,
+            cwd=str(cwd),
+            stdin=subprocess.DEVNULL,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            creationflags=base_flags | _CREATE_BREAKAWAY_FROM_JOB,
+            close_fds=False,
+        )
+    except OSError as exc:
+        if getattr(exc, "winerror", None) != 5:
+            raise
+        breakaway = False
+        launcher_proc = subprocess.Popen(
+            launcher_args,
+            cwd=str(cwd),
+            stdin=subprocess.DEVNULL,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            creationflags=base_flags,
+            close_fds=False,
+        )
+    _breakaway_note_path(change_dir).write_text(
+        json.dumps(
+            {
+                "breakawayFromJob": breakaway,
+                "note": (
+                    None
+                    if breakaway
+                    else "spawned inside the caller's Job Object "
+                    "(CREATE_BREAKAWAY_FROM_JOB denied); the service is "
+                    "terminated when the agent session ends"
+                ),
+            },
+            ensure_ascii=False,
+        )
+        + "\n",
+        encoding="utf-8",
+        newline="\n",
     )
     _launcher_pid_path(change_dir).write_text(str(launcher_proc.pid), encoding="utf-8")
     _wait_for_child_pid(pid_path)
@@ -2400,7 +2440,21 @@ def _start_and_record(
             }
         )
         write_json(mutation_state_path(change_dir), mutation_state)
-        return emit_error(f"failed to start service: {exc}", as_json=as_json)
+        if getattr(exc, "winerror", None) == 5:
+            return emit_error(
+                "failed to start service: Windows denied process creation "
+                f"({exc}). The agent shell blocks detached spawns; start the "
+                "service from a terminal the agent does not own (or use the "
+                "documented nohup fallback) and re-run `ensure` so the harness "
+                "adopts the running instance.",
+                as_json=as_json,
+                reasonCode="SERVICE_SPAWN_DENIED",
+            )
+        return emit_error(
+            f"failed to start service: {exc}",
+            as_json=as_json,
+            reasonCode="SERVICE_START_FAILED",
+        )
 
     # Give the OS a moment to register the process before identity/create-time reads
     time.sleep(0.15)

package/harness/bundles/java/claude-code/scripts/harness_test_guard.py

@@ -178,6 +178,32 @@ def _state_project_root(project: Path) -> Path:
     return resolved.parent if resolved.name == ".git" else project
 
 
+def _invalid_project_root(
+    action: str, project: Path | str, resolved: Path
+) -> dict[str, Any] | None:
+    """Reject a --project that is not an existing directory.
+
+    Passing the *project name* (``--project udp``) instead of its path used to
+    resolve to ``<cwd>/udp`` and then surface as SNAPSHOT_MISSING — an error
+    that points at the wrong thing entirely. Fail here with the resolved path
+    so the real mistake is visible.
+    """
+    if resolved.is_dir():
+        return None
+    return _result(
+        False,
+        action,
+        "PROJECT_ROOT_INVALID",
+        [],
+        project=str(project),
+        resolvedProject=str(resolved),
+        hint=(
+            "--project takes a filesystem path to the project root "
+            "(use '.' when running from it), not the project name"
+        ),
+    )
+
+
 def _change_dir(project: Path, change_dir: Path | str) -> Path | None:
     state_project = _state_project_root(project)
     candidate = Path(change_dir)
@@ -556,6 +582,9 @@ def record(
 ) -> dict[str, Any]:
     action = "record"
     project_root = Path(project).resolve()
+    invalid_root = _invalid_project_root(action, project, project_root)
+    if invalid_root is not None:
+        return invalid_root
     if not files:
         return _result(False, action, "EMPTY_FILES", [])
     if reason not in REASONS:
@@ -1452,6 +1481,9 @@ def _reconcile_close_manifest(
 def begin(project: Path | str, change_dir: Path | str) -> dict[str, Any]:
     action = "begin"
     project_root = Path(project).resolve()
+    invalid_root = _invalid_project_root(action, project, project_root)
+    if invalid_root is not None:
+        return invalid_root
     change_root = _change_dir(project_root, change_dir)
     if change_root is None:
         return _result(False, action, "CHANGE_DIR_OUTSIDE_PROJECT", [])
@@ -1545,12 +1577,24 @@ def begin(project: Path | str, change_dir: Path | str) -> dict[str, Any]:
 def close(project: Path | str, change_dir: Path | str) -> dict[str, Any]:
     action = "close"
     project_root = Path(project).resolve()
+    invalid_root = _invalid_project_root(action, project, project_root)
+    if invalid_root is not None:
+        return invalid_root
     change_root = _change_dir(project_root, change_dir)
     if change_root is None:
         return _result(False, action, "CHANGE_DIR_OUTSIDE_PROJECT", [])
     snapshot_path = _state_root(change_root) / SNAPSHOT_REL
     if not snapshot_path.is_file():
-        return _result(False, action, "SNAPSHOT_MISSING", [])
+        # Name the exact path: this snapshot is evidence/test-guard-snapshot.json,
+        # not meta/state-snapshot.json, and the two are easy to confuse.
+        return _result(
+            False,
+            action,
+            "SNAPSHOT_MISSING",
+            [],
+            expectedSnapshot=str(snapshot_path),
+            hint="run `harness_test_guard.py begin` for this change first",
+        )
     try:
         snapshot = _read_json(snapshot_path)
     except (OSError, json.JSONDecodeError) as exc:
@@ -1752,6 +1796,9 @@ def mark(
 def stage(project: Path | str, change_dir: Path | str) -> dict[str, Any]:
     action = "stage"
     project_root = Path(project).resolve()
+    invalid_root = _invalid_project_root(action, project, project_root)
+    if invalid_root is not None:
+        return invalid_root
     change_root = _change_dir(project_root, change_dir)
     if change_root is None:
         return _result(False, action, "CHANGE_DIR_OUTSIDE_PROJECT", [])

package/harness/bundles/java/codebuddy/.harness-build.json

@@ -2,5 +2,5 @@
   "schemaVersion": 1,
   "overlay": "java",
   "agent": "codebuddy",
-  "coreHash": "9f91fcbcac46e102"
+  "coreHash": "86f5a6b27795a615"
 }

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

@@ -3,7 +3,7 @@ name: harness-apidoc
 description: 从 Java 后端代码生成结构化前端 API 文档（Controller/VO/ErrorCode）。仅当用户显式调用
   /harness-apidoc 时使用，不得自动触发。
 ---
-<!-- generated by harness_deploy.py; core=9f91fcbcac46e102; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=86f5a6b27795a615; overlay=java; agent=codebuddy; do not edit -->
 # harness-apidoc — 前端接口文档（Java overlay）
 
 ## Purpose

package/harness/bundles/java/codebuddy/harness-archive/SKILL.md

@@ -3,7 +3,7 @@ name: harness-archive
 description: 归档所有变更产出（计划/测试报告/审查/SQL/API文档）到 .harness/archive/，含归档元数据。仅当用户显式调用
   /harness-archive 时使用；不得被其他阶段 skill 自动接续触发。
 ---
-<!-- generated by harness_deploy.py; core=9f91fcbcac46e102; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=86f5a6b27795a615; overlay=java; agent=codebuddy; do not edit -->
 # harness-archive — 变更归档
 
 ## Purpose

package/harness/bundles/java/codebuddy/harness-codebase-map/SKILL.md

@@ -3,7 +3,7 @@ name: harness-codebase-map
 description: 分析现有代码库并生成 .harness/codebase/map/
   下的结构化代码库地图。用于陌生项目理解、重大改造前梳理、harness-sync 提示 map 过期后的人工刷新。
 ---
-<!-- generated by harness_deploy.py; core=9f91fcbcac46e102; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=86f5a6b27795a615; overlay=java; agent=codebuddy; do not edit -->
 # harness-codebase-map — 代码库地图
 
 ## Purpose

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

@@ -2,7 +2,7 @@
 name: harness-knowledge-ingest
 description: 确认归档 ZIP 已上传并由 Hunter Platform 在服务端解包、校验和入库。客户端不再构建或维护本地知识索引。
 ---
-<!-- generated by harness_deploy.py; core=9f91fcbcac46e102; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=86f5a6b27795a615; overlay=java; agent=codebuddy; do not edit -->
 # harness-knowledge-ingest
 
 知识 ingest 完全由 Hunter Platform 负责。归档完成时，客户端生成一个确定性 ZIP；

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

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

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

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

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

@@ -3,7 +3,7 @@ name: harness-plan
 description: 将需求转化为设计文档+实施计划+完整测试场景表，必须在编码前完成。仅当用户显式调用 /harness-plan 或明确要求进入
   Harness 规划阶段时使用；不得因用户描述需求就自动触发。
 ---
-<!-- generated by harness_deploy.py; core=9f91fcbcac46e102; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=86f5a6b27795a615; overlay=java; agent=codebuddy; do not edit -->
 # harness-plan — 需求规划
 
 ## Purpose
@@ -102,6 +102,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/java/codebuddy/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/codebuddy/harness-pull/SKILL.md

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

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

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

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

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

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

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

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

@@ -3,7 +3,7 @@ name: harness-test
 description: 测试执行：读取场景表，执行单元测试+API接口测试+数据兼容验证，输出测试报告。仅当用户显式调用 /harness-test
   时使用；不得在 run 结束后自动接续执行。
 ---
-<!-- generated by harness_deploy.py; core=9f91fcbcac46e102; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=86f5a6b27795a615; overlay=java; agent=codebuddy; 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/codebuddy/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/codebuddy/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/codebuddy/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",
         )