From 3e1e47a6a2159f344e36fabe3b99b5ba95832e44 Mon Sep 17 00:00:00 2001 From: CleverAgents Bot Date: Sun, 12 Apr 2026 19:28:21 +0000 Subject: [PATCH] docs(reference): document empty-run guard for ApplyValidationSummary (PR #7786) - Add empty-run guard section to ApplyValidationSummary explaining that all_required_passed now returns False when is_empty is True - Add required_total property to the properties list - Add is_empty column to ValidationSummary model table - Include behaviour table showing all three gate outcomes - Document why the guard matters (silent bypass of apply gate) Closes #7508 documentation gap. --- docs/reference/validation_pipeline.md | 31 +++++++++++++++++++++++++-- 1 file changed, 29 insertions(+), 2 deletions(-) diff --git a/docs/reference/validation_pipeline.md b/docs/reference/validation_pipeline.md index eaacc5613..9980b05de 100644 --- a/docs/reference/validation_pipeline.md +++ b/docs/reference/validation_pipeline.md @@ -145,7 +145,8 @@ results without re-running the pipeline. | `informational_passed` | `int` | Informational passes | | `informational_failed` | `int` | Informational failures | | `results` | `list[ValidationResult]`| All results | -| `all_required_passed` | `bool` (property) | True if no req. failures | +| `all_required_passed` | `bool` (property) | `False` if any required failures **or** if no validations ran (empty-run guard, v3.2.0) | +| `is_empty` | `bool` (property) | `True` when result set is empty (zero validations executed) | --- @@ -218,12 +219,38 @@ Aggregated results with gating decision. **Properties:** `total`, `required_passed`, `required_failed`, `informational_passed`, `informational_failed`, `all_required_passed`, -`is_empty` +`is_empty`, `required_total` **Methods:** - `to_plan_metadata()` — Dict for plan `validation_summary` field - `format_cli_output()` — Human-readable summary for CLI display +#### Empty-Run Guard (v3.2.0, PR #7786) + +!!! warning "Breaking behaviour change" + Prior to v3.2.0, `all_required_passed` returned `True` when zero + validations were run, silently bypassing the apply gate. + +`all_required_passed` now returns `False` when `is_empty` is `True` +(i.e. the result set is empty — no validations were executed at all). +This ensures that apply is **blocked** unless at least one validation +was actually run. + +| Condition | `is_empty` | `all_required_passed` | Apply | +|-----------|-----------|----------------------|-------| +| No validations run | `True` | `False` | **Blocked** | +| All required pass | `False` | `True` | Allowed | +| Any required fails | `False` | `False` | **Blocked** | + +The `required_total` property (`required_passed + required_failed`) is +also available for display and diagnostic purposes. + +**Why this matters:** Plans with no attached validations (e.g. plans +created before validations were configured, or plans on resources with +no validation rules) previously proceeded to apply without any gate +check. The empty-run guard ensures that the gate is always meaningful — +if no validations ran, the plan must be explicitly reviewed before apply. + ## Runner Interface ### `ValidationRunner` (ABC) -- 2.52.0