feat(workflows): add ms.date documentation freshness checking

[rezatnoMsirhC]

feat(workflows): add ms.date documentation freshness checking

Description

This PR ports the automated ms.date documentation freshness checking system from Azure-Samples/azure-nvidia-robotics-reference-architecture PR #448 into hve-core. The system tracks the ms.date frontmatter field across all markdown files, surfaces stale content through CI annotations during pull requests, and automates GitHub issue creation for stale files on a weekly schedule.

PowerShell Script and Tests

The core of the feature is Invoke-MsDateFreshnessCheck.ps1, a PowerShell 7 script that discovers markdown files, parses ms.date from YAML frontmatter, computes staleness against a configurable day threshold, and generates both a JSON report (logs/msdate-freshness-results.json) and a markdown summary (logs/msdate-summary.md). Stale files emit CI annotations via the existing Write-CIAnnotation helper.

• Added scripts/linting/Invoke-MsDateFreshnessCheck.ps1 — file discovery with configurable exclusions (node_modules, .git, logs, .copilot-tracking, CHANGELOG.md), YAML frontmatter parsing via powershell-yaml, and changed-files-only mode backed by git diff
  • Fixed a bug present in the source repo: $isExplicitFilePath now uses Test-Path -PathType Leaf rather than $path -ne '.', ensuring absolute directory paths correctly receive exclusion filtering
• Added scripts/tests/linting/Invoke-MsDateFreshnessCheck.Tests.ps1 — Pester 5 test suite (~530 lines) with Unit and Integration tags, covering file discovery (6 contexts), frontmatter parsing (5 contexts including YAML errors and file-not-found), report generation (4 contexts), and an integration loop exercising Write-CIAnnotation via a verifiable mock
• Added msdate to .cspell/general-technical.txt

GitHub Actions Workflows

Three new reusable workflows implement the dual-context checking pattern:

• Added .github/workflows/msdate-freshness-check.yml — reusable workflow_call with staleness-threshold-days (default: 90) and changed-files-only inputs; uploads msdate-freshness-results.json as a workflow artifact and writes the markdown summary to the Actions job summary
• Added .github/workflows/weekly-validation.yml — scheduled orchestrator running Monday at 09:00 UTC; calls msdate-freshness-check.yml for a full-repository scan, then calls create-stale-docs-issues.yml
• Added .github/workflows/create-stale-docs-issues.yml — idempotent issue automation; uses a hidden <!-- automation:stale-docs:{file-path} --> marker to locate existing open issues before creating new ones, avoiding duplicates across weekly runs

Modified .github/workflows/pr-validation.yml to add the msdate-freshness job between frontmatter-validation and plugin-validation, running with changed-files-only: true against files changed in the PR.

Documentation

Added docs/contributing/documentation-maintenance.md explaining the dual-context freshness pattern, how to fix stale documentation, how to configure thresholds, how the issue automation deduplicates, and common troubleshooting steps. Stale soft-fail references were also removed from the guide during review — the implementation is a hard-fail; there is no soft-fail mode.

Related Issue(s)

Closes #968

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)

Note for AI Artifact Contributors:

• Agents: Research, indexing/referencing other project (using standard VS Code GitHub Copilot/MCP tools), planning, and general implementation agents likely already exist. Review .github/agents/ before creating new ones.
• Skills: Must include both bash and PowerShell scripts. See Skills.
• Model Versions: Only contributions targeting the latest Anthropic and OpenAI models will be accepted. Older model versions (e.g., GPT-3.5, Claude 3) will be rejected.
• See Agents Not Accepted and Model Version Requirements.

Other:

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

Sample Prompts (for AI Artifact Contributions)

Testing

Validated using the Pester 5 test suite added as part of this PR:

• npm run test:ps — 1691 tests passed (0 failures); includes all existing tests plus the new Invoke-MsDateFreshnessCheck.Tests.ps1 suite covering Get-MarkdownFiles, Get-MsDateFromFrontmatter, New-MsDateReport, and integration contexts
• npm run lint:ps — PSScriptAnalyzer reported no issues against Invoke-MsDateFreshnessCheck.ps1
• npm run lint:frontmatter — 0 errors, 0 warnings across all markdown files including the new documentation-maintenance.md
• npm run validate:skills — 5 skills validated, 0 errors
• npm run plugin:generate — 11 plugins generated successfully

Manual verification: Reviewed all workflow files for SHA-pinned actions, least-privilege permissions, and consistent shell: pwsh per-step (no workflow-level defaults).

Checklist

Required Checks

• Documentation is updated (if applicable)
• Files follow existing naming conventions
• Changes are backwards compatible (if applicable)
• Tests added for new functionality (if applicable)

AI Artifact Contributions

• Used /prompt-analyze to review contribution (N/A — no AI artifact changes)
• Addressed all feedback from prompt-builder review (N/A — no AI artifact changes)
• Verified contribution follows common standards and type-specific requirements (N/A — no AI artifact changes)

Required Automated Checks

The following validation commands must pass before merging:

• Markdown linting: npm run lint:md (not available in local environment; runs in CI)
• Spell checking: npm run spell-check (not available in local environment; runs in CI)
• Frontmatter validation: npm run lint:frontmatter
• Skill structure validation: npm run validate:skills
• Link validation: npm run lint:md-links (not available in local environment; runs in CI)
• 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
• Security-related scripts follow the principle of least privilege (N/A — no security scripts modified)

Additional Notes

• GitHub labels stale-docs and automated must be created in the repository before create-stale-docs-issues.yml runs in production. No automated pre-flight check exists — this is an operational prerequisite.
• create-stale-docs-issues.yml rewrites the full issue body on each weekly run. Human edits to the issue body will be discarded; comments are preserved.
• PowerShell-Yaml is installed on each run without a version pin or module cache. Pinning the version is a follow-up improvement.
• The artifact name msdate-freshness-results is hardcoded in the producer workflow and referenced by name in the consumer. This loose coupling is intentional but worth noting for future maintainers.

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

OpenSSF Scorecard

Package	Version	Score	Details
actions/actions/checkout	de0fac2e4500dabe0009e67214ff5f5447ce83dd	🟢 5.9	Details Check Score Reason Maintained ⚠️ 2 3 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 2 Code-Review 🟢 10 all changesets reviewed Dangerous-Workflow 🟢 10 no dangerous workflow patterns detected Binary-Artifacts 🟢 10 no binaries found in the repo CII-Best-Practices ⚠️ 0 no effort to earn an OpenSSF best practices badge detected Token-Permissions ⚠️ 0 detected GitHub workflow tokens with excessive permissions Packaging ⚠️ -1 packaging workflow not detected Fuzzing ⚠️ 0 project is not fuzzed License 🟢 10 license file detected Signed-Releases ⚠️ -1 no releases found Pinned-Dependencies 🟢 3 dependency not pinned by hash detected -- score normalized to 3 Security-Policy 🟢 9 security policy file detected Branch-Protection 🟢 5 branch protection is not maximal on development and all release branches SAST 🟢 8 SAST tool detected but not run on all commits
actions/actions/upload-artifact	bbbca2ddaa5d8feaa63e36b76fdaad77386f024f	🟢 6.2	Details Check Score Reason Maintained 🟢 10 28 commit(s) and 1 issue activity found in the last 90 days -- score normalized to 10 Binary-Artifacts 🟢 10 no binaries found in the repo Code-Review 🟢 10 all changesets reviewed Dangerous-Workflow 🟢 10 no dangerous workflow patterns detected Packaging ⚠️ -1 packaging workflow not detected CII-Best-Practices ⚠️ 0 no effort to earn an OpenSSF best practices badge detected Token-Permissions ⚠️ 0 detected GitHub workflow tokens with excessive permissions Pinned-Dependencies ⚠️ 1 dependency not pinned by hash detected -- score normalized to 1 Fuzzing ⚠️ 0 project is not fuzzed License 🟢 10 license file detected Signed-Releases ⚠️ -1 no releases found Security-Policy 🟢 9 security policy file detected Branch-Protection ⚠️ 0 branch protection not enabled on development/release branches SAST 🟢 10 SAST tool is run on all commits

Scanned Files

• .github/workflows/msdate-freshness-check.yml

[codecov-commenter]

Codecov Report

❌ Patch coverage is 91.89189% with 9 lines in your changes missing coverage. Please review.
✅ Project coverage is 86.01%. Comparing base (a1a6845) to head (e64df4f).
⚠️ Report is 46 commits behind head on main.

Files with missing lines	Patch %	Lines
scripts/linting/Invoke-MsDateFreshnessCheck.ps1	91.89%	9 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #969      +/-   ##
==========================================
+ Coverage   85.88%   86.01%   +0.12%     
==========================================
  Files          27       28       +1     
  Lines        5159     5270     +111     
==========================================
+ Hits         4431     4533     +102     
- Misses        728      737       +9     

Flag	Coverage Δ
pester	86.01% <91.89%> (+0.12%)	⬆️

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

Files with missing lines	Coverage Δ
scripts/linting/Invoke-MsDateFreshnessCheck.ps1	91.89% <91.89%> (ø)

🚀 New features to boost your workflow:

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

[katriendg]

I've left a few comments, once those are closed I think this is good to go. Thanks!