Coverage for src/governed_harness/retrospective/causal.py: 93%

57 statements  

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

1"""Recommendations derived from causes (``retrospective.causal``); see ``causes``.""" 

2 

3from __future__ import annotations 

4 

5from typing import Literal 

6 

7from governed_harness.domain.enums import ActorType 

8from governed_harness.domain.ids import new_id 

9from governed_harness.domain.models import ( 

10 Actor, 

11 Provenance, 

12 Recommendation, 

13 Retrospective, 

14 RetrospectiveCause, 

15 RetrospectiveObservation, 

16 RetrospectiveTrigger, 

17) 

18from governed_harness.retrospective.causes import CauseAnalysis 

19from governed_harness.telemetry.metrics import MetricValue 

20 

21Risk = Literal["LOW", "MEDIUM", "HIGH"] 

22_Spec = tuple[RetrospectiveCause | None, str, str, str, float, Risk] 

23"""A recommendation before it has an id: (cause, category, statement, rationale, confidence, 

24risk).""" 

25 

26 

27def _observation(statement: str, evidence_refs: tuple[str, ...]) -> RetrospectiveObservation: 

28 return RetrospectiveObservation( 

29 observation_id=new_id("observation"), 

30 statement=statement, 

31 evidence_refs=evidence_refs, 

32 ) 

33 

34 

35def _recommendation(evidence_refs: tuple[str, ...], spec: _Spec) -> Recommendation: 

36 cause, category, statement, rationale, confidence, risk = spec 

37 return Recommendation( 

38 recommendation_id=new_id("recommendation"), 

39 category=category, 

40 statement=statement, 

41 rationale=rationale, 

42 evidence_refs=(*evidence_refs, *(cause.evidence_refs if cause else ())), 

43 confidence=round(min(0.95, confidence), 2), 

44 risk=risk, 

45 ) 

46 

47 

48def _cause_statement(cause: RetrospectiveCause) -> str: 

49 where = ( 

50 " (attempt " + ", ".join(str(item) for item in cause.attempts) + ")" 

51 if cause.attempts 

52 else "" 

53 ) 

54 return ( 

55 f"{cause.reason_code} {cause.subject}: {cause.effect}, {cause.occurrences} time(s){where}." 

56 ) 

57 

58 

59def _blocking_finding_spec(cause: RetrospectiveCause, excepted: set[str]) -> _Spec: 

60 precision = cause.subject in excepted 

61 return ( 

62 cause, 

63 f"rule:{cause.subject}", 

64 ( 

65 f"Check whether rule {cause.subject} is precise: it failed the gate " 

66 f"{cause.occurrences} time(s) and an exception was granted over it." 

67 ) 

68 if precision 

69 else ( 

70 f"Address rule {cause.subject} before verification (task constraints or " 

71 f"agent instructions): it failed the gate {cause.occurrences} time(s)." 

72 ), 

73 f"Reason code BLOCKING_FINDING for {cause.subject}.", 

74 0.65 + 0.1 * cause.occurrences, 

75 "MEDIUM" if precision else "LOW", 

76 ) 

77 

78 

79def _cause_spec(cause: RetrospectiveCause, excepted: set[str]) -> _Spec | None: 

80 """The recommendation a cause leads to, if any.""" 

81 code = cause.reason_code 

82 if code.startswith("MANDATORY_VALIDATOR_"): 

83 return ( 

84 cause, 

85 f"validation:{cause.subject}", 

86 f"Run {cause.subject} before handing the change over: it stopped VERIFICATION " 

87 f"in {cause.occurrences} attempt(s).", 

88 f"Reason code {code} in attempt(s) " 

89 + ", ".join(str(item) for item in cause.attempts) 

90 + "; optional validators without effect on the gate are not counted.", 

91 0.6 + 0.1 * cause.occurrences, 

92 "LOW", 

93 ) 

94 if code == "BLOCKING_FINDING": 

95 return _blocking_finding_spec(cause, excepted) 

96 if code == "CHANGES_REQUESTED": 

97 return ( 

98 cause, 

99 "specification", 

100 "Review whether acceptance criteria can be made more discriminating before " 

101 "implementation.", 

102 f"A person requested changes {cause.occurrences} time(s) after the evidence had " 

103 "been produced.", 

104 0.70, 

105 "LOW", 

106 ) 

107 if code == "REJECTED": 

108 return ( 

109 cause, 

110 "specification", 

111 "Compare the rejected change with the task's acceptance criteria before the next " 

112 "run: they did not exclude what was rejected.", 

113 "The run was rejected by a human decision.", 

114 0.70, 

115 "MEDIUM", 

116 ) 

117 if code == "PROVIDER_TRANSIENT_FAILURE": 

118 return ( 

119 cause, 

120 "provider", 

121 f"Check the limits and availability of provider {cause.subject}: its call was " 

122 f"repeated {cause.occurrences} time(s) after transient failures.", 

123 "Reason code PROVIDER_TRANSIENT_FAILURE.", 

124 0.60, 

125 "LOW", 

126 ) 

127 if code.startswith("POST_RUN_"): 127 ↛ 128line 127 didn't jump to line 128 because the condition on line 127 was never true

128 kind = code.removeprefix("POST_RUN_").lower() 

129 return ( 

130 cause, 

131 "outcome", 

132 f"Review which controls let this change pass: a {kind} ({cause.subject}) was " 

133 "linked to it after the run.", 

134 "An outcome recorded after the run points at the change this run approved.", 

135 0.75, 

136 "MEDIUM", 

137 ) 

138 return None 

139 

140 

141def _run_specs(files: int, reviews: int) -> list[_Spec]: 

142 """Recommendations from the size of the ChangeSet and the review cycles.""" 

143 specs: list[_Spec] = [] 

144 if files >= 12: 144 ↛ 145line 144 didn't jump to line 145 because the condition on line 144 was never true

145 specs.append( 

146 ( 

147 None, 

148 "scope", 

149 "Consider splitting future tasks with a similar ChangeSet size into " 

150 "independently verifiable units.", 

151 f"The ChangeSet touched {files} files, increasing review and traceability burden.", 

152 0.65, 

153 "MEDIUM", 

154 ) 

155 ) 

156 if reviews > 1: 

157 specs.append( 

158 ( 

159 None, 

160 "review", 

161 "Inspect recurring review findings before changing any rule or prompt.", 

162 "The independent review phase was repeated.", 

163 0.60, 

164 "MEDIUM", 

165 ) 

166 ) 

167 return specs 

168 

169 

170_NO_CAUSE: _Spec = ( 

171 None, 

172 "observation", 

173 "Preserve the current controls and collect additional executions before proposing a " 

174 "rule change.", 

175 "No cause stopped or redirected this run.", 

176 0.80, 

177 "LOW", 

178) 

179 

180 

181def causal_retrospective( 

182 *, 

183 execution_id: str, 

184 metrics: dict[str, MetricValue], 

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

186 provenance: Provenance, 

187 analysis: CauseAnalysis, 

188 trigger: RetrospectiveTrigger, 

189) -> Retrospective: 

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

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

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

193 statements = [ 

194 f"Retrospective {trigger} after {attempts} implementation attempt(s).", 

195 *(_cause_statement(cause) for cause in analysis.causes), 

196 *analysis.notes, 

197 ] 

198 observations = [_observation(statement, evidence_refs) for statement in statements] 

199 excepted = { 

200 cause.subject for cause in analysis.causes if cause.reason_code == "EXCEPTION_GRANTED" 

201 } 

202 specs = [spec for spec in (_cause_spec(cause, excepted) for cause in analysis.causes) if spec] 

203 specs += _run_specs(files, reviews) 

204 recommendations = [_recommendation(evidence_refs, spec) for spec in specs or [_NO_CAUSE]] 

205 actor = Actor(actor_type=ActorType.HARNESS, actor_id="harness.retrospective", version="2") 

206 return Retrospective( 

207 retrospective_id=new_id("retro"), 

208 execution_id=execution_id, 

209 observations=tuple(observations), 

210 recommendations=tuple(recommendations), 

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

212 trigger=trigger, 

213 causes=tuple(analysis.causes), 

214 )