@hunter-harness/workflow-harness 0.2.54 → 0.2.55

package/harness/bundles/general/claude-code/scripts/harness_events_sync.py

@@ -51,6 +51,15 @@ WHITELIST = {
     "duration_ms",
     "schemaVersion",
     "summary",
+    "executor_tool",
+    "executor_agent",
+    "executor_model",
+    "execution_mode",
+    "decision_reason_code",
+    "fallback_reason_code",
+    "trigger",
+    "from_phase",
+    "result_status",
 }
 
 MAX_BATCH_SIZE = 100
@@ -110,20 +119,43 @@ def _summary_text(value: Any) -> str:
     return text[:EVENT_SUMMARY_MAX_LENGTH].rstrip()
 
 
+_MACHINE_DETAIL_RE = re.compile(
+    r"(?:\s*[；;,，]?\s*)"
+    r"(?:artifactsHash|artifactHash|receiptHash|content_sha256|contentSha256)"
+    r"\s*[:=]\s*(?:sha256:)?[0-9a-f]{32,64}",
+    re.IGNORECASE,
+)
+
+
+def _readable_summary_text(value: Any) -> str:
+    text = _summary_text(value)
+    if not text:
+        return ""
+    text = _MACHINE_DETAIL_RE.sub("", text)
+    text = re.sub(
+        r"\bfinalize\s+ok\b",
+        "规划产物已校验并发布",
+        text,
+        flags=re.IGNORECASE,
+    )
+    text = re.sub(r"\s*([；;，,])\s*([；;，,])", r"\1", text)
+    return _summary_text(text.strip(" ；;，,"))
+
+
 def build_event_summary(event: dict[str, Any]) -> str:
-    explicit = _summary_text(event.get("summary"))
+    explicit = _readable_summary_text(event.get("summary"))
     if explicit:
         return explicit
 
     event_type = _summary_text(event.get("type"))
     phase = _summary_text(event.get("phase"))
     phase_label = PHASE_LABELS.get(phase, phase or "当前")
-    note = _summary_text(event.get("note"))
-    message = _summary_text(event.get("message"))
-    decision = _summary_text(event.get("decision"))
-    reason = _summary_text(event.get("reason"))
-    name = _summary_text(event.get("name"))
-    code = _summary_text(event.get("code"))
+    note = _readable_summary_text(event.get("note"))
+    message = _readable_summary_text(event.get("message"))
+    decision = _readable_summary_text(event.get("decision"))
+    reason = _readable_summary_text(event.get("reason"))
+    name = _readable_summary_text(event.get("name"))
+    code = _readable_summary_text(event.get("code"))
     status = _summary_text(event.get("status"))
 
     if event_type == "decision" and decision:
@@ -754,6 +786,39 @@ def _discover_changes(project_root: Path) -> list[Path]:
     return sorted(path for path in root.glob("*") if path.is_dir()) if root.is_dir() else []
 
 
+def _change_has_open_phase(change_dir: Path) -> bool:
+    """Project the append-only stream into open/closed phase state."""
+    try:
+        path = Path(harness_paths.resolve_state_dir_for_contract(change_dir)) / "events.ndjson"
+    except (OSError, ValueError):
+        return False
+    if not path.is_file():
+        return False
+    open_phases: dict[str, bool] = {}
+    try:
+        for line in path.read_text(encoding="utf-8-sig").splitlines():
+            if not line.strip():
+                continue
+            event = json.loads(line)
+            if not isinstance(event, dict):
+                continue
+            phase = event.get("phase")
+            event_type = event.get("type")
+            if not isinstance(phase, str) or not phase:
+                continue
+            if event_type == "phase.start":
+                open_phases[phase] = True
+            elif event_type in {"phase.end", "phase.auto_sealed", "workflow.end", "run.end"}:
+                open_phases[phase] = False
+    except (OSError, json.JSONDecodeError):
+        return False
+    return any(open_phases.values())
+
+
+def _project_has_open_phase(project_root: Path) -> bool:
+    return any(_change_has_open_phase(path) for path in _discover_changes(project_root))
+
+
 def _run_agent_session(project_root: Path) -> dict[str, Any]:
     attempts = 0
     uploaded = 0
@@ -766,14 +831,28 @@ def _run_agent_session(project_root: Path) -> dict[str, Any]:
         if all(item.get("ok") for item in results):
             time.sleep(0.6)
             if generation == _read_nudge_generation(project_root):
-                return {
-                    "ok": True,
-                    "uploaded": uploaded,
-                    "quarantined": quarantined,
-                    "attempts": attempts + 1,
-                }
+                if not _project_has_open_phase(project_root):
+                    return {
+                        "ok": True,
+                        "uploaded": uploaded,
+                        "quarantined": quarantined,
+                        "attempts": attempts + 1,
+                    }
+                # Keep a finite workflow lease alive while a phase is open.
+                # A phase.end nudge is observed on the next pass and releases
+                # the worker naturally; no terminal window is created.
+                time.sleep(10.0)
+                heartbeat_results = [
+                    sync_change(project_root, path, heartbeat_only=True)
+                    for path in _discover_changes(project_root)
+                ]
+                if all(item.get("ok") for item in heartbeat_results):
+                    attempts = 0
+                    continue
+                results = heartbeat_results
             attempts = 0
-            continue
+            if generation != _read_nudge_generation(project_root):
+                continue
         time.sleep(min(16.0, float(2 ** attempts)))
         attempts += 1
     return {

package/harness/bundles/general/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/general/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/general/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/general/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/general/codebuddy/.harness-build.json

@@ -2,5 +2,5 @@
   "schemaVersion": 1,
   "overlay": "none",
   "agent": "codebuddy",
-  "coreHash": "9f66b2de1ca64c6e"
+  "coreHash": "e9b3973b8ba91be9"
 }

package/harness/bundles/general/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=9f66b2de1ca64c6e; overlay=none; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=e9b3973b8ba91be9; overlay=none; agent=codebuddy; do not edit -->
 # harness-archive — 变更归档
 
 ## Purpose

package/harness/bundles/general/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=9f66b2de1ca64c6e; overlay=none; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=e9b3973b8ba91be9; overlay=none; agent=codebuddy; do not edit -->
 # harness-codebase-map — 代码库地图
 
 ## Purpose

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

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

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

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

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

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

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