feat(#194): enhance text file formatting rules and add guardrails

- update documentation to specify newline and blank line requirements
- introduce Test-TextFileFormatting script to enforce formatting rules
- add tests to validate text file formatting compliance

Author: stiwicourage

CHANGELOG.md

@@ -17,6 +17,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
     - The generated guidance now expresses PowerShell source/helper-script maintainability rules through `code-quality-matrix.instructions.md` and keeps test-specific design guidance in the testing instruction/skill files.
       - The generated guidance now requires `docs/<ProjectName>/en-US/*.md` to stay valid PlatyPS help with YAML metadata and build-compatible structure, tells agents to use the documented `New-MarkdownCommandHelp` / `Update-MarkdownCommandHelp` / `Test-MarkdownCommandHelp` workflow instead of replacing command help with plain Markdown that breaks `nova build`, and requires a matching help file for every new public entry point in the same change.
       - The generated PowerShell guidance now requires agents to review every changed or generated text file before handoff and normalize the file ending to exactly one trailing newline with no extra blank lines at the bottom.
+      - The starter now also ships a generated `scripts/build/Test-TextFileFormatting.ps1` helper and, when project tests are enabled, a `tests/TextFileFormatting.Tests.ps1` guardrail so trailing blank-line violations fail `Test-NovaBuild` instead of relying on instructions alone.
     - When Git is enabled during either scaffold flow, Nova now creates or updates a default `.gitignore` in the generated project root and appends only the missing Nova-managed artifact entries instead of overwriting existing ignore rules.
     - `Initialize-NovaModule` and `% nova init` now check for newer NovaModuleTools releases before the first interactive scaffold question and reuse the same non-blocking update warning behavior already used by build.
 

README.md

@@ -506,7 +506,8 @@ Packaged resources that ship with the module, including:
 - the packaged example project under `src/resources/example/`
 - the Agentic Copilot starter package under `src/resources/agentic-copilot/`
 
-The example project is both a shipped resource and a maintained working reference. The Agentic Copilot starter package is generated from Nova's repository-local agentic guidance, including Nova build/test/package expectations, `project.json` `Manifest.PowerShellHostVersion` compatibility guidance, generated `dist` module files, command-help ownership, source-mirrored test guidance, Test-NovaBuild-only project test guidance that forbids direct `Invoke-Pester` so agent validation matches Nova's build/import/StrictMode flow, guidance that ScriptAnalyzer findings reported by `run.ps1` must be fixed before handoff, explicit PSScriptAnalyzer workflow guidance for `./scripts/build/Invoke-ScriptAnalyzerCI.ps1`, `./run.ps1`, and focused `Invoke-ScriptAnalyzer` usage, explicit public/private PowerShell file ownership rules, best-effort source/helper-script maintainability guidance plus separate test-design guidance that live in Agentic Copilot files, explicit valid-PlatyPS help guidance for
+The example project is both a shipped resource and a maintained working reference. The Agentic Copilot starter package is generated from Nova's repository-local agentic guidance, including Nova build/test/package expectations, `project.json` `Manifest.PowerShellHostVersion` compatibility guidance, generated `dist` module files, command-help ownership, source-mirrored test guidance, Test-NovaBuild-only project test guidance that forbids direct `Invoke-Pester` so agent validation matches Nova's build/import/StrictMode flow, guidance that ScriptAnalyzer findings reported by `run.ps1` must be fixed before handoff, explicit PSScriptAnalyzer workflow guidance for `./scripts/build/Invoke-ScriptAnalyzerCI.ps1`, `./run.ps1`, and focused `Invoke-ScriptAnalyzer` usage, explicit public/private PowerShell file ownership rules, best-effort source/helper-script maintainability guidance plus separate test-design guidance that live in Agentic Copilot files, a generated
+`scripts/build/Test-TextFileFormatting.ps1` helper and matching `tests/TextFileFormatting.Tests.ps1` guardrail when Pester is enabled so extra blank lines at EOF fail the project test flow, and explicit valid-PlatyPS help guidance for
 `docs/<ProjectName>/en-US/*.md` that uses the documented `New-MarkdownCommandHelp` / `Update-MarkdownCommandHelp` /
 `Test-MarkdownCommandHelp` workflow and requires a matching help file for every new public entry point in the same change, and a strict file-ending rule for changed or generated text files. When the init flow adds that starter package, it also asks for a short project name so scaffolded guidance can replace placeholders such as `Invoke-<ShortName>*`. Run
 `./scripts/build/Sync-AgenticCopilotScaffold.ps1` after changing `.github/agents/`, `.github/instructions/`,

RELEASE_NOTE.md

@@ -7,6 +7,7 @@ This file summarizes public cmdlet, CLI, configuration, and migration changes fo
 ### Added
 - `Initialize-NovaModule` and `% nova init` now offer an optional Agentic Copilot starter package in both the minimal and example interactive scaffold flows.
     - The starter package follows a filtered mirror of Nova's maintained agentic guidance so newly scaffolded projects receive a broader Nova-style agentic baseline without Nova-specific surfaces.
+  - The starter now includes a generated text-file-formatting guardrail helper and, when project tests are enabled, a Pester guardrail test so trailing blank-line violations fail the normal project test flow.
   - Before the first interactive scaffold question, Nova now also warns when a newer NovaModuleTools release is available by reusing the same non-blocking update warning behavior already used by `build`.
 
 ### Changed

docs/NovaModuleTools/en-US/Initialize-NovaModule.md

@@ -30,7 +30,7 @@ PS> Initialize-NovaModule [-Path <string>] [-Example] [-WhatIf] [-Confirm] [<Com
 The command collects project details interactively, including the module name, description, version, author, minimum PowerShell version, Git initialization, and an optional Agentic Copilot starter package. Before the first interactive question, Nova checks whether a newer `NovaModuleTools` release is available and warns without blocking the scaffold flow. When Git initialization is enabled, Nova also creates or updates a default `.gitignore` in the generated project root so common local and CI artifact paths such as `artifacts/`, `dist/`, `run.ps1`, and `reload.ps1` are ignored from the start. Existing `.gitignore` files are preserved and only receive the missing Nova-managed entries. When you enable the Agentic package, Nova also asks for a project short name used in generated guidance placeholders such as `Invoke-<ShortName>*`; for NovaModuleTools the short name is `Nova`, but it could also have been
 `NMT`. The Agentic package follows Nova's maintained agentic guidance through a filtered starter mirror, including Nova build/test/package expectations, `project.json`
 `Manifest.PowerShellHostVersion` compatibility guidance, strict ScriptAnalyzer guidance without excluded rules, generated `dist` module files, command-help ownership, source-mirrored test guidance, guidance that ScriptAnalyzer findings reported by
-`run.ps1` must be fixed before handoff, explicit PSScriptAnalyzer workflow guidance for `./scripts/build/Invoke-ScriptAnalyzerCI.ps1`, `./run.ps1`, and focused `Invoke-ScriptAnalyzer` usage, explicit public/private PowerShell file ownership rules, best-effort source/helper-script maintainability guidance plus separate test-design guidance delivered through Agentic Copilot files, explicit valid-PlatyPS help guidance for `docs/<ProjectName>/en-US/*.md` that uses `New-MarkdownCommandHelp`, `Update-MarkdownCommandHelp`, and `Test-MarkdownCommandHelp`, and a strict file-ending rule for changed or generated text files. For the standard scaffold, the interactive flow also includes optional basic Pester support.
+`run.ps1` must be fixed before handoff, explicit PSScriptAnalyzer workflow guidance for `./scripts/build/Invoke-ScriptAnalyzerCI.ps1`, `./run.ps1`, and focused `Invoke-ScriptAnalyzer` usage, explicit public/private PowerShell file ownership rules, best-effort source/helper-script maintainability guidance plus separate test-design guidance delivered through Agentic Copilot files, a generated `scripts/build/Test-TextFileFormatting.ps1` helper plus `tests/TextFileFormatting.Tests.ps1` when project tests are enabled so trailing blank-line violations fail the project test flow, explicit valid-PlatyPS help guidance for `docs/<ProjectName>/en-US/*.md` that uses `New-MarkdownCommandHelp`, `Update-MarkdownCommandHelp`, and `Test-MarkdownCommandHelp`, and a strict file-ending rule for changed or generated text files. For the standard scaffold, the interactive flow also includes optional basic Pester support.
 
 If you enter an invalid answer during the interactive flow, `Initialize-NovaModule` reports the validation problem immediately and retries that prompt before it continues to the next question.
 
@@ -140,7 +140,7 @@ This cmdlet does not emit an output object.
 ## NOTES
 
 Generated projects start with NovaModuleTools defaults for recursive discovery, source markers, duplicate-function validation, and—when Git is enabled—a default `.gitignore` for common local and CI artifact paths. The packaged example scaffold keeps its bundled example source and tests, while still updating prompt-driven metadata such as project name, description, version, author, and PowerShell host version. The optional Agentic Copilot starter package adds repository-local Copilot workflow files under the project root and `.github/` that tell agents to keep build/test/package workflows on Nova, treat `project.json` `Manifest.PowerShellHostVersion` as the PowerShell compatibility target, run ScriptAnalyzer before build/test through the repo-standard `Invoke-ScriptAnalyzerCI.ps1` / `run.ps1` workflow, fix any ScriptAnalyzer findings before handoff, run project tests through `Test-NovaBuild` instead of direct `Invoke-Pester`, leave `.psm1` / `.psd1` files to generated
-`dist` output, generate and validate command help with the Microsoft.PowerShell.PlatyPS cmdlets instead of hand-written Markdown structure, require a matching help file for every new public entry point in the same change, and mirror new tests to source files.
+`dist` output, generate and validate command help with the Microsoft.PowerShell.PlatyPS cmdlets instead of hand-written Markdown structure, require a matching help file for every new public entry point in the same change, mirror new tests to source files, and add a text-file-formatting guardrail helper plus a Pester guardrail test when project tests are enabled.
 
 `Initialize-NovaModule` uses `SupportsShouldProcess`, so `Get-Help Initialize-NovaModule -Full` surfaces native
 `-WhatIf` and

scripts/build/Sync-AgenticCopilotScaffold.psd1

@@ -16,6 +16,8 @@
         'CHANGELOG.md'
         'RELEASE_NOTE.md'
         '.github/pull_request_template.md'
+        'scripts/build/Test-TextFileFormatting.ps1'
+        'tests/TextFileFormatting.Tests.ps1'
     )
 
     ExcludedPaths = @(

src/private/scaffold/InitializeNovaModuleAgenticCopilotScaffold.ps1

@@ -90,6 +90,80 @@ function Expand-NovaModuleAgenticCopilotTemplateContent {
     return $expandedContent
 }
 
+function Test-NovaModuleAgenticCopilotTemplateFileEnabled {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)][hashtable]$Answer,
+        [Parameter(Mandatory)][string]$RelativePath,
+        [switch]$Example
+    )
+
+    if (-not $RelativePath.StartsWith('tests/', [System.StringComparison]::OrdinalIgnoreCase)) {
+        return $true
+    }
+
+    if ($Example) {
+        return $true
+    }
+
+    return $Answer.ContainsKey('EnablePester') -and $Answer.EnablePester -eq 'Yes'
+}
+
+function ConvertTo-NovaModuleAgenticCopilotNormalizedFileContent {
+    [CmdletBinding()]
+    param(
+        [AllowEmptyString()][string]$Content
+    )
+
+    if ($null -eq $Content -or $Content.Length -eq 0) {
+        return $Content
+    }
+
+    $trimmedContent = $Content.TrimEnd([char[]]@([char]13, [char]10))
+    if ($trimmedContent.Length -eq 0) {
+        return $Content
+    }
+
+    $lineEnding = if ( $Content.Contains("`r`n")) {
+        "`r`n"
+    } else {
+        "`n"
+    }
+
+    return $trimmedContent + $lineEnding
+}
+
+function Get-NovaModuleAgenticCopilotDestinationContent {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)][string]$RelativePath,
+        [Parameter(Mandatory)][string]$TemplateContent,
+        [Parameter(Mandatory)][System.Collections.IDictionary]$ScaffoldContext
+    )
+
+    if ($RelativePath -eq 'README.md') {
+        return Get-NovaModuleAgenticCopilotReadmeContent -TemplateContent $TemplateContent -TokenMap $ScaffoldContext['TokenMap'] -ProjectRoot $ScaffoldContext['ProjectRoot'] -Example:([bool]$ScaffoldContext['Example'])
+    }
+
+    return Expand-NovaModuleAgenticCopilotTemplateContent -Content $TemplateContent -TokenMap $ScaffoldContext['TokenMap']
+}
+
+function Write-NovaModuleAgenticCopilotDestinationFile {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)][string]$DestinationPath,
+        [Parameter(Mandatory)][string]$Content
+    )
+
+    $destinationDirectory = Split-Path -Parent $DestinationPath
+    if (-not (Test-Path -LiteralPath $destinationDirectory)) {
+        New-Item -ItemType Directory -Path $destinationDirectory -Force | Out-Null
+    }
+
+    $normalizedContent = ConvertTo-NovaModuleAgenticCopilotNormalizedFileContent -Content $Content
+    Set-Content -LiteralPath $DestinationPath -Value $normalizedContent -Encoding utf8 -NoNewline
+}
+
 function Initialize-NovaModuleAgenticCopilotScaffold {
     [CmdletBinding()]
     param(
@@ -100,23 +174,22 @@ function Initialize-NovaModuleAgenticCopilotScaffold {
 
     $templateRoot = Get-NovaModuleAgenticCopilotTemplateRoot
     $tokenMap = Get-NovaModuleAgenticCopilotTemplateTokenMap -Answer $Answer
+    $scaffoldContext = [ordered]@{
+        TokenMap = $tokenMap
+        ProjectRoot = $ProjectRoot
+        Example = [bool]$Example
+    }
     $templateFileList = @(Get-ChildItem -LiteralPath $templateRoot -File -Recurse -Force | Sort-Object FullName)
 
     foreach ($templateFile in $templateFileList) {
         $relativePath = Get-NormalizedRelativePath -Root $templateRoot -FullName $templateFile.FullName
-        $destinationPath = Join-Path $ProjectRoot ($relativePath -replace '/', [System.IO.Path]::DirectorySeparatorChar)
-        $destinationDirectory = Split-Path -Parent $destinationPath
-        if (-not (Test-Path -LiteralPath $destinationDirectory)) {
-            New-Item -ItemType Directory -Path $destinationDirectory -Force | Out-Null
+        if (-not (Test-NovaModuleAgenticCopilotTemplateFileEnabled -Answer $Answer -RelativePath $relativePath -Example:$Example)) {
+            continue
         }
 
+        $destinationPath = Join-Path $ProjectRoot ($relativePath -replace '/', [System.IO.Path]::DirectorySeparatorChar)
         $templateContent = Get-Content -LiteralPath $templateFile.FullName -Raw
-        $destinationContent = if ($relativePath -eq 'README.md') {
-            Get-NovaModuleAgenticCopilotReadmeContent -TemplateContent $templateContent -TokenMap $tokenMap -ProjectRoot $ProjectRoot -Example:$Example
-        } else {
-            Expand-NovaModuleAgenticCopilotTemplateContent -Content $templateContent -TokenMap $tokenMap
-        }
-
-        Set-Content -LiteralPath $destinationPath -Value $destinationContent -Encoding utf8
+        $destinationContent = Get-NovaModuleAgenticCopilotDestinationContent -RelativePath $relativePath -TemplateContent $templateContent -ScaffoldContext $scaffoldContext
+        Write-NovaModuleAgenticCopilotDestinationFile -DestinationPath $destinationPath -Content $destinationContent
     }
 }

src/resources/agentic-copilot/AGENTS.md

@@ -7,7 +7,7 @@ This repository uses an Agentic Copilot workflow.
 This is a Nova-managed PowerShell module project. Use Nova commands and `project.json` for build, test, package, and release behavior. Match PowerShell code, tests, and examples to `project.json` `Manifest.PowerShellHostVersion`; if it is `5.1`, avoid PowerShell 7.x-only features. Fix any ScriptAnalyzer findings reported by `run.ps1` before handoff. Follow `.github/instructions/psscriptanalyzer.instructions.md` as the ScriptAnalyzer workflow source of truth, with `./scripts/build/Invoke-ScriptAnalyzerCI.ps1` and `./run.ps1` as the normal entrypoints. Use `Test-NovaBuild` as the project test entrypoint and do not validate with direct `Invoke-Pester`. Keep one externally called function per file and match the file name to that function, with private-file extras limited to related same-file top-level support helpers and no nested function declarations inside PowerShell functions. Follow `.github/instructions/code-quality-matrix.instructions.md` for source/helper-script maintainability and
 `.github/instructions/testing-policy.instructions.md` for test design. Keep
 `docs/{{ProjectName}}/en-US/*.md` as valid PlatyPS command help by using `New-MarkdownCommandHelp`,
-`Update-MarkdownCommandHelp`, and `Test-MarkdownCommandHelp`, and create the matching help file immediately for every new public entry point. End every changed or generated text file with exactly one trailing newline and no extra blank lines at the bottom. Do not hand-create module
+`Update-MarkdownCommandHelp`, and `Test-MarkdownCommandHelp`, and create the matching help file immediately for every new public entry point. End every changed or generated text file immediately after exactly one newline terminator with no blank spacer line at the bottom. Use `pwsh -NoLogo -NoProfile -File ./scripts/build/Test-TextFileFormatting.ps1` for a focused check, and keep `tests/TextFileFormatting.Tests.ps1` passing when Pester is enabled. Do not hand-create module
 `.psm1` or module `.psd1` files in source. Do not exclude or suppress PSScriptAnalyzer rules.
 
 ## Workflow

src/resources/agentic-copilot/CONTRIBUTING.md

@@ -18,7 +18,7 @@ Before opening a pull request:
 - keep one externally called function per file and match the file name to that function; private files may keep extra related functions only as same-file top-level support helpers, and PowerShell functions must not declare nested functions inside their bodies
 - follow `.github/instructions/code-quality-matrix.instructions.md` for source/helper-script maintainability and `.github/instructions/testing-policy.instructions.md` for test design
 - keep `docs/{{ProjectName}}/en-US/*.md` as valid PlatyPS command help by using `New-MarkdownCommandHelp`, `Update-MarkdownCommandHelp`, and `Test-MarkdownCommandHelp`
-- make every changed or generated text file end with exactly one trailing newline and no extra blank lines at the bottom
+- make every changed or generated text file end immediately after exactly one newline terminator with no blank spacer line at the bottom; use `pwsh -NoLogo -NoProfile -File ./scripts/build/Test-TextFileFormatting.ps1` for a focused check, and keep `tests/TextFileFormatting.Tests.ps1` green when Pester is enabled
 - do not exclude or suppress PSScriptAnalyzer rules
 - do not hand-create module `.psm1` or module `.psd1` files in source
 - review `README.md`, `CHANGELOG.md`, and `RELEASE_NOTE.md` when the workflow or public behavior changed