Move generic step infrastructure into IdLE.Core and keep IdLE.Steps.Common as step implementations

[blindzero]

Problem Statement

IdLE.Steps.Common currently bundles two different concerns:

1. Generic step infrastructure (shared step types/contracts/registration/metadata & helpers that all step packs rely on)
2. Generic step implementations (actual “common steps”)

This makes the dependency graph less clear and makes it harder to reason about which parts are engine foundations vs. step library implementations.

We want a clearer layering where all step packs (including third-party) are expected to rely on IdLE.Core as the foundational layer, and IdLE.Steps.Common becomes a pure library of reusable step implementations.

Target date: 2026-01-31

Proposed Solution

Refactor the modules so that all generic step foundations live in IdLE.Core, while IdLE.Steps.Common contains only step implementations.

Goals

• IdLE.Core becomes the single foundational dependency for:
  • step definitions / base types / generic helpers required by steps at runtime
  • step registration/discovery (metadata catalog) if it is part of orchestration
  • any step execution contracts used by the engine
• IdLE.Steps.Common becomes pure step implementations (e.g., Ensure*, Disable*, etc.)
• First-party step packs (e.g., IdLE.Steps.Mailbox, IdLE.Steps.DirectorySync) depend on:
  • IdLE.Core (always)
  • IdLE.Steps.Common only when they reuse/extend common step implementations

Scope of changes (high level)

1. Identify all “generic step foundation” components currently in IdLE.Steps.Common:
   • contracts / types
   • metadata/registration mechanisms
   • shared runtime helpers used by step packs
2. Move these components into IdLE.Core:
   • preserve public surface area as much as possible
   • or provide compatibility shims if needed (pre-1.0: breaking changes are acceptable but must be explicit)
3. Adjust all first-party step packs to reference the new locations.
4. Ensure the engine/plan builder continues to discover and execute step types correctly.
5. Update documentation and examples to reflect the new layering.

Acceptance criteria

• IdLE.Steps.Common contains only step implementations (no foundational step contracts/registry).
• All first-party step packs run successfully with IdLE.Core providing the foundational step infrastructure.
• Tests pass (unit tests for step discovery/registration + any contract tests affected).
• Documentation clearly states:
  • “Step packs require IdLE.Core”
  • “IdLE.Steps.Common is optional and provides reusable step implementations”

Implementation checklist (agent-ready)

• Inventory: list each file/type/function moving from IdLE.Steps.Common to IdLE.Core and why
• Move/refactor code with a clear public/private structure
• Update module manifests (exports and RequiredModules as applicable)
• Update step discovery/registration paths
• Update examples and docs (single source of truth; other docs reference it)
• Add/adjust Pester tests covering:
  - step registration/discovery
  - execution of at least one step from IdLE.Steps.Common and one from another pack
• Add release notes entry describing the behavior change (breaking if applicable)

Alternatives Considered

• Split IdLE.Steps.Common into IdLE.Steps.Abstractions + IdLE.Steps.Common instead of moving abstractions into Core.
  • Rejected for now: we want the foundational dependency for all steps to be IdLE.Core and avoid introducing additional foundational modules unless necessary.
• Keep current structure.
  • Rejected: the mixed responsibilities make the layering unclear and complicate future scaling with many step packs.

Impact

• Potential breaking change (pre-1.0 acceptable):
  • Step packs may need updated imports/RequiredModules or updated type/function references after the move.
• Documentation and examples must be updated accordingly.
• May require updates to any third-party steps that depended on internals of IdLE.Steps.Common.

Additional Context

• Design decision: third-party steps are expected to rely on IdLE.Core (engine foundations).
• IdLE.Steps.Common should remain a reusable step implementation library, not a foundational layer.