Add comment-based help for IdLE.Core public functions

[Copilot]

IdLE.Core public functions lacked complete comment-based help, causing Get-Help to return only auto-generated parameter signatures with no documentation.

Changes

• Added complete CBH to New-IdleLifecycleRequestObject:

  • Synopsis and description explaining core factory role, ScriptBlock validation, and hashtable cloning behavior
  • Parameter docs for all 6 parameters
  • 3 examples: minimal request, request with identity keys/desired state, mover with changes
  • Security notes covering data-only validation, AuthSessionBroker pattern, and redaction boundaries

• Added examples to 3 additional functions:

  • Invoke-IdlePlanObject: Added example showing plan execution
  • New-IdlePlanObject: Added example showing plan creation
  • Test-IdleWorkflowDefinitionObject: Added example showing workflow validation

• Added comprehensive test in tests/Core/ModuleExports.Tests.ps1 to verify CBH presence (synopsis, description, examples, and parameter documentation) for all IdLE.Core public functions

Example

Before:

PS> Get-Help New-IdleLifecycleRequestObject
NAME
    New-IdleLifecycleRequestObject
SYNTAX
    New-IdleLifecycleRequestObject [-LifecycleEvent] <string> ...

After:

PS> Get-Help New-IdleLifecycleRequestObject
NAME
    New-IdleLifecycleRequestObject
SYNOPSIS
    Creates a lifecycle request object (core factory).
DESCRIPTION
    Constructs and returns an IdleLifecycleRequest domain object representing business intent
    (e.g. Joiner/Mover/Leaver). Validates no ScriptBlocks are present in input data...
EXAMPLES
    Example 1: $request = New-IdleLifecycleRequestObject -LifecycleEvent 'Joiner'
    Example 2: $request = New-IdleLifecycleRequestObject -LifecycleEvent 'Joiner' -IdentityKeys @{ ... }
    Example 3: $request = New-IdleLifecycleRequestObject -LifecycleEvent 'Mover' -Changes @{ ... }

Testing

All 8 IdLE.Core public functions now have complete CBH and pass the comprehensive validation test that checks for synopsis, description, examples, and parameter documentation (per STYLEGUIDE.md requirements).

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Add comment-based help for New-IdleLifecycleRequestObject (public API)</issue_title>
<issue_description>## Problem Statement

New-IdleLifecycleRequestObject is a public function but lacks complete comment-based help (CBH). This violates the project's documentation consistency expectations and reduces usability (help discovery, generated docs, examples).

Proposed Solution

Add full CBH to New-IdleLifecycleRequestObject following the project's conventions:

• .SYNOPSIS, .DESCRIPTION
• Parameter docs for all parameters
• At least 2 examples:
  1. Minimal request creation
  2. Request creation with identity keys / attributes relevant to typical workflows
• Notes about:
  • Data-only expectations (no ScriptBlocks in user-provided config)
  • Security considerations (do not embed secrets in messages / outputs; rely on redaction boundaries where applicable)

Additionally:

• Ensure the function appears correctly in generated documentation (if the project generates API docs from CBH).
• If there is a docs “reference” page for request objects, link it or update it (single source of truth).

Alternatives Considered

• Leaving CBH minimal and relying on README snippets.
  • Rejected: drift risk and inconsistent user experience.

Impact

• Does this affect existing workflows?
  • No runtime behavior change.
• Any backward compatibility concerns?
  • None.

Acceptance Criteria:

• Get-Help New-IdleLifecycleRequestObject -Full provides meaningful, complete help.
• Examples run successfully in a pwsh environment with IdLE imported.
• Doc generation (if applicable) includes/updates the function reference.

Additional Context

Testing:

• Add or update a lightweight Pester test to assert CBH presence for public functions (if such tests already exist). If not, limit to verifying this function only.

Definition of Done:

• CBH implemented in English.
• Examples validated.
• Any generated docs updated (if applicable).
  </issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes Add comment-based help for New-IdleLifecycleRequestObject (public API) #183

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[Copilot]

Pull request overview

This PR adds comprehensive comment-based help (CBH) to IdLE.Core public functions to improve API documentation and Get-Help output. Before this change, functions lacked complete CBH, making them harder to use and discover. The PR focuses on New-IdleLifecycleRequestObject with complete documentation and adds examples to three other functions, plus a general test to prevent future CBH regressions.

Changes:

• Added complete CBH (synopsis, description, parameters, 3 examples, outputs, security notes) to New-IdleLifecycleRequestObject
• Added examples to Invoke-IdlePlanObject, New-IdlePlanObject, and Test-IdleWorkflowDefinitionObject
• Added automated test to validate all IdLE.Core public functions have synopsis, description, and examples

Reviewed changes

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

Show a summary per file

File	Description
src/IdLE.Core/Public/New-IdleLifecycleRequestObject.ps1	Added complete CBH including synopsis, description, all parameter docs, 3 examples showing minimal/typical/mover workflows, outputs, and comprehensive security notes
src/IdLE.Core/Public/Invoke-IdlePlanObject.ps1	Added example demonstrating plan execution with provider registry
src/IdLE.Core/Public/New-IdlePlanObject.ps1	Added example demonstrating plan creation from workflow and request
src/IdLE.Core/Public/Test-IdleWorkflowDefinitionObject.ps1	Added example demonstrating workflow validation
tests/Core/ModuleExports.Tests.ps1	Added comprehensive test validating all IdLE.Core public functions have synopsis, description, and at least one example