@hunter-harness/workflow-harness 0.2.85 → 0.3.0

package/harness/bundles/java/cursor/scripts/harness_context.py

@@ -21,27 +21,18 @@ if str(SCRIPTS_DIR) not in sys.path:
     sys.path.insert(0, str(SCRIPTS_DIR))
 
 import harness_ledger as hl  # noqa: E402
+import harness_paths as hpaths  # noqa: E402
 
 
 PHASE_GRAPH = {
-    "plan": ("run",),
-    "run": ("test",),
-    "test": ("review", "run"),
-    "review": ("submit", "run"),
+    "plan": ("execute",),
+    "execute": ("review", "execute"),
+    "review": ("submit", "execute"),
     "submit": (),
 }
 
-WORKFLOW_PHASES = (
-    "plan",
-    "run",
-    "test",
-    "review",
-    "package",
-    "apidoc",
-    "submit",
-    "merge",
-    "archive",
-)
+# 唯一权威清单在 harness_paths（叶子模块，harness_phase 引的是同一个对象）。
+WORKFLOW_PHASES = hpaths.WORKFLOW_PHASES
 
 DISPLAY_TITLE_MAX_LENGTH = 80
 
@@ -270,13 +261,26 @@ def _contract(project: Path, change: str) -> tuple[Path, dict[str, Any], Path]:
 
 
 def _phase_plan(contract_root: Path) -> tuple[list[str] | None, str]:
-    policy_path = contract_root / "meta" / "gate-policy.json"
-    if not policy_path.is_file():
-        return None, "legacy"
-    try:
-        policy = _read_json(policy_path)
-    except (OSError, ValueError, json.JSONDecodeError):
+    """读出阶段计划；无法采信时说明原因，而不是悄悄退成 legacy。
+
+    以前这里遇到未知阶段名一律返回 (None, "legacy")：阶段计划整个失效，
+    `_allowed_next_phases` 退回硬编码的 PHASE_GRAPH，而调用方看不出发生过这件事。
+    未知阶段名不是假想问题——阶段清单少一个 merge 时，worktree 变更的
+    plannedPhases 就会带着 merge 走到这里。
+
+    未知名先过 LEGACY_PHASE_ALIASES 读时映射（阶段改名后历史 change 靠它继续可读），
+    仍然解析不了才降级，并把原因与具体阶段名带在 source 里。
+
+    权威切换（2026-08）：v2 发布快照（plan-profile.json）优先，classify 工作
+    副本回退——发布后的阶段计划以已审批快照为准。
+    """
+    loaded = hpaths.load_change_gate_policy(contract_root)
+    policy = loaded.get("policy")
+    if policy is None:
+        if loaded.get("working_error"):
+            return None, "legacy:policy-unreadable"
         return None, "legacy"
+    unknown: list[str] = []
     for field, source in (
         ("plannedPhases", "change"),
         ("defaultPhases", "policy-default"),
@@ -285,25 +289,31 @@ def _phase_plan(contract_root: Path) -> tuple[list[str] | None, str]:
         if not isinstance(raw, list):
             continue
         phases = [str(item).strip() for item in raw if str(item).strip()]
-        if (
-            phases
-            and len(phases) == len(set(phases))
-            and all(item in WORKFLOW_PHASES for item in phases)
-        ):
-            return phases, source
+        if not phases or len(phases) != len(set(phases)):
+            continue
+        resolved = [hpaths.resolve_phase_name(item) for item in phases]
+        missing = [item for item, hit in zip(phases, resolved) if hit is None]
+        if missing:
+            unknown.extend(missing)
+            continue
+        # 映射后可能出现重复（两个旧名合并成同一个新阶段），保序去重。
+        return list(dict.fromkeys(str(item) for item in resolved)), source
+    if unknown:
+        return None, "legacy:unknown-phases=" + ",".join(dict.fromkeys(unknown))
     return None, "legacy"
 
 
 def _allowed_next_phases(contract_root: Path, from_phase: str) -> list[str]:
     planned, _source = _phase_plan(contract_root)
+    resolved_from = hpaths.resolve_phase_name(from_phase) or from_phase
     if planned is None:
-        return list(PHASE_GRAPH.get(from_phase, ()))
-    if from_phase not in planned:
+        return list(PHASE_GRAPH.get(resolved_from, ()))
+    if resolved_from not in planned:
         return []
-    index = planned.index(from_phase)
+    index = planned.index(resolved_from)
     allowed = planned[index + 1 : index + 2]
-    if from_phase in {"test", "review"} and "run" in planned:
-        allowed = [*allowed, "run"]
+    if resolved_from in {"execute", "review"} and "execute" in planned:
+        allowed = [*allowed, "execute"]
     return list(dict.fromkeys(allowed))
 
 
@@ -322,12 +332,14 @@ def configure_phase_plan(
     except (OSError, ValueError, json.JSONDecodeError) as exc:
         return {"ok": False, "code": _contract_error_code(exc), "error": str(exc)}
     normalized = [str(item).strip() for item in phases if str(item).strip()]
+    resolved = [hpaths.resolve_phase_name(item) for item in normalized]
     if (
         not normalized
         or len(normalized) != len(set(normalized))
-        or any(item not in WORKFLOW_PHASES for item in normalized)
-        or normalized[0] != "plan"
-        or normalized[-1] != "archive"
+        or any(item is None for item in resolved)
+        or len(set(resolved)) != len(resolved)
+        or resolved[0] != "plan"
+        or resolved[-1] != "archive"
     ):
         return {
             "ok": False,
@@ -340,6 +352,9 @@ def configure_phase_plan(
             "ok": False,
             "code": "PHASE_PLAN_JUSTIFICATION_REQUIRED",
         }
+    # 旧名入参（plan,run,test,review,archive）归一为现阶段名后落盘；
+    # 上面已校验 resolved 无 None 且保序唯一。
+    normalized = [str(item) for item in resolved]
     worktree_path = contract_root / "meta" / "worktree.json"
     if worktree_path.is_file():
         try:
@@ -405,6 +420,7 @@ def _paths(state_root: Path) -> dict[str, Path]:
         "begins": runtime / "transition-begins.ndjson",
         "current": runtime / "current-context.json",
         "lease": runtime / "context-lease.json",
+        "adoptions": runtime / "context-adoptions.ndjson",
     }
 
 
@@ -442,7 +458,7 @@ def _reselect_review_fixback(
     state_root: Path,
     executor: str,
 ) -> dict[str, Any]:
-    """Supersede an unbegun review→submit choice with review→run."""
+    """Supersede an unbegun review→submit choice with review→execute."""
 
     paths = _paths(state_root)
     with _exclusive_state_lock(paths["runtime"] / "branch-selection.lock"):
@@ -450,8 +466,8 @@ def _reselect_review_fixback(
         latest = transitions[-1] if transitions else None
         if (
             isinstance(latest, dict)
-            and latest.get("fromPhase") == "review"
-            and latest.get("toPhase") == "run"
+            and hpaths.resolve_phase_name(latest.get("fromPhase")) == "review"
+            and hpaths.resolve_phase_name(latest.get("toPhase")) == "execute"
             and latest.get("trigger") == "review-fixback"
         ):
             return {
@@ -503,14 +519,14 @@ def _reselect_review_fixback(
                 }
             paths["lease"].unlink(missing_ok=True)
         # Any submit context present here was only prepared, never begun.  The
-        # new run context is written by prepare_context after this atomic choice.
+        # new execute context is written by prepare_context after this atomic choice.
         paths["current"].unlink(missing_ok=True)
 
         receipt: dict[str, Any] = {
             "schemaVersion": 1,
             "changeName": change,
             "fromPhase": "review",
-            "toPhase": "run",
+            "toPhase": "execute",
             "status": "OK",
             "executor": executor,
             "productCommit": _head(project),
@@ -519,8 +535,8 @@ def _reselect_review_fixback(
             + sum(
                 1
                 for item in transitions
-                if item.get("fromPhase") == "review"
-                and item.get("toPhase") == "run"
+                if hpaths.resolve_phase_name(item.get("fromPhase")) == "review"
+                and hpaths.resolve_phase_name(item.get("toPhase")) == "execute"
             ),
             "closedAt": _now().isoformat(),
             "previousReceiptHash": latest.get("receiptHash"),
@@ -534,7 +550,7 @@ def _reselect_review_fixback(
             state_root,
             transition_hash=receipt["receiptHash"],
             from_phase="review",
-            to_phase="run",
+            to_phase="execute",
         )
         return {
             "ok": True,
@@ -604,13 +620,20 @@ def _claim_prepared_context(
             )
         except (OSError, ValueError, json.JSONDecodeError):
             return {"ok": False, "code": "CONTEXT_CURRENT_INVALID"}
+        # 跨阶段推进必须有 receipt 证明它合法；同一个阶段换执行者不需要。
+        # 以前两者都要 receipt，于是上一阶段崩溃没能正常 close 时，接手的工具
+        # 连"继续把这个阶段干完"都做不到。并发保护不受影响：租约未过期而
+        # owner 不同，上面 CONTEXT_LEASE_HELD 已经拦下了，能走到这里只剩
+        # 「租约已过期」和「租约已被上一阶段 close 删除」两种情况。
+        adoption: dict[str, Any] | None = None
         if recovery is None and isinstance(current, dict) and (
-            current.get("executor") != executor or current.get("phase") != phase
+            hpaths.resolve_phase_name(current.get("phase")) != phase
         ):
             valid_receipt = (
                 isinstance(latest, dict)
-                and latest.get("toPhase") == phase
-                and latest.get("fromPhase") == current.get("phase")
+                and hpaths.resolve_phase_name(latest.get("toPhase")) == phase
+                and hpaths.resolve_phase_name(latest.get("fromPhase"))
+                == hpaths.resolve_phase_name(current.get("phase"))
             )
             if not valid_receipt:
                 return {
@@ -621,6 +644,19 @@ def _claim_prepared_context(
                     "toExecutor": executor,
                     "toPhase": phase,
                 }
+        executor_changed = (
+            isinstance(current, dict) and current.get("executor") != executor
+        )
+        if recovery is not None or executor_changed:
+            adoption = {
+                "previousExecutor": (
+                    current.get("executor") if isinstance(current, dict) else None
+                ),
+                "newExecutor": executor,
+                "reason": (
+                    "lease_expired" if recovery is not None else "same_phase_handoff"
+                ),
+            }
 
         try:
             execution_root = _execution_root(project, contract_root, state_root)
@@ -657,6 +693,20 @@ def _claim_prepared_context(
             current_context["preparationId"] = preparation_id
         _write_json_atomic(paths["lease"], lease)
         _write_json_atomic(paths["current"], current_context)
+        if adoption is not None:
+            # 接管必须留痕。过期租约本来就允许任何执行者顶替，但以前只在返回体
+            # 里挂一个 recovery，退出进程就没了——事后查"这个阶段是谁接手的"
+            # 无据可依。收据形状照 harness_archive.adopt_existing_range。
+            adoption = {
+                "schemaVersion": 1,
+                "changeName": change,
+                "phase": phase,
+                **adoption,
+                "previousOwner": recovery.get("previousOwner") if recovery else None,
+                "expiredAt": recovery.get("expiredAt") if recovery else None,
+                "adoptedAt": now.isoformat(),
+            }
+            _append_ndjson(paths["adoptions"], adoption)
         return {
             "ok": True,
             "lease": lease,
@@ -664,10 +714,25 @@ def _claim_prepared_context(
             "transitions": transitions,
             "latestTransition": latest,
             "recovery": recovery,
+            "adoption": adoption,
             "executionRoot": str(execution_root),
         }
 
 
+def _unknown_phase_error(phase: Any) -> dict[str, Any]:
+    return {
+        "ok": False,
+        "code": "PHASE_UNKNOWN",
+        "phase": str(phase),
+        "allowedPhases": list(WORKFLOW_PHASES),
+        "legacyAliases": dict(hpaths.LEGACY_PHASE_ALIASES),
+        "message": (
+            f"未知阶段名 {phase!r}；合法阶段 {list(WORKFLOW_PHASES)}，"
+            f"旧名别名 {hpaths.LEGACY_PHASE_ALIASES}。"
+        ),
+    }
+
+
 def prepare_context(
     project: Path,
     *,
@@ -680,6 +745,10 @@ def prepare_context(
     preparation_id: str | None = None,
 ) -> dict[str, Any]:
     project = Path(project).resolve()
+    canonical_phase = hpaths.resolve_phase_name(phase)
+    if canonical_phase is None:
+        return _unknown_phase_error(phase)
+    phase = canonical_phase
     candidates = _active_changes(project)
     if change is None:
         if not candidates:
@@ -726,7 +795,7 @@ def prepare_context(
     paths = _paths(state_root)
     paths["runtime"].mkdir(parents=True, exist_ok=True)
     reselection: dict[str, Any] | None = None
-    if trigger == "review-fixback" and phase == "run":
+    if trigger == "review-fixback" and phase == "execute":
         reselection = _reselect_review_fixback(
             project,
             change,
@@ -768,9 +837,14 @@ def prepare_context(
         _allowed_next_phases(contract_root, phase)
         if planned_phases is not None
         else (
-            list(PHASE_GRAPH.get(str(latest.get("toPhase")), ()))
+            list(
+                PHASE_GRAPH.get(
+                    hpaths.resolve_phase_name(str(latest.get("toPhase"))) or "",
+                    (),
+                )
+            )
             if latest
-            else ["plan", "run"]
+            else ["plan", "execute"]
         )
     )
     return {
@@ -1014,7 +1088,7 @@ def _bootstrap_v2_plan_transition(
     """v2 发布已 committed 却没有交接凭证时，补录 plan → to_phase 凭证。
 
     v2 plan finalize 只写 plan-events.ndjson 与发布 journal，不碰 context 事务
-    存储，于是 run 阶段 prepare 必报 HANDOFF_REQUIRED、begin 必报
+    存储，于是 execute 阶段 prepare 必报 HANDOFF_REQUIRED、begin 必报
     LEGACY_BOOTSTRAP_REQUIRED——两个错误都不给恢复路径，调用方只能读脚本源码
     自己拼出 classify + configure-plan + close，参数全靠现编，可审计性更差。
 
@@ -1061,6 +1135,14 @@ def close_transition(
     status: str = "OK",
 ) -> dict[str, Any]:
     project = Path(project).resolve()
+    canonical_from = hpaths.resolve_phase_name(from_phase)
+    canonical_to = hpaths.resolve_phase_name(to_phase)
+    if canonical_from is None:
+        return _unknown_phase_error(from_phase)
+    if canonical_to is None:
+        return _unknown_phase_error(to_phase)
+    from_phase = canonical_from
+    to_phase = canonical_to
     try:
         contract_root, _contract_data, state_root = _contract(project, change)
     except (OSError, ValueError, json.JSONDecodeError) as exc:
@@ -1136,8 +1218,8 @@ def close_transition(
         latest = transitions[-1] if transitions else None
         if (
             isinstance(latest, dict)
-            and latest.get("fromPhase") == from_phase
-            and latest.get("toPhase") == to_phase
+            and hpaths.resolve_phase_name(latest.get("fromPhase")) == from_phase
+            and hpaths.resolve_phase_name(latest.get("toPhase")) == to_phase
             and latest.get("status") == status
             and latest.get("artifacts") == artifact_entries
             and (executor is None or latest.get("executor") == executor)
@@ -1158,7 +1240,9 @@ def close_transition(
     effective_executor = executor or str(lease.get("owner") or "")
     if not effective_executor:
         return {"ok": False, "code": "CONTEXT_EXECUTOR_REQUIRED"}
-    if lease.get("owner") != effective_executor or lease.get("phase") != from_phase:
+    if lease.get("owner") != effective_executor or (
+        hpaths.resolve_phase_name(lease.get("phase")) != from_phase
+    ):
         return {
             "ok": False,
             "code": "CONTEXT_LEASE_MISMATCH",
@@ -1177,8 +1261,8 @@ def close_transition(
         + sum(
             1
             for item in transitions
-            if item.get("fromPhase") == from_phase
-            and item.get("toPhase") == to_phase
+            if hpaths.resolve_phase_name(item.get("fromPhase")) == from_phase
+            and hpaths.resolve_phase_name(item.get("toPhase")) == to_phase
         )
     )
     receipt: dict[str, Any] = {
@@ -1204,7 +1288,7 @@ def close_transition(
     _append_ndjson(paths["transitions"], receipt)
     paths["lease"].unlink(missing_ok=True)
     invalidation = None
-    if to_phase == "run" and from_phase in {"test", "review"}:
+    if to_phase == "execute" and from_phase in {"execute", "review"}:
         invalidation = _invalidate_for_fixback(
             state_root,
             transition_hash=receipt["receiptHash"],
@@ -1283,7 +1367,7 @@ def _begin_transition_unlocked(
             ),
         }
     receipt = transitions[-1]
-    if receipt.get("toPhase") != phase:
+    if hpaths.resolve_phase_name(receipt.get("toPhase")) != phase:
         return {
             "ok": False,
             "code": "HANDOFF_REQUIRED",
@@ -1360,6 +1444,10 @@ def begin_transition(
     """Acknowledge a transition while serializing branch selection."""
 
     project = Path(project).resolve()
+    canonical_phase = hpaths.resolve_phase_name(phase)
+    if canonical_phase is None:
+        return _unknown_phase_error(phase)
+    phase = canonical_phase
     try:
         _contract_root, _contract_data, state_root = _contract(project, change)
     except (OSError, ValueError, json.JSONDecodeError) as exc:
@@ -1386,6 +1474,10 @@ def cancel_prepared_context(
     """Remove a target-phase preparation that never obtained its gate."""
 
     project = Path(project).resolve()
+    canonical_phase = hpaths.resolve_phase_name(phase)
+    if canonical_phase is None:
+        return _unknown_phase_error(phase)
+    phase = canonical_phase
     try:
         _contract_root, _contract_data, state_root = _contract(project, change)
     except (OSError, ValueError, json.JSONDecodeError) as exc:
@@ -1400,7 +1492,8 @@ def cancel_prepared_context(
             except (OSError, ValueError, json.JSONDecodeError):
                 current = None
             if isinstance(current, dict) and (
-                current.get("phase") == phase and current.get("executor") == executor
+                hpaths.resolve_phase_name(current.get("phase")) == phase
+                and current.get("executor") == executor
                 and (
                     preparation_id is None
                     or current.get("preparationId") == preparation_id
@@ -1415,7 +1508,8 @@ def cancel_prepared_context(
             except (OSError, ValueError, json.JSONDecodeError):
                 lease = None
             if isinstance(lease, dict) and (
-                lease.get("phase") == phase and lease.get("owner") == executor
+                hpaths.resolve_phase_name(lease.get("phase")) == phase
+                and lease.get("owner") == executor
                 and (
                     preparation_id is None
                     or lease.get("preparationId") == preparation_id
@@ -1429,7 +1523,7 @@ def cancel_prepared_context(
             for item in begins
             if not (
                 receipt_hash is not None
-                and item.get("phase") == phase
+                and hpaths.resolve_phase_name(item.get("phase")) == phase
                 and item.get("executor") == executor
                 and item.get("receiptHash") == receipt_hash
                 and (

package/harness/bundles/java/cursor/scripts/harness_events.py

@@ -2014,7 +2014,7 @@ def cmd_append(args: argparse.Namespace) -> int:
             "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.",
+            "plan rerun plan evidence-pack + plan finalize with the next attempt.",
             as_json=as_json,
             error_code="PHASE_ALREADY_CLOSED",
         )

package/harness/bundles/java/cursor/scripts/harness_events_sync.py

@@ -76,6 +76,7 @@ EVENT_SUMMARY_MAX_LENGTH = 500
 
 PHASE_LABELS = {
     "plan": "计划",
+    "execute": "执行",
     "run": "编码",
     "test": "测试",
     "review": "评审",

package/harness/bundles/java/cursor/scripts/harness_fixback.py

@@ -333,7 +333,7 @@ def open_review_batch(
     _write_json(_session_path(change_dir), session)
     he.append_event(
         change_dir,
-        phase="run",
+        phase="execute",
         type_="decision",
         note=f"已从评审结果创建修复批次，共 {len(issue_entries)} 个代码修复项。",
         run_id=run_id,
@@ -355,7 +355,7 @@ def _default_context_prepare(**kwargs: Any) -> dict[str, Any]:
 
     return hctx.prepare_context(
         kwargs["project"],
-        phase="run",
+        phase="execute",
         executor=kwargs["executor"],
         change=kwargs["change"],
         trigger="review-fixback",
@@ -369,7 +369,7 @@ def _default_context_begin(**kwargs: Any) -> dict[str, Any]:
     return hctx.begin_transition(
         kwargs["project"],
         kwargs["change"],
-        phase="run",
+        phase="execute",
         executor=kwargs["executor"],
         preparation_id=kwargs["preparation_id"],
     )
@@ -381,7 +381,7 @@ def _default_context_cancel(**kwargs: Any) -> dict[str, Any]:
     return hctx.cancel_prepared_context(
         kwargs["project"],
         kwargs["change"],
-        phase="run",
+        phase="execute",
         executor=kwargs["executor"],
         preparation_id=kwargs["preparation_id"],
     )
@@ -394,7 +394,7 @@ def _default_gate_begin(**kwargs: Any) -> dict[str, Any]:
         "begin",
         "--json",
         "--phase",
-        "run",
+        "execute",
         "--change",
         str(kwargs["change"]),
         "--project",
@@ -405,6 +405,10 @@ def _default_gate_begin(**kwargs: Any) -> dict[str, Any]:
         str(kwargs["run_id"]),
         "--note",
         "开始处理评审中确认需要修改的代码问题。",
+        # 显式标记这一轮是 review fixback。以前靠 gate 嗅探 note 里有没有
+        # "fixback" 字样——而上面这条 note 一个都没有，于是 fixback 的 run 事件
+        # 从来没被打上 trigger/from_phase。
+        "--fixback",
     ]
     for option, key in (
         ("--executor-tool", "executor_tool"),
@@ -483,7 +487,7 @@ def launch_review_fixback(
     started_at = time.monotonic()
     start_event = he.append_event(
         change_dir,
-        phase="run",
+        phase="execute",
         type_="phase.prepare.start",
         note="正在检查评审修复的前置条件。",
         run_id=effective_run_id,
@@ -518,7 +522,7 @@ def launch_review_fixback(
         message = str(result.get("message") or result.get("error") or "前置条件未满足，修复未启动。")
         he.append_event(
             change_dir,
-            phase="run",
+            phase="execute",
             type_="phase.prepare.end",
             status="BLOCKED",
             code=code,
@@ -537,7 +541,7 @@ def launch_review_fixback(
             "ok": False,
             "code": code,
             "message": message,
-            "recoveryAction": "处理提示的前置条件后重新执行 /harness-run --fixback",
+            "recoveryAction": "处理提示的前置条件后重新执行 /harness-execute --fixback",
             "preparationDurationMs": duration,
             "contextCancellation": cancellation,
         }
@@ -562,7 +566,7 @@ def launch_review_fixback(
     duration = max(0, round((time.monotonic() - started_at) * 1000))
     he.append_event(
         change_dir,
-        phase="run",
+        phase="execute",
         type_="phase.prepare.end",
         status="STARTED",
         message="前置条件已满足，修复编码已启动。",
@@ -661,7 +665,7 @@ def resume_batch(
     _write_json(session_path, session)
     he.append_event(
         change_dir,
-        phase="run",
+        phase="execute",
         type_="decision",
         note=(
             "已恢复现有修复批次，将从未完成步骤继续。"