Add Get-StandardTimestamp utility to CIHelpers module

[WilliamBerryiii]

Summary

Five distinct timestamp formats exist across linting and security scripts with no shared utility function. This causes inconsistent log output that makes cross-script correlation unreliable. Add a Get-StandardTimestamp function to CIHelpers.psm1 returning ISO 8601 UTC format.

Current Behavior

Scripts use 5 different timestamp expressions:

• Get-Date -Format "o" (local offset) — 4 scripts
• (Get-Date).ToUniversalTime().ToString("o") (UTC) — 2 scripts
• Get-Date -Format 'yyyy-MM-dd HH:mm:ss' (no timezone) — SecurityHelpers
• 'yyyy-MM-ddTHH:mm:ss.fffZ' (fake UTC) — SecurityClasses ComplianceReport
• [datetime]::UtcNow (raw .NET) — FrontmatterValidation

Expected Behavior

A single Get-StandardTimestamp function in CIHelpers.psm1 returns (Get-Date).ToUniversalTime().ToString("o") (ISO 8601 UTC). All scripts that generate timestamps use this function for consistency.

Root Cause

No shared timestamp utility was created when the scripts were developed independently. Each author chose their own format.

Files Requiring Changes

File	Change
scripts/lib/Modules/CIHelpers.psm1	Add Get-StandardTimestamp function
scripts/tests/lib/CIHelpers.Tests.ps1	Add tests for Get-StandardTimestamp

Fix Guidance

Add to CIHelpers.psm1:

function Get-StandardTimestamp {
    <#
    .SYNOPSIS
        Returns the current UTC time in ISO 8601 format.
    #>
    [CmdletBinding()]
    [OutputType([string])]
    param()
    return (Get-Date).ToUniversalTime().ToString("o")
}

Export the function in the module's Export-ModuleMember or FunctionsToExport manifest.

Unit Testing and Code Coverage Requirements

Pester tests should verify:

• Returns a string
• String matches ISO 8601 pattern with Z suffix (UTC)
• Consecutive calls return monotonically increasing timestamps

RPI Phase Testing Guidance:

• Research: Audit CIHelpers.psm1 export mechanism and existing test patterns.
• Plan: Design test cases for format validation and UTC verification.
• Implement: Add function and tests.
• Review: Confirm function is exported and tests pass.

RPI Framework Starter Prompts

Phase 1: Research

Select Task Researcher from the agent picker at the bottom of the GitHub Copilot Chat prompt pane, then send the following prompt:

Research adding Get-StandardTimestamp to CIHelpers.psm1. Investigate: (1) Read scripts/lib/Modules/CIHelpers.psm1 to understand the module structure, existing exported functions, and the export mechanism (Export-ModuleMember or manifest). (2) Audit all 5 timestamp formats currently in use — identify exact file paths and line numbers for each. (3) Check scripts/tests/lib/CIHelpers.Tests.ps1 for existing test patterns and mock conventions. (4) Determine whether the function should accept parameters (e.g., -AsDateTime to return a DateTime object instead of string) or be zero-parameter. (5) Review ISO 8601 format options — "o" round-trip format includes fractional seconds and Z suffix when UTC.

Phase 2: Plan

Select Task Planner from the agent picker at the bottom of the GitHub Copilot Chat prompt pane, then send the following prompt:

Plan adding Get-StandardTimestamp to CIHelpers.psm1 using the research document. The plan should cover: (1) Adding the function with [CmdletBinding()], [OutputType([string])], and zero parameters. (2) Returning (Get-Date).ToUniversalTime().ToString("o"). (3) Exporting the function alongside existing exports. (4) Adding Pester tests for return type, ISO 8601 format match, and UTC suffix. (5) Validation: npm run test:ps, npm run lint:ps.

Phase 3: Implement

Select Task Implementor from the agent picker at the bottom of the GitHub Copilot Chat prompt pane, then send the following prompt:

Implement Get-StandardTimestamp in CIHelpers.psm1 following the plan. Steps: (1) Add the function to scripts/lib/Modules/CIHelpers.psm1 with comment-based help. (2) Ensure it is exported in the module's export mechanism. (3) Add tests to scripts/tests/lib/CIHelpers.Tests.ps1 verifying: returns string, matches ISO 8601 pattern, ends with Z. (4) Run npm run lint:ps for PSScriptAnalyzer. (5) Run npm run test:ps for Pester.

Phase 4: Review

Select Task Reviewer from the agent picker at the bottom of the GitHub Copilot Chat prompt pane, then send the following prompt:

Review Get-StandardTimestamp addition to CIHelpers.psm1. Verify: (1) Function follows PowerShell conventions: [CmdletBinding()], [OutputType()], comment-based help. (2) Returns ISO 8601 UTC string with .ToString("o"). (3) Function is properly exported from the module. (4) Pester tests cover return type, format validation, and UTC verification. (5) npm run lint:ps passes. (6) npm run test:ps passes. (7) No other module functions were modified.

References

• scripts/lib/Modules/CIHelpers.psm1 — target module
• scripts/tests/lib/CIHelpers.Tests.ps1 — test file
• Cross-cutting: This is a prerequisite for Issues 8-17 (per-script timestamp standardization)