feat(#194): add code quality matrix for src and tests

- Introduce a best-effort code quality matrix for source and test files.
- Define warning and alert thresholds to guide maintainability.
- Provide authoring guidance to help shape code quality from the start.

Author: stiwicourage

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

@@ -16,6 +16,7 @@ Implement PowerShell command and helper changes in the NovaModuleTools style.
 - 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.
+- Use `.github/instructions/code-quality-matrix.instructions.md` as the best-effort source-code matrix while shaping `src/**/*.ps1`.
 - 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.
 
@@ -40,6 +41,7 @@ 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 inside the warning thresholds from `.github/instructions/code-quality-matrix.instructions.md` unless the scope explicitly justifies otherwise.
 
 ## Definition of done
 

.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.
+- 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 any PSScriptAnalyzer rule excludes or suppressions; the code should be fixed instead.

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

@@ -15,6 +15,7 @@ Improve or maintain the repository's Pester coverage, coverage-gate behavior, an
 - Refactor brittle or duplicated tests into reusable support patterns.
 - Enforce a source-mirrored test layout for new projects and newly added or changed source files.
 - Keep test files and helpers compatible with the project's `project.json` `Manifest.PowerShellHostVersion` target.
+- Use `.github/instructions/code-quality-matrix.instructions.md` as the best-effort test-code matrix while shaping `tests/**/*.ps1`.
 - Keep CI coverage output compatible with the CodeScene workflow.
 
 ## Inputs to inspect
@@ -41,6 +42,7 @@ Improve or maintain the repository's Pester coverage, coverage-gate behavior, an
 - 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.
 
 ## Definition of done
 

.github/copilot-instructions.md

@@ -15,6 +15,7 @@ Read these files before making non-trivial changes:
 3. `.github/pull_request_template.md`
 4. The relevant file in `.github/instructions/`
 5. The relevant skill under `.github/skills/<skill-name>/SKILL.md`
+6. `.github/instructions/code-quality-matrix.instructions.md` when shaping or reviewing `src/**/*.ps1` or `tests/**/*.ps1`
 
 Prompt templates under `.github/prompts/*.prompt.md` are not auto-loaded. Reference them explicitly in chat when you want to use one of the repository's reusable task prompts.
 
@@ -45,6 +46,7 @@ For new or not-yet-scoped work, start with `.github/agents/architect.agent.md` a
 - 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.
+- 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`.
 - 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/code-quality-matrix.instructions.md

@@ -0,0 +1,58 @@
+---
+applyTo: "src/**/*.ps1,tests/**/*.ps1"
+---
+
+# Agentic code quality matrix
+
+## Purpose
+
+Use this file as the best-effort code quality matrix for generated and reviewed code in this repository.
+
+The matrix translates the repository's preferred `src/**` and `tests/**` maintainability thresholds into agent guidance, so agents can shape code toward the expected quality from the start. This guidance does **not** require a `.codescene/code-health-rules.json` file in generated projects.
+
+## How to use the matrix
+
+- Treat warning thresholds as the default design ceiling for new or heavily changed code.
+- Treat alert thresholds as refactor-now signals for new or heavily changed code.
+- When a threshold has no alert value, stay below the warning threshold by default.
+- When a threshold is marked `not used`, do not optimize around it; focus on the other limits instead.
+- If a change must exceed a threshold, call it out in the handoff and explain the trade-off clearly.
+
+## Source code matrix (`**/src/**`)
+
+| Threshold                                          | Warning          | Alert | Best-effort authoring guidance                                                                               |
+|----------------------------------------------------|------------------|-------|--------------------------------------------------------------------------------------------------------------|
+| `constructor_max_arguments`                        | `4`              | —     | Extract parameter objects or workflow-context objects before constructors exceed four inputs.                |
+| `file_mean_cyclomatic_complexity_warning`          | `26`             | —     | Split growing files or extract helpers before the file's average complexity drifts past this point.          |
+| `function_complex_conditional_branches_warning`    | `6`              | `11`  | Break up long boolean expressions before complex branch conditions become hard to read.                      |
+| `function_cyclomatic_complexity_warning`           | `6`              | `11`  | Extract helpers and flatten control flow before a function becomes a local hotspot.                          |
+| `function_duplication_min_lines_of_code_for_check` | `6 lines`        | —     | Treat six or more repeated lines as an extraction candidate.                                                 |
+| `function_duplication_min_similarity_percentage`   | `89% similarity` | —     | Consolidate near-copy/paste logic even when names or literals differ slightly.                               |
+| `function_lines_of_code_warning`                   | `16`             | `31`  | Keep new or heavily changed functions short; extract helpers before they drift beyond the warning threshold. |
+| `function_max_arguments`                           | `4`              | —     | Introduce context objects, parameter objects, or helper abstractions before functions exceed four inputs.    |
+| `function_nesting_depth_warning`                   | `6`              | —     | Flatten nested control flow early; do not let new logic grow into deep indentation towers.                   |
+
+## Test code matrix (`**/tests/**`)
+
+| Threshold                                          | Warning    | Alert                        | Best-effort authoring guidance                                                                                           |
+|----------------------------------------------------|------------|------------------------------|--------------------------------------------------------------------------------------------------------------------------|
+| `constructor_max_arguments`                        | `5`        | —                            | Keep test helper constructors simple; prefer factory helpers or setup objects before they sprawl.                        |
+| `file_lines_of_code_for_warning`                   | `1000`     | `5000` (`critical`: `10000`) | Split oversized test files by source ownership or behavior before they become hard to review.                            |
+| `file_mean_cyclomatic_complexity_warning`          | `4`        | —                            | Refactor test helpers or `BeforeAll` setup when a file becomes too branch-heavy overall.                                 |
+| `file_primitive_obsession_percentage_for_warning`  | `0.3`      | —                            | Extract builders, fixtures, or named data objects when tests lean too heavily on raw strings, ints, and hashtables.      |
+| `function_bumpy_road_bumps_for_warning`            | `2`        | —                            | Keep each test focused on one logical path; extract setup helpers when the flow breaks into many chunks.                 |
+| `function_bumpy_road_nesting_level_depth`          | `2`        | —                            | Keep test logic shallow and linear; avoid nested setup trees in individual test functions.                               |
+| `function_complex_conditional_branches_warning`    | `2`        | `10`                         | Prefer separate tests or helper functions over highly conditional test logic.                                            |
+| `function_cyclomatic_complexity_warning`           | `9`        | `100`                        | Split test helpers or parameterized cases before one test function turns into control-flow-heavy code.                   |
+| `function_embedded_content_lines_of_code_warning`  | `not used` | `not used`                   | Do not optimize for this metric; focus on the other thresholds instead.                                                  |
+| `function_lines_of_code_warning`                   | `70`       | `500`                        | Keep new or heavily changed test functions compact; extract setup and assertion helpers when they grow too large.        |
+| `function_max_arguments`                           | `4`        | —                            | Keep helper/test function signatures tight; prefer fixtures or context objects over long parameter lists.                |
+| `function_nesting_depth_warning`                   | `4`        | —                            | Flatten nested assertions and setup paths before they become difficult to follow.                                        |
+| `unit_test_consecutive_asserts_for_large_block`    | `4`        | —                            | Split assertion helpers or use richer comparison helpers before an assertion block grows past four consecutive asserts.  |
+| `unit_test_suite_number_of_large_assertion_blocks` | `4`        | —                            | If a suite accumulates multiple large assertion blocks, extract reusable assertion helpers instead of copy/paste growth. |
+
+## Review expectations
+
+- PowerShell implementation agents should use the source code matrix while shaping `src/**/*.ps1`.
+- Test-focused agents should use the test code matrix while shaping `tests/**/*.ps1`.
+- Review agents should flag new or heavily changed code that ignores the warning thresholds without a clear, justified reason.

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

@@ -75,6 +75,7 @@ Use this file when changing `src/public/`, `src/private/`, or PowerShell build/r
 
 ## Maintainability rules
 
+- Use `.github/instructions/code-quality-matrix.instructions.md` as the best-effort source-code matrix for `src/**/*.ps1`; warning thresholds are the default ceiling for new or heavily changed code.
 - Favor short functions and extracted helpers over large nested logic.
 - Avoid copy/paste across source or test files.
 - Add comments only when the code would otherwise be hard to follow.

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

@@ -16,6 +16,7 @@ Use this file when changing production code, tests, coverage behavior, or CI tes
 - Reuse `*.TestSupport.ps1` helpers where possible.
 - For every new or changed `src/**/*.ps1` file, add or update the matching source-mirrored `.Tests.ps1` file.
 - Keep test files and helpers compatible with `project.json` `Manifest.PowerShellHostVersion`; if a project targets `5.1`, do not rely on PowerShell 7.x-only syntax, cmdlets, parameters, or APIs in the tests.
+- Use `.github/instructions/code-quality-matrix.instructions.md` as the best-effort test-code matrix for `tests/**/*.ps1`; warning thresholds are the default ceiling for new or heavily changed tests.
 - Use broad guardrail, architecture, command-model, or integration tests only for behavior that genuinely spans multiple source files; do not use them as the default place for unit coverage of unrelated source files.
 
 ## Repository test structure

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

@@ -17,16 +17,17 @@ Implement the issue in the NovaModuleTools repository using the repository-local
 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. Inspect `project.json` `Manifest.PowerShellHostVersion` before changing PowerShell code, tests, or examples, and keep the implementation compatible with that target.
 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. 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`).
+8. Use `.github/instructions/code-quality-matrix.instructions.md` as the best-effort quality matrix for changed `src/**/*.ps1` and `tests/**/*.ps1`; keep new or heavily changed code within the relevant warning thresholds unless the scope explicitly justifies otherwise.
+9. Do not add PSScriptAnalyzer excluded rules or suppressions; fix analyzer findings in the code.
+10. If `run.ps1` or `Invoke-ScriptAnalyzerCI.ps1` reports ScriptAnalyzer findings, fix them before handoff instead of only reporting the failure.
+11. 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.
+12. 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.
+13. 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.
+14. Add or update PlatyPS-compatible help under `docs/<ProjectName>/en-US/` when public commands or public classes change.
+15. Review `README.md`, `CONTRIBUTING.md`, `CHANGELOG.md`, `RELEASE_NOTE.md`, help docs, and `docs/*.html` as applicable.
+16. If a commit message is requested, derive it from `$GIT_BRANCH_NAME` and the implemented change using the repository's Conventional Commit rules.
+17. Run the relevant validation, then summarize what changed, why, and how it was verified.
+18. 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

@@ -8,10 +8,11 @@ Improve changed-code coverage in NovaModuleTools without lowering maintainabilit
 2. Read the nearby production code and the most relevant existing test/support files.
 3. Place new tests in the source-mirrored path under `tests/` by default: one focused `.Tests.ps1` file per covered `src/**/*.ps1` file.
 4. Use an existing guardrail or integration test only when it intentionally owns genuinely cross-cutting behavior, and document that ownership in the handoff.
-5. Add the smallest test that proves the missing behavior.
-6. If setup is duplicated, refactor the tests before adding more assertions.
-7. Re-run the focused tests, then the repository quality loop if code changed.
-8. Recheck CodeScene coverage or Code Health if that was the original failure.
+5. Use `.github/instructions/code-quality-matrix.instructions.md` as the best-effort test-code matrix; keep new or heavily changed tests within the warning thresholds unless the scope explicitly justifies otherwise.
+6. Add the smallest test that proves the missing behavior.
+7. If setup is duplicated, refactor the tests before adding more assertions.
+8. Re-run the focused tests, then the repository quality loop if code changed.
+9. Recheck CodeScene coverage or Code Health if that was the original failure.
 
 ## Repository-specific reminders