microsoft/hve-core

Commit

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

## 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)
* [x] New feature (non-breaking change adding functionality)
* [ ] Breaking change (fix or feature causing existing functionality to
change)
* [x] 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
* [x] 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](../docs/contributing/skills.md).
> * **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](../docs/contributing/custom-agents.md#agents-not-accepted) and
[Model Version
Requirements](../docs/contributing/ai-artifacts-common.md#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:

```powershell
# 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:

```powershell
# 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

* [x] Documentation is updated (if applicable)
* [x] Files follow existing naming conventions
* [x] 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:

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

## Security Considerations

* [x] This PR does not contain any sensitive or NDA information
* [x] Any new dependencies have been reviewed for security issues (N/A —
no new dependencies)
* [x] 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.