feat(#163): enhance preview mode for stable version bumps

[stiwicourage]

• Make Update-NovaModuleVersion -Preview enter the next patch preview track deterministically from stable versions
• Ensure stable versions increment the patch version and append -preview
• Maintain existing prerelease versions' semantic core and sequence

Summary

• Make Update-NovaModuleVersion -Preview and % nova bump --preview enter the preview track deterministically from stable versions by always incrementing the patch version before appending -preview.
• Keep existing prerelease versions on their current semantic core while continuing the prerelease suffix sequence, and surface the patch fallback through the workflow context so reporting can distinguish the detected semantic label from the applied preview-plan label.
• Implements [Feature]: Make -Preview on stable versions create the next patch preview #163. Related workflow investigation: stiwicourage/KeepAChangelog#14.

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
• Other

Review guidance

• Start with src/private/release/GetNovaVersionUpdatePlan.ps1 and src/private/release/GetNovaVersionUpdateWorkflowContext.ps1, because that is where stable preview requests now fall back to a patch preview plan while preserving the detected semantic label for reporting.
• Then review tests/CoverageGaps.ReleaseInternals.Tests.ps1, tests/NovaCommandModel.BumpAndCli.Tests.ps1, and tests/NovaCommandModel.TestSupport/CliProjectSupport.ps1 to see the updated expectations for cmdlet behavior, workflow-context metadata, and installed % nova bump --preview --what-if output.
• Finish with docs/NovaModuleTools/en-US/Update-NovaModuleVersion.md and CHANGELOG.md for the user-facing behavior and release-note wording.
• Trade-off: stable -Preview no longer reuses semantic history inference for the semantic core, so automation that previously expected results like 1.6.0-preview from 1.5.3 will now receive 1.5.4-preview.

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:

Targeted release/versioning validation:
- Invoke-NovaBuild
- Invoke-Pester -Path ./tests/CoverageGaps.ReleaseInternals.Tests.ps1,./tests/NovaCommandModel.BumpAndCli.Tests.ps1 -Output Detailed
- Result: 108 passed, 0 failed

Repository analyzer validation:
- ./scripts/build/Invoke-ScriptAnalyzerCI.ps1
- Result: PSScriptAnalyzer: no findings.
- Artifacts: ./artifacts/scriptanalyzer.txt, ./artifacts/scriptanalyzer-preview-versioning.log

Workflow exercised:
- Update-NovaModuleVersion -Preview and -WhatIf coverage through release internals and command-model tests
- Continuous-integration preview planning coverage through Update-NovaModuleVersion workflow tests
- Installed CLI preview WhatIf output covered through tests/NovaCommandModel.TestSupport/CliProjectSupport.ps1 expectations

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:

Medium compatibility risk for automation that depended on the previous stable-preview behavior. Stable preview bumps now always plan the next patch preview, so maintainers should review any workflow or release step that previously expected semantic-history inference to produce versions like 1.6.0-preview from 1.5.3.

This change is intentionally scoped to preview-entry behavior from stable versions. Existing prerelease versions still stay on their current semantic core and continue the prerelease sequence, and non-preview bumps still follow Nova's normal release/finalization rules.

Rollback is straightforward: revert the preview patch fallback in Get-NovaVersionPartForUpdatePlan / Get-NovaVersionUpdateWorkflowContext, restore the previous test expectations, and revert the command help / changelog wording.

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

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

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[codescene-delta-analysis]

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

Review details by gate

• Overall Coverage

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

• New & Changed Code Coverage

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