feat(changelog): add template-level CHANGELOG.md (CalVer)

Track changes to the PowerShell module template itself with its own
changelog, separate from the downstream-module starter changelog.

CHANGELOG.md (new) — template's own history. Uses Calendar Versioning
(YYYY.MM.DD) since the template has no API contract for SemVer to
describe; date-based answers the question downstream consumers actually
ask ("how stale is my init?"). First entry [2026.04.29] captures the
five chunks landed in the chore/template-sync branch.

Initialize-Template.ps1:
- Add CHANGELOG.md to the substitution-loop exclusion list. Without
  this, init would rewrite literal {{ModuleName}} mentions in the
  template's history to the user's chosen module name.
- After the README.template.md → README.md swap, add a parallel
  CHANGELOG.template.md → CHANGELOG.md swap so downstream modules
  receive the placeholder-laden starter changelog (the existing
  CHANGELOG.template.md, formerly CHANGELOG.md), not the template's
  own history.

tests/Manifest.tests.ps1:
- Skip the "Changelog and manifest versions are the same" assertion
  when running on the un-initialized template, where CHANGELOG.md
  holds the template's CalVer version which intentionally diverges
  from the {{ModuleName}}.psd1 ModuleVersion. Marker: presence of
  CHANGELOG.template.md (exists only pre-init; survives init's
  substitution loop because nothing in the path matches a placeholder
  token). The "valid version in changelog" assertion stays — PowerShell
  parses [Version]'2026.4.29' fine.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: tablackburn

CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes to this template will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project uses [Calendar Versioning](https://calver.org/) (`YYYY.MM.DD`).
+
+For the changelog of a *module initialized from this template*, see the module's
+own `CHANGELOG.md` (generated from `CHANGELOG.template.md` during init).
+
+## [Unreleased]
+
+## [2026.04.29] - 2026-04-29
+
+### Added
+
+- SemVer-aware dependency version checks: new `tests/ManifestHelpers.psm1` exporting `Test-VersionConstraint`. `tests/Manifest.tests.ps1` now differentiates `RequiredVersion` / `ModuleVersion` / `MaximumVersion`, accepts both string and hashtable shapes in `requirements.psd1`, and detects duplicate `RequiredModules` entries.
+- README split: template-facing `README.md` (what GitHub visitors see) and module-facing `README.template.md` (substituted into `README.md` during init).
+- `docs/en-US/about_{{ModuleName}}.help.md` stub for `Get-Help about_<Module>`. `Initialize-Template.ps1` now also renames `{{ModuleName}}` files in `docs/en-US/`.
+- `.gitattributes` marking `docs/en-US/*` as `linguist-generated`.
+- `.markdownlint-cli2.jsonc` config (relax MD013 in tables/code, allow MD024 siblings, ignore generated docs and `instructions/`).
+
+### Changed
+
+- `PSScriptAnalyzerSettings.psd1`: replaced one-line `@{ IncludeRules = @('*') }` with the structured form (Include/Exclude/Rules + commented compat scaffold).
+- Bumped `PSScriptAnalyzer` 1.24.0 → 1.25.0.
+
+### Fixed
+
+- `tests/Help.tests.ps1`: replaced undefined `$parameterNames` with `$commandParameterNames` in the help-vs-code parameter check (was silently asserting against `$null`).
+- `{{ModuleName}}/{{ModuleName}}.psm1`: dot-source catch block now preserves the original `ErrorRecord` via bare `throw` (was `throw $_`, which wrapped the error).
+
+[Unreleased]: https://github.com/tablackburn/PowerShellModuleTemplate/compare/v2026.04.29...HEAD
+[2026.04.29]: https://github.com/tablackburn/PowerShellModuleTemplate/releases/tag/v2026.04.29

Initialize-Template.ps1

@@ -180,6 +180,7 @@ $filesToProcess = Get-ChildItem -Path $PSScriptRoot -Recurse -File | Where-Objec
     $_.FullName -notmatch '[\\/]Output[\\/]' -and
     $_.FullName -notmatch '[\\/]out[\\/]' -and
     $_.Name -ne 'Initialize-Template.ps1' -and
+    $_.Name -ne 'CHANGELOG.md' -and
     $_.Extension -in @('.ps1', '.psm1', '.psd1', '.md', '.json', '.yml', '.yaml', '.xml', '.txt', '')
 }
 
@@ -287,6 +288,15 @@ if (Test-Path -Path $readmeTemplate) {
     Write-Host '  Generated module README.md from template' -ForegroundColor Green
 }
 
+# Replace template-facing CHANGELOG.md with the module-facing CHANGELOG.template.md
+# (placeholders inside CHANGELOG.template.md were already substituted by the file-processing loop above)
+$changelogTemplate = Join-Path -Path $PSScriptRoot -ChildPath 'CHANGELOG.template.md'
+$changelogPath = Join-Path -Path $PSScriptRoot -ChildPath 'CHANGELOG.md'
+if (Test-Path -Path $changelogTemplate) {
+    Move-Item -Path $changelogTemplate -Destination $changelogPath -Force
+    Write-Host '  Generated module CHANGELOG.md from template' -ForegroundColor Green
+}
+
 # Initialize Git repository if requested
 if (-not $NoGitInit) {
     $gitFolder = Join-Path -Path $PSScriptRoot -ChildPath '.git'

tests/Manifest.tests.ps1

@@ -86,6 +86,14 @@ BeforeDiscovery {
     }
     $manifestData = Test-ModuleManifest @testModuleManifestParameters
     $dependencies = $manifestData.RequiredModules
+
+    # When running on the un-initialized template, CHANGELOG.md tracks the template's
+    # CalVer version (YYYY.MM.DD), which deliberately decouples from the manifest's
+    # ModuleVersion. Skip the equality assertion in that case; downstream modules (post-init)
+    # keep the assertion. Marker: CHANGELOG.template.md exists only pre-init —
+    # Initialize-Template.ps1 moves it onto CHANGELOG.md during init. The marker survives
+    # the init substitution loop because no token in the path matches a {{Placeholder}}.
+    $isTemplate = Test-Path -LiteralPath (Join-Path -Path $Env:BHProjectPath -ChildPath 'CHANGELOG.template.md')
 }
 BeforeAll {
     # Check if the BHBuildOutput environment variable exists to determine if this test is running in a psake
@@ -180,7 +188,7 @@ Describe 'Module manifest' {
             $changelogVersion -as [Version] | Should -Not -BeNullOrEmpty
         }
 
-        It 'Changelog and manifest versions are the same' {
+        It 'Changelog and manifest versions are the same' -Skip:$isTemplate {
             $changelogVersion -as [Version] | Should -Be ( $manifestData.Version -as [Version] )
         }