feat(instructions): add PowerShell coding standards, Pester testing conventions, and bash copyright headers

[WilliamBerryiii]

Description

This PR introduces comprehensive PowerShell coding standards and Pester testing conventions to the hve-core project and adds copyright header requirements to the existing bash instructions. It also standardizes attribution conventions across AI artifact documentation.

PowerShell Coding Standards

PowerShell scripting lacked formal coding guidance, leading to inconsistent patterns across the codebase.

Added powershell.instructions.md establishing complete scripting standards for .ps1, .psm1, and .psd1 files. The instruction covers a 10-section script structure, module patterns, naming conventions, error handling, CI integration via Write-CIAnnotation, parameter validation, PSScriptAnalyzer compliance, and copyright headers. Two complete working examples — a script template and a module template — demonstrate the conventions in practice.

Pester Testing Conventions

Pester test files lacked dedicated coding guidance, causing inconsistent test structure across scripts/tests/.

Added pester.instructions.md (245 lines) establishing Pester 5.x testing conventions for .Tests.ps1 files. The instruction covers test naming and location, file headers (#Requires, copyright), SUT imports via $PSScriptRoot-relative paths, Describe/Context/It block structure, mocking with Mock/InModuleScope, assertions, tag conventions, output handling, and a complete annotated example template. Separated from powershell.instructions.md to keep each file focused and avoid excessive length.

Bash Copyright Headers

Updated bash.instructions.md with a copyright header section matching the PowerShell format (2-line Microsoft/SPDX-MIT). Corrected the attribution from microsoft/edge-ai to microsoft/hve-core.

Attribution Convention

Updated ai-artifacts-common.md to standardize attribution: frontmatter description field applies to all artifacts, while the blockquote footer is retained only for skill files (SKILL.md).

Collection and Plugin Metadata

Registered the new PowerShell and Pester instructions across collection manifests and plugin outputs. Updated coding-standards.collection.md, coding-standards.collection.yml, and hve-core-all.collection.yml to include PowerShell and Pester in descriptions, tags, and item lists. Updated marketplace.json and plugin metadata to reflect the expanded language coverage. Added plugin symlinks for both coding-standards and hve-core-all plugins.

Related Issue(s)

Closes #308
Closes #316

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)

User Request:

"Write a PowerShell script that validates configuration files" or "Create a PowerShell module for log processing." The instructions activate automatically via the applyTo glob pattern (**/*.ps1, **/*.psm1, **/*.psd1) when editing PowerShell files. For test files, "Write Pester tests for the log processor module" activates pester.instructions.md via the applyTo pattern (**/*.Tests.ps1).

Execution Flow:

1. User creates or edits a .ps1, .psm1, or .psd1 file in the workspace.
2. Copilot attaches powershell.instructions.md based on the applyTo pattern match.
3. Generated code follows the 10-section script structure: copyright header, #Requires statements, using statements, comment-based help, [CmdletBinding()] declaration, parameter block, begin/process/end blocks, and helper functions.
4. Error handling uses try/catch with Write-CIAnnotation -Level Error for CI-aware output.
5. Module files follow the module pattern with proper manifest (.psd1) and script module (.psm1) conventions.
6. When editing *.Tests.ps1 files, pester.instructions.md activates and guides Pester 5.x test structure, SUT imports, mocking, and assertions.

Output Artifacts:

Generated PowerShell scripts contain structured sections following the convention:

# Copyright (c) Microsoft Corporation.
# Licensed under the MIT License.

#Requires -Version 7.0

<#
.SYNOPSIS
    Brief description of the script purpose.
.DESCRIPTION
    Detailed description of what the script does.
#>
[CmdletBinding()]
param(
    [Parameter(Mandatory)]
    [string]$InputPath
)

Generated Pester tests follow the convention:

# Copyright (c) Microsoft Corporation.
# Licensed under the MIT License.

#Requires -Version 7.0
#Requires -Modules @{ ModuleName = 'Pester'; RequiredVersion = '5.7.1' }

Describe 'Function-Name' {
    BeforeAll {
        . "$PSScriptRoot/../../src/Function-Name.ps1"
    }
    Context 'when given valid input' {
        It 'returns expected output' {
            # Arrange, Act, Assert
        }
    }
}

Success Indicators:

• Generated PowerShell code passes PSScriptAnalyzer validation (npm run lint:ps).
• Scripts include the 2-line Microsoft/SPDX-MIT copyright header.
• Parameter names use PascalCase; variables use camelCase.
• Error handling follows the try/catch pattern with Write-CIAnnotation for CI output.
• Pester tests follow Describe/Context/It hierarchy with BeforeAll SUT imports.
• Test files pass npm run test:ps execution.

Testing

Automated validation performed:

• Markdown linting (npm run lint:md): Passed (287 files, 0 errors)
• Spell checking (npm run spell-check): Passed (added LASTEXITCODE and scriptblock to cspell dictionary)
• Frontmatter validation (npm run lint:frontmatter): Passed (271 files, 0 errors, 0 warnings)
• Skill structure validation (npm run validate:skills): Passed (2 skills, 0 errors)
• Link validation (npm run lint:md-links): Passed (12 pre-existing broken links in 7 unrelated files; 0 issues in PR files)
• PowerShell analysis (npm run lint:ps): Passed (all scripts clean)
• Plugin freshness (npm run plugin:generate): Passed (11 plugins, 147 instructions, 330 symlink index entries)

Security analysis: No sensitive data exposure, dependency vulnerabilities, or privilege escalation concerns identified. Changes strengthen code quality and licensing compliance.

Diff-based assessment: All changed files verified against commit history. No unintended modifications detected. Attribution correction (edge-ai → hve-core) confirmed consistent across bash instructions and plugin READMEs.

Manual testing was not performed.

Checklist

Required Checks

• Documentation is updated (if applicable)
• Files follow existing naming conventions
• Changes are backwards compatible (if applicable) (N/A — new instruction files with no removal of existing surfaces)
• Tests added for new functionality (if applicable) (N/A — instruction files do not require tests)

AI Artifact Contributions

• Used /prompt-analyze to review contribution
• Addressed all feedback from prompt-builder review
• Verified contribution follows common standards and type-specific requirements

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 new dependencies)
• Security-related scripts follow the principle of least privilege (N/A — no security scripts modified)

GHCP Artifact Maturity

File	Type	Maturity	Notes
powershell.instructions.md	Instructions	✅ stable	All builds
pester.instructions.md	Instructions	✅ stable	All builds
bash.instructions.md	Instructions	✅ stable	All builds

Additional Notes

• Plugin symlinks for the PowerShell and Pester instructions were added to both coding-standards and hve-core-all plugin directories.
• The attribution convention change in ai-artifacts-common.md narrows blockquote footers to skill files only, simplifying the requirement for instructions, prompts, and agents.
• pester.instructions.md was separated from powershell.instructions.md to keep each file focused and under 250 lines, following the convention of one concern per instruction file.

[github-actions]

Dependency Review

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

Scanned Files

None

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 85.34%. Comparing base (551fddc) to head (5283eb4).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #836   +/-   ##
=======================================
  Coverage   85.34%   85.34%           
=======================================
  Files          27       27           
  Lines        5076     5076           
=======================================
  Hits         4332     4332           
  Misses        744      744           

Flag	Coverage Δ
pester	85.34% <ø> (ø)

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

🚀 New features to boost your workflow:

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

[bindsi]

great