fix(scripts): standardize timestamp in FrontmatterValidation.psm1 to use Get-StandardTimestamp

[chaosdinosaur]

Pull Request

Description

Standardized timestamps in FrontmatterValidation.psm1 to use Get-StandardTimestamp from CIHelpers.psm1:

• Changed ValidatedAt property from [datetime] to [string], now set via Get-StandardTimestamp producing ISO 8601 UTC strings ending in Z.
• Replaced [datetime]::UtcNow with (Get-Date).ToUniversalTime() for StartedAt and CompletedAt to preserve Duration arithmetic while using the same UTC source as Get-StandardTimestamp.
• Added Timestamp = Get-StandardTimestamp to ValidationSummary.ToHashtable() so the JSON output includes a standardized timestamp consistent with all other lint result files.
• Added Import-Module for CIHelpers.psm1 at module scope.

Related Issue(s)

Fixes #1001

Type of Change

Select all that apply:

Code & Documentation:

• Bug fix (non-breaking change fixing an issue)
• New feature (non-breaking change adding functionality)
• Breaking change (fix or feature causing existing functionality to change)
• Documentation update

Infrastructure & Configuration:

• GitHub Actions workflow
• Linting configuration (markdown, PowerShell, etc.)
• Security configuration
• DevContainer configuration
• Dependency update

AI Artifacts:

• Reviewed contribution with prompt-builder agent and addressed all feedback
• Copilot instructions (.github/instructions/*.instructions.md)
• Copilot prompt (.github/prompts/*.prompt.md)
• Copilot agent (.github/agents/*.agent.md)
• Copilot skill (.github/skills/*/SKILL.md)

Other:

• Script/automation (.ps1, .sh, .py)
• Other (please describe):

Testing

• Verified [datetime]::UtcNow replaced with Get-StandardTimestamp for ValidatedAt (type changed from [datetime] to [string]).
• Verified StartedAt/CompletedAt use (Get-Date).ToUniversalTime() preserving Duration arithmetic.
• Verified Timestamp field added to ToHashtable() using Get-StandardTimestamp.
• Updated Pester test for ValidatedAt to assert ISO 8601 UTC format instead of DateTime range comparison.
• Added Pester test for Timestamp key in ToHashtable() output.
• npm run lint:ps passed.
• npm run test:ps passed (129 tests for this file).

Checklist

Required Checks

• Documentation is updated (if applicable) (N/A — no docs change needed)
• Files follow existing naming conventions
• Changes are backwards compatible (if applicable)
• Tests added for new functionality (if applicable)

Required Automated Checks

The following validation commands must pass before merging:

• Markdown linting: npm run lint:md
• Spell checking: npm run spell-check
• Frontmatter validation: npm run lint:frontmatter
• Skill structure validation: npm run validate:skills
• Link validation: npm run lint:md-links
• PowerShell analysis: npm run lint:ps
• Plugin freshness: npm run plugin:generate

Security Considerations

• This PR does not contain any sensitive or NDA information
• Any new dependencies have been reviewed for security issues (N/A — no dependency changes)
• Security-related scripts follow the principle of least privilege (N/A — no privilege changes)

Additional Notes

This is the most complex issue in the timestamp standardization series (#994-#1002) because FrontmatterValidation.psm1 uses [datetime] typed class properties for arithmetic (Duration computation). The fix preserves [datetime] typing for StartedAt/CompletedAt to maintain Duration arithmetic, while changing ValidatedAt to a [string] type with Get-StandardTimestamp. A Timestamp field was added to ToHashtable() to ensure JSON output includes a standardized UTC timestamp consistent with all other lint result files.

The prerequisite Get-StandardTimestamp function was merged in #993.

[github-actions]

Review Summary

This PR correctly addresses issue #1001 — the implementation is well-reasoned, the approach to preserving [datetime] typing for StartedAt/CompletedAt (required for Duration arithmetic) while using Get-StandardTimestamp for the string-typed ValidatedAt is sound, and the test updates are thorough. One naming consistency issue found.

---

Issue Alignment ✅

The PR directly and completely addresses issue #1001:

• All three [datetime]::UtcNow usages are replaced.
• CIHelpers.psm1 is imported.
• ValidatedAt type changed from [datetime] to [string].
• Timestamp field added to ToHashtable().
• Pester tests updated for the new string format.

---

PR Template Compliance ✅

• Description is clear and specific.
• Fixes #1001 is present.
• "Bug fix" and "Script/automation" checkboxes are correctly checked.
• Testing section is detailed.
• Checklist items are appropriately checked.

---

Coding Standards ✅ (one minor finding)

See inline comment on FrontmatterValidation.psm1 line 197.

---

Code Quality ✅

• The Import-Module at module scope follows the established pattern from other .psm1 files in the repo.
• Using (Get-Date).ToUniversalTime() for StartedAt/CompletedAt preserves the [datetime] type required for $this.Duration = $this.CompletedAt - $this.StartedAt arithmetic — correct design decision.
• Get-StandardTimestamp returns (Get-Date).ToUniversalTime().ToString('o') which matches the regex assertion ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d+Z$ in the tests — format validation is accurate.
• No security concerns.

---

Action Required

One change needed (inline comment above):

• Rename Timestamp → timestamp in ToHashtable() (line 197 of FrontmatterValidation.psm1) and update the matching test assertions in FrontmatterValidation.Tests.ps1 (lines 355–356) to keep JSON key casing consistent with all other keys in the hashtable.

Generated by PR Review for issue #1285

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 87.71%. Comparing base (84ddd5d) to head (b11cec6).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1285      +/-   ##
==========================================
- Coverage   87.72%   87.71%   -0.01%     
==========================================
  Files          61       61              
  Lines        9320     9322       +2     
==========================================
+ Hits         8176     8177       +1     
- Misses       1144     1145       +1     

Flag	Coverage Δ
pester	85.31% <100.00%> (-0.02%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
scripts/linting/Modules/FrontmatterValidation.psm1	96.05% <100.00%> (+0.02%)	⬆️

... and 1 file with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.