@hunter-harness/workflow-harness 0.2.54 → 0.2.55

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

@@ -30,6 +30,7 @@ if str(SCRIPTS_DIR) not in sys.path:
     sys.path.insert(0, str(SCRIPTS_DIR))
 
 import harness_change as hc  # noqa: E402
+import harness_context as hctx  # noqa: E402
 import harness_events as he  # noqa: E402
 import harness_events_sync as hes  # noqa: E402
 import harness_ledger as hl  # noqa: E402
@@ -1602,6 +1603,18 @@ def append_phase_event(
     auto_sealed: list[dict[str, Any]] = []
     with he.event_file_lock(lock_path):
         existing = he.load_events(events_file)
+        phase_attempts = he.split_phase_attempts(
+            [event for event in existing if event.get("phase") == phase]
+        )
+        latest_attempt = max(
+            (
+                int(item.get("attempt"))
+                for item in phase_attempts
+                if isinstance(item.get("attempt"), int)
+            ),
+            default=0,
+        )
+        event_attempt = latest_attempt + 1 if type_ == "phase.start" else latest_attempt or 1
         args = argparse.Namespace(
             phase=phase,
             type=type_,
@@ -1619,12 +1632,18 @@ def append_phase_event(
             decision=None,
             reason=None,
             run_id=run_id,
-            attempt=None,
+            attempt=event_attempt,
             executor_tool=executor_tool,
             executor_agent=executor_agent,
             executor_model=executor_model,
             handoff_from_tool=None,
             handoff_reason=None,
+            execution_mode=None,
+            decision_reason_code=None,
+            fallback_reason_code=None,
+            trigger=("fixback" if "fixback" in note.lower() else None),
+            from_phase=("review" if phase == "run" and "fixback" in note.lower() else None),
+            result_status=None,
         )
         event = he.build_event(args, existing)
         if identity:
@@ -1655,6 +1674,7 @@ def append_phase_event(
         content = he.render_execution_log(events)
         log_path = he.write_execution_log(change_dir, content)
         rendered = True
+    he.nudge_remote_sync(change_dir)
     return {
         "ok": True,
         "eventId": event.get("id"),
@@ -1702,6 +1722,80 @@ def _phase_event_exists(change_dir: Path, phase: str, type_: str, run_id: str) -
     )
 
 
+def _latest_phase_end(
+    change_dir: Path,
+    phase: str,
+    run_id: str | None = None,
+) -> dict[str, Any] | None:
+    for event in reversed(he.load_events(he.events_path(change_dir))):
+        if event.get("phase") != phase or event.get("type") != "phase.end":
+            continue
+        if run_id and event.get("run_id") != run_id:
+            continue
+        return event
+    return None
+
+
+def _terminal_matches_context_session(
+    project: Path,
+    change_id: str,
+    phase: str,
+    terminal: dict[str, Any],
+) -> bool:
+    view = hctx.context_view(project, change_id)
+    current = view.get("current") if isinstance(view, dict) else None
+    if not isinstance(current, dict) or current.get("phase") != phase:
+        return False
+    prepared_at = he.parse_timestamp(current.get("preparedAt"))
+    terminal_at = he.parse_timestamp(
+        terminal.get("timestamp") or terminal.get("occurred_at")
+    )
+    return (
+        prepared_at is not None
+        and terminal_at is not None
+        and terminal_at >= prepared_at
+    )
+
+
+def _close_context_handoff(
+    project: Path,
+    change_id: str,
+    args: argparse.Namespace,
+    *,
+    status: str,
+) -> dict[str, Any] | None:
+    to_phase = getattr(args, "to_phase", None)
+    if not to_phase:
+        return None
+    try:
+        return hctx.close_transition(
+            project,
+            change_id,
+            from_phase=args.phase,
+            to_phase=str(to_phase),
+            executor=getattr(args, "executor", None),
+            artifacts=list(getattr(args, "artifact", None) or []),
+            status=status,
+        )
+    except Exception as exc:  # noqa: BLE001 — phase close remains locally durable
+        return {
+            "ok": False,
+            "code": "CONTEXT_HANDOFF_FAILED",
+            "message": str(exc),
+        }
+
+
+def _sync_after_phase_close(project: Path, change_dir: Path) -> dict[str, Any]:
+    try:
+        return hes.auto_events_sync(project, change_dir)
+    except Exception as exc:  # noqa: BLE001 — remote sync is recoverable
+        return {
+            "ok": False,
+            "code": "PLATFORM_EVENTS_SYNC_WARN",
+            "warning": f"events-sync hook failed: {exc}",
+        }
+
+
 def _validate_scenario_coverage(change_dir: Path) -> dict[str, Any]:
     """C9: validate all ledger-required scenarios are covered by ledger entries.
 
@@ -2266,6 +2360,48 @@ def cmd_close(args: argparse.Namespace) -> int:
     explicit_run_id = args.run_id or os.environ.get("HUNTER_HARNESS_RUN_ID")
     current_lease = hc.inspect_lease(project, resolved["changeId"])
     if current_lease is None:
+        terminal = _latest_phase_end(change_dir, args.phase, explicit_run_id)
+        if (
+            getattr(args, "to_phase", None)
+            and terminal is not None
+            and _terminal_matches_context_session(
+                project, str(resolved["changeId"]), args.phase, terminal
+            )
+        ):
+            terminal_status = str(terminal.get("status") or args.status)
+            handoff = _close_context_handoff(
+                project,
+                str(resolved["changeId"]),
+                args,
+                status=terminal_status,
+            )
+            monitor = _sync_after_phase_close(project, change_dir)
+            if not isinstance(handoff, dict) or not handoff.get("ok"):
+                return emit_error(
+                    "PHASE_HANDOFF_PENDING",
+                    "phase gate is closed, but context handoff still needs attention",
+                    as_json=as_json,
+                    extra={
+                        "localCloseComplete": True,
+                        "retryable": True,
+                        "contextHandoff": handoff,
+                        "platformMonitor": monitor,
+                    },
+                )
+            emit(
+                {
+                    "ok": True,
+                    "code": "PHASE_CLOSE_RESUMED",
+                    "phase": args.phase,
+                    "status": terminal_status,
+                    "changeId": resolved["changeId"],
+                    "localCloseComplete": True,
+                    "contextHandoff": handoff,
+                    "platformMonitor": monitor,
+                },
+                as_json=as_json,
+            )
+            return 0
         return emit_error("LEASE_ABSENT", "no active lease for phase close", as_json=as_json)
     run_id = explicit_run_id or str(current_lease.get("runId") or "")
     if str(current_lease.get("runId")) != run_id or str(current_lease.get("phase")) != args.phase:
@@ -2597,6 +2733,29 @@ def cmd_close(args: argparse.Namespace) -> int:
         capsule["closeStatus"] = close_status
         write_phase_capsule(change_dir, args.phase, run_id, capsule)
 
+    context_handoff = _close_context_handoff(
+        project,
+        str(resolved["changeId"]),
+        args,
+        status=close_status,
+    )
+    platform_monitor = _sync_after_phase_close(project, change_dir)
+    if isinstance(context_handoff, dict) and not context_handoff.get("ok"):
+        return emit_error(
+            "PHASE_HANDOFF_PENDING",
+            "phase gate closed locally, but context handoff failed; retry the same close command",
+            as_json=as_json,
+            extra={
+                "localCloseComplete": True,
+                "retryable": True,
+                "phase": args.phase,
+                "status": close_status,
+                "changeId": resolved["changeId"],
+                "contextHandoff": context_handoff,
+                "platformMonitor": platform_monitor,
+            },
+        )
+
     payload = {
         "ok": True,
         "code": close_code,
@@ -2612,6 +2771,8 @@ def cmd_close(args: argparse.Namespace) -> int:
         "lease": release,
         "gateSeverityMode": severity_mode,
         "gateWarnings": gate_warnings,
+        "contextHandoff": context_handoff,
+        "platformMonitor": platform_monitor,
     }
     emit(payload, as_json=as_json)
     return 0
@@ -2806,6 +2967,9 @@ def build_parser() -> argparse.ArgumentParser:
     p_close.add_argument("--run-id", default=None)
     p_close.add_argument("--task", type=int, default=None)
     p_close.add_argument("--note", default="")
+    p_close.add_argument("--to-phase", default=None)
+    p_close.add_argument("--executor", default=None)
+    p_close.add_argument("--artifact", action="append", default=[])
     p_close.set_defaults(func=cmd_close)
 
     p_classify = sub.add_parser("classify", parents=[shared])

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

@@ -1160,6 +1160,8 @@ _DYNAMIC_OWN_DIRS = ("events.ndjson", "logs", "evidence", "reports", "runtime",
 
 def _matches_ownership_path(rel: str, declared: Any) -> bool:
     scope = str(declared).replace("\\", "/").strip("/")
+    if scope.endswith("/**"):
+        scope = scope[:-3].rstrip("/")
     if not scope:
         return False
     normalized = rel.replace("\\", "/").strip("/")

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

@@ -1155,6 +1155,7 @@ def finalize_plan(
                 "artifactsHash": validation["artifactsHash"],
                 "files": validation["files"],
                 "receiptPath": str(receipt_path),
+                "artifactRef": "meta/plan-finalization.json",
             }
 
     lock_path.parent.mkdir(parents=True, exist_ok=True)
@@ -1253,6 +1254,7 @@ def finalize_plan(
             "artifactsHash": validation["artifactsHash"],
             "files": validation["files"],
             "receiptPath": str(receipt_path),
+            "artifactRef": "meta/plan-finalization.json",
             "executionLogPath": str(harness_events.execution_log_path(change_dir)),
         }
     except OSError as exc:

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

@@ -1593,18 +1593,15 @@ def close(project: Path | str, change_dir: Path | str) -> dict[str, Any]:
             [],
             error=str(exc),
         )
-    if (
+    profile_changed = bool(
         isinstance(snapshot.get("profileFingerprint"), str)
         and snapshot["profileFingerprint"] != current_profile_fingerprint
-    ):
-        return _result(False, action, "PROFILE_CHANGED", [])
+    )
     baseline_commit = _snapshot_baseline_commit(
         project_root,
         change_root,
         snapshot,
     )
-    profile_changed = False
-
     before_entries = snapshot.get("files")
     if not isinstance(before_entries, list):
         return _result(False, action, "SNAPSHOT_INVALID", [])
@@ -1682,11 +1679,21 @@ def close(project: Path | str, change_dir: Path | str) -> dict[str, Any]:
             return result
 
     recorded = [rel for rel, _ in touched]
-    reconciliation = _reconcile_close_manifest(
-        project_root,
-        change_root,
-        set(recorded),
-        baseline_commit,
+    reconciliation = (
+        {
+            "ok": True,
+            "code": "PROFILE_REBASED_MANIFEST_PRESERVED",
+            "removedCurrentTouches": 0,
+            "deletedEntries": 0,
+            "preservedForeignEntries": 0,
+        }
+        if profile_changed
+        else _reconcile_close_manifest(
+            project_root,
+            change_root,
+            set(recorded),
+            baseline_commit,
+        )
     )
     if not reconciliation.get("ok"):
         return _result(
@@ -1696,40 +1703,26 @@ def close(project: Path | str, change_dir: Path | str) -> dict[str, Any]:
             list(reconciliation.get("files") or []),
         )
 
-    # Cross-check (retro §5.10): if the manifest has active entries for this
-    # change but close computed recordedCount=0, the snapshot/manifest/diff
-    # are inconsistent. Fail closed instead of silently returning success.
-    manifest_path = _manifest_path(change_root)
-    if manifest_path is not None and manifest_path.is_file():
-        try:
-            manifest = _read_json(manifest_path)
-        except (OSError, json.JSONDecodeError):
-            manifest = None
-        if isinstance(manifest, dict):
-            manifest_files = manifest.get("files")
-            if isinstance(manifest_files, list):
-                is_v2 = manifest.get("schemaVersion") == 2
-                change_id = change_root.name
-                active_entries = [
-                    f for f in manifest_files
-                    if isinstance(f, dict)
-                    and f.get("reason") in ("tdd-created", "test-updated", "stale-test-repair")
-                    and (
-                        not is_v2
-                        or f.get("introducedBy") == change_id
-                        or change_id in (f.get("touchedBy") or [])
-                    )
-                ]
-                if active_entries and not recorded:
-                    return _result(
-                        False,
-                        action,
-                        "MANIFEST_DIFF_HASH_MISMATCH",
-                        [],
-                        manifestEntries=len(active_entries),
-                        recordedCount=0,
-                        detail="manifest has active entries but close computed 0 recorded tests",
-                    )
+    # A manifest is change-wide and intentionally survives phase boundaries.
+    # Therefore pre-existing entries with no new diff are consistent and must
+    # not force a test-guard reset. When the build profile changes mid-phase,
+    # retain the diff result and rebaseline the reusable snapshot atomically.
+    if profile_changed:
+        snapshot.update(
+            {
+                "profileFingerprint": current_profile_fingerprint,
+                "capturedAt": time.strftime("%Y-%m-%dT%H:%M:%S"),
+                "files": [
+                    {
+                        "path": rel,
+                        "sha256": digest,
+                        "ignored": _is_ignored(project_root, rel),
+                    }
+                    for rel, digest in sorted(current.items())
+                ],
+            }
+        )
+        _write_json(snapshot_path, snapshot)
 
     return _result(
         True,

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

@@ -2,5 +2,5 @@
   "schemaVersion": 1,
   "overlay": "java",
   "agent": "codebuddy",
-  "coreHash": "790b0d238b58acd7"
+  "coreHash": "219ad7fdedbec84f"
 }

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=790b0d238b58acd7; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=219ad7fdedbec84f; 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=790b0d238b58acd7; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=219ad7fdedbec84f; 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=790b0d238b58acd7; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=219ad7fdedbec84f; 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=790b0d238b58acd7; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=219ad7fdedbec84f; 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=790b0d238b58acd7; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=219ad7fdedbec84f; 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=790b0d238b58acd7; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=219ad7fdedbec84f; 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=790b0d238b58acd7; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=219ad7fdedbec84f; overlay=java; agent=codebuddy; do not edit -->
 # harness-plan — 需求规划
 
 ## Purpose
@@ -74,7 +74,7 @@ description: 将需求转化为设计文档+实施计划+完整测试场景表
 | 4 | **设计审批包** blocking user confirmation；确认事件早于 approved 设计文档和 `meta/worktree.json` |
 | 5–6 | plan + implementation-detail + test-scenarios → `plans/` |
 | 7.5 | 仅 `--adversarial` 对抗评审 |
-| 8 | 在临时产物集上运行 `harness_plan_finalize.py finalize`，随后立即运行 `verify`；成功后执行 `harness_context.py close --from-phase plan --to-phase run --executor <tool> --artifact <plan-finalization> --json` 写 append-only handoff receipt；原子发布、派生清单计数对账、完整生命周期、render → `checklist.md` |
+| 8 | 在临时产物集上运行 `harness_plan_finalize.py finalize`，随后立即运行 `verify`；成功后把 finalizer 返回的绝对 `receiptPath` 原样传给 `harness_context.py close --from-phase plan --to-phase run --executor <tool> --artifact "<receiptPath>" --json`（也可使用返回的稳定 `artifactRef=meta/plan-finalization.json`），写 append-only handoff receipt；不得手写占位路径；原子发布、派生清单计数对账、完整生命周期、render → `checklist.md` |
 
 change-name 范围变更 → 提示重命名或记 🟡WARN（→ `reference.md`）
 

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

@@ -211,13 +211,14 @@ source: harness-plan
 
 - [ ] 所有待发布产物先写入 staging，不直接覆盖正式 change 目录
 - [ ] 执行 `harness_plan_finalize.py finalize --change-dir ... --staging-dir ... --change ... --run-id <plan-run-id> --attempt <attempt> --json`；身份必须与本次 `phase.start` 完全相同
-- [ ] finalizer 返回 `ok=true` 与 `artifactsHash`；重复执行返回 `idempotent=true`
+- [ ] finalizer 返回 `ok=true`、`artifactsHash`、绝对 `receiptPath` 与稳定 `artifactRef=meta/plan-finalization.json`；重复执行返回 `idempotent=true`
 - [ ] 紧接着执行 `harness_plan_finalize.py verify --change-dir ... --json`
 - [ ] verify 返回 `phaseStartCount=1`、`phaseEndCount=1`、`phaseEndStatus=OK`、`receiptConsistent=true`
 - [ ] 收据 `files` 完整包含 design / plan / implementation-detail / test-scenarios / gate-policy / worktree 六项标准产物；不得省略、重复或经 symlink/junction/reparse point 引用
 - [ ] verify 的 `taskCount` 等于全部任务表行数，`scenarioCount` 等于 Markdown 中全部唯一场景 ID 数；任一为 0 或不一致即 ❌FAIL
 - [ ] finalizer 失败时正式目录无半发布产物、无成功 `phase.end`、无伪造 execution log
 - [ ] 禁止在 finalizer 之前手工追加成功 `phase.end`
+- [ ] context close 的 `--artifact` 只传 finalizer 原样返回的 `receiptPath` 或 `artifactRef`，不得猜测、拼接或使用 `<plan-finalization>` 占位文本
 
 | 文件 | 必须存在 | 检查结果 |
 |------|:---:|:---:|

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=790b0d238b58acd7; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=219ad7fdedbec84f; overlay=java; agent=codebuddy; do not edit -->
 # harness-review — 代码审查
 
 ## Purpose
@@ -45,14 +45,16 @@ description: 6维度代码审查（架构/安全/规范/兼容/测试/性能）
 
 ## Workflow
 
-先用 `harness_context.py prepare --phase review --executor <tool> [--change <id>] --json` 与 `harness_context.py begin --phase review --change <id> --executor <tool> --json` 解析唯一 active change 并校验 test→review receipt；多个 active change 未显式选择时返回 `ACTIVE_CHANGE_AMBIGUOUS`，禁止再按 Glob/mtime 猜测。阶段门禁使用 `harness_gate.py begin --phase review --change <id> --task <n> --skills-root <skills-root> --executor-tool <tool> --json` 和 `harness_gate.py close --phase review --change <id> --status <OK|WARN|FAIL> --run-id <begin-run-id> --json`；之后通过 `harness_context.py close --from-phase review --to-phase submit|run --executor <tool> --json` 交接或 fixback。不得手工追加 `phase.start/phase.end`；任一 close 失败不得宣称审查完成。
+先用 `harness_context.py prepare --phase review --executor <tool> [--change <id>] --json` 与 `harness_context.py begin --phase review --change <id> --executor <tool> --json` 解析唯一 active change 并校验 test→review receipt；多个 active change 未显式选择时返回 `ACTIVE_CHANGE_AMBIGUOUS`，禁止再按 Glob/mtime 猜测。阶段门禁使用 `harness_gate.py begin --phase review --change <id> --task <n> --skills-root <skills-root> --executor-tool <tool> --json`；结束时只执行一次 `harness_gate.py close --phase review --change <id> --status <OK|WARN|FAIL> --run-id <begin-run-id> --to-phase submit|run --executor <tool> --json`，由 gate 完成阶段事件、租约、上下文交接与远端补传。不得手工追加 `phase.start/phase.end` 或再次调用 context close；任一 close 失败不得宣称审查完成。
 
 0. **启动准备** — 确定变更名（Glob `.harness/changes/*/plans/*-plan.md`，排除 `.harness/archive/*/`，读 frontmatter 提取 change-name）；**append `phase.start` 事件**（不得等审查完成才补）
 1. **读取 worktree 状态（门禁检查）** — 读 `.harness/changes/<change-name>/meta/worktree.json`：`requested=true` 但 worktree 不存在 → 停止并提示先修复 `harness-run`，不得静默回主目录（否则 git diff 为空）；`requested=true` 且 worktree 已创建 → spawned agent 用该 worktree 路径执行 `git diff`（确保审查 worktree 变更而非主目录）；`requested=false` → 审查主目录变更
 <!-- @section-id review.delegate -->
-### 2. 审查执行（风险分级、inline 优先）
+### 2. 审查执行（隔离 reviewer 优先）
 
-默认由主会话按同一 6 维度检查清单审查。仅发布候选，或变更命中权限/安全、支付、数据迁移、并发幂等、公共契约、跨模块核心路径时，才考虑隔离 reviewer；需要固定 `harness-reviewer` 时执行一次 `python <skills-root>/scripts/harness_preflight.py check-agents --skills-root <skills-root> --agent harness-reviewer --json`。只有 `executionMode=delegated` 才委派；`executionMode=inline` 静默由主会话审查，不显示缺失告警。定义损坏、spawn 失败、空返回或只有元数据 → 记录一次 issue 后直接主会话审查，`fallbackPolicy=inline-no-retry`。
+review 默认优先在独立上下文执行，避免主会话已形成的实现结论影响审查。阶段开始后只做一次能力判定：固定 reviewer 可用时执行 `python <skills-root>/scripts/harness_preflight.py check-agents --skills-root <skills-root> --agent harness-reviewer --json`；宿主提供通用隔离任务能力时可直接委派一次只读审查。委派只读取 diff、规则和测试证据，主会话负责最终核验与落盘。
+
+无隔离能力、定义损坏、spawn 失败、空返回或只有元数据时，不重试，立即由主会话按同一 6 维度检查清单完成审查。无论是否委派，都必须追加一条 `decision` 事件：`executor_agent=harness-reviewer` 表示已委派；`decision` 写执行方式，`reason` 写选择或回退原因，稳定原因码使用 `REVIEW_DELEGATED`、`REVIEW_INLINE_UNAVAILABLE`、`REVIEW_INLINE_SPAWN_FAILED` 或 `REVIEW_INLINE_INVALID_RESULT`。正常 inline 是可接受结果，不显示成流程故障；`fallbackPolicy=inline-no-retry`。
 
 3. **持久化报告与事实 sidecar（强制，主会话）** — Agent 返回后主会话 Write 到 `reports/review/review-report-*.md`，并把同一批发现写成临时 JSON 后调用 `python <skills-root>/scripts/harness_review.py write-findings --change-dir <change-dir> --input <findings.json>`。权威计数来自 `reports/review/review-findings.json`，不是 Markdown。任一写入缺失 → 🟡WARN，不得宣称 review 完成。
 4. **生成修复反馈（原生协议）** — 若报告存在 RED/YELLOW 问题，执行 `protocols.md` 的 `review-fixback-protocol`，将问题转化为结构化 fixback 清单并落盘到 `.harness/changes/<change-name>/reports/review/fixback-YYYYMMDD-HHmm.md`；随后把 disposition 临时 JSON 交给 `python <skills-root>/scripts/harness_review.py write-dispositions --change-dir <change-dir> --input <dispositions.json>`，权威状态写入 `reports/review/fixback-dispositions.json`。若无 RED/YELLOW，也必须写空 findings sidecar，并记录 `review-fixback-protocol: skipped(no findings)`。不调用 Superpowers `receiving-code-review`，也不记录外部 skill 降级。

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=790b0d238b58acd7; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=219ad7fdedbec84f; overlay=java; agent=codebuddy; do not edit -->
 # harness-run — 需求编码
 
 ## Purpose
@@ -60,11 +60,11 @@ description: 按变更簇执行 TDD 编码循环（RED→GREEN→REFACTOR→编
 ## Workflow 概要
 
 0. 加载上下文：先 `harness_context.py prepare --phase run --executor <tool> [--change <id>] --json`，以返回的唯一 change/executionRoot/transition receipt 为准（多 active 缺参 → `ACTIVE_CHANGE_AMBIGUOUS`，禁止按 mtime 猜测）；再 **`harness_context.py begin --phase run --change <id> --executor <tool> --json`** 校验 Plan artifact/hash/HEAD，读 spec/plan/detail/scenarios/ledger/run-task-status/worktree；`--fixback` 读 fixback → **`harness_gate.py begin --phase run --change <id>`**（claim + phase.start + identity；禁止手工 Write `events.ndjson` / 手工 `phase.end`）。**C3 钩子**：`harness_gate.py begin` 在已连接平台时会 best-effort 调用 events-sync（注册 run / `running`）；失败只告警，不阻断 begin。
-0.5. **测试基础设施探测**（先写 `CHECKING`，四项证据齐备后再结论）→ `reference.md` Step 0.5；进入 TDD 前执行 `harness_test_guard.py begin --project . --change-dir ".harness/changes/<cn>" --json`
+0.5. **测试基础设施探测**（先写 `CHECKING`，四项证据齐备后再结论）→ `reference.md` Step 0.5；测试基线已由上一步 gate begin 内部建立，不得再次执行 guard begin
 1. **变更簇 TDD** — `protocols.md` `run-tdd-protocol`；批量 RED/GREEN；按需 `change-cluster-review-protocol`（高风险 + reviewer 预检可用）
 2. 构建验证 + **仅**通过 `harness_ledger.py record` 写 ledger（禁止 Write/Edit `verification-ledger.json`）；`diff-hash --change-dir` 纳入 ignored tests → `reference.md` Step 2c
 3. **场景覆盖检查**（场景表映射，禁止用用例数冒充场景数）
-4. **关门检查**（10 项）→ `harness_test_guard.py close` → **`harness_gate.py close --phase run --change <id> --status <OK|WARN|FAIL>`** → `harness_context.py close --from-phase run --to-phase test --executor <tool> --json`（内部 phase.end + append-only handoff + 释放租约；任一 close 失败不得用自然语言宣称成功）
+4. **关门检查**（10 项）→ 只执行一次 **`harness_gate.py close --phase run --change <id> --status <OK|WARN|FAIL> --to-phase test --executor <tool> --json`**。该命令内部依次关闭 test guard、写 `phase.end`、释放阶段租约、写 append-only handoff，并立即补传远端事件；不得再单独调用 test-guard/context close。若返回 `PHASE_HANDOFF_PENDING`，修正明确指出的输入后原样重试同一命令，已完成步骤会幂等复用。
 
 **Fixback**：`--fixback` 或用户要求时读 `reports/review/fixback-*.md`；RED 优先；未选用则记 `fixback: advisory-not-applied`。
 
@@ -101,7 +101,7 @@ description: 按变更簇执行 TDD 编码循环（RED→GREEN→REFACTOR→编
 | **RED/GREEN** | RED 须有效；静态验证 ≠ 测试通过；greenfield 大重写豁免见 reference |
 | **Mapper/DB** | 纯 Mock 不得宣称 DB 验证通过；迁移脚本**永不自动执行** |
 | **探测/ledger** | 基础设施先探测；每次构建/测试经 `harness_ledger.py record`；禁止手写 ledger JSON；用 canonical `diff-hash --change-dir` |
-| **Gate/Guard** | 跨 Agent/阶段先用 `harness_context.py prepare/begin/close`；阶段门禁用 `harness_gate.py begin/close`；测试跟踪用 `harness_test_guard.py begin/close/record/stage` |
+| **Gate/Guard** | 跨 Agent/阶段先用 `harness_context.py prepare/begin`；阶段门禁与上下文交接统一用 `harness_gate.py begin/close`；gate 内部负责 guard begin/close，模型只在需要记录测试来源或修复时调用 guard 的 `record/stage/mark` |
 | **预存变更** | 保留 → baseline 隔离；存在则最终 ≥ 🟡WARN |
 | **关门/状态** | 10 项关门检查；持久化 run-task-status；P0 静态-only 不得建议 submit |
 | **Worktree** | `requested=true` 时代码只写 worktree |

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=790b0d238b58acd7; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=219ad7fdedbec84f; 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=790b0d238b58acd7; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=219ad7fdedbec84f; 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=790b0d238b58acd7; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=219ad7fdedbec84f; overlay=java; agent=codebuddy; do not edit -->
 # harness-test — 测试执行
 
 ## Purpose
@@ -46,7 +46,9 @@ description: 测试执行：读取场景表，执行单元测试+API接口测试
 
 ## Workflow
 
-测试跟踪的确定性边界为 `harness_test_guard.py begin` 和 `harness_test_guard.py close`；任一失败都必须传递给 `harness_gate.py close`，不得以自然语言覆盖失败状态。
+测试跟踪由 `harness_gate.py begin/close` 统一协调 test guard；不得额外手工执行 guard close。任一失败都必须使用 gate 返回的结构化状态，不得以自然语言覆盖失败状态。
+
+兼容实现中的底层命令名是 `harness_test_guard.py begin` 与 `harness_test_guard.py close`，两者只允许由 gate 内部调用；写在这里用于能力审计，不构成模型执行步骤。
 
 并行服务测试先运行 `harness_change.py lease-port --change <id> --run-id <run-id> --range <start-end> --json`，再把返回端口传给 `harness_service.py ensure --leased-port <port> --lease-owner <run-id>`。`serviceStart` 的 command/health/overlay 可用 `{leasedPort}` 占位符；用户自启进程仍只进入 Service Gate，禁止 kill。测试清理的 `finally` 中运行 `harness_change.py release-port --change <id> --run-id <run-id> --json`，避免租约池耗尽。
 
@@ -85,7 +87,7 @@ Runner 强制同项目单实例、低调度优先级、逐命令超时、正常
 
 先 `harness_context.py prepare --phase test --executor <tool> [--change <id>] --json`，再 `harness_context.py begin --phase test --change <id> --executor <tool> --json` 校验最新 run→test receipt 的 artifact/hash/HEAD；然后 **`harness_gate.py begin --phase test --change <id>`**（禁止手工 phase.start / 手写 ledger）。执行各项强制环境检查 + **命令执行模式 preflight (0.1)**；只有首选执行器不可用时，才执行 fallback 执行器探测。
 
-验证写入**仅**允许 `harness_ledger.py record` / `can-reuse`；禁止 Write/Edit `verification-ledger.json`。测试跟踪：`harness_test_guard.py begin` → 执行 → `close`（可选 `mark` stale-test-repair）。阶段结束必须 `harness_gate.py close --phase test --status ...`，随后 `harness_context.py close --from-phase test --to-phase review --executor <tool> --json`；fixback 时由 `harness_fixback.py` 合批记录 RED/GREEN 和 affected verification，再 `--to-phase run` 并由 context 失效受影响 target。
+验证写入**仅**允许 `harness_ledger.py record` / `can-reuse`；禁止 Write/Edit `verification-ledger.json`。测试跟踪：gate begin → 执行（可选 `harness_test_guard.py mark stale-test-repair`）→ 单次 `harness_gate.py close --phase test --status ... --to-phase review --executor <tool> --json`。fixback 时由 `harness_fixback.py` 合批记录 RED/GREEN 和 affected verification，再把同一 close 命令的 `--to-phase` 改为 `run`，由 context 失效受影响 target。
 
 - **Read `checklist.md`** — 各项检查详情 + 0.1 preflight + Playwright 探测 + 避坑规则指引
 - **失败处理**：任一项检查失败 → 终止流程并报告原因，用户确认修复后才能继续