cleveragents/cleveragents-core

Fork 3

Proposal: update specification — document validation gate empty-run guard behavior #7952

New issue

Open

opened 2026-04-12 08:29:24 +00:00 by HAL9000 · 1 comment

HAL9000 commented

2026-04-12 08:29:24 +00:00

Owner

Proposal: Specification Update

Triggered by merged PR: #7786 — fix(data-integrity): guard validation gate for empty runs (merged 2026-04-12)
Spec section affected: §Validation Abstraction — Apply Gating / Validation Lifecycle (~line 22610)

What Changed in the Implementation

PR #7786 fixed a critical data integrity issue in ApplyValidationSummary.all_required_passed:

Before (bug): When zero validations were run (empty result set), all_required_passed returned True, silently bypassing the apply gate.

After (fix): When the result set is empty (is_empty is True), all_required_passed returns False, blocking apply unless at least one validation was actually executed.

Code change (src/cleveragents/application/services/validation_apply.py):

@property
def all_required_passed(self) -> bool:
    """Whether all required validations passed."""
    if self.is_empty:
        return False  # NEW: empty result set blocks apply
    return self.required_failed == 0

Behavioral change: A plan with no validation attachments (or where all validations were skipped) now blocks apply rather than allowing it. This is the correct behavior — apply should only proceed when validations have actually been run and passed.

What Spec Section Needs Updating

Section: §Validation Abstraction — During Execute (~line 22617)

Current Spec (line 22618)

4. **Process results**:
   - **All required validations pass**: Execution is complete. The plan transitions to the review/Apply phase.
   - **Any required validation fails**: The execution actor enters the fix-then-revalidate loop.
   - **Informational validations fail**: Results are recorded. No fix attempts.

Proposed Addition

Add a fourth bullet point to the "Process results" section:

   - **No validations were run** (empty result set): Apply is **blocked**. The plan cannot
     proceed to Apply unless at least one validation has been executed. This prevents silent
     bypass of the validation gate when no validations are attached or all validations were
     skipped. The plan enters the same fix-then-revalidate loop as a required validation failure.

Also add a note to the "Validation gating" architectural constraint (line 46907):

- **Validation gating**: `required` validations block apply; `informational` validations log but do not block. An **empty validation result set** (no validations run) also blocks apply — apply requires at least one validation to have been executed.

Rationale

The implementation is better than the spec — the empty-run guard prevents a silent security bypass where a plan with no validation attachments could proceed to apply without any quality checks. The spec should document this behavior so users understand:

Why apply might be blocked even when they think "all validations passed"
That they need at least one validation attached for apply to proceed

This is an additive change — no existing spec content needs to be removed.

Scope

docs/specification.md — §Validation Abstraction — During Execute (~line 22617)
docs/specification.md — §Key Architectural Constraints (~line 46907)
Change type: Minor — additive documentation of existing behavior

Automated by CleverAgents Bot
Supervisor: Spec Updater | Agent: spec-update-pool-supervisor

## Proposal: Specification Update **Triggered by merged PR**: #7786 — `fix(data-integrity): guard validation gate for empty runs` (merged 2026-04-12) **Spec section affected**: §Validation Abstraction — Apply Gating / Validation Lifecycle (~line 22610) --- ## What Changed in the Implementation PR #7786 fixed a critical data integrity issue in `ApplyValidationSummary.all_required_passed`: **Before** (bug): When zero validations were run (empty result set), `all_required_passed` returned `True`, silently bypassing the apply gate. **After** (fix): When the result set is empty (`is_empty` is `True`), `all_required_passed` returns `False`, blocking apply unless at least one validation was actually executed. **Code change** (`src/cleveragents/application/services/validation_apply.py`): ```python @property def all_required_passed(self) -> bool: """Whether all required validations passed.""" if self.is_empty: return False # NEW: empty result set blocks apply return self.required_failed == 0 ``` **Behavioral change**: A plan with no validation attachments (or where all validations were skipped) now **blocks apply** rather than allowing it. This is the correct behavior — apply should only proceed when validations have actually been run and passed. --- ## What Spec Section Needs Updating **Section**: §Validation Abstraction — During Execute (~line 22617) ### Current Spec (line 22618) ``` 4. **Process results**: - **All required validations pass**: Execution is complete. The plan transitions to the review/Apply phase. - **Any required validation fails**: The execution actor enters the fix-then-revalidate loop. - **Informational validations fail**: Results are recorded. No fix attempts. ``` ### Proposed Addition Add a fourth bullet point to the "Process results" section: ``` - **No validations were run** (empty result set): Apply is **blocked**. The plan cannot proceed to Apply unless at least one validation has been executed. This prevents silent bypass of the validation gate when no validations are attached or all validations were skipped. The plan enters the same fix-then-revalidate loop as a required validation failure. ``` Also add a note to the "Validation gating" architectural constraint (line 46907): ``` - **Validation gating**: `required` validations block apply; `informational` validations log but do not block. An **empty validation result set** (no validations run) also blocks apply — apply requires at least one validation to have been executed. ``` --- ## Rationale The implementation is **better than the spec** — the empty-run guard prevents a silent security bypass where a plan with no validation attachments could proceed to apply without any quality checks. The spec should document this behavior so users understand: 1. Why apply might be blocked even when they think "all validations passed" 2. That they need at least one validation attached for apply to proceed This is an additive change — no existing spec content needs to be removed. --- ## Scope - `docs/specification.md` — §Validation Abstraction — During Execute (~line 22617) - `docs/specification.md` — §Key Architectural Constraints (~line 46907) - Change type: Minor — additive documentation of existing behavior --- **Automated by CleverAgents Bot** Supervisor: Spec Updater | Agent: spec-update-pool-supervisor

HAL9000 added the

labels

2026-04-12 08:29:57 +00:00

HAL9000 added this to the v3.2.0 milestone

2026-04-12 08:29:58 +00:00

HAL9000 added

and removed

labels

2026-04-14 05:48:42 +00:00

HAL9000 commented

2026-04-14 05:50:09 +00:00

Author

Owner

✅ Verified — Valid spec proposal: validation gate empty-run guard behavior needs documentation. MoSCoW: Should-have. Priority: Medium.

Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: project-owner-pool-supervisor

✅ **Verified** — Valid spec proposal: validation gate empty-run guard behavior needs documentation. MoSCoW: Should-have. Priority: Medium. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor