feat(#200): establish mirrored test layout convention

- Document the source-mirrored, dot-source-first test loading pattern in the testing-policy instruction and pester-testing skill (mirrored into the agentic-copilot scaffold), add a non-blocking scripts/build/Get-TestMirrorStatus.ps1 helper that reports src files without a mirrored test, add proof-of-concept mirrored tests for
- Format-ProjectJsonValue and Get-ProjectJsonValueTypeName, remove the dist-psm1 coverage Path override so project.json owns the coverage Path, and temporarily disable the Pester coverage gate while the existing suite migrates to the new pattern.

Author: stiwicourage

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

@@ -8,6 +8,49 @@ applyTo: "tests/**/*.ps1,scripts/build/**/*.ps1,.github/workflows/Tests.yml,.git
 
 Use this file when changing production code, tests, coverage behavior, or CI test flows.
 
+## Test loading pattern (mirrored, dot-source-first)
+
+NovaModuleTools is migrating tests to a 1:1 source-to-test layout per issue #208. New and migrated tests follow this loading pattern:
+
+- The test file's `BeforeAll` dot-sources **only** the `src/**/*.ps1` files it needs (the source under test plus its private collaborators that are not being mocked).
+- Tests do **not** `Import-Module $project.OutputModuleDir`.
+- Tests do **not** use `InModuleScope <ModuleName> { ... }`. Mocked functions live in the same scope as the test because they were dot-sourced into it.
+- Shared fixtures and dot-source helpers live in `tests/TestHelpers/`.
+- This makes `project.json` `Pester.CodeCoverage.Path = ["src/public/*.ps1", "src/private/**/*.ps1"]` produce real source-file coverage and means `Test-NovaBuild` does not require a `dist/` folder.
+
+Example:
+
+```powershell
+BeforeAll {
+    $projectRoot = Split-Path -Parent (Split-Path -Parent $PSScriptRoot)
+    . (Join-Path $projectRoot 'src/private/quality/Initialize-NovaPesterCoverageConfiguration.ps1')
+    . (Join-Path $projectRoot 'src/public/Test-NovaBuild.ps1')
+}
+```
+
+Legacy tests that still use `Import-Module $project.OutputModuleDir` + `InModuleScope` are being migrated in the issue series #200..#207. While migration is in progress, `project.json` `CodeCoverage.Enabled` is `false` so the percentage gate does not fail. The gate is re-enabled in issue #207 once enough tests use the mirrored pattern.
+
+## Cross-cutting tests are still allowed
+
+Use a cross-cutting test file (not a mirrored one) when the behavior under test truly spans multiple source files:
+
+- Architecture guardrails (layering, adapter boundaries, file ownership rules)
+- Public command surface tests that exercise the built module end-to-end
+- Workflow tests that intentionally validate multi-helper orchestration
+- CLI route/forwarding tests that prove the routing topology, not the helpers it routes to
+
+Cross-cutting files should be **named for the behavior** they validate (e.g., `ArchitectureGuardrails.Tests.ps1`), not for "remaining coverage". A test belongs in a mirrored file when it covers a single source file's behavior.
+
+## Where new tests for a source file go
+
+| Source file                       | Mirrored test file                        |
+|-----------------------------------|-------------------------------------------|
+| `src/public/<Name>.ps1`           | `tests/public/<Name>.Tests.ps1`           |
+| `src/private/<domain>/<Name>.ps1` | `tests/private/<domain>/<Name>.Tests.ps1` |
+| `src/classes/<Name>.ps1`          | `tests/classes/<Name>.Tests.ps1`          |
+
+A non-blocking mirror status helper is available at `scripts/build/Get-TestMirrorStatus.ps1` to show which source files still lack a mirrored test.
+
 ## Test expectations
 
 - Behavior changes require Pester coverage.
@@ -27,25 +70,28 @@ Use this file when changing production code, tests, coverage behavior, or CI tes
 
 ## Repository test structure
 
-- `tests/NovaCommandModel*.Tests.ps1` - public command, CLI, and workflow behavior
+- `tests/public/<Name>.Tests.ps1`, `tests/private/<domain>/<Name>.Tests.ps1`, `tests/classes/<Name>.Tests.ps1` - mirrored unit tests (preferred for new and migrated tests)
 - `tests/ArchitectureGuardrails.Tests.ps1` - layering and adapter boundaries
-- `tests/*TestSupport.ps1` - shared helpers and reusable fixtures
-- Source-mirrored tests should use `tests/public/<Name>.Tests.ps1`, `tests/private/<domain>/<Name>.Tests.ps1`, and `tests/classes/<Name>.Tests.ps1` for matching `src/public/`, `src/private/`, and `src/classes/` files.
-- Repeated setup belongs in `tests/TestHelpers/` or `tests/*TestSupport.ps1`, not in duplicated blocks across mirrored tests.
+- `tests/NovaCommandModel*.Tests.ps1` - public command, CLI, and workflow behavior (legacy bucket, being migrated)
+- `tests/*TestSupport.ps1`, `tests/TestHelpers/` - shared helpers, reusable fixtures, dot-source helpers
+- `tests/CoverageGaps*.Tests.ps1`, `tests/Remaining*Coverage*.Tests.ps1` - legacy coverage buckets being retired in issue #207
 
 ## Coverage and CodeScene
 
 - CI coverage is generated by `./scripts/build/ci/Invoke-NovaModuleToolsCI.ps1`.
 - `Test-NovaBuild` runs once and produces a JaCoCo coverage report at `artifacts/coverage.xml`.
 - The JaCoCo artifact is reused by the CodeScene PR coverage gate and by the develop/manual CodeScene analysis flow.
 - The CodeScene analysis upload sends coverage twice: once for `line-coverage` and once for `branch-coverage`.
+- Coverage paths in `project.json` must point at `src/**/*.ps1`, not at the built `dist` psm1. Nova does not override `CodeCoverage.Path`.
+- During the test-layout migration, `CodeCoverage.Enabled` is temporarily `false` so the percentage gate does not block work. It is re-enabled in issue #207.
 - If CodeScene flags coverage or duplication, fix the underlying test design instead of suppressing the warning casually.
 
 ## Common pitfalls
 
-- Many tests expect the built module under `dist/NovaModuleTools`; build first when needed.
+- Importing the built `dist/NovaModuleTools` module from a new mirrored test - mirrored tests dot-source `src/**/*.ps1` files directly instead.
+- Using `InModuleScope NovaModuleTools { ... }` in new tests - the function under test is already in scope after dot-sourcing.
 - Direct `Invoke-Pester` runs can hide Nova-specific build/import/StrictMode behavior and should not be used as the project test entrypoint.
-- Some support helpers must be dot-sourced and re-exported inside `BeforeAll`.
+- Some legacy support helpers must be dot-sourced and re-exported inside `BeforeAll`; new TestHelpers should expose dot-source helpers directly.
 - Duplicated test setup can lower Code Health even when tests pass.
 - Tests that only cover the happy path can miss the edge cases that caused the change in the first place.
 - Shared mutable state between tests makes failures order-dependent and unreliable.

.github/skills/pester-testing/SKILL.md

@@ -21,7 +21,7 @@ Use this skill when adding tests, closing coverage gaps, fixing regressions, or
 
 - Match existing `Describe` / `It` naming style.
 - Prefer support helpers for repeated setup.
-- Build/import the dist module when the test file expects it.
+- For new and migrated tests, dot-source `src/**/*.ps1` files directly in `BeforeAll`. Do not `Import-Module $project.OutputModuleDir` in mirrored unit tests, and do not use `InModuleScope NovaModuleTools { ... }` - the function under test is already in scope after dot-sourcing.
 - Use `Test-NovaBuild` as the authoritative test entrypoint in Nova-managed projects. Do not validate with direct `Invoke-Pester`, because it can miss the Nova build/import/StrictMode flow.
 - Add coverage for both happy paths and explicit warnings/errors when behavior changed.
 - For every new or changed `src/**/*.ps1` file, add or update one focused test file that mirrors the source path under `tests/`.
@@ -30,19 +30,35 @@ Use this skill when adding tests, closing coverage gaps, fixing regressions, or
 - Keep shared setup in `tests/TestHelpers/` or `*TestSupport.ps1`; do not hide unrelated source-file coverage in broad catch-all test files.
 - If a mirrored test is not practical because the behavior is genuinely cross-cutting, document the reason in the handoff and point to the owning integration or guardrail test.
 
+## Mirrored layout example
+
+```powershell
+BeforeAll {
+    $projectRoot = Split-Path -Parent (Split-Path -Parent $PSScriptRoot)
+    . (Join-Path $projectRoot 'src/private/quality/Initialize-NovaPesterCoverageConfiguration.ps1')
+}
+
+Describe 'Initialize-NovaPesterCoverageConfiguration' {
+    It 'leaves CodeCoverage.Path to project.json when coverage is enabled' {
+        # ...
+    }
+}
+```
+
 ## Common pitfalls
 
-- Forgetting that many tests assume `dist/NovaModuleTools` already exists
-- Duplicating setup instead of extending `*.TestSupport.ps1`
-- Exporting helper functions at the wrong time in test lifecycle
-- Validating a Nova-managed project with direct `Invoke-Pester` instead of `Test-NovaBuild`
-- Passing tests while still degrading Code Health through duplication
-- Grouping unrelated source files into one large test file when a source-mirrored layout would make ownership clearer
-- Adding source files without a matching mirrored test or an explicit cross-cutting-test justification
-- Ignoring boundary/unhappy-path coverage or test isolation and relying on happy-path-only verification
+- Importing the built `dist/NovaModuleTools` module from a new mirrored test - dot-source the relevant `src/**/*.ps1` files instead.
+- Using `InModuleScope NovaModuleTools { ... }` in new mirrored tests - the function is already in scope after dot-sourcing.
+- Duplicating setup instead of extending `*.TestSupport.ps1` or `tests/TestHelpers/`.
+- Exporting helper functions at the wrong time in test lifecycle.
+- Validating a Nova-managed project with direct `Invoke-Pester` instead of `Test-NovaBuild`.
+- Passing tests while still degrading Code Health through duplication.
+- Grouping unrelated source files into one large test file when a source-mirrored layout would make ownership clearer.
+- Adding source files without a matching mirrored test or an explicit cross-cutting-test justification.
+- Ignoring boundary/unhappy-path coverage or test isolation and relying on happy-path-only verification.
 
 ## Verification
 
 - Run `Test-NovaBuild`
 - Run `./run.ps1` before finishing code changes
-- If coverage is the goal, inspect `artifacts/pester-coverage.cobertura.xml` via the CI helper flow
+- If coverage is the goal, inspect `artifacts/coverage.xml` produced by the CI helper flow. Coverage is JaCoCo and references source files under `src/**/*.ps1` directly.

.github/workflows/Tests.yml

@@ -30,7 +30,7 @@ jobs:
       - name: Install required CI PowerShell modules
         run: ./scripts/build/ci/Install-CiPowerShellModules.ps1
 
-      - name: Run NovaModuleTools CI test and coverage workflow
+      - name: Run NovaModuleTools CI test
         run: ./scripts/build/ci/Invoke-NovaModuleToolsCI.ps1 -OutputDirectory ./artifacts
 
       - name: Validate release history files with Test-KeepAChangelogFile

CHANGELOG.md

@@ -21,9 +21,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
     - 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.
     - `Initialize-NovaModule` and `% nova init` now check for newer NovaModuleTools releases before the first interactive scaffold question and reuse the same non-blocking update warning behavior already used by build.
 - `Test-NovaBuild` and `% nova test` now enforce `Pester.CodeCoverage.CoveragePercentTarget` from `project.json` when `CodeCoverage.Enabled` is `true`, failing the test run when measured coverage drops below the configured target.
+- Added a non-blocking `scripts/build/Get-TestMirrorStatus.ps1` helper that reports `src/**/*.ps1` files without a matching mirrored test file under `tests/`, to support the migration to the source-mirrored, dot-source-first test layout.
 
 
 ### Changed
+- Test-loading guidance for NovaModuleTools' own tests and for generated Agentic Copilot scaffolds now follows a source-mirrored, dot-source-first pattern: new mirrored tests dot-source the relevant `src/**/*.ps1` files directly in `BeforeAll` instead of importing the built `dist` module or wrapping assertions in `InModuleScope`, so tests run against source files and JaCoCo coverage references real source paths.
+- `project.json` `Pester.CodeCoverage.Enabled` is temporarily `false` while the existing test suite migrates to the new dot-source pattern; the configured `90` percent target stays in place and is re-enabled once migration completes.
 - The architect/design flow now surfaces settled vs unresolved design items before finalization, offers explicit choices for full finalization vs design-package-only handoff, clarifies how to use design notes versus the paste-ready GitHub issue draft, and requires finalization output to follow the project Markdown authoring guidance.
 - `ProjectTemplate.json` and the packaged example `project.json` now include Nova's default Pester `CodeCoverage` block with `Enabled=false`, shared `src/` coverage paths, JaCoCo output, and a `90` percent target so new projects can opt into coverage without hand-authoring the configuration.
 - `Invoke-NovaModuleToolsCI.ps1` now delegates the full test run to a single `Test-NovaBuild` call; the previous second `Invoke-Pester` pass and post-run Cobertura source-path remapping step have been removed.
@@ -39,7 +42,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ### Fixed
 - `Test-NovaBuild` and `% nova test` no longer emit `Remove-Item -Recurse` progress bars during the Pester run; `$global:ProgressPreference` is saved and restored around the test execution so CI logs stay clean.
-- Code coverage in `Test-NovaBuild` now runs against the built `dist/<ModuleName>/<ModuleName>.psm1` file instead of source files, so measured coverage percentages and line numbers align with the deployed module.
+- Code coverage in `Test-NovaBuild` now runs against the source files, instead of the built `dist/<ModuleName>/<ModuleName>.psm1` file so measured coverage percentages and line numbers align with the deployed module.
 
 
 ### Security

RELEASE_NOTE.md

@@ -20,8 +20,6 @@ This file summarizes public cmdlet, CLI, configuration, and migration changes fo
 
 
 ### Fixed
-- Code coverage in `Test-NovaBuild` now runs against the built `dist/` module instead of source files, so reported coverage percentages and line numbers match the deployed module.
-- `Test-NovaBuild` and `% nova test` no longer emit `Remove-Item` progress bars during the Pester run.
 
 
 ### Security

project.json

@@ -41,7 +41,11 @@
   },
   "Pester": {
     "CodeCoverage": {
-      "Enabled": true,
+      "Enabled": false,
+      "Path": [
+        "src/public/*.ps1",
+        "src/private/**/*.ps1"
+      ],
       "CoveragePercentTarget": 90,
       "OutputPath": "artifacts/coverage.xml",
       "OutputFormat": "JaCoCo"

scripts/build/Get-TestMirrorStatus.ps1

@@ -0,0 +1,94 @@
+param(
+    [string]$ProjectRoot,
+    [switch]$Quiet
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+function Resolve-MirrorStatusProjectRoot {
+    param([string]$ProjectRoot)
+
+    if (-not [string]::IsNullOrWhiteSpace($ProjectRoot)) {
+        return (Resolve-Path -LiteralPath $ProjectRoot -ErrorAction Stop).Path
+    }
+
+    return (Resolve-Path -LiteralPath (Join-Path $PSScriptRoot '..' '..')).Path
+}
+
+function Get-SourceMirrorEntry {
+    param(
+        [Parameter(Mandatory)][string]$ProjectRoot,
+        [Parameter(Mandatory)][string]$SourceRelative
+    )
+
+    $sourceFull = Join-Path $ProjectRoot $SourceRelative
+    if (-not (Test-Path -LiteralPath $sourceFull -PathType Leaf)) {
+        return $null
+    }
+
+    $sourceFileName = [System.IO.Path]::GetFileNameWithoutExtension($sourceFull)
+    $testRelativeParent = ($SourceRelative -replace '^src/', 'tests/')
+    $testRelativeParent = Split-Path -Parent $testRelativeParent
+    $testRelative = Join-Path $testRelativeParent ("$sourceFileName.Tests.ps1")
+    $testRelative = $testRelative -replace '\\', '/'
+    $testFull = Join-Path $ProjectRoot $testRelative
+
+    return [pscustomobject]@{
+        SourcePath = $SourceRelative
+        TestPath = $testRelative
+        Mirrored = Test-Path -LiteralPath $testFull -PathType Leaf
+    }
+}
+
+function Get-SourceMirrorStatus {
+    param([Parameter(Mandatory)][string]$ProjectRoot)
+
+    $sourcePatterns = @(
+        'src/public/*.ps1'
+        'src/private/**/*.ps1'
+        'src/classes/*.ps1'
+    )
+
+    $entries = New-Object System.Collections.Generic.List[object]
+    foreach ($pattern in $sourcePatterns) {
+        $patternPath = Join-Path $ProjectRoot $pattern
+        foreach ($file in Get-ChildItem -Path $patternPath -File -ErrorAction SilentlyContinue) {
+            $relative = ($file.FullName.Substring($ProjectRoot.Length + 1)) -replace '\\', '/'
+            $entry = Get-SourceMirrorEntry -ProjectRoot $ProjectRoot -SourceRelative $relative
+            if ($null -ne $entry) {
+                $entries.Add($entry)
+            }
+        }
+    }
+
+    return $entries
+}
+
+function Write-MirrorStatusReport {
+    param(
+        [Parameter(Mandatory)][object[]]$Entries,
+        [switch]$Quiet
+    )
+
+    $missing = @($Entries | Where-Object {-not $_.Mirrored})
+    $covered = @($Entries | Where-Object {$_.Mirrored})
+
+    if (-not $Quiet) {
+        Write-Host ('Source files scanned : {0}' -f $Entries.Count)
+        Write-Host ('Mirrored test files  : {0}' -f $covered.Count)
+        Write-Host ('Missing mirrored test: {0}' -f $missing.Count)
+        if ($missing.Count -gt 0) {
+            Write-Host ''
+            Write-Host 'Sources without a mirrored test file:'
+            foreach ($entry in $missing | Sort-Object SourcePath) {
+                Write-Host ("  {0} -> {1}" -f $entry.SourcePath, $entry.TestPath)
+            }
+        }
+    }
+}
+
+$resolvedRoot = Resolve-MirrorStatusProjectRoot -ProjectRoot $ProjectRoot
+$entries = Get-SourceMirrorStatus -ProjectRoot $resolvedRoot
+Write-MirrorStatusReport -Entries $entries -Quiet:$Quiet
+return $entries

src/private/quality/GetNovaTestWorkflowContext.ps1

@@ -109,8 +109,6 @@ function Initialize-NovaPesterCoverageConfiguration {
     if ($null -ne $coveragePercentTarget) {
         $PesterConfig.CodeCoverage.CoveragePercentTarget = $coveragePercentTarget
     }
-
-    $PesterConfig.CodeCoverage.Path = $ProjectInfo.ModuleFilePSM1
 }
 
 function Get-NovaPesterSettingValue {