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
« 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).
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.
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.
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."""
23from __future__ import annotations
25from dataclasses import dataclass
26from typing import TYPE_CHECKING, Any
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
54if TYPE_CHECKING:
55 from governed_harness.events.sqlite_store import StoredEvent
56 from governed_harness.orchestration.hosts import ResultsHost
58MALFORMED_RULE = "planning.plan-malformed"
59DEFAULT_MAX_SUBTASKS = 12
60_SUBTASK_STARTED = "subtask.started"
63@dataclass(frozen=True)
64class SubTask:
65 title: str
66 requirements: tuple[str, ...]
67 criteria: tuple[str, ...]
68 constraints: tuple[str, ...]
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 }
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
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 )
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
135class Decomposition:
136 def __init__(self, results: ResultsHost) -> None:
137 self.results = results
139 @property
140 def config(self) -> Any:
141 return self.results.project.planning
143 @property
144 def enabled(self) -> bool:
145 return bool(self.config and self.config.enabled)
147 def _key(self, execution: Execution) -> str:
148 return f"decomposition:{execution.execution_id}"
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
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 ]
168 def index(self, execution: Execution) -> int:
169 return int(self.results.s.state.get_flag(f"subtask:{execution.execution_id}") or 0)
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
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)
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 )
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
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 )
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 )
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 )
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 )
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 )
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
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
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