@hunter-harness/workflow-harness 0.2.54 → 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(
@@ -474,30 +578,103 @@ def close_transition(
     *,
     from_phase: str,
     to_phase: str,
-    executor: str,
+    executor: str | None,
     artifacts: list[str] | None = None,
     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]] = []
+    for raw in artifacts or []:
+        requested = Path(raw)
+        candidates = (
+            [requested]
+            if requested.is_absolute()
+            else [project / requested, contract_root / requested]
+        )
+        valid: list[Path] = []
+        for candidate in candidates:
+            try:
+                resolved_candidate = candidate.resolve()
+            except OSError:
+                continue
+            if resolved_candidate in valid:
+                continue
+            if resolved_candidate.is_relative_to(project) and resolved_candidate.is_file():
+                valid.append(resolved_candidate)
+        if len(valid) > 1:
+            return {
+                "ok": False,
+                "code": "TRANSITION_ARTIFACT_AMBIGUOUS",
+                "path": raw,
+                "candidates": [item.relative_to(project).as_posix() for item in valid],
+                "message": "relative artifact exists under both project and change roots",
+            }
+        if not valid:
+            return {
+                "ok": False,
+                "code": "TRANSITION_ARTIFACT_INVALID",
+                "path": raw,
+                "acceptedBases": [str(project), str(contract_root)],
+                "examples": [
+                    str(contract_root / "meta" / "plan-finalization.json"),
+                    f".harness/changes/{change}/meta/plan-finalization.json",
+                    "meta/plan-finalization.json",
+                ],
+            }
+        resolved_artifact = valid[0]
+        artifact_entries.append(
+            {
+                "path": resolved_artifact.relative_to(project).as_posix(),
+                "sha256": _sha256(resolved_artifact),
+            }
+        )
+
+    transitions = _read_ndjson(paths["transitions"])
     if not paths["lease"].is_file():
+        latest = transitions[-1] if transitions else None
+        if (
+            isinstance(latest, dict)
+            and latest.get("fromPhase") == from_phase
+            and 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)
+        ):
+            return {
+                "ok": True,
+                "code": "TRANSITION_ALREADY_CLOSED",
+                "idempotent": True,
+                "receipt": latest,
+                "path": str(paths["transitions"]),
+                "invalidation": None,
+            }
         return {"ok": False, "code": "CONTEXT_LEASE_REQUIRED"}
     try:
         lease = _read_json(paths["lease"])
     except (OSError, ValueError, json.JSONDecodeError):
         return {"ok": False, "code": "CONTEXT_LEASE_INVALID"}
-    if lease.get("owner") != executor or lease.get("phase") != from_phase:
+    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:
         return {
             "ok": False,
             "code": "CONTEXT_LEASE_MISMATCH",
@@ -508,25 +685,6 @@ def close_transition(
     if expiry is None or _now() >= expiry:
         return {"ok": False, "code": "CONTEXT_LEASE_EXPIRED"}
 
-    artifact_entries: list[dict[str, Any]] = []
-    for raw in artifacts or []:
-        path = Path(raw)
-        if not path.is_absolute():
-            path = contract_root / path
-        resolved = path.resolve()
-        if not resolved.is_relative_to(project) or not resolved.is_file():
-            return {
-                "ok": False,
-                "code": "TRANSITION_ARTIFACT_INVALID",
-                "path": str(path),
-            }
-        artifact_entries.append(
-            {
-                "path": resolved.relative_to(project).as_posix(),
-                "sha256": _sha256(resolved),
-            }
-        )
-    transitions = _read_ndjson(paths["transitions"])
     previous_hash = transitions[-1].get("receiptHash") if transitions else None
     attempt = (
         1
@@ -543,7 +701,7 @@ def close_transition(
         "fromPhase": from_phase,
         "toPhase": to_phase,
         "status": status,
-        "executor": executor,
+        "executor": effective_executor,
         "productCommit": _head(project),
         "artifacts": artifact_entries,
         "attempt": attempt,
@@ -724,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)
@@ -759,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

@@ -41,7 +41,7 @@ def _project_root_for_change(change_dir: Path) -> Path | None:
     return None
 
 
-def _nudge_remote_sync(change_dir: Path) -> None:
+def nudge_remote_sync(change_dir: Path) -> None:
     """Best-effort wake-up after the event append has been flushed to disk."""
     project_root = _project_root_for_change(change_dir)
     if project_root is None:
@@ -55,6 +55,11 @@ def _nudge_remote_sync(change_dir: Path) -> None:
         return
 
 
+def _nudge_remote_sync(change_dir: Path) -> None:
+    """Compatibility wrapper for older callers and focused tests."""
+    nudge_remote_sync(change_dir)
+
+
 if hasattr(sys.stdout, "reconfigure"):
     sys.stdout.reconfigure(encoding="utf-8")
 if hasattr(sys.stderr, "reconfigure"):
@@ -66,6 +71,8 @@ EVENT_TYPES = frozenset(
         "phase.start",
         "phase.end",
         "phase.auto_sealed",
+        "gate.blocked",
+        "gate.recovered",
         "command",
         "verification",
         "artifact",
@@ -121,6 +128,12 @@ OPTIONAL_FIELDS = (
     "renamed_from",
     "renamed_to",
     "change_uuid",
+    "execution_mode",
+    "decision_reason_code",
+    "fallback_reason_code",
+    "trigger",
+    "from_phase",
+    "result_status",
 )
 
 _PROVENANCE_FIELDS = frozenset(
@@ -139,6 +152,12 @@ _PROVENANCE_FIELDS = frozenset(
         "orchestration_active_ms",
         "wall_clock_ms",
         "user_wait_ms",
+        "execution_mode",
+        "decision_reason_code",
+        "fallback_reason_code",
+        "trigger",
+        "from_phase",
+        "result_status",
     }
 )
 _EVENT_ALLOWED_FIELDS = {
@@ -148,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(
@@ -1698,6 +1721,22 @@ def append_with_auto_seal(
                 else []
             )
         )
+        if event_type in {"phase.start", "phase.end", "phase.auto_sealed"} and phase:
+            phase_attempts = split_phase_attempts(
+                [item for item in loaded if item.get("phase") == phase]
+            )
+            latest_attempt = max(
+                (
+                    int(item.get("attempt"))
+                    for item in phase_attempts
+                    if isinstance(item.get("attempt"), int)
+                ),
+                default=0,
+            )
+            if not isinstance(event.get("attempt"), int) or int(event["attempt"]) <= 0:
+                event["attempt"] = (
+                    latest_attempt + 1 if event_type == "phase.start" else latest_attempt or 1
+                )
         if event_type == "phase.start" and phase:
             auto_sealed = seal_open_phase_attempts(loaded, phase=phase)
             for seal_event in auto_sealed:
@@ -1765,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:
@@ -1797,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:
@@ -1819,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)
 
@@ -1967,6 +2042,12 @@ def build_parser() -> argparse.ArgumentParser:
     p_append.add_argument("--orchestration-active-ms", type=int, default=None)
     p_append.add_argument("--wall-clock-ms", type=int, default=None)
     p_append.add_argument("--user-wait-ms", type=int, default=None)
+    p_append.add_argument("--execution-mode", default=None)
+    p_append.add_argument("--decision-reason-code", default=None)
+    p_append.add_argument("--fallback-reason-code", default=None)
+    p_append.add_argument("--trigger", default=None)
+    p_append.add_argument("--from-phase", default=None)
+    p_append.add_argument("--result-status", default=None)
     p_append.add_argument(
         "--legacy-lenient",
         action="store_true",