feat(#194): strengthen agentic scaffold guidance

 Clarify Agentic Copilot starter guidance so generated projects stay on Nova workflows, generated dist output, PlatyPS help, source-mirrored tests, and strict ScriptAnalyzer behavior.

Author: stiwicourage

.github/agents/reviewer.agent.md

@@ -20,6 +20,7 @@ Review changes for correctness, maintainability, test coverage, workflow safety,
 - Check that Nova projects still use generated `dist/` module files instead of hand-written source `.psm1` or module `.psd1` files.
 - Check that public commands/classes have matching PlatyPS-compatible help and that new source files have source-mirrored tests.
 - Flag broad catch-all test files when focused source-mirrored tests would make ownership clearer.
+- Flag any PSScriptAnalyzer rule excludes or suppressions; the code should be fixed instead.
 
 ## Inputs to inspect
 

.github/copilot-instructions.md

@@ -41,6 +41,8 @@ For new or not-yet-scoped work, start with `.github/agents/architect.agent.md` a
 - Treat `project.json` as the source of truth for project metadata, build output, package settings, and release settings.
 - Use Nova commands and repository wrappers for build, test, package, and release workflows; do not replace them with ad hoc PowerShell module build scripts.
 - Do not create or maintain hand-written module `.psm1` or module `.psd1` files in source; Nova generates the built module root and manifest under `dist/<ProjectName>/` from `project.json` and `src/**/*.ps1`.
+- Do not exclude or suppress PSScriptAnalyzer rules in repository analyzer helpers; fix the code that violates analyzer rules instead.
+- Keep `run.ps1` as the local quality loop: run ScriptAnalyzer first, then `Invoke-NovaBuild`, then `Test-NovaBuild`.
 - Review `README.md`, `CONTRIBUTING.md`, `CHANGELOG.md`, and `RELEASE_NOTE.md` after every meaningful change.
 - Update tests when behavior changes.
 - Prefer existing helpers and support files over ad hoc duplication.

.github/instructions/powershell-coding-standards.instructions.md

@@ -28,6 +28,8 @@ Use this file when changing `src/public/`, `src/private/`, or PowerShell build/r
 - Prefer clear, structured Nova errors over silent fallback behavior.
 - Preserve existing warning semantics; do not rename warning opt-ins to a generic `-Force` pattern.
 - Keep CLI spellings and PowerShell spellings distinct in messages and docs.
+- Do not add PSScriptAnalyzer `ExcludeRule`, `ExcludeRules`, suppression attributes, or generated settings that hide analyzer findings. Fix the rule violation instead.
+- Keep local quality wrappers ordered as ScriptAnalyzer first, then `Invoke-NovaBuild`, then `Test-NovaBuild`.
 
 ## Formatting rules
 

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

@@ -18,12 +18,13 @@ Implement the issue in the NovaModuleTools repository using the repository-local
    `scripts/build/ci/*.ps1` files.
 5. Preserve the Nova build model: use `project.json` and Nova commands for build/test/package/release behavior, and do not create hand-written source `.psm1` or module `.psd1` files.
 6. Implement the smallest maintainable fix.
-7. 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.
-8. Add or update PlatyPS-compatible help under `docs/<ProjectName>/en-US/` when public commands or public classes change.
-9. Review `README.md`, `CONTRIBUTING.md`, `CHANGELOG.md`, `RELEASE_NOTE.md`, help docs, and `docs/*.html` as applicable.
-10. If a commit message is requested, derive it from `$GIT_BRANCH_NAME` and the implemented change using the repository's Conventional Commit rules.
-11. Run the relevant validation, then summarize what changed, why, and how it was verified.
-12. If that summary is returned as Markdown or copy-ready UI output, format it according to the `markdown-authoring`
+7. Do not add PSScriptAnalyzer excluded rules or suppressions; fix analyzer findings in the code.
+8. 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.
+9. Add or update PlatyPS-compatible help under `docs/<ProjectName>/en-US/` when public commands or public classes change.
+10. Review `README.md`, `CONTRIBUTING.md`, `CHANGELOG.md`, `RELEASE_NOTE.md`, help docs, and `docs/*.html` as applicable.
+11. If a commit message is requested, derive it from `$GIT_BRANCH_NAME` and the implemented change using the repository's Conventional Commit rules.
+12. Run the relevant validation, then summarize what changed, why, and how it was verified.
+13. 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/skills/powershell-module-development/SKILL.md

@@ -30,6 +30,8 @@ Use this skill when changing public commands, private helpers, CLI routing suppo
 - Preserve native PowerShell semantics and Nova naming patterns.
 - Reuse existing workflow-context helpers and shared adapters.
 - Follow the repository's PowerShell style rules: 4-space indentation, same-line opening braces, restrained blank lines, full cmdlet names, and readable operator spacing.
+- Keep ScriptAnalyzer strict: do not add excluded rules, suppression attributes, or settings that hide analyzer findings.
+- Keep `run.ps1`-style local checks ordered as ScriptAnalyzer first, then `Invoke-NovaBuild`, then `Test-NovaBuild`.
 - Add or update PlatyPS-compatible help under `docs/<ProjectName>/en-US/` when public commands or public classes change.
 - Add or update the source-mirrored Pester test file for every changed `src/**/*.ps1` file.
 
@@ -40,6 +42,7 @@ Use this skill when changing public commands, private helpers, CLI routing suppo
 - Calling `git`, `Invoke-WebRequest`, `Update-Module`, or `$env:` from the wrong layer
 - Replacing explicit warning opt-ins with generic force semantics
 - Creating a root module `.psm1` or module manifest `.psd1` by hand instead of letting Nova generate them from `project.json`
+- Excluding PSScriptAnalyzer rules instead of fixing the code that violates them
 
 ## Verification
 

CHANGELOG.md

@@ -14,6 +14,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
     - The starter tree is now generated from a filtered mirror of Nova's own agentic `.github/` files, with a dedicated sync script and drift test so future scaffolds and `dist` stay aligned with the maintained source guidance.
     - The generated architect/design prompt now requires final design packages and issue/work item drafts to be returned as copy-ready Markdown using the project Markdown authoring guidance.
   - The generated guidance now explicitly keeps Agentic Copilot projects on the Nova build model, treats `.psm1` / `.psd1` files as generated `dist` output, requires PlatyPS-compatible help for public commands/classes, and expects one focused source-mirrored test file for every new or changed `src/**/*.ps1` file.
+  - The generated guidance now keeps local `run.ps1` quality loops ordered as ScriptAnalyzer, `Invoke-NovaBuild`, then `Test-NovaBuild`, and tells agents to fix ScriptAnalyzer findings instead of excluding or suppressing rules.
 
 ### Changed
 

RELEASE_NOTE.md

@@ -12,6 +12,7 @@ changes will be included in the next **stable** release!
     - 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 CodeScene or docs-site surfaces.
     - Generated architect/design guidance now requires final design packages and issue/work item drafts to be returned as copy-ready Markdown using the project Markdown authoring guidance.
   - Generated implementation/test guidance now keeps projects on Nova build/test/package workflows, treats `.psm1` / `.psd1` files as generated output, and calls out PlatyPS help plus one focused source-mirrored test file for every new or changed `src/**/*.ps1` file.
+  - Generated quality-loop guidance now keeps ScriptAnalyzer first and tells agents to fix ScriptAnalyzer findings instead of excluding or suppressing rules.
 
 ### Changed
 

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

@@ -27,7 +27,7 @@ PS> Initialize-NovaModule [-Path <string>] [-Example] [-WhatIf] [-Confirm] [<Com
 
 `Initialize-NovaModule` creates a new project folder, the standard `src/` layout, and a starter `project.json` file.
 
-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. The Agentic package follows Nova's maintained agentic guidance through a filtered starter mirror, including Nova build/test/package expectations, generated `dist` module files, command-help ownership, and source-mirrored test guidance. For the standard scaffold, the interactive flow also includes optional basic Pester support.
+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. The Agentic package follows Nova's maintained agentic guidance through a filtered starter mirror, including Nova build/test/package expectations, strict ScriptAnalyzer guidance without excluded rules, generated `dist` module files, command-help ownership, and source-mirrored test guidance. 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.
 
@@ -136,7 +136,7 @@ This cmdlet does not emit an output object.
 
 ## NOTES
 
-Generated projects start with NovaModuleTools defaults for recursive discovery, source markers, and duplicate-function validation. 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, leave `.psm1` / `.psd1` files to generated `dist` output, maintain PlatyPS-compatible help, and mirror new tests to source files.
+Generated projects start with NovaModuleTools defaults for recursive discovery, source markers, and duplicate-function validation. 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, run ScriptAnalyzer before build/test without excluding rules, leave `.psm1` / `.psd1` files to generated `dist` output, maintain PlatyPS-compatible help, and mirror new tests to source files.
 
 `Initialize-NovaModule` uses `SupportsShouldProcess`, so `Get-Help Initialize-NovaModule -Full` surfaces native
 `-WhatIf` and

docs/commands.html

@@ -177,8 +177,9 @@ <h3>Start a new project</h3>
                         <p>Create the minimal scaffold or the example scaffold for a new module project. Both interactive
                             flows can also add the optional Agentic Copilot starter package, which follows Nova's
                             maintained agentic guidance through a filtered starter mirror, including Nova build/test
-                            expectations, generated <code>dist</code> module files, command-help ownership, and
-                            source-mirrored test guidance.</p>
+                            expectations, strict ScriptAnalyzer guidance without excluded rules, generated
+                            <code>dist</code> module files, command-help ownership, and source-mirrored test guidance.
+                        </p>
                         <ul class="plain-list">
                             <li><strong>Use when:</strong> you are creating a fresh NovaModuleTools project</li>
                             <li data-command-visibility="command-line" hidden><strong>Remember:</strong> pass the target path

docs/core-workflows.html

@@ -126,8 +126,9 @@ <h2>Create the project</h2>
                 <p>Both scaffold styles ask the same core project questions, and both now offer an optional Agentic
                     Copilot starter package after the Git prompt. The Agentic prompt defaults to <code>No</code>, and
                     the package follows Nova's maintained agentic guidance through a filtered starter mirror, including
-                    Nova build/test/package expectations, generated <code>dist</code> module files, command-help
-                    ownership, and source-mirrored test guidance.</p>
+                    Nova build/test/package expectations, strict ScriptAnalyzer guidance without excluded rules,
+                    generated <code>dist</code> module files, command-help ownership, and source-mirrored test
+                    guidance.</p>
                 <p>Use the example scaffold when you want the shortest path to understanding a real project layout, test
                     suite, and package configuration. Use the minimal scaffold when you already know the structure you
                     want.</p>