docs(security): add security assurance case and threat model for OSSF Silver (#259)

## Summary

Adds comprehensive security threat model documentation for OSSF Silver
badge compliance, aligned with GitHub's defensive architecture
principles.

Closes #244

## Changes

This PR adds **5 files**:

### Security Documentation
- **`docs/security/threat-model.md`** - Comprehensive threat model with
36 threats (STRIDE + AI-specific + RAI), 18+ controls, and MCP server
trust analysis
- **`docs/security/README.md`** - Security documentation index
- **`SECURITY.md`** - Added link to new security documentation

### Bug Fixes
- **`scripts/linting/Validate-MarkdownFrontmatter.ps1`** - Fixed
repo-relative path detection for template exclusion; updated comment
wording for clarity
- **`.github/workflows/pester-tests.yml`** - Updated Pester from 5.6.1
to 5.7.1 to resolve PSGallery availability issues

## Threat Model Highlights

- **36 identified threats** across STRIDE categories, AI/ML-specific
risks, and Responsible AI concerns
- **18+ security controls** mapped to threats with implementation
guidance
- **MCP server trust boundaries** - Analysis of ADO, GitHub, Microsoft
Docs, and Context7 integrations
- **Data flow diagrams** - Mermaid-based visualization of system
boundaries

## Testing

- ✅ All linting passes (`npm run lint`)
- ✅ All 338 Pester tests pass (`npm run test:ps`)
- ✅ Frontmatter validation passes with template exclusion fix

Author: WilliamBerryiii

.github/workflows/frontmatter-validation.yml

@@ -45,6 +45,11 @@ jobs:
         run: |
           New-Item -ItemType Directory -Force -Path logs | Out-Null
 
+      - name: Install PowerShell-Yaml
+        shell: pwsh
+        run: |
+          Install-Module -Name PowerShell-Yaml -Force -Scope CurrentUser
+
       - name: Run Frontmatter Validation
         shell: pwsh
         run: |

.github/workflows/pester-tests.yml

@@ -41,8 +41,8 @@ jobs:
       - name: Install Pester
         shell: pwsh
         run: |
-          Install-Module -Name Pester -RequiredVersion 5.6.1 -Force -Scope CurrentUser
-          Import-Module Pester -RequiredVersion 5.6.1
+          Install-Module -Name Pester -RequiredVersion 5.7.1 -Force -Scope CurrentUser
+          Import-Module Pester -RequiredVersion 5.7.1
 
       - name: Install PowerShell-Yaml
         shell: pwsh

SECURITY.md

@@ -53,6 +53,10 @@ Microsoft follows the principle of [Coordinated Vulnerability Disclosure](https:
 
 <!-- END MICROSOFT SECURITY.MD BLOCK -->
 
+## Security Documentation
+
+For comprehensive security documentation including threat models and security controls, see [Security Documentation](docs/security/README.md).
+
 ## Verifying Release Integrity
 
 HVE Core releases are cryptographically signed using GitHub Artifact Attestations. This establishes provenance and allows you to verify that release artifacts were built from this repository's official CI/CD pipeline.

docs/security/README.md

@@ -0,0 +1,49 @@
+---
+title: Security Documentation
+description: Index of security documentation including threat model and assurance case for HVE Core
+author: Microsoft
+ms.date: 2026-01-23
+ms.topic: overview
+keywords:
+  - security
+  - documentation
+  - index
+estimated_reading_time: 2
+---
+
+## Overview
+
+This directory contains security documentation for HVE Core, demonstrating defense-in-depth security practices.
+
+## Documents
+
+| Document                         | Description                                            |
+|----------------------------------|--------------------------------------------------------|
+| [Threat Model](threat-model.md)  | Comprehensive threat model and security assurance case |
+| [SECURITY.md](../../SECURITY.md) | Vulnerability disclosure and reporting process         |
+
+## Security Posture
+
+HVE Core is an enterprise prompt engineering framework that:
+
+- Contains no runtime services or user data storage
+- Operates as development-time tooling consumed by GitHub Copilot
+- Relies on defense-in-depth with 18+ automated security controls
+
+The [threat model](threat-model.md) documents:
+
+- 36 threats across STRIDE, AI-specific, and Responsible AI categories
+- Security controls mapped to each threat
+- MCP server trust analysis
+- Quantitative security metrics
+- GSN-style assurance argument
+
+## Related Resources
+
+- [Branch Protection](../contributing/branch-protection.md): Repository protection configuration
+- [MCP Configuration](../getting-started/mcp-configuration.md): MCP server setup and trust guidance
+- [GOVERNANCE.md](../../GOVERNANCE.md): Project governance and maintainer roles
+
+---
+
+🤖 *Crafted with precision by ✨Copilot following brilliant human instruction, then carefully refined by our team of discerning human reviewers.*

docs/security/threat-model.md

@@ -617,9 +617,15 @@ function Test-CommonFields {
     $issues = [System.Collections.Generic.List[ValidationIssue]]::new()
 
     # Validate keywords array
+    # ConvertFrom-Yaml returns sequences as List[object], not native PowerShell arrays
     if ($Frontmatter.ContainsKey('keywords')) {
         $keywords = $Frontmatter['keywords']
-        if ($keywords -isnot [array] -and $keywords -notmatch ',') {
+        $isCollection = $keywords -is [array] -or
+                        $keywords -is [System.Collections.IList] -or
+                        ($keywords -is [System.Collections.IEnumerable] -and
+                         $keywords -isnot [string] -and
+                         $keywords -isnot [hashtable])
+        if (-not $isCollection -and $keywords -notmatch ',') {
             $issues.Add([ValidationIssue]::new('Warning', 'keywords', 'Keywords should be an array', $RelativePath))
         }
     }
@@ -749,10 +755,13 @@ function Get-FileTypeInfo {
         ($File.Name -in @('CODE_OF_CONDUCT.md', 'CONTRIBUTING.md', 'SECURITY.md', 'SUPPORT.md', 'README.md'))
     $info.IsDevContainer = $File.DirectoryName -like "*.devcontainer*" -and $File.Name -eq 'README.md'
     $info.IsVSCodeReadme = $File.DirectoryName -like "*.vscode*" -and $File.Name -eq 'README.md'
-    # Exclude .copilot-tracking and templates from docs validation
+    # Exclude .copilot-tracking (gitignored workflow artifacts) and markdown templates from docs validation
     $isCopilotTracking = $File.DirectoryName -like "*.copilot-tracking*"
     $isTemplate = $File.Name -like "*TEMPLATE*"
-    $info.IsDocsFile = $File.DirectoryName -like "*docs*" -and -not $info.IsGitHub -and -not $isCopilotTracking -and -not $isTemplate
+    # Use repo-relative path to avoid misclassifying files when repo is under a parent containing "docs"
+    $relativePath = [System.IO.Path]::GetRelativePath($RepoRoot, $File.FullName)
+    $relativePathNormalized = $relativePath -replace '\\', '/'
+    $info.IsDocsFile = ($relativePathNormalized -match '(^|/)docs(/|$)') -and -not $info.IsGitHub -and -not $isCopilotTracking -and -not $isTemplate
 
     return $info
 }

scripts/linting/Modules/FrontmatterValidation.psm1

@@ -13,6 +13,9 @@
 #requires -Version 7.0
 
 using namespace System.Collections.Generic
+# Import FrontmatterValidation module with 'using' to make PowerShell class types
+# (FileTypeInfo, ValidationIssue, etc.) available at parse time for [OutputType] attributes
+using module .\Modules\FrontmatterValidation.psm1
 
 param(
     [Parameter(Mandatory = $false)]
@@ -41,8 +44,8 @@ param(
 )
 
 # Import helper modules
+# Note: FrontmatterValidation.psm1 is imported via 'using module' at top of script for class type availability
 Import-Module (Join-Path -Path $PSScriptRoot -ChildPath 'Modules/LintingHelpers.psm1') -Force
-Import-Module (Join-Path -Path $PSScriptRoot -ChildPath 'Modules/FrontmatterValidation.psm1') -Force
 
 #region Type Definitions
 
@@ -429,7 +432,7 @@ function Test-JsonSchemaValidation {
     }
 }
 
-# Get-FileTypeInfo moved to FrontmatterValidation.psm1
+# Get-FileTypeInfo is provided by FrontmatterValidation.psm1 via 'using module' directive
 
 function Test-FrontmatterValidation {
     <#
@@ -731,12 +734,26 @@ if ($MyInvocation.InvocationName -ne '.') {
         $result = Test-FrontmatterValidation -Paths $Paths -ExcludePaths $ExcludePaths -WarningsAsErrors:$WarningsAsErrors -EnableSchemaValidation:$EnableSchemaValidation -SkipFooterValidation:$SkipFooterValidation
     }
 
+    # Normalize result: if pipeline output produced an array, extract the ValidationSummary object
+    # PowerShell functions can inadvertently output multiple objects; take the last (the return value)
+    if ($result -is [System.Array]) {
+        $result = $result | Where-Object { $null -ne $_ -and $_.GetType().GetMethod('GetExitCode') } | Select-Object -Last 1
+    }
+
     # In ChangedFilesOnly mode with no changed files, TotalFiles=0 is a successful no-op
-    if ($ChangedFilesOnly -and $result.TotalFiles -eq 0) {
+    if ($ChangedFilesOnly -and $null -ne $result -and $result.TotalFiles -eq 0) {
         Write-Host "✅ No changed markdown files to validate - success!" -ForegroundColor Green
         exit 0
     }
 
+    # Validate result object before calling GetExitCode to prevent method invocation errors
+    # PowerShell class methods are compiled to .NET type metadata, not stored in PSObject.Methods (ETS only)
+    if ($null -eq $result -or $null -eq $result.GetType().GetMethod('GetExitCode')) {
+        $resultTypeName = if ($null -eq $result) { '<null>' } else { $result.GetType().FullName }
+        Write-Host "Validation did not produce a usable result object (type: $resultTypeName). Exiting with code 1."
+        exit 1
+    }
+
     $exitCode = $result.GetExitCode($WarningsAsErrors)
     if ($exitCode -ne 0) {
         exit $exitCode

scripts/linting/Validate-MarkdownFrontmatter.ps1

@@ -1,8 +1,12 @@
 #Requires -Modules Pester
+# Import module with 'using' to make PowerShell class types (FileTypeInfo, ValidationSummary, etc.) available at parse time
+using module ..\..\linting\Modules\FrontmatterValidation.psm1
 
 BeforeAll {
+    # Dot-source the main script
     $scriptPath = Join-Path $PSScriptRoot '../../linting/Validate-MarkdownFrontmatter.ps1'
     . $scriptPath
+
     $mockPath = Join-Path $PSScriptRoot '../Mocks/GitMocks.psm1'
     Import-Module $mockPath -Force
     $script:SchemaDir = Join-Path $PSScriptRoot '../../linting/schemas'