@hunter-harness/workflow-harness 0.4.3 → 0.4.9

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

@@ -317,6 +317,24 @@ def _allowed_next_phases(contract_root: Path, from_phase: str) -> list[str]:
     return list(dict.fromkeys(allowed))
 
 
+def allowed_next_phases(project: Path, change: str, phase: str) -> list[str]:
+    """公开版后继查询：包装 _contract + _allowed_next_phases。
+
+    gate close 的幂等续跑（phase.end 已写但 handoff 未完成的中间态）需要在
+    没有 --to-phase 的情况下派生唯一计划后继；契约读取失败一律回退空表，
+    由调用方退到"后继不明确，请显式 --to-phase"的报错路径。
+    """
+    project = Path(project).resolve()
+    try:
+        contract_root, _contract_data, _state_root = _contract(project, change)
+    except (OSError, ValueError, json.JSONDecodeError):
+        return []
+    canonical = hpaths.resolve_phase_name(phase)
+    if canonical is None:
+        return []
+    return _allowed_next_phases(contract_root, canonical)
+
+
 def configure_phase_plan(
     project: Path,
     change: str,
@@ -450,6 +468,16 @@ def _execution_root(project: Path, contract_root: Path, state_root: Path) -> Pat
     return project.resolve()
 
 
+def _phase_has_ended(event_paths: list[Path], phase: str) -> bool:
+    """目标阶段是否已写入 phase.end（关门事实，与租约/交接状态无关）。"""
+    return any(
+        hpaths.resolve_phase_name(item.get("phase")) == phase
+        and item.get("type") == "phase.end"
+        for path in event_paths
+        for item in _read_ndjson(path)
+    )
+
+
 def _reselect_review_fixback(
     project: Path,
     change: str,
@@ -468,13 +496,75 @@ def _reselect_review_fixback(
             isinstance(latest, dict)
             and hpaths.resolve_phase_name(latest.get("fromPhase")) == "review"
             and hpaths.resolve_phase_name(latest.get("toPhase")) == "execute"
-            and latest.get("trigger") == "review-fixback"
         ):
+            # review→execute 已选定即为目标分支：trigger 只区分来源（close 时显式
+            # --to-phase execute 的也是同一份意图），不该把修复挡在门外
             return {
                 "ok": True,
                 "code": "FIXBACK_BRANCH_ALREADY_SELECTED",
                 "receipt": latest,
             }
+        event_paths = [state_root / "events.ndjson"]
+        if state_root != contract_root:
+            event_paths.append(contract_root / "events.ndjson")
+        review_ended = _phase_has_ended(event_paths, "review")
+        if (
+            isinstance(latest, dict)
+            and hpaths.resolve_phase_name(latest.get("fromPhase")) == "execute"
+            and hpaths.resolve_phase_name(latest.get("toPhase")) == "review"
+            and review_ended
+        ):
+            # review 已关门但从没写下后继分支（0.4.7 及之前 plain close 不带
+            # --to-phase 的静默断链产物）：此时分支选择还开着，fixback 是唯一
+            # 合法的推进——补写 review→execute 收据，与重选 submit 分支同构。
+            if paths["lease"].is_file():
+                try:
+                    lease = _read_json(paths["lease"])
+                except (OSError, ValueError, json.JSONDecodeError):
+                    return {"ok": False, "code": "CONTEXT_LEASE_INVALID"}
+                if lease.get("phase") != "review":
+                    return {
+                        "ok": False,
+                        "code": "FIXBACK_RESELECT_UNSAFE",
+                        "message": "当前上下文租约不属于已结束的评审阶段。",
+                    }
+                paths["lease"].unlink(missing_ok=True)
+            paths["current"].unlink(missing_ok=True)
+            receipt: dict[str, Any] = {
+                "schemaVersion": 1,
+                "changeName": change,
+                "fromPhase": "review",
+                "toPhase": "execute",
+                "status": "OK",
+                "executor": executor,
+                "productCommit": _head(project),
+                "artifacts": [],
+                "attempt": 1
+                + sum(
+                    1
+                    for item in transitions
+                    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"),
+                "trigger": "review-fixback",
+                "selectionReason": "用户选择处理评审中的代码修复项",
+            }
+            receipt["receiptHash"] = _payload_hash(receipt)
+            _append_ndjson(paths["transitions"], receipt)
+            invalidation = _invalidate_for_fixback(
+                state_root,
+                transition_hash=receipt["receiptHash"],
+                from_phase="review",
+                to_phase="execute",
+            )
+            return {
+                "ok": True,
+                "code": "FIXBACK_BRANCH_RESELECTED",
+                "receipt": receipt,
+                "invalidation": invalidation,
+            }
         if not (
             isinstance(latest, dict)
             and latest.get("fromPhase") == "review"
@@ -484,6 +574,23 @@ def _reselect_review_fixback(
                 "ok": False,
                 "code": "FIXBACK_RESELECT_UNAVAILABLE",
                 "message": "当前没有可安全重选的评审后继分支。",
+                "latestTransition": (
+                    {
+                        "fromPhase": latest.get("fromPhase"),
+                        "toPhase": latest.get("toPhase"),
+                        "trigger": latest.get("trigger"),
+                    }
+                    if isinstance(latest, dict)
+                    else None
+                ),
+                "reviewPhaseEnded": review_ended,
+                "recoveryAction": (
+                    "修复分支要求评审已关门。若 review 尚未关门：先 "
+                    "harness_gate.py close --phase review --status <OK|WARN> "
+                    "（0.4.5+ 可省略 --to-phase，唯一后继自动交接；要进修复则显式 "
+                    "--to-phase execute），再重跑 /harness-execute --fixback。"
+                    "若 submit 已关门，修复窗口已过，请走新一轮评审流程。"
+                ),
             }
         begins = _read_ndjson(paths["begins"])
         submit_begun = any(
@@ -492,9 +599,6 @@ def _reselect_review_fixback(
             and item.get("receiptHash") == latest.get("receiptHash")
             for item in begins
         )
-        event_paths = [state_root / "events.ndjson"]
-        if state_root != contract_root:
-            event_paths.append(contract_root / "events.ndjson")
         submit_started = any(
             item.get("phase") == "submit" and item.get("type") == "phase.start"
             for path in event_paths
@@ -909,13 +1013,19 @@ def bootstrap_plan(
     import harness_state as hs
 
     project = Path(project).resolve()
-    changes_root = project / ".harness" / "changes"
+    harness_root = project / ".harness"
+    changes_root = harness_root / "changes"
     if not changes_root.is_dir():
-        return {
-            "ok": False,
-            "code": "PROJECT_ROOT_INVALID",
-            "error": f"{changes_root} 不存在——先在该项目运行 hunter-harness init",
-        }
+        if harness_root.is_dir():
+            # 项目已 init 但从未建过 change——changes/ 目录此前没有任何脚本负责创建，
+            # 不该把用户误导去重跑 init（init 是空白项目用的）
+            changes_root.mkdir(parents=True, exist_ok=True)
+        else:
+            return {
+                "ok": False,
+                "code": "PROJECT_ROOT_INVALID",
+                "error": f"{harness_root} 不存在——该项目尚未初始化，先运行 hunter-harness init",
+            }
 
     # 新 change 的目录此前没有任何脚本负责创建，靠的是后续 Write 的副作用；
     # 引导阶段显式建立骨架，prepare 才有 contract 可读
@@ -1433,6 +1543,134 @@ def _begin_transition_unlocked(
     }
 
 
+def handoff_transition(
+    project: Path,
+    change: str,
+    *,
+    to_phase: str,
+    executor: str,
+    from_phase: str | None = None,
+    status: str = "OK",
+) -> dict[str, Any]:
+    """一条命令补齐缺失的阶段交接：补租约 → close → begin 确认。
+
+    0.4.7 及之前的 plain gate close 不写交接，后继阶段 begin 撞
+    CONTEXT_HANDOFF_REQUIRED 后，使用者要在 context close（缺租约报错）→
+    change claim → context prepare → context close → context begin →
+    change release 之间试错（2026-08-30 sales-insight-agent submit 实测，
+    六条命令）。本命令把合法恢复收敛为一步：来源阶段必须已关门
+    （phase.end 落盘），缺失的 context 租约由 prepare 幂等重建，
+    交接收据与 begin 确认走与正常流程完全相同的状态机。阶段租约
+    （harness_change）在 gate close 时已释放，无需也不应重新 claim。
+    """
+    project = Path(project).resolve()
+    canonical_to = hpaths.resolve_phase_name(to_phase)
+    if canonical_to is None:
+        return _unknown_phase_error(to_phase)
+    to_phase = canonical_to
+    try:
+        contract_root, _contract_data, state_root = _contract(project, change)
+    except (OSError, ValueError, json.JSONDecodeError) as exc:
+        return {"ok": False, "code": _contract_error_code(exc), "error": str(exc)}
+    paths = _paths(state_root)
+    transitions = _read_ndjson(paths["transitions"])
+    latest = transitions[-1] if transitions else None
+
+    if from_phase is None:
+        if (
+            isinstance(latest, dict)
+            and hpaths.resolve_phase_name(latest.get("toPhase")) == to_phase
+        ):
+            # 交接已写、只剩 begin 确认的半成品状态：来源从收据取
+            from_phase = str(latest.get("fromPhase") or "")
+        else:
+            view = context_view(project, change)
+            current = (
+                view.get("current") if isinstance(view.get("current"), dict) else {}
+            )
+            from_phase = str(current.get("phase") or "").strip()
+    canonical_from = hpaths.resolve_phase_name(from_phase or "")
+    if canonical_from is None:
+        return {
+            "ok": False,
+            "code": "HANDOFF_SOURCE_UNKNOWN",
+            "message": "无法确定交接来源阶段；请显式传 --from-phase。",
+            "toPhase": to_phase,
+        }
+    from_phase = canonical_from
+
+    closed: dict[str, Any]
+    if (
+        isinstance(latest, dict)
+        and hpaths.resolve_phase_name(latest.get("fromPhase")) == from_phase
+        and hpaths.resolve_phase_name(latest.get("toPhase")) == to_phase
+    ):
+        # 收据已存在——重放 close 只会写重复 receipt，直接进入 begin 确认
+        closed = {
+            "ok": True,
+            "code": "TRANSITION_ALREADY_CLOSED",
+            "idempotent": True,
+            "receipt": latest,
+        }
+    else:
+        event_paths = [state_root / "events.ndjson"]
+        if state_root != contract_root:
+            event_paths.append(contract_root / "events.ndjson")
+        if not _phase_has_ended(event_paths, from_phase):
+            return {
+                "ok": False,
+                "code": "HANDOFF_SOURCE_NOT_CLOSED",
+                "message": (
+                    f"{from_phase} 阶段尚未关门（无 phase.end）；handoff 只补齐"
+                    "已关门阶段的交接，不能截胡进行中的阶段。"
+                ),
+                "fromPhase": from_phase,
+                "toPhase": to_phase,
+                "recoveryAction": (
+                    f"先完成来源阶段关门：harness_gate.py close --phase {from_phase} "
+                    f"--change {change} --status <OK|WARN> --json"
+                    "（0.4.6+ 缺省 --to-phase 时自动派生交接），再重跑本命令。"
+                ),
+            }
+        # 缺失/过期的 context 租约由 prepare 幂等重建；被他人持有则原样报错
+        prepared = prepare_context(
+            project,
+            change=change,
+            phase=from_phase,
+            executor=executor,
+        )
+        if not prepared.get("ok"):
+            return prepared
+        closed = close_transition(
+            project,
+            change,
+            from_phase=from_phase,
+            to_phase=to_phase,
+            executor=executor,
+            status=status,
+        )
+        if not closed.get("ok"):
+            return closed
+    begun = begin_transition(project, change, phase=to_phase, executor=executor)
+    if not begun.get("ok"):
+        return {
+            "ok": False,
+            "code": "HANDOFF_BEGIN_FAILED",
+            "message": "交接收据已写入，但 begin 确认失败。",
+            "transition": closed,
+            "begin": begun,
+        }
+    return {
+        "ok": True,
+        "code": "HANDOFF_COMPLETED",
+        "changeName": change,
+        "fromPhase": from_phase,
+        "toPhase": to_phase,
+        "transition": closed,
+        "begin": begun,
+    }
+
+
 def begin_transition(
     project: Path,
     change: str,
@@ -1689,6 +1927,20 @@ def build_parser() -> argparse.ArgumentParser:
     begin.add_argument("--change", required=True)
     begin.add_argument("--phase", required=True)
     begin.add_argument("--executor", required=True)
+    handoff = sub.add_parser(
+        "handoff",
+        help="一条命令补齐缺失的阶段交接：补租约 → close → begin 确认",
+    )
+    handoff.add_argument("--json", action="store_true")
+    handoff.add_argument("--project", required=True, type=Path)
+    handoff.add_argument("--change", required=True)
+    handoff.add_argument("--to-phase", required=True)
+    handoff.add_argument(
+        "--from-phase",
+        help="缺省从当前上下文/最新交接收据推断",
+    )
+    handoff.add_argument("--executor", required=True)
+    handoff.add_argument("--status", default="OK")
     renew = sub.add_parser(
         "renew", help="extend the current phase lease without touching context"
     )
@@ -1749,6 +2001,15 @@ def main(argv: list[str] | None = None) -> int:
             phase=args.phase,
             executor=args.executor,
         )
+    elif args.command == "handoff":
+        result = handoff_transition(
+            args.project,
+            args.change,
+            to_phase=args.to_phase,
+            from_phase=args.from_phase,
+            executor=args.executor,
+            status=args.status,
+        )
     elif args.command == "renew":
         result = renew_lease(
             args.project,

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

@@ -479,10 +479,10 @@ def copy_overlay_extras(overlay_dir: Path, out_dir: Path) -> list[str]:
     # it must NOT be installed to runtime. Only pitfalls-java.md is runtime.
     pitfalls = overlay_dir / "pitfalls-java.md"
     if pitfalls.is_file():
-        test_pit = out_dir / "harness-test" / "pitfalls-java.md"
+        test_pit = out_dir / "harness-execute" / "testing-pitfalls-java.md"
         test_pit.parent.mkdir(parents=True, exist_ok=True)
         shutil.copy2(pitfalls, test_pit)
-        extras.append("harness-test/pitfalls-java.md")
+        extras.append("harness-execute/testing-pitfalls-java.md")
     return extras
 
 

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

@@ -927,7 +927,10 @@ def validate_append_event(args: argparse.Namespace) -> tuple[str, str] | None:
         if re.search(r"\bREVIEW_[A-Z0-9_]+\b", body):
             return (
                 "EVENT_REVIEW_REASON_IN_BODY",
-                "EVENT_REVIEW_REASON_IN_BODY: 评审原因码只能写入结构化字段，正文请使用中文说明",
+                "EVENT_REVIEW_REASON_IN_BODY: 评审原因码只能写入结构化字段"
+                "（--execution-mode delegated|inline，配合 --decision-reason-code "
+                "REVIEW_DELEGATED 或 --fallback-reason-code REVIEW_INLINE_*），"
+                "正文请使用中文说明",
             )
         execution_mode = str(getattr(args, "execution_mode", "") or "").strip()
         decision_code = str(