Coverage for src/governed_harness/orchestration/decomposition.py: 88%

227 statements  

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

1"""Decomposition of large tasks into governed sub-tasks in PLANNING (#39, N10). 

2 

3A single governed task with dozens of requirements was too large for one implementation call: 

4weaker models delivered partial work, and the verification only saw the end. Under 

5``planning.decomposition: agent``, a task with more requirements than ``planning.threshold`` 

6gets a plan from a provider (call kind ``plan``, read-only): ordered sub-tasks that partition the 

7task's requirements, each with its criteria and constraints. The harness validates the partition 

8(every requirement exactly once), stores the plan with its digest and waits for a person to 

9approve it (``harness plan decide``, digest-bound). An approved plan is reused when the run 

10resumes. 

11 

12The sub-tasks then run in order on the same workspace, each through IMPLEMENTATION and 

13VERIFICATION with its own correction budget and its own gate (``subtask-<n>``), recorded as a 

14child of the run (``subtask.started`` / ``subtask.completed``). A sub-task whose gate does not 

15pass stops the run (dependent sub-tasks do not start). The parent reaches INDEPENDENT_REVIEW 

16and DECISION when every sub-task passed. The task's own constraints apply to every sub-task. 

17 

18Adaptive granularity (``planning.granularity: adaptive``): a capable model 

19(``planning.coarseModels``) starts with the whole task; only when that coarse attempt fails 

20its corrections does the run return to PLANNING and decompose (split on failure). Other models 

21decompose from the start above the threshold.""" 

22 

23from __future__ import annotations 

24 

25from dataclasses import dataclass 

26from typing import TYPE_CHECKING, Any 

27 

28from governed_harness.configuration.agent_results import DEFAULT_COARSE_MODELS 

29from governed_harness.domain.enums import ( 

30 ActorType, 

31 DecisionKind, 

32 FindingSeverity, 

33 PhaseId, 

34 ResultStatus, 

35) 

36from governed_harness.domain.errors import NotFoundError, PolicyViolationError 

37from governed_harness.domain.ids import new_id 

38from governed_harness.domain.models import ( 

39 AcceptanceCriterion, 

40 Actor, 

41 Execution, 

42 Finding, 

43 PhaseExecution, 

44 PlanStep, 

45 Task, 

46 ValidationResult, 

47 utc_now, 

48) 

49from governed_harness.evidence import sha256_json 

50from governed_harness.gates import GatePolicy 

51from governed_harness.intake import task_digest 

52from governed_harness.orchestration.engine_types import PhaseOutcome 

53 

54if TYPE_CHECKING: 

55 from governed_harness.events.sqlite_store import StoredEvent 

56 from governed_harness.orchestration.hosts import ResultsHost 

57 

58MALFORMED_RULE = "planning.plan-malformed" 

59DEFAULT_MAX_SUBTASKS = 12 

60_SUBTASK_STARTED = "subtask.started" 

61 

62 

63@dataclass(frozen=True) 

64class SubTask: 

65 title: str 

66 requirements: tuple[str, ...] 

67 criteria: tuple[str, ...] 

68 constraints: tuple[str, ...] 

69 

70 def as_dict(self) -> dict[str, Any]: 

71 return { 

72 "title": self.title, 

73 "requirements": list(self.requirements), 

74 "criteria": list(self.criteria), 

75 "constraints": list(self.constraints), 

76 } 

77 

78 

79def validate_plan(task: Task, result: dict[str, Any], max_subtasks: int) -> list[SubTask]: 

80 """The sub-tasks of a ``plan`` result; raises ``ValueError`` unless they partition the 

81 task's requirements (every requirement exactly once) and name only known criteria.""" 

82 raw = result.get("subtasks") 

83 if not isinstance(raw, list) or not raw: 83 ↛ 84line 83 didn't jump to line 84 because the condition on line 83 was never true

84 raise ValueError("the plan result needs a non-empty 'subtasks' list") 

85 if len(raw) > max_subtasks: 85 ↛ 86line 85 didn't jump to line 86 because the condition on line 85 was never true

86 raise ValueError(f"the plan has {len(raw)} sub-tasks; at most {max_subtasks} are allowed") 

87 known = [item.requirement_id for item in task.requirements] 

88 criteria = {item.criterion_id for item in task.acceptance_criteria} 

89 seen: dict[str, int] = {} 

90 items = [ 

91 _subtask(index, entry, known, criteria, seen) for index, entry in enumerate(raw, start=1) 

92 ] 

93 missing = [item for item in known if item not in seen] 

94 if missing: 

95 raise ValueError(f"requirements in no sub-task: {', '.join(missing)}") 

96 return items 

97 

98 

99def _subtask( 

100 index: int, entry: Any, known: list[str], criteria: set[str], seen: dict[str, int] 

101) -> SubTask: 

102 """One validated sub-task of the plan (the ``index`` counts from 1); records in ``seen`` 

103 the sub-task that holds each of its requirements.""" 

104 if not isinstance(entry, dict): 104 ↛ 105line 104 didn't jump to line 105 because the condition on line 104 was never true

105 raise ValueError(f"sub-task {index} is not an object") 

106 title = str(entry.get("title") or "").strip() 

107 if not title: 107 ↛ 108line 107 didn't jump to line 108 because the condition on line 107 was never true

108 raise ValueError(f"sub-task {index} has no title") 

109 requirements = entry.get("requirements") 

110 if not isinstance(requirements, list) or not requirements: 110 ↛ 111line 110 didn't jump to line 111 because the condition on line 110 was never true

111 raise ValueError(f"sub-task {index} has no requirements") 

112 _claim(index, requirements, known, seen) 

113 named = [str(item) for item in entry.get("criteria") or []] 

114 unknown = sorted(set(named) - criteria) 

115 if unknown: 115 ↛ 116line 115 didn't jump to line 116 because the condition on line 115 was never true

116 raise ValueError(f"sub-task {index} names unknown criteria: {', '.join(unknown)}") 

117 constraints = [str(item) for item in entry.get("constraints") or [] if str(item).strip()] 

118 return SubTask( 

119 title[:300], tuple(str(r) for r in requirements), tuple(named), tuple(constraints) 

120 ) 

121 

122 

123def _claim(index: int, requirements: list[Any], known: list[str], seen: dict[str, int]) -> None: 

124 """Assign the requirements to sub-task ``index``: each one known and in no other.""" 

125 for requirement in requirements: 

126 if requirement not in known: 126 ↛ 127line 126 didn't jump to line 127 because the condition on line 126 was never true

127 raise ValueError(f"sub-task {index} names an unknown requirement {requirement!r}") 

128 if requirement in seen: 128 ↛ 129line 128 didn't jump to line 129 because the condition on line 128 was never true

129 raise ValueError( 

130 f"requirement {requirement} is in sub-tasks {seen[requirement]} and {index}" 

131 ) 

132 seen[requirement] = index 

133 

134 

135class Decomposition: 

136 def __init__(self, results: ResultsHost) -> None: 

137 self.results = results 

138 

139 @property 

140 def config(self) -> Any: 

141 return self.results.project.planning 

142 

143 @property 

144 def enabled(self) -> bool: 

145 return bool(self.config and self.config.enabled) 

146 

147 def _key(self, execution: Execution) -> str: 

148 return f"decomposition:{execution.execution_id}" 

149 

150 def state(self, execution: Execution) -> dict[str, Any] | None: 

151 value = self.results.flag_json(self._key(execution)) 

152 return value if isinstance(value, dict) else None 

153 

154 def approved(self, execution: Execution) -> list[SubTask] | None: 

155 state = self.state(execution) 

156 if not state or state.get("status") != "APPROVED": 

157 return None 

158 return [ 

159 SubTask( 

160 item["title"], 

161 tuple(item["requirements"]), 

162 tuple(item["criteria"]), 

163 tuple(item["constraints"]), 

164 ) 

165 for item in state["subtasks"] 

166 ] 

167 

168 def index(self, execution: Execution) -> int: 

169 return int(self.results.s.state.get_flag(f"subtask:{execution.execution_id}") or 0) 

170 

171 # ----- PLANNING ------------------------------------------------------------------------ 

172 def _coarse(self, execution: Execution, task: Task) -> bool: 

173 """Whether adaptive granularity lets the implementing model start with the whole task.""" 

174 config = self.config 

175 if config.granularity != "adaptive": 

176 return False 

177 if self.results.s.state.get_flag(f"replan:{execution.execution_id}"): 177 ↛ 178line 177 didn't jump to line 178 because the condition on line 177 was never true

178 return False 

179 model = self.results.implement_model(execution, task) 

180 coarse = config.coarse_models if config.coarse_models is not None else DEFAULT_COARSE_MODELS 

181 return bool(model) and model in coarse 

182 

183 def plan(self, execution: Execution, phase: PhaseExecution, task: Task) -> PhaseOutcome | None: 

184 """Request, validate and hold for approval the decomposition of a large task.""" 

185 if not self.enabled: 

186 return None 

187 results = self.results 

188 replan = bool(results.s.state.get_flag(f"replan:{execution.execution_id}")) 

189 threshold = self.config.requirement_threshold 

190 size = len(task.requirements) 

191 state = self.state(execution) 

192 digest = task_digest(task) 

193 if state and state.get("taskDigest") == digest: 

194 if state["status"] == "APPROVED": 

195 return None 

196 if state["status"] == "REJECTED": 196 ↛ 198line 196 didn't jump to line 198 because the condition on line 196 was always true

197 return None 

198 return PhaseOutcome( 

199 ResultStatus.BLOCKED, 

200 f"The decomposition into {len(state['subtasks'])} sub-task(s) waits for a " 

201 f"person: harness plan decide --run {execution.execution_id} --decision " 

202 f"APPROVE --digest {state['digest']}", 

203 (state["ref"],), 

204 ) 

205 if size < 2 or (size <= threshold and not replan): 

206 return None 

207 if not replan and self._coarse(execution, task): 

208 results.s.events.append( 

209 execution.execution_id, 

210 "planning.decomposition.deferred", 

211 {"requirements": size, "threshold": threshold, "reason": "coarse model first"}, 

212 ) 

213 return None 

214 return self._propose(execution, phase, task, digest, threshold, replan) 

215 

216 def _propose( 

217 self, 

218 execution: Execution, 

219 phase: PhaseExecution, 

220 task: Task, 

221 digest: str, 

222 threshold: int, 

223 replan: bool, 

224 ) -> PhaseOutcome: 

225 """Ask the planner for the decomposition, validate it and hold it for a person.""" 

226 results = self.results 

227 max_subtasks = self.config.max_subtasks or DEFAULT_MAX_SUBTASKS 

228 outcome = results.call_agent( 

229 execution, 

230 phase, 

231 "plan", 

232 {"threshold": threshold, "maxSubtasks": max_subtasks, "replan": replan}, 

233 task=task, 

234 instruction_values={"maxSubtasks": max_subtasks}, 

235 validate=lambda result: validate_plan(task, result, max_subtasks), 

236 ) 

237 if outcome.status is not ResultStatus.PASSED or outcome.result is None: 

238 return PhaseOutcome( 

239 ResultStatus.BLOCKED, 

240 f"The planning call did not answer ({outcome.status}): {outcome.summary}", 

241 outcome.evidence_refs, 

242 ) 

243 try: 

244 subtasks = validate_plan(task, outcome.result, max_subtasks) 

245 except ValueError as error: 

246 results.record_finding( 

247 execution, 

248 validator_id="planning.decomposition", 

249 rule_id=MALFORMED_RULE, 

250 category="planning", 

251 severity=FindingSeverity.HIGH, 

252 message=f"The proposed decomposition is not valid: {error}", 

253 evidence_refs=outcome.evidence_refs, 

254 recommendation="Fix the planner's answer and continue the run.", 

255 ) 

256 return PhaseOutcome( 

257 ResultStatus.BLOCKED, 

258 f"The proposed decomposition is not valid: {error}", 

259 outcome.evidence_refs, 

260 ) 

261 plan_digest = sha256_json( 

262 {"taskDigest": digest, "subtasks": [item.as_dict() for item in subtasks]} 

263 ) 

264 record = { 

265 "taskDigest": digest, 

266 "digest": plan_digest, 

267 "status": "PROPOSED", 

268 "subtasks": [item.as_dict() for item in subtasks], 

269 "invocationId": outcome.invocation_id, 

270 "replan": replan, 

271 } 

272 ref = results.record_json( 

273 execution, 

274 PhaseId.PLANNING, 

275 record, 

276 kind="decomposition-plan", 

277 summary=f"Proposed decomposition into {len(subtasks)} sub-task(s)", 

278 supports=tuple(item.requirement_id for item in task.requirements), 

279 ) 

280 results.set_flag_json(self._key(execution), {**record, "ref": ref}) 

281 results.s.events.append( 

282 execution.execution_id, 

283 "planning.decomposition.proposed", 

284 {"digest": plan_digest, "subtasks": len(subtasks), "evidenceRef": ref}, 

285 phase_execution_id=phase.phase_execution_id, 

286 ) 

287 return PhaseOutcome( 

288 ResultStatus.BLOCKED, 

289 f"The decomposition into {len(subtasks)} sub-task(s) waits for a person: harness " 

290 f"plan decide --run {execution.execution_id} --decision APPROVE --digest " 

291 f"{plan_digest}", 

292 (ref,), 

293 ) 

294 

295 def decide( 

296 self, 

297 execution: Execution, 

298 *, 

299 decision: DecisionKind, 

300 digest: str, 

301 actor: Actor, 

302 rationale: str, 

303 ) -> dict[str, Any]: 

304 """A person's approval or rejection of the proposed plan, bound to its digest.""" 

305 if actor.actor_type is not ActorType.HUMAN: 305 ↛ 306line 305 didn't jump to line 306 because the condition on line 305 was never true

306 raise PolicyViolationError("only a person can decide a decomposition plan") 

307 if decision not in {DecisionKind.APPROVE, DecisionKind.REJECT}: 307 ↛ 308line 307 didn't jump to line 308 because the condition on line 307 was never true

308 raise PolicyViolationError("a decomposition plan is approved or rejected") 

309 state = self.state(execution) 

310 if not state or state.get("status") != "PROPOSED": 310 ↛ 311line 310 didn't jump to line 311 because the condition on line 310 was never true

311 raise NotFoundError(f"run {execution.execution_id} has no proposed decomposition") 

312 if state["digest"] != digest: 

313 raise PolicyViolationError( 

314 "the digest does not match the proposed decomposition; the plan may have changed" 

315 ) 

316 status = "APPROVED" if decision is DecisionKind.APPROVE else "REJECTED" 

317 state = {**state, "status": status, "decidedBy": actor.actor_id, "rationale": rationale} 

318 self.results.set_flag_json(self._key(execution), state) 

319 if status == "APPROVED": 

320 self.results.s.state.set_flag(f"decomposed:{execution.execution_id}", "1") 

321 self.results.s.state.set_flag(f"subtask:{execution.execution_id}", "0") 

322 self.results.s.events.append( 

323 execution.execution_id, 

324 "planning.decomposition.decided", 

325 {"decision": decision.value, "digest": digest, "rationale": rationale}, 

326 actor=actor, 

327 ) 

328 return state 

329 

330 def plan_steps(self, execution: Execution) -> tuple[PlanStep, ...]: 

331 subtasks = self.approved(execution) or [] 

332 return tuple( 

333 PlanStep( 

334 step_id=new_id("step"), 

335 description=( 

336 f"Sub-task {number} of {len(subtasks)}: {item.title} " 

337 f"(requirements {', '.join(item.requirements)})" 

338 ), 

339 capabilities=("filesystem.read", "filesystem.write", "process.execute"), 

340 expected_evidence=("agent invocation", "ChangeSet", f"gate subtask-{number}"), 

341 ) 

342 for number, item in enumerate(subtasks, start=1) 

343 ) 

344 

345 # ----- IMPLEMENTATION and VERIFICATION ------------------------------------------------- 

346 def subtask_task(self, execution: Execution, task: Task) -> Task: 

347 """The task an implement call of a decomposed run receives: the current sub-task's 

348 requirements, criteria and constraints plus the task's own constraints.""" 

349 subtasks = self.approved(execution) 

350 if not subtasks: 

351 return task 

352 index = self.index(execution) 

353 if index >= len(subtasks): 353 ↛ 355line 353 didn't jump to line 355 because the condition on line 353 was never true

354 # Every sub-task passed: a correction after DECISION addresses the whole task. 

355 return task 

356 item = subtasks[index] 

357 if index == 0 or not self._started(execution, index): 

358 self._start(execution, index, item, len(subtasks)) 

359 criteria = [c for c in task.acceptance_criteria if c.criterion_id in item.criteria] 

360 if not criteria: 

361 criteria = [ 

362 AcceptanceCriterion( 

363 criterion_id=f"subtask-{index + 1}", 

364 text=( 

365 f"Requirements {', '.join(item.requirements)} are implemented and the " 

366 "tests of the earlier sub-tasks still pass." 

367 ), 

368 ) 

369 ] 

370 wanted = set(item.requirements) 

371 return task.model_copy( 

372 update={ 

373 "title": f"{task.title} - sub-task {index + 1} of {len(subtasks)}: {item.title}"[ 

374 :300 

375 ], 

376 "requirements": tuple(r for r in task.requirements if r.requirement_id in wanted), 

377 "acceptance_criteria": tuple(criteria), 

378 "constraints": tuple(dict.fromkeys((*task.constraints, *item.constraints))), 

379 "metadata": { 

380 **task.metadata, 

381 "subtask": { 

382 "index": index + 1, 

383 "count": len(subtasks), 

384 "parentTaskId": task.task_id, 

385 }, 

386 }, 

387 } 

388 ) 

389 

390 def verification_task(self, execution: Execution, task: Task) -> Task: 

391 """Under decomposition, the requirements of the sub-tasks implemented so far (what a 

392 sub-task's VERIFICATION can expect tests for).""" 

393 subtasks = self.approved(execution) 

394 if not subtasks: 

395 return task 

396 done = { 

397 requirement 

398 for item in subtasks[: self.index(execution) + 1] 

399 for requirement in item.requirements 

400 } 

401 return task.model_copy( 

402 update={"requirements": tuple(r for r in task.requirements if r.requirement_id in done)} 

403 ) 

404 

405 def _started(self, execution: Execution, index: int) -> bool: 

406 return any( 

407 event.event_type == _SUBTASK_STARTED and event.payload.get("index") == index + 1 

408 for event in self.results.s.events.list(execution.execution_id) 

409 ) 

410 

411 def _start(self, execution: Execution, index: int, item: SubTask, count: int) -> None: 

412 if self._started(execution, index): 412 ↛ 413line 412 didn't jump to line 413 because the condition on line 412 was never true

413 return 

414 self.results.s.events.append( 

415 execution.execution_id, 

416 _SUBTASK_STARTED, 

417 {"index": index + 1, "count": count, **item.as_dict()}, 

418 ) 

419 

420 def budget_start(self, events: list[StoredEvent]) -> int: 

421 """Position after which a sub-task's corrections are counted (0 without decomposition).""" 

422 start = 0 

423 for position, event in enumerate(events): 

424 if event.event_type == _SUBTASK_STARTED: 

425 start = position 

426 return start 

427 

428 def after_passed_verification(self, execution: Execution) -> bool: 

429 """Evaluate the finished sub-task's gate; hand the workspace to the next sub-task.""" 

430 subtasks = self.approved(execution) 

431 if not subtasks: 

432 return False 

433 results = self.results 

434 engine = results.engine 

435 execution = engine.get_execution(execution.execution_id) 

436 index = self.index(execution) 

437 if index >= len(subtasks): 437 ↛ 438line 437 didn't jump to line 438 because the condition on line 437 was never true

438 return False 

439 digest = execution.change_set_digest or "" 

440 validations: list[ValidationResult] = engine._latest_validations( 

441 execution.execution_id, digest 

442 ) 

443 ids = {finding_id for item in validations for finding_id in item.finding_ids} 

444 findings = [ 

445 item 

446 for item in results.s.state.list( 

447 "finding", Finding, execution_id=execution.execution_id 

448 ) 

449 if item.finding_id in ids 

450 ] 

451 names = results.s.resolved.effective_policies.get( 

452 "findingBlockSeverities", ["HIGH", "CRITICAL"] 

453 ) 

454 gate = engine.gate_engine.evaluate( 

455 execution_id=execution.execution_id, 

456 gate_id=f"subtask-{index + 1}", 

457 change_set_digest=digest, 

458 policy_digest=execution.policy_digest, 

459 validations=validations, 

460 findings=findings, 

461 policy=GatePolicy( 

462 require_human_decision=False, 

463 blocking_severities=tuple(FindingSeverity(str(name)) for name in names), 

464 ), 

465 provenance=engine._provenance(execution), 

466 ) 

467 status = getattr(gate, "status", ResultStatus.ERROR) 

468 results.s.events.append( 

469 execution.execution_id, 

470 "subtask.completed", 

471 { 

472 "index": index + 1, 

473 "count": len(subtasks), 

474 "title": subtasks[index].title, 

475 "requirements": list(subtasks[index].requirements), 

476 "changeSetDigest": digest, 

477 "gateStatus": status, 

478 "reasonCodes": list(getattr(gate, "reason_codes", ())), 

479 }, 

480 ) 

481 if status is not ResultStatus.PASSED: 481 ↛ 482line 481 didn't jump to line 482 because the condition on line 481 was never true

482 engine._save_execution( 

483 execution.model_copy( 

484 update={ 

485 "status": ResultStatus.FAILED, 

486 "current_phase": PhaseId.VERIFICATION, 

487 "terminal_reason": ( 

488 f"Sub-task {index + 1} did not pass its gate ({status}); the " 

489 "sub-tasks after it do not start" 

490 ), 

491 "updated_at": utc_now(), 

492 } 

493 ) 

494 ) 

495 return False 

496 if index + 1 >= len(subtasks): 

497 results.s.state.set_flag(f"subtask:{execution.execution_id}", str(index + 1)) 

498 return False 

499 results.s.state.set_flag(f"subtask:{execution.execution_id}", str(index + 1)) 

500 transition = engine.state_machine.authorize_next_subtask(PhaseId.VERIFICATION) 

501 engine._save_execution( 

502 execution.model_copy( 

503 update={ 

504 "status": ResultStatus.PENDING, 

505 "current_phase": transition.target, 

506 "gate_evaluation_id": None, 

507 "human_decision_id": None, 

508 "updated_at": utc_now(), 

509 } 

510 ) 

511 ) 

512 self._start(execution, index + 1, subtasks[index + 1], len(subtasks)) 

513 return True 

514 

515 def replan_after_failure(self, execution: Execution) -> bool: 

516 """Adaptive granularity: a coarse attempt whose corrections are exhausted returns to 

517 PLANNING to be decomposed (once). Only the attempt of a model listed in 

518 ``planning.coarseModels`` is coarse (#77): another model's failure stops the run, it is 

519 not sent back to PLANNING.""" 

520 if not self.enabled or self.config.granularity != "adaptive": 

521 return False 

522 results = self.results 

523 if results.s.state.get_flag(f"replan:{execution.execution_id}") or self.approved(execution): 523 ↛ 524line 523 didn't jump to line 524 because the condition on line 523 was never true

524 return False 

525 task = results.engine.run_task(execution) 

526 if len(task.requirements) < 2 or not self._coarse(execution, task): 

527 return False 

528 results.s.state.set_flag(f"replan:{execution.execution_id}", "1") 

529 results.s.state.set_flag(self._key(execution), "") 

530 transition = results.engine.state_machine.authorize_replanning(PhaseId.VERIFICATION) 

531 latest = results.engine.get_execution(execution.execution_id) 

532 results.engine._save_execution( 

533 latest.model_copy( 

534 update={ 

535 "status": ResultStatus.PENDING, 

536 "current_phase": transition.target, 

537 "gate_evaluation_id": None, 

538 "human_decision_id": None, 

539 "terminal_reason": None, 

540 "updated_at": utc_now(), 

541 } 

542 ) 

543 ) 

544 results.s.events.append( 

545 execution.execution_id, 

546 "planning.split-on-failure", 

547 {"requirements": len(task.requirements)}, 

548 ) 

549 return True