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

1"""INTENT under the ladder settings (#55, items 7, 8 and 11). 

2 

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.""" 

17 

18from __future__ import annotations 

19 

20from dataclasses import dataclass 

21from typing import TYPE_CHECKING, Any 

22 

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 

36 

37if TYPE_CHECKING: 

38 from governed_harness.orchestration.ladder_host import LadderHost 

39 

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.""" 

44 

45 

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, ...] = () 

52 

53 

54class LadderIntake: 

55 def __init__(self, ladder: LadderHost) -> None: 

56 self.ladder = ladder 

57 

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" 

63 

64 @property 

65 def locate_config(self) -> Any: 

66 context = self.ladder.project.context 

67 return context.locate if context else None 

68 

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 

103 

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)) 

138 

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 

182 

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 

187 

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 

205 

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 

209 

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 ) 

236 

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 } 

263 

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 ) 

383 

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 ) 

399 

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"],)) 

423 

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] 

450 

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 ) 

465 

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 

469 

470 

471__all__ = ["HUMAN_EVENTS", "IntentResult", "LadderIntake"]