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
« 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).
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"""
10from __future__ import annotations
12from governed_harness.configuration.models import WorkflowDefinition
13from governed_harness.domain.errors import ConfigurationError
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."""
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."""
40DECISION_TRANSITION_CONDITIONS: frozenset[str] = frozenset({"authorized_correction"})
41"""Conditions of transitions that ``harness gate decide`` takes, not a phase attempt."""
44def canonical_condition(name: str) -> str:
45 """The condition a gate or transition name stands for."""
46 return CONDITION_ALIASES.get(name, name)
49def known_condition(name: str) -> bool:
50 return canonical_condition(name) in EXIT_GATE_CONDITIONS
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 ]
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
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 ]
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 ]
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 )