fix(scripts): align agent frontmatter schema with VS Code spec

[aavetis]

Pull Request

Description

Aligns the agent frontmatter JSON schema with the VS Code Custom Agents spec deltas described in #425, and updates the repo's schema validator so the new schema constraints are enforced.

Implementation Notes

• Test-JsonSchemaValidation now supports the schema constructs required for this issue (oneOf, nested object with required/properties, and array.items)
• additionalProperties is still not enforced by the validator (documented), consistent with prior behavior

Issue #425 Requirements (Checklist)

• Add missing fields to agent-frontmatter.schema.json: agents, user-invokable, disable-model-invocation
• Fix model type to allow string OR array of strings
• Make handoffs.prompt optional
• Add handoffs.model (optional string)
• Preserve HVE-Core specific maturity field

Related Issue(s)

Fixes #425

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

Ran locally:

• npm run lint:frontmatter
• npm run lint:ps
• npm run test:ps
• npm run spell-check
• Validated all agents with schema validation enabled:
  • pwsh -NoProfile -Command "& scripts/linting/Validate-MarkdownFrontmatter.ps1 -WarningsAsErrors -EnableSchemaValidation -Files (Get-ChildItem -Path .github/agents -Filter *.agent.md -File | Select-Object -ExpandProperty FullName)"

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)

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

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

Additional Notes

• Adds dependency-pinning-artifacts/ to .gitignore since it is generated by the dependency pinning scan script during local runs and can otherwise leave the working tree dirty.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 86.53%. Comparing base (73c0d2c) to head (18700ad).
⚠️ Report is 5 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #469      +/-   ##
==========================================
+ Coverage   86.30%   86.53%   +0.23%     
==========================================
  Files          23       23              
  Lines        4762     4836      +74     
==========================================
+ Hits         4110     4185      +75     
+ Misses        652      651       -1     

Flag	Coverage Δ
pester	86.53% <100.00%> (+0.23%)	⬆️

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

Files with missing lines	Coverage Δ
scripts/linting/Validate-MarkdownFrontmatter.ps1	74.66% <100.00%> (+8.89%)	⬆️

🚀 New features to boost your workflow:

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

[Copilot]

Pull request overview

Updates the repo’s agent frontmatter JSON schema to match VS Code Custom Agents spec deltas from #425, and extends the PowerShell schema validator to enforce the newly needed schema constructs during frontmatter linting.

Changes:

• Expanded agent-frontmatter.schema.json with agents, user-invokable, disable-model-invocation, handoffs.model, and corrected model to allow string or string-array.
• Enhanced Test-JsonSchemaValidation to support oneOf and nested object/array.items validation patterns used by repo schemas.
• Added unit tests for oneOf and nested object/array validation scenarios.

Reviewed changes

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

Show a summary per file

File	Description
scripts/tests/linting/Validate-MarkdownFrontmatter.Tests.ps1	Adds unit tests covering oneOf and nested object/array schema validation behavior.
scripts/linting/schemas/agent-frontmatter.schema.json	Aligns agent frontmatter schema fields and types with the VS Code spec deltas (while preserving maturity).
scripts/linting/Validate-MarkdownFrontmatter.ps1	Implements validator support for oneOf and nested object/array validation patterns used by the updated schema.
.gitignore	Ignores locally generated dependency-pinning artifacts directory.
.cspell.json	Adds “invokable” to spelling allowlist.

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

Copilot reviewed 4 out of 5 changed files in this pull request and generated 1 comment.

[katriendg]

Thank you so much for picking up an open issue and addressing this @aavetis!

Really appreciate your work on this. Love the code coverage result as well, neat!
I have a few minor comments, if you could please review those? For the rest I have no other comments and we look forward to being able to merge this one in.

Thanks again and hope to see you contribute in the future.

[WilliamBerryiii]

@aavetis - once the code comments are resolved, I'll get this approved and merged in. Thanks for the contribution!!!

[Copilot]

Pull request overview

Copilot reviewed 4 out of 5 changed files in this pull request and generated 1 comment.

[WilliamBerryiii]

Thank you for your contribution, @aavetis. We restructured the PR description to follow the project's pull request template. Please review the updated description and check any additional boxes that apply to your changes.

[WilliamBerryiii]

Thank you for this contribution, @aavetis! 🎉 Your work aligning the agent frontmatter schema and validator with the VS Code custom agent spec is a meaningful improvement to the project's schema validation pipeline.

We've rebased onto main, addressed the review comments (function hoisting, validation order, oneOf early-exit, docblock cleanup, and the new negative test case), and all 1404 tests pass cleanly. The branch is updated and ready for final review.

We really appreciate the time and care you put into this. Great work!