@hunter-harness/workflow-harness 0.2.54 → 0.2.56

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
@@ -692,11 +693,12 @@ def validate_ledger_for_phase_close(
         try:
             current_repository = hp.repository_identity(root)
             current_ownership = hl.ownership_hash(contract)
-            current_diff = hl.compute_ownership_diff(
+            current_diff_detail = hl.compute_ownership_diff(
                 root,
                 base=str(ledger["baseCommit"]),
                 change_dir=change_dir,
-            )["diffHash"]
+            )
+            current_diff = current_diff_detail["diffHash"]
             current_head = _git_text(root, "rev-parse", "--verify", "HEAD")
         except (OSError, ValueError, RuntimeError) as exc:
             return {
@@ -726,6 +728,18 @@ def validate_ledger_for_phase_close(
                 "storedHead": ledger.get("currentHead"),
                 "currentHead": current_head,
                 "ledgerPath": str(ledger_path) if ledger_path else None,
+                "pathSummary": {
+                    "ownedFiles": list(current_diff_detail.get("files") or [])[:20],
+                    "foreignPaths": list(current_diff_detail.get("foreignPaths") or [])[:20],
+                    "ownedFileCount": current_diff_detail.get("ownedFileCount", 0),
+                    "excludedRuntimeCount": current_diff_detail.get(
+                        "excludedRuntimeCount", 0
+                    ),
+                },
+                "recoveryAction": (
+                    "先确认新增、删除或越界路径是否属于当前变更；更新所有权后，"
+                    "只重新执行受影响的验证，再原样重试 close。"
+                ),
             }
 
     problems: list[dict[str, Any]] = []
@@ -1602,6 +1616,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 +1645,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 +1687,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"),
@@ -1693,6 +1726,98 @@ def record_blocked_attempt(
     )
 
 
+def record_gate_blocked(
+    change_dir: Path,
+    *,
+    phase: str,
+    code: str,
+    message: str,
+    run_id: str | None = None,
+) -> dict[str, Any]:
+    """Persist a recoverable gate rejection without manufacturing a phase run."""
+    return append_phase_event(
+        change_dir,
+        phase=phase,
+        type_="gate.blocked",
+        status="BLOCKED",
+        note=message,
+        run_id=run_id or "blocked-" + uuid.uuid4().hex[:12],
+        code=code,
+    )
+
+
+def record_gate_recovered(
+    change_dir: Path,
+    *,
+    phase: str,
+    run_id: str,
+) -> dict[str, Any]:
+    """Close the latest unresolved gate.blocked record for this phase."""
+    blocked: dict[str, Any] | None = None
+    for event in reversed(he.load_events(he.events_path(change_dir))):
+        if event.get("phase") != phase:
+            continue
+        if event.get("type") == "gate.recovered":
+            break
+        if event.get("type") == "gate.blocked":
+            blocked = event
+            break
+    if blocked is None:
+        return {"ok": True, "skipped": True, "reason": "no-unresolved-block"}
+    return append_phase_event(
+        change_dir,
+        phase=phase,
+        type_="gate.recovered",
+        status="OK",
+        note="阶段交接已恢复，门禁现已成功启动。",
+        run_id=run_id,
+        code=str(blocked.get("code") or "GATE_BLOCKED"),
+    )
+
+
+def validate_context_for_gate_begin(
+    project: Path,
+    change_id: str,
+    phase: str,
+) -> dict[str, Any]:
+    """Require a completed Context handoff whenever modern Context state exists."""
+    view = hctx.context_view(project, change_id)
+    if not isinstance(view, dict) or not view.get("ok"):
+        return {"ok": True, "code": "CONTEXT_LEGACY_COMPATIBLE"}
+    current = view.get("current")
+    transitions = view.get("transitions")
+    begins = (view.get("attemptHistory") or {}).get("begins")
+    if not isinstance(current, dict):
+        return {"ok": True, "code": "CONTEXT_LEGACY_COMPATIBLE"}
+    current_phase = str(current.get("phase") or view.get("currentPhase") or "")
+    if current_phase != phase:
+        return {
+            "ok": False,
+            "code": "CONTEXT_HANDOFF_REQUIRED",
+            "message": "阶段交接尚未完成，门禁未启动；请先完成上下文交接。",
+            "expectedPhase": current_phase or None,
+            "requestedPhase": phase,
+        }
+    if isinstance(transitions, list) and transitions:
+        latest = transitions[-1] if isinstance(transitions[-1], dict) else {}
+        receipt_hash = latest.get("receiptHash")
+        begin_items = begins if isinstance(begins, list) else []
+        acknowledged = any(
+            isinstance(item, dict)
+            and item.get("phase") == phase
+            and item.get("receiptHash") == receipt_hash
+            for item in begin_items
+        )
+        if latest.get("toPhase") != phase or not acknowledged:
+            return {
+                "ok": False,
+                "code": "CONTEXT_BEGIN_REQUIRED",
+                "message": "阶段交接收据尚未确认，门禁未启动；请先执行上下文 begin。",
+                "requestedPhase": phase,
+            }
+    return {"ok": True, "code": "CONTEXT_READY"}
+
+
 def _phase_event_exists(change_dir: Path, phase: str, type_: str, run_id: str) -> bool:
     return any(
         event.get("phase") == phase
@@ -1702,6 +1827,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.
 
@@ -1971,6 +2170,32 @@ def cmd_begin(args: argparse.Namespace) -> int:
             extra={k: v for k, v in resolved.items() if k not in {"ok", "message"}},
         )
     change_dir = Path(resolved["changeDir"])
+    context_check = validate_context_for_gate_begin(
+        project, str(resolved["changeId"]), args.phase
+    )
+    if not context_check.get("ok"):
+        code = str(context_check.get("code") or "CONTEXT_HANDOFF_REQUIRED")
+        message = str(
+            context_check.get("message")
+            or "阶段交接尚未完成，门禁未启动。"
+        )
+        record_gate_blocked(
+            change_dir,
+            phase=args.phase,
+            code=code,
+            message=message,
+            run_id=args.run_id or os.environ.get("HUNTER_HARNESS_RUN_ID"),
+        )
+        return emit_error(
+            code,
+            message,
+            as_json=as_json,
+            extra={
+                key: value
+                for key, value in context_check.items()
+                if key not in {"ok", "code", "message"}
+            },
+        )
     severity_mode = gate_severity_mode(project, change_dir)
     gate_warnings: list[dict[str, Any]] = []
     plan_verification: dict[str, Any] | None = None
@@ -2142,6 +2367,16 @@ def cmd_begin(args: argparse.Namespace) -> int:
                             message="test guard begin failed (downgraded to WARN)",
                         ))
                     else:
+                        record_gate_blocked(
+                            change_dir,
+                            phase=args.phase,
+                            code=str(
+                                guard_result.get("code")
+                                or "TEST_GUARD_BEGIN_FAILED"
+                            ),
+                            message="测试保护快照建立失败，已停止阶段启动。",
+                            run_id=run_id,
+                        )
                         hc.release_lease(
                             project,
                             change_id=resolved["changeId"],
@@ -2158,6 +2393,11 @@ def cmd_begin(args: argparse.Namespace) -> int:
             current_head = _git_text(execution_root, "rev-parse", "--verify", "HEAD")
             ledger, _ = hl.load_ledger(change_dir)
             base_commit = ledger.get("baseCommit") if isinstance(ledger, dict) else None
+            try:
+                begin_contract = hp.load_change_contract(change_dir)
+                begin_ownership_hash = hl.ownership_hash(begin_contract)
+            except (OSError, ValueError, json.JSONDecodeError):
+                begin_ownership_hash = None
             capsule = {
                 "schemaVersion": 1,
                 "changeId": resolved["changeId"],
@@ -2170,6 +2410,7 @@ def cmd_begin(args: argparse.Namespace) -> int:
                 "repositoryId": hp.repository_identity(execution_root),
                 "baseCommit": base_commit or current_head,
                 "currentHead": current_head,
+                "ownershipHash": begin_ownership_hash,
                 "createdAt": he.now_iso(),
                 "projectionReceipt": projection,
             }
@@ -2187,6 +2428,11 @@ def cmd_begin(args: argparse.Namespace) -> int:
                 executor_agent=args.executor_agent or os.environ.get("HUNTER_HARNESS_AGENT"),
                 executor_model=args.executor_model or os.environ.get("HUNTER_HARNESS_MODEL"),
             )
+        recovery_result = record_gate_recovered(
+            change_dir,
+            phase=args.phase,
+            run_id=run_id,
+        )
     except BaseException:
         hc.release_lease(
             project, change_id=resolved["changeId"], phase=args.phase, run_id=run_id
@@ -2206,6 +2452,7 @@ def cmd_begin(args: argparse.Namespace) -> int:
         "lease": claim.get("lease"),
         "identity": identity,
         "event": event_result,
+        "gateRecovery": recovery_result,
         "testGuard": guard_result,
         "policySchemaVersion": policy.get("schemaVersion"),
         "planVerification": plan_verification,
@@ -2266,6 +2513,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:
@@ -2432,6 +2721,16 @@ def cmd_close(args: argparse.Namespace) -> int:
             status="LEDGER_VALIDATION_FAILED",
             error=ledger_result,
         )
+        record_gate_blocked(
+            change_dir,
+            phase=args.phase,
+            code=str(ledger_result.get("code") or "LEDGER_INVALID"),
+            message=(
+                "验证记录与当前变更身份不一致，已保留现场；"
+                "请按返回的路径摘要重新验证受影响范围。"
+            ),
+            run_id=run_id,
+        )
         return emit_error(
             str(ledger_result.get("code", "LEDGER_INVALID")),
             str(ledger_result.get("message", "ledger validation failed")),
@@ -2520,6 +2819,16 @@ def cmd_close(args: argparse.Namespace) -> int:
                             "updatedAt": he.now_iso(),
                         })
                         write_phase_capsule(change_dir, args.phase, run_id, capsule)
+                    record_gate_blocked(
+                        change_dir,
+                        phase=args.phase,
+                        code=str(
+                            guard_result.get("code")
+                            or "TEST_GUARD_CLOSE_FAILED"
+                        ),
+                        message="测试保护关门失败，已保留现场并等待同一命令恢复。",
+                        run_id=run_id,
+                    )
                     return emit_error(
                         str(guard_result.get("code", "TEST_GUARD_CLOSE_FAILED")),
                         "test guard close failed",
@@ -2597,6 +2906,41 @@ 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"):
+        record_gate_blocked(
+            change_dir,
+            phase=args.phase,
+            code=str(context_handoff.get("code") or "PHASE_HANDOFF_PENDING"),
+            message="阶段本地关门已完成，但上下文交接尚待恢复。",
+            run_id=run_id,
+        )
+        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,
+            },
+        )
+
+    recovery_result = record_gate_recovered(
+        change_dir,
+        phase=args.phase,
+        run_id=run_id,
+    )
     payload = {
         "ok": True,
         "code": close_code,
@@ -2612,6 +2956,9 @@ def cmd_close(args: argparse.Namespace) -> int:
         "lease": release,
         "gateSeverityMode": severity_mode,
         "gateWarnings": gate_warnings,
+        "contextHandoff": context_handoff,
+        "platformMonitor": platform_monitor,
+        "gateRecovery": recovery_result,
     }
     emit(payload, as_json=as_json)
     return 0
@@ -2806,6 +3153,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])