Enhance Nova version bump behavior and CLI warning handling

[stiwicourage]

Summary

• Implement SemVer major-zero behavior for Update-NovaModuleVersion / % nova bump so stable 0.y.z projects no longer auto-jump to 1.0.0 when commit history implies a breaking change.
• Stable major bumps on 0.y.z now keep the detected Major label for reporting, plan the next minor version instead, and print guidance telling users to set 1.0.0 manually once the software is stable.
• Preserve existing -Preview behavior, surface the advisory in both direct PowerShell and CLI output, and document the rule across help and docs.
• Closes SemVer major-zero behavior for nova bump #146.

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, semantic-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 (package.json, workflow dependencies, release tooling)
• Security-sensitive change
• Documentation-only change
• Other

Review guidance

• Start with src/private/release/GetNovaVersionUpdateWorkflowContext.ps1, which now resolves an effective label for stable 0.y.z major bumps and carries advisory metadata through the workflow context.
• Then review src/private/release/InvokeNovaVersionUpdateWorkflow.ps1, src/private/release/WriteNovaVersionUpdateResultMessages.ps1, and src/public/UpdateNovaModuleVersion.ps1 to see how the effective label is applied during writes and how warnings are emitted for direct cmdlet usage.
• Review src/private/cli/FormatNovaCliCommandResult.ps1 for the CLI-facing advisory output and src/resources/cli/help/bump.psd1, docs/NovaModuleTools/en-US/Update-NovaModuleVersion.md, docs/versioning-and-updates.html, docs/commands.html, and README.md for the updated user guidance.
• Test coverage was added in tests/NovaCommandModel.BumpAndCli.Tests.ps1, tests/CoverageGaps.ReleaseInternals.Tests.ps1, tests/CoverageGaps.Cli.Tests.ps1, tests/NovaCommandModel.StandaloneCli.Tests.ps1, and the helper allowlist in tests/ArchitectureGuardrails.Tests.ps1.
• Trade-off: this is intentionally an additive policy layer on top of the existing version planner, so stable 0.y.z bumps are remapped only at the workflow boundary while -Preview behavior remains unchanged.

Validation

• Invoke-NovaBuild
• 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:

Validated the feature through both targeted and broader repository runs.

- Invoke-NovaBuild
  - Rebuilt the dist module after the source/help changes.

- Targeted suites
  - Invoke-Pester -Path ./tests/NovaCommandModel.Tests.ps1 -CI
	- Tests Passed: 38, Failed: 0
  - Invoke-Pester -Path @(
	  ./tests/NovaCommandModel.BumpAndCli.Tests.ps1,
	  ./tests/CoverageGaps.ReleaseInternals.Tests.ps1,
	  ./tests/CoverageGaps.Cli.Tests.ps1,
	  ./tests/NovaCommandModel.StandaloneCli.Tests.ps1
	) -CI
	- Tests Passed: 231, Failed: 0
  - Invoke-Pester -Path @(
	  ./tests/ArchitectureGuardrails.Tests.ps1,
	  ./tests/BuildOptions.Tests.ps1
	) -CI
	- Tests Passed: 29, Failed: 0

- Full repository workflow
  - Import-Module ./dist/NovaModuleTools -Force; Test-NovaBuild
	- Tests Passed: 635, Failed: 0

- Code Health safeguard
  - pre_commit_code_health_safeguard passed after consolidating the new internal tests into a table-driven structure.

- Targeted nova bump workflow coverage
  - Standalone CLI tests validate stable `0.y.z` + breaking-change behavior and confirm that `--preview` remains unchanged.

I did not rerun ./scripts/build/Invoke-ScriptAnalyzerCI.ps1 or ./scripts/build/ci/Invoke-NovaModuleToolsCI.ps1 as standalone post-fix commands because the final state was already covered by the broader test/analyzer checks above.

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
• 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, 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:

Compatibility impact is intentionally narrow:

- Stable breaking-change bumps on 0.y.z now plan the next minor version instead of 1.0.0.
- The detected release label remains Major in the result/output so the commit intent is still visible.
- Preview behavior is unchanged.

This is not a breaking API change for users of the bump command; it is a behavioral safeguard for initial-development versions.

Rollback is straightforward:
- Revert commit 26e338a01cc67b6faff3509404c54156bb6e6ad0 on feature/146-semver-major-zero-behavior-for-nova-bump.

Known limitation:
- The rule is enforced at the workflow/context layer rather than by rewriting the lower-level semver math, which keeps the change smaller and protects existing preview behavior.

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.

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[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.