feat(#194): enhance coding standards and guidance documentation

- Add new coding standards for private helper naming conventions
- Update guidance to clarify public command naming and file structure rules
- Refine generated guidance for project scaffolding and maintainability

Author: stiwicourage

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

@@ -14,7 +14,7 @@ Use this file when changing `src/public/`, `src/private/`, or PowerShell build/r
 - Keep exactly one top-level public function per file in `src/public/`.
 - Match the file name to that top-level public function name.
 - Public mutating commands should support PowerShell `ShouldProcess` semantics.
-- Preserve existing naming and command model conventions such as `Invoke-Nova*`, `Get-Nova*`, `Update-Nova*`, and the `nova` CLI routing model.
+- Preserve existing naming and command model conventions for public commands/functions such as `Invoke-Nova*`, `Get-Nova*`, `Update-Nova*`, and the `nova` CLI routing model.
 - 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/NovaModuleTools/` from `project.json` and `src/**/*.ps1`.
 
 ## Internal structure rules
@@ -23,6 +23,7 @@ Use this file when changing `src/public/`, `src/private/`, or PowerShell build/r
 - In `src/private/`, keep at most one externally called function per file and match the file name to that entry function.
 - Additional functions in a private file are allowed only as support helpers called from that same file.
 - If two private functions are both called from outside their file, split them into separate same-named files.
+- Private helper names should stay clear and responsibility-focused; they do not need to mirror the public `Invoke-Nova*`, `Get-Nova*`, `Update-Nova*`, or `nova` CLI route naming conventions unless they are intentionally part of the public surface.
 - Reuse existing adapters and shared helpers before adding new infrastructure calls.
 - Keep direct environment access, Git execution, upload requests, and self-update execution in their approved helper locations. `tests/ArchitectureGuardrails.Tests.ps1` is authoritative.
 - Prefer explicit workflow-context objects (`[pscustomobject]` / ordered hashtables) for multi-step flows.

CHANGELOG.md

@@ -13,7 +13,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
   - The generated guidance now explicitly keeps Agentic Copilot projects on the Nova build model, treats `.psm1` / `.psd1` files as generated `dist` output, requires project test validation to run through `Test-NovaBuild` instead of direct `Invoke-Pester`, requires PlatyPS-compatible help for public commands/classes, expects one focused source-mirrored test file for every new or changed `src/**/*.ps1` file, tells agents to honor `project.json` `Manifest.PowerShellHostVersion` when writing PowerShell code and tests, and now asks for a short project name so placeholders such as `Invoke-<ShortName>*` can be replaced in the generated starter files.
       - 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 reported by `run.ps1` instead of excluding, suppressing, or handing them off unresolved.
       - The generated guidance now points agents to the documented PSScriptAnalyzer workflow, using `./scripts/build/Invoke-ScriptAnalyzerCI.ps1` and `./run.ps1` as the normal entrypoints and reserving direct `Invoke-ScriptAnalyzer` for focused local checks that reuse repo-approved settings.
-      - The generated PowerShell guidance now requires public files to keep one top-level function per file, requires private files to keep at most one externally called function per file, and keeps any extra private functions limited to same-file support helpers whose file names match the owning function.
+    - The generated PowerShell guidance now requires public files to keep one top-level function per file, requires private files to keep at most one externally called function per file, keeps any extra private functions limited to same-file support helpers whose file names match the owning function, and limits the `Invoke-<ShortName>*` / `Get-<ShortName>*` / `Update-<ShortName>*` naming guidance to public commands instead of private helpers.
     - 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.

RELEASE_NOTE.md

@@ -6,17 +6,7 @@ This file summarizes public cmdlet, CLI, configuration, and migration changes fo
 ## [Unreleased]
 ### 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 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, requires project test validation to run through `Test-NovaBuild` instead of direct `Invoke-Pester`, calls out PlatyPS help plus one focused source-mirrored test file for every new or changed `src/**/*.ps1` file, tells agents to honor `project.json` `Manifest.PowerShellHostVersion` when writing PowerShell code and tests, and now asks for a short project name so placeholders such as `Invoke-<ShortName>*` can be replaced in the generated starter files.
-      - Generated quality-loop guidance now keeps ScriptAnalyzer first and tells agents to fix ScriptAnalyzer findings reported by `run.ps1` instead of excluding, suppressing, or handing them off unresolved.
-    - Generated guidance now points agents to the documented PSScriptAnalyzer workflow, with `./scripts/build/Invoke-ScriptAnalyzerCI.ps1` and `./run.ps1` as the normal entrypoints and direct `Invoke-ScriptAnalyzer` reserved for focused local checks that reuse repo-approved settings.
-    - Generated PowerShell guidance now requires public files to keep one top-level function per file, requires private files to keep at most one externally called function per file, and keeps any extra private functions limited to same-file support helpers whose file names match the owning function.
-    - 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.
-    - Generated guidance now requires `docs/<ProjectName>/en-US/*.md` to stay valid PlatyPS help with YAML metadata and build-compatible structure, points agents to the `New-MarkdownCommandHelp` / `Update-MarkdownCommandHelp` / `Test-MarkdownCommandHelp` workflow, and requires a matching help file for every new public entry point in the same change so command help stays build-compatible from the start.
-    - 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.
-    - 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.
-
+    - 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.
 
 ### Changed
 

src/resources/agentic-copilot/.github/instructions/powershell-coding-standards.instructions.md

@@ -14,7 +14,7 @@ Use this file when changing `src/public/`, `src/private/`, or PowerShell build/r
 - Keep exactly one top-level public function per file in `src/public/`.
 - Match the file name to that top-level public function name.
 - Public mutating commands should support PowerShell `ShouldProcess` semantics.
-- Preserve existing naming and command model conventions such as `Invoke-{{ShortName}}*`, `Get-{{ShortName}}*`, `Update-{{ShortName}}*`.
+- Preserve existing naming and command model conventions for public commands/functions such as `Invoke-{{ShortName}}*`, `Get-{{ShortName}}*`, `Update-{{ShortName}}*`.
 - 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`.
 
 ## Internal structure rules
@@ -23,6 +23,7 @@ Use this file when changing `src/public/`, `src/private/`, or PowerShell build/r
 - In `src/private/`, keep at most one externally called function per file and match the file name to that entry function.
 - Additional functions in a private file are allowed only as support helpers called from that same file.
 - If two private functions are both called from outside their file, split them into separate same-named files.
+- Private helper names should stay clear and responsibility-focused; they do not need to mirror the public `Invoke-{{ShortName}}*`, `Get-{{ShortName}}*`, `Update-{{ShortName}}*`, or `nova` CLI route naming conventions unless they are intentionally part of the public surface.
 - Reuse existing adapters and shared helpers before adding new infrastructure calls.
 - Keep direct environment access, Git execution, upload requests, and self-update execution in their approved helper locations. `tests/*Architecture*.Tests.ps1` is authoritative.
 - Prefer explicit workflow-context objects (`[pscustomobject]` / ordered hashtables) for multi-step flows.

tests/AgenticCopilotScaffoldSync.Tests.ps1

@@ -78,12 +78,14 @@ Describe 'Agentic Copilot scaffold sync' {
         $content.Instruction | Should -Match 'Do not exclude or suppress PSScriptAnalyzer rules'
         $content.Instruction | Should -Match 'If `run\.ps1` or `\./scripts/build/Invoke-ScriptAnalyzerCI\.ps1` reports ScriptAnalyzer findings, fix them before review, handoff, or commit'
 
+        $content.CodingStandards | Should -Match 'Preserve existing naming and command model conventions for public commands/functions'
         $content.CodingStandards | Should -Match 'Invoke-\{\{ShortName\}\}\*'
         $content.CodingStandards | Should -Match 'code-quality-matrix\.instructions\.md'
         $content.CodingStandards | Should -Match 'psscriptanalyzer\.instructions\.md'
         $content.CodingStandards | Should -Match 'Match the file name to that top-level public function name'
         $content.CodingStandards | Should -Match 'In `src/private/`, keep at most one externally called function per file and match the file name to that entry function'
         $content.CodingStandards | Should -Match 'If two private functions are both called from outside their file, split them into separate same-named files'
+        $content.CodingStandards | Should -Match 'Private helper names should stay clear and responsibility-focused; they do not need to mirror the public'
         $content.CodingStandards | Should -Match 'platyps-help\.instructions\.md'
         $content.CodingStandards | Should -Match 'New-MarkdownCommandHelp'
         $content.CodingStandards | Should -Match 'Every changed or generated text file, including `\.ps1` files, must end with exactly one trailing newline and no extra blank lines at the bottom'