Coverage for src/governed_harness/orchestration/exit_gates.py: 73%
124 statements
« prev ^ index » next coverage.py v7.17.2, created at 2026-11-12 16:06 +0000
« prev ^ index » next coverage.py v7.17.2, created at 2026-11-12 16:06 +0000
1"""Evaluation of the workflow's exit gates under ``governance.enforceWorkflow`` (#3).
3After a phase attempt returns ``PASSED`` the engine evaluates the phase's ``exitGate`` and the
4condition of the transition it takes (``WorkflowGraph.exit_conditions``) from what the run
5recorded: evidence, flags, the plan, the ChangeSet, validations, the human decision and events.
6Each check is deterministic and reads only the run's records; it does not repeat the phase's
7policy decisions (an INTENT that passed with clarification warnings still passes), it checks
8that the phase left the record the next phase relies on. Every name is listed with what it
9checks in ``configuration.workflow_rules.EXIT_GATE_CONDITIONS``.
10"""
12from __future__ import annotations
14from collections.abc import Callable
15from dataclasses import dataclass
16from typing import TYPE_CHECKING
18from governed_harness.configuration.workflow_rules import (
19 EXIT_GATE_CONDITIONS,
20 canonical_condition,
21)
22from governed_harness.domain.enums import DecisionKind, EvidenceKind, PhaseId, ResultStatus
23from governed_harness.domain.errors import NotFoundError, PolicyViolationError
24from governed_harness.domain.models import (
25 Evidence,
26 Execution,
27 HumanDecision,
28 PhaseExecution,
29 Plan,
30 ValidationResult,
31 utc_now,
32)
34if TYPE_CHECKING:
35 from governed_harness.orchestration.hosts import EngineHost
37REVIEW_VALIDATOR_ID = "review.independent"
38APPROVALS = frozenset({DecisionKind.APPROVE, DecisionKind.APPROVE_EXCEPTION})
39_NO_CHANGESET = "the run has no current ChangeSet"
42@dataclass(frozen=True)
43class ExitGateCheck:
44 condition: str
45 met: bool
46 reason: str
48 def as_dict(self) -> dict[str, object]:
49 return {"condition": self.condition, "met": self.met, "reason": self.reason}
52class ExitGateEvaluator:
53 def __init__(self, engine: EngineHost) -> None:
54 self.engine = engine
55 self._checks: dict[str, Callable[[Execution, PhaseExecution], str | None]] = {
56 "intent_complete": self._intent_complete,
57 "discovery_sufficient": self._discovery_sufficient,
58 "specification_approved": self._specification_approved,
59 "plan_authorized": self._plan_authorized,
60 "candidate_changeset": self._candidate_changeset,
61 "verification_passed": self._verification_passed,
62 "review_complete": self._review_complete,
63 "decision_approved": self._decision_approved,
64 "run_closed": self._run_closed,
65 }
66 missing = set(EXIT_GATE_CONDITIONS) - set(self._checks)
67 if missing: # pragma: no cover - a programming error caught by the unit tests
68 raise RuntimeError(f"exit gates without a check: {sorted(missing)}")
70 def evaluate(self, condition: str, execution_id: str, phase: PhaseExecution) -> ExitGateCheck:
71 """Evaluate one condition for the attempt ``phase`` of the run. An unknown name is
72 unmet (the resolver rejects it before a run starts)."""
73 name = canonical_condition(condition)
74 check = self._checks.get(name)
75 if check is None: 75 ↛ 76line 75 didn't jump to line 76 because the condition on line 75 was never true
76 return ExitGateCheck(name, False, f"unknown condition {condition!r}")
77 execution = self.engine.get_execution(execution_id)
78 problem = check(execution, phase)
79 if problem is None:
80 return ExitGateCheck(name, True, EXIT_GATE_CONDITIONS[name])
81 return ExitGateCheck(name, False, problem)
83 # ----- records -----------------------------------------------------------------------
84 def _evidence(self, execution: Execution, phase_id: PhaseId, kind: EvidenceKind) -> bool:
85 return any(
86 item.phase_id is phase_id and item.kind is kind
87 for item in self.engine.s.state.list(
88 "evidence", Evidence, execution_id=execution.execution_id
89 )
90 )
92 def _attempt_validations(
93 self, execution: Execution, phase: PhaseExecution
94 ) -> dict[str, ValidationResult]:
95 """The latest validation of each validator recorded during this attempt for the
96 current ChangeSet."""
97 started = phase.started_at
98 latest: dict[str, ValidationResult] = {}
99 for item in self.engine.s.state.list(
100 "validation", ValidationResult, execution_id=execution.execution_id
101 ):
102 if item.change_set_digest != execution.change_set_digest:
103 continue
104 if started is not None and item.finished_at < started:
105 continue
106 previous = latest.get(item.validator_id)
107 if previous is None or item.finished_at >= previous.finished_at: 107 ↛ 99line 107 didn't jump to line 99 because the condition on line 107 was always true
108 latest[item.validator_id] = item
109 return latest
111 # ----- checks: None when met, otherwise the reason -------------------------------------
112 def _intent_complete(self, execution: Execution, phase: PhaseExecution) -> str | None:
113 if not self.engine.run_task(execution).acceptance_criteria: 113 ↛ 114line 113 didn't jump to line 114 because the condition on line 113 was never true
114 return "the run's task has no acceptance criteria"
115 if not self._evidence(execution, PhaseId.INTENT, EvidenceKind.INTENT): 115 ↛ 116line 115 didn't jump to line 116 because the condition on line 115 was never true
116 return "INTENT recorded no intent evidence"
117 return None
119 def _discovery_sufficient(self, execution: Execution, phase: PhaseExecution) -> str | None:
120 if not self.engine.s.state.get_flag(f"baseline:{execution.execution_id}"): 120 ↛ 121line 120 didn't jump to line 121 because the condition on line 120 was never true
121 return "DISCOVERY recorded no baseline snapshot"
122 if not execution.baseline_revision: 122 ↛ 123line 122 didn't jump to line 123 because the condition on line 122 was never true
123 return "DISCOVERY recorded no baseline revision"
124 return None
126 def _specification_approved(self, execution: Execution, phase: PhaseExecution) -> str | None:
127 if not self._evidence(execution, PhaseId.SPECIFICATION, EvidenceKind.INTENT):
128 return "SPECIFICATION recorded no acceptance contract"
129 try:
130 self.engine._current_contract_digest(execution)
131 except PolicyViolationError as error:
132 return str(error)
133 return None
135 def _plan_authorized(self, execution: Execution, phase: PhaseExecution) -> str | None:
136 plan_id = self.engine.s.state.get_flag(f"plan:{execution.execution_id}")
137 if not plan_id: 137 ↛ 138line 137 didn't jump to line 138 because the condition on line 137 was never true
138 return "PLANNING stored no plan for the run"
139 try:
140 plan = self.engine.s.state.get("plan", plan_id, Plan)
141 except NotFoundError:
142 return f"the run's plan {plan_id} is not recorded"
143 if plan.execution_id != execution.execution_id: 143 ↛ 144line 143 didn't jump to line 144 because the condition on line 143 was never true
144 return f"plan {plan_id} belongs to run {plan.execution_id}"
145 return None
147 def _candidate_changeset(self, execution: Execution, phase: PhaseExecution) -> str | None:
148 if not execution.change_set_digest: 148 ↛ 149line 148 didn't jump to line 149 because the condition on line 148 was never true
149 return _NO_CHANGESET
150 try:
151 change_set = self.engine.current_change_set(execution.execution_id)
152 except NotFoundError:
153 return "the run's ChangeSet is not recorded"
154 if change_set.digest != execution.change_set_digest: 154 ↛ 155line 154 didn't jump to line 155 because the condition on line 154 was never true
155 return "the recorded ChangeSet is not the run's current one"
156 allow_empty = bool(self.engine.s.resolved.effective_policies.get("allowEmptyChangeSet"))
157 if not change_set.files and not allow_empty: 157 ↛ 158line 157 didn't jump to line 158 because the condition on line 157 was never true
158 return "the current ChangeSet is empty"
159 return None
161 def _verification_passed(self, execution: Execution, phase: PhaseExecution) -> str | None:
162 if not execution.change_set_digest: 162 ↛ 163line 162 didn't jump to line 163 because the condition on line 162 was never true
163 return _NO_CHANGESET
164 validations = self._attempt_validations(execution, phase)
165 if not validations: 165 ↛ 166line 165 didn't jump to line 166 because the condition on line 165 was never true
166 return "VERIFICATION recorded no validation for the current ChangeSet"
167 failing = sorted(
168 item.validator_id
169 for item in validations.values()
170 if item.mandatory and item.status is not ResultStatus.PASSED
171 )
172 if failing: 172 ↛ 173line 172 didn't jump to line 173 because the condition on line 172 was never true
173 return f"mandatory validation(s) did not pass: {', '.join(failing)}"
174 return None
176 def _review_complete(self, execution: Execution, phase: PhaseExecution) -> str | None:
177 if not execution.change_set_digest: 177 ↛ 178line 177 didn't jump to line 178 because the condition on line 177 was never true
178 return _NO_CHANGESET
179 if REVIEW_VALIDATOR_ID not in self._attempt_validations(execution, phase): 179 ↛ 180line 179 didn't jump to line 180 because the condition on line 179 was never true
180 return "the independent review recorded no result for the current ChangeSet"
181 return None
183 def _decision_approved(self, execution: Execution, phase: PhaseExecution) -> str | None:
184 if not execution.human_decision_id: 184 ↛ 185line 184 didn't jump to line 185 because the condition on line 184 was never true
185 return "no current human decision"
186 try:
187 decision = self.engine.s.state.get(
188 "decision", execution.human_decision_id, HumanDecision
189 )
190 except NotFoundError:
191 return f"human decision {execution.human_decision_id} is not recorded"
192 if decision.decision not in APPROVALS: 192 ↛ 193line 192 didn't jump to line 193 because the condition on line 192 was never true
193 return f"the current human decision is {decision.decision.value}, not an approval"
194 if decision.change_set_digest != execution.change_set_digest: 194 ↛ 195line 194 didn't jump to line 195 because the condition on line 194 was never true
195 return "the human decision is bound to another ChangeSet digest"
196 if decision.expires_at is not None and decision.expires_at <= utc_now(): 196 ↛ 197line 196 didn't jump to line 197 because the condition on line 196 was never true
197 return f"the human decision expired at {decision.expires_at.isoformat()}"
198 return None
200 def _run_closed(self, execution: Execution, phase: PhaseExecution) -> str | None:
201 closed = any(
202 event.event_type == "run.closed"
203 and event.payload.get("changeSetDigest") == execution.change_set_digest
204 for event in self.engine.s.events.list(execution.execution_id)
205 )
206 return None if closed else "CLOSURE recorded no run.closed for the current ChangeSet"