Coverage for src/governed_harness/orchestration/ladder_intake.py: 92%
187 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"""INTENT under the ladder settings (#55, items 7, 8 and 11).
3* **Operational contract** (``intake.operationalContract``): the contract summary of the task
4 revision (``ladder.contract``) is recorded, bound to the task digest. Under ``batch`` it rides
5 in the one clarification request INTENT sends anyway (a ``contract`` section next to the
6 questions, answered in the same file); under ``enforce`` INTENT also stops until every item is
7 settled and a person confirmed the summary (``harness task confirm`` or ``confirmContract`` in
8 the answers file).
9* **Interruption budget** (``intake.interruptions``): the human interactions of a run are counted
10 from its event chain and reported against the target; the declared stop conditions are
11 recorded when they occur (here: questions asked again about a task that was already
12 clarified, ``unresolvable-ambiguity``).
13* **Localisation** (``context.locate``): for a task the router classifies M or L, a read-only
14 ``locate`` call returns where to intervene; it runs once per task revision (cached by its
15 digest, reused by later runs) on the cheapest rung of the router; ambiguous places come back
16 as questions (rule ``A3``) and the locations feed the context manifest of IMPLEMENTATION."""
18from __future__ import annotations
20from dataclasses import dataclass
21from typing import TYPE_CHECKING, Any
23from governed_harness.agents.routing import classify_size
24from governed_harness.domain.enums import FindingSeverity, PhaseId, ResultStatus
25from governed_harness.domain.models import (
26 ClarificationQuestion,
27 ClarificationRecord,
28 Execution,
29 PhaseExecution,
30 Task,
31)
32from governed_harness.evidence.hashing import sha256_json
33from governed_harness.intake import task_digest
34from governed_harness.ladder.contract import ContractSummary, derive_contract
35from governed_harness.telemetry.metrics import HUMAN_INTERACTION_EVENTS, human_interactions
37if TYPE_CHECKING:
38 from governed_harness.orchestration.ladder_host import LadderHost
40LOCATE_MALFORMED_RULE = "locate.malformed"
41MAX_LOCATE_QUESTIONS = 10
42HUMAN_EVENTS = HUMAN_INTERACTION_EVENTS
43"""Events a person causes, by the kind of interruption they count as."""
46@dataclass(frozen=True)
47class IntentResult:
48 questions: tuple[ClarificationQuestion, ...] = ()
49 contract: dict[str, Any] | None = None
50 blocked: str | None = None
51 evidence_refs: tuple[str, ...] = ()
54class LadderIntake:
55 def __init__(self, ladder: LadderHost) -> None:
56 self.ladder = ladder
58 # ----- configuration ----------------------------------------------------------------------
59 @property
60 def contract_mode(self) -> str:
61 intake = self.ladder.project.intake
62 return (intake.operational_contract if intake else None) or "off"
64 @property
65 def locate_config(self) -> Any:
66 context = self.ladder.project.context
67 return context.locate if context else None
69 def defaults(
70 self, execution: Execution | None = None, task: Task | None = None
71 ) -> dict[str, Any]:
72 """What the project configuration says about the items a task's contract may leave
73 out (a branch template is filled with the run and the task)."""
74 project = self.ladder.project
75 delivery = project.delivery_settings
76 verification = project.verification
77 ladder = verification.ladder if verification else None
78 isolation = project.workspace.isolation
79 coverage = None
80 if verification and verification.test_quality and verification.test_quality.diff_coverage:
81 coverage = verification.test_quality.diff_coverage
82 branch_template: str | None
83 if isolation and isolation.effective_mode == "worktree": 83 ↛ 84line 83 didn't jump to line 84 because the condition on line 83 was never true
84 branch_template = isolation.branch_template
85 else:
86 branch_template = delivery.branch_template if delivery.mode == "branch" else None
87 values: dict[str, Any] = {
88 "verificationLevel": ladder.required_default.value
89 if ladder and ladder.enabled
90 else None,
91 "branch": branch_template,
92 "push": delivery.push,
93 "createPullRequest": delivery.pull_request.create if delivery.pull_request else None,
94 "comment": delivery.comment,
95 "coverageThreshold": coverage,
96 }
97 branch = values["branch"]
98 if isinstance(branch, str) and execution is not None and task is not None: 98 ↛ 102line 98 didn't jump to line 102 because the condition on line 98 was always true
99 values["branch"] = branch.replace("{runId}", execution.execution_id).replace(
100 "{taskId}", task.task_id
101 )
102 return values
104 # ----- INTENT -----------------------------------------------------------------------------
105 def intent(
106 self,
107 execution: Execution,
108 phase: PhaseExecution,
109 task: Task,
110 questions: tuple[ClarificationQuestion, ...],
111 ) -> IntentResult:
112 refs: list[str] = []
113 located = self.locate(execution, phase, task, len(questions) + 1)
114 if located.blocked is not None: 114 ↛ 115line 114 didn't jump to line 115 because the condition on line 114 was never true
115 return located
116 refs.extend(located.evidence_refs)
117 asked = (*questions, *located.questions)
118 if asked:
119 self._ambiguity_stop(execution, task)
120 mode = self.contract_mode
121 if mode == "off":
122 return IntentResult(located.questions, None, None, tuple(refs))
123 summary, ref = self.summarize(execution, phase, task)
124 refs.append(ref)
125 confirmed = self.confirmed(execution, summary)
126 section = {**summary.as_dict(), "mode": mode, "confirmed": confirmed}
127 blocked: str | None = None
128 if mode == "enforce" and (summary.missing or not confirmed):
129 blocked = (
130 f"Operational contract: {len(summary.missing)} item(s) not settled "
131 f"({', '.join(summary.missing)})"
132 if summary.missing
133 else "Operational contract not confirmed: harness task confirm --task "
134 f"{task.task_id} --digest {summary.digest}"
135 )
136 include = bool(asked) or blocked is not None
137 return IntentResult(located.questions, section if include else None, blocked, tuple(refs))
139 def summarize(
140 self, execution: Execution, phase: PhaseExecution, task: Task
141 ) -> tuple[ContractSummary, str]:
142 """The contract summary of the task revision, recorded once per task digest."""
143 results = self.ladder.engine.results
144 digest = task_digest(task)
145 summary = derive_contract(task, digest, self.defaults(execution, task))
146 key = f"contract:{execution.execution_id}:{summary.digest}"
147 known = results.flag_json(key)
148 if isinstance(known, dict) and isinstance(known.get("ref"), str):
149 return summary, str(known["ref"])
150 ref = results.record_json(
151 execution,
152 PhaseId.INTENT,
153 summary.as_dict(),
154 kind="operational-contract",
155 summary=(
156 f"Operational contract {summary.digest[:19]}: "
157 f"{len(summary.missing)} item(s) not settled"
158 ),
159 supports=(task.task_id,),
160 )
161 results.set_flag_json(key, {"ref": ref})
162 results.set_flag_json(
163 f"contractcurrent:{execution.execution_id}",
164 {
165 "digest": summary.digest,
166 "taskDigest": digest,
167 "ref": ref,
168 },
169 )
170 self.ladder.s.events.append(
171 execution.execution_id,
172 "contract.summarized",
173 {
174 "digest": summary.digest,
175 "taskDigest": digest,
176 "missing": list(summary.missing),
177 "evidenceRef": ref,
178 },
179 phase_execution_id=phase.phase_execution_id,
180 )
181 return summary, ref
183 def confirm_revision(self, execution: Execution, task: Task, actor: Any) -> str:
184 """A person confirmed, with their answers, the contract of the revision the answers
185 produce (``confirmContract`` in the answers file)."""
186 from governed_harness.domain.models import utc_now
188 summary = derive_contract(task, task_digest(task), self.defaults(execution, task))
189 self.ladder.engine.results.set_flag_json(
190 f"contractconfirmed:{execution.execution_id}",
191 {
192 "digest": summary.digest,
193 "actorId": actor.actor_id,
194 "confirmedAt": utc_now().isoformat(),
195 },
196 )
197 self.ladder.s.events.append(
198 execution.execution_id,
199 "contract.confirmed",
200 # Confirmed in the answers to the clarification: the same interaction.
201 {"digest": summary.digest, "taskDigest": summary.task_digest, "withAnswers": True},
202 actor=actor,
203 )
204 return summary.digest
206 def confirmed(self, execution: Execution, summary: ContractSummary) -> bool:
207 value = self.ladder.engine.results.flag_json(f"contractconfirmed:{execution.execution_id}")
208 return isinstance(value, dict) and value.get("digest") == summary.digest
210 # ----- interruptions ------------------------------------------------------------------------
211 def _ambiguity_stop(self, execution: Execution, task: Task) -> None:
212 """A task that a person already clarified in this run and still raises questions is
213 the ``unresolvable-ambiguity`` stop condition."""
214 config = self.ladder.project.intake.interruptions if self.ladder.project.intake else None
215 if config is None or "unresolvable-ambiguity" not in config.conditions:
216 return
217 rounds = [
218 item
219 for item in self.ladder.s.state.list(
220 "clarification", ClarificationRecord, execution_id=execution.execution_id
221 )
222 if item.task_id == task.task_id
223 ]
224 if not rounds:
225 return
226 self.ladder.s.events.append(
227 execution.execution_id,
228 "stop.condition",
229 {
230 "condition": "unresolvable-ambiguity",
231 "rounds": len(rounds),
232 "taskDigest": task_digest(task),
233 "detail": "INTENT asks again after the task was clarified",
234 },
235 )
237 def interruptions(self, execution: Execution) -> dict[str, Any] | None:
238 """The human interactions of a run against the budget (``intake.interruptions``)."""
239 intake = self.ladder.project.intake
240 config = intake.interruptions if intake else None
241 if config is None:
242 return None
243 events = self.ladder.s.events.list(execution.execution_id)
244 by_kind = human_interactions(events)
245 count = sum(by_kind.values())
246 stops = [
247 {
248 "condition": event.payload.get("condition"),
249 "detail": event.payload.get("detail"),
250 "recordedAt": event.occurred_at,
251 }
252 for event in events
253 if event.event_type == "stop.condition"
254 ]
255 return {
256 "count": count,
257 "target": config.effective_target,
258 "overBudget": count > config.effective_target,
259 "byKind": by_kind,
260 "stopConditions": list(config.conditions),
261 "stops": stops,
262 }
264 # ----- localisation ---------------------------------------------------------------------------
265 def locate(
266 self, execution: Execution, phase: PhaseExecution, task: Task, start: int
267 ) -> IntentResult:
268 config = self.locate_config
269 if config is None or not config.enabled:
270 return IntentResult()
271 hub = self.ladder
272 results = hub.engine.results
273 policy = hub.project.agent_routing
274 size, rule = classify_size(
275 results.task_signals(execution, task), policy.thresholds if policy else None
276 )
277 digest = task_digest(task)
278 if size == "S":
279 hub.s.events.append(
280 execution.execution_id,
281 "locate.skipped",
282 {"taskDigest": digest, "size": size, "rule": rule},
283 phase_execution_id=phase.phase_execution_id,
284 )
285 return IntentResult()
286 friction = hub.engine.friction
287 if friction.active and friction.skips(execution, "locate", PhaseId.INTENT): 287 ↛ 289line 287 didn't jump to line 289 because the condition on line 287 was never true
288 # governance.riskProfile: the light profile asks for no localisation.
289 return IntentResult()
290 key = f"locate:{execution.project_id}:{task.task_id}:{digest}"
291 scope_key = (
292 f"locatescope:{execution.project_id}:{task.task_id}:"
293 f"{self._scope_digest(task, size, config.limit)}"
294 if config.reuses_scope
295 else None
296 )
297 cached = results.flag_json(key)
298 if scope_key is not None and not isinstance(cached, dict):
299 reused = self._scope_reuse(execution, phase, digest, results.flag_json(scope_key))
300 if reused is not None:
301 return reused
302 if isinstance(cached, dict) and isinstance(cached.get("locations"), list):
303 hub.s.events.append(
304 execution.execution_id,
305 "locate.reused",
306 {
307 "taskDigest": digest,
308 "locations": len(cached["locations"]),
309 "evidenceRef": cached["ref"],
310 },
311 phase_execution_id=phase.phase_execution_id,
312 )
313 results.set_flag_json(f"located:{execution.execution_id}", cached)
314 return IntentResult(
315 self._questions(start, cached.get("questions") or []), None, None, (cached["ref"],)
316 )
317 payload = {"maxLocations": config.limit, "size": size}
318 outcome = results.call_agent(
319 execution,
320 phase,
321 "locate",
322 payload,
323 task=task,
324 instruction_values={"maxLocations": config.limit},
325 validate=lambda result: self._validated(result, config.limit),
326 )
327 if outcome.status is not ResultStatus.PASSED or outcome.result is None: 327 ↛ 328line 327 didn't jump to line 328 because the condition on line 327 was never true
328 return IntentResult(
329 (),
330 None,
331 f"The locate call did not answer ({outcome.status}): {outcome.summary}",
332 outcome.evidence_refs,
333 )
334 try:
335 locations, questions = self._validated(outcome.result, config.limit)
336 except ValueError as error:
337 results.record_finding(
338 execution,
339 validator_id="harness.locate",
340 rule_id=LOCATE_MALFORMED_RULE,
341 category="localisation",
342 severity=FindingSeverity.HIGH,
343 message=f"The locate call returned a malformed result: {error}",
344 evidence_refs=outcome.evidence_refs,
345 )
346 return IntentResult(
347 (), None, f"The locate call was malformed: {error}", outcome.evidence_refs
348 )
349 record = {
350 "taskDigest": digest,
351 "size": size,
352 "locations": locations,
353 "questions": questions,
354 "invocationId": outcome.invocation_id,
355 }
356 ref = results.record_json(
357 execution,
358 PhaseId.INTENT,
359 record,
360 kind="locate-result",
361 summary=f"Locate: {len(locations)} location(s), {len(questions)} question(s)",
362 supports=(task.task_id,),
363 )
364 stored = {**record, "ref": ref}
365 results.set_flag_json(key, stored)
366 if scope_key is not None:
367 results.set_flag_json(scope_key, stored)
368 results.set_flag_json(f"located:{execution.execution_id}", stored)
369 hub.s.events.append(
370 execution.execution_id,
371 "locate.completed",
372 {
373 "taskDigest": digest,
374 "locations": len(locations),
375 "questions": len(questions),
376 "evidenceRef": ref,
377 },
378 phase_execution_id=phase.phase_execution_id,
379 )
380 return IntentResult(
381 self._questions(start, questions), None, None, (*outcome.evidence_refs, ref)
382 )
384 @staticmethod
385 def _scope_digest(task: Task, size: str, limit: int) -> str:
386 """The scope a locate answer depends on (``context.locate.reuse: scope``): the owned
387 paths, the scope items of the task's contract, the size class and the limit."""
388 contract = task.contract.model_dump(mode="json", by_alias=True) if task.contract else {}
389 return sha256_json(
390 {
391 "ownedPaths": sorted(str(item) for item in task.metadata.get("ownedPaths") or []),
392 "scope": contract.get("scope"),
393 "scopePaths": contract.get("scopePaths"),
394 "outOfScope": contract.get("outOfScope"),
395 "size": size,
396 "limit": limit,
397 }
398 )
400 def _scope_reuse(
401 self, execution: Execution, phase: PhaseExecution, digest: str, cached: Any
402 ) -> IntentResult | None:
403 """The locate result of an earlier revision with the same scope, reused without a call
404 and without its questions (the clarification that produced this revision answered
405 them); ``None`` when there is none."""
406 if not isinstance(cached, dict) or not isinstance(cached.get("locations"), list):
407 return None
408 hub = self.ladder
409 hub.s.events.append(
410 execution.execution_id,
411 "locate.reused",
412 {
413 "taskDigest": digest,
414 "fromTaskDigest": cached.get("taskDigest"),
415 "scope": True,
416 "locations": len(cached["locations"]),
417 "evidenceRef": cached["ref"],
418 },
419 phase_execution_id=phase.phase_execution_id,
420 )
421 hub.engine.results.set_flag_json(f"located:{execution.execution_id}", cached)
422 return IntentResult((), None, None, (cached["ref"],))
424 @staticmethod
425 def _validated(result: dict[str, Any], limit: int) -> tuple[list[dict[str, Any]], list[str]]:
426 raw = result.get("locations")
427 if not isinstance(raw, list): 427 ↛ 428line 427 didn't jump to line 428 because the condition on line 427 was never true
428 raise ValueError("the locate result needs a 'locations' list")
429 locations: list[dict[str, Any]] = []
430 for index, item in enumerate(raw[:limit], start=1):
431 if not isinstance(item, dict) or not isinstance(item.get("path"), str): 431 ↛ 432line 431 didn't jump to line 432 because the condition on line 431 was never true
432 raise ValueError(f"location {index} needs a path")
433 path = item["path"].strip().removeprefix("./")
434 if not path or path.startswith("/") or ".." in path.split("/"): 434 ↛ 435line 434 didn't jump to line 435 because the condition on line 434 was never true
435 raise ValueError(f"location {index} must be relative to the workspace: {path!r}")
436 line = item.get("line")
437 locations.append(
438 {
439 "path": path,
440 "line": line if isinstance(line, int) and line >= 1 else None,
441 "evidence": str(item.get("evidence") or "")[:1000],
442 "reason": str(item.get("reason") or "")[:500],
443 }
444 )
445 questions = [
446 str(item.get("text") if isinstance(item, dict) else item).strip()[:1000]
447 for item in (result.get("questions") or [])[:MAX_LOCATE_QUESTIONS]
448 ]
449 return locations, [item for item in questions if item]
451 @staticmethod
452 def _questions(start: int, texts: list[str]) -> tuple[ClarificationQuestion, ...]:
453 return tuple(
454 ClarificationQuestion.model_validate(
455 {
456 "questionId": f"Q-{number}",
457 "ruleId": "A3",
458 "target": "task",
459 "text": text,
460 "category": "ambiguity",
461 }
462 )
463 for number, text in enumerate(texts, start=start)
464 )
466 def located(self, execution: Execution) -> dict[str, Any] | None:
467 value = self.ladder.engine.results.flag_json(f"located:{execution.execution_id}")
468 return value if isinstance(value, dict) and value.get("locations") else None
471__all__ = ["HUMAN_EVENTS", "IntentResult", "LadderIntake"]