Add runtime preconditions (read-only execution guards) with Blocked, Fail, and Continue behavior

[Copilot]

• All precondition schema, runtime, and OnFailureSteps changes complete
• Remove broken ../reference/specs/conditions.md link from docs/use/preconditions.md (file does not exist)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Runtime Preconditions (read-only guards) with Blocked stop behavior</issue_title>
<issue_description>## Problem Statement

IdLE evaluates Condition only during plan creation. The plan is then executed 1:1. This makes planning deterministic, but it introduces a safety gap when time passes between plan and execution:

• External state can change (e.g., group membership / entitlements / device state).
• A plan that was correct at planning time may be unsafe or invalid at execution time.
• For safety/policy scenarios we must prevent execution from performing an action if the current (live) state violates a precondition.

Concrete example (BYOD policy):

• If the user is currently in a BYOD group (Android/iOS), company data must be wiped/retired in Intune before disabling the identity.
• If the plan was created earlier and the user later enters/leaves those groups, a plan-only condition can become stale and either:
  • incorrectly allow disablement (policy violation), or
  • incorrectly block disablement (unnecessary stop).

We need a generic, read-only, runtime mechanism to guard execution with “fail fast” behavior without introducing side effects or turning IdLE into an interactive system.

Related / Dependencies

This issue intentionally does not define request schema naming or planning-time context enrichment. It assumes those are handled by separate issues:

• Issue (Schema): Separate Request.Intent from Request.Context (rename DesiredState, forbid Request.Identity)
• Issue (Snapshot): Plan snapshot/export contract for Request.Intent and Request.Context (auditability + safety)
• Issue (Planning Context): Planning-time ContextResolvers (read-only) using provider capabilities to populate Request.Context

Runtime Preconditions may use:

• live provider queries (preferred for safety), and/or
• Request.Context when available.

Proposed Solution

Introduce Runtime Preconditions (read-only execution guards) that are evaluated during execution immediately before running a step.

High-level concept

• Keep existing Condition semantics as planning-time (deterministic plan building).
• Add an optional Preconditions capability per step that is evaluated at execution time (online evaluation).
• Preconditions are read-only checks, allowed to query providers (live state), but must not change state.
• If a precondition fails, the engine must stop execution in a controlled manner and surface a Blocked outcome (not a generic failure), optionally emitting a structured event payload for hosts.

Workflow schema (proposal)

Add optional properties to step definitions:

• Preconditions: list of preconditions to evaluate at execution time (read-only).
• OnPreconditionFalse: Blocked | Fail (default: Blocked if Preconditions exists; otherwise N/A).
• PreconditionEvent: optional structured object that is emitted when precondition fails, e.g.:
  • Type (e.g., ManualActionRequired)
  • Message
  • Data (key-value payload, safe for logs)

Notes:

• This issue does not require choosing the final schema names yet, but implementation MUST include an explicit, documented and testable structure.

Engine behavior

Plan creation remains unchanged:

• Evaluate Condition during planning and set step Status accordingly.

Execution phase:

• For each step with Status == Planned (or equivalent), evaluate Preconditions before invoking the step action.
• If all pass, invoke step action as usual.
• If any fails:
  • If OnPreconditionFalse == Blocked: mark step outcome as Blocked and stop the plan execution (do not continue to subsequent steps).
  • If OnPreconditionFalse == Fail: mark step outcome as Failed and stop, running existing failure semantics as appropriate.
  • Emit PreconditionEvent as a structured engine event (if provided).

Minimal API surface

• Add a new step-result/outcome classification: Blocked.
• Add execution logic that stops the run when a step becomes Blocked (or Failed), with predictable return objects/events.
• Keep compatibility: steps without Preconditions behave exactly as before.

Semantics: Blocked vs Failed

Blocked is not a “technical failure”. It represents a policy / precondition gate and is intended to support human-in-the-loop or external dependency resolution.

Required clarifications/behavior:

• Blocked MUST stop execution immediately (no subsequent steps).
• Blocked MUST be distinguishable from Failed in the returned plan execution result.
• Failure handlers (e.g., “on failure” steps / compensation) MUST NOT run for Blocked by default.
  • If IdLE supports configurable failure handling, document how Blocked is treated.
• Failed remains reserved for genuine errors (provider failure, unexpected exception, etc.) and continues to follow existing failure seman...

• Fixes Runtime Preconditions (read-only guards) with Blocked stop behavior #210

---

🔒 GitHub Advanced Security automatically protects Copilot coding agent pull requests. You can protect all pull requests by enabling Advanced Security for your repositories. Learn more about Advanced Security.

[blindzero]

@copilot make sure that precondition should also have some continue Mode to emmit an event but continue, as before

[Copilot]

@copilot make sure that precondition should also have some continue Mode to emmit an event but continue, as before

Added Continue as a third OnPreconditionFalse value (commit 308be94).

When OnPreconditionFalse = 'Continue':

• Both StepPreconditionFailed and the optional PreconditionEvent are emitted (same as the other modes).
• The step is marked PreconditionSkipped in the result.
• Execution continues to subsequent steps — the overall run status remains Completed.
• OnFailureSteps are not triggered.

Blocked (default) and Fail continue to stop execution as before.

[blindzero]

@copilot make sure that the onprecondition events of Blocked or Failed also Emit events.

[Copilot]

@copilot make sure that the onprecondition events of Blocked or Failed also Emit events.

Done in commit 2f68fd2. When a precondition fails, the engine now emits outcome-specific events in addition to the existing StepPreconditionFailed:

• OnPreconditionFalse=Blocked → emits StepBlocked (with StepType and Index)
• OnPreconditionFalse=Fail → emits StepFailed (with StepType, Index, and Error, matching the format of regular step failure events)
• OnPreconditionFalse=Continue → no additional outcome event (step is skipped, not failed or blocked)

The StepPreconditionFailed event (with OnPreconditionFalse in its data) continues to be emitted for all three modes. Tests have been updated to assert the new events.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2f68fd2292

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Copilot]

Pull request overview

Adds runtime preconditions to IdLE step execution so plans can be guarded against stale/unsafe external state immediately before each step runs, without changing deterministic planning semantics.

Changes:

• Adds step-level Preconditions, OnPreconditionFalse (Blocked|Fail|Continue), and PreconditionEvent to the workflow schema and plan step normalization.
• Implements execution-time evaluation in Invoke-IdlePlanObject, including Blocked run status handling and adjusted OnFailureSteps gating.
• Adds Pester coverage + workflow fixtures and user/extend documentation describing semantics and emitted events.

Reviewed changes

Copilot reviewed 21 out of 21 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
website/sidebars.js	Links the new runtime preconditions documentation page in the site nav.
src/IdLE.Core/Public/Invoke-IdlePlanObject.ps1	Evaluates runtime preconditions before step dispatch; emits events; supports Blocked/Fail/Continue outcomes.
src/IdLE.Core/Private/ConvertTo-IdleWorkflowSteps.ps1	Extracts/validates new step fields and persists them onto IdLE.PlanStep.
src/IdLE.Core/Private/Test-IdleWorkflowSchema.ps1	Adds schema validation for the new step keys for both Steps and OnFailureSteps.
docs/use/workflows.md	Documents execution-control properties and links to runtime preconditions.
docs/use/preconditions.md	New documentation page describing schema, DSL roots, semantics, and events.
docs/extend/steps.md	Documents Blocked as a first-class outcome and its runtime-precondition semantics.
tests/Core/Invoke-IdlePlan.Preconditions.Tests.ps1	Adds Pester tests covering Blocked/Fail/Continue behavior, event emission, and schema failures.
tests/fixtures/workflows/preconditions/*.psd1	Adds workflow fixtures for the new behaviors and schema validation cases.

[github-actions]

Code Coverage Report

Overall Project	73.21%	🍏

There is no coverage information present for the Files changed