feat(#194): enhance agentic guidance and documentation

- Add reviewer agent content to improve review processes
- Include implement prompt content for better implementation guidance
- Update coding standards to clarify file and function ownership rules

Author: stiwicourage

.codescene/code-health-rules.json

@@ -60,7 +60,88 @@
   ],
   "rule_sets": [
     {
-      "thresholds": [],
+      "thresholds": [
+        {
+          "name": "constructor_max_arguments",
+          "value": 5
+        },
+        {
+          "name": "file_lines_of_code_for_alert",
+          "value": 5000
+        },
+        {
+          "name": "file_lines_of_code_for_critical_alert",
+          "value": 10000
+        },
+        {
+          "name": "file_lines_of_code_for_warning",
+          "value": 1000
+        },
+        {
+          "name": "file_mean_cyclomatic_complexity_warning",
+          "value": 4
+        },
+        {
+          "name": "file_primitive_obsession_percentage_for_warning",
+          "value": 0.3
+        },
+        {
+          "name": "function_bumpy_road_bumps_for_warning",
+          "value": 2
+        },
+        {
+          "name": "function_bumpy_road_nesting_level_depth",
+          "value": 2
+        },
+        {
+          "name": "function_complex_conditional_branches_alert",
+          "value": 10
+        },
+        {
+          "name": "function_complex_conditional_branches_warning",
+          "value": 2
+        },
+        {
+          "name": "function_cyclomatic_complexity_alert",
+          "value": 100
+        },
+        {
+          "name": "function_cyclomatic_complexity_warning",
+          "value": 9
+        },
+        {
+          "name": "function_embedded_content_lines_of_code_alert",
+          "value": "-"
+        },
+        {
+          "name": "function_embedded_content_lines_of_code_warning",
+          "value": "-"
+        },
+        {
+          "name": "function_lines_of_code_alert",
+          "value": 500
+        },
+        {
+          "name": "function_lines_of_code_warning",
+          "value": 70
+        },
+        {
+          "name": "function_max_arguments",
+          "value": 4
+        },
+        {
+          "name": "function_nesting_depth_warning",
+          "value": 4
+        },
+        {
+          "name": "unit_test_consecutive_asserts_for_large_block",
+          "value": 4
+        },
+        {
+          "name": "unit_test_suite_number_of_large_assertion_blocks",
+          "value": 4
+        }
+      ],
       "thresholds_doc": "The thresholds let you redefine the details of the code health issues. For example, specifying what a Complex Method means to you. Be restrictive with overrides.",
       "matching_content_path": "**/tests/**",
       "matching_content_path_doc": "Specify a glob pattern relative to this repository root.",

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

@@ -15,6 +15,7 @@ Implement PowerShell command and helper changes in the NovaModuleTools style.
 - Keep public files delegating and internal helpers domain-aligned.
 - 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 functions may stay only as same-file support helpers called by that file's entry function.
 - Add or update source-mirrored tests and PlatyPS-compatible help docs for the changed behavior.
 - 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.
 
@@ -44,6 +45,7 @@ Implement PowerShell command and helper changes in the NovaModuleTools style.
 
 - 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.
 - 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

@@ -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 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 PlatyPS-compatible help and that new source files have source-mirrored tests.
+- 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 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/copilot-instructions.md

@@ -23,7 +23,7 @@ For new or not-yet-scoped work, start with `.github/agents/architect.agent.md` a
 ## Repository map
 
 - `src/public/` - public PowerShell command surface; one top-level function per file
-- `src/private/` - internal helpers grouped by domain (`build/`, `cli/`, `package/`, `quality/`, `release/`, `scaffold/`, `shared/`, `update/`)
+- `src/private/` - internal helpers grouped by domain (`build/`, `cli/`, `package/`, `quality/`, `release/`, `scaffold/`, `shared/`, `update/`); keep one externally called helper per file and limit any extra functions to same-file support helpers
 - `tests/` - Pester tests and shared test-support scripts
 - `scripts/build/` - local analyzer and build helpers
 - `scripts/build/ci/` - CI coverage, CodeScene, and artifact helpers
@@ -44,6 +44,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.
 - Keep `run.ps1` as the local quality loop: run ScriptAnalyzer first, then `Invoke-NovaBuild`, then `Test-NovaBuild`.
 - 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.
 - 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

@@ -12,13 +12,17 @@ Use this file when changing `src/public/`, `src/private/`, or PowerShell build/r
 
 - Keep public command files small and delegating.
 - 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.
 - 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
 
 - Put internal helpers in the correct domain folder under `src/private/`.
+- 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.
 - 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.

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

@@ -19,13 +19,14 @@ Implement the issue in the NovaModuleTools repository using the repository-local
 7. Implement the smallest maintainable fix.
 8. Do not add PSScriptAnalyzer excluded rules or suppressions; fix analyzer findings in the code.
 9. If `run.ps1` or `Invoke-ScriptAnalyzerCI.ps1` reports ScriptAnalyzer findings, fix them before handoff instead of only reporting the failure.
-10. 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.
-11. 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.
-12. Add or update PlatyPS-compatible help under `docs/<ProjectName>/en-US/` when public commands or public classes change.
-13. Review `README.md`, `CONTRIBUTING.md`, `CHANGELOG.md`, `RELEASE_NOTE.md`, help docs, and `docs/*.html` as applicable.
-14. If a commit message is requested, derive it from `$GIT_BRANCH_NAME` and the implemented change using the repository's Conventional Commit rules.
-15. Run the relevant validation, then summarize what changed, why, and how it was verified.
-16. 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`).
+10. 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.
+11. 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.
+12. 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.
+13. Add or update PlatyPS-compatible help under `docs/<ProjectName>/en-US/` when public commands or public classes change.
+14. Review `README.md`, `CONTRIBUTING.md`, `CHANGELOG.md`, `RELEASE_NOTE.md`, help docs, and `docs/*.html` as applicable.
+15. If a commit message is requested, derive it from `$GIT_BRANCH_NAME` and the implemented change using the repository's Conventional Commit rules.
+16. Run the relevant validation, then summarize what changed, why, and how it was verified.
+17. 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

@@ -29,6 +29,7 @@ Use this skill when changing public commands, private helpers, CLI routing suppo
 - Read `project.json` `Manifest.PowerShellHostVersion` before changing PowerShell code, tests, or examples, and keep new work compatible with that target. A `5.1` project must not receive PowerShell 7.x-only syntax, cmdlets, parameters, or APIs unless the change explicitly adds guarded compatibility handling.
 - Do not create or maintain hand-written module `.psm1` or module `.psd1` files in source; Nova generates those files under `dist/<ProjectName>/`.
 - Preserve native PowerShell semantics and Nova naming patterns.
+- Keep one externally called function per file and match the file name to that function. In `src/private/`, additional functions may stay only as same-file support helpers called by that file's entry function.
 - 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.
@@ -45,6 +46,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`
+- Grouping two externally called private helpers in one file instead of splitting them into separate same-named files
 - Ignoring the project's `Manifest.PowerShellHostVersion` target and introducing PowerShell 7.x-only features into a `5.1` project
 - Excluding PSScriptAnalyzer rules instead of fixing the code that violates them
 

CHANGELOG.md

@@ -15,6 +15,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
     - 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, 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 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 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.
 
 ### Changed

README.md

@@ -506,7 +506,7 @@ 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, guidance that ScriptAnalyzer findings reported by `run.ps1` must be fixed before handoff, 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
+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, guidance that ScriptAnalyzer findings reported by `run.ps1` must be fixed before handoff, explicit public/private PowerShell file ownership rules, 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/`,
 `.github/skills/`, `.github/prompts/`, or `.github/copilot-instructions.md` so future scaffolds and `dist` stay in sync.
 

RELEASE_NOTE.md

@@ -12,6 +12,7 @@ This file summarizes public cmdlet, CLI, configuration, and migration changes fo
     - 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, 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 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 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.
 
 ### Changed