forked from HAL9000/cleveragents-core
CoreRasurae
116 lines
3.8 KiB
Markdown
116 lines
3.8 KiB
Markdown
# 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` | Optional regex pattern for evaluation |
|
|
|
|
### `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:
|
|
|
|
```python
|
|
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:
|
|
|
|
```python
|
|
{
|
|
"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.
|