@hunter-harness/workflow-harness 0.2.55 → 0.2.56

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

@@ -23,6 +23,18 @@ PHASE_GRAPH = {
     "submit": (),
 }
 
+WORKFLOW_PHASES = (
+    "plan",
+    "run",
+    "test",
+    "review",
+    "package",
+    "apidoc",
+    "submit",
+    "merge",
+    "archive",
+)
+
 DISPLAY_TITLE_MAX_LENGTH = 80
 
 
@@ -206,6 +218,107 @@ def _contract(project: Path, change: str) -> tuple[Path, dict[str, Any], Path]:
     return contract_root, contract, state_root
 
 
+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):
+        return None, "legacy"
+    for field, source in (
+        ("plannedPhases", "change"),
+        ("defaultPhases", "policy-default"),
+    ):
+        raw = policy.get(field)
+        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
+    return None, "legacy"
+
+
+def _allowed_next_phases(contract_root: Path, from_phase: str) -> list[str]:
+    planned, _source = _phase_plan(contract_root)
+    if planned is None:
+        return list(PHASE_GRAPH.get(from_phase, ()))
+    if from_phase not in planned:
+        return []
+    index = planned.index(from_phase)
+    allowed = planned[index + 1 : index + 2]
+    if from_phase in {"test", "review"} and "run" in planned:
+        allowed = [*allowed, "run"]
+    return list(dict.fromkeys(allowed))
+
+
+def configure_phase_plan(
+    project: Path,
+    change: str,
+    *,
+    phases: list[str],
+    operator: str,
+    reason: str,
+) -> dict[str, Any]:
+    """Persist the single phase plan consumed by Context, Archive and Platform."""
+    project = Path(project).resolve()
+    try:
+        contract_root, _contract_data, _state_root = _contract(project, change)
+    except (OSError, ValueError, json.JSONDecodeError) as exc:
+        return {"ok": False, "code": "CHANGE_NOT_FOUND", "error": str(exc)}
+    normalized = [str(item).strip() for item in phases if str(item).strip()]
+    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"
+    ):
+        return {
+            "ok": False,
+            "code": "PHASE_PLAN_INVALID",
+            "message": "phase plan must be unique, start with plan, and end with archive",
+            "allowedPhases": list(WORKFLOW_PHASES),
+        }
+    if not operator.strip() or not reason.strip():
+        return {
+            "ok": False,
+            "code": "PHASE_PLAN_JUSTIFICATION_REQUIRED",
+        }
+    policy_path = contract_root / "meta" / "gate-policy.json"
+    policy = _read_json(policy_path) if policy_path.is_file() else {"schemaVersion": 1}
+    skipped = [
+        {
+            "phase": phase,
+            "reason": reason.strip(),
+            "operator": operator.strip(),
+            "decidedAt": _now().isoformat(),
+        }
+        for phase in WORKFLOW_PHASES
+        if phase not in normalized and phase != "merge"
+    ]
+    policy["plannedPhases"] = normalized
+    policy["skippedPhases"] = skipped
+    policy["phasePlan"] = {
+        "source": "change-override",
+        "operator": operator.strip(),
+        "reason": reason.strip(),
+        "updatedAt": _now().isoformat(),
+    }
+    _write_json_atomic(policy_path, policy)
+    return {
+        "ok": True,
+        "code": "PHASE_PLAN_CONFIGURED",
+        "plannedPhases": normalized,
+        "skippedPhases": skipped,
+        "path": str(policy_path),
+    }
+
+
 def _active_changes(project: Path) -> list[str]:
     root = project.resolve() / ".harness" / "changes"
     if not root.is_dir():
@@ -319,6 +432,14 @@ def prepare_context(
         and lifecycle.get("status") not in {None, "active"}
     ):
         return {"ok": False, "code": "CHANGE_NOT_ACTIVE", "changeName": change}
+    planned_phases, phase_plan_source = _phase_plan(contract_root)
+    if planned_phases is not None and phase not in planned_phases:
+        return {
+            "ok": False,
+            "code": "PHASE_NOT_PLANNED",
+            "phase": phase,
+            "plannedPhases": planned_phases,
+        }
     paths = _paths(state_root)
     paths["runtime"].mkdir(parents=True, exist_ok=True)
     recovery: dict[str, Any] | None = None
@@ -395,9 +516,13 @@ def prepare_context(
         },
     )
     next_phases = (
-        list(PHASE_GRAPH.get(str(latest.get("toPhase")), ()))
-        if latest
-        else ["plan", "run"]
+        _allowed_next_phases(contract_root, phase)
+        if planned_phases is not None
+        else (
+            list(PHASE_GRAPH.get(str(latest.get("toPhase")), ()))
+            if latest
+            else ["plan", "run"]
+        )
     )
     return {
         "ok": True,
@@ -408,6 +533,8 @@ def prepare_context(
         "contractRoot": str(contract_root),
         "stateRoot": str(state_root),
         "nextPhases": next_phases,
+        "plannedPhases": planned_phases,
+        "phasePlanSource": phase_plan_source,
         "legacyBootstrap": not transitions,
         "latestTransition": latest,
         "lease": lease,
@@ -423,42 +550,19 @@ def _invalidate_for_fixback(
     from_phase: str,
     to_phase: str,
 ) -> dict[str, Any]:
-    ledger_path = state_root / "evidence" / "verification-ledger.json"
-    invalidated: list[str] = []
-    if ledger_path.is_file():
-        try:
-            ledger = _read_json(ledger_path)
-        except (OSError, ValueError, json.JSONDecodeError):
-            ledger = {}
-        targets = ledger.get("verificationTargets")
-        if isinstance(targets, dict):
-            for target_id, target in targets.items():
-                if not isinstance(target, dict):
-                    continue
-                target["reusable"] = False
-                target["invalidation"] = {
-                    "code": "FIXBACK_INVALIDATED",
-                    "transitionHash": transition_hash,
-                    "fromPhase": from_phase,
-                    "toPhase": to_phase,
-                    "invalidatedAt": _now().isoformat(),
-                }
-                invalidated.append(str(target_id))
-        validations = ledger.get("validations")
-        if isinstance(validations, dict):
-            for entry in validations.values():
-                if isinstance(entry, dict):
-                    entry["reusable"] = False
-                    entry["invalidation"] = {
-                        "code": "FIXBACK_INVALIDATED",
-                        "transitionHash": transition_hash,
-                    }
-        _write_json_atomic(ledger_path, ledger)
+    # A review→run handoff happens before product files are changed. Invalidating
+    # every target here made unrelated API/build evidence unusable. The Fixback
+    # resolver now invalidates only entries whose inputsFiles intersect the
+    # issue's actual changedFiles.
     record = {
         "schemaVersion": 1,
-        "code": "FIXBACK_INVALIDATED",
+        "code": "FIXBACK_INVALIDATION_DEFERRED",
         "transitionHash": transition_hash,
-        "targetIds": invalidated,
+        "fromPhase": from_phase,
+        "toPhase": to_phase,
+        "targetIds": [],
+        "deferred": True,
+        "reason": "changed-files-not-known",
         "createdAt": _now().isoformat(),
     }
     _append_ndjson(
@@ -479,17 +583,22 @@ def close_transition(
     status: str = "OK",
 ) -> dict[str, Any]:
     project = Path(project).resolve()
-    if to_phase not in PHASE_GRAPH.get(from_phase, ()):
+    try:
+        contract_root, _contract_data, state_root = _contract(project, change)
+    except (OSError, ValueError, json.JSONDecodeError) as exc:
+        return {"ok": False, "code": "CHANGE_NOT_FOUND", "error": str(exc)}
+    allowed_next = _allowed_next_phases(contract_root, from_phase)
+    if to_phase not in allowed_next:
+        planned_phases, source = _phase_plan(contract_root)
         return {
             "ok": False,
             "code": "TRANSITION_ILLEGAL",
             "fromPhase": from_phase,
             "toPhase": to_phase,
+            "allowedNextPhases": allowed_next,
+            "plannedPhases": planned_phases,
+            "phasePlanSource": source,
         }
-    try:
-        contract_root, _contract_data, state_root = _contract(project, change)
-    except (OSError, ValueError, json.JSONDecodeError) as exc:
-        return {"ok": False, "code": "CHANGE_NOT_FOUND", "error": str(exc)}
     paths = _paths(state_root)
 
     artifact_entries: list[dict[str, Any]] = []
@@ -773,6 +882,13 @@ def build_parser() -> argparse.ArgumentParser:
     begin.add_argument("--change", required=True)
     begin.add_argument("--phase", required=True)
     begin.add_argument("--executor", required=True)
+    configure = sub.add_parser("configure-plan")
+    configure.add_argument("--json", action="store_true")
+    configure.add_argument("--project", required=True, type=Path)
+    configure.add_argument("--change", required=True)
+    configure.add_argument("--phases", required=True)
+    configure.add_argument("--operator", required=True)
+    configure.add_argument("--reason", required=True)
     view = sub.add_parser("view")
     view.add_argument("--json", action="store_true")
     view.add_argument("--project", required=True, type=Path)
@@ -808,6 +924,14 @@ def main(argv: list[str] | None = None) -> int:
             phase=args.phase,
             executor=args.executor,
         )
+    elif args.command == "configure-plan":
+        result = configure_phase_plan(
+            args.project,
+            args.change,
+            phases=[item.strip() for item in args.phases.split(",") if item.strip()],
+            operator=args.operator,
+            reason=args.reason,
+        )
     else:
         result = context_view(args.project, args.change)
     print(json.dumps(result, ensure_ascii=False, indent=2))

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

@@ -71,6 +71,8 @@ EVENT_TYPES = frozenset(
         "phase.start",
         "phase.end",
         "phase.auto_sealed",
+        "gate.blocked",
+        "gate.recovered",
         "command",
         "verification",
         "artifact",
@@ -165,6 +167,10 @@ _EVENT_ALLOWED_FIELDS = {
     )
     | _PROVENANCE_FIELDS,
     "phase.auto_sealed": frozenset({"status", "reason", "note"}) | _PROVENANCE_FIELDS,
+    "gate.blocked": frozenset({"status", "code", "reason", "note"})
+    | _PROVENANCE_FIELDS,
+    "gate.recovered": frozenset({"status", "code", "reason", "note"})
+    | _PROVENANCE_FIELDS,
     "command": frozenset({"command", "exit_code", "duration_ms", "note"})
     | _PROVENANCE_FIELDS,
     "verification": frozenset(
@@ -1798,18 +1804,45 @@ def cmd_append(args: argparse.Namespace) -> int:
             "warning: verification missing --name or --status",
             file=sys.stderr,
         )
-    line = json.dumps(event, ensure_ascii=False, separators=(",", ":"))
     phase_closed = False
     projection_error: str | None = None
+    attempt_error: str | None = None
     auto_sealed_events: list[dict[str, Any]] = []
     try:
         with event_file_lock(lock_path):
             existing_events = (
                 load_events(path)
                 if args.type in {"phase.end", "correction", "phase.start"}
+                or event.get("run_id") is not None
+                or event.get("attempt") is not None
                 else []
             )
-            if args.type == "phase.end":
+            run_id = event.get("run_id")
+            if run_id is not None:
+                run_attempts = {
+                    int(item["attempt"])
+                    for item in existing_events
+                    if item.get("phase") == event.get("phase")
+                    and item.get("run_id") == run_id
+                    and isinstance(item.get("attempt"), int)
+                    and int(item["attempt"]) > 0
+                }
+                if run_attempts:
+                    expected_attempt = max(run_attempts)
+                    explicit_attempt = event.get("attempt")
+                    if (
+                        isinstance(explicit_attempt, int)
+                        and explicit_attempt != expected_attempt
+                    ):
+                        attempt_error = (
+                            "EVENT_ATTEMPT_CONFLICT: run_id is already bound to "
+                            f"attempt {expected_attempt}, received {explicit_attempt}"
+                        )
+                    else:
+                        event["attempt"] = expected_attempt
+            if attempt_error is not None:
+                pass
+            elif args.type == "phase.end":
                 phase_closed = phase_end_already_recorded(existing_events, event)
             elif args.type == "correction":
                 try:
@@ -1830,13 +1863,16 @@ def cmd_append(args: argparse.Namespace) -> int:
                         phase=args.phase,
                         seal_reason=inferred_reason,
                     )
-            if not phase_closed and projection_error is None:
+            if not phase_closed and projection_error is None and attempt_error is None:
                 for seal_event in auto_sealed_events:
                     atomic_append_line(
                         path,
                         json.dumps(seal_event, ensure_ascii=False, separators=(",", ":")),
                     )
-                atomic_append_line(path, line)
+                atomic_append_line(
+                    path,
+                    json.dumps(event, ensure_ascii=False, separators=(",", ":")),
+                )
     except (OSError, TimeoutError, ValueError) as exc:
         return emit_error(f"append failed: {exc}", as_json=as_json)
     if phase_closed:
@@ -1852,6 +1888,12 @@ def cmd_append(args: argparse.Namespace) -> int:
             as_json=as_json,
             error_code=error_code,
         )
+    if attempt_error is not None:
+        return emit_error(
+            attempt_error,
+            as_json=as_json,
+            error_code="EVENT_ATTEMPT_CONFLICT",
+        )
 
     _nudge_remote_sync(change_dir)
 

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

@@ -60,6 +60,12 @@ WHITELIST = {
     "trigger",
     "from_phase",
     "result_status",
+    "planned_phases",
+    "skipped_phases",
+    "next_phase",
+    "phase_plan_source",
+    "closure_disposition",
+    "closure_reason",
 }
 
 MAX_BATCH_SIZE = 100
@@ -79,6 +85,14 @@ PHASE_LABELS = {
     "archive": "归档",
 }
 
+REVIEW_REASON_SUMMARIES = {
+    "REVIEW_DELEGATED": "已使用独立评审，主会话负责核验结果。",
+    "REVIEW_INLINE_UNAVAILABLE": "当前环境没有可用的隔离评审能力，已由主会话完成评审。",
+    "REVIEW_INLINE_SPAWN_FAILED": "独立评审启动失败，已由主会话完成评审。",
+    "REVIEW_INLINE_INVALID_RESULT": "独立评审未返回有效结果，已由主会话重新完成评审。",
+    "INLINE_BY_ADAPTER": "当前适配器未提供隔离评审，已由主会话完成评审。",
+}
+
 
 def _yaml_scalar(text: str, key: str) -> str | None:
     match = re.search(rf"(?m)^[ \t]*{re.escape(key)}:\s*['\"]?([^'\"\n#]+)", text)
@@ -143,8 +157,21 @@ def _readable_summary_text(value: Any) -> str:
 
 
 def build_event_summary(event: dict[str, Any]) -> str:
+    reason_code = _summary_text(
+        event.get("fallback_reason_code") or event.get("decision_reason_code")
+    )
+    reason_summary = REVIEW_REASON_SUMMARIES.get(reason_code)
     explicit = _readable_summary_text(event.get("summary"))
-    if explicit:
+    if reason_summary and (
+        not explicit
+        or explicit == reason_code
+        or re.search(r"REVIEW_[A-Z0-9_]+|INLINE_BY_ADAPTER", explicit)
+    ):
+        return reason_summary
+    if explicit and not re.search(
+        r"\b[A-Z][A-Z0-9_]{3,}\b|\b[a-z][\w.-]+\s*=\s*(?:true|false)\b",
+        explicit,
+    ):
         return explicit
 
     event_type = _summary_text(event.get("type"))
@@ -177,6 +204,10 @@ def build_event_summary(event: dict[str, Any]) -> str:
         return _summary_text(
             f"{phase_label}阶段已结束：{detail}" if detail else f"{phase_label}阶段已结束。"
         )
+    if event_type == "gate.blocked":
+        return note or message or "阶段门禁暂未通过，现场已保留，可按提示恢复。"
+    if event_type == "gate.recovered":
+        return note or message or "阶段门禁已恢复，流程可以继续。"
     if event_type == "command":
         detail = name or note
         return _summary_text(f"执行步骤：{detail}" if detail else "执行了一项工作步骤。")
@@ -205,6 +236,48 @@ def sanitize(event: dict[str, Any]) -> dict[str, Any]:
     return payload
 
 
+def _workflow_plan(change_dir: Path) -> dict[str, Any] | None:
+    policy_path = change_dir / "meta" / "gate-policy.json"
+    if not policy_path.is_file():
+        return None
+    try:
+        policy = json.loads(policy_path.read_text(encoding="utf-8-sig"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    if not isinstance(policy, dict):
+        return None
+    raw = policy.get("plannedPhases")
+    source = "change"
+    if not isinstance(raw, list) or not raw:
+        raw = policy.get("defaultPhases")
+        source = "policy-default"
+    if not isinstance(raw, list):
+        return None
+    phases = [str(item).strip() for item in raw if str(item).strip()]
+    if not phases:
+        return None
+    skipped = policy.get("skippedPhases")
+    return {
+        "planned_phases": list(dict.fromkeys(phases)),
+        "skipped_phases": skipped if isinstance(skipped, list) else [],
+        "phase_plan_source": source,
+    }
+
+
+def _event_payload(event: dict[str, Any], phase_plan: dict[str, Any] | None) -> dict[str, Any]:
+    payload = sanitize(event)
+    if phase_plan is None:
+        return payload
+    payload.update(phase_plan)
+    if str(event.get("type") or "") in {"phase.end", "phase.auto_sealed"}:
+        phase = str(event.get("phase") or "").strip()
+        planned = phase_plan["planned_phases"]
+        if phase in planned:
+            index = planned.index(phase)
+            payload["next_phase"] = planned[index + 1] if index + 1 < len(planned) else None
+    return payload
+
+
 def _valid_display_title(value: Any) -> str | None:
     if not isinstance(value, str):
         return None
@@ -469,6 +542,7 @@ def sync_change(
         repair=True,
     )
     pending_raw = lines[acked:]
+    phase_plan = _workflow_plan(change_dir)
     uploaded = 0
     quarantined = 0
     last_result: dict[str, Any] | None = None
@@ -500,7 +574,7 @@ def sync_change(
                 "producer_seq": line_number,
                 "event_type": str(event.get("type") or "unknown"),
                 "occurred_at": str(event.get("timestamp") or event.get("ts") or client_time),
-                "payload": sanitize(event),
+                "payload": _event_payload(event, phase_plan),
             }
             if event.get("phase") is not None:
                 item["phase"] = event.get("phase")
@@ -727,6 +801,31 @@ class _CrossProcessLock:
             self._stream = None
 
 
+def _windowless_python_executable(
+    executable: str, base_executable: str | None
+) -> str:
+    """Return a Windows interpreter that cannot allocate a console window.
+
+    Virtual-environment ``python.exe`` files may be forwarding launchers.  Even
+    when the first process is created with ``CREATE_NO_WINDOW``, such a launcher
+    can start the real console interpreter and make Windows Terminal flash.  A
+    sibling ``pythonw.exe`` preserves the windowless subsystem across that hop.
+    """
+    executable_path = Path(executable)
+    candidates = [executable_path.with_name("pythonw.exe")]
+    if base_executable:
+        base_path = Path(base_executable)
+        base_windowless = base_path.with_name("pythonw.exe")
+        if base_windowless not in candidates:
+            candidates.append(base_windowless)
+    for candidate in candidates:
+        if candidate.is_file():
+            return str(candidate)
+    if base_executable and Path(base_executable).is_file():
+        return str(Path(base_executable))
+    return str(executable_path)
+
+
 def schedule_events_sync(project_root: Path, change_dir: Path) -> bool:
     """Wake a finite, project-local sync worker after an event is durable.
 
@@ -748,8 +847,14 @@ def schedule_events_sync(project_root: Path, change_dir: Path) -> bool:
     temporary = nudge.with_name(f".{nudge.name}.{uuid.uuid4().hex}.tmp")
     temporary.write_text(json.dumps(payload, separators=(",", ":")) + "\n", encoding="utf-8")
     os.replace(temporary, nudge)
+    interpreter = sys.executable
+    if os.name == "nt":
+        interpreter = _windowless_python_executable(
+            sys.executable,
+            getattr(sys, "_base_executable", None),
+        )
     command = [
-        sys.executable,
+        interpreter,
         str(Path(__file__).resolve()),
         "--project",
         str(project_root),