feat(#194): update guidance for Test-NovaBuild usage

- Add documentation for using Test-NovaBuild as the authoritative test entrypoint
- Update instructions to prohibit direct Invoke-Pester calls in Nova-managed projects
- Revise various documentation files to reflect the new testing policy

Author: stiwicourage

.github/agents/powershell-developer.agent.md

@@ -45,6 +45,7 @@ Implement PowerShell command and helper changes in the NovaModuleTools style.
 - Preserve existing command names, warning semantics, and output shape.
 - Keep new or heavily changed source functions inside the warning thresholds from `.github/instructions/code-quality-matrix.instructions.md` unless the scope explicitly justifies otherwise.
 - Prefer `./scripts/build/Invoke-ScriptAnalyzerCI.ps1` and `./run.ps1` for normal analyzer loops; use direct `Invoke-ScriptAnalyzer` only for focused local checks that reuse the repository-approved settings.
+- Validate Nova-managed project tests through `Test-NovaBuild`; do not call `Invoke-Pester` directly.
 - When help files change, keep `docs/NovaModuleTools/en-US/*.md` valid for `Import-MarkdownCommandHelp`: use `New-MarkdownCommandHelp` for new files, `Update-MarkdownCommandHelp` after command-surface changes, and `Test-MarkdownCommandHelp` before handoff. A new public `src/public/*.ps1` file is not done until its matching help file exists.
 
 ## Definition of done
@@ -53,6 +54,7 @@ Implement PowerShell command and helper changes in the NovaModuleTools style.
 - Build output still comes from Nova-generated `dist/` files, not hand-authored module files in `src/`.
 - Public/private file ownership still follows the one externally called function per file rule.
 - Every new public entry point has its matching help file.
+- Project test validation ran through `Test-NovaBuild`.
 - Any ScriptAnalyzer findings reported by `run.ps1` or `Invoke-ScriptAnalyzerCI.ps1` are resolved.
 - Every changed or generated text file has been checked and ends with exactly one trailing newline and no extra blank lines at the bottom.
 - Docs/changelog review is complete.

.github/agents/reviewer.agent.md

@@ -25,6 +25,7 @@ Review changes for correctness, maintainability, test coverage, workflow safety,
 - Review changed `src/**/*.ps1` and `tests/**/*.ps1` against `.github/instructions/code-quality-matrix.instructions.md`; flag new or heavily changed code that exceeds the warning thresholds without a clear, explicit reason.
 - Flag public files that do not keep exactly one top-level function, and flag private files that group multiple externally called functions instead of limiting extra functions to same-file support helpers. Also flag file/function name mismatches for public commands or externally called private helpers.
 - Flag broad catch-all test files when focused source-mirrored tests would make ownership clearer.
+- Flag Nova-managed validation that bypasses `Test-NovaBuild` with direct `Invoke-Pester`.
 - Flag any PSScriptAnalyzer rule excludes or suppressions; the code should be fixed instead.
 - Flag unresolved ScriptAnalyzer findings from `run.ps1` or `Invoke-ScriptAnalyzerCI.ps1`; they should be fixed instead of deferred.
 

.github/agents/test-engineer.agent.md

@@ -37,20 +37,22 @@ Improve or maintain the repository's Pester coverage, coverage-gate behavior, an
 
 ## Constraints
 
-- Prefer targeted tests first, then the full repo quality loop.
+- Prefer the smallest `Test-NovaBuild` scope the project already supports, then the full repo quality loop.
 - Keep test files maintainable; passing tests are not enough if Code Health degrades.
 - Reuse existing fixture and support patterns before adding new ones.
 - Do not group unrelated source files into one broad test file when mirrored `tests/public`, `tests/private`, or `tests/classes` ownership is possible.
 - Do not introduce PowerShell 7.x-only test syntax or APIs into a project that targets `5.1` unless compatibility coverage is explicitly part of the scope.
 - If CodeScene flags a regression, refactor the tests or helpers instead of suppressing the finding.
 - Keep new or heavily changed tests inside the warning thresholds from `.github/instructions/code-quality-matrix.instructions.md` unless the scope explicitly justifies otherwise.
 - Use `./scripts/build/Invoke-ScriptAnalyzerCI.ps1` as the normal analyzer entrypoint for changed test/helpers, and only fall back to direct `Invoke-ScriptAnalyzer` for focused local investigation with the repository-approved settings.
+- Use `Test-NovaBuild` as the test entrypoint for Nova-managed projects; do not validate with direct `Invoke-Pester`.
 
 ## Definition of done
 
 - The changed behavior is covered.
 - Each new or changed `src/**/*.ps1` file has a matching source-mirrored test, or the cross-cutting owner test is named explicitly.
 - The touched tests are readable and low-duplication.
+- Validation uses `Test-NovaBuild` for project test execution.
 - Validation and CodeScene implications are addressed.
 - The pre-commit CodeScene safeguard is clean before the work is treated as commit-ready when local CodeScene tooling is available.
 

.github/copilot-instructions.md

@@ -47,6 +47,7 @@ For new or not-yet-scoped work, start with `.github/agents/architect.agent.md` a
 - Do not exclude or suppress PSScriptAnalyzer rules in repository analyzer helpers; fix the code that violates analyzer rules instead.
 - Use `.github/instructions/psscriptanalyzer.instructions.md` as the ScriptAnalyzer workflow source of truth. Prefer `./scripts/build/Invoke-ScriptAnalyzerCI.ps1` and `./run.ps1`, and only use direct `Invoke-ScriptAnalyzer` for focused local checks or deliberate analyzer-tooling changes.
 - Keep `run.ps1` as the local quality loop: run ScriptAnalyzer first, then `Invoke-NovaBuild`, then `Test-NovaBuild`.
+- Use `Test-NovaBuild` as the authoritative test entrypoint in Nova-managed projects. Do not call `Invoke-Pester` directly, because it can bypass Nova's build/import/StrictMode flow and disagree with the result users get later.
 - If `run.ps1` or `./scripts/build/Invoke-ScriptAnalyzerCI.ps1` reports ScriptAnalyzer findings, fix them before review, handoff, or commit. Do not treat a failing local quality loop as an acceptable stopping point.
 - Keep file/function ownership explicit: `src/public/` files should own exactly one top-level function each, and `src/private/` files should expose at most one externally called function per file. Additional private functions may stay only as support helpers used from the same file, and the file name should match the function that owns the file.
 - Use `.github/instructions/code-quality-matrix.instructions.md` as the best-effort quality matrix for `src/**/*.ps1` and `tests/**/*.ps1`; generated projects should follow that guidance through Agentic Copilot files, not by depending on a required `.codescene/code-health-rules.json`.
@@ -88,7 +89,7 @@ For new or not-yet-scoped work, start with `.github/agents/architect.agent.md` a
 Use the smallest validation set that proves the change, then run the repository quality loop before finishing code work:
 
 - local quality loop: `pwsh -NoLogo -NoProfile -File ./run.ps1`
-- targeted tests: `Invoke-Pester -Path ./tests/<File>.Tests.ps1 -Output Detailed`
+- test validation: `Test-NovaBuild`
 - analyzer only: `./scripts/build/Invoke-ScriptAnalyzerCI.ps1`
 - CI-parity coverage flow: `./scripts/build/ci/Invoke-NovaModuleToolsCI.ps1 -OutputDirectory ./artifacts`
 

.github/instructions/testing-policy.instructions.md

@@ -11,7 +11,8 @@ Use this file when changing production code, tests, coverage behavior, or CI tes
 ## Test expectations
 
 - Behavior changes require Pester coverage.
-- Prefer targeted tests close to the changed workflow area before running the full quality loop.
+- Use `Test-NovaBuild` as the authoritative test entrypoint in Nova-managed projects. Do not validate with direct `Invoke-Pester`, because it can bypass Nova's build/import/StrictMode flow and disagree with what users see later.
+- Prefer the smallest `Test-NovaBuild` scope the project already supports before running the full quality loop.
 - Keep test names explicit about the behavior being proven.
 - Reuse `*.TestSupport.ps1` helpers where possible.
 - For every new or changed `src/**/*.ps1` file, add or update the matching source-mirrored `.Tests.ps1` file.
@@ -37,12 +38,13 @@ Use this file when changing production code, tests, coverage behavior, or CI tes
 ## Common pitfalls
 
 - Many tests expect the built module under `dist/NovaModuleTools`; build first when needed.
+- Direct `Invoke-Pester` runs can hide Nova-specific build/import/StrictMode behavior and should not be used as the project test entrypoint.
 - Some support helpers must be dot-sourced and re-exported inside `BeforeAll`.
 - Duplicated test setup can lower Code Health even when tests pass.
 - Docs-only changes usually do not need executable validation, but workflow/test docs must still be kept accurate.
 
 ## Verification
 
-- Targeted Pester file(s)
+- `Test-NovaBuild`
 - `./scripts/build/Invoke-ScriptAnalyzerCI.ps1` when PowerShell code changed
 - `pwsh -NoLogo -NoProfile -File ./run.ps1` before completion

.github/prompts/implement-issue.prompt.md

@@ -24,12 +24,13 @@ Implement the issue in the NovaModuleTools repository using the repository-local
 12. Keep file/function ownership explicit: one externally called function per file, with private-file extras limited to same-file support helpers, and keep the file name aligned to the entry function.
 13. Before handoff, review every changed or generated text file and normalize it to exactly one trailing newline with no extra blank lines at the bottom.
 14. Add or update the matching source-mirrored Pester file for every changed `src/**/*.ps1` file; if the behavior is genuinely cross-cutting, document which integration/guardrail test owns it and why a mirrored unit test is not practical.
-15. Add or update valid PlatyPS-compatible help under `docs/NovaModuleTools/en-US/` when public commands or public classes change. Use `New-MarkdownCommandHelp` for new help, `Update-MarkdownCommandHelp` after command-surface changes, and `Test-MarkdownCommandHelp` before handoff; do not replace command help with plain Markdown prose.
-16. For every new public entry point, create its matching help file immediately in the same change.
-17. Review `README.md`, `CONTRIBUTING.md`, `CHANGELOG.md`, `RELEASE_NOTE.md`, help docs, and `docs/*.html` as applicable.
-18. If a commit message is requested, derive it from `$GIT_BRANCH_NAME` and the implemented change using the repository's Conventional Commit rules.
-19. Run the relevant validation, then summarize what changed, why, and how it was verified.
-20. If that summary is returned as Markdown or copy-ready UI output, format it according to the `markdown-authoring` skill (`.github/skills/markdown-authoring/SKILL.md`).
+15. Validate Nova-managed project tests through `Test-NovaBuild`; do not call `Invoke-Pester` directly because it can bypass Nova's build/import/StrictMode flow.
+16. Add or update valid PlatyPS-compatible help under `docs/NovaModuleTools/en-US/` when public commands or public classes change. Use `New-MarkdownCommandHelp` for new help, `Update-MarkdownCommandHelp` after command-surface changes, and `Test-MarkdownCommandHelp` before handoff; do not replace command help with plain Markdown prose.
+17. For every new public entry point, create its matching help file immediately in the same change.
+18. Review `README.md`, `CONTRIBUTING.md`, `CHANGELOG.md`, `RELEASE_NOTE.md`, help docs, and `docs/*.html` as applicable.
+19. If a commit message is requested, derive it from `$GIT_BRANCH_NAME` and the implemented change using the repository's Conventional Commit rules.
+20. Run the relevant validation, then summarize what changed, why, and how it was verified.
+21. If that summary is returned as Markdown or copy-ready UI output, format it according to the `markdown-authoring` skill (`.github/skills/markdown-authoring/SKILL.md`).
 
 ## Repository-specific reminders
 

.github/prompts/improve-test-coverage.prompt.md

@@ -12,11 +12,12 @@ Improve changed-code coverage in NovaModuleTools without lowering maintainabilit
 6. Follow `.github/instructions/psscriptanalyzer.instructions.md` when test code or test helpers change. Prefer `./scripts/build/Invoke-ScriptAnalyzerCI.ps1` for repo-standard analyzer runs, and use direct `Invoke-ScriptAnalyzer` only for focused local checks that reuse the repo-approved settings.
 7. Add the smallest test that proves the missing behavior.
 8. If setup is duplicated, refactor the tests before adding more assertions.
-9. Re-run the focused tests, then the repository quality loop if code changed.
+9. Re-run `Test-NovaBuild`, then the repository quality loop if code changed. Do not validate a Nova-managed project with direct `Invoke-Pester`.
 10. Recheck CodeScene coverage or Code Health if that was the original failure.
 
 ## Repository-specific reminders
 
 - Many tests expect a built `dist/NovaModuleTools` module.
 - The CI coverage flow writes `artifacts/pester-coverage.cobertura.xml`.
+- Use `Test-NovaBuild` as the project test entrypoint; direct `Invoke-Pester` can miss Nova-specific strict-mode behavior.
 - Do not "fix" coverage by weakening assertions or suppressing CodeScene warnings.

.github/prompts/review-change.prompt.md

@@ -9,7 +9,7 @@ Review a NovaModuleTools change set with emphasis on correctness, maintainabilit
 3. Check changed `src/**/*.ps1` and `tests/**/*.ps1` against `.github/instructions/code-quality-matrix.instructions.md`.
 4. Check changed PowerShell validation flow against `.github/instructions/psscriptanalyzer.instructions.md`; flag direct analyzer usage that bypasses the repository wrapper or repo-approved settings without a clear reason.
 5. Check changed `docs/NovaModuleTools/en-US/*.md` against `.github/instructions/platyps-help.instructions.md` when command help was added or updated; flag files that do not follow the `New-MarkdownCommandHelp` / `Update-MarkdownCommandHelp` / `Test-MarkdownCommandHelp` workflow, miss a new public entry point's matching help file, or break the required PlatyPS section structure.
-6. Check whether tests, docs, and changelog updates match the change.
+6. Check whether tests, docs, and changelog updates match the change, and flag Nova-managed validation that bypasses `Test-NovaBuild` with direct `Invoke-Pester`.
 7. Call out the smallest set of meaningful issues first.
 8. Note any missing validation or follow-up work.
 9. If the review is returned as Markdown or copy-ready UI text, format it according to the `markdown-authoring` skill (`.github/skills/markdown-authoring/SKILL.md`).

.github/skills/pester-testing/SKILL.md

@@ -13,7 +13,7 @@ Use this skill when adding tests, closing coverage gaps, fixing regressions, or
 
 - `tests/*.Tests.ps1`
 - `tests/*TestSupport.ps1`
-- `pwsh -NoLogo -NoProfile -Command "Invoke-Pester -Path ./tests/<File>.Tests.ps1 -Output Detailed"`
+- `Test-NovaBuild`
 - `pwsh -NoLogo -NoProfile -File ./run.ps1`
 - `./scripts/build/ci/Invoke-NovaModuleToolsCI.ps1 -OutputDirectory ./artifacts`
 
@@ -22,6 +22,7 @@ Use this skill when adding tests, closing coverage gaps, fixing regressions, or
 - Match existing `Describe` / `It` naming style.
 - Prefer support helpers for repeated setup.
 - Build/import the dist module when the test file expects it.
+- Use `Test-NovaBuild` as the authoritative test entrypoint in Nova-managed projects. Do not validate with direct `Invoke-Pester`, because it can miss the Nova build/import/StrictMode flow.
 - Add coverage for both happy paths and explicit warnings/errors when behavior changed.
 - For every new or changed `src/**/*.ps1` file, add or update one focused test file that mirrors the source path under `tests/`.
 - Keep test files and helpers compatible with `project.json` `Manifest.PowerShellHostVersion`; if a project targets `5.1`, do not introduce PowerShell 7.x-only syntax, cmdlets, parameters, or APIs in the tests.
@@ -34,13 +35,14 @@ Use this skill when adding tests, closing coverage gaps, fixing regressions, or
 - Forgetting that many tests assume `dist/NovaModuleTools` already exists
 - Duplicating setup instead of extending `*.TestSupport.ps1`
 - Exporting helper functions at the wrong time in test lifecycle
+- Validating a Nova-managed project with direct `Invoke-Pester` instead of `Test-NovaBuild`
 - Passing tests while still degrading Code Health through duplication
 - Grouping unrelated source files into one large test file when a source-mirrored layout would make ownership clearer
 - Adding source files without a matching mirrored test or an explicit cross-cutting-test justification
 - Ignoring the test-code matrix and letting new or heavily changed tests grow beyond the warning thresholds without justification
 
 ## Verification
 
-- Run the touched test file(s) directly first
+- Run `Test-NovaBuild`
 - Run `./run.ps1` before finishing code changes
 - If coverage is the goal, inspect `artifacts/pester-coverage.cobertura.xml` via the CI helper flow

.github/skills/powershell-module-development/SKILL.md

@@ -60,6 +60,6 @@ Use this skill when changing public commands, private helpers, CLI routing suppo
 
 ## Verification
 
-- Targeted Pester file(s) for the changed behavior
+- `Test-NovaBuild` for the changed behavior
 - `tests/ArchitectureGuardrails.Tests.ps1` implications checked
 - `pwsh -NoLogo -NoProfile -File ./run.ps1`