Enhance Nova CLI workflows, testing, and project.json schema support

[stiwicourage]

Summary

• What changed? This branch packages the 3.1.1-preview02 prerelease line on develop relative to the stable 3.1.0 line on main, with the biggest release-facing changes being the new Invoke-NovaTest unit-test entrypoint, the Test-NovaBuild build-validation split, hosted single-source project.json schema export/injection, Get-NovaProjectInfo version-surface alignment, Update-NovaModuleTool follow-up guidance updates, stricter Package.Latest validation, and broad mirrored test/help/docs coverage to lock those contracts in.
• Why was this change needed? To separate unit-test and build-validation responsibilities cleanly, improve project.json authoring and VS Code validation, tighten package/config compatibility rules, and make repository, CI, publish, and release quality flows validate unit tests before build-validation integration tests.
• Link the issue, discussion, or follow-up work (for example Closes #123). Release-prep scope only: this diff is the promotion candidate from main stable 3.1.0 to develop prerelease 3.1.1-preview02. The behavior described here remains prerelease-only until promoted to main. No publish, tag, or push actions were performed.

Affected area

• nova CLI or command routing
• Public PowerShell cmdlet behavior
• Scaffolding or project.json handling
• Build, test, analyzer, coverage, or CI helper flow
• Package, raw upload, or package metadata workflow
• Publish, release, or GitHub Actions automation
• Self-update or notification preference behavior
• Contributor documentation (README.md, CONTRIBUTING.md, repository workflow docs)
• End-user docs (docs/*.html)
• Command help (docs/NovaModuleTools/en-US/*.md)
• src/resources/example/
• Dependency or manifest changes (project.json, workflow dependencies, release tooling)
• Security-sensitive change
• Documentation-only change
• Agentic Copilot Workflow + scaffold mirror + scaffold-sync guardrail test.
• Other

Review guidance

• Start with the test-flow split instead of reading the 147-file diff linearly: review src/public/InvokeNovaTest.ps1, src/public/TestNovaBuild.ps1, src/private/quality/, and src/private/cli/InvokeNovaCliCommandRoute.ps1 first.
• Then review the schema path: src/resources/Schema-Project.json, docs/schema/v3/project.json, src/private/build/ExportNovaProjectJsonSchema.ps1, src/private/scaffold/WriteNovaModuleProjectJson.ps1, and src/private/scaffold/WriteNovaVsCodeSettings.ps1.
• The rest of the diff is largely contract locking and rollout support across tests/, docs/, README.md, CONTRIBUTING.md, scaffold mirrors, and release/package workflow helpers. Main trade-off/risk: Package.Latest=true|false is no longer accepted, so projects still using the old boolean form must migrate to "always" or "never" before stable promotion.

Validation

• Invoke-NovaBuild
• Invoke-NovaTest
• Test-NovaBuild
• ./scripts/build/Invoke-ScriptAnalyzerCI.ps1
• ./scripts/build/ci/Invoke-NovaModuleToolsCI.ps1
• Targeted Nova workflow validated (% nova build, % nova test, % nova merge, % nova deploy, % nova publish, % nova release, % nova update, % nova notification, or % nova init as relevant)
• Docs/example only; executable validation not needed

Validation notes:

- Invoke-NovaTest passed.
- Test-NovaBuild passed.
- pwsh -NoLogo -NoProfile -File ./run.ps1 passed (includes the repository quality wrapper path and Invoke-NovaBuild).
- Test-MarkdownCommandHelp -Path ./docs/NovaModuleTools/en-US/Invoke-NovaTest.md -DetailView passed.
- CodeScene pre-commit safeguard passed.
- No publish, tag, or push actions were performed.

Documentation and release follow-up

• README.md reviewed and updated if contributor workflow, architecture, CI, release, or automation changed
• CONTRIBUTING.md reviewed and updated if contribution expectations or review guidance changed
• CHANGELOG.md reviewed and updated if the change matters to users, maintainers, or contributors
• RELEASE_NOTE.md reviewed and updated if the change affects public cmdlet usage, CLI usage, configuration semantics, or migration expectations
• docs/NovaModuleTools/en-US/ help updated if a public command or CLI behavior changed
• docs/*.html updated if end-user workflows or examples changed
• src/resources/example/ reviewed and updated if the real-world project layout, package model, or upload workflow changed
• No documentation, changelog, release-note, or example updates were needed

Maintainability, compatibility, and risk

• Code Health / maintainability impact considered
• No breaking change
• Breaking change
• Security-sensitive change
• CI, workflow, or release-pipeline impact
• Dependency-review impact

Risk, rollout, or rollback notes:

- Stable vs prerelease: main remains the stable 3.1.0 release line and develop remains the 3.1.1-preview02 prerelease line. This branch contains prerelease-only behavior until promoted to main.
- Release-flow semantics stay branch-specific: main still runs stable Invoke-NovaRelease automation with changelog/release-note move + tag/commit + forced develop reset/bump, while develop still publishes a prerelease and bumps to the next prerelease.
- Workflow impact: repository/CI/release/package quality paths now expect Invoke-NovaTest to run before Test-NovaBuild.
- Compatibility/migration: Package.Latest boolean values are now rejected; migrate existing project.json files to "always" or "never".
- Rollback path: revert the test-flow split, schema export/injection, and Package.Latest enforcement before stable promotion if prerelease feedback finds regressions.

Important

Do not use a public pull request to disclose a vulnerability before coordinated handling.
Use the private reporting path in SECURITY.md for new security issues.

[codescene-delta-analysis]

Gates Passed
6 Quality Gates Passed

See analysis details in CodeScene

Quality Gate Profile: Pay Down Tech Debt
Install CodeScene MCP: safeguard and uplift AI-generated code. Catch issues early with our IDE extension and CLI tool.

[codescene-delta-analysis]

Code Coverage Gates Passed
Overall Coverage: 99.8% (required = 95%)
New & Changed Code Coverage: 100% (required = 99%)

Review details by gate

• Overall Coverage

  • Pass/Fail Reason:
    The overall coverage gate was checked for all code and meets the goal: 99.8% covered >= threshold = 95%
  • Action:
    You have 294 files with a sum of 4073 covered and 7 uncovered lines of code.

• New & Changed Code Coverage

  • Pass/Fail Reason:
    New or changed code meets coverage goal: 100% covered >= threshold = 99%
  • Action:
    You modified 26 files, and covered 426 added/modified lines of code.