Default to Plan.Providers when executing without explicit -Providers

[Copilot]

Implementation Plan: Invoke-IdlePlan Providers Fallback

• 1. Core implementation: Add fallback logic in Invoke-IdlePlanObject.ps1
  • Resolve effective providers at start of function (before security checks)
  • Use explicit -Providers if supplied, otherwise fall back to Plan.Providers
  • Support both IDictionary and PSCustomObject provider shapes
  • Simplify validation logic with combined condition
  • Fail early with clear error if neither is valid
  • Apply all existing security validations to effective providers
• 2. Test implementation
  • Add test for default path (Plan.Providers used when -Providers not supplied)
  • Add test for override path (-Providers overrides Plan.Providers)
  • Add test for missing providers (clear error message)
  • Add regression test (ensure "Context.Providers must be a hashtable" doesn't occur)
  • Add test for PSCustomObject provider registries
  • Update existing tests to verify both paths work (175 tests pass, 0 failed)
  • Improve test comment clarity
• 3. Documentation updates
  • Update providers.md with provider resolution section and simplified examples
  • Update quickstart.md to show simplified workflow
  • Update plan-export.md to clarify exported plan provider handling
  • Update cmdlet help in Invoke-IdlePlan.ps1 and Invoke-IdlePlanObject.ps1
  • Update example script Invoke-IdleDemo.ps1 to use simplified workflow
  • Remove references to non-existent Import-IdlePlan function
• 4. Validation
  • Run full test suite (175 passed, 0 failed, 2 skipped)
  • Verify security validations still work
  • All acceptance criteria validated

Summary

Successfully implemented provider fallback functionality with support for both hashtable and PSCustomObject provider registries, simplified validation logic, documentation corrections, and improved test clarity.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Invoke-IdlePlan should default to Plan.Providers when -Providers is not supplied</issue_title>
<issue_description>## Problem Statement

Today, executing a plan requires passing the provider registry twice:

1. During planning:
   • New-IdlePlan -Providers $providers
2. During execution:
   • Invoke-IdlePlan -Plan $plan -Providers $providers

If -Providers is omitted during Invoke-IdlePlan, steps can fail with errors like:

• Context.Providers must be a hashtable.

This is confusing and adds unnecessary boilerplate for the most common workflow:

$providers = @{
  Identity          = $providerAD
  AuthSessionBroker = $authSession
}

$plan   = New-IdlePlan -WorkflowPath .\joiner.psd1 -Request $req -Providers $providers
$result = Invoke-IdlePlan -Plan $plan   # <-- fails today unless -Providers is passed again

The expectation for a typical user is that a plan built with providers can be executed without re-supplying the same providers, unless the caller explicitly wants to override them.

Proposed Solution

Implement a deterministic fallback in the execution path:

• If Invoke-IdlePlan / Invoke-IdlePlanObject is called without -Providers (i.e., $null)
• And the plan object contains a Providers property that is a dictionary/hashtable
• Then execution must use Plan.Providers as the effective provider registry.

Override rules:

• If -Providers is supplied to Invoke-IdlePlan / Invoke-IdlePlanObject, it must take precedence over Plan.Providers.

Validation / error message rules:

• If neither -Providers nor Plan.Providers are present/valid, execution must fail early with a clear message, e.g.:
  • Providers are required. Provide -Providers to Invoke-IdlePlan or build the plan with Providers.

Security rules:

• All existing security validations must continue to apply to the effective provider registry:
  • ScriptBlocks must still be rejected (e.g., Assert-IdleNoScriptBlock).
  • Providers must still be redacted at the output boundary (no provider objects leaked in result).
• The fallback must not weaken the “host supplies auth broker” design: the effective provider registry still needs AuthSessionBroker when steps require it.

Implementation detail (explicit, agent-safe):

• Implement the fallback in IdLE.Core (not only in the thin public wrapper), so all hosts benefit.

Suggested code location:

• src/IdLE.Core/Public/Invoke-IdlePlanObject.ps1

  • Before any provider validation or use (before Assert-IdleNoScriptBlock -InputObject $Providers, before Get-IdleStepRegistry -Providers $Providers), resolve:

    1. $effectiveProviders = $Providers
    2. If $effectiveProviders -eq $null:
       • If $Plan has property Providers and it is an IDictionary / hashtable: set $effectiveProviders = $Plan.Providers
    3. Use $effectiveProviders throughout the function instead of $Providers.

• Ensure the public entrypoint src/IdLE/Public/Invoke-IdlePlan.ps1 continues to pass through -Providers as-is; no behavior changes needed there if core is fixed, but update comment-based help accordingly.

Alternatives Considered

1. Keep current behavior (status quo)

   • Pros: Explicit host injection every time.
   • Cons: Duplicated configuration, confusing UX, common user error (Context.Providers must be a hashtable.).

2. Remove -Providers from New-IdlePlan

   • Pros: No more duplication.
   • Cons: Planning would lose early validation / capability satisfaction checks and becomes less “fail-fast”.

3. Always ignore Plan.Providers and require explicit Invoke -Providers

   • Pros: Clear separation, exported plans remain pure.
   • Cons: Worse UX for the primary “build plan -> run plan” scenario.

The proposed fallback keeps the best parts of (status quo) and preserves override + export scenarios.

Impact

• User experience: Plan execution becomes simpler for the default scenario.
• Backward compatibility:
  • Existing scripts that pass -Providers to Invoke-IdlePlan are unaffected (explicit override remains).
  • Existing scripts that do not pass -Providers will now work if the plan contains Providers. This is a positive compatibility improvement.
• Plan export/import:
  • Exported plans that do not include provider objects still require explicit Invoke -Providers (unchanged).
• Security: No change intended; security checks must apply to the effective providers.

Additional Context

Documentation updates (required)

Update documentation to reflect the new default behavior and override behavior:

1. Usage docs (intro-use.md)
   • Add a “Providers resolution” section:
     • Default: Invoke-IdlePlan uses Plan.Providers when -Providers is omitted.
     • Override: passing -Providers to Invoke-IdlePlan replaces Plan.Providers.
     • Export scenario: export...

• Fixes Invoke-IdlePlan should default to Plan.Providers when -Providers is not supplied #150

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[Copilot]

Pull request overview

Implements a provider-resolution fallback so plan execution can default to Plan.Providers when Invoke-IdlePlan / Invoke-IdlePlanObject is called without an explicit -Providers, improving the common “plan then execute” workflow in IdLE.

Changes:

• Added effective-provider resolution and early “providers required” failure in Invoke-IdlePlanObject.
• Added new Pester coverage for fallback/override/error paths and updated existing ExecutionOptions validation tests to supply providers.
• Updated cmdlet help, docs, and demo script examples to reflect the simplified execution flow.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/Core/Invoke-IdlePlan.ProviderFallback.Tests.ps1	New tests covering fallback to Plan.Providers, override via -Providers, missing-provider error, security validation, and output redaction.
tests/Core/Invoke-IdlePlan.ExecutionOptions.Tests.ps1	Updates existing tests to build plans with providers so ExecutionOptions validation paths remain reachable.
src/IdLE/Public/Invoke-IdlePlan.ps1	Updates comment-based help to document provider resolution behavior and examples.
src/IdLE.Core/Public/Invoke-IdlePlanObject.ps1	Core implementation: resolves effective providers, validates, and uses them consistently (step registry, context, auth broker checks, redaction).
examples/Invoke-IdleDemo.ps1	Demo updated to execute without re-supplying providers.
docs/use/quickstart.md	Quickstart reorganized to select providers first and execute without re-supplying them.
docs/use/providers.md	Adds “Provider Resolution” section and clarifies override/export scenarios.
docs/use/plan-export.md	Updates example to build plans with providers and clarifies exported plan execution expectations.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 383117c43b

ℹ️ 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".