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
« 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``."""
3from __future__ import annotations
5from typing import Literal
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
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)."""
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 )
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 )
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 )
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 )
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
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
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)
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 )