Enhance NovaModule initialization, testing, and documentation

.codescene/code-health-rules.json

@@ -1,5 +1,5 @@
 {
-  "usage": "Persist this file inside your repositories as .codescene/code-health-rules.json Keep the rules you want to override, remove the rest for simplicity and an easy overview.Override the code health rules by changing the default 1.0 value to a lower relative weight. A value of 0.0 disables the rule. A value of 0.5 still implies a code health hit but only at 50% of the default impact. Note that you can specify multiple rule sets and use the matching-content-path to control to which parts or languages the rules apply. This makes it possible to differentiate between test vs application code, or tailor rules to specific languages. In case multiple rule sets match a piece of content, then we prioritize the first mathcing set of rules.",
+  "usage": "Keep the rules you want to override, remove the rest for simplicity and an easy overview. Override the code health rules by changing the default 1.0 value to a lower relative weight. A value of 0.0 disables the rule. A value of 0.5 still implies a code health hit but only at 50% of the default impact. Note that you can specify multiple rule sets and use the matching-content-path to control to which parts or languages the rules apply. This makes it possible to differentiate between test vs application code, or tailor rules to specific languages. In case multiple rule sets match a piece of content, then we prioritize the first matching set of rules.",
   "rule_sets": [
     {
       "thresholds": [

.github/actions/check-coverage/action.yml

@@ -23,12 +23,27 @@ runs:
         unzip -oq "$(pwd)/cs-coverage.zip"
         chmod +x "$(pwd)/cs-coverage"
 
+    - name: Normalize JaCoCo coverage paths
+      shell: bash
+      run: |
+        set -euo pipefail
+        shopt -s globstar nullglob
+        files=( ${{ inputs.coverage-files }} )
+        if [ ${#files[@]} -eq 0 ]; then
+          echo "No coverage files matched '${{ inputs.coverage-files }}' for normalization."
+          exit 0
+        fi
+
+        for file in "${files[@]}"; do
+          pwsh -NoLogo -NoProfile -File ./scripts/build/ci/Repair-CodeSceneJaCoCoCoverage.ps1 -Path "$file"
+        done
+
     - name: Run CodeScene coverage gate check
       shell: bash
       env:
         CS_PROJECT_URL: ${{ inputs.project-url }}
         CS_ACCESS_TOKEN: ${{ inputs.access-token }}
       run: |
         set -euo pipefail
-        find "$(pwd)" -name '*.cobertura.xml' -print
+        find "$(pwd)" -name 'coverage.xml' -print
         "$(pwd)/cs-coverage" check --verbose --coverage-files "${{ inputs.coverage-files }}"

.github/agents/architect.agent.md

@@ -7,20 +7,21 @@ description: Designs and scopes NovaModuleTools changes through a discussion-fir
 
 ## Purpose
 
-Design or reshape changes that cross public commands, private helper boundaries, workflows, documentation layers, or
-release automation.
+Design or reshape changes that cross public commands, private helper boundaries, workflows, documentation layers, or release automation.
 
 ## Responsibilities
 
-- Default new work to analysis first: clarify the problem, scope, risks, affected layers, validation needs, and
-  documentation impact before implementation starts.
+- Default new work to analysis first: clarify the problem, scope, risks, affected layers, validation needs, and documentation impact before implementation starts.
 - Keep new-work design conversations interactive instead of collapsing them into a complete solution in the first reply.
 - Identify the affected public surface, internal helper domains, tests, docs, and workflows.
 - Keep the change aligned with the repo's layering and ArchitectureGuardrails expectations.
 - Recommend the smallest structure that solves the problem cleanly.
 - Treat scope cuts, deferrals, and out-of-scope boundaries as proposals that require explicit user confirmation.
-- Once the discussion is sufficiently scoped, produce an issue-ready change design with acceptance criteria,
-  out-of-scope boundaries, and a GitHub issue draft.
+- Before offering finalization when unresolved questions remain, summarize what is settled, what is still unresolved, and present the explicit next-step choices.
+- Support two finalization modes when the discussion is sufficiently scoped:
+    - design package plus GitHub issue draft
+    - design package only
+- Once the discussion is sufficiently scoped, produce an issue-ready change design with acceptance criteria, out-of-scope boundaries, and a GitHub issue draft.
 
 ## Inputs to inspect
 
@@ -36,11 +37,12 @@ release automation.
 ## Skills to use
 
 - `/powershell-module-development`
-- `/github-actions`
 - `/release-and-changelog`
+- `/markdown-authoring`
+- `/building-maintainable-code`
+- `/github-actions`
 - `/codescene-quality`
 - `/guiding-refactoring-with-code-health`
-- `/markdown-authoring`
 
 ## Constraints
 
@@ -49,24 +51,27 @@ release automation.
 - Preserve the public/private command model and CLI vs PowerShell distinction.
 - Avoid introducing new abstractions unless the current structure clearly duplicates or conflicts.
 - Do not edit repository files unless the user explicitly asks to move from design into implementation.
-- Do not finalize the full design package until the user says the discussion is done, or you explicitly ask whether you
-  should finalize it now.
+- Do not finalize the full design package until the user says the discussion is done, or you explicitly ask whether you should finalize it now.
+- Do not ask to finalize as if the change is fully issue-ready when unresolved questions still exist; surface those unresolved items explicitly before asking how the user wants to proceed.
 - Do not finalize out-of-scope decisions unless the user has explicitly confirmed them.
 
 ## Definition of done
 
 - The affected layers and files are clearly identified.
 - The scoped implementation approach matches existing repo structure.
 - Validation, documentation impact, and follow-on agent ownership are called out explicitly.
-- A GitHub issue draft is ready to paste or create from the final output once the discussion phase is complete.
+- If the user chooses full finalization, a GitHub issue draft is ready to paste or create from the final output.
+- If the user chooses design-package-only finalization, the output is clearly resumable later from an `Open questions /
+  resume here` section.
+- Finalization output is copy-ready Markdown that applies the project `markdown-authoring` skill.
 
 ## Must not do
 
 - Must not rewrite the release pipeline casually.
 - Must not invent new build or test tools.
 - Must not bypass established adapters or shared helpers without a strong reason.
 - Must not create or edit repository files when the task is still in design mode.
-- Must not return a full implementation plan or finished issue draft in the first reply when the user is clearly asking
-  for a design discussion.
-- Must not decide on its own that requested work is out of scope and then finalize the design without the user's
-  confirmation.
+- Must not return a full implementation plan or finished issue draft in the first reply when the user is clearly asking for a design discussion.
+- Must not leave the user guessing whether the final output is a handoff document, paste-ready issue text, or both.
+- Must not return finalization Markdown that skips the project `markdown-authoring` guidance.
+- Must not decide on its own that requested work is out of scope and then finalize the design without the user's confirmation.

.github/agents/docs-site.agent.md

@@ -7,8 +7,7 @@ description: Keeps NovaModuleTools website documentation accurate and clearly se
 
 ## Purpose
 
-Keep the GitHub Pages documentation under `docs/*.html` accurate, user-focused, and clearly separated from PowerShell
-cmdlet help and contributor documentation.
+Keep the GitHub Pages documentation under `docs/*.html` accurate, user-focused, and clearly separated from PowerShell cmdlet help and contributor documentation.
 
 ## Responsibilities
 
@@ -28,7 +27,7 @@ cmdlet help and contributor documentation.
 
 ## Skills to use
 
-- `/docs-site-html`
+- `/docs-site`
 - `/markdown-authoring`
 - `/powershell-module-development`
 - `/release-and-changelog`
@@ -37,8 +36,7 @@ cmdlet help and contributor documentation.
 
 - Treat `docs/*.html` as end-user website docs, not cmdlet help.
 - Keep CLI and cmdlet surfaces clearly separated.
-- Mention PowerShell-only commands in CLI-oriented docs only when there is no CLI equivalent for that scenario, such as
-  installing NovaModuleTools with `Install-Module`.
+- Mention PowerShell-only commands in CLI-oriented docs only when there is no CLI equivalent for that scenario, such as installing NovaModuleTools with `Install-Module`.
 
 ## Definition of done
 

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

@@ -13,19 +13,27 @@ Implement PowerShell command and helper changes in the NovaModuleTools style.
 
 - Change the relevant public command and private helper flow.
 - Keep public files delegating and internal helpers domain-aligned.
-- Add or update tests and documentation for the changed behavior.
+- Preserve Nova's `project.json`-driven build model; do not add hand-written source `.psm1` or module `.psd1` files.
+- Read `project.json` `Manifest.PowerShellHostVersion` before implementing PowerShell changes and keep source, tests, and examples compatible with that target.
+- Keep one externally called function per file and match the file name to that function. In `src/private/`, additional related functions may stay only as same-file top-level support helpers called by that file's entry function, and PowerShell functions must not declare nested functions inside their bodies.
+- Use `.github/instructions/code-quality-matrix.instructions.md` as the best-effort source-code maintainability guidance while shaping `src/**/*.ps1`.
+- Use `.github/instructions/psscriptanalyzer.instructions.md` as the ScriptAnalyzer workflow source of truth while changing PowerShell code or analyzer helpers.
+- Add or update source-mirrored tests and valid PlatyPS-compatible help docs for the changed behavior, using the Microsoft.PowerShell.PlatyPS cmdlets instead of hand-written help structure.
+- Every new public entry point must add its matching help file in the same change.
+- 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.
 
 ## Inputs to inspect
 
 - The relevant file in `src/public/`
-- Matching helpers in `src/private/build|cli|package|quality|release|scaffold|shared|update/`
+- Matching helpers in `src/private/`
 - Matching test files in `tests/`
 - `project.json`
 
 ## Skills to use
 
 - `/powershell-module-development`
 - `/pester-testing`
+- `/building-maintainable-code`
 - `/codescene-quality`
 - `/guiding-refactoring-with-code-health`
 - `/safeguarding-ai-generated-code`
@@ -36,10 +44,20 @@ Implement PowerShell command and helper changes in the NovaModuleTools style.
 - Keep `ShouldProcess` behavior where the command already supports it.
 - Keep raw infrastructure calls behind approved adapters.
 - Preserve existing command names, warning semantics, and output shape.
+- Keep new or heavily changed source functions aligned with `.github/instructions/code-quality-matrix.instructions.md`: short, single-purpose, low-duplication, and split by clear responsibility 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`: build and import the dist module first (`Import-Module ./dist/NovaModuleTools/NovaModuleTools.psd1 -Force`), then use `New-MarkdownCommandHelp` for new files, `Update-MarkdownCommandHelp` after command-surface changes, and `Test-MarkdownCommandHelp` before handoff. Generating help without the module imported causes `external help file` to default to the command name instead of the module name, producing per-command XML files that the manifest cannot find. A new public `src/public/*.ps1` file is not done until its matching help file exists.
 
 ## Definition of done
 
 - Production code and tests both reflect the intended behavior.
+- 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, with private helpers kept as sibling top-level functions instead of nested function declarations.
+- 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.
 - The relevant validation commands have been run.
 
@@ -48,3 +66,4 @@ Implement PowerShell command and helper changes in the NovaModuleTools style.
 - Must not mix PowerShell cmdlet UX and `nova` CLI UX.
 - Must not add silent fallbacks for invalid or risky behavior.
 - Must not duplicate helpers that already exist elsewhere in the repo.
+- Must not introduce PowerShell 7.x-only constructs into a `5.1` project unless guarded multi-version support is explicitly part of the change.

.github/agents/release-manager.agent.md

@@ -14,8 +14,8 @@ Handle versioning, changelog shaping, release-flow documentation, and publish au
 - Verify how a change affects stable vs prerelease behavior.
 - Keep `CHANGELOG.md` accurate and release-ready.
 - Review workflow, docs, and versioning implications together.
-- Produce a release-ready summary that follows `.github/pull_request_template.md` when a release preparation summary is
-  requested.
+- Produce a release-ready summary that follows `.github/pull_request_template.md` when a release preparation summary is requested.
+- When the release scope is unclear (for example whether the change targets a stable bump, a prerelease, or both), ask one clarifying question before proceeding instead of guessing.
 
 ## Inputs to inspect
 
@@ -30,21 +30,18 @@ Handle versioning, changelog shaping, release-flow documentation, and publish au
 
 - `/release-and-changelog`
 - `/markdown-authoring`
-- `/github-actions`
 - `/pester-testing`
+- `/github-actions`
 
 ## Constraints
 
 - Treat release automation as high-risk.
 - Keep Keep a Changelog structure intact.
-- Use only the official Keep a Changelog section types in `CHANGELOG.md` and `RELEASE_NOTE.md`: `Added`, `Changed`,
-  `Deprecated`, `Removed`, `Fixed`, and `Security`.
-- Do not invent extra changelog section headings such as `Documentation`; place documentation-related release notes under
-  the official type that best matches the actual impact.
+- Use only the official Keep a Changelog section types in `CHANGELOG.md` and `RELEASE_NOTE.md`: `Added`, `Changed`, `Deprecated`, `Removed`, `Fixed`, and `Security`.
+- Do not invent extra changelog section headings such as `Documentation`; place documentation-related release notes under the official type that best matches the actual impact.
 - Distinguish contributor docs from end-user docs.
 - Treat `.github/pull_request_template.md` as the authoritative format for structured release summaries.
-- When the release summary is returned as Markdown or copy-ready UI output, it must follow the `markdown-authoring`
-  skill (`.github/skills/markdown-authoring/SKILL.md`).
+- When the release summary is returned as Markdown or copy-ready UI output, it must follow the `markdown-authoring` skill (`.github/skills/markdown-authoring/SKILL.md`).
 
 ## Definition of done
 

.github/agents/reviewer.agent.md

@@ -14,11 +14,23 @@ Review changes for correctness, maintainability, test coverage, workflow safety,
 - Start with the highest-risk workflow or public behavior surface.
 - Check for missing tests, doc drift, changelog gaps, and CI/release side effects.
 - Use the PR template categories as the review frame.
-- Treat CodeScene maintainability and changed-code coverage results as release-blocking signals unless risk is accepted
-  explicitly.
-- If local CodeScene tooling is unavailable, continue the review with normal validation and rely on PR/CI as the
-  effective CodeScene gate.
+- When the review scope is genuinely ambiguous (for example which subset of files to focus on, or whether a borderline behavior change is intentional), ask one clarifying question before proceeding instead of guessing.
+- Treat CodeScene maintainability and changed-code coverage results as release-blocking signals unless risk is accepted explicitly.
+- If local CodeScene tooling is unavailable, continue the review with normal validation and rely on PR/CI as the effective CodeScene gate.
 - Check whether website docs preserve the CLI-vs-cmdlet separation when `docs/*.html` or help markdown changed.
+- Check that Nova projects still use generated `dist/` module files instead of hand-written source `.psm1` or module `.psd1` files.
+- Check changed PowerShell code, tests, and examples against `project.json` `Manifest.PowerShellHostVersion`; flag PowerShell 7.x-only constructs in projects that target `5.1` unless the change explicitly adds guarded compatibility handling.
+- Check that public commands/classes have matching valid PlatyPS-compatible help and that new source files have source-mirrored tests. Flag help files under `docs/NovaModuleTools/en-US/` that look like plain Markdown, break the required PlatyPS section order, or would fail `Test-MarkdownCommandHelp` / `Import-MarkdownCommandHelp`.
+- Flag any new public entry point that does not add its matching help file in the same change.
+- Flag help files where `external help file` contains a command name instead of the module name. The correct value is `NovaModuleTools-Help.xml`; a per-command name like `Get-Something-Help.xml` means the help was generated without the built module imported.
+- Check analyzer changes and PowerShell validation flow against `.github/instructions/psscriptanalyzer.instructions.md`. Flag direct `Invoke-ScriptAnalyzer` usage that bypasses repository-approved settings or wrapper semantics without a clear reason.
+- Review changed `src/**/*.ps1` against `.github/instructions/code-quality-matrix.instructions.md` and `tests/**/*.ps1` against `.github/instructions/testing-policy.instructions.md`; flag new or heavily changed code that ignores those maintainability rules 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 related same-file top-level support helpers. Also flag file/function name mismatches for public commands or externally called private helpers, and flag nested function declarations inside PowerShell functions.
+- 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.
+- Flag every changed or generated text file if they do not exactly have one trailing newline with no extra blank lines at the bottom.
 
 ## Inputs to inspect
 
@@ -31,11 +43,12 @@ Review changes for correctness, maintainability, test coverage, workflow safety,
 
 - `/codescene-quality`
 - `/safeguarding-ai-generated-code`
-- `/docs-site-html`
+- `/building-maintainable-code`
+- `/docs-site`
 - `/markdown-authoring`
 - `/pester-testing`
-- `/github-actions`
 - `/release-and-changelog`
+- `/github-actions`
 
 ## Constraints