Coverage for src/governed_harness/retrospective/engine.py: 100%

41 statements  

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

1from __future__ import annotations 

2 

3from governed_harness.domain.enums import ActorType 

4from governed_harness.domain.ids import new_id 

5from governed_harness.domain.models import ( 

6 Actor, 

7 Provenance, 

8 Recommendation, 

9 Retrospective, 

10 RetrospectiveObservation, 

11 RetrospectiveTrigger, 

12) 

13from governed_harness.retrospective.causal import causal_retrospective 

14from governed_harness.retrospective.causes import CauseAnalysis 

15from governed_harness.telemetry.metrics import MetricValue 

16 

17 

18class RetrospectiveEngine: 

19 """Deterministic recommendation engine. It never mutates policies or configuration.""" 

20 

21 def generate( 

22 self, 

23 *, 

24 execution_id: str, 

25 metrics: dict[str, MetricValue], 

26 evidence_refs: tuple[str, ...], 

27 provenance: Provenance, 

28 analysis: CauseAnalysis | None = None, 

29 trigger: RetrospectiveTrigger | None = None, 

30 ) -> Retrospective: 

31 """Without ``analysis`` this is the 1.0.0 retrospective. With it (``retrospective.causal``) 

32 the recommendations come from the causes: one per mandatory validator that stopped 

33 VERIFICATION, per rule that failed a gate, per decision that redirected or ended the run 

34 and per outcome recorded after it, never from optional validators without effect on the 

35 gate.""" 

36 if analysis is not None: 

37 return causal_retrospective( 

38 execution_id=execution_id, 

39 metrics=metrics, 

40 evidence_refs=evidence_refs, 

41 provenance=provenance, 

42 analysis=analysis, 

43 trigger=trigger or "ON_DEMAND", 

44 ) 

45 observations: list[RetrospectiveObservation] = [] 

46 recommendations: list[Recommendation] = [] 

47 

48 def observe(statement: str) -> str: 

49 observation_id = new_id("observation") 

50 observations.append( 

51 RetrospectiveObservation( 

52 observation_id=observation_id, 

53 statement=statement, 

54 evidence_refs=evidence_refs, 

55 ) 

56 ) 

57 return observation_id 

58 

59 non_passed = int(metrics["validation.non_passed"].value or 0) 

60 automatic = metrics.get("correction.verification_cycles") 

61 automatic_cycles = int(automatic.value or 0) if automatic else 0 

62 # correction.cycles also counts automatic corrections; the observation and the 

63 # specification recommendation are about the ones a person authorized. 

64 corrections = int(metrics["correction.cycles"].value or 0) - automatic_cycles 

65 attempts = int(metrics["implementation.attempts"].value or 0) 

66 reviews = int(metrics["review.cycles"].value or 0) 

67 files = int(metrics["changeset.files"].value or 0) 

68 observe(f"The execution recorded {attempts} implementation attempt(s).") 

69 observe(f"The execution recorded {non_passed} non-passed validation result(s).") 

70 observe(f"The execution recorded {corrections} human-authorized correction cycle(s).") 

71 if automatic_cycles: 

72 observe( 

73 f"The execution recorded {automatic_cycles} automatic correction cycle(s) " 

74 "after a failed verification." 

75 ) 

76 if non_passed >= 2: 

77 recommendations.append( 

78 Recommendation( 

79 recommendation_id=new_id("recommendation"), 

80 category="validation", 

81 statement="Run the fastest deterministic validators earlier in implementation.", 

82 rationale="Multiple validation failures increase delayed feedback and retrabajo.", 

83 evidence_refs=evidence_refs, 

84 confidence=min(0.95, 0.55 + 0.1 * non_passed), 

85 risk="LOW", 

86 ) 

87 ) 

88 if corrections >= 1: 

89 recommendations.append( 

90 Recommendation( 

91 recommendation_id=new_id("recommendation"), 

92 category="specification", 

93 statement="Review whether acceptance criteria can be made more discriminating before implementation.", 

94 rationale="A correction cycle occurred after review and decision evidence had been produced.", 

95 evidence_refs=evidence_refs, 

96 confidence=0.70, 

97 risk="LOW", 

98 ) 

99 ) 

100 if files >= 12: 

101 recommendations.append( 

102 Recommendation( 

103 recommendation_id=new_id("recommendation"), 

104 category="scope", 

105 statement="Consider splitting future tasks with a similar ChangeSet size into independently verifiable units.", 

106 rationale=f"The ChangeSet touched {files} files, increasing review and traceability burden.", 

107 evidence_refs=evidence_refs, 

108 confidence=0.65, 

109 risk="MEDIUM", 

110 ) 

111 ) 

112 if reviews > 1: 

113 recommendations.append( 

114 Recommendation( 

115 recommendation_id=new_id("recommendation"), 

116 category="review", 

117 statement="Inspect recurring review findings before changing any rule or prompt.", 

118 rationale="The independent review phase was repeated, which may indicate recurrent issues or expected correction.", 

119 evidence_refs=evidence_refs, 

120 confidence=0.60, 

121 risk="MEDIUM", 

122 ) 

123 ) 

124 if not recommendations: 

125 recommendations.append( 

126 Recommendation( 

127 recommendation_id=new_id("recommendation"), 

128 category="observation", 

129 statement="Preserve the current controls and collect additional executions before proposing a rule change.", 

130 rationale="This single execution does not provide enough recurring evidence for a structural change.", 

131 evidence_refs=evidence_refs, 

132 confidence=0.80, 

133 risk="LOW", 

134 ) 

135 ) 

136 actor = Actor(actor_type=ActorType.HARNESS, actor_id="harness.retrospective", version="1") 

137 return Retrospective( 

138 retrospective_id=new_id("retro"), 

139 execution_id=execution_id, 

140 observations=tuple(observations), 

141 recommendations=tuple(recommendations), 

142 provenance=provenance.model_copy(update={"actor": actor}), 

143 )