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

1"""Evaluation of the workflow's exit gates under ``governance.enforceWorkflow`` (#3). 

2 

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""" 

11 

12from __future__ import annotations 

13 

14from collections.abc import Callable 

15from dataclasses import dataclass 

16from typing import TYPE_CHECKING 

17 

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) 

33 

34if TYPE_CHECKING: 

35 from governed_harness.orchestration.hosts import EngineHost 

36 

37REVIEW_VALIDATOR_ID = "review.independent" 

38APPROVALS = frozenset({DecisionKind.APPROVE, DecisionKind.APPROVE_EXCEPTION}) 

39_NO_CHANGESET = "the run has no current ChangeSet" 

40 

41 

42@dataclass(frozen=True) 

43class ExitGateCheck: 

44 condition: str 

45 met: bool 

46 reason: str 

47 

48 def as_dict(self) -> dict[str, object]: 

49 return {"condition": self.condition, "met": self.met, "reason": self.reason} 

50 

51 

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)}") 

69 

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) 

82 

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 ) 

91 

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 

110 

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 

118 

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 

125 

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 

134 

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 

146 

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 

160 

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 

175 

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 

182 

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 

199 

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"