Coverage for src/governed_harness/configuration/workflow_rules.py: 100%

35 statements  

« prev     ^ index     » next       coverage.py v7.17.2, created at 2026-11-12 16:06 +0000

1"""The workflow conditions the engine evaluates under ``governance.enforceWorkflow`` (#3). 

2 

3The workflow names an ``exitGate`` per phase and a ``condition`` per transition. Under 

4``governance.enforceWorkflow`` the engine evaluates them from the run's records after a phase 

5attempt returns ``PASSED``, so a name it does not know is a configuration error when the 

6configuration is resolved, not a silent pass during a run. Without the key the names stay 

7labels, as in 1.0.0. 

8""" 

9 

10from __future__ import annotations 

11 

12from governed_harness.configuration.models import WorkflowDefinition 

13from governed_harness.domain.errors import ConfigurationError 

14 

15EXIT_GATE_CONDITIONS: dict[str, str] = { 

16 "intent_complete": "the run's task has acceptance criteria and INTENT recorded it", 

17 "discovery_sufficient": "DISCOVERY recorded the baseline snapshot and revision", 

18 "specification_approved": "SPECIFICATION froze the acceptance contract and the run's task " 

19 "still produces it", 

20 "plan_authorized": "PLANNING stored the run's plan (a PASSED PLANNING is authorised: a plan " 

21 "that needs a person's approval keeps PLANNING BLOCKED)", 

22 "candidate_changeset": "the run's current ChangeSet is recorded and is not empty (unless " 

23 "policies.allowEmptyChangeSet)", 

24 "verification_passed": "every mandatory validation this VERIFICATION attempt recorded for the " 

25 "current ChangeSet passed", 

26 "review_complete": "the independent review recorded its result for the current ChangeSet", 

27 "decision_approved": "the current human decision is APPROVE or APPROVE_EXCEPTION, bound to " 

28 "the current ChangeSet digest and not expired", 

29 "run_closed": "CLOSURE recorded run.closed for the current ChangeSet", 

30} 

31"""Every condition the engine evaluates, with what it checks.""" 

32 

33CONDITION_ALIASES: dict[str, str] = {"decision_recorded": "decision_approved"} 

34"""Names accepted for a condition. The built-in DECISION phase names ``decision_recorded`` as 

35its exit gate while its transition to CLOSURE names ``decision_approved``: an attempt of 

36DECISION passes only on an approval (``REQUEST_CHANGES`` returns to IMPLEMENTATION and 

37``REJECT`` ends the run through ``harness gate decide``, never through a passed attempt), so 

38both names are the same check.""" 

39 

40DECISION_TRANSITION_CONDITIONS: frozenset[str] = frozenset({"authorized_correction"}) 

41"""Conditions of transitions that ``harness gate decide`` takes, not a phase attempt.""" 

42 

43 

44def canonical_condition(name: str) -> str: 

45 """The condition a gate or transition name stands for.""" 

46 return CONDITION_ALIASES.get(name, name) 

47 

48 

49def known_condition(name: str) -> bool: 

50 return canonical_condition(name) in EXIT_GATE_CONDITIONS 

51 

52 

53def enforced_workflow_errors(workflow: WorkflowDefinition) -> list[str]: 

54 """What makes a workflow unusable under ``governance.enforceWorkflow``: unknown exit gates 

55 or transition conditions, a dependency on a phase that does not come earlier (the order of 

56 the nine phases is fixed, so it could never be met), a phase that is not followed by a 

57 declared transition to the next one, and a parallelizable phase that writes the workspace 

58 (there is one workspace per run).""" 

59 return [ 

60 *_phase_errors(workflow), 

61 *_transition_errors(workflow), 

62 *_missing_transitions(workflow), 

63 ] 

64 

65 

66def _phase_errors(workflow: WorkflowDefinition) -> list[str]: 

67 errors: list[str] = [] 

68 order = [phase.phase_id for phase in workflow.phases] 

69 for position, phase in enumerate(workflow.phases): 

70 if not known_condition(phase.exit_gate): 

71 errors.append( 

72 f"phase {phase.phase_id.value}: unknown exitGate {phase.exit_gate!r}; known: " 

73 f"{', '.join(sorted({*EXIT_GATE_CONDITIONS, *CONDITION_ALIASES}))}" 

74 ) 

75 errors.extend( 

76 f"phase {phase.phase_id.value}: dependsOn {dependency.value} is not an " 

77 "earlier phase of the workflow" 

78 for dependency in phase.depends_on 

79 if dependency not in order[:position] 

80 ) 

81 if phase.parallelizable and "filesystem.write" in phase.allowed_capabilities: 

82 errors.append( 

83 f"phase {phase.phase_id.value}: parallelizable but allowed filesystem.write; " 

84 "a run has one workspace" 

85 ) 

86 return errors 

87 

88 

89def _transition_errors(workflow: WorkflowDefinition) -> list[str]: 

90 return [ 

91 f"transition {transition.source.value} -> {transition.target.value}: unknown " 

92 f"condition {transition.condition!r}" 

93 for transition in workflow.transitions 

94 if transition.condition not in DECISION_TRANSITION_CONDITIONS 

95 and not known_condition(transition.condition) 

96 ] 

97 

98 

99def _missing_transitions(workflow: WorkflowDefinition) -> list[str]: 

100 order = [phase.phase_id for phase in workflow.phases] 

101 declared = {(item.source, item.target) for item in workflow.transitions} 

102 return [ 

103 f"no transition from {source.value} to {target.value}" 

104 for source, target in zip(order, order[1:], strict=False) 

105 if (source, target) not in declared 

106 ] 

107 

108 

109def validate_enforced_workflow(workflow: WorkflowDefinition) -> None: 

110 """Raise ``ConfigurationError`` when the workflow cannot be enforced.""" 

111 errors = enforced_workflow_errors(workflow) 

112 if errors: 

113 raise ConfigurationError( 

114 f"workflow {workflow.workflow_id} cannot be enforced " 

115 f"(governance.enforceWorkflow): {'; '.join(errors)}" 

116 )