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