@hunter-harness/workflow-harness 0.4.9 → 0.4.11

package/harness/bundles/general/pi/scripts/harness_ledger.py

@@ -1624,6 +1624,15 @@ def evidence_summary(entry: dict[str, Any]) -> dict[str, Any]:
     }
 
 
+def _is_relative_to(path: Path, base: Path) -> bool:
+    """Python 3.9 兼容的 is_relative_to。"""
+    try:
+        path.relative_to(base)
+        return True
+    except ValueError:
+        return False
+
+
 def _nonempty_str(value: Any) -> bool:
     return isinstance(value, str) and bool(value.strip())
 
@@ -3056,6 +3065,12 @@ def cmd_record(args: argparse.Namespace) -> int:
         "scenarioCoverage": entry.get("scenarioCoverage"),
         "migrationReceipt": migration_receipt,
     }
+    zero_warn = _zero_tests_with_selector_warning(
+        str(args.command), args.evidence, project_root
+    )
+    if zero_warn is not None:
+        payload["warnings"] = [zero_warn]
+        print(f"[harness-ledger] WARNING {zero_warn}", file=sys.stderr)
     emit_compact_or_verbose(
         payload, as_json=as_json, verbose=verbose,
         compact_fn=_compact_record_payload,
@@ -3063,6 +3078,47 @@ def cmd_record(args: argparse.Namespace) -> int:
     return 0
 
 
+def _zero_tests_with_selector_warning(
+    command: str, evidence: str | None, project_root: Path | None
+) -> str | None:
+    """选择器存在却 0 命中 → WARN（E-2）。
+
+    surefire 插件级 ``<excludedGroups>`` 会压过命令行空值覆盖，
+    `-Dgroups=X` 选择器 0 命中仍 exit 0——只看退出码就是假阳性
+    （2026-08-30 demo-datasource 集成测试静默 0 执行实测）。
+    证据文本出现 Tests run: 0 且命令含选择器时，record 给出醒目警告。
+    """
+    if not evidence:
+        return None
+    selectors = ("-Dgroups=", "-Dtest=", "--groups", "--filter", "-DfailIfNoSpecifiedTests")
+    if not any(selector in str(command) for selector in selectors):
+        return None
+    candidates = [Path(evidence)]
+    if project_root is not None and not Path(evidence).is_absolute():
+        candidates.insert(0, project_root / evidence)
+    text: str | None = None
+    for candidate in candidates:
+        try:
+            if candidate.is_file() and candidate.stat().st_size <= 4 * 1024 * 1024:
+                text = candidate.read_text(encoding="utf-8", errors="replace")
+                break
+        except OSError:
+            continue
+    if text is None:
+        return None
+    zero = re.search(
+        r"Tests run:\s*0,\s*Failures:\s*0,\s*Errors:\s*0", text
+    )
+    ran_something = re.search(r"Tests run:\s*[1-9]", text)
+    if zero is not None and ran_something is None:
+        return (
+            "ZERO_TESTS_WITH_SELECTOR: 命令含测试选择器但 Tests run=0（exit 0 不代表通过）；"
+            "常见于 surefire 插件级 excludedGroups 压过命令行覆盖——检查 pom 是否写死 "
+            "<excludedGroups>（应改为 ${excludedGroups} 属性占位）"
+        )
+    return None
+
+
 def cmd_scenario_receipt_template(args: argparse.Namespace) -> int:
     """Emit a schema-v2 receipt skeleton built from the scenario manifest.
 
@@ -3202,8 +3258,32 @@ def cmd_scenario_receipt_template(args: argparse.Namespace) -> int:
         return 0
     out_path = Path(str(out_raw)).expanduser()
     if not out_path.is_absolute():
-        out_path = change_dir / out_path
+        # 防双重拼接（E-1）：调用方按 CLI 惯例传 cwd 相对路径时（如
+        # .harness/changes/<cn>/evidence/x.json），直接拼 change_dir 会产生嵌套
+        # 幽灵目录。相对路径若以 change-dir 自身前缀开头，按 cwd 解析；否则按
+        # 文档规则相对 change-dir 解析。
+        cwd = Path.cwd().resolve()
+        change_resolved = change_dir.resolve()
+        if _is_relative_to(change_resolved, cwd):
+            change_rel = change_resolved.relative_to(cwd)
+            if out_path.parts[: len(change_rel.parts)] == change_rel.parts:
+                out_path = cwd / out_path
+            else:
+                out_path = change_dir / out_path
+        else:
+            out_path = change_dir / out_path
     out_path = out_path.resolve()
+    change_resolved = change_dir.resolve()
+    cwd = Path.cwd().resolve()
+    if not (
+        _is_relative_to(out_path, change_resolved)
+        or _is_relative_to(out_path, cwd)
+    ):
+        return emit_error(
+            "--out 解析后越出项目目录: " + str(out_path),
+            as_json=as_json,
+            error_code="SCENARIO_RECEIPT_OUT_OF_PROJECT",
+        )
     try:
         out_path.parent.mkdir(parents=True, exist_ok=True)
         out_path.write_text(body, encoding="utf-8", newline="\n")
@@ -3321,7 +3401,7 @@ def build_parser() -> argparse.ArgumentParser:
     p_hash.set_defaults(func=cmd_hash)
 
     p_reuse = sub.add_parser("can-reuse", parents=[shared_json], help="decide whether a verification can be reused")
-    p_reuse.add_argument("--change-dir", required=True)
+    p_reuse.add_argument("--change-dir", "--change", dest="change_dir", required=True)
     p_reuse.add_argument(
         "--verification",
         required=True,
@@ -3389,7 +3469,7 @@ def build_parser() -> argparse.ArgumentParser:
     p_reuse.set_defaults(func=cmd_can_reuse)
 
     p_record = sub.add_parser("record", parents=[shared_json], help="write validation result into ledger")
-    p_record.add_argument("--change-dir", required=True)
+    p_record.add_argument("--change-dir", "--change", dest="change_dir", required=True)
     p_record.add_argument("--verification", required=True)
     p_record.add_argument("--status", required=True)
     p_record.add_argument("--command", required=True)
@@ -3515,7 +3595,7 @@ def build_parser() -> argparse.ArgumentParser:
             "pre-filled from meta/scenario-manifest.json"
         ),
     )
-    p_receipt.add_argument("--change-dir", required=True)
+    p_receipt.add_argument("--change-dir", "--change", dest="change_dir", required=True)
     p_receipt.add_argument(
         "--scenario-ids",
         required=True,

package/harness/bundles/general/pi/scripts/harness_process.py

@@ -15,6 +15,7 @@ import json
 import os
 from pathlib import Path
 import signal
+import shutil
 import subprocess
 import sys
 import time
@@ -946,6 +947,23 @@ def capture_owned_members(spawned: SpawnedProcess) -> dict[str, Any] | None:
     return proof
 
 
+def resolve_windows_executable(argv: Sequence[str]) -> list[str]:
+    """Windows 无扩展名命令解析为实际可执行文件（F-1）。
+
+    CreateProcess 不走 shell，`mvn`/`npm` 这类 .cmd 包装会报 WinError 2；
+    shutil.which 遵循 PATHEXT 能找到 mvn.cmd。POSIX 或未命中时原样返回。
+    """
+    if os.name != "nt" or not argv:
+        return list(argv)
+    head = argv[0]
+    if not isinstance(head, str) or not head or os.path.splitext(head)[1]:
+        return list(argv)
+    resolved = shutil.which(head)
+    if resolved is None:
+        return list(argv)
+    return [resolved, *argv[1:]]
+
+
 def spawn_structured_argv(
     argv: Sequence[str],
     *,

package/harness/bundles/general/pi/scripts/harness_runtime.py

@@ -1099,6 +1099,9 @@ def _spawn_detached_worker(
     env: dict[str, str],
     output: Any = subprocess.DEVNULL,
 ) -> subprocess.Popen[bytes]:
+    from harness_process import resolve_windows_executable
+
+    argv = resolve_windows_executable(argv)
     kwargs: dict[str, Any] = {
         "cwd": str(cwd),
         "env": env,
@@ -1171,6 +1174,40 @@ def start_run_session(
     working_directory = working_directory.expanduser().resolve()
     if not working_directory.is_dir():
         raise ValueError(f"RUN_SESSION_WORKDIR_MISSING: {working_directory}")
+    # F-2：fixback 会话缺 product-identity 时白跑一轮、register 才拒。批次开着
+    # 就从 baseProductIdentity 自动注入；没有 OPEN 批次则当场拒绝（2026-08-31
+    # demo-datasource 实测）。
+    if verification.startswith("fixback") and not (
+        product_identity and product_identity.strip()
+    ):
+        batches_dir = state_root / "fixback" / "batches"
+        open_identity: str | None = None
+        open_batch_id: str | None = None
+        if batches_dir.is_dir():
+            for batch_file in sorted(batches_dir.glob("*.json")):
+                try:
+                    batch = json.loads(batch_file.read_text(encoding="utf-8-sig"))
+                except (OSError, json.JSONDecodeError):
+                    continue
+                if (
+                    isinstance(batch, dict)
+                    and batch.get("status") == "OPEN"
+                    and isinstance(batch.get("baseProductIdentity"), str)
+                    and batch["baseProductIdentity"].strip()
+                ):
+                    open_identity = str(batch["baseProductIdentity"]).strip()
+                    open_batch_id = str(batch.get("batchId") or "")
+                    break
+        if open_identity is None:
+            raise ValueError(
+                "FIXBACK_PRODUCT_IDENTITY_REQUIRED: fixback 会话必须有产品身份——"
+                "传 --product-identity，或先启动 fixback 批次（其 baseProductIdentity "
+                "会被自动注入）"
+            )
+        product_identity = open_identity
+        product_identity_source = f"fixback-batch:{open_batch_id}"
+    else:
+        product_identity_source = None
     session_id = session_id or f"run-{uuid.uuid4().hex}"
     run_id = run_id or session_id
     session_root = _run_session_root(state_root, session_id)
@@ -1215,6 +1252,11 @@ def start_run_session(
         "heartbeatSeconds": heartbeat_seconds,
         "expectedDurationSeconds": expected_duration_seconds,
         "productIdentity": product_identity,
+        **(
+            {"productIdentitySource": product_identity_source}
+            if product_identity_source is not None
+            else {}
+        ),
         "resourceLocks": normalized_resource_locks,
         "resourceLockTokens": {},
         "resourceWaitMs": 0,
@@ -1427,8 +1469,12 @@ def _run_session_worker(state_root: Path, session_id: str) -> int:
             "wb", buffering=0
         ) as stderr:
             try:
-                from harness_process import spawn_structured_argv
+                from harness_process import (
+                    resolve_windows_executable,
+                    spawn_structured_argv,
+                )
 
+                argv = resolve_windows_executable(argv)
                 spawned = spawn_structured_argv(
                     argv,
                     cwd=Path(str(receipt["workingDirectory"])),

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

@@ -2,5 +2,5 @@
   "schemaVersion": 1,
   "overlay": "java",
   "agent": "claude-code",
-  "coreHash": "8334c3150a633202"
+  "coreHash": "916ab39c6dcafe3a"
 }

package/harness/bundles/java/claude-code/harness-apidoc/SKILL.md

@@ -21,7 +21,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=8334c3150a633202; overlay=java; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=916ab39c6dcafe3a; overlay=java; agent=claude-code; do not edit -->
 # harness-apidoc — 前端接口文档（Java overlay）
 
 ## Purpose

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

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

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

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

package/harness/bundles/java/claude-code/harness-execute/SKILL.md

@@ -23,7 +23,7 @@ disallowed-tools:
   - Bash(node *)
   - Bash(codegraph *)
 ---
-<!-- generated by harness_deploy.py; core=8334c3150a633202; overlay=java; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=916ab39c6dcafe3a; overlay=java; agent=claude-code; do not edit -->
 # harness-execute — 执行（编码 + 验证）
 
 > 2026-08 阶段合并：原 `run`（编码）与 `test`（验证）合并为单一 `execute` 阶段；
@@ -80,13 +80,15 @@ disallowed-tools:
 
 ## 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/claude-code/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/claude-code/harness-knowledge-ingest/SKILL.md

@@ -8,7 +8,7 @@ disallowed-tools:
   - Bash(git *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=8334c3150a633202; overlay=java; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=916ab39c6dcafe3a; overlay=java; agent=claude-code; do not edit -->
 # harness-knowledge-ingest
 
 知识 ingest 完全由 Hunter Platform 负责。归档完成时，客户端生成一个确定性 ZIP；
@@ -46,6 +46,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/claude-code/harness-knowledge-query/SKILL.md

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

package/harness/bundles/java/claude-code/harness-package/SKILL.md

@@ -21,7 +21,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=8334c3150a633202; overlay=java; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=916ab39c6dcafe3a; overlay=java; agent=claude-code; do not edit -->
 # harness-package — 增量模块打包（Java overlay）
 
 ## Purpose

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

@@ -21,7 +21,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=8334c3150a633202; overlay=java; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=916ab39c6dcafe3a; overlay=java; agent=claude-code; do not edit -->
 # harness-plan — 需求规划
 
 ## Purpose
@@ -86,10 +86,10 @@ disallowed-tools:
 | 阶段 | 动作 |
 |------|------|
 | 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/claude-code/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/claude-code/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/claude-code/harness-pull/SKILL.md

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

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

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

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

@@ -22,7 +22,7 @@ disallowed-tools:
   - Bash(curl *)
   - Bash(codegraph *)
 ---
-<!-- generated by harness_deploy.py; core=8334c3150a633202; overlay=java; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=916ab39c6dcafe3a; overlay=java; agent=claude-code; do not edit -->
 # harness-review — 代码审查
 
 ## Purpose
@@ -75,6 +75,17 @@ review 默认优先在独立上下文执行，避免主会话已形成的实现
 
 无隔离能力、定义损坏、spawn 失败、空返回或只有元数据时，不重试，立即由主会话按同一 6 维度检查清单完成审查。无论是否委派，都必须追加一条结构化 `decision` 事件：`--execution-mode delegated|inline` 标明执行方式；委派时写 `--executor-agent harness-reviewer --decision-reason-code REVIEW_DELEGATED`；回退时只写一个 `--fallback-reason-code REVIEW_INLINE_UNAVAILABLE|REVIEW_INLINE_SPAWN_FAILED|REVIEW_INLINE_INVALID_RESULT`。`decision` 和 `reason` 必须用中文完整说明，禁止把原因码拼进正文。正常主会话评审是可接受结果，不显示成流程故障；`fallbackPolicy=inline-no-retry`。
 
+完整示例（委派路径，可直接复制改参）：
+
+```bash
+python <skills-root>/scripts/harness_events.py append --change-dir ".harness/changes/<cn>" \
+  --phase review --type decision --execution-mode delegated \
+  --executor-agent harness-reviewer --decision-reason-code REVIEW_DELEGATED \
+  --decision "已使用独立评审完成 6 维度审查" --reason "固定 reviewer 可用，避免主会话实现结论影响审查" --json
+```
+
+注意：`decision` 事件**不接受** `--name`/`--status`（那是 verification 的字段）；`issue` 事件必须带 `--severity`。
+
 项目规模小、风险低或没有 CodeGraph 都不是跳过独立评审的理由。原因码是稳定机器字段，仅用于协议与技术详情；面向用户的事件摘要必须写成「已使用独立评审」或「当前环境没有可用的隔离评审能力，已由主会话完成评审」等中文说明。
 
 3. **持久化报告与事实 sidecar（强制，主会话）** — Agent 返回后主会话 Write 到 `reports/review/review-report-*.md`，并调用 `python <skills-root>/scripts/harness_review.py scaffold --change-dir <change-dir> [--run-id <id>]` 生成 findings 写入骨架（runId 缺省从 events.ndjson 最新 review phase.start 推断），补齐每一条发现后经 `harness_review.py write-findings --change-dir <change-dir> --stdin` 落地。每条发现必须填写 `fixbackAction=code|manual|workflow`：只有确实需要修改产品代码的项使用 `code`；人工验收用 `manual`；流程、暂存或工具使用建议用 `workflow`。权威计数来自 `reports/review/review-findings.json`，不是 Markdown。任一写入缺失 → 评审未完整结束，不得关门。

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

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

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

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