cleveragents-core/docs/reference/definition_of_done.md

Definition-of-Done Gating

Overview

The definition-of-done (DoD) subsystem enforces completion criteria before a plan is permitted to apply changes. Each plan may carry a definition_of_done text field listing testable criteria that must be satisfied before the apply phase proceeds.

Domain Models

DoDStatus

A StrEnum with three values:

Value	Meaning
passed	Criterion was met
failed	Criterion was not met
skipped	Criterion could not be evaluated

DoDCriterion

A single testable criterion parsed from DoD text.

Field	Type	Description
index	int	Zero-based position in the DoD list
text	str	Human-readable criterion text
pattern	`str	None`

DoDResult

Evaluation result for a single criterion.

Field	Type	Description
criterion	DoDCriterion	The evaluated criterion
status	DoDStatus	Pass/fail/skip result
reasoning	str	Explanation for the evaluation

DoDSummary

Aggregated evaluation results for all criteria in a plan.

Field	Type	Description
plan_id	str	Plan ULID
definition_of_done	str	Original DoD text
results	list[DoDResult]	Per-criterion results
evaluated_at	datetime	Evaluation timestamp

Properties: total, passed, failed, skipped, all_passed, is_empty

Methods:

• to_cli_dict() — Dictionary for CLI display
• to_validation_summary() — Dict compatible with plan validation_summary

Functions

parse_dod_criteria(definition_of_done: str) -> list[DoDCriterion]

Parses DoD text into individual criteria. Supports:

• Plain text (one criterion per line)
• Bullet points (- or * prefix)
• Numbered lists (1., 2. prefix)
• Empty/whitespace-only input returns empty list

render_dod_template(template: str, arguments: dict) -> str

Substitutes {placeholder} markers in a DoD template with values from the arguments dict. Unmatched placeholders are preserved as-is.

Evaluator Interface

DoDEvaluator (ABC)

Abstract base class for DoD evaluation. Implementations must provide:

def evaluate(
    self,
    criteria: list[DoDCriterion],
    context: dict[str, Any],
) -> list[DoDResult]: ...

TextMatchEvaluator

Default evaluator using text/regex matching:

• If a criterion has a pattern, uses regex matching against context values
• Otherwise, checks if criterion text appears in any context key or value
• Empty context causes all criteria to be marked SKIPPED
• Invalid regex patterns result in FAILED status with error reasoning

Integration with Plan Lifecycle

The DoD evaluation result feeds into the plan's validation_summary via DoDSummary.to_validation_summary(), which produces a dict compatible with the existing validation gate format:

{
    "total": 3,
    "required_passed": 2,
    "required_failed": 1,
    "informational_passed": 0,
    "informational_failed": 0,
    "dod_evaluated": True,
    "dod_all_passed": False,
}

When dod_all_passed is False, the apply phase is blocked.