Validate markdown frontmatter

This directory contains PowerShell scripts for automating linting, validation, and security checks in the hve-core repository.

Directory Structure

scripts/
├── collections/     Collection validation and shared helpers
├── agents/          Agent activation harness and baseline snapshots
├── evals/           Eval runner and moderation automation
├── release/         Release version-file update helper
├── devcontainer/    Devcontainer lockfile and change log validation
├── extension/       VS Code extension packaging utilities
├── lib/             Shared utility modules
├── linting/         PowerShell linting and validation scripts
├── plugins/         Copilot CLI plugin generation
├── security/        Security scanning and dependency pinning scripts
└── tests/           Pester test organization

Extension

VS Code extension packaging utilities.

Script	Purpose
Package-Extension.ps1	Package the VS Code extension
Prepare-Extension.ps1	Prepare extension contents for packaging

Library

Shared utility modules used across scripts.

Script	Purpose
Get-VerifiedDownload.ps1	Download files with SHA verification

Agents

The agents/ directory contains the activation harness for Copilot agent cold-start validation.

Script	Purpose
activation-harness/Get-AgentActivationFingerprint.psm1	Compute deterministic activation fingerprints for custom agents across scenarios
activation-harness/Update-AgentActivationBaseline.ps1	Regenerate baseline.json for the activation harness and support dry-run drift checks
activation-harness/baseline.json	Snapshot of the current activation fingerprint baseline for the ADR creation agent

See activation-harness/README.md for the full harness contract and baseline workflow.

Release

The release/ directory contains the repository version-update helper used by release workflows.

Script	Purpose
Update-VersionFiles.ps1	Update version strings across package.json, package-lock.json, extension manifests, plugin metadata, and release manifests

Linting Scripts

The linting/ directory contains scripts for validating code quality and documentation:

Script	Purpose
Invoke-PSScriptAnalyzer.ps1	Static analysis for PowerShell files
Validate-MarkdownFrontmatter.ps1	Validate YAML frontmatter in markdown files
Validate-SkillStructure.ps1	Validate skill directory structure and frontmatter
Invoke-LinkLanguageCheck.ps1	Detect en-us language paths in URLs
Link-Lang-Check.ps1	Link language checking entry point
Markdown-Link-Check.ps1	Validate markdown links
Invoke-YamlLint.ps1	YAML file validation
Test-CopyrightHeaders.ps1	Validate copyright headers in source files
Invoke-MsDateFreshnessCheck.ps1	Check ms.date frontmatter freshness
Invoke-PythonLint.ps1	Python linting via ruff
Invoke-PythonTests.ps1	Python tests via pytest
Validate-AdrConsistency.ps1	Validate ADR structure and Govern-phase consistency rules

See linting/README.md for detailed documentation.

Evals

The evals/ directory contains PowerShell entry points for agent-behavior, baseline-equivalence, moderation, and other eval automation.

Script	Purpose
Build-AgentBehaviorSpec.ps1	Regenerate the agent-behavior eval spec from per-agent stimulus partials
Build-AgentInventory.ps1	Generate the authoritative agent inventory used by eval suites
Invoke-AgentMatrix.ps1	Run the agent-behavior matrix and aggregate per-agent summaries
Invoke-BaselineEquivalence.ps1	Run baseline-vs-customized equivalence evals for a target agent
Invoke-ContentModeration.ps1	Invoke the content moderation CLI over prompt or output content
Invoke-CorpusModeration.ps1	Moderate changed AI corpus content from the changed-artifact manifest
Invoke-VallyEvals.ps1	Execute vally evals for changed AI artifacts

See ../evals/README.md for the broader eval framework documentation.

Devcontainer Scripts

The devcontainer/ directory contains scripts for devcontainer infrastructure validation:

Script	Purpose
Test-DevcontainerLockfile.ps1	Validate lockfile existence, SHA-256 integrity, coverage
Write-DevcontainerChangeLog.ps1	Classify changed files and generate markdown summary

Run locally:

npm run validate:devcontainer-lockfile
npm run validate:devcontainer-changelog

Security Scripts

The security/ directory contains scripts for security scanning and dependency management:

Script	Purpose
Test-DependencyPinning.ps1	Validate dependency pinning compliance
Test-SHAStaleness.ps1	Check for outdated SHA pins
Update-ActionSHAPinning.ps1	Automate updating GitHub Actions SHA pins
Test-ActionVersionConsistency.ps1	Validate action version consistency

Plugins

Copilot CLI plugin generation and validation.

Script	Purpose
Generate-Plugins.ps1	Generate plugin packages from collections
Validate-Marketplace.ps1	Validate marketplace metadata

Collections

Collection validation and shared helpers.

Script	Purpose
Validate-Collections.ps1	Validate collection metadata and structure

Tests

Pester test organization matching the scripts structure.

Directory	Tests For
collections/	Collection helpers tests
devcontainer/	Devcontainer validation tests
extension/	Extension packaging tests
lib/	Library utility tests
linting/	Linting script tests
security/	Security validation tests
plugins/	Plugin generation tests
Fixtures/	Shared test fixtures
Mocks/	Shared mock data

Run all tests:

npm run test:ps

Usage

All scripts are designed to run both locally and in GitHub Actions workflows. They support common parameters like -Verbose and -Debug for troubleshooting.

Local Testing

# Test PSScriptAnalyzer on changed files
./scripts/linting/Invoke-PSScriptAnalyzer.ps1 -ChangedFilesOnly -Verbose

# Validate markdown frontmatter
./scripts/linting/Validate-MarkdownFrontmatter.ps1 -Verbose

# Check for language paths in URLs
./scripts/linting/Invoke-LinkLanguageCheck.ps1 -Verbose

GitHub Actions Integration

All scripts automatically detect GitHub Actions environment and provide appropriate output formatting (annotations, summaries, artifacts).

Contributing

When adding new scripts:

1. Follow PowerShell best practices (PSScriptAnalyzer compliant)
2. Include the entry point guard pattern (see below)
3. Support -Verbose and -Debug parameters
4. Add GitHub Actions integration using LintingHelpers module functions
5. Include inline help with .SYNOPSIS, .DESCRIPTION, .PARAMETER, and .EXAMPLE
6. Document in relevant README files
7. Test locally before creating PR

Entry Point Guard Pattern

All production scripts use a dot-source guard that enables Pester tests to import functions without executing main logic. Extract main logic into an Invoke-* orchestrator function and wrap direct execution in a guard block:

#region Functions

function Invoke-ScriptMain {
    [CmdletBinding()]
    param( <# script params #> )
    # Main logic here
}

#endregion Functions

#region Main Execution
if ($MyInvocation.InvocationName -ne '.') {
    try {
        Invoke-ScriptMain @PSBoundParameters
        exit 0
    }
    catch {
        Write-Error -ErrorAction Continue "ScriptName failed: $($_.Exception.Message)"
        Write-CIAnnotation -Message $_.Exception.Message -Level Error
        exit 1
    }
}
#endregion Main Execution

Key rules:

• The if guard wraps try/catch (not the reverse)
• Name the orchestrator Invoke-* matching the script noun
• Use #region Functions and #region Main Execution markers
• See Package-Extension.ps1 for a canonical example

Related Documentation

• Collection Scripts Documentation
• Extension Packaging Documentation
• Library Utilities Documentation
• Linting Scripts Documentation
• Plugin Generation Documentation
• Security Scripts Documentation
• Test Organization Documentation
• Agent Activation Harness Documentation
• Evaluation Framework Documentation
• GitHub Workflows Documentation
• Contributing Guidelines

---

🤖 Crafted with precision by ✨Copilot following brilliant human instruction, then carefully refined by our team of discerning human reviewers.